fix(cli): the organization-ownership ceremony reads its dialect once, through metadata-core's shared resolver, and refuses an unresolved one before any statement

[objectstack-fleet]

Fixes #23558
Clause-②: yes (widening)

The grade is yes (widening) because this PR exports one resolver from @objectstack/metadata-core, dialectOfDriver, so the ceremony can share it. The claim graded the card no unless that export was added, and it was added. No existing export answered a driver's dialect.

What changed

os migrate organization-ownership (the plan and --apply) now reads its SQL dialect once, from the stack's driver, before either arm runs a statement. It uses the resolver that metadata-core's legacy-row reader uses: the driver's dialectName first, then a recognised config.client string.

Anything else is refused with driver-unsupported and exit 1, and no statement runs. That covers a client class with no recognised dialectName, an unrecognised client string, dialectName: 'unknown', and a driver with no dialect at all. The refusal names the driver: its name, its dialectName, and its client string or client class name.

• packages/metadata-core/src/legacy-organization-row.ts: dialectOfDriver is exported. Its behaviour is unchanged, and its doc comment says who shares it.
• packages/cli/src/utils/organization-ownership-plan.ts:
  • dialectOf, which read the client string only, is replaced by ceremonyDialectOf(driver). It calls the shared resolver and throws the refusal.
  • PlanReader carries the resolved dialect. client stays as the plan file's record, and only when it is a string.
  • The plan no longer derives a dialect itself, and its catalog statement is keyed on the resolved dialect.
• packages/cli/src/utils/organization-ownership-apply.ts: the dialect ?? 'sqlite' default is gone. The apply takes the executor's resolved dialect.
• packages/cli/src/commands/migrate/organization-ownership.ts:
  • Both arms call ceremonyDialectOf(stack.driver) right after the raw-seam check, before any statement. In --apply this is also before the ledger check.
  • The template lookup's dialectOf(executor.client) ?? 'sqlite' is gone.
• Changeset: @objectstack/cli patch, @objectstack/metadata-core minor.

Premise check against main (f7cd580bff)

• The card's harm does not happen on main. The card said "the ceremony would then build SQLite-dialect raw SQL against a PostgreSQL or MySQL database". It would not. Both arms run the plan step first, and the plan's dialectOf(String(client)) returned null for a client class (stringified) and for an unrecognised string. So the plan refused with driver-unsupported before any statement.
  • The apply's ?? 'sqlite' and the template lookup's ?? 'sqlite' were reached only after the plan had resolved the same client to a dialect, so neither ever applied.
  • What was live: the refusal printed a client class's whole source text as the driver's name, and three readers each kept their own copy of the resolution.
  • This PR still does what the card's Wanted lines ask: one shared resolver, a refusal naming the driver before any statement, and no SQLite default left.
• Hypothesis (a), falsified in part. resolvePlannedDriverExec reads no config.client; it only picks execute or raw. In that module the string-only read is readPhysicalTableNames, which belongs to os migrate plan's unmanaged-table sweep. The ceremony never calls it. It is left unchanged (see Acceptance notes).
• Hypothesis (b). metadata-core's dialectOfDriver / dialectOfName were not exported, and no exported entry in the repository answers a driver's dialect this way. That is why there is one export.
• Hypothesis (c). The refusal happens once, at the command, where the driver is first read. The utils take the resolved dialect.

No-regression guard: every in-repo driver, measured

Each driver was constructed through the shared datasource factory (createDefaultDatasourceDriverFactory) or the runtime's Turso factory, from the build of 0fc3ae2575. No driver package is touched by this PR. The main column is the command's own expression, dialectOf(String(config.client)).

driver path	name	dialectName	config.client	main	shared resolver
SqlDriver on better-sqlite3	com.objectstack.driver.sql	sqlite	'better-sqlite3'	sqlite	sqlite
SqliteWasmDriver	com.objectstack.driver.sqlite-wasm	sqlite	class Client_WasmSqlite2	refused	sqlite
SqlDriver on pg	com.objectstack.driver.sql	postgres	'pg'	postgres	postgres
SqlDriver on mysql2	com.objectstack.driver.sql	mysql	'mysql2'	mysql	mysql
TursoDriver, remote libsql://	com.objectstack.driver.turso	sqlite	'better-sqlite3'	sqlite	sqlite
TursoDriver, file:	com.objectstack.driver.turso	sqlite	'better-sqlite3'	sqlite	sqlite

