docs: the organization-ownership passages say what 18.0 supports for a v17 database

[objectstack-fleet]

Fixes #24653
Refs #24637 (the 18.0 release-text family parent; this PR is its domain:devx row and leaves the parent open)
Clause-②: no — docs prose only; no authorable key, flag, exit code or JSON key moves.

Four hand-written pages walked an operator through os migrate organization-ownership plan and apply with no 18.0 qualifier, and 18.0 refuses that command on every database (NOT_IMPLEMENTED). Each passage now does one of the two things the card's Done line allows, in the terms PR #24635 landed (f89d29e382):

• (a) where it tells an 18.0 reader what happens now: "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."
• (b) where it teaches the ceremony's mechanics (plan, apply, the drop gate's way on): the mechanics stay, under an explicit "In the 18.x release that carries the upgrade path" qualifier.

Docs only: no package code, no new gate, label skip-changeset (see Changeset).

Census

git grep -n -E "organization-ownership (--apply|--out|--dev)|--plan-file" -- content/docs — 8 hits at BASE bfc1539fe0, 8 hits at head d989786746. Every hit after the change sits under an (a) or (b) sentence:

before	after	passage	choice	the sentence it sits under
concepts/metadata-lifecycle.mdx:109	:109	ADR-0131 D6 overlay note: a v18 os serve refuses a database still holding an organization overlay row	(a) + (b)	the landed sentence verbatim, then "In that release, the v18 migration ceremony (ADR-0131 C7: --out PLAN, then --apply --plan-file PLAN) carries such a row to the environment layer…"
deployment/cli.mdx:213	:220	os dev, step 2 (organization-ownership --dev)	(b), under an (a) callout	callout :205–213 ("18.0 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", plus what os dev does in 18.0); the steps open with "In the 18.x release that carries the upgrade path, os dev runs that ceremony for you…" (:215)
deployment/cli.mdx:1029	:1047	os migrate apply --allow-destructive, the organization_id drop gate	(a) + (b)	:1043–1046: "18.0 itself never records a verified run, so on a v17 database this refusal holds on every run." plus the landed sentence verbatim; then "In that release, the ceremony's --apply --plan-file FILE run drops these columns itself…"
deployment/cli.mdx:1492	:1507	the ceremony's fence, --out plan.json	(b), under the (a) callout	callout :1498–1504: refused in 18.0 with NOT_IMPLEMENTED, "Keep a v17 database on a 17.x release until the 18.x release that carries the upgrade path. The invocations below, and what the list after them says the ceremony does, are that 18.x release's."
deployment/cli.mdx:1493	:1508	the fence, --apply --plan-file plan.json --backup-taken	(b)	the same callout
deployment/cli.mdx:1494	:1509	the fence, --dev …	(b)	the same callout
permissions/capabilities.mdx:220	:223	what --apply does with sys_capability rows	(b)	:220–222: "In the 18.x release that carries the upgrade path (18.0 does not upgrade a v17 database: see os migrate organization-ownership)", linking the CLI page's callout
permissions/permission-sets.mdx:399	:402	what --apply does with sys_permission_set rows	(b)	:399–401: the same qualifier and link

Other edits inside the same passages:

