Skip to content

Commit 0e4b0fa

Browse files
objectstack-fleet[bot]os-warrenclaude
authored
docs(adr-0146): D8 item 2 names the pair's export, GET /packages/X.custom/export, never the base's (#29791)
<!-- claude-projects-attribution: {"github_login":"os-warren"} --> _Requested by **Warren** · [project thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ8HLVv2CKkgELbzCPtU3zP5X)_ Fixes #29601 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:ADR-0146 D8 第 2 条里「the export of X's app surface」改为点名配对包的导出 `GET /packages/X.custom/export`(指向第 3 条),并写明它永远不是基础包的导出 `GET /packages/X/export`;第 2 条首句与「Decided here」#5 随之收窄;Refs 加一条带日期的出处。只改措辞,+12/−6。 - 为什么改:原句可读成基础包导出,与第 3 条「基础包导出原样、配对包导出带 `overrides` 声明」矛盾;#29563 的开发把它列为缺陷,PR #29597 和 `getMetaItemsPerPackage` 的注释都按配对包导出理解。 - 风险与回滚:无代码、无 schema;不改任何裁决,Status 行不加修订条目(出处记在 Refs);回滚即还原这两个 commit。 - 先看:`docs/adr/0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md` D8 第 2 条,其次「Decided here」#5 与 Refs。 - 两分钟验证:`git diff origin/main -- docs/adr/0146-*.md`,预期只有 D8 第 2 条、「Decided here」#5 与 Refs;`pnpm check:adr-links && pnpm check:adr-anchors` 预期绿。 - 需要你做的:Tier H(`docs/adr/**`),席位合同审查 PASS(6595888270,delta 6596113742)且已 ACCEPT;需要 GOVERNED_APPROVERS 的 APPROVED 后落地。 ## What changes One sentence of ADR-0146 D8 item 2. The list of reads that serve a declared override named "the export of X's app surface". It now names the export it means: the **pair's** export, `GET /packages/X.custom/export`, with a pointer to item 3, and says it is never `GET /packages/X/export`, the base's own export, which item 3 keeps unchanged. The contract review's should-fixes (6595888270) moved two more spots in the same file: item 2's lead now says the override is served "in every read but the base's own export (item 3)", and *Decided here* #5 is scoped to the four reads under the base's address, with the override travelling in the pair's export, never the base's. Refs gains a dated entry naming #29601 and this PR. No code, no schema, no other ADR. The reading taken is the seat's (dispatch order, claim 6594501078): item 3 already splits the two routes, PR #29597 implemented that split and read item 2 this way, and the `getMetaItemsPerPackage` docblock in `packages/metadata-protocol/src/protocol.ts` reads it the same way. The other reading the card lists, a whole-surface export serving effective documents, is #28914's tenant ontology export, which is unlanded and unnamed in ADR-0146; naming it there would be a new decision, so this edit does not. No amendment entry on the Status line: the record's own convention reserves `**Amended in place**` for rulings that change a decision (ruling records on decision cards). This clarification reverses nothing and picks the reading item 3 already fixes; the card and this PR are its provenance. ## Why Read literally, item 2 said the base's export serves the override, while item 3 says the base's export carries the base unchanged. Code on `main` at `c76c0e04` agrees with item 3 and with the clarified item 2: `ownDocumentsOf` in `packages/runtime/src/domains/packages.ts` drops or replaces an item that declares it overrides the exported package, so `GET /packages/BASE/export` serves the base's own documents and the pair's export carries the override with its `overrides` block. No code on `main` contradicts the reading. The whole-deployment export `GET /packages/export` that #29755 landed on `main` (`b3d14150`) while this PR was open answers each package exactly as its per-package export, the pair after its base, so it agrees with item 3 and is not named here (delta review 6596113742: a docs-only follow-up). ## Tests Docs-only; no test changes. The gate families derived for the diff ran locally (Verification). ## Acceptance notes - Naming `GET /packages/export` (#28914, landed by #29755) in ADR-0146 is a new decision and goes to a docs-only follow-up card, not this clause. - `skip-changeset`: `docs/adr/**` publishes nothing (the fast lane of the changeset rule). ## Verification Head `71e8cc17` (two commits on `origin/main` `c76c0e04`; the second answers the contract review's should-fixes). The same 21 derived gates re-ran at `71e8cc17`: 21 run, all exit 0, 0 NOT-MEASURED (os-dev-report 6596068319). <details><summary>dispatch-gates --commands (21) and --ran reconciliation, first run at 954c3bd</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 21 commands from the diff (1 path, +3/-1). Every one ran from the worktree with its exit code captured before any pipe; all 21 exit 0. Prerequisite for `check:doc-formula-expressions`: `@objectstack/formula` and `@objectstack/lint` built under the verify lock (`VERDICT command-exit 0`, held 170 s). `node scripts/pm/dispatch-gates.mjs --ran ran.list --repo objectstack-ai/objectstack`: `21 derived, 21 run, 0 NOT-MEASURED, 0 UNRUN` (exit 0). Exit 0: check-adr-links (+ --self-test), check-closing-keyword-parity (+ --self-test), check-comment-mask-corpus, ci/plan-test-core-shards --self-test, lint check:doc-formula-expressions, check:adr-anchors, check:adr-index, check:adr-symbol-anchors, check:ci-filter-parity, check:closed-ceremony-text, check:cross-package-test-inputs, check:doc-authoring, check:driver-memory-census, check:gitlink-declared, check:nul-bytes, check:pm-governed-merges, check:pm-prior-rulings, check:refd-timer-probe, check:watch-hint-literal. Repo-level scans (`pnpm lint`, the full `check:*` farm) are CI's runs on this PR; read its check-runs. </details> Governed surface (`docs/adr/**`, Tier H): this PR stays a draft; it lands only after an authorized APPROVED review from `GOVERNED_APPROVERS`, following the owning seat's contract-tier review and ACCEPT. No reviewers requested by the dev. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (No `packages/spec` change.) - [x] 2. Every name I added uses the casing for its kind. (No names added.) - [x] 3. No formatter ran; `pnpm lint` is CI's repo-level run (no code touched). - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset: docs-only, publishes nothing; both declaration lines are filled in above. - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the 维护者速读 block is the os-dev house format). - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01JQwxbYeS2U1HKXS13SzfKe --- _Generated by [Claude Code](https://claude.ai/code/session_01JQwxbYeS2U1HKXS13SzfKe)_ <!-- signed: domain:server#3 · os-warren · session_01JQwxbYyp6wSRcywGFK2L4A --> --------- Co-authored-by: os-warren <318460043+os-warren@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
1 parent eb05ea2 commit 0e4b0fa

1 file changed

Lines changed: 12 additions & 6 deletions

File tree

‎docs/adr/0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -418,10 +418,13 @@ from **one** resolution:
418418
code package is a candidate of `packagelessAddress`, and a stored row bound to another package never wins by being
419419
the only stored row (#28238, N-03). A stored row with **no** package — the row Setup writes today — keeps winning
420420
over the code package until [D11](#d11) migrates it; ⛔ that card does not break an existing customization.
421-
2. **Within X's address, a declared override is served over the base's document.** The read that serves X's name — the
421+
2. **Within X's address, a declared override is served over the base's document, in every read but the base's own
422+
export (item 3).** The reads that serve X's name or carry X's customizations — the
422423
package-less read, the read naming X (`?package=X`), the layered read (`packages/metadata-protocol/src/protocol.ts#getMetaItemLayered`: `code` = the base's
423424
document, `override` = the `.custom` item, `effective` = the served one), the list (`GET /api/v1/meta/:type`, scoped
424-
to X or not) and the export of X's app surface — serves the **one** document the declaration selects, the `.custom` item that declares it. An item of the pair that
425+
to X or not) and the export that carries X's customizations, the **pair's** export `GET /packages/X.custom/export`
426+
(item 3; ⛔ never `GET /packages/X/export`, the base's own export, which item 3 keeps unchanged) — serve the **one**
427+
document the declaration selects, the `.custom` item that declares it. An item of the pair that
425428
bears X's name **without** the declaration, and an item of any other dependent that bears X's name — declared or not —
426429
have no place under this record: each is refused when its package publishes ([D2](#d2)); until N-09 lands, item 1 keeps
427430
the code package the owner of X's address, so such a row is not served as X's (N-03). A same-named item of a package
@@ -676,9 +679,10 @@ of Q1's refusal and `action` — were ruled by the maintainer on 2026-10-31 (dec
676679
against `FieldSchema` and publishes them as one closed constant — the whitelist the write gate reads, in the shape of
677680
[D2](#d2)'s type list; the maintainer's 2026-10-31 reading: the criterion stays, the whitelist is that constant. A
678681
list written here would be either stale or invented.
679-
5. **A declared override is served within the base's address for all five read kinds, and the base's own document
680-
stays reachable as the layered read's `code` layer** ([D8](#d8)) — so "Restore package original" needs no second
681-
read path and the chip needs no computation.
682+
5. **A declared override is served within the base's address for the four reads under it — package-less, named,
683+
layered and list — and travels in the pair's export, never the base's ([D8](#d8) items 2 and 3); the base's own
684+
document stays reachable as the layered read's `code` layer** ([D8](#d8)) — so "Restore package original" needs no
685+
second read path and the chip needs no computation.
682686
6. **The migration is an administrator's CLI ceremony, idempotent, per base** ([D11](#d11)), in ADR-0131 D10's shape
683687
— not a boot step: a boot that rewrites rows into a package it creates is the recorded-verdict defect AGENTS.md's
684688
*Startup registry reads* section names.
@@ -700,7 +704,9 @@ of Q1's refusal and `action` — were ruled by the maintainer on 2026-10-31 (dec
700704
`basedOn` records the base package's version, ruling record 6549129352 on [#28404](https://github.com/objectstack-ai/objectstack/issues/28404));
701705
PR [#28145](https://github.com/objectstack-ai/objectstack/pull/28145) (closed unmerged; its three wording fixes
702706
S13–S15 are folded into this rewrite); PR [#28045](https://github.com/objectstack-ai/objectstack/pull/28045) (the
703-
Proposed draft this rewrite replaces, hand-merged 2026-10-30).
707+
Proposed draft this rewrite replaces, hand-merged 2026-10-30); card [#29601](https://github.com/objectstack-ai/objectstack/issues/29601)
708+
and PR [#29791](https://github.com/objectstack-ai/objectstack/pull/29791) (2026-11-03, wording only: [D8](#d8) item 2 names
709+
the pair's export and scopes its lead; *Decided here* #5 scoped with it).
704710
- [#27356](https://github.com/objectstack-ai/objectstack/issues/27356) rows 12, 13, 14, 19, 20, 21 and their landed
705711
PRs #27376, #27927, #28076.
706712
- ADR-0005, ADR-0009, ADR-0010, ADR-0029, ADR-0048 (and its 2026-10-08 addendum), ADR-0070, ADR-0126, ADR-0131,

0 commit comments

Comments
 (0)