fix(runtime): the base's package export leaves out its pair's dashboard and report overrides (#29563) by objectstack-fleet[bot] · Pull Request #29597 · objectstack-ai/objectstack

objectstack-fleet · 2026-11-02T20:43:05Z

Requested by Warren · project thread
Fixes #29563

Clause-②: no
Metadata-protocol: none

维护者速读

改了什么:基础包的导出 GET /packages/BASE/export 不再夹带 .custom 配对包已发布的仪表盘、报表覆盖项;配对包的导出照旧带覆盖项和 overrides 声明。
为什么改:ADR-0146 D8 第 3 条要求基础包导出「原样」;视图已经如此,仪表盘和报表却把客户的改动写进了厂商的包文件,无法当作厂商包重新部署。
风险与回滚:只在导出时多过滤一类条目(声明「覆盖本包」的条目),其余读取不变;回滚即撤回本 PR 的一个 commit。
先看:packages/runtime/src/domains/packages.ts 的 declaresOverrideOf 与 assemblePackageManifest 里的那一行过滤;再看新测试 packages-export-base-unchanged-per-type.integration.test.ts。
两分钟验证:pnpm --filter @objectstack/runtime exec vitest run --project local src/domains/packages-export-base-unchanged-per-type.integration.test.ts,预期 3 条全绿(视图、仪表盘、报表)。
需要你做的:无,席位落地。

What changes

assemblePackageManifest (the GET /packages/:id/export door) now leaves out, from a package's own export read through the per-package layer, any item whose overrides.package names that same package. A package's own document never declares that it overrides itself: that declaration is what an item of the base's .custom pair carries. The pair's export is unchanged and keeps the overriding item with its overrides block. A protocol with no per-package layer is read as before, so the existing CONTROL in packages-export-per-package-layer.test.ts stays as it is.

One @objectstack/runtime patch changeset.

Why

ADR-0146 D8 item 3: "GET /packages/hotcrm.custom/export carries the overriding item with its overrides block; GET /packages/hotcrm/export carries the base unchanged."

Measured red first on the real protocol and engine (new pin, before the fix), per type:

view: the base's export carried only the base's document (already correct);
dashboard: expected [ 'Shipped label', 'Edited label' ] to deeply equal [ 'Shipped label' ];
report: expected [ 'Shipped label', 'Edited label' ] to deeply equal [ 'Shipped label' ].

Where the second item comes from, read off the registry in the same harness: publishing the pair's row writes it through to the SchemaRegistry's bare slot (hydrateOverlayIntoRegistry in packages/metadata-protocol/src/protocol.ts). The artifact lookup there falls back to the base's code artifact, because the pair ships no artifact of that name, so the bare copy wears the base's envelope (_packageId = the base, _provenance: 'package'). listItems(type, BASE) then answers both the base's composite entry and that copy, and the per-package layer lists both under the base. Views are spared by the #22057 guard in the same hydrator, which is view-only by its own comment.

The upstream (the hydrator lending a base's envelope to its pair's row) is in protocol.ts, which is frozen until 2026-11-03 06:00Z and outside this card's claim. It is reported in the card's os-dev-report as a follow-up, with the minimal change named. This PR closes the export contract at the door the card names.

ADR-0146 D8 item 2, "the export of X's app surface": read here as the pair's export, the one that carries X's app surface as customized, not as GET /packages/X/export. Item 3 names that route and gives it the opposite rule, and getMetaItemsPerPackage's docblock (protocol.ts) and #28409 read it the same way. The ADR text is not edited here (outside the claim); the report names the clarifying sentence for the seat.

Tests

New packages/runtime/src/domains/packages-export-base-unchanged-per-type.integration.test.ts: the real door (HttpDispatcher.handlePackages) over the real ObjectStackProtocolImplementation and ObjectQL on a SQLite file. The base is a code package, the pair is installed through the package door, each override goes through the draft save and the per-item publish. Per type (view, dashboard, report): the effective read serves the override (CONTROL), the base's export carries only the base's document with no overrides block, and the pair's export carries the override with its declaration.
Ablation (fix committed first, mutation through scripts/ablation-replace.mjs; the test reads packages.ts from source, no dist in the path): deleting the filter line turned dashboard and report red with the same two messages above, view stayed green; restore proved blob == HEAD and git diff HEAD empty.

Acceptance notes

studio-authoring.package-customize-restore-display acceptance[4] is a live-run checklist item; its record is not edited in this PR (outside the claim). The seat can mark it once a live run reads the base export clean.

Verification

Head e81217fe (main merged at 1a95c746; the 11 later main commits touch none of this PR's files).

pnpm --filter @objectstack/runtime exec vitest run --project local src/domains/packages-export… (3 files): before the fix 2 failed | 1 passed (dashboard, report red); after, Test Files 3 passed (3), Tests 9 passed (9).
pnpm --filter @objectstack/runtime test at e81217fe: Test Files 526 passed (526), Tests 8489 passed | 19 skipped (8508), lock VERDICT command-exit 0.
pnpm --filter @objectstack/runtime typecheck at e81217fe: exit 0 (tsc and check:test-typecheck; the new file is in the checked zone with no ledger entry).
pnpm lint: exit 0.

dispatch-gates --commands (60) and --ran reconciliation

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 60 commands; 58 exit 0. The union ran on 4a7b14f4; the only later commit (e81217fe) deletes one unused line in the new test file.

NOT MEASURED, exit 3 (prerequisite not met), CI runs both:

node scripts/check-plugin-teardown-shape.mjs --self-test: its fixture is pinned to a commit the shallow clone does not hold (checker-health only).
pnpm check:dual-build-cjs-loads: needs every package's dist/; only the runtime closure was built here.

dispatch-gates --ran: "60 derived famil(ies) accounted for — 58 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3)", exit 0.

Human Minimum

1. Schemas start as Zod; packages/spec holds no runtime logic. (No packages/spec change.)
2. Every name I added uses the casing for its kind.
3. No formatter ran; pnpm lint passes.
4. One issue, one branch off an up-to-date main, one pull request.
5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
6. packages/spec touched: n/a.
7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
8. Title, body and comments are in English (the 维护者速读 block is the os-dev house format).
The Before Submitting list in CONTRIBUTING.md is done.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JQwxbXd7sSh6S5XDDEd7Ei

Generated by Claude Code

…rd and report overrides ADR-0146 D8 item 3: GET /packages/BASE/export carries the base unchanged. A published .custom dashboard or report row is registered in the registry's bare slot under the base's envelope, so the per-package layer listed it beside the base's own item and the base's export carried both. The export now drops, from a package's own export, any item that declares it overrides that package. Pinned per type (view, dashboard, report) over the real protocol and engine. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JQwxbXd7sSh6S5XDDEd7Ei

…-1ikc5d

Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JQwxbXd7sSh6S5XDDEd7Ei

github-actions · 2026-11-02T20:44:23Z

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

the SDK route bridge reached 60 of 216 client-bound route-ledger rows — the other 156 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 156: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 101 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 28 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 50e35a280994dcecb714b6fa1f2d44840900f5e7 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c756f595fc2b433d55a69115390952a019d5bc00 — the merge of head e81217fe9a50bae8e2cb9ad0563e4bd77095c798 into base 50e35a280994dcecb714b6fa1f2d44840900f5e7, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c756f595fc2b433d55a69115390952a019d5bc00 && git checkout c756f595fc2b433d55a69115390952a019d5bc00
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 50e35a280994dcecb714b6fa1f2d44840900f5e7 e81217fe9a50bae8e2cb9ad0563e4bd77095c798 && git checkout -B drift-repro 50e35a280994dcecb714b6fa1f2d44840900f5e7 && git merge --no-ff e81217fe9a50bae8e2cb9ad0563e4bd77095c798

node scripts/docs-audit/affected-docs.mjs --json 50e35a280994dcecb714b6fa1f2d44840900f5e7

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

objectstack-fleet · 2026-11-02T21:04:41Z

domain:server#4 · os-warren · session_01JQwxbacSXJQqAztgt4UMrS

席位核对

ACCEPT · domain:server#4 · head e81217fe9a50bae8e2cb9ad0563e4bd77095c798 · 2026-11-02T21:04Z · seat review of record at TIER_DEFAULT (not governed: check-governed-merges --pr 29597 0 of 3 paths; Clause-②: no; no packages/spec path; no contract face, so no second agent)

Shape: draft, base main, body line 3 Fixes #29563. 3 files, +248/-0: one @objectstack/runtime changeset, packages/runtime/src/domains/packages.ts (export path only), one new integration pin per type. Seat read the diff: a helper declaresOverrideOf(item, packageId) and one filter in assemblePackageManifest, applied only when the protocol has a per-package layer, dropping from package X's own export any item whose overrides.package is X. The pair's export and the no-layer path are unchanged. The CUSTOMISE_BESIDE_REMEDY region (packages: the 422 WRITABLE_PACKAGE_REQUIRED remedy still tells the caller to save an item under its own name, the package-less save ADR-0146 D11 closed #29568) and protocol.ts are untouched.
Premise measured: red first over the real protocol and engine (report 6588016343): after a published .custom override, GET /packages/BASE/export carried two items for dashboard and report (the base's own plus the override with its overrides block); view was already clean. Cause read off the registry: the hydrator registers the pair's row in the bare slot wearing the base's envelope, and the finding(metadata-protocol): on an unscoped kernel, a package-bound stored row of a view name two packages ship is hydrated into the registry's bare slot, so a by-name read naming the other package serves that row's body under its own _packageId #22057 guard spares view only. The seat read ADR-0146 D8 items 2 and 3 on main: item 3 names GET /packages/hotcrm/export as carrying the base unchanged, so the order's needs_decision stop did not fire. Ablation red, restore clean.
Gates on this head: check-runs pinned to e81217fe: 48 total, 35 success, 13 skipped, 0 failed. mergeable_state clean. Dev local (one commit before head; the head commit drops an unused stub from the test only): runtime 526/526 files, typecheck 0, pnpm lint 0, dispatch-gates --ran 60 derived / 58 run / 2 NOT MEASURED (teardown self-test needs an unshallow clone; check:dual-build-cjs-loads, covered by Build Core).
Accepted deviations: the fix is at the export door, not at the cause, because the cause sits in frozen protocol.ts. The filter stays correct after the cause is fixed: a package's own document never declares that it overrides itself.
Out of scope: the cause is filed as metadata-protocol: a published .custom override of a dashboard or report is registered in the registry's bare slot wearing the base's envelope (the #22057 guard spares only views) #29600 (hydrator lends the base's envelope to a .custom row for every non-view type; hold for the freeze). The D8 item 2 wording is filed as docs(adr-0146): D8 item 2's "the export of X's app surface" can be read as GET /packages/X/export, which item 3 says carries the base unchanged; name the export it means #29601 (docs-only ADR edit). The QA checklist record studio-authoring.package-customize-restore-display acceptance[4] is a live-run record; it is marked when a live run reads the base export clean, not by this PR. Skills-docs: n/a (Metadata-protocol: none).
Landing: not governed, under 3000 lines ⇒ the seat lands it (pr_ready + automerge_enable). At MERGED: landing record on packages: the base export carries a published dashboard or report override from its .custom pair, where ADR-0146 D8 item 3 says the base export is unchanged #29563 (closed by Fixes), pm:dispatched removed.

claude added 3 commits November 2, 2026 19:55

Merge remote-tracking branch 'origin/main' into claude/project-thread…

4a7b14f

…-1ikc5d

test(runtime): drop an unused logger stub from the per-type export pin

e81217f

Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JQwxbXd7sSh6S5XDDEd7Ei

github-actions Bot added size/m documentation Improvements or additions to documentation tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 2, 2026

objectstack-fleet Bot marked this pull request as ready for review November 2, 2026 21:05

objectstack-fleet Bot added this pull request to the merge queue Nov 2, 2026

Merged via the queue into main with commit 81cd9eb Nov 2, 2026
49 checks passed

objectstack-fleet Bot deleted the claude/project-thread-1ikc5d branch November 2, 2026 21:20

Navigation Menu

Repository navigation

fix(runtime): the base's package export leaves out its pair's dashboard and report overrides (#29563) - #29597

fix(runtime): the base's package export leaves out its pair's dashboard and report overrides (#29563)#29597
objectstack-fleet[bot] merged 3 commits into
mainfrom
claude/project-thread-1ikc5d

objectstack-fleet Bot commented Nov 2, 2026

Uh oh!

github-actions Bot commented Nov 2, 2026

Uh oh!

objectstack-fleet Bot commented Nov 2, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

objectstack-fleet Bot commented Nov 2, 2026

维护者速读

What changes

Why

Tests

Acceptance notes

Verification

Human Minimum

Uh oh!

github-actions Bot commented Nov 2, 2026

📓 Docs Drift Check

Uh oh!

objectstack-fleet Bot commented Nov 2, 2026

席位核对

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant