Skip to content

Commit 65b2b74

Browse files
committed
docs(metadata-service): the overlay note says what 18.0 supports for a v17 database
The Environment Customization note said an 18.x os serve refuses a database still holding an organization-layer overlay row "until the v18 migration ceremony has carried it", with no 18.0 qualifier, and 18.0 has no ceremony. It now carries the 18.0 sentence and puts both ceremony halves (the overlay row and the public-form withdrawals) under the 18.x qualifier, as its twin in metadata-lifecycle does. The refusal is stated as the boot guard measures it: on a SQL database, where the sys_metadata family still carries its organization_id column. The guard reads physical columns and is inert on memory and MongoDB, so the twin note in metadata-lifecycle gains the same condition. Claude-Session: https://claude.ai/code/session_01FM29ZqLTrnPNXxijioZwMp Co-authored-by: Claude <noreply@anthropic.com>
1 parent d989786 commit 65b2b74

2 files changed

Lines changed: 11 additions & 6 deletions

File tree

‎content/docs/concepts/metadata-lifecycle.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ later ships. See [ADR-0070](https://github.com/objectstack-ai/objectstack/blob/m
106106

107107
**Most metadata types must not be overlaid by an environment** — overlaying a packaged item would break the physical schema or the behaviour its package ships. The whitelist lives in **one** place: `MetadataTypeRegistryEntry.allowEnvironmentOverlay` in `packages/spec/src/kernel/metadata-plugin.zod.ts` (spelled `allowOrgOverride` before protocol 18; `GET /api/v1/meta/types` serves it per entry as `allowEnvironmentOverlay`).
108108

109-
> **ADR-0131 D6 — the per-organization overlay axis is retired.** The `/meta` doors (REST and the runtime dispatcher) carry no organization into a metadata write or read: a Studio or `PUT /api/v1/meta/...` write of the five ✅ types below lands **environment-wide** (since ADR-0131 D7 the `sys_metadata` family declares no organization column) and is served to every organization, and an organization admin holding only the retired `manage_org_presentation` capability is refused (`403`). The protocol itself refuses every organization-scoped write, and every read — item, list, layers, cached, history, diff, audit, drafts and the commit timeline — is environment → code, whatever organization a caller names. An overlay row an earlier release stored under an organization — under the `single` posture, every Studio save of these types, filed under the Default Organization — is served by no read, and a v18 `os serve` refuses to start on a database still holding one. 18.0 supports fresh installs only and does not upgrade a v17 database: keep a v17 database on a 17.x release until the 18.x release that carries the upgrade path. In that release, the v18 migration ceremony (ADR-0131 C7: `os migrate organization-ownership --out PLAN`, then `--apply --plan-file PLAN`) carries such a row to the environment layer and drops the column; nothing deletes or rewrites it before then. The anonymous form doors read the environment alone too: in that release the ceremony carries every organization-layer public-form withdrawal onto the environment, fail-closed. The table still records which types take an overlay of a shipped item.
109+
> **ADR-0131 D6 — the per-organization overlay axis is retired.** The `/meta` doors (REST and the runtime dispatcher) carry no organization into a metadata write or read: a Studio or `PUT /api/v1/meta/...` write of the five ✅ types below lands **environment-wide** (since ADR-0131 D7 the `sys_metadata` family declares no organization column) and is served to every organization, and an organization admin holding only the retired `manage_org_presentation` capability is refused (`403`). The protocol itself refuses every organization-scoped write, and every read — item, list, layers, cached, history, diff, audit, drafts and the commit timeline — is environment → code, whatever organization a caller names. An overlay row an earlier release stored under an organization — under the `single` posture, every Studio save of these types, filed under the Default Organization — is served by no read, and on a SQL database (SQLite, PostgreSQL, MySQL) still holding one a v18 `os serve` refuses to start. 18.0 supports fresh installs only and does not upgrade a v17 database: keep a v17 database on a 17.x release until the 18.x release that carries the upgrade path. In that release, the v18 migration ceremony (ADR-0131 C7: `os migrate organization-ownership --out PLAN`, then `--apply --plan-file PLAN`) carries such a row to the environment layer and drops the column; nothing deletes or rewrites it before then. The anonymous form doors read the environment alone too: in that release the ceremony carries every organization-layer public-form withdrawal onto the environment, fail-closed. The table still records which types take an overlay of a shipped item.
110110

111111
| Type | `allowEnvironmentOverlay` | Rationale |
112112
| :--- | :---: | :--- |

‎content/docs/kernel/contracts/metadata-service.mdx‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -412,11 +412,16 @@ overlay axis is retired: the doors carry no organization, so the overlay is
412412
column, ADR-0131 D7) and served to every organization
413413
of the deployment, whatever the author's active organization. Every protocol
414414
read is environment → code, whatever organization a caller names. An overlay
415-
row an earlier release stored under an organization is served by no read, and
416-
an 18.x `os serve` refuses to start on a database still holding one until the
417-
v18 migration ceremony (ADR-0131 C7) has carried it to the environment layer. The anonymous form doors read the environment alone too: the ceremony carries
418-
every organization-layer public-form withdrawal onto the environment,
419-
fail-closed. The per-user,
415+
row an earlier release stored under an organization is served by no read. On a
416+
SQL database (SQLite, PostgreSQL, MySQL) still holding one, a v18 `os serve`
417+
refuses to start, because the `sys_metadata` family there still carries its
418+
`organization_id` column. 18.0 supports fresh installs only and does not
419+
upgrade a v17 database: keep a v17 database on a 17.x release until the 18.x
420+
release that carries the upgrade path. In that release, the v18 migration
421+
ceremony (ADR-0131 C7) carries such a row to the environment layer. The
422+
anonymous form doors read the environment alone too; in that release the
423+
ceremony carries every organization-layer public-form withdrawal onto the
424+
environment, fail-closed. The per-user,
420425
per-field patch overlay a previous revision of this page taught here was
421426
removed in #13135 — it was never served by any route.
422427

0 commit comments

Comments
 (0)