fix(runtime): the SQLite file-path refusal names what the operator can change

[objectstack-fleet]

Fixes #23898

Clause-②: no

What changes

sqliteFilenameFromUrl in packages/runtime/src/standalone-stack.ts raises the refusal "KIND driver was selected but the URL does not look like a file path (WHY)." Both hosts print it: the standalone host tags it [StandaloneStack], and the CLI's legacy os serve path prints it untagged as the fatal UnsupportedDriverError. The first clause is unchanged, and so are the rule, the set of refused inputs, the error class, the exit and the scheme-only naming. Only the advice after the first clause changes.

arm	before	after
its scheme is "SCHEME"	Use file:/path/to/db.sqlite, or set OS_DATABASE_DRIVER explicitly.	Use file:/path/to/db.sqlite to keep the KIND driver, or use a driver that matches the URL: unset the driver selection (OS_DATABASE_DRIVER, --database-driver or the databaseDriver option) so the URL selects it, or set the selection to the URL's driver.
it names no file after "file:"	Use file:/path/to/db.sqlite, or set OS_DATABASE_DRIVER explicitly.	Name the file after "file:", as in file:/path/to/db.sqlite.

Why each arm gets its own remedy. The card says this refusal reaches an operator "only under an explicit sqlite / sqlite-wasm selection". I measured that on the public door, and it holds for the scheme arm but not for the empty-file: arm. OS_DATABASE_URL=file: os serve --dev, with no driver selected, gets the empty-file: refusal on both hosts (table below). A file: URL selects the sqlite kind on its own, so any driver advice on that arm would send the operator around a loop: unsetting the selection hands the URL straight back to sqlite. On that arm the remedy names the file and nothing else. On the scheme arm it carries both options the card's Done-looks-like names. The selection doors are listed and none is assumed, because the kind may have come from OS_DATABASE_DRIVER (which --database-driver sets), from the databaseDriver option, or from the URL.

CLI host. It holds no copy of the sentence. sqliteFileFor in packages/cli/src/utils/storage-driver.ts re-raises the runtime's message with the tag stripped, so the CLI is not edited. driver-vocabulary-parity.test.ts still holds the two hosts equal (green, below). Its rows carry the WHY fragment, and the whole sentence is held by derivation (toBe(sentence.replace(...))) rather than by a literal sentence row, so no remedy row was added there.

Public door, base fd0e72abc vs head 012b45095

Each case ran from a fresh directory outside the repo with node packages/cli/bin/run.js serve --dev. The standalone host cases used a minimal objectstack.config.ts. The CLI host cases set OS_MODE=off and used a config that declares one object, because the legacy path resolves storage only for a stack that declares objects. Every case exited 1. PLACEHOLDER appeared 0 times in every output, and no directory was created in the case directory on either tree.

case	base: first error line, after the first clause	head: the same
standalone, OS_DATABASE_DRIVER=sqlite, jdbc:postgresql://127.0.0.1:5999/db	(its scheme is "jdbc:"). Use file:/path/to/db.sqlite, or set OS_DATABASE_DRIVER explicitly.	(its scheme is "jdbc:"). Use file:/path/to/db.sqlite to keep the sqlite driver, or use a driver that matches the URL: unset ... or set the selection to the URL's driver.
standalone, OS_DATABASE_DRIVER=sqlite-wasm, postgres://PLACEHOLDER-USER:PLACEHOLDER-SECRET@127.0.0.1:5999/db	(its scheme is "postgres://"). Use file:/path/to/db.sqlite, or set OS_DATABASE_DRIVER explicitly.	(its scheme is "postgres://"). Use file:/path/to/db.sqlite to keep the sqlite-wasm driver, or use a driver that matches the URL: ...
CLI legacy (OS_MODE=off), the same two	the same, untagged	the same new remedy, untagged
standalone and CLI legacy, no selection, OS_DATABASE_URL=file:	(it names no file after "file:"). Use file:/path/to/db.sqlite, or set OS_DATABASE_DRIVER explicitly.	(it names no file after "file:"). Name the file after "file:", as in file:/path/to/db.sqlite.