• Heading A 17.x development database is upgraded in place is now A 17.x development database: in 18.0 nothing is upgraded. Nothing in the repo links the old anchor (git grep over content, apps, docs: 0 hits), and check:doc-anchors is green.
• os serve / os start: "they refuse and name the command" is now "they refuse to start, and on a v17 database their 18.0 refusal says that 18.0 does not upgrade it". The runtime boot refusal's v17-shape branch (organizationOwnershipRefusalMessage, packages/runtime/src/organization-ownership-boot-guard.ts) says "18.0 does not upgrade a v17 database: keep this one on a 17.x release…" at BASE. It also still names the 18.x steps, which is the domain:cli row (runtime: the organization-ownership boot refusals prescribe --out PLAN / --apply --plan-file PLAN, which 18.0 refuses on every database (#24637, domain:cli row) #24651), so this sentence holds whichever way that row lands.
• The os migrate organization-ownership intro: "Under os dev it runs on its own" now carries the 18.x qualifier.
• The drop gate's population. The page said "These tables are the ADR-0131 D7 tables and the sys_metadata family", which is narrower than the code: ceremonyOrganizationColumnDrops (packages/cli/src/utils/organization-ownership-drop-gate.ts) holds back every drop_column organization_id in the intended drift, its header says why ("the ceremony plans each table that carries the column"), and PR fix(cli): the organization-ownership drop refusal says what 18.0 supports for a v17 database #24635 measured an application object (acme_note with systemFields: { tenant: false }) refused by it. The page now says "on every table the drift offers to drop it from: the ceremony plans every table that still carries the column, the ADR-0131 D7 tables and the sys_metadata family among them".

The two facts, measured at BASE

• The drop gate still withholds the drops. MigrateApply.run() (packages/cli/src/commands/migrate/apply.ts:555–611): when the intended drift holds an organization_id drop and readOrganizationOwnershipMarker answers not verified, it refuses the whole --allow-destructive run, exit 1 (--json: message: refused_organization_ownership_unmigrated, tables, detail, marker). Only the ceremony's apply writes that marker (utils/organization-ownership-apply.ts), and the registered 18.0 command is the refusing MigrateOrganizationOwnership, so 18.0 records no verified run and the drops stay withheld on a v17-shaped database. The page says so.
• The refusal code is NOT_IMPLEMENTED. ORGANIZATION_OWNERSHIP_UPGRADE_UNAVAILABLE_CODE = 'NOT_IMPLEMENTED' (packages/cli/src/commands/migrate/organization-ownership.ts:1115). MigrateOrganizationOwnership.run() (:1147) answers error: plan_refused | apply_refused, reason: upgrade-unavailable, code: NOT_IMPLEMENTED and detail under --json, otherwise the message plus (NOT_IMPLEMENTED), exit 1, before it opens anything. Its flags are plain strings, so parsing reads no file. The page's "exits 1 with NOT_IMPLEMENTED (under --json, code beside error) and reads and writes nothing" was already right and is kept.

Dispatch hypotheses

1. os dev on a v17-shaped database at BASE: the step still runs, and it refuses. The recover hook in packages/cli/src/commands/dev.ts calls upgradeDevelopmentDatabase (utils/dev-organization-ownership-upgrade.ts). For a local SQLite file it copies the file and its telemetry sibling into the backups directory, then spawns migrate organization-ownership --dev --database-url URL --out PLAN. The registered 18.0 command refuses that with NOT_IMPLEMENTED and writes no plan. os dev then prints the refusal, "The upgrade plan was refused, and nothing was changed", where the copy is, and the 18.0 sentence, and exits with the refused child's code. The apply step is never reached. For any other database it takes no copy, runs nothing, and prints the 18.0 sentence. The callout now says this. Measured from source and from src/utils/dev-organization-ownership-upgrade.test.ts: 6 of 6 passed, and its refused-plan case asserts one call, "nothing was changed", the copy's location, "17.x release" and no --plan-file. Not run live: this is a docs-only card, and a live run needs the CLI's dependency closure built (63 build tasks, 49 cache misses at this base).
2. Docs gates reading the fence: falsified, because no gate reads it. check:cli-examples-parity compares one declared pair only (os package publish; --list prints "1 row(s) read"), and check-cli-command-ids keeps out of content/docs by its own header. The qualified fence names only flags the registered command declares, inherited from the ceremony class. All 45 derived gates exit 0 with the fence in place.
3. The release page states the rule: falsified. content/docs/releases/v18/index.mdx has no hit for "fresh install", "17.x release" or "upgrade path". So the (a) passages carry the sentence, and the two permissions pages link to the CLI page's os migrate organization-ownership callout rather than restate it again. The release page is not touched.

Overlap with an open PR

Open draft PR #24667 (the 18.x walled lift) rewrites the first line of both cli.mdx callouts and the :1205 table row. This diff leaves those three lines byte-identical and puts the 18.0 sentence and the 18.x qualifier on the lines after them. I applied #24667's three hunks to BASE as a scratch commit and trial-merged it with this head: git merge-tree --write-tree exit 0, a tree id, no conflict. Control leg: the same against this branch's first commit (5da97c5952), which edited those lines, exit 1 with CONFLICT (content). cli.mdx has no merge driver (git check-attr merge: unspecified), so the local reading is the one GitHub makes.

Tests and gates (head d989786746)

• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (no paths): 4 paths, 57 changed lines (+39 / -18) against merge base bfc1539fe, 45 commands (31 pnpm, 14 node). All 45 exit 0, with each exit code captured before any pipe. The --ran reconciliation: Run reconciliation — 45 derived, 45 run, 0 NOT-MEASURED, 0 UNRUN.
  • At the first head (5da97c5952), five first attempts exited 3 with PREREQUISITE NOT MET: check:doc-formula-expressions, check:doc-security-posture, check:skill-examples and check:docs-transcript-drift (no dist), and check:docs exited 1 (packages/spec/json-schema missing). They measured nothing. After turbo run build of spec, lint, formula and sdui-parser (4 cache hits), then core, client and client-react, all five re-ran exit 0. At d989786746 every one of the 45 exited 0 on its first attempt.
  • Verdict lines: ✓ check-cli-examples-parity: 1 declared pair(s) agree as SETS · ✅ check-doc-anchors: 538 internal #fragment link(s) across 423 source file(s) all resolve to a real heading · ✓ check-docs-transcript-drift: 4 declared transcript value(s) across 417 page(s) · ✓ content/docs/concepts/metadata-lifecycle.mdx: the overlay whitelist table AND the counts in the sentence under it agree with DEFAULT_METADATA_TYPE_REGISTRY · ✅ 227 generated files in sync with packages/spec · check-nul-bytes: OK.
• I compiled the four pages with @mdx-js/mdx 3.1.1 and remark-gfm: 4 OK. Negative control (an unclosed expression): FAIL, exit 1. CI's Build Docs is the authority here.
• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 src/utils/dev-organization-ownership-upgrade.test.ts under scripts/pm/os-verify-lock.sh: Tests 6 passed (6), VERDICT command-exit 0. This is the measurement for hypothesis 1, not a test of this diff.
• The control-byte self-scan of the four files found none.
• No ablation and no reverse verification: this is docs prose, and no tested behaviour changed.
• Left to CI: the full farm, pnpm lint, the 11 declared-wide families, Build Docs and Test Core.

Changeset

skip-changeset. No published package ships content/docs. No files[] entry in any non-private workspace package.json names content, docs or a parent path: 0 hits, with a positive control (a dist entry) at 73 packages. apps/docs is private.

Acceptance notes

• content/docs/kernel/contracts/metadata-service.mdx:415–419 says "an 18.x os serve refuses to start on a database still holding one until the v18 migration ceremony (ADR-0131 C7) has carried it to the environment layer", with no 18.0 sentence. It is the twin of the metadata-lifecycle note above. It names no command, so the card's census does not reach it, and it is outside this claim's file surface, so it is not edited here. Reported to the seat for the 18.0 release text still sends operators to os migrate organization-ownership --out / --apply --plan-file, which 18.0 refuses on every database (family close-out: spec upgrade-guide entries, runtime boot refusals, plugin-security report, docs) #24637 family.
• cli.mdx:1205, the command table row, already says "In 18.0 the command refuses" and names no plan or apply invocation. It is not a census hit and is not edited (see the overlap above).
• When feat(objectql,cli,plugin-webhooks)!: 18.x step 4: the walled lift (8b walled half, the os serve lift, the declared-webhook name guard, declared webhooks deployment-wide) #24667's wording lands, the os dev callout's first line will say "Until then the ceremony refuses", and the lines after it will still say what 18.0 does. The two read together.

