docs(adr-0029): amend D3 — a tenant object overlay is its own contributor layer (#6853)

[os-zhuang]

Fixes #6853

Design document only. No implementation, and none is intended in this PR.

The 2026-08-09 maintainer ruling on #6853 approved direction B in principle, rejected A, and shipped C separately as #7012 — and it made this card's deliverable the ADR-0029 amendment that designs B, because B's semantics were explicitly to be designed in the amendment, not guessed. docs/adr/** is maintainer-merged (#6741), so merging this PR is what ratifies the design.

What is added

• docs/adr/0029-…md — a Status-line entry plus an end-of-document ## Amendment (2026-08-09, #6853) section declaring D9. D1-D8 and D3's text are left standing (Prime Directive [WIP] Add Chinese version of the documentation #13); the amendment holds the present tense.
• scripts/adr-anchors.json — one entry: packages/objectql/src/registry.ts against ADR-0029.

The design question the ruling posed, and the answer

The tension it named: an overlay replaces the whole body today, while mergeObjectDefinitions merges fields additively — so modelling the overlay as an extender would silently stop an overlay removing a packaged field, and modelling it as a second own breaks assertSingleOwnerPerObject.

Chosen: a replace-semantics, NON-owning contributor kind (overlay). Not a new ownership kind.

• Resolution becomes base = overlay ?? own, then extenders fold on top exactly as today. That is bit-for-bit what the current splice already produces — today the overlay is the owner and extenders fold over it. The resolved schema, _provenance: 'org' included, does not move; only what the registry remembers does.
• assertSingleOwnerPerObject is unchanged, literally: overlays are not owners, so D3's sentence keeps holding with no exemption clause. That matters because ADR-0028 D5/D6 depend on D3 being unconditional. One violation class is added — an orphan overlay with no owner.
• computeFQN is untouched (it is identity today); the layer shares the owner's key and no namespace dimension is introduced. The measured namespace loss on the owner contributor is repaired by subtraction, because the owner is no longer removed.
• Priority stays descriptive. A constant between owner (100) and extender (200) keeps the list in layer order, but base selection asks the kind, never "highest priority wins" — extender priority is author-declared and must not be able to re-rank which layer is the base.
• Artifact identity is read from the OWNER contributor, not the merged object. This clause is not implied by the one above and had to be decided: the merged body deliberately keeps _provenance: 'org', so isArtifactBacked only stops lying if getArtifactItem's object branch reads the owner's definition.

An ownership kind that also owns is rejected in the record: it grants authority the overlay measurably never uses (it registers no namespace, does not decide package membership, owns no table), and it would make D3 conditional at every getObjectOwner call site.

#6995, per the ruling

Answered by the model rather than left open. Because the overlay makes no ownership claim, registerObject's "already owned by package X" throw is unreachable from the overlay seams, so the silent-discard-with-success-receipt cannot recur. The amendment rules all three bindings: same package (normal), package-less sentinel (accepted — today's throw was an artefact of the borrowed slot, not a decision), different package (refused at the producer, loudly). The last one carries its own reason: the overlay-uniqueness index can legitimately hold two rows for one (type, name) bound to two packages, which for object the registry can never represent, because computeFQN is identity and there is exactly one entry per object name.

Honestly stated cost

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, not a new restriction, but a deployment living in the post-first-write state will feel it. Recorded in D9.6 with the migration note.

The amendment also carries a measured blast-radius table (every .ownership read site on the current tree and what D9 does to it) — including one silent regression a naive implementation would ship: provisionPrimary / provisionSearchCompanion are gated on own, and that gate has to become "is this a BASE layer", or nameField changes on every overlaid object.

Verification

Prose has no test coverage, and no reverse verification is reported, because none exists for a design document — inventing one would be fabricated evidence. What was done instead: every file:line claim was re-read on 2f3e79351 rather than carried over from the 08:12Z measurement report (which cites 51f2bb8c3), and the docs gates were run locally:

check-adr-anchors: OK (47 anchored file(s), every governing ADR still referenced; 118 decision number(s) …; 20542 citation(s) across 3353 file(s) resolve)
check-adr-links:   531 relative link destination(s) under docs/adr/ resolve
check-nul-bytes:   OK (scanned 6525 tracked text file(s); no raw ASCII control bytes)
check-doc-authoring / check-docs-audit-scope / check-role-word /
check-quick-reference-counts / check-release-notes: all OK

pnpm install was deliberately skipped: the diff is one Markdown file and one JSON file, and every gate above is a zero-dependency node script — which is exactly how check-links.yml and adr-merge-approval.yml run them in CI.

Changeset

None, deliberately. This releases no package, and pr-automation.yml's changeset gate prescribes the skip-changeset label rather than an empty changeset file (an empty file is a real input to changesets/action; the label is a gate-level exemption). The label is applied on this PR.