Every driver that ran the ceremony before still runs it.

SqliteWasmDriver never reaches the resolver through the command today. It was measured through the CLI at 91084b5d5e: os migrate organization-ownership --database-url wasm-sqlite://FILE --json answers {"error":"plan_refused","reason":"driver-unsupported","detail":"no SQL driver with a raw-SQL seam is active"}. That is the same answer main gives. The schema boot's SQL-driver lookup does not include the service name that driver registers under, so stack.driver is null. This is reported as a finding and not fixed here.

The SQLite path was also run through the CLI at f9f69beda5: --database-url FILE (better-sqlite3) writes the plan, records "client": "better-sqlite3", and exits 0.

NOT MEASURED: a live PostgreSQL or MySQL run of the ceremony. Both shapes were measured on constructed drivers, and the command pins assert that each one's first statement is its own dialect's catalog read.

Tests

• packages/cli/src/commands/migrate/organization-ownership.dialect.test.ts (new, unit tier):
  • Five refused shapes, each in both arms: a client class with no dialectName; a client class as SqlDriver answers it (dialectName: 'unknown'); an unrecognised client string (oracledb); dialectName: 'unknown' beside pg; no dialectName and no client.
  • Each one checks: plan_refused / apply_refused, reason driver-unsupported, a detail that names the driver, exit 1, zero statements, no plan file, and the apply step never called.
  • A client class is named, and its source is never printed.
  • Six proceeding shapes: each in-repo driver's measured shape, plus a driver with only a recognised client string. Each one's first statement is its dialect's catalog read.
  • --apply hands the executor dialect, and client only when it is a string.
• packages/metadata-core/src/legacy-organization-row.test.ts: the exported dialectOfDriver, nine rows. dialectName first; a client string when there is no dialectName; 'unresolved' for a client class, an unknown string, and dialectName: 'unknown' beside pg; 'none' for no dialect and no driver.
• organization-ownership-plan.integration.test.ts: the oracledb refusal now pins that the dialect is refused before the plan issues any statement.
• The other readers and executors in the ceremony's tests (organization-ownership-apply.test.ts:60, ...served-catalog.integration.test.ts, ...host-supplement.integration.test.ts) gain dialect: 'sqlite'.

Runs on 107a7a923c, the final head, after merging main at edac2183c0, which brings in PR #23624's hunks in the same files. The merge was clean, and was followed by pnpm install --frozen-lockfile and a rebuild of the cli closure.

