fix(metadata-protocol): a .custom pair's published override of a dashboard, report or email template no longer wears the base's envelope in the registry's bare slot - #29640

Requested by Steve · project thread

Fixes #29600
Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：.custom 配对包对基础包仪表盘、报表、邮件模板的已发布覆盖，不再以基础包的信封注册进注册表的裸槽位（沿用 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 对 view 的规则，扩到这三种类型）。
• 为什么改：基础包的按包层（导出读取它）会把覆盖项和基础包自己的项并列列出，注册表直读也会把覆盖项当成基础包的项。
• 风险与回滚：所有协议服务读取（按名读、有效列表、分层读）前后逐项测量不变；只有注册表直读不再看到覆盖。回滚即还原本 PR，无需迁移。
• 先看：packages/metadata-protocol/src/protocol-package-bindings.ts 中的 declinesBorrowedEnvelope，以及新测试 protocol-custom-override-bare-slot-envelope.test.ts。
• 两分钟验证：pnpm --filter @objectstack/objectql exec vitest run src/protocol-custom-override-bare-slot-envelope.test.ts src/environment-overlay-email-locale-restart.test.ts
• 需要你做的：无,席位落地

What changes

A published override of a base's dashboard, report or email template, saved in the base's .custom pair, was registered in the registry's bare slot wearing the BASE's artifact envelope (_packageId = BASE, _provenance: 'package'). The base's per-package layer, which the base's export reads, then listed the override beside the base's own item, and every registry-direct read of the base's item answered the override.

The hydrator (hydrateOverlayIntoRegistry) now declines the bare slot for a row of these three types when the row's bound package ships no artifact of the name while another package does. This is the #22057 view rule, widened per seat ruling A to dashboard, report and email_template. The rule lives in declinesBorrowedEnvelope in protocol-package-bindings.ts, a closed list of three types.

• View is unchanged (it keeps its own 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 limb).
• The loadMetaFromDb boot hydration keeps a third inline copy of the overlay→registry rule with an UNSCOPED artifact lookup (ADR-0048 gap) #4624 case keeps its bare entry: a row of a package that ships its own artifact of the name.
• page, app, dataset, doc and book are left out on purpose. For them the bare slot IS the served override (getMetaItem, getMetaItems, GET /me/apps), so they need a row-served path first. That is follow-up metadata-protocol: page, app, dataset, doc and book serve a published override only from the registry bare slot; build the row-served path, then take them out of it #29613, which also carries the two class-b findings from the measurement.
• flow is left out: no envelope (Regime C), and the boot pull arms its declared override from the bare slot.
• The delete-heal limb has no twin of the rule, because it registers the baseline's own body and grafts no artifact envelope (docblock note only, no code change).

Files (5, +424 / −17):

• packages/metadata-protocol/src/protocol-package-bindings.ts: declinesBorrowedEnvelope and its type list.
• packages/metadata-protocol/src/protocol.ts: one guard line in the hydrator, plus the header and heal docblocks.
• packages/objectql/src/protocol-custom-override-bare-slot-envelope.test.ts (NEW): the per-type pins. It sits in objectql because the pins need the real ObjectQL engine, the in-memory driver and the real registry, and a metadata-protocol test cannot import objectql (that would be a dependency cycle). It reads metadata-protocol from dist/, like the sibling protocol-per-package-layer-provenance.test.ts whose harness it copies. No objectql source is edited.
• packages/objectql/src/environment-overlay-email-locale-restart.test.ts: forced edits, listed below.
• .changeset/29600-pair-override-bare-slot-envelope.md: patch for @objectstack/metadata-protocol.

Tests

New file packages/objectql/src/protocol-custom-override-bare-slot-envelope.test.ts, 9 tests. Per type (view, dashboard, report, email_template) two tests:

• (a) The base's per-package layer lists the base's item alone, and the pair's lists the override alone. The bare slot holds no entry for the name (name@en-US for the email template). registry.getItem answers the base's own item.
• (b) The served reads still serve the override: getMetaItem with no package, BASE and PAIR; getMetaItems with no package and BASE; getMetaItemLayered(BASE).effective.

A control pins #4624: OTHER also ships the dashboard and owns a stored row, so its bare entry stays with OTHER's envelope and _provenance: 'package'.

Forced edits in packages/objectql/src/environment-overlay-email-locale-restart.test.ts (seat-approved, on condition that no non-test email_template registry reader moves; the audit is under Acceptance notes). These four cases pinned the registry entry of a pair's override of a SHIPPED member, which is exactly the entry this PR removes. Each now pins the served read, and keeps the registry pin on the shipped body:

1. "DELETE by member: resetting zh-CN removes its row only, and the en-US overlay stays served — the registry included": the registry pins become PKG en / PKG zh. The served reads go through the protocol (subjectOf(protocol, 'en-US')), and after the restart subjectOf(after.protocol, 'en-US') = ADMIN en.
2. "DELETE by member of a member NO artifact ships: its overlay leaves the registry, and the canonical overlay stays": adds the by-name read getMetaItem({ type, name, member: 'en-US' }) = ADMIN digest en; the registry entry for en-US is PKG digest en.
3. "DELETE with no member": the registry pin on zh-CN ADMIN zh is replaced by subjectOf(protocol, 'zh-CN') = ADMIN zh.
4. "the cluster fan-out: a peer converges on the member a write changed, and a member reset heals only that member": the peer converges through vi.waitFor on subjectOf(peer.protocol, 'zh-CN') = ADMIN zh; the registry pins are PKG zh / PKG en and stay PKG zh on both nodes after the delete.

Ablation of the guard back to view-only. The anchor line in declinesBorrowedEnvelope is replaced so that it returns false for every type. The marker is confirmed in dist/, and the restore is proved by an empty git diff HEAD and ablation-dist-preflight --absent exit 0.

• New pin file alone: 3 red (dashboard, report, email_template per-package tests), 6 green.
• New pin file plus the email-locale file: 6 red (those 3 plus forced-edit cases 1, 2 and 4), 44 green.
• The (b) served-read tests stay green under the ablation by design: those reads never came from the bare slot. The view pin stays green because 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 limb guards view on its own.
• A first ablation attempt failed the build and ran no tests. It was restored and is not counted.

✓ dist/: marker present in 2 built files -- the ablation is live in the artifact the suite consumes.
     × dashboard: the base's per-package layer lists the base's item alone, the pair's the override alone
     × report: the base's per-package layer lists the base's item alone, the pair's the override alone
     × email_template: the base's per-package layer lists the base's item alone, the pair's the override alone
     × DELETE by member: resetting zh-CN removes its row only, and the en-US overlay stays served — the registry included
     × DELETE by member of a member NO artifact ships: its overlay leaves the registry, and the canonical overlay stays
     × the cluster fan-out: a peer converges on the member a write changed, and a member reset heals only that member
 Test Files  2 failed (2)
      Tests  6 failed | 44 passed (50)
DIFF-HEAD-EMPTY=yes
✓ dist/: marker absent from all 24 built files
ABSENT-EXIT=0

Acceptance notes

Bar from the ruling: no protocol read moves. Every reader was measured before (main 0ab4a09) and after (this branch) with the same harness: real ObjectQL, the in-memory driver and the protocol from dist/. The base is registered by registerApp, the pair installed by installPackage, and the override is a draft save into the pair declaring the override, then the publish. S is the shipped body, O the override; the envelope is label / _packageId / _provenance.

Only the bold cells move, and none of them is a protocol served read. translation was not measurable through the pair (the save is refused NOT_OVERRIDABLE in this harness). flow and action are outside the card.

email_template non-test registry readers, per the condition on the forced edits:

The plugin-email suite (48 files) and the cli ownership tests pass on the fixed head, as listed under Verification.

Follow-up: #29613 holds page, app, dataset, doc and book (row-served override path first, then the guard), and the two class-b findings: the pair's per-package layer is empty for those types, and their layered effective serves S while getMetaItem serves O.

Verification

Head c58da12 (c58da128a9b58e5d34788a9cabe48c1a87c1590f) (main merged in). All heavy runs went through scripts/pm/os-verify-lock.sh, and each VERDICT is command-exit 0.

• Full build ./packages/** and ./examples/**: 79/79 tasks.
• @objectstack/metadata-protocol test: 308 files passed (4 skipped), 22257 tests passed (26 skipped).
• @objectstack/objectql test: 542 files, 10517 tests passed.
• Typecheck of metadata-protocol plus 11 dependents (cli, client, cloud-connection, objectql, plugin-approvals, plugin-security, rest, runtime, service-automation, service-messaging, service-package): 12/12 tasks.
• Dogfood, 17 files touching email templates, metadata reads, package customization and overrides: 17 files, 138 tests passed.
• Cross-package pair-override suites: runtime 6 files / 59 tests (including packages-export-base-unchanged-per-type.integration.test.ts from fix(runtime): the base's package export leaves out its pair's dashboard and report overrides (#29563) #29597), cloud-connection 3 / 27, cli 2 / 118 (organization-ownership apply and withdrawal-pair), plugin-email 48 / 785.
• eslint --no-inline-config on packages/metadata-protocol and packages/objectql: exit 0.
• dispatch-gates --commands: 62 derived, 62 run, every one exit 0; dispatch-gates --ran reports 0 NOT-MEASURED, 0 UNRUN.

Run reconciliation — 62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 62 derived famil(ies) accounted for — 62 run, 0 NOT-MEASURED (a DERIVED zero — all 62 recorded an exit code and none of them is 3).

Generated by Claude Code