Following the new remedy's unset leg for the card's own URL (OS_DATABASE_URL=jdbc:postgresql://127.0.0.1:5999/db, no driver) on head exits 1 with [StandaloneStack] Unsupported database URL scheme "jdbc:". Supported schemes: postgres://, pg://, .... So the next refusal names the drivers that exist.

Tests (head 012b45095)

• pnpm --filter @objectstack/runtime exec vitest run --project local --maxWorkers=2: exit 0, Test Files 404 passed (404), Tests 6157 passed | 19 skipped (6176).
• pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 src/utils/driver-vocabulary-parity.test.ts src/utils/storage-driver.test.ts: exit 0, Test Files 2 passed (2), Tests 204 passed (204). @objectstack/runtime resolves to its dist/ there, which was rebuilt at head first (grep -c 'unset the driver selection' gives 1 in both dist/index.js and dist/index.cjs).
• pnpm --filter @objectstack/runtime typecheck: exit 0. pnpm --filter @objectstack/cli typecheck: exit 0. The runtime's tsconfig.json excludes tests. The changed test compiles in the test layer (check:test-typecheck OK), and it is not in test-typecheck-debt.json.
• New rows in standalone-stack-explicit-sqlite-non-file-refusal.test.ts (98 tests in the file, 18 of them new):
  • the scheme arm under both kinds, both doors and two URLs, plus the exported rule;
  • the empty-file: arm via file: and FILE:, with no selection (the databaseUrl option and OS_DATABASE_URL) and with an explicit sqlite selection (both doors).
  • Each row reads the remedy only after checking that the message opens with the unchanged first clause.

Ablation (one-off, no permanent file)

The fix was committed first. node scripts/ablation-replace.mjs wrote the old remedy back into standalone-stack.ts:

• anchor hit 1 time, count 1 to 0; the replacement marker went 0 to 1;
• blob 6ddd65e0af79 to 9d5038cced7e;
• on-disk counts during the run: marker 1, new remedy 0.

The suite imports ./standalone-stack.js relatively, so it reads src/ and no rebuild leg was needed. Result: Tests 18 failed | 80 passed (98). The 18 red rows are exactly the new remedy rows, and the 80 first-clause, credential and control rows stayed green. Restore: blob after restore equals HEAD (6ddd65e0af79), and git diff HEAD is empty.

Gates (head 012b45095)

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 62 commands from merge base 9e797a897. All 62 ran locally, each exit recorded before any pipe.
• --ran reconciliation: exit 0, 62 derived famil(ies) accounted for — 60 run, 2 NOT-MEASURED.
• 60 exited 0.
• NOT MEASURED locally, pnpm check:dual-build-cjs-loads (exit 3, PREREQUISITE NOT MET): it reads built output from packages outside this diff's closure that this checkout has not built. CI runs it on a full build.
• NOT MEASURED locally, pnpm check:type-check-debt (exit 3): its own build leg timed out waiting for the shared verify lock. CI runs it.
• pnpm exec eslint --no-inline-config packages/runtime/src/standalone-stack.ts packages/runtime/src/standalone-stack-explicit-sqlite-non-file-refusal.test.ts: exit 0, 0 errors and 0 warnings on each file, and neither was ignored. The repo-wide lint run is the PR's Lint & Repo Gates check-run.

Acceptance notes

• Observation, not filed: the scheme arm is also reachable with no selection. A file: (or sqlite:, or wasm-sqlite://) prefix that wraps a SCHEME:// value reaches it. Measured on both trees: OS_DATABASE_URL=file:postgres://PLACEHOLDER-USER:PLACEHOLDER-SECRET@127.0.0.1:5999/db gets (its scheme is "postgres://"), with the credentials absent. There the new remedy's first option (a file: path) is the fix, and its "unset the driver selection" leg does nothing because nothing was selected. No sentence is false, so this is an observation, not a defect. Carrier: none.
• The pending .changeset/23863-explicit-sqlite-non-file-refusal.md quotes the old remedy in its "After" sentence. That changeset and this one are both pending, so they ship in the same release, and this changeset's FROM/TO supersedes the quote. It is outside this card's file surface and was not edited.
• content/, skills/ and docs/ quote neither the first clause nor the remedy (git grep count 0 at head). The positive control is the same grep over packages/, which hits.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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 — 26 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 2b274600b1361b6a39b078e965443ddb3ddace79 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 42cbe84538688b049270067d329893b8131e36f4 — the merge of head 012b450951aed6e81e1011d70ca7a29fe722dd0f into base 2b274600b1361b6a39b078e965443ddb3ddace79, 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 42cbe84538688b049270067d329893b8131e36f4 && git checkout 42cbe84538688b049270067d329893b8131e36f4
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2b274600b1361b6a39b078e965443ddb3ddace79 012b450951aed6e81e1011d70ca7a29fe722dd0f && git checkout -B drift-repro 2b274600b1361b6a39b078e965443ddb3ddace79 && git merge --no-ff 012b450951aed6e81e1011d70ca7a29fe722dd0f

node scripts/docs-audit/affected-docs.mjs --json 2b274600b1361b6a39b078e965443ddb3ddace79

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

[objectstack-fleet]

席位核对

ACCEPT · #23898 · domain:cli seat 2 · os-tesla · session session_018t6a5rvqPRvEDMCVVW9kYT · 2026-10-16T20:53Z · reviewed head 012b450951aed6e81e1011d70ca7a29fe722dd0f, against GitHub and the branch, not against the report's prose. Holder of claim 6222932269; report on #23898.

1. Shape.
   • Draft, base main, assignee os-tesla. Line 1 is Fixes #23898; Clause-②: no is in the body and the changeset.
   • 3 files, +101 / −1.
   • check-governed-merges --pr 24039: NOT governed; 102 changed lines.
   • git merge-tree is clean against origin/main b74434c58.
2. The change, read by this seat.
   • sqliteFilenameFromUrl's rule and its first clause ("${kind} driver was selected but the URL does not look like a file path (${why}).") are unchanged. Only the remedy after it changes, and it still names the scheme only, never the URL.
   • The scheme arm names both options the card asks for: keep the kind with a file: path, or use a driver that matches the URL (unset the selection, OS_DATABASE_DRIVER / --database-driver / databaseDriver, so the URL selects it, or set the selection to the URL's driver).
   • The empty-file: arm names the file only. The dev measured, on both hosts, that it is reached with no driver selected (OS_DATABASE_URL=file:), so driver advice there would loop. That is right, and it stays inside the claimed surface (the sentence only).
   • The CLI holds no copy: storage-driver.ts sqliteFileFor re-raises the runtime's message, so both hosts print one sentence, and driver-vocabulary-parity.test.ts stays green by identity.
3. Review of record: this record. A refusal's wording has no contract face: the same URLs are refused, with the same error class and exit.
4. Changeset: one, '@objectstack/runtime': patch, with FROM / TO for both arms.
5. Gates, pinned to the head. Check-runs on 012b450951 read at this stamp, latest run per name: 40 names, 34 success, 6 skipped, 0 failure, nothing running.
   • The successes include Build Core, Test Core 1–6/6, TypeScript Type Check, Lint & Repo Gates, Check Changeset and Governed Surface Queue Guard.
   • The 6 skips are roster names.
   • The dev's local subset: 61 of 62 derived commands exit 0. check:dual-build-cjs-loads is NOT MEASURED locally (exit 3), and CI covers it. check:type-check-debt exited 3 on a lock timeout, then 0 on a re-run at this head; the PR body still records the first reading.
   • Runtime: 404 files, 6157 passed. The CLI's parity and storage-driver tests: 204 passed. The new remedy rows: 18, all red under the old text by ablation, while the first-clause, credential and control rows stay green.
   • At the public door, base against head, on both hosts: every case exits 1, prints no credentials and creates no directory.
6. Accepted deviations: the remedy is split per arm (above); the main merge (3 commits, no overlap).

Noted, not filed (the dev's, as 承接者:无): a file:-prefixed SCHEME:// value reaches the scheme arm with no selection, where the file: option is the fix. The pending .changeset/23863-… quotes the old remedy; both ship in the same release, and this card's FROM/TO supersedes it.

Landing: pr_ready + automerge_enable through the relay, in this act. The card closes on the merge (Fixes).

---

Generated by Claude Code