• @objectstack/cli unit project, by path (organization-ownership.dialect, unmanaged-tables, organization-ownership.apply-flags, organization-ownership-inventory): 4 files, 90 tests passed.
• @objectstack/cli integration project, by path (the plan, apply, served-catalog, host-supplement, column-drops, unmanaged-tables and meta-stored-legacy-organization suites, and the command's fate-supplement, occupancy and journal-mode suites): 10 files, 148 tests passed. This layer was run locally because the diff edits integration-tier files.
• pnpm --filter @objectstack/cli typecheck (tsc --noEmit and check:test-typecheck): exit 0.
• pnpm --filter @objectstack/metadata-core typecheck: exit 0. pnpm --filter @objectstack/metadata-core test: 18 files, 728 tests passed.
• pnpm --filter @objectstack/cli exec vitest run --project unit (the whole unit layer): 290 of 291 files and 4341 of 4342 tests passed. The one red was boot-preparation-parity.test.ts > every SERVE_ONLY entry is still used by serve.ts, a 5000 ms timeout (5160 ms) on a shared box while the gate battery ran beside it. The diff touches neither that file nor serve.ts. Re-run alone on the same head: 37 of 37 passed.

Ablation (one-off proofs, through scripts/ablation-replace.mjs with an EXIT INT TERM restore trap)

Both mutated subjects are packages/cli/src, resolved relatively, and metadata-core is aliased to src in the cli vitest config, so no dist/ is involved.

The SQLite fallback restored in ceremonyDialectOf, on 107a7a923c. The anchor if (… ) return dialect; was replaced with return … ? dialect : 'sqlite';. On disk: injected 1, anchor 0; blob 25cf4a26b487 became 476f0e239e7b.

• The command pins went 11 red / 8 green. Every refused shape went red in both arms, plus the class-naming pin. All proceeding pins stayed green.
• The plan integration suite went 1 red / 11 green: the oracledb pin.
• Restored: blob equals HEAD (25cf4a26b487) and git diff HEAD is empty. The same result held on 91084b5d5e.

Gates

Local, on 107a7a923c:

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 67 commands from the merge base edac2183c, with no stale-tree warning. All 67 were run, and each exit code was captured before any pipe: 67 of 67 exit 0.
• --ran reconciliation: "67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN", exit 0.
  • check:dual-build-cjs-loads, check:i18n, check:i18n-coverage and check:i18n-walk-parity need build output beyond the cli closure. They were measured after building their named prerequisite closures (the CLI, the examples, and the plugins and services they extract). On the pre-merge head they first answered exit 3 (PREREQUISITE NOT MET) and were re-run green.
• Ratchet families in that set: check:type-check-coverage and check:type-check-debt, exit 0.
• pnpm lint narrowed to the 10 changed .ts files: eslint --no-inline-config on them, exit 0, no output. The full repo scan is CI's Lint & Repo Gates.
• Control-byte self-scan of the changed files and the changeset: no hits.

Acceptance notes

• os migrate finds no SQL driver on a wasm-sqlite:// or *.wasm.db database. The schema boot looks a SQL driver up by SQL_DRIVER_SERVICES in packages/cli/src/utils/schema-migrate.ts (driver.com.objectstack.driver.sql, driver.com.objectstack.driver.turso, driver.sql). SqliteWasmDriver registers under none of them. So the ceremony refuses a SQLite database with "No SQL driver with a raw-SQL seam is active … The ceremony supports SQLite, PostgreSQL and MySQL." This was measured through the CLI (above). It is reported to the seat as a finding and is not fixed here, because schema-migrate.ts is outside this claim.
• os migrate plan's unmanaged-table sweep still reads config.client as a string only (readPhysicalTableNames, packages/cli/src/utils/unmanaged-tables.ts). It is the only remaining string-only reader in the cli. It has no reach today: its drivers come from the same lookup, which never plans SqliteWasmDriver. Carrier: none.
• packages/runtime/src/organization-ownership-boot-guard.ts keeps a third copy of the resolver. In that copy, an unrecognised dialectName falls through to the client string. No in-repo driver reaches the difference: SqlDriver answers 'unknown' only for a client that the same three spelling sets do not recognise. Carrier: none.
• Unchanged: organization-ownership-plan.ts:181, organization-ownership-grants.ts, and the apply test's :1979, which belong to PR fix(plugin-security,spec): the grant remedy texts name the reviewed-plan ceremony; C7b wording follow-ups in cli, plugin-auth and the durability vocabularies (#23513) #23624; and packages/drivers/**.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, @objectstack/metadata-core, touching 12 documentable anchor(s).

16 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json a647783d46a69775a97ea57c2d1a54dae1b7333e.

⛔ 8 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 31 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json a647783d46a69775a97ea57c2d1a54dae1b7333e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1178dce5aa16eb839f7ffacc8bb8213a9b91816d — the merge of head 107a7a923cd473f50016cee23ea47111bdcaa5ec into base a647783d46a69775a97ea57c2d1a54dae1b7333e, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1178dce5aa16eb839f7ffacc8bb8213a9b91816d && git checkout 1178dce5aa16eb839f7ffacc8bb8213a9b91816d
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a647783d46a69775a97ea57c2d1a54dae1b7333e 107a7a923cd473f50016cee23ea47111bdcaa5ec && git checkout -B drift-repro a647783d46a69775a97ea57c2d1a54dae1b7333e && git merge --no-ff 107a7a923cd473f50016cee23ea47111bdcaa5ec

node scripts/docs-audit/affected-docs.mjs --json a647783d46a69775a97ea57c2d1a54dae1b7333e

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs a647783d46a69775a97ea57c2d1a54dae1b7333e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 107a7a923cd473f50016cee23ea47111bdcaa5ec
Local-runs: none

The review is owed by the Clause-②: yes (widening) line alone (the declaration face). There is no packages/spec/src/** path and no governed path (check-governed-merges --pr 23647: NOT governed), so this seat writes it itself. It rests on the PR's 11-file diff against its merge base, card #23558 with all its comments, and the 40 check-runs on this head (34 success, 6 roster skips). Nothing was built or run.

① Derived judgments

• Public surface: one widening, right. @objectstack/metadata-core now exports dialectOfDriver(driver) through its barrel (src/index.ts:120, export * from './legacy-organization-row.js').
  • The signature is (driver: { dialectName?: unknown; config?: { client?: unknown } } | null | undefined) => 'sqlite' | 'postgres' | 'mysql' | 'none' | 'unresolved'.
  • Its body is the pre-existing private resolver, unchanged: a dialectName string is the whole answer, and config.client is read only when there is no dialectName, and only as a string. readLegacyOrganizationRows keeps calling it.
  • type Dialect stays module-private and is emitted in place.
  • No other export moves.
• CLI accept set: no narrowing, right.
  • On main the ceremony's plan step already refused, with driver-unsupported and exit 1, every shape this PR refuses: a stringified client class, an unrecognised client string, and dialectName: 'unknown'. The plan runs first in both arms (dev readings, quoted in the changeset's FROM).
  • The apply's and the template lookup's ?? 'sqlite' defaults were unreachable behind that refusal. Removing them changes no answer.
  • The one visible change is the refusal's text: it names the driver (name, dialectName, and client string or class name) instead of printing a class's source.
• No-regression guard (the claim's condition): measured on constructed drivers. SqlDriver on better-sqlite3, pg and mysql2, and TursoDriver (remote and file) each resolve to the dialect they did before.
  • SqliteWasmDriver would now resolve to sqlite, but the ceremony's boot never hands it over (findSqlDriver, unchanged). That is filed separately as cli: os migrate organization-ownership refuses a SQLite database served by SqliteWasmDriver ("no SQL driver with a raw-SQL seam is active"): findSqlDriver's SQL_DRIVER_SERVICES omits com.objectstack.driver.sqlite-wasm #23648.
• Pins:
  • organization-ownership.dialect.test.ts (new): every refused shape in both arms, the class-naming pin, and the proceeding dialects.
  • The plan integration suite, including an oracledb refusal.
  • The ablation (the SQLite fallback put back in ceremonyDialectOf) turned 11 command pins and 1 plan pin red. The restore was proven against HEAD.

② Semver level

• @objectstack/metadata-core minor: an additive export. Right.
• @objectstack/cli patch: no flag, exit-code or JSON-shape change, only refusal wording and internal plumbing. Right.
• The plan file's client field is now written only when the client is a string. A stringified class was never a usable value, so no reader loses information.
• The changeset's Clause-②: yes (widening) and the PR body's line 2 agree with the diff. No ADR-0087 marker is owed: nothing is removed or narrowed.

③ Boundary flags

• premise_still_valid: false, as reported: the card's harm (SQLite SQL against PG or MySQL) does not happen on main. What survives is the card's Wanted lines, and those are delivered: one shared resolver, a refusal naming the driver before any statement, and the three refusal pins.
• Open questions: none.
• Out-of-scope findings:
  • the wasm-sqlite ceremony refusal, filed as cli: os migrate organization-ownership refuses a SQLite database served by SqliteWasmDriver ("no SQL driver with a raw-SQL seam is active"): findSqlDriver's SQL_DRIVER_SERVICES omits com.objectstack.driver.sqlite-wasm #23648;
  • readPhysicalTableNames' string-only read, which has no reach (承接者:无, in the PR's Acceptance notes);
  • the runtime boot guard's third resolver, which no in-repo driver reaches (承接者:无).
• Deviations:
  • The in-place fix of readPhysicalTableNames was committed and then reverted for lack of reach. The final diff does not touch unmanaged-tables.ts.
  • origin/main was merged cleanly, bringing PR fix(plugin-security,spec): the grant remedy texts name the reviewed-plan ceremony; C7b wording follow-ups in cli, plugin-auth and the durability vocabularies (#23513) #23624's hunks.
  • Lint was narrowed; CI's Lint · ESLint is green.

Implemented-by: claude/issue-23558-ceremony-dialect-resolver
Reviewed-by: session_01Q9PZ5Pzqcus4woVvTZwWNU

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

席位核对

✅ ACCEPT: PR #23647 at 107a7a923c (#23558). Every check on this head is green or a roster skip; the TIER_DEFAULT record 6189556846 is PASS on this head · 2026-10-15T10:06Z

domain:cli seat 2 (#22648) · sunhaolin · session session_01Q9PZ5Pzqcus4woVvTZwWNU · holder of claim 6187405745. Report: os-dev-report 6189072331 on #23558.

Checklist, read against GitHub and origin/main, not against the report:

• PR shape: draft, base main, title fix(cli):, assignee sunhaolin. Line 1 is Fixes #23558, the body's only closing keyword. Line 2 is Clause-②: yes (widening).
• Scope: 11 files, +371 / −34, inside the claim's surface:
  • the command's two arms and its :622 reader;
  • organization-ownership-plan.ts (ceremonyDialectOf; ⛔ not :181);
  • organization-ownership-apply.ts (the ?? 'sqlite' default removed);
  • metadata-core's one export;
  • the pins and one changeset.
  • unmanaged-tables.ts is untouched in the final diff.
  • check-governed-merges --pr 23647: NOT governed. Merge-tree is clean against origin/main.
• The fix, read in the diff: the dialect is read once, from the stack's driver, before either arm runs a statement, through dialectOfDriver.
  • An unresolved dialect is refused (driver-unsupported, exit 1), naming the driver.
  • PlanReader and ApplyExecutor carry the resolved dialect, and no 'sqlite' default remains.
• The claim's no-regression guard: measured, and it holds. Every in-repo SQL driver resolves as before, and SqliteWasmDriver never reaches the ceremony (cli: os migrate organization-ownership refuses a SQLite database served by SqliteWasmDriver ("no SQL driver with a raw-SQL seam is active"): findSqlDriver's SQL_DRIVER_SERVICES omits com.objectstack.driver.sqlite-wasm #23648).
• The contract review: TIER_DEFAULT record 6189556846, PASS, written by this seat for the declaration face, on this head. Its judgments: one additive export, no accept-set narrowing, minor / patch correct.
• Changeset prose, sentence by sentence:
  • @objectstack/cli patch and @objectstack/metadata-core minor, fix(cli):, Clause-②: yes (widening).
  • The FROM states truthfully that the old run was already refused (class source text in the message, unreachable defaults).
  • The TO states the refused shapes, the naming, and the client-field change.
  • The metadata-core paragraph matches the export's docblock.
• Gates:
  • Local, at 107a7a923c: 67 derived, 67 run, all exit 0.
    • cli by path: 4 unit files with 90 tests, and 10 integration files with 148 tests.
    • The cli unit layer: 4,341 of 4,342. The one red was a contended 5 s timeout in an untouched file, green alone at 37/37.
    • metadata-core: 728 tests. Both typechecks exit 0.
  • Gate evidence: the check-runs pinned to 107a7a923c, read at this stamp. 40 distinct checks: 34 success, including Lint & Repo Gates, TypeScript Type Check, Test Core 1-6 and Build Core, and 6 roster skips. Nothing is running and nothing failed.

Accepted:

• premise_still_valid: false. The card's harm does not happen on main, and its surviving Wanted lines are delivered.
• The reverted in-place sweep fix.
• The narrowed lint.

Filed from this report: #23648 (os migrate organization-ownership refuses a SQLite database served by SqliteWasmDriver). The two Acceptance-note readers have no reach.

Landing: pr_ready + automerge_enable through the relay, in this act.

---

Generated by Claude Code