fix(spec): 18.0 upgrade-guide entries say 18.0 supports fresh installs only (#24661)

Refs #24637

Clause-②: no

The `domain:spec` row of #24637. The parent closes once this PR and its
three children land (#24651, #24652, #24653 are not addressed here), so
this PR does not close it.

## What changes

In 18.0, `os migrate organization-ownership` refuses plan and apply on
every database (exit 1, `NOT_IMPLEMENTED`, nothing read or written), and
18.0 supports fresh installs only. Seven ADR-0087 semantic entries under
`packages/spec/src/migrations/entries/semantic/` compile into the 18.0
upgrade guide, and they still prescribed `--out PLAN` then `--apply
--plan-file PLAN` as if 18.0 upgraded a v17 database.

Each entry now says what 18.0 supports for a v17 database, in the words
PR #24635 (`f89d29e382`) landed in the CLI and the boot refusal:

> 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.

Each entry keeps the plan and apply steps, now introduced as "In that
18.x release, ...".

| entry | fields changed |
|:--|:--|
| `sys-metadata-organization-column-retired`, `-audit-`, `-commit-`,
`-history-` | `replacement` and `acceptanceCriteria` lead with the 18.0
sentence and qualify the ceremony as 18.x; in `reason`, "the v18
ceremony" becomes "the 18.x ceremony", and the boot-refusal clause says
it refuses in 18.0 on every such database |
| `ups-permission-set-id-column-retired` | `replacement` and
`acceptanceCriteria` the same way; `reason` names "the 18.x ceremony" |
| `sharing-rule-declared-mirror-retired` | `replacement` leads with the
18.0 sentence; `surface` and `acceptanceCriteria` name the ceremony as
18.x |
| `cli-organization-ownership-apply-plan-file-required` | see below |

### The `cli-organization-ownership-apply-plan-file-required` entry

The command itself is this entry's whole subject. I kept the entry and
rewrote the guidance rather than deleting it:

- The upgrade guide renders each entry as `` `surface` → replacement ``,
then "Why not automatic" (`reason`) and "Done when"
(`acceptanceCriteria`) (`packages/spec/scripts/build-upgrade-guide.ts`).
Nothing checks the prose against the CLI. The entry's id and step are
registered, and `.changeset/pre/15211-cli-apply-reviewed-plan.md` cites
it.
- The `surface` stays as it is: the bare `--apply --backup-taken`
invocation that `@objectstack/cli` 18.0.0-next.1 shipped. A script
written against that prerelease is still a real reader, and in 18.0 the
invocation is refused.
- The `replacement` now opens with "nothing in 18.0: 18.0 refuses this
invocation, as it refuses every plan and apply of `os migrate
organization-ownership` on every database". Then it gives the 18.0
sentence, then the plan-file rule, introduced as "In that 18.x release".
- `reason` adds one sentence on why 18.0 holds the ceremony back. The
ceremony is knowingly incomplete, and an incomplete ceremony must never
certify a v17 database that the boot would then serve. This paraphrases
the docblock on `ORGANIZATION_OWNERSHIP_UPGRADE_UNAVAILABLE`.
- `acceptanceCriteria` now opens with what holds on 18.0, then keeps the
18.x plan-file criteria.

Deleting the entry would drop the 18.x plan-file rule from the guide,
and it would leave a next.1 script with no entry that names its
invocation.

Only text changes. Every entry keeps its `id`, its step and its fields.

## Census

```
git grep -n -E "organization-ownership (--apply|--out|--dev)|--plan-file" -- packages/spec/src ':!*.test.ts'
```

At `a58972d67b`, every hit in the seven entries sits after the 18.0
sentence or under an "In that 18.x release" / "In the 18.x release that
carries the upgrade path" qualifier. The one hit not in an entry is the
code comment at `system/migration.zod.ts:174`, which is out of scope by
the card's rule. The cli entry's `surface` (line 10) names the refused
invocation and prescribes nothing.

In a rendered single-file guide (`tsx scripts/build-upgrade-guide.ts
--out`, written to a scratch path), the sentence "18.0 supports fresh
installs only" appears 12 times: 7 replacements and 5 acceptance
criteria. `sharing-rule-declared-mirror-retired`'s acceptance criteria
say "18.0 upgrades no v17 database" instead.

## Verification (head `a58972d67b`)

- `pnpm --filter @objectstack/spec build`: `VERDICT command-exit 0`.
- `pnpm --filter @objectstack/spec test`: `Test Files 702 passed (702)`,
`Tests 21349 passed | 1 todo (21350)`.
- `pnpm --filter @objectstack/spec typecheck`: exit 0.
check:test-typecheck reports OK.
- `pnpm --filter @objectstack/spec check:generated`: "All 14 generated
artifacts are up to date", with no tracked file changed. No baseline
pins this text.
- `node scripts/pm/dispatch-gates.mjs --commands` derived 83 commands,
and all of them were run:
- 80 exit 0, including `check:upgrade-guide`, `check:spec-changes`,
`check:adr-0087-registration --base origin/main`, `check:doc-authoring`,
`check:nul-bytes`, `check:empty-changeset` and
`check:changeset-no-major`.
- 3 exit 3, PREREQUISITE NOT MET, so NOT MEASURED here:
`check:doc-formula-expressions` (`@objectstack/formula` not built),
`check:dual-build-cjs-loads` (workspace `dist/` absent) and
`check:lean-entry-closure` (`@objectstack/objectql` not built). None
reads these entries. They are declared to CI.
- No open PR touches `packages/spec/src/migrations/entries/semantic/`. I
checked all 14 open PRs' file lists over REST.

## Acceptance notes

- Out of scope by the card's rule: `packages/spec/CHANGELOG.md` history,
and the code comment at `packages/spec/src/system/migration.zod.ts:174`.
- The boot guard, the plugin-security report and the docs rows are
#24651, #24652 and #24653.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01D6F9axfoPzR7t8G1J7Ytzz)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/24637-spec-upgrade-entries-fresh-install-only.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the 18.0 upgrade-guide entries that name `os migrate organization-ownership` say first that 18.0 supports fresh installs only
+
+Clause-②: no
+
+In 18.0, `os migrate organization-ownership` refuses plan and apply alike on every database (exit 1, `NOT_IMPLEMENTED`, nothing read or written). Seven ADR-0087 semantic entries still told an operator to run `--out PLAN`, then `--apply --plan-file PLAN`, as if 18.0 upgraded a v17 database. Each now says, in the same words as the CLI and the boot refusal: 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. The plan and apply steps stay, marked as the 18.x release's ceremony.
+
+- `sys-metadata-organization-column-retired`, `sys-metadata-audit-organization-column-retired`, `sys-metadata-commit-organization-column-retired`, `sys-metadata-history-organization-column-retired`, `ups-permission-set-id-column-retired`: the replacement and the acceptance criteria.
+- `sharing-rule-declared-mirror-retired`: the replacement and the acceptance criteria.
+- `cli-organization-ownership-apply-plan-file-required`: the replacement now says that 18.0 refuses this invocation, as it refuses every invocation of the command, and keeps the plan-file rule as the 18.x release's.
+
+Only the text changes. Every entry keeps its `id`, its surface and its step.

packages/spec/src/migrations/entries/semantic/18.cli-organization-ownership-apply-plan-file-required.ts

@@ -10,21 +10,29 @@ export const entry: SemanticMigration = {
     'os migrate organization-ownership --apply, invoked without --plan-file (the bare --apply --backup-taken that '
     + '@objectstack/cli 18.0.0-next.1 shipped, with or without --fate-supplement)',
   replacement:
-    'Run the plan first, `os migrate organization-ownership --out plan.json` (with the same `--fate-supplement`, '
-    + 'under the same tenancy posture, against the same database), review the file it writes, then '
-    + '`os migrate organization-ownership --apply --backup-taken --plan-file plan.json`. A script or runbook that '
-    + 'applies directly gains the plan step and the flag; nothing in a package source or a stored row changes.',
+    'nothing in 18.0: 18.0 refuses this invocation, as it refuses every plan and apply of '
+    + '`os migrate organization-ownership` on every database (exit 1, `NOT_IMPLEMENTED`, nothing read or written). '
+    + '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. A script or runbook that applies directly does not run '
+    + 'against 18.0 at all. In that 18.x release, run the plan first, `os migrate organization-ownership --out plan.json` '
+    + '(with the same `--fate-supplement`, under the same tenancy posture, against the same database), review the file '
+    + 'it writes, then `os migrate organization-ownership --apply --backup-taken --plan-file plan.json`: the script or '
+    + 'runbook gains the plan step and the flag; nothing in a package source or a stored row changes.',
   reason:
     'ADR-0131 D10 makes the ceremony an operator\'s act on a plan the operator reviewed. The apply computes its '
     + 'own plan at apply time, and that plan\'s inputs can move between the review and the run: a different host '
     + 'fate supplement, another release\'s inventory, another tenancy posture or another database. Planning with '
     + 'one supplement and applying with another ran the second one\'s fates unreviewed, including a mirror deletion '
-    + 'the reviewed plan never listed. So the apply now reads the plan file the operator reviewed and refuses, before '
+    + 'the reviewed plan never listed. So the 18.x apply reads the plan file the operator reviewed and refuses, before '
     + 'anything is written, when its inventory digest, posture or database differs from the run\'s. Without the '
-    + 'file there is nothing to compare, so the bare invocation is refused.',
+    + 'file there is nothing to compare, so the bare invocation is refused. 18.0 itself withholds the whole '
+    + 'ceremony: it is knowingly incomplete in 18.0, and an incomplete ceremony must never certify a v17 database '
+    + 'that the boot would then serve, so 18.0 refuses plan and apply alike before it reads anything.',
   acceptanceCriteria:
-    'Every invocation of `os migrate organization-ownership --apply` passes `--plan-file` with the file a plan run '
-    + 'wrote, and the run reports `reviewedPlan`. A run that answers `plan-file-required`, `plan-digest-mismatch`, '
+    'On 18.0, no script or runbook runs `os migrate organization-ownership`, and every v17 database stays on a 17.x '
+    + 'release. In the 18.x release that carries the upgrade path, every invocation of '
+    + '`os migrate organization-ownership --apply` passes `--plan-file` with the file a plan run wrote, and the run '
+    + 'reports `reviewedPlan`. A run that answers `plan-file-required`, `plan-digest-mismatch`, '
     + '`plan-posture-mismatch` or `plan-database-mismatch` has written nothing: plan again, review, and pass the new '
     + 'file.',
 };

packages/spec/src/migrations/entries/semantic/18.sharing-rule-declared-mirror-retired.ts

@@ -9,16 +9,16 @@ export const entry: SemanticMigration = {
     + 'the declared-rule seeder (`bootstrapDeclaredSharingRules`, @objectstack/plugin-sharing) is '
     + 'retired. FROM one `managed_by: package` row per declared rule TO none: the sharing-rule '
     + 'service reads each declared rule from the registry, its id is its name, and its grants carry '
-    + 'that name as `sys_record_share.source_id`; the organization-ownership ceremony renames the '
+    + 'that name as `sys_record_share.source_id`; the 18.x organization-ownership ceremony renames the '
     + 'grants of the rows the seeder wrote, then deletes those rows, and Setup\'s Sharing Rules object '
     + 'list (which lists rows) no longer shows declared rules. `DELETE /api/v1/sharing/rules/:idOrName` '
     + 'on a declared rule: FROM 204 with the seeded row deleted (and written again by the next boot) '
     + 'TO 403 PERMISSION_DENIED',
   replacement:
     'change or remove the rule in its declaration in the package (the stack\'s `sharingRules`); '
     + 'read declared rules through `GET /api/v1/sharing/rules`, which lists them beside the rules an '
-    + 'organization authors. An organization\'s own rule is deleted as before. On an upgraded '
-    + 'database run `os migrate organization-ownership --apply` with a fresh plan: its mirror-deletion '
+    + 'organization authors. An organization\'s own rule is deleted as before. Existing databases: 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 18.x release, run `os migrate organization-ownership --apply` on the upgraded database with a fresh plan: its mirror-deletion '
     + 'step removes the seeded copies',
   reason:
     'ADR-0131 D2 retires the seeders: declared metadata is code, served from the registry, and a '
@@ -34,6 +34,6 @@ export const entry: SemanticMigration = {
   acceptanceCriteria:
     'A fresh boot in every posture writes no `sys_sharing_rule` row for a declared rule and the rule '
     + 'still grants; removing the declaration stops its grant; no consumer deletes a declared rule '
-    + 'through the sharing-rule API or expects it as a `sys_sharing_rule` row; an upgraded database '
-    + 'certifies only after the ceremony has deleted the seeded copies.',
+    + 'through the sharing-rule API or expects it as a `sys_sharing_rule` row. 18.0 upgrades no v17 database; in the '
+    + '18.x release that carries the upgrade path, an upgraded database certifies only after its ceremony has deleted the seeded copies.',
 };

packages/spec/src/migrations/entries/semantic/18.sys-metadata-audit-organization-column-retired.ts

@@ -18,15 +18,15 @@ export const entry: SemanticMigration = {
   replacement:
     'nothing on this table — metadata is the environment\'s (ADR-0131 D6), and no organization owns '
     + 'a row. Delete any authored filter, list-view column, report grouping, formula or seed key that '
-    + 'names `organization_id` on `sys_metadata_audit`. Existing databases: run the v18 ceremony, '
-    + '`os migrate organization-ownership --out PLAN` to write its plan for review, then '
+    + 'names `organization_id` on `sys_metadata_audit`. Existing databases: 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 18.x release, run its ceremony: `os migrate organization-ownership --out PLAN` to write its plan for review, then '
     + '`os migrate organization-ownership --apply --plan-file PLAN`, which promotes or reports the legacy '
     + 'organization rows and then drops the physical column',
   reason:
     'ADR-0131 D6 retired the per-organization overlay axis: every metadata write now lands '
     + 'environment-wide with a NULL organization, every read is environment then code, and a legacy '
-    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column until the ceremony has run. The column therefore only holds '
-    + 'the legacy rows the 17.x organization layer wrote, and the v18 ceremony owns those: under '
+    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column (18.0 on every such database; the 18.x release that carries the upgrade path until its ceremony has run). The column therefore only holds '
+    + 'the legacy rows the 17.x organization layer wrote, and the 18.x ceremony owns those: under '
     + 'single it promotes the presentational customizations to environment rows and carries every '
     + 'public-form withdrawal onto the environment, fail-closed (the maintainer rulings on organization customizations and form withdrawals), and '
     + 'it reports the rest. Only then does its column-drops step drop the column, through the '
@@ -40,6 +40,7 @@ export const entry: SemanticMigration = {
   acceptanceCriteria:
     'No authored metadata names `organization_id` on `sys_metadata_audit`: the field resolver (lint and the data '
     + 'door) answers it as an unknown field. A fresh database creates `sys_metadata_audit` with no organization '
-    + 'column. On a legacy database, after `os migrate organization-ownership --apply --plan-file PLAN` the column is '
+    + 'column. 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 18.x release, after `os migrate organization-ownership --apply --plan-file PLAN` on a legacy database the column is '
     + 'gone and the boot no longer reports it orphaned.',
 };

packages/spec/src/migrations/entries/semantic/18.sys-metadata-commit-organization-column-retired.ts

@@ -18,15 +18,15 @@ export const entry: SemanticMigration = {
   replacement:
     'nothing on this table — metadata is the environment\'s (ADR-0131 D6), and no organization owns '
     + 'a row. Delete any authored filter, list-view column, report grouping, formula or seed key that '
-    + 'names `organization_id` on `sys_metadata_commit`. Existing databases: run the v18 ceremony, '
-    + '`os migrate organization-ownership --out PLAN` to write its plan for review, then '
+    + 'names `organization_id` on `sys_metadata_commit`. Existing databases: 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 18.x release, run its ceremony: `os migrate organization-ownership --out PLAN` to write its plan for review, then '
     + '`os migrate organization-ownership --apply --plan-file PLAN`, which promotes or reports the legacy '
     + 'organization rows and then drops the physical column',
   reason:
     'ADR-0131 D6 retired the per-organization overlay axis: every metadata write now lands '
     + 'environment-wide with a NULL organization, every read is environment then code, and a legacy '
-    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column until the ceremony has run. The column therefore only holds '
-    + 'the legacy rows the 17.x organization layer wrote, and the v18 ceremony owns those: under '
+    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column (18.0 on every such database; the 18.x release that carries the upgrade path until its ceremony has run). The column therefore only holds '
+    + 'the legacy rows the 17.x organization layer wrote, and the 18.x ceremony owns those: under '
     + 'single it promotes the presentational customizations to environment rows and carries every '
     + 'public-form withdrawal onto the environment, fail-closed (the maintainer rulings on organization customizations and form withdrawals), and '
     + 'it reports the rest. Only then does its column-drops step drop the column, through the '
@@ -40,6 +40,7 @@ export const entry: SemanticMigration = {
   acceptanceCriteria:
     'No authored metadata names `organization_id` on `sys_metadata_commit`: the field resolver (lint and the data '
     + 'door) answers it as an unknown field. A fresh database creates `sys_metadata_commit` with no organization '
-    + 'column. On a legacy database, after `os migrate organization-ownership --apply --plan-file PLAN` the column is '
+    + 'column. 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 18.x release, after `os migrate organization-ownership --apply --plan-file PLAN` on a legacy database the column is '
     + 'gone and the boot no longer reports it orphaned.',
 };

packages/spec/src/migrations/entries/semantic/18.sys-metadata-history-organization-column-retired.ts

@@ -18,15 +18,15 @@ export const entry: SemanticMigration = {
   replacement:
     'nothing on this table — metadata is the environment\'s (ADR-0131 D6), and no organization owns '
     + 'a row. Delete any authored filter, list-view column, report grouping, formula or seed key that '
-    + 'names `organization_id` on `sys_metadata_history`. Existing databases: run the v18 ceremony, '
-    + '`os migrate organization-ownership --out PLAN` to write its plan for review, then '
+    + 'names `organization_id` on `sys_metadata_history`. Existing databases: 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 18.x release, run its ceremony: `os migrate organization-ownership --out PLAN` to write its plan for review, then '
     + '`os migrate organization-ownership --apply --plan-file PLAN`, which promotes or reports the legacy '
     + 'organization rows and then drops the physical column',
   reason:
     'ADR-0131 D6 retired the per-organization overlay axis: every metadata write now lands '
     + 'environment-wide with a NULL organization, every read is environment then code, and a legacy '
-    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column until the ceremony has run. The column therefore only holds '
-    + 'the legacy rows the 17.x organization layer wrote, and the v18 ceremony owns those: under '
+    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column (18.0 on every such database; the 18.x release that carries the upgrade path until its ceremony has run). The column therefore only holds '
+    + 'the legacy rows the 17.x organization layer wrote, and the 18.x ceremony owns those: under '
     + 'single it promotes the presentational customizations to environment rows and carries every '
     + 'public-form withdrawal onto the environment, fail-closed (the maintainer rulings on organization customizations and form withdrawals), and '
     + 'it reports the rest. Only then does its column-drops step drop the column, through the '
@@ -40,6 +40,7 @@ export const entry: SemanticMigration = {
   acceptanceCriteria:
     'No authored metadata names `organization_id` on `sys_metadata_history`: the field resolver (lint and the data '
     + 'door) answers it as an unknown field. A fresh database creates `sys_metadata_history` with no organization '
-    + 'column. On a legacy database, after `os migrate organization-ownership --apply --plan-file PLAN` the column is '
+    + 'column. 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 18.x release, after `os migrate organization-ownership --apply --plan-file PLAN` on a legacy database the column is '
     + 'gone and the boot no longer reports it orphaned.',
 };

packages/spec/src/migrations/entries/semantic/18.sys-metadata-organization-column-retired.ts

@@ -18,15 +18,15 @@ export const entry: SemanticMigration = {
   replacement:
     'nothing on this table — metadata is the environment\'s (ADR-0131 D6), and no organization owns '
     + 'a row. Delete any authored filter, list-view column, report grouping, formula or seed key that '
-    + 'names `organization_id` on `sys_metadata`. Existing databases: run the v18 ceremony, '
-    + '`os migrate organization-ownership --out PLAN` to write its plan for review, then '
+    + 'names `organization_id` on `sys_metadata`. Existing databases: 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 18.x release, run its ceremony: `os migrate organization-ownership --out PLAN` to write its plan for review, then '
     + '`os migrate organization-ownership --apply --plan-file PLAN`, which promotes or reports the legacy '
     + 'organization rows and then drops the physical column',
   reason:
     'ADR-0131 D6 retired the per-organization overlay axis: every metadata write now lands '
     + 'environment-wide with a NULL organization, every read is environment then code, and a legacy '
-    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column until the ceremony has run. The column therefore only holds '
-    + 'the legacy rows the 17.x organization layer wrote, and the v18 ceremony owns those: under '
+    + 'organization row is served by no read, and the v18 runtime refuses to start on a database still holding the column (18.0 on every such database; the 18.x release that carries the upgrade path until its ceremony has run). The column therefore only holds '
+    + 'the legacy rows the 17.x organization layer wrote, and the 18.x ceremony owns those: under '
     + 'single it promotes the presentational customizations to environment rows and carries every '
     + 'public-form withdrawal onto the environment, fail-closed (the maintainer rulings on organization customizations and form withdrawals), and '
     + 'it reports the rest. Only then does its column-drops step drop the column, through the '
@@ -40,6 +40,7 @@ export const entry: SemanticMigration = {
   acceptanceCriteria:
     'No authored metadata names `organization_id` on `sys_metadata`: the field resolver (lint and the data '
     + 'door) answers it as an unknown field. A fresh database creates `sys_metadata` with no organization '
-    + 'column. On a legacy database, after `os migrate organization-ownership --apply --plan-file PLAN` the column is '
+    + 'column. 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 18.x release, after `os migrate organization-ownership --apply --plan-file PLAN` on a legacy database the column is '
     + 'gone and the boot no longer reports it orphaned.',
 };