Landing

Do not auto-merge. ADR maintainer approval (#6741) will sit unsatisfied until the maintainer's own approval, and per the ruling that is the point: it puts the design question on the maintainer's desk by construction.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 9, 2026 2:21pm

[os-zhuang]

ACCEPT — PM step-7 review (domain:metadata seat, session session_01W6bLax4KMrSfnE1ydFU8Dw). Marking ready. Deliberately NOT enabling auto-merge and not queueing — docs/adr/** is maintainer-merged only (#6741), and per the 08:52Z ruling that gate is the point: it puts the design question on the maintainer's desk by construction.

Verified against GitHub:

• File surface: 2 files — the ADR amendment and one scripts/adr-anchors.json entry. No implementation, exactly as the ruling required: applyObjectRegistryMutation, loadMetaFromDb, registerObject, restoreArtifactRegistryView and saveMetaItem's gate are all untouched, so this does not collide with 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 (in flight in tier 3) or with PR fix(metadata-protocol): refuse an org-scoped write of a type that has no per-org channel (#6190) #6973 (being rebased by another session).
• CI on 746c47d: 26 check runs, all completed, none in_progress — ESLint success, TypeScript Type Check success, Check Documentation Links success, Check Changeset success (read the skip-changeset label live), plus Auto Label / Check PR Size / Test Core / Dogfood Regression Gate / Console Pin Freshness / filter / "No other open PR may claim the same issue"; packages/** jobs skipped by path filter. ADR maintainer approval = failure, which is the designed pending human gate — its own log says drafting the PR was fine and only the merge is reserved.
• No fabricated reverse verification. Prose has no test coverage, and the report says so plainly instead of inventing a red/green — the PR docs(adr-0005): amend the overlay-index section instead of rewriting it #6981 precedent, applied correctly. What was run is reported with output: check-adr-anchors self-test + gate (47 anchored files, 118 decision numbers, 20542 citations across 3353 files resolve), check-adr-links (531 destinations), check-nul-bytes plus a targeted control-byte scan of both changed files, check-doc-authoring, check-docs-audit-scope, check-role-word, check-quick-reference-counts, check-release-notes.

Why this design answers the question that was actually asked

The ruling sent this card to design because B's semantics could not be guessed: an overlay replaces the whole body while mergeObjectDefinitions merges additively, so "overlay as extender" would silently stop an overlay removing a packaged field, and a second own would break assertSingleOwnerPerObject.

D9 resolves that by refusing both horns: a third, non-owning overlay contributor kind with replace-semantics on the base layer (base = overlay ?? own, extenders folding on top unchanged). The decisive argument is the one I would have wanted and did not ask for — it resolves bit-for-bit to what today's splice already produces. The resolved schema, _provenance: 'org' included, does not move; only what the registry remembers does. That is what makes it safe: assertSingleOwnerPerObject stays literally unchanged (load-bearing, since ADR-0028 D5/D6 depend on D3 being unconditional), computeFQN stays identity, and base selection is made by kind rather than by priority, so an author-declared extender priority cannot re-rank the base.

The clause that would have been guessed wrong is called out rather than buried: getArtifactItem's object branch must read the owner contributor, not the merged body — otherwise isArtifactBacked keeps lying even after B lands, and half of B's purpose evaporates. That is precisely the kind of second-order requirement a design document exists to surface before implementation, not after.

#6995 is answered by the model rather than left dangling, as the ruling required: the row's package_id is provenance on the layer and never an ownership claim — same-package normal, package-less accepted, different-package refused loudly at the producer, with a real reason (the overlay-uniqueness index can hold two rows for one (type, name) that the object registry can never represent).

Also good: one anchor added for packages/objectql/src/registry.ts → ADR-0029, which was unanchored despite implementing D3 — the same recurrence shape PR #6981 found for ADR-0005.

Both open questions resolved here, no escalation

1. ADR-0005 "Amended by" pointer — A: leave it until acceptance. Correct, and for the right reason: an "Amended by" line asserts acceptance, and this is a proposal until the maintainer merges it. Writing it now would put a claim into an accepted record that may never become true. It is a one-line follow-up in the accepting commit, and it is recorded so it is not lost.
2. Late install (a package registering an object a tenant sys_metadata row already owns under the sentinel still hits "already owned by") — stays open in the record, decided by the implementation card. The recommendation (the code layer becomes owner, the tenant contribution re-classified as its overlay layer) is the outcome that loses nothing, but it is a second discriminator that wants its own measurement. Naming it as open in an ADR is the honest move; deciding it from a design document without measuring would repeat exactly the mistake this whole family was escalated to avoid.

@maintainer: this one needs your review to move — and by the ruling's own logic, reviewing it is the decision on B's semantics.

---

Generated by Claude Code