Skip to content

Commit 0f254f4

Browse files
docs(adr): ADR-0048 §3.5 rename-on-install ships for unmanaged copies; ADR-0131 D6 notes the Q3 extension and the Q6 answer (#31205)
<!-- claude-projects-attribution: {"github_login":"marchtian"} --> _Requested by **田騏** · [project thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiU1rhbHT2BKdngdowSzudqP)_ Fixes #30794 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:两份 ADR 加注记。ADR-0048 §3.5「装时改名」从「暂不做」改为「unmanaged 副本可以改名,managed 永不改名」;ADR-0131 D6 记下副本可带自己的 namespace,以及 Q6 的裁定。 - 为什么改:PR A(#30997)和 PR C(#31182)已经上线了改名安装,ADR 还写着「不做」;Q6 你已裁定 B(改名副本不拒绝),要落进决策记录。 - 风险与回滚:只改文档,不动代码、不发版;原段落一字未改,只在旁边加带日期的注记和状态行条目;回滚即 revert。 - 先看:`docs/adr/0131-total-organization-ownership-no-null-organization-id.md`(D6 Unmanaged 后的新注记,Q6 那段)、`docs/adr/0048-cross-package-metadata-collision.md`(§3.5 下的注记)。 - 两分钟验证:打开 ADR-0131 搜「Note (2026-11-07, #30794)」,读 Q6 一段,预期写的是「改名副本不拒绝,未改名副本 Q6 原文有效」,并引用裁定记录 6709037798。 - 需要你做的:Fable 复核与席位 ACCEPT 之后,由维护者(os-zhuang 或 hotlong)合并。 ## What changes Docs only, two files, nothing else (`skip-changeset`: the diff publishes nothing). - **ADR-0048 §3.5.** The original paragraph stays verbatim. A dated note `Amended (2026-11-07, #30794)` records that rename-on-install ships for unmanaged copies only: a `targetNamespace` on an unmanaged install renames the copy through `planNamespaceRename` (`packages/metadata-protocol/src/package-namespace-rename.ts`), the one engine `duplicatePackage` already applies (ADR-0070 D4). It states what the two doors share and what they do not (only the duplicate rebinds a permission set's `packageId`, ADR-0086 D3; only the import judges copy names against the item-name grammar and the 63/255 limits); that a view container follows its object on both doors; the refusals before the base exists, including the `targetNamespace` refusals that answer `400 INVALID_REQUEST` since #31182; that §3.2 runs on the renamed names; that a managed install is never renamed (`targetNamespace` beside it: `400 INVALID_REQUEST`); provenance (`sourceNamespace`, `installedFrom.namespace`); and that the CLI sends no `targetNamespace`. Out of scope: bare non-object names (ruling C on #30798), seed data, and the hosted-cloud default namespace (objectstack-ai/cloud#3624). The status line gains an **Amended** entry. - **ADR-0131 D6.** After the **Unmanaged** bullet, a dated note `Note (2026-11-07, #30794)`: Q3 on #15213 (seat answer, stage-0 ACCEPT record `6108175106`) is extended — the copy still goes into a NEW base, and keeps the source namespace unless the install names a `targetNamespace`. Q6 (same record) does not apply to a renamed copy, by the maintainer's ruling **B** (record `6709037798` on #30794, 「B 不拒绝(推荐)」); for a copy that kept the source namespace, Q6 stands exactly as written. The status line gains an **Amended** entry. ## Review - **Fable review (independent, contract tier), verdict PASS with nits**, no must-fix or should-fix. Scope per the narrowed rule: the two ADR diffs, checked claim by claim against the code they describe. Files it read: both ADRs; `packages/metadata-protocol/src/package-unmanaged-install.ts` (whole), `package-namespace-rename.ts` (whole), `protocol-package-commits.ts` (duplicate and import callers); `packages/cloud-connection/src/marketplace-install-local-plugin.ts` (managed `targetNamespace` refusal, step 1f `findEnvironmentBaseHoldingNamespace`, `installedFrom`); `marketplace-install-local-install-modes.test.ts` (the Q6 = B pair); `content/docs/deployment/install-modes.mdx`; `packages/cli/src/commands/package/install.ts`; `packages/spec/src/api/package-lifecycle.zod.ts`; ADR-0070 and ADR-0086 headings. It also confirmed records `6108175106` and `6709037798`. - Nits applied in `35c09fa7`: "Every reference to a renamed name follows" narrowed to "Every reference the engine reads follows (the first bullet below says where)"; the #15213 Q3/Q6 now say they are that record's, not ADR-0131's own §6 Q3/Q6. Not changed: the status-entry punctuation (harmless), and the cloud#3624 citation (not verifiable from this repo, kept as the card states it). Under the narrowed rule no delta re-review is owed for nits. ## Acceptance notes - objectstack-ai/cloud#3600 comment 6676044775 (the epic ruling) was not read: it is in another repository this session cannot reach. Someone who can read it should check the §3.5 note agrees with it. - ADR-0048's TL;DR item 5, its non-goals line and Phase 4 still describe rename-on-install as a non-goal; they are kept verbatim as the record's original text, and the status line plus the §3.5 note carry the amendment. ## Verification <details><summary>Derived gates (head 35c09fa): 21 derived, 21 exit 0</summary> Derived with `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (2 paths vs merge base bd5a443), run on the final head under `NODE_OPTIONS=--max-old-space-size=8192`, exit codes captured before any pipe; `--ran`: "21 derived famil(ies) accounted for — 21 run, 0 NOT-MEASURED". ```text node scripts/check-adr-links.mjs :: exit 0 node scripts/check-adr-links.mjs --self-test :: exit 0 node scripts/check-closing-keyword-parity.mjs :: exit 0 node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0 node scripts/check-comment-mask-corpus.mjs :: exit 0 node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0 pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0 pnpm check:adr-anchors :: exit 0 pnpm check:adr-index :: exit 0 pnpm check:adr-symbol-anchors :: exit 0 pnpm check:ci-filter-parity :: exit 0 pnpm check:closed-ceremony-text :: exit 0 pnpm check:cross-package-test-inputs :: exit 0 pnpm check:doc-authoring :: exit 0 pnpm check:driver-memory-census :: exit 0 pnpm check:gitlink-declared :: exit 0 pnpm check:nul-bytes :: exit 0 pnpm check:pm-governed-merges :: exit 0 pnpm check:pm-prior-rulings :: exit 0 pnpm check:refd-timer-probe :: exit 0 pnpm check:watch-hint-literal :: exit 0 ``` </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- _Generated by [Claude Code](https://claude.ai/code/session_017ihL2ewD2rAszkPvzKBT8T)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 007fdb1 commit 0f254f4

2 files changed

Lines changed: 64 additions & 2 deletions

File tree

‎docs/adr/0048-cross-package-metadata-collision.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-0048: Cross-package metadata collision — package-id identity, namespace install gate, package-scoped resolution
22

3-
**Status**: Revised (2026-06-13) — supersedes the original *per-item collision detection* framing. The runtime guard shipped under the original proposal is **retained as a same-package authoring backstop**; the strategic direction for the app-marketplace era is revised below. · **Superseded in part by [ADR-0146](./0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md)** (2026-10-31) — §3.3's sentence that a context-free read "is best-effort: it returns the first match": a read of a name a code package ships has an owner — that package, or the declared override its paired `<base>.custom` publishes — and a same-named item of a package outside that closure is served only under its own address (ADR-0146 D8); and §3.4's coexistence "by construction", for a base's dependency closure only: the paired `<base>.custom`'s item bearing a base item's name is a declared override or is refused at publish — declare or rename — and any other dependent package's item bearing a base item's name is refused at publish — rename; only the pair declares (ADR-0146 D2, ruled 2026-10-31 on #28364 and #28390). Packages with no dependency relation keep §3.3 and §3.4 as written; qualify-to-cross, the same-package overwrite and the 2026-10-08 addendum stand.
3+
**Status**: Revised (2026-06-13) — supersedes the original *per-item collision detection* framing. The runtime guard shipped under the original proposal is **retained as a same-package authoring backstop**; the strategic direction for the app-marketplace era is revised below. · **Superseded in part by [ADR-0146](./0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md)** (2026-10-31) — §3.3's sentence that a context-free read "is best-effort: it returns the first match": a read of a name a code package ships has an owner — that package, or the declared override its paired `<base>.custom` publishes — and a same-named item of a package outside that closure is served only under its own address (ADR-0146 D8); and §3.4's coexistence "by construction", for a base's dependency closure only: the paired `<base>.custom`'s item bearing a base item's name is a declared override or is refused at publish — declare or rename — and any other dependent package's item bearing a base item's name is refused at publish — rename; only the pair declares (ADR-0146 D2, ruled 2026-10-31 on #28364 and #28390). Packages with no dependency relation keep §3.3 and §3.4 as written; qualify-to-cross, the same-package overwrite and the 2026-10-08 addendum stand. · **Amended** (2026-11-07, [#30794](https://github.com/objectstack-ai/objectstack/issues/30794)): §3.5 — rename-on-install ships for **unmanaged** copies, through the one rename engine `duplicatePackage` applies; a managed install is never renamed and §3.2 stands for it as written. See the dated note under §3.5.
44
**Deciders**: ObjectStack Protocol Architects
55
**Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md) (package as first-class citizen), [ADR-0005](./0005-metadata-customization-overlay.md) (artifact vs runtime overlay precedence), [ADR-0008](./0008-metadata-repository-and-change-log.md) (metadata repository, `MetaRef` identity), [ADR-0010](./0010-metadata-protection-model.md) (package provenance / `_packageId` stamping)
66
**Consumers**: `@objectstack/objectql` (`SchemaRegistry.registerItem`, `ObjectQL.registerApp`, install path), `@objectstack/console` / `objectui` (routing + metadata resolution), package authors, CLI/CI install path, the app marketplace registry.
@@ -293,6 +293,45 @@ formula / view / flow that names `crm_account`. That is a deep rewrite, not a
293293
URL change. v1 is **refuse-on-conflict** (§3.2). Rename-on-install is recorded
294294
as future work, not part of this decision.
295295

296+
> **Amended (2026-11-07, #30794) — rename-on-install ships for unmanaged copies, and only for them.**
297+
> An unmanaged install ([ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) D6)
298+
> may name a `targetNamespace`. The copy's new base takes it as its `namespace`. Every copied object
299+
> name takes it in place of the package's, and a name that lacks the package's prefix takes it in front.
300+
> Every reference the engine reads follows (the first bullet below says where). That is the deep rewrite this section describes, done by
301+
> the one engine `duplicatePackage` already applies (ADR-0070 D4): `planNamespaceRename`,
302+
> `packages/metadata-protocol/src/package-namespace-rename.ts`. Both doors call it, so the two renames
303+
> cannot drift. The doors share the rename and nothing more: only the duplicate rebinds a permission
304+
> set's `packageId` (ADR-0086 D3), which the import never does, and only the import judges the copy
305+
> names against the item-name grammar and the identifier limits below.
306+
>
307+
> - **The rename runs after view containers are expanded.** A view item follows its object, and so
308+
> does a view container (a view named exactly like an object) and every view it expands into; this
309+
> holds on both doors, so a bare object's container now follows it under the duplicate too.
310+
> Translations are named `<targetNamespace>_<locale>`, with the object keys inside them renamed. A
311+
> field keeps its key. Free text is renamed only at a whole prefixed object name.
312+
> - **Every refusal the names can answer comes before the base exists**: a copy name another object's
313+
> copy takes, a copy name the item-name grammar refuses, a copy name longer than an object's table
314+
> identifier (63) or an item name (255) may be, and a renamed key that meets a key the item already
315+
> holds. `targetNamespace` is judged by `manifest.namespace`'s own declaration, and the shared
316+
> namespaces `base`, `system` and `sys` are refused; both refusals answer `400 INVALID_REQUEST`,
317+
> naming `targetNamespace`.
318+
> - **§3.2's refuse-on-conflict runs on the renamed names.** A `targetNamespace` another package owns
319+
> is refused, and so is a renamed name the environment or a managed package holds.
320+
> - ⛔ **A managed install is never renamed.** It keeps the package's namespace and its upgrade
321+
> channel, and `targetNamespace` beside it is refused (`400 INVALID_REQUEST`) before anything is
322+
> fetched. For a managed install, §3.2 stands exactly as written.
323+
> - **Provenance** is the import answer's `sourceNamespace` and the install-local answer's
324+
> `installedFrom.namespace`. Both are information only, as ADR-0131 D6 records provenance.
325+
> - **The request carries it, the CLI does not.** `targetNamespace` is a key of the import's request
326+
> (`importUnmanagedPackage`) and of the `POST /api/v1/marketplace/install-local` body;
327+
> `os package install` sends none.
328+
>
329+
> Not in this amendment: renaming bare non-object names (ruling C on #30798 makes every
330+
> package-authored top-level name carry the namespace, see the
331+
> [2026-11-06 addendum](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed)),
332+
> seed data (the import copies none), and the hosted-cloud default namespace
333+
> (objectstack-ai/cloud#3624).
334+
296335
### 3.6 The package-id URL is transparent; a friendly alias is optional
297336

298337
A reverse-domain URL — `/apps/com.acme.crm/page/home` — is **self-describing**:

‎docs/adr/0131-total-organization-ownership-no-null-organization-id.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-0131: Organization ownership is total — no NULL `organization_id`; declared metadata stays in code; a row exists only when an organization authored it
22

3-
**Status**: Accepted (2026-09-04) — accepted by the merge that landed it on `main` ([#14976](https://github.com/objectstack-ai/objectstack/pull/14976), commit `0ed271574`), which is itself the acceptance act for a governed surface (Prime Directive #14). Execution is paused under #15193 and the maintainer's standing instruction; that pause is carried there, not by this status line. · **Amended** (2026-09-17, [#18413](https://github.com/objectstack-ai/objectstack/issues/18413) — maintainer ruling option **B** on [#18336](https://github.com/objectstack-ai/objectstack/issues/18336), 2026-09-16: **D5's assignment of `reportLegacyPlatformAdminGrant` and `resetLegacyPlatformAdminGrantReport` to D13 is withdrawn**. Those two symbols retire on the **17.x** line under [#11663](https://github.com/objectstack-ai/objectstack/issues/11663)'s design, **walled posture only**; the `single` posture keeps its zero-config first-user promotion and its grant row. **D5's Default-Organization ownership of that row is unchanged** and still lands on the v18 line under C3 — nothing about NULL ownership moves here. D14 gains one named exception. See **"Amendment (2026-09-17, #18413): the legacy-anchor retirement leaves D13 for the walled posture"** at the end.) · **Amended** (2026-10-16 — maintainer ruling on the v18 upgrade of long-lived development databases: **`os dev` runs D10's ceremony itself on a local SQLite development database**, after copying it, and boots again; `os serve` / `os start` and every other database keep the manual ceremony and the boot refusal, and **what the ceremony decides on the operator's behalf is printed as a warning before its first write**. The ceremony plans and applies **each object in the database the deployment keeps it in** (the `telemetry` sibling included), and **adopts the shipped permission sets an install seeded as `admin` rows** as the platform seeds they are. See **"Amendment (2026-10-16): the development exception, the telemetry sibling, and the legacy shipped-set seeds"** at the end.) · **Amended** (2026-10-22, #24897 — maintainer ruling letter **A** on [#25134](https://github.com/objectstack-ai/objectstack/issues/25134), record `6328195425`, 「25134 … 同意」: **D1's text states where the tenant column is NOT NULL and which nullable columns remain**, adopting the card's wording; the decision that NULL is not a state is unchanged. Dated notes beside D1, D2, D5, D7, D8, D9 and D14 record the 18.x line as shipped: the release scope of 18.0.0, the lean-embedding exception and its boundaries under ruling A on [#25133](https://github.com/objectstack-ai/objectstack/issues/25133), and the step 7 parts each describes.) · **Superseded in part by [ADR-0146](./0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md)** (2026-10-31) — D6's sentence that what the customer changes "lives **beside** the managed item, as environment-level state": it lives in the paired `<base>.custom` package, exported and deployed as a package (ADR-0146 D2, D3); "no door edits a managed definition", environment scope and the retired per-organization axis stand.
3+
**Status**: Accepted (2026-09-04) — accepted by the merge that landed it on `main` ([#14976](https://github.com/objectstack-ai/objectstack/pull/14976), commit `0ed271574`), which is itself the acceptance act for a governed surface (Prime Directive #14). Execution is paused under #15193 and the maintainer's standing instruction; that pause is carried there, not by this status line. · **Amended** (2026-09-17, [#18413](https://github.com/objectstack-ai/objectstack/issues/18413) — maintainer ruling option **B** on [#18336](https://github.com/objectstack-ai/objectstack/issues/18336), 2026-09-16: **D5's assignment of `reportLegacyPlatformAdminGrant` and `resetLegacyPlatformAdminGrantReport` to D13 is withdrawn**. Those two symbols retire on the **17.x** line under [#11663](https://github.com/objectstack-ai/objectstack/issues/11663)'s design, **walled posture only**; the `single` posture keeps its zero-config first-user promotion and its grant row. **D5's Default-Organization ownership of that row is unchanged** and still lands on the v18 line under C3 — nothing about NULL ownership moves here. D14 gains one named exception. See **"Amendment (2026-09-17, #18413): the legacy-anchor retirement leaves D13 for the walled posture"** at the end.) · **Amended** (2026-10-16 — maintainer ruling on the v18 upgrade of long-lived development databases: **`os dev` runs D10's ceremony itself on a local SQLite development database**, after copying it, and boots again; `os serve` / `os start` and every other database keep the manual ceremony and the boot refusal, and **what the ceremony decides on the operator's behalf is printed as a warning before its first write**. The ceremony plans and applies **each object in the database the deployment keeps it in** (the `telemetry` sibling included), and **adopts the shipped permission sets an install seeded as `admin` rows** as the platform seeds they are. See **"Amendment (2026-10-16): the development exception, the telemetry sibling, and the legacy shipped-set seeds"** at the end.) · **Amended** (2026-10-22, #24897 — maintainer ruling letter **A** on [#25134](https://github.com/objectstack-ai/objectstack/issues/25134), record `6328195425`, 「25134 … 同意」: **D1's text states where the tenant column is NOT NULL and which nullable columns remain**, adopting the card's wording; the decision that NULL is not a state is unchanged. Dated notes beside D1, D2, D5, D7, D8, D9 and D14 record the 18.x line as shipped: the release scope of 18.0.0, the lean-embedding exception and its boundaries under ruling A on [#25133](https://github.com/objectstack-ai/objectstack/issues/25133), and the step 7 parts each describes.) · **Superseded in part by [ADR-0146](./0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md)** (2026-10-31) — D6's sentence that what the customer changes "lives **beside** the managed item, as environment-level state": it lives in the paired `<base>.custom` package, exported and deployed as a package (ADR-0146 D2, D3); "no door edits a managed definition", environment scope and the retired per-organization axis stand. · **Amended** (2026-11-07, [#30794](https://github.com/objectstack-ai/objectstack/issues/30794)): D6's **Unmanaged** copy may take a namespace of its own (`targetNamespace`, renamed by the duplicate's engine; [ADR-0048](./0048-cross-package-metadata-collision.md) §3.5 as amended), extending Q3 on #15213; Q6 does not apply to a renamed copy (maintainer ruling **B**, record `6709037798`) and stands as written for a copy that kept the source namespace. See the dated note after D6's **Unmanaged** bullet.
44
**Deciders**: ObjectStack maintainer, 2026-09-03/04, live chat on
55
[#13564](https://github.com/objectstack-ai/objectstack/issues/13564), verbatim and untranslated,
66
in the order the model was built: the premise 「我理解只有代码定义的元数据是跨租户的,对象、字段、视图等
@@ -523,6 +523,29 @@ spelling moves: the copy-once import, full editability, no upgrade channel and t
523523
naming the posture: a template import would hand every tenant an editable shared schema. Under `single`
524524
it is how a customer takes an app and makes it theirs wholesale — Salesforce's unmanaged package.
525525

526+
> **Note (2026-11-07, #30794) — the copy may take a namespace of its own (Q3 on #15213, extended).**
527+
> Q3 (a seat answer in the #15213 stage-0 ACCEPT, record `6108175106`; not this record's §6 Q3) put the copied rows in a NEW writable base that keeps the
528+
> source namespace. The base is still new, and the copy still never lands in an existing base: Q3's
529+
> reason, an existing base's namespace broken on export, is untouched. The namespace is now kept
530+
> *unless* the install names a `targetNamespace`
531+
> ([ADR-0048](./0048-cross-package-metadata-collision.md) §3.5 as amended). In that case every copied
532+
> name is renamed into it, by the rename `duplicatePackage` applies. A managed install is never renamed.
533+
> The provenance recorded for information only gains the source namespace beside the package id and
534+
> version.
535+
>
536+
> Q6 (the same record's, not this record's §6 Q6: a later managed install of the same package is refused at the door, before any
537+
> write, on both install branches, naming the copy base) **does not apply to a renamed copy**, by the
538+
> maintainer's ruling **B** of 2026-11-07 (record `6709037798` on #30794, 「B 不拒绝(推荐)」): a renamed
539+
> copy does not hold the source namespace, so a later managed install of the same source package is not
540+
> refused. Q6 guards against shadowing by name: a managed registration over a writable base of the same
541+
> namespace would stop serving the customer's edited copy at the next boot. A renamed copy holds no
542+
> namespace of the package's, and its object names and every name that carried the package's prefix
543+
> are its own, so the namespace guard has nothing to shadow; a name the two still share is judged at
544+
> the managed install by ADR-0048 §3.2 and its addenda, as between any two packages. The two stand side
545+
> by side, each with its own data, and the customer decides when to retire the copy. For a copy that
546+
> kept the source namespace, Q6 stands exactly as written: a `targetNamespace` equal to the source
547+
> namespace renames nothing, and the copy holds the source namespace as before.
548+
526549
> **Note (2026-10-19, ruling of record `6258883445` on #24378, letter A, which supersedes ruling
527550
> `6257388265`, letter B′) — `sharing_rule` is charted under regime C.** A managed declared sharing rule
528551
> is read-only and clonable. **Switching it off** is the `active` bit of a `sys_metadata_activation` row

0 commit comments

Comments
 (0)