fix(cli): os migrate organization-ownership plans a v17 database still holding the retired sys_scim_provider, as fate 4 (ADR-0131 D10) - #23874

Clause-②: no

What was wrong

os migrate organization-ownership refuses a v17 database that still holds the retired sys_scim_provider table:

sys_scim_provider carries organization_id but the ADR-0131 D10 inventory gives it no fate.

• Why the inventory had no row. sys_scim_provider was retired from the tree on 2026-08-28. The ADR-0087 entry is packages/spec/src/migrations/entries/semantic/18.scim-provider-object-retired.ts. The first census was measured on 2026-08-31, so neither census counted the object, and the inventory got no row for it.
• Why the table is still there. The same ADR-0087 entry leaves the table in deployed databases "in place untouched, by ruling — no backfill, no reaper, no migrate command". So every database that booted an earlier release still holds it, organization_id included.
• What the plan does with it. It throws uninventoried-platform-table for any platform-prefixed table that carries the column and has no row (organization-ownership-plan.ts, the loop in buildOrganizationOwnershipPlan). --apply builds the same plan, so the ceremony cannot run on such a database at all. os dev / os serve then stay refused, because the boot guard waits for the ceremony's marker.
• Where it was measured. A copy of the maintainer's local hotcrm dev.db, a long-lived SQLite dev database first created on 17.x, on @objectstack/* 18.0.0-next.2. The plan refused it. A one-row host fate supplement for sys_scim_provider was the workaround there.

What changed

• A new census population, retired-before-census. It holds platform objects retired from the tree before the first census, whose tables an upgraded database still holds. It is documented in the inventory's header with the other populations.

• A fate-4 row for sys_scim_provider. It follows the precedent of sys_view_definition, sys_saved_report and sys_report_schedule (fate report: rows listed, never attributed, never deleted). Its citation names the ADR-0087 entry and carries no tracker number.

• notNullExempt on the row. The precedent rows do not carry one; this row does, for three reasons:

  • the ruling leaves this table untouched;
  • no declaration anchors tenancy on its column any more;
  • the retired object declared organization_id as required: false, because better-auth's SCIM plugin scopes a connection to an organization only optionally. A connection with no organization was a legitimate row.

  Without the exemption, the plan would report that the table "will receive NOT NULL" once no NULL row remains, which is a promise about a table the ruling says nothing touches.

Pins

• organization-ownership-inventory.test.ts. A new frozen list, RETIRED_BEFORE_CENSUS (sys_scim_provider → scim-provider-object-retired). For each entry, the test asserts:
  • the population's premise: it is in neither census list and not in PLATFORM_OBJECTS_BY_PACKAGE;
  • the ADR-0087 entry the citation names exists in MIGRATIONS_BY_MAJOR, and its acceptance criteria still say the table is "left in place untouched", which is what licenses fate 4;
  • the row has census retired-before-census, fate report, a citation containing the entry id and no tracker number, and a notNullExempt;
  • control: no other row claims the population.
• organization-ownership-plan.integration.test.ts. A v17-shaped sys_scim_provider (its last declared columns: id, provider_id, provider_key, scim_token, organization_id, user_id, created_at, updated_at), with one stamped row and one NULL row.
  • Under isolated and single, it plans as source: inventory, fate report.
  • Counts: 2 total / 1 NULL / 1 stamped.
  • The NULL row is listed as "fate 4: reported, never guessed". Under single it is not given to the Default Organization.
  • notNull.willReceive: false, with the exemption's reason.
  • Control: the same database, planned with the inventory minus this row, is refused uninventoried-platform-table naming sys_scim_provider.

Verification

On b0aca327bf (base origin/main f7e836da1e):

• pnpm --filter @objectstack/cli typecheck: exit 0.
• The two touched files (vitest run src/utils/organization-ownership-inventory.test.ts src/utils/organization-ownership-plan.integration.test.ts): Test Files 2 passed, Tests 37 passed.
• pnpm --filter @objectstack/cli test (both projects):
  • First run: Test Files 13 failed | 430 passed | 1 skipped (444), Tests 11 failed | 5694 passed | 51 skipped. None of the 13 is an ownership-ceremony file. Five of them refused to load with "packages/cli is not built", because the run had built only the CLI's dependencies.
  • After pnpm exec turbo run build --filter=@objectstack/cli, the 13 re-run as 7 failed | 6 passed, 14 failed tests.
  • Clean-base control. The three changed source files were restored to the base f7e836da1e, the CLI was rebuilt, and those 7 re-run. The failing set is identical, test by test: 7 failed (7), 14 failed. The tree was then restored to HEAD and the CLI rebuilt.
  • So the 7 are this machine's environment, not this change. The causes the assertions name: macOS tmpdir() resolving to /private/var/… against an expected /var/…, and no util-linux script(1) for os dev on a real terminal. The 7 are the two published-subpath-* pins, dev-boot-output-order, published-entry-node-env-source-reroute, serve-runtime-state-project-key, verify-dashboard-windows and plan.reads-env-files. CI runs all of them.
• ESLint on the three changed TypeScript files, with --no-inline-config: exit 0. node scripts/check-doc-authoring.mjs: clean. node scripts/check-cross-package-test-inputs.mjs: OK.
• origin/main has moved two commits past the base (6422da58e8, 7a6ba03109). Neither touches packages/cli or packages/spec/src/migrations.

Acceptance notes

• The inventoryDigest changes. A plan file written by an earlier CLI no longer matches, and --apply --plan-file refuses it with plan-digest-mismatch, as for any inventory change. The changeset says to re-plan.
• The other three blockers from the same hotcrm reproduction are filed, not fixed here:
  • The v17 boot refusal sends the operator to the ownership ceremony without the composition it needs (NODE_ENV=development or OS_AUTH_SECRET), and names a bare --apply the ceremony refuses without --plan-file #23871: the boot refusal does not say the ceremony needs the dev boot's composition, and names a bare --apply;
  • [Decision] The ownership ceremony classes the 8 shipped permission sets an old seeder stored as managed_by='admin' as authored and says to rename them: mirror them, keep blocking with the true remedy, or ask per row? #23873 (decision): the 8 shipped permission sets an old seeder stored as managed_by='admin';
  • os migrate organization-ownership --apply: column-drops blocks on stale primary copies of the telemetry-routed objects with "Run the ceremony with the release whose declaration drops it", and the ceremony never reads the telemetry sibling #23872: stale primary copies of telemetry-routed objects block column-drops, and the ceremony never reads the sibling.
• No issue was filed for this fix itself. The defect and its reproduction are in this body.

Generated by Claude Code