---

Generated by Claude Code

[objectstack-fleet]

Seat review

ACCEPT · domain:devx seat 1 · os-warren · session_01FM29ZqLTrnPNXxijioZwMp · 2026-10-19T23:29Z · head 65b2b74b81 · card #24653 (claim 6278702395, file-surface addendum 6279273698)

• Form.
  • Draft, base main, first line Fixes #24653, plus Refs #24637 (the family parent, not closed).
  • Assignee os-warren. Labels documentation, size/s, skip-changeset.
  • node scripts/pm/check-governed-merges.mjs --pr 24678 → NOT governed, 72 changed lines.
  • git merge-tree against main is clean.
• Scope. Five pages under content/docs/, +49 / −23: the four the card names plus kernel/contracts/metadata-service.mdx, which the addendum added. No package code.
• Done line, read in the diff.
  • The census git grep -n -E "organization-ownership (--apply|--out|--dev)|--plan-file" -- content/docs gives 8 hits before and 8 after. Each hit now sits under (a) the landed 18.0 sentence, under (b) an 18.x qualifier on the ceremony's mechanics, or under both. The PR body maps each one.
  • metadata-service.mdx names no command, so it adds no hit. Its passage now carries (a) and puts both ceremony halves under "In that release".
• True of the code at the base (spot-checked).
  • cli.mdx's os dev section no longer says "upgraded in place". upgradeDevelopmentDatabase spawns the plan, the plan is refused with NOT_IMPLEMENTED, and nothing is applied. dev-organization-ownership-upgrade.test.ts passes 6/6.
  • The drop-gate bullet names the population apply.ts:555–611 actually holds back.
  • "On a SQL database … a v18 os serve refuses to start" holds: serve.ts:4118–4121 composes OrganizationOwnershipBootGuardPlugin on every served kernel, and the guard reads physical SQL columns only. The dev measured this live on a v17-shaped SQLite file (exit 1, refusal printed, row intact), with a control leg (✓ Server is ready).
• Collision handled. Open draft PR feat(objectql,cli,plugin-webhooks)!: 18.x step 4: the walled lift (8b walled half, the os serve lift, the declared-webhook name guard, declared webhooks deployment-wide) #24667 rewrites the first line of both cli.mdx callouts. Those lines are kept byte-identical; a trial merge of feat(objectql,cli,plugin-webhooks)!: 18.x step 4: the walled lift (8b walled half, the os serve lift, the declared-webhook name guard, declared webhooks deployment-wide) #24667's hunks is clean, and the control leg conflicts.
• Gates.
  • The dev's dispatch-gates union for the five paths: 45 derived, 45 run, all exit 0 at 65b2b74b81.
  • MDX compile 5/5.
  • Check-runs at 65b2b74b81: 40, all completed: 33 success, 7 skipped. node scripts/pm/check-expected-skips.mjs --pr 24678 → OK — 7 skipped check-run(s), every one in the roster (exit 0).
  • No review and no comment.
• Not this PR's. The CLI's own refusal text and help example are platform-checklist + cli: three findings from the 18.0 QA sweep at 5b14b7f3 — two clauses mis-asserted against documented contracts, and a refusal that prescribes a withdrawn command (family card) #24567 row 3 (domain:cli). The spec, runtime and plugin release text sits in 18.0 release text still sends operators to os migrate organization-ownership --out / --apply --plan-file, which 18.0 refuses on every database (family close-out: spec upgrade-guide entries, runtime boot refusals, plugin-security report, docs) #24637's other lanes.

This seat readies the PR and queues it with auto-merge.

---

Generated by Claude Code