Skip to content

Commit 51ad8e4

Browse files
fix(cli,runtime): the 17 → 18 ownership ceremony leaves no row without an organization on a single-posture database, its prescribed boot writes nothing before the guard refuses, and an unverified ceremony is not served (#24325)
Fixes #24282 Clause-②: yes (widening) Basis for the Clause-② line, as the seat re-declared it on the claim: one new entry export, `ensureDefaultOrganizationExists` from `@objectstack/plugin-auth` (the package entry lists 221 names on `main` and 222 here, the list is below). The `@objectstack/runtime` entry is byte-identical to `main` (`src/index.ts` unchanged, 637 names before and after), and `@objectstack/cli` exports nothing new. No published schema and no REST answer moves. This is leg A of #24282: the organization-ownership ceremony and the v18 boot guard. Leg B, where the seed loader refuses an organization-scoped twin (`packages/metadata-protocol`), is tracked on #24301, and #24301 is not addressed here. Repairing a hosted database's existing twins is an operator's data repair. It is not this PR. ## What changes 1. **On a single-posture database, the ceremony leaves no NULL-organization row (`packages/cli`).** On a database that holds no organization at all, with rows that no anchor names, `os migrate organization-ownership` now plans those rows as the Default Organization's. The plan says so in a warning (`defaultOrganizationCreatedByApply: true`). `--apply` then creates the Default Organization before its first write and gives it every such row. A run that cannot create it blocks at attribution and says why. It no longer checkpoints attribution done at zero rows and then certifies. - The route comes from ADR-0131, not from a choice made here. D3 says the Default Organization *"exists before the first write that needs an owner"*, and D10 fate 3 says the attributed rows take their owner *"under `single`, the Default Organization"*. The ceremony's attribution is a write that needs an owner, so the owner must exist before it runs. - The other route the card offered was "do not checkpoint attribution done at zero". On its own, that route deadlocks once the boot writes nothing before it refuses (point 3): nothing would ever create the owner. - Nothing is created under a walled posture, or when the database already holds organizations. - **The ceremony names the Default Organization the way the boot does** (patch round 1, the seat's ruling). Under `single`, the Default Organization is the organization with `slug = 'default'`, or else the sole organization whatever its slug. That is the find half of plugin-auth's invariant and the tenancy service's `defaultOrgId()`, and ADR-0093 D3 states it: *"the bootstrap org (stable `slug='default'`), or the sole org row if a deployment renamed it"*. ADR-0131 has no text that limits it to the slug. - Before this round, the plan required the slug. A 17.x single database whose only organization had another slug kept its unanchored rows NULL, failed verification, and with point 4 its boot would have been refused, although v18 derives every owner from that organization. - Several organizations with none `default` still name none, and their rows are reported. The plan file's `defaultOrganization.slug` is now that organization's own slug. The plan file is the command's output, not a published schema. - The organization is created through plugin-auth's boot invariant, `ensureDefaultOrganizationExists`, which is the function `AuthPlugin.start()` and the identity-objects plugin call. So the row is the one a single-posture boot would have created, and it has one producer. 2. **A checkpointed attribution runs again when the plan finds an owner for rows that are still NULL (`packages/cli`).** This is the card's step 5. The step writes only where `organization_id IS NULL`, so it never derives an owner a second time (D10 item 3). It covers D10 item 4's "resolves them and re-runs". It also completes a database that an earlier release's ceremony left with attribution checkpointed at zero. 3. **The boot the ceremony prescribes writes nothing before its guard refuses (`packages/runtime`, `packages/plugins/plugin-auth`).** `OrganizationOwnershipBootGuardPlugin` now judges in its own `start()`, not at `kernel:ready`. - It starts after the engine, whose `start()` runs the additive schema sync that the rewrite step's "boot this release once" relies on, and after the platform objects. - It starts before every plugin that writes rows at start. `AppPlugin` (the inline seed), `AuthPlugin` and the identity-objects plugin (the Default Organization) now list it in `optionalDependencies`, so the order is declared and does not depend on registration order. `os serve` registers it before them as well. - Each writer spells the name as the string literal `'com.objectstack.organization-ownership-boot-guard'`, because `check:init-service-contract` reads `optionalDependencies` only as string literals. An identifier element there made the guard read `AppPlugin`'s whole array as undeclared, which is CI's red on `a91dad2d8`, fixed in round 1. - A `start()` that throws is reported by the kernel as its own error, with the refusal as its `cause`. `os serve` and `os dev` now read the refusal from that chain, so `os dev`'s automatic upgrade and the printed refusal text are unchanged. 4. **The guard does not serve a ceremony that did not verify (`packages/runtime`).** Once no table is left in the v17 shape, a boot whose `adr-0131-organization-ownership` marker exists but is not verified is refused with `ORGANIZATION_OWNERSHIP_MIGRATION_REQUIRED`. That state is the one where the post-check found rows the ceremony did not carry, and the refusal names the re-run. D10 item 5 refuses a database the ceremony has not *completed*, and `verified_at` is the ceremony's completion marker. A database with no marker (a fresh one) boots as before, and a marker that cannot be read is refused rather than passed. - A boot with no storage (`os serve` with no `OS_DATABASE_URL` and no driver, so no driver serves `sys_migration`) has no ledger to judge, and it boots as before. The guard checks this the same way its column probe skips an object no driver serves. - Before round 1, the engine's "no driver" refusal of that read was taken as an unreadable marker, which is CI's red in `Test Core` 3/6 and 4/6 on `a91dad2d8` (four storage-less `os serve` integration tests). Fixed in round 1. ## The measured path, before and after This is the card's path, run with the real commands (`os serve` with `OS_MIGRATE_AND_EXIT=1` for the boots, `os migrate organization-ownership` for the ceremony) on one SQLite file. The file was built from a served boot of this release. It was then put into the 17.x shape: no organization, every `organization_id` NULL, `sys_job` still carrying its retired column, and `sys_user_permission_set` without `permission_set`, so the rewrite step asks for a boot. Its seed holds 5 rows of an application object, plus 5 NULL rows in `sys_activity`, `sys_setting` and `sys_setting_audit`. | step | `main` (`d537a318b`) | this branch (final head) | |---|---|---| | plan | 0 organizations, 10 rows unattributable, no warning | 0 rows unattributable, `defaultOrganizationCreatedByApply: true`, and the warning says `--apply` creates the Default Organization and gives it 10 rows | | `--apply` #1 | attribution `done` with `rowsAttributed: 0`, rewrite blocked ("Boot this release once…"), exit 1 | Default Organization created, attribution `done` with `rowsAttributed: 10`, rewrite blocked, exit 1 | | the prescribed boot | refused, after writing `sys_organization` 0 → 1 and stamping all 5 seeded rows with the new organization | refused; **no table's row count moved** | | `--apply` #2 | attribution `checkpointed`, `complete: true, blocking: 5` (`sys_activity` 2, `sys_setting` 1, `sys_setting_audit` 2), marker applied with `verified_at` NULL, exit 1 | `complete: true, blocking: 0`, marker verified, exit 0 | | the next boot | **served** (exit 0) on the unverified marker | served (exit 0) on the verified marker; the 5 seeded rows keep their one owner | The reproduction ran on `a91dad2d8`, and round 1 does not change this path (the database holds no organization). The reproduction is not a permanent test. It is pinned instead by the command-level test below. ## Public surface The `@objectstack/plugin-auth` entry adds exactly one export and removes none. Its full signature, from the built `dist/index.d.ts`, with each generic spelled out in words so the platform's body sanitizer leaves it intact: ```text declare function ensureDefaultOrganizationExists(ql: any, options?: { logger?: InvariantLogger }) : Promise of DefaultOrganizationInvariantResult interface DefaultOrganizationInvariantResult { organizationId?: string; created: boolean; ambiguous?: { organizationCount: number } } interface InvariantLogger { info: (message: string, meta?: Record of string to any) returning void } ``` The two interfaces are reached through the signature. They are not entry exports. Apart from that export line and these three declarations, the `dist/index.d.ts` with comments stripped is line-for-line unchanged. Entry exports after this change, sorted (222 names). Before is the same list without `ensureDefaultOrganizationExists` (221 names): ```text ACTIVATION_LEDGER_STANDING_KEYS, AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_ASSERTION_SCHEMA, AUTH_OAUTH_CLIENT_RESOURCE_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_OAUTH_RESOURCE_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_PHONE_NUMBER_USER_FIELDS, AUTH_SESSION_CONFIG, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AccountIdentityCollision, AccountIdentityPreflightOptions, AccountIdentityPreflightRefusal, AccountIdentityPreflightReport, AccountIdentityReadEngine, AdminActor, AdminBanEndpointDeps, AdminCreateCapableApi, AdminUserDataEngine, AdminUserEndpointDeps, AdoptMembershipOptions, AuthActorResolver, AuthBanContextLike, AuthConfig, AuthContextLike, AuthEventAuditSurface, AuthManager, AuthManagerOptions, AuthPlugin, AuthPluginConfig, AuthPluginOptions, AuthProviderConfig, AuthRequestHandler, AuthSessionAuditEventInput, BackfillMembershipsResult, CanonicalizeStoredMemberRolesOptions, CanonicalizeStoredMemberRolesResult, CounterStore, CredentialAccountAdapter, DEFAULT_ACCOUNT_SCAN_MAX, DEFAULT_AUTH_BASE_PATH, EndedMembership, EndpointResult, EnsureDefaultOrganizationOnceOptions, EnsureDefaultOrganizationOptions, EnsureDefaultOrganizationResult, FixedWindowCount, GRANT_STANDING_KEYS, IDENTITY_OBJECTS_PLUGIN_NAME, IMPORT_USERS_MAX_ROWS, INTERACTIVE_REVOKE_REASON, IdentityImportDeps, IdentityImportEngine, IdentityImportRowResult, IdentityObjectsPlugin, IdentityObjectsPluginOptions, IdentityWriteGuardOptions, ImportManagerOutcome, ImportPasswordPolicy, InProcessCounterStore, InvitationPlacementServiceLike, LAST_LOCAL_CREDENTIAL_CODE, LAST_LOCAL_CREDENTIAL_MESSAGE, LastAdminGuardEngine, LastAdminGuardOptions, LazyCacheRateLimitStorageOptions, LazyCounterStoreOptions, MAX_COOLDOWN_SECONDS, MEMBERSHIP_ENDED_REVOKE_REASON, MEMBERSHIP_POLICIES, MEMBER_OBJECT, MEMBER_STANDING_KEYS, METADATA_ACTIVATION, MemberRoleCanonicalizationOptions, MemberRoleSpellingCensusEntry, MembershipAdoptionDecision, MembershipAdoptionEngine, MembershipAdoptionVerdict, MembershipEndOutcome, MembershipEndedSessionEngine, MembershipEndedSessionOptions, MembershipPolicy, NORMALISED_IDENTIFIER_FIELDS, ObjectQLAdapterFactoryOptions, OtpGuardStorage, OtpSendDecision, OtpSendGuard, OtpSendGuardOptions, PLACEHOLDER_EMAIL_DOMAIN, PLATFORM_ADMIN_REFUSAL_MESSAGES, PlatformAdminActor, PlatformAdminRefusal, PlatformAdminVerdict, ReconcileMembershipDeps, ReconcileOutcome, RegisterSsoFormResult, RepointGuardEngine, ResendVerificationEmailResult, SESSION_ERASURE_PATHS, SIGN_OUT_PATH, STANDING_KEYS_BY_TABLE, STANDING_KEY_EXCLUSIONS, SUPPORTED_WHERE_OPERATORS, SYS_ACCOUNT_OBJECT, SYS_USER_IMPORT_UPDATE_FIELDS, SYS_USER_PROFILE_EDIT_FIELDS, SecondaryStorageLike, SessionTombstonePatch, SetInitialPasswordResult, SetPasswordCapableApi, TenancyPosture, TenancyService, TenancyServiceDeps, USER_STANDING_KEYS, adoptExistingMembership, assertNoAccountIdentityCollisions, assertOtpCooldownSeconds, assertScimAdminCoherence, authEmailLocaleFromRequest, authSystemWriteContext, backfillMemberships, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildPhoneNumberPluginSchema, buildTwoFactorPluginSchema, cacheSecondaryStorage, canonicalMemberRole, canonicalizeStoredMemberRoles, counterStoreFromKv, createEnsureDefaultOrganizationOnce, createIdentityObjectsPlugin, createLazyCacheRateLimitStorage, createLazyCounterStore, createObjectQLAdapter, createObjectQLAdapterFactory, createTenancyService, currentAuthEndpointPath, decideAdoptedRole, emitAuthSessionAuditEvent, endSessionClaimsForEndedMembership, ensureDefaultOrganization, ensureDefaultOrganizationExists, filterRevokedSessionRows, formatAccountIdentityPreflightReport, generatePlaceholderEmail, generateTemporaryPassword, getManagedUpdateWhitelist, hideRevokedSessionRow, incrementFixedWindow, ipMatchesRange, isCanonicalMemberRole, isDefaultOrganizationBootstrapTrigger, isKnownMembershipRole, isLastLocalCredentialHolder, isLikelyEmail, isMembershipPolicy, isOAuthEligibleBaseUrl, isPlaceholderEmail, isPlatformAdminUser, isRevokedSessionRow, judgeHeldSession, judgePlatformAdmin, loginEventFor, logoutEventFor, mapAuthApiError, normalizeAuthEmailLocale, normalizePhoneNumber, probeAccountIdentityCollisions, readInvitationPlacementIntent, readMcpServerEnabledEnv, reconcileMembership, reconcileSessionDelete, refuseIssuerRepointWithLiveBindings, registerIdentityWriteGuard, registerLastAdminGuard, registerManagedUpdateWhitelist, registerMemberRoleCanonicalization, registerMembershipEndedSessionTrigger, resolveAttributedUserId, resolveDcrEnabled, resolveDefaultOrgId, resolveOidcProviderEnabled, resolveProtocolName, resolveScimEnabled, runAdminBanUser, runAdminCreateUser, runAdminImportUsers, runAdminSetUserPassword, runAdminUnbanUser, runAttributedToUser, runRegisterSamlProviderFromForm, runRegisterSsoProviderFromForm, runRequestDomainVerification, runResendVerificationEmail, runSetInitialPassword, runVerifyDomain, runWithAuthActorScope, setAuthActorResolver, withSystemContext, withSystemReadContext, withValidationErrorMapping ``` `@objectstack/runtime`'s entry is unchanged. Its declarations differ in one line, which is not a type change: `readonly name = "com.objectstack.organization-ownership-boot-guard"` becomes `readonly name: "com.objectstack.organization-ownership-boot-guard"`, the same literal type, now taken from a package-internal constant that `AppPlugin` reads. The one behaviour a host can observe is that a host composing the guard now sees the kernel's start-failure error with the refusal as its `cause`. The changeset says so, with the one-line read. **Why the export, and not a narrower route.** `default-organization-invariant.ts` kept the invariant internal so that no host composing a kernel has to remember to call it. That still holds: the module header now says so, and only the two plugins call it on a boot. The ceremony is not a host composing a kernel. It is the one caller that is not a boot, and the boot that would have created the organization is the one the guard now refuses before any plugin writes. The routes that need no export are either a second producer of the Default Organization row (an engine insert in the CLI) or calling `IdentityObjectsPlugin.start()` by hand outside a kernel. The first forks the invariant and the second is a workaround. ## Files outside this lane These files belong to `domain:services` (plugin-auth), and the seat declared them on the lane post: - `packages/plugins/plugin-auth/src/index.ts` - `default-organization-invariant.ts` (the header note) - `auth-plugin.ts` and `identity-objects-plugin.ts` (the guard in `optionalDependencies`, plus the note) - `default-organization-guard-ordering.pin.test.ts` The changes there are the producer side of points 1 and 3. `packages/qa/dogfood/test/organization-ownership-boot-refusal-order.dogfood.test.ts` is updated to read the refusal from the cause chain. ## Tests - `packages/runtime` - `organization-ownership-boot-guard.kernel.test.ts` boots a real kernel over SQLite. In the hostile slot, `AppPlugin` and plugin-auth's identity-objects plugin are `use()`d before the guard, and the refused file holds no organization and no seed row. `AppPlugin` alone gives the same result. Control: the same composition over a fresh file writes both. It also covers the unverified-marker refusal with no v17 column, plus its verified control. - In the same kernel test, a fresh database boots with the ledger registered and its read answering no row. That means the guard took the read and found the marker absent, not unreadable. - `organization-ownership-boot-guard.test.ts` covers the start-phase refusal registering no hook, the declarations, the unverified, unreadable and absent marker cases after the column drops, a boot with no storage, and the existing cases. - `packages/plugins/plugin-auth` - `default-organization-guard-ordering.pin.test.ts` shows that the declaration moves the order for `AuthPlugin` and `IdentityObjectsPlugin` in a hostile registry, that removing it reverts the order, and that it is order-if-present. - `packages/cli` - `utils/organization-ownership-apply.test.ts` covers creation before the first write, the marker verifying, a missing or failing producer blocking at attribution, and the controls (no row falls to the Default Organization, a walled posture, organizations present with none the Default Organization). It also covers the checkpointed attribution running again over the state an earlier run left. - **One definition of the Default Organization** (round 1, in `utils/organization-ownership-apply.test.ts`). Over the same SQLite fixtures, the plan's `defaultOrganization` and plugin-auth's `ensureDefaultOrganizationExists` name the same organization in each case: - `default` present beside another organization - a sole organization with another slug - two organizations with none `default` (both name none; the invariant answers `ambiguous`) - none at all (the plan says `--apply` creates it; the invariant creates it, and the next plan names it) - Also in round 1: a sole organization with another slug takes every unanchored row through `--apply`, and the marker verifies. - `utils/organization-ownership-plan.integration.test.ts` covers the plan's count and warning, the sole-organization case, and the walled control. - `commands/migrate/organization-ownership.no-organization.integration.test.ts` runs the card's path through the real command: plan, `--apply`, the guarded boot refused with every row count unchanged, `--apply` again verified, then the guarded boot starts with no duplicate. Round-1 results on head `eb9605968`, through the shared verify lock: - runtime guard files: 3 files, 29/29 passed - cli: the ceremony family, plus the four `os serve` integration files CI found red on `a91dad2d8` (`serve-no-transport-announcements` (both), `serve-no-storage-boot-guard`, `serve-kernel-only-lifetime`, `serve-no-server-banner`), 29 files: 275 passed, 1 skipped - typecheck for runtime and cli: exit 0. plugin-auth is unchanged this round. Round 0, on `a91dad2d8`: - plugin-auth ordering pins: 13/13 passed - typecheck for runtime, plugin-auth and cli: exit 0 Full suites, on the round-0 pre-merge head: - runtime: 417 files, 6573 passed - plugin-auth: 160 files, 3118 passed - cli `unit` project: 308/310 files. The 2 remaining failed only because `packages/cli/dist` was not yet built (`published-subpath-*.pin`). They passed on the final head after the build. Incoming `main` touched none of these packages' sources other than a runtime test and a dev alias. The touched dogfood file (`organization-ownership-boot-refusal-order.dogfood.test.ts`, the showcase composition upgraded through the refusal) was run once on the final head: 4/4 passed. In that run the refused boot still adds the column the ceremony waits for, the ceremony verifies, and the next boot starts. **Ablations.** Each one was mutated through `scripts/ablation-replace.mjs`, which verifies the mutation landed, and restored, with blob equal to `HEAD` and `git diff HEAD` empty: - guard back at `kernel:ready`: 4 red, including both "writes nothing" cases - `AppPlugin` without the guard declaration: 2 red (the declaration pin and the `AppPlugin`-alone case). The all-writers case stays green, because the identity-objects plugin's own declaration still pulls the guard ahead. - no marker read once the columns are gone: 3 red - attribution without creating the Default Organization: 3 red - the plan reporting instead of counting: 4 red - a checkpointed attribution never re-run: 1 red - round 1, the plan's Default Organization reverted to slug-only: 3 red (the one-definition pin's sole-organization case, the plan's sole-organization case, and the `--apply` sole-organization case) - round 1, the storage-less ledger check removed: 1 red A first attempt at the `AppPlugin` leg was refused by the tool (a delete written as a replace) and was re-run as `--delete`. **Gates (round 1, head `eb9605968`).** - `node scripts/pm/dispatch-gates.mjs --commands` derives 80 commands, and all 80 exit 0. `check:dual-build-cjs-loads` and `check:i18n-coverage` first exited 3 on missing `dist/` and exited 0 after building what they named. `--ran` reconciliation: 80 derived, 80 run, 0 NOT-MEASURED. - **Declared wide-population families**, listed by `dispatch-gates` without `--commands`, whose population covers the changed packages: - `check:init-service-contract` exited 1 on `a91dad2d8` (reproduced locally: `packages/runtime/src/app-plugin.ts:710 — AppPlugin`) and exits 0 on the fix. - `check:live-db-isolation`, `check:optional-error-sink`, `check:resume-authority-declared`, `check:runner-env-posture`, `check:settings-bind-window`, `check:startup-registry-verdict`, `check:verify-stand-in` and `check:wildcard-fallthrough` each exit 0. - `check:meta-type-normalized` reads `packages/rest/src` only, which this diff does not touch. - `pnpm exec eslint --no-inline-config` over the 18 changed source and test files exits 0. - Changed lines: +1242 / −115 over 19 files. ## Acceptance notes - The docblock of `ORGANIZATION_OWNERSHIP_MIGRATION_ID` (`packages/spec/src/system/migration.zod.ts`) describes the refusal only for a database still in the v17 shape. It is now narrower than the guard, which also refuses an unverified marker after the column drops. `packages/spec` is not this lane's, so the docblock is left as it is. - After the verified ceremony, the next boot of the reproduction (a development boot, which seeds an admin) wrote a `sys_user_permission_set` `admin_full_access` grant with `organization_id` NULL. The same boot over a fresh file wrote one too. That is ADR-0131 D5's platform-admin grant row, whose Default-Organization ownership D5 assigns to C3. The seat dropped this note as covered by #15204 (C3; D5's stated interim). --- _Generated by [Claude Code](https://claude.ai/code/session_01SYEJqDL3NXxrJRBVqaMu9T)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 68a090f commit 51ad8e4

19 files changed

Lines changed: 1242 additions & 115 deletions
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
'@objectstack/cli': patch
3+
'@objectstack/runtime': patch
4+
'@objectstack/plugin-auth': minor
5+
---
6+
7+
Clause-②: yes (widening)
8+
9+
fix(cli,runtime): the 17 → 18 organization-ownership upgrade of a single-posture database that holds no organization leaves no row without one, the boot the ceremony prescribes writes nothing before it is refused, and a ceremony that did not verify is never served (ADR-0131 D3, D10)
10+
11+
A 17.x single-posture install whose seed ran before any organization existed holds rows of organization-owned objects with `organization_id` NULL and an empty `sys_organization`. Upgrading it took this path: the ceremony's attribution checkpointed itself done at zero rows; the boot its rewrite step asks for created the Default Organization and let the inline seed stamp some rows before it refused; the second `--apply` did not run attribution again, dropped the columns and recorded discrepancies with `verified_at` NULL; and `os start` then served that database.
12+
13+
- **The ceremony creates the Default Organization (`@objectstack/cli`).** Under the `single` posture, on a database that holds no organization and rows no anchor names, `os migrate organization-ownership` plans those rows as the Default Organization's and says so in a plan warning (`defaultOrganizationCreatedByApply: true` in the plan file). `--apply` creates it before its first write, through plugin-auth's boot invariant (the row a single-posture boot creates), and gives it every such row. A run that cannot create it — a boot without the auth family that declares `sys_organization` — blocks at attribution, naming why, instead of attributing nothing and certifying. Nothing is created under a walled posture, or when the database holds organizations.
14+
- **The ceremony names the Default Organization as the boot does (`@objectstack/cli`).** Under `single` it is the organization with `slug = 'default'`, else the sole organization whatever its slug — the boot invariant's and the tenancy service's definition (ADR-0093 D3). Before, the plan required `slug = 'default'`, so a database whose only organization had another slug kept its unanchored rows NULL through the ceremony while v18 derives every owner from that organization. Several organizations, none of them `default`, still name none, and their rows are reported. In the plan file (the command's own output, not a published schema) `defaultOrganization.slug` is now that organization's own slug, no longer always `'default'`.
15+
- **A checkpointed attribution runs again (`@objectstack/cli`)** whenever the plan derives an owner for rows still NULL: a row the operator made attributable since, or one an earlier run found no Default Organization for. It writes only where `organization_id` is NULL, so no owner already written is derived again. A database left by an earlier release's ceremony in that state is completed by re-running `--apply`.
16+
- **The boot guard judges before any plugin writes (`@objectstack/runtime`, `@objectstack/plugin-auth`).** `OrganizationOwnershipBootGuardPlugin` judges in its own `start()`, after the engine's schema sync (the column the rewrite step waits for is still added) and before every plugin that writes rows at start: `AppPlugin` (the inline seed), `AuthPlugin` and the identity-objects plugin (the Default Organization) name it (`com.objectstack.organization-ownership-boot-guard`) in `optionalDependencies`. A refused boot leaves every row as it found it.
17+
- **A ceremony that did not verify is refused (`@objectstack/runtime`).** With no table left in the v17 shape, a boot whose `adr-0131-organization-ownership` marker exists and is not verified — the post-check found rows the ceremony has not carried — is refused with `ORGANIZATION_OWNERSHIP_MIGRATION_REQUIRED`, naming the re-run. A database with no marker (a fresh one) boots as before.
18+
- **The refusal now arrives as a `cause` (`@objectstack/runtime`).** A failed `start()` is reported by the kernel as its own error ("Plugin … failed to start"), with the plugin's error as its `cause`. A host that composes the guard and inspects the boot error asks `isOrganizationOwnershipBootRefusal` of each `cause` down the chain: asked of the kernel's own error it now answers `false`. `assertOrganizationOwnershipMigrated(engine)` still throws the refusal itself. `os serve` and `os dev` read it from the chain.
19+
- **One new export (`@objectstack/plugin-auth`, `minor`).** `ensureDefaultOrganizationExists(ql, options?)` — the Default Organization's boot invariant, find-or-create under `single` — for the ceremony, so the organization it creates is the row a single-posture boot creates, from one producer. A host composing a kernel still never calls it: `AuthPlugin` and the identity-objects plugin keep the invariant on every boot. No other package entry changes.
20+
21+
Unchanged: the ceremony's steps, fates and refusals otherwise; a walled posture's unattributable rows (reported, never assigned); the boot of a fresh or verified database; and every plugin's order on a kernel that does not compose the guard. Repairing a database whose organization-scoped seed load already inserted twins of NULL-organization rows is an operator's data repair.
Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* The 17 → 18 upgrade of a single-posture database whose seed ran before any
5+
* organization existed — through `os migrate organization-ownership`, over a
6+
* SQLite file, with the boot the ceremony prescribes in between (ADR-0131 D3,
7+
* D10 items 3 to 5).
8+
*
9+
* ## The database
10+
*
11+
* A served boot of THIS release (`@objectstack/verify`'s `bootStack`, plugin
12+
* starts included) of a package whose seed writes three rows of an
13+
* organization-owned object; then what a 17.x install left instead: no
14+
* organization, every row's `organization_id` NULL, no grant, `sys_job` still
15+
* carrying its retired organization column (the v17 shape the boot guard
16+
* reads), and `sys_user_permission_set` without its `permission_set` column —
17+
* so the ceremony's rewrite step asks for one boot of this release.
18+
*
19+
* ## The path, measured end to end on the release before this pin
20+
*
21+
* 1. the plan counted every seeded row unattributable ("no Default
22+
* Organization exists to fall back to");
23+
* 2. `--apply` checkpointed attribution done at zero rows and stopped at the
24+
* rewrite, asking for a boot;
25+
* 3. that boot created the Default Organization and let the inline seed stamp
26+
* the rows with it, and only then refused;
27+
* 4. the second `--apply` did not run attribution again, dropped the columns
28+
* and found discrepancies — marker applied, never verified;
29+
* 5. and the next boot served that database.
30+
*
31+
* ## What this pins instead
32+
*
33+
* 1. the plan says `--apply` creates the Default Organization and counts no
34+
* row unattributable;
35+
* 2. `--apply` creates it (plugin-auth's boot invariant, through the apply's
36+
* own boot) and gives it every seeded row, then stops at the rewrite;
37+
* 3. ⭐ the prescribed boot is refused, and wrote no row: every table's row
38+
* count is what the apply left;
39+
* 4. the second `--apply` completes with zero discrepancies and verifies;
40+
* 5. the guarded boot starts.
41+
*
42+
* The guard's own ordering, on a bare kernel, is
43+
* `runtime/src/organization-ownership-boot-guard.kernel.test.ts`; the apply's
44+
* steps without a boot are `utils/organization-ownership-apply.test.ts`.
45+
*/
46+
47+
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
48+
import Database from 'better-sqlite3';
49+
import { mkdtempSync, rmSync } from 'node:fs';
50+
import { tmpdir } from 'node:os';
51+
import { join } from 'node:path';
52+
import { fileURLToPath } from 'node:url';
53+
import { ORGANIZATION_OWNERSHIP_MIGRATION_ID } from '@objectstack/spec/system';
54+
import { bootStack } from '@objectstack/verify';
55+
import { isOrganizationOwnershipBootRefusal, OrganizationOwnershipBootGuardPlugin } from '@objectstack/runtime';
56+
import { isExitSignal } from '../../utils/format.js';
57+
58+
// Pay the first transform of the dist-resolved workspace deps the boots reach
59+
// through dynamic `import()`s at MODULE LOAD, not inside a clocked case.
60+
import '@objectstack/objectql';
61+
import '@objectstack/metadata-protocol';
62+
import '@objectstack/plugin-auth';
63+
64+
type Command = (typeof import('./organization-ownership.js'))['default'];
65+
let MigrateOrganizationOwnership: Command;
66+
67+
const CLI_ROOT = fileURLToPath(new URL('../../..', import.meta.url));
68+
const CASE_TIMEOUT_MS = 180_000;
69+
70+
/** Env that would point a boot somewhere other than the fixture, or change what it composes. */
71+
const OVERRIDING_ENV = [
72+
'OS_DATABASE_URL', 'DATABASE_URL', 'TURSO_DATABASE_URL', 'TURSO_AUTH_TOKEN', 'OS_DATABASE_AUTH_TOKEN',
73+
'OS_DATABASE_DRIVER', 'OS_HOME', 'OS_ARTIFACT_PATH', 'OS_TELEMETRY_DB', 'OS_TENANCY_POSTURE',
74+
'OS_MULTI_ORG_ENABLED', 'OS_SKIP_SCHEMA_SYNC', 'NODE_ENV',
75+
] as const;
76+
77+
const SUBJECTS = ['kick-off', 'review', 'sign-off'];
78+
79+
/** A package whose seed writes three rows of an organization-owned object; built anew per boot, as `bootStack` asks. */
80+
const stackConfig = () => ({
81+
manifest: { id: 'com.test.ceremony_no_organization', name: 'Ceremony with no organization', type: 'app', version: '1.0.0' },
82+
objects: [{ name: 'crm_event', label: 'Event', fields: { subject: { type: 'text', label: 'Subject' } } }],
83+
data: [{ object: 'crm_event', mode: 'upsert', externalId: 'subject', records: SUBJECTS.map((subject) => ({ subject })) }],
84+
});
85+
86+
let dir: string;
87+
/** The file the ceremony runs over. */
88+
let file: string;
89+
const savedEnv: Record<string, string | undefined> = {};
90+
const savedCwd = process.cwd();
91+
92+
/** One statement against the file, through a connection of its own. */
93+
function sql(statement: string, ...params: unknown[]): Record<string, unknown>[] {
94+
const db = new Database(file);
95+
try {
96+
const prepared = db.prepare(statement);
97+
return prepared.reader ? (prepared.all(...params) as Record<string, unknown>[]) : (prepared.run(...params), []);
98+
} finally {
99+
db.close();
100+
}
101+
}
102+
103+
/** Every table's row count: what a refused boot must leave as it found it. */
104+
function rowCounts(): Record<string, number> {
105+
const tables = sql(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`);
106+
return Object.fromEntries(tables.map(({ name }) => [String(name), Number(sql(`SELECT COUNT(*) AS n FROM "${String(name)}"`)[0]!.n)]));
107+
}
108+
109+
/** The real command, its stdout parsed, and the exit it asked for. */
110+
async function run(args: string[]): Promise<{ payload: any; exitCode: number }> {
111+
const savedExit = process.exitCode;
112+
const swallow = ((_chunk: unknown, ...rest: unknown[]) => {
113+
const cb = rest.find((a) => typeof a === 'function') as (() => void) | undefined;
114+
if (cb) cb();
115+
return true;
116+
}) as typeof process.stdout.write;
117+
const stdout = vi.spyOn(process.stdout, 'write').mockImplementation(swallow);
118+
vi.spyOn(process.stderr, 'write').mockImplementation(swallow);
119+
vi.spyOn(console, 'log').mockImplementation(() => {});
120+
vi.spyOn(console, 'warn').mockImplementation(() => {});
121+
vi.spyOn(console, 'error').mockImplementation(() => {});
122+
process.chdir(dir);
123+
let exitCode: number | undefined;
124+
try {
125+
try {
126+
await MigrateOrganizationOwnership.run(args, { root: CLI_ROOT });
127+
} catch (error) {
128+
if (!isExitSignal(error)) throw error;
129+
exitCode = (error as { oclif?: { exit?: number } }).oclif?.exit;
130+
}
131+
const payload = JSON.parse(stdout.mock.calls.map((c) => String(c[0])).join('').trim());
132+
return { payload, exitCode: exitCode ?? (process.exitCode as number | undefined) ?? 0 };
133+
} finally {
134+
process.chdir(savedCwd);
135+
process.exitCode = savedExit;
136+
vi.restoreAllMocks();
137+
}
138+
}
139+
140+
/** A served boot over the file with the v18 guard composed (`os serve`'s refusal); the error it failed with, or null once it started and stopped. */
141+
async function guardedBoot(): Promise<unknown> {
142+
try {
143+
const stack = await bootStack(stackConfig(), { databaseFile: file, extraPlugins: [new OrganizationOwnershipBootGuardPlugin({ dev: true })] });
144+
await stack.stop();
145+
return null;
146+
} catch (error) {
147+
return error;
148+
}
149+
}
150+
151+
/** The guard's refusal down a failed boot's `cause` chain (the kernel reports a failed `start()` as its own error). */
152+
function refusalIn(error: unknown): { code: string; tables: readonly string[] } | undefined {
153+
for (let e = error, depth = 0; !!e && typeof e === 'object' && depth < 8; e = (e as { cause?: unknown }).cause, depth++) {
154+
if (isOrganizationOwnershipBootRefusal(e)) return e;
155+
}
156+
return undefined;
157+
}
158+
159+
describe('os migrate organization-ownership on a single-posture database that holds no organization', () => {
160+
beforeAll(async () => {
161+
for (const key of OVERRIDING_ENV) {
162+
savedEnv[key] = process.env[key];
163+
delete process.env[key];
164+
}
165+
({ default: MigrateOrganizationOwnership } = await import('./organization-ownership.js'));
166+
dir = mkdtempSync(join(tmpdir(), 'os-ceremony-no-organization-'));
167+
file = join(dir, 'fixture.db');
168+
169+
const stack = await bootStack(stackConfig(), { databaseFile: file });
170+
await stack.stop();
171+
expect(sql('SELECT COUNT(*) AS n FROM crm_event')).toEqual([{ n: SUBJECTS.length }]);
172+
173+
// What a 17.x install whose seed ran before any organization existed left.
174+
for (const { name } of sql(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`)) {
175+
const columns = sql(`SELECT name FROM pragma_table_info(?)`, name).map((c) => c.name);
176+
if (columns.includes('organization_id')) sql(`UPDATE "${String(name)}" SET organization_id = NULL`);
177+
}
178+
sql('DELETE FROM sys_organization');
179+
sql('DELETE FROM sys_member');
180+
sql('DELETE FROM sys_user_permission_set');
181+
sql(`DELETE FROM sys_migration WHERE id IN ('seed-tenancy-backfill', ?)`, ORGANIZATION_OWNERSHIP_MIGRATION_ID);
182+
sql('ALTER TABLE sys_job ADD COLUMN organization_id varchar(255)');
183+
for (const { name } of sql(`SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'sys_user_permission_set' AND sql IS NOT NULL`)) {
184+
sql(`DROP INDEX "${String(name)}"`);
185+
}
186+
sql('ALTER TABLE sys_user_permission_set DROP COLUMN permission_set');
187+
}, CASE_TIMEOUT_MS);
188+
189+
afterAll(() => {
190+
for (const key of OVERRIDING_ENV) {
191+
if (savedEnv[key] === undefined) delete process.env[key];
192+
else process.env[key] = savedEnv[key];
193+
}
194+
if (dir) rmSync(dir, { recursive: true, force: true });
195+
});
196+
197+
it('⭐ the Default Organization the ceremony creates owns every seeded row, the boot it prescribes writes nothing before its refusal, and the marker verifies', async () => {
198+
const planFile = join(dir, 'plan.json');
199+
const plan = await run(['--dev', '--database-url', `file:${file}`, '--json', '--out', planFile]);
200+
expect(plan.payload.error, JSON.stringify(plan.payload).slice(0, 800)).toBeUndefined();
201+
expect(plan.payload.plan).toMatchObject({ posture: 'single', organizations: 0, defaultOrganization: null, defaultOrganizationCreatedByApply: true });
202+
expect(plan.payload.plan.warnings).toContainEqual(expect.stringMatching(/^This database holds no organization, and the tenancy posture is single: --apply creates the Default Organization/));
203+
expect(plan.payload.plan.tables.find((t: { object: string }) => t.object === 'crm_event')).toMatchObject({
204+
attribution: { 'default-organization': SUBJECTS.length },
205+
unattributable: [],
206+
});
207+
208+
// The first apply: the Default Organization first, then every seeded row to it; the rewrite asks for a boot.
209+
const applyArgs = (out: string) => ['--dev', '--apply', '--backup-taken', '--plan-file', planFile, '--database-url', `file:${file}`, '--json', '--out', join(dir, out)];
210+
const first = await run(applyArgs('apply-1.json'));
211+
expect(first.payload.error, JSON.stringify(first.payload).slice(0, 800)).toBeUndefined();
212+
const firstSteps = first.payload.report.steps as Array<{ step: string; status: string; summary: Record<string, number>; blockers: string[] }>;
213+
expect(firstSteps[0]).toMatchObject({ step: 'attribution', status: 'done' });
214+
expect(firstSteps.find((s) => s.step === 'rewrite')).toMatchObject({
215+
status: 'blocked',
216+
blockers: [expect.stringMatching(/Boot this release once against the database \(its schema sync adds the column\), then re-run/)],
217+
});
218+
expect(first.exitCode).toBe(1);
219+
const organizations = sql('SELECT id, slug FROM sys_organization');
220+
expect(organizations).toEqual([{ id: expect.any(String), slug: 'default' }]);
221+
expect(sql('SELECT DISTINCT organization_id FROM crm_event')).toEqual([{ organization_id: organizations[0]!.id }]);
222+
223+
// ⭐ The boot it prescribes: refused, having written no row.
224+
const before = rowCounts();
225+
const refusal = refusalIn(await guardedBoot());
226+
expect(refusal?.code).toBe('ORGANIZATION_OWNERSHIP_MIGRATION_REQUIRED');
227+
expect(refusal?.tables).toContain('sys_job');
228+
expect(sql('SELECT name FROM pragma_table_info(?)', 'sys_user_permission_set').map((c) => c.name)).toContain('permission_set');
229+
const after = rowCounts();
230+
expect(Object.fromEntries(Object.keys(before).map((t) => [t, after[t]]))).toEqual(before);
231+
for (const table of Object.keys(after).filter((t) => !(t in before))) expect(after[table], table).toBe(0);
232+
233+
const second = await run(['--dev', '--apply', '--backup-taken', '--plan-file', planFile, '--database-url', `file:${file}`, '--json', '--out', join(dir, 'apply-2.json')]);
234+
expect(second.payload.error, JSON.stringify(second.payload).slice(0, 800)).toBeUndefined();
235+
expect([second.exitCode, second.payload.report.complete, second.payload.report.blocking]).toEqual([0, true, 0]);
236+
expect(sql('SELECT verified_at IS NOT NULL AS verified, blocking FROM sys_migration WHERE id = ?', ORGANIZATION_OWNERSHIP_MIGRATION_ID))
237+
.toEqual([{ verified: 1, blocking: 0 }]);
238+
expect(sql('SELECT COUNT(*) AS n FROM crm_event WHERE organization_id IS NULL')).toEqual([{ n: 0 }]);
239+
240+
// The verified database starts; its inline seed finds every row it owns, so it adds none.
241+
expect(await guardedBoot()).toBeNull();
242+
expect(sql('SELECT COUNT(*) AS n, COUNT(DISTINCT organization_id) AS owners FROM crm_event')).toEqual([{ n: SUBJECTS.length, owners: 1 }]);
243+
}, CASE_TIMEOUT_MS);
244+
});

0 commit comments

Comments
 (0)