Implement ADR-0029 D9 — register a tenant object overlay as its own contributor layer instead of splicing out the packaged owner

[os-zhuang]

Implementation card for ADR-0029 D9, which was ratified when PR #7087 merged (fb5ebc5df, 2026-08-10). Filed by the domain:metadata PM seat as the designed follow-on to #6853; the design question is settled, this card is the code.

Why this exists

The maintainer's 2026-08-09 ruling on #6853 approved direction B in principle but required its semantics to be designed in an amendment, not guessed. That amendment is now merged as ADR-0029 D9. Nothing in this card re-opens the design — read D9 and implement it.

Measured today (see #6853's dev report, and #7012 which shipped the stop-the-bleed half): when an overlay row's package_id equals the packaged owner's id, registerObject splices the packaged contributor out, so the packaged definition is destroyed at write time rather than shadowed, and loadMetaFromDb replays that destruction on every boot with no gate and no log.

What D9 specifies

• A tenant overlay registers as a third, NON-owning overlay contributor kind with replace semantics on the base layer — not a new ownership kind, and not an extender.
• Resolution becomes base = overlay ?? own, with extenders folding on top exactly as today. This is bit-for-bit what the current splice already produces: the resolved schema, _provenance: 'org' included, does not move. Only what the registry remembers changes.
• assertSingleOwnerPerObject is unchanged, literally — overlays are not owners, so D3's sentence keeps holding with no exemption clause (ADR-0028 D5/D6 depend on D3 being unconditional). One new violation class: an orphan overlay with no owner.
• computeFQN untouched (identity today); the layer shares the owner's key.
• Priority stays descriptive. A constant between owner (100) and extender (200) keeps list order, but base selection asks the kind, never "highest priority wins" — author-declared extender priority must not be able to re-rank which layer is the base.

Three things a naive implementation gets wrong — all named in D9

1. getArtifactItem's object branch must read the OWNER contributor, not the merged object. The merged body deliberately keeps _provenance: 'org', so isArtifactBacked only stops lying if artifact identity is read from the owner's layer. This clause is not implied by the layering change and has to be done deliberately.
2. provisionPrimary / provisionSearchCompanion are gated on own — that gate must become "is this the BASE layer", or nameField changes on every overlaid object. D9 carries a measured blast-radius table of every .ownership read site; work from it rather than from grep alone.
3. An object overlay write over a packaged object is silently discarded by registerObject's ownership rule while saveMetaItem reports success #6995 is subsumed and must be implemented as ruled: the row's package_id is provenance on the layer, never an ownership claim — same package normal, package-less sentinel accepted (today's throw was an artefact of the borrowed slot), different package refused loudly at the producer. The reason for the last one is in D9: the overlay-uniqueness index can hold two rows for one (type, name) bound to two packages, which the object registry can never represent because computeFQN is identity.

Cost that is already accepted in the record

With the predicate honest, saveMetaItem refuses an overlay write to a packaged object with NOT_OVERRIDABLE every time, not only the first — object declares allowOrgOverride: false. Today the first write is refused and, by destroying the evidence, admits every later one through the allowRuntimeCreate tier. This is the declared contract enforced consistently rather than a new restriction, but a deployment living in the post-first-write state will feel it. D9.6 carries this with its migration note; do not soften it without a new ruling.

Left open by D9 on purpose

• Late install — a package registering an object a tenant sys_metadata row already owns under the sentinel still hits "already owned by". D9 records the recommendation (the code layer becomes owner, the tenant contribution re-classified as its overlay layer) but explicitly leaves it to this card with its own measurement, because it is a second discriminator.
• ADR-0005's "Amended by" cross-reference was deliberately not written while D9 was a proposal, since that line asserts acceptance. D9 is now accepted, so the one-line pointer is in scope here.

Family

• Registry heal restores the metadata-map view but never re-registers a packaged contributor definition an overlay save replaced #6853 (the finding + the ruling), PR docs(adr-0029): amend D3 — a tenant object overlay is its own contributor layer (#6853) #7087 (D9 itself)
• Stop-the-bleed: tier-3 heal must not unregister a package-bound object — decide on the contributor's package binding, not isArtifactBacked (#6853 ruling C) #7012 / PR fix(metadata-protocol): tier 3 refuses to unregister an object bound to an installed package (#7012) #7093 — the stop-the-bleed guard already landed; D9 is what makes its accepted cost unnecessary, so check whether that guard can be narrowed or retired once isArtifactBacked stops lying
• MetadataFacade.register('object', …) writes where neither of its own object reads look #6725 — the write side of the same split, dormant in-tree; domain:engine-core's surface, so coordinate rather than absorb
• A deleted runtime object is still served by SchemaRegistry.getObject — the registry heal reaches the metadata map but never objectContributors #6808 / PR fix(objectql): deleting an object really unregisters it — a name-addressed SchemaRegistry.unregisterObject (#6808) #6818 — the removal half, merged; its unregisterObject is the verb the overlay-layer removal reuses

[os-zhuang]

Claim: PM loop round 10 (domain:metadata seat, sticker #6367)

Session: session_01W6bLax4KMrSfnE1ydFU8Dw
Branch: claude/issue-7277-adr-0029-d9-overlay-layer
Worktree: objectstack-issue-7277
Base: origin/main @ fb5ebc5df or newer (the commit that ratified D9)

Dispatching now rather than waiting for a triage grading pass: the design landed 30 minutes ago, the lane has no other dispatchable card (its three queue items are all blocked on other seats), and the standing maintainer directive is to keep dispatching. Triage remains free to grade this card — including target:v17 — while it is in flight; nothing in the dispatch depends on that grading.

⛔ Not re-opening the design. D9 is ratified. Any disagreement with it is a new ADR amendment, not a decision for the implementing dev.

The card body carries the full constraint set. The three that a naive implementation gets wrong (owner-contributor artifact identity, the own-gated provisioning that must become base-layer-gated, and #6995's three bindings) are named there and are all repeated in the dispatch as hard requirements, each with its own pin.

---

Generated by Claude Code

[os-zhuang]

os-dev report

Issue: #7277 · PR: #7306 (draft) · Branch: claude/issue-7277-adr-0029-d9-overlay-layer · Base: origin/main @ 708431313 · Status: done · Premise still valid: yes

D9's premise was re-verified against origin/main before any edit: the two hydration seams still pass two arguments (so ownership defaults to 'own'), registerObject's same-package splice still removes the packaged contributor, getArtifactItem's object branch still reads the merged body, provisionPrimary is still gated on own, and ObjectOwnershipEnum still has zero runtime consumers. Only the line numbers had moved.

1. The bit-for-bit resolution check

The pin compares two registries directly: D9 (packaged own + tenant overlay) against the pre-D9 world (the overlay body as the sole own — what the splice left behind), with expect(d9.getObject(name)).toEqual(preD9.getObject(name)). No resolved schema moved anywhere, _provenance: 'org' included. The pin is not decorative: RV-3 below turns it red, which is what "the resolved object moved" actually looks like.

2. The three naive-failure pins

1. getArtifactItem reads the OWNER contributor. Implemented via a new private resolveOwnerLayer(fqn) — the owner's declaration with its extenders folded on, ignoring the overlay layer. What comes back is the code-layer baseline, which is what every consumer of lookupArtifactItem wants (_lock / _packageId / _provenance grafting, the code baseline layer); with no overlay registered it is byte-for-byte the previous answer, pinned separately. Uncached on purpose so it cannot drift from mergedObjectCache's seven invalidation points.
2. The provisioning gate is now "is this a BASE layer" (own or overlay). Worked from D9 section 5's blast-radius table, not from grep — dispositions in section 5 below.
3. An object overlay write over a packaged object is silently discarded by registerObject's ownership rule while saveMetaItem reports success #6995's three bindings implemented as ruled: same package normal, package-less sentinel accepted, different package refused at the producer with the newly minted OBJECT_OVERLAY_PACKAGE_MISMATCH / 422 and counted in loadMetaFromDb's per-record errors at boot.

3. Late install — measured, then implemented

D9's recommended default is taken: the code layer becomes owner, the tenant contribution is re-classified as its overlay layer. Narrowed to fire only when the sitting owner is tenant-authored (_provenance: 'org') and the incoming body is not — two code packages claiming one name is still D3's cross-package refusal, pinned.

The measurement found a second spelling the card did not name: when the arriving package's id equals the row's binding, pre-D9 did not throw "already owned by" — it took the re-registration splice and destroyed the tenant's customization silently. Both spellings are pinned. A useful side effect: a boot order that puts loadMetaFromDb before package registration now self-heals into the same two layers.

4. What happened to #7012's guard — RETIRED, measured

RV-5 put the guard back, unchanged in intent, and exactly one test turned red: a package-bound RUNTIME-authored object is retired, and its data plane closes. Nothing that protects a package-shipped object moved at all.

That is the whole argument. After D9 the packaged own contributor is never spliced out, so isArtifactBacked is honest and the case the guard was written for cannot reach the retirement limb (the layer subtraction returns first, and the predicate is true besides). What the guard still reached was only its own accepted cost — a package-bound RUNTIME-authored object (Studio's package workspace, #4636) kept listable-but-rowless until restart. With the predicate honest that is no longer the cheap direction, it is the wrong answer: nothing ships the name, the row WAS the item, and data CRUD kept writing into a table whose metadata the operator had just deleted.

Also verified for assumption 2: removeObjectOverlay cannot live in tier 3. Tier 1 (removeRuntimeShadow) returns as soon as it heals the generic metadata map, so an object whose plain-key shadow it can heal would keep its overlay layer registered — the #6808 asymmetry replayed one layer down. The subtraction runs ahead of the tier walk, unconditionally for object.

5. Blast-radius table dispositions (D9 section 5, row by row)

D9 row	Disposition
registry.ts default priority	third arm added, DEFAULT_OVERLAY_PRIORITY = 150
provisionPrimary / provisionSearchCompanion	gate changed to own or overlay; pinned by the nameField test AND (unexpectedly) by the bit-for-bit test
second-owner throw	now unreachable from the overlay seams; still thrown for a second code package (pinned)
same-package own splice	untouched; the overlay never enters this branch. Late install added ahead of it
same-package extend splice	mirrored for overlay, keyed by KIND not package (D9.9)
base selection	find(overlay) ?? find(own), extracted into a shared foldExtenders
extender fold	unchanged
getAllObjects _packageId stamp	no code change needed — it already reads getObjectOwner, which now naturally yields the packaged owner. Pinned
getObjectOwner	unchanged; doc states it still means "owns the table"
assertSingleOwnerPerObject	count literally unchanged; orphan-overlay violation class added
unregisterObjectsByPackage	the overlay layer leaves with the owner it layers over
unregisterObject	extender guard unchanged; the layer-addressed verb runs first in the heal
getArtifactItem object branch	reads the owner layer (D9.6)
spec/data/object.zod.ts	third value + the "loader-set, never authored" clause
protocol.ts both seams	D9.8 discriminator via getPackagedObjectOwner
objectql/src/plugin.ts two seams	discriminator adopted, with a narrower rule: a body arriving under the owner's own id and not claiming tenant provenance stays own, so a package's HMR reload is not mistaken for a layer

ObjectContributor is exported, so the widened union is a public type change — minor, with a changeset, as D9 says.

6. Reverse verification — direction decided before each run

Every probe reverts to this PR's own base; dist is rebuilt before any result is read.

Probe	Predicted	Measured	Reading
RV-1 getArtifactItem back to the merged body	5 red	6 stable red + 1 unstable	Missed prediction: the late-install pin also asserts the predicate is honest — cause identified. The unstable one is GREEN at --maxWorkers=1 and in isolation under the same probe; reported as an ordering artefact, not counted as evidence
RV-2 base selection back to own	6-8 red	11 red	Under-predicted
RV-3 provisioning gate back to own only	exactly 1 red	2 red	Missed one, and it is the valuable one: the bit-for-bit pin goes red. Skipping title provisioning on the overlay layer MOVES the resolved schema
RV-4 both seams back to 'own'	~9 red, all in the e2e file	exactly 9 red, 0 in the registry unit file	Hit, including the prediction that the registry unit file is immune (it registers 'overlay' directly)
RV-5 #7012's guard put back	exactly 1 red	exactly 1 red	Hit — the measured basis for the retirement

Green in both directions, reported as guards not evidence: the single-owner count on an overlaid object; the cross-package second-owner refusal; the artifact item still carrying extenders when there is no overlay; a tenant re-writing its own runtime object staying a single own; package-less and non-installed-binding objects still being retired; non-object types untouched by the mismatch rule.

Unmeasured: none. The unstable RV-1 red is reported as unstable rather than counted as passed.

7. CI — per-job conclusions on 426cf5281

• ESLint — completed / success (this is where the repo's family gates run)
• TypeScript Type Check — completed / success
• Build Core, Build Docs, Test Core (1/3, 2/3, 3/3) and the roll-up, Dogfood Regression Gate (1/3, 2/3, 3/3) and the roll-up, Dogfood Verify CLI, Temporal Conformance (live PG + MySQL), Check Changeset, Check PR Size, Spec property liveness, Console Pin Freshness, Check Documentation Links, Auto Label — all completed / success
• ADR maintainer approval — completed / failure, BY DESIGN. The PR touches docs/adr/0005-*.md (the "Amended by" pointer this card scoped). The gate's own message: "Drafting this PR was fine and stays fine — only the MERGE is reserved." Green path is an APPROVED review from @hotlong, which re-runs the check. Nothing to fix here.

Local: objectql 168 files / 2974 tests, metadata-protocol 67 / 861, plus the consumption-radius sweep (metadata 30/593, runtime 118/1837, rest 76/1219, plugin-security 43/878, cli 105/1139) — all green. The suites that actually exercise the changed path are objectql and metadata-protocol; the other five are breadth, and that is stated rather than counted.

8. Two things needing your attention

a. CROSS-SEAT: two packages/spec files touched. The dispatch says to stop and report if packages/spec is needed. Both edits are required verbatim by D9.1 (ObjectOwnershipEnum gains 'overlay') and D9.9 (the ADR-0112 code), and D9.1 explicitly rejects the alternative of a parallel local union ("one vocabulary, not a parallel list", Prime Directive #8) — so the card cannot be implemented as ratified without them. I implemented rather than stopping, and declare it here for routing. Measured against #6298's own admission criterion: ObjectOwnershipEnum has no runtime consumer in this repo, so widening it changes no metadata's legality — what parsed before parses byte-for-byte after, and what was rejected stays rejected.

b. D9.6's cost reaches one gate the record does not name. Confirmed that saveMetaItem now refuses an overlay write to a packaged object every time (pinned, three attempts, asserting code AND status). The same predicate also feeds deleteMetaItem's two-tier authorization and SysMetadataRepository.assertAllowed — so RESETTING such a customization is refused too, and the repository check is topology-independent, so a control-plane kernel refuses as well. Not softened: both are pinned, since a fixture encoding the old leniency would be encoding the defect. The hatch is the same one door (OS_METADATA_WRITABLE=object), now required for the LIFE of the customization rather than only its first save. D9.6 states this for the save side only; the delete side is the same declaration on the other verb, and it is exactly the delete whose unchecked version took the object off the data plane (#7012). Flagging in case the maintainer wants a separate ruling on the reset path.

Not absorbed: #6725 (the write side, domain:engine-core). Not touched: content/docs/releases/. content/docs/references/** (12 files) are regenerated artifacts — the whole diff is the new error code count plus the ledger and object pages.

No out-of-scope findings were filed: nothing surfaced that was not already covered by D9's own record or by this card.

---

Generated by Claude Code

---

Generated by Claude Code