fix(driver-turso)!: refuse a remote url beside syncUrl, and any replica not on a local file, instead of running on :memory:

[objectstack-fleet]

Fixes #19893

Clause-②: no (narrowing)

What was wrong

TursoDriver.detectMode classified a remote url (libsql://, https://, http://, wss://, ws://) beside syncUrl as replica. The last arm of toKnexConfig then handed that mode's local engine (Knex + better-sqlite3) :memory:. Every write read back, then vanished on restart, and nothing reached the remote. The code comment saying @libsql/client "operates in embedded replica mode with an in-memory local cache" was false.

What this changes

• The constructor refuses these configurations before super(), beside the two existing timeout refusals and with the same envelope (VALIDATION_ERROR / 400):
  • a remote url in a local or replica mode: auto-detected through syncUrl (the card), or forced with mode: 'replica' / mode: 'local';
  • a replica whose url is not a local file: path: :memory:, file::memory:, or a bare path under a forced mode: 'replica'.
• The message names the scheme it met and both ways out: drop syncUrl (or the forced mode) for a remote database, or use url: 'file:./data/replica.db' beside syncUrl for an embedded replica. It never echoes the url, which may carry a live ?authToken= (pinned).
• detectMode returns the same answers as before: the pair still classifies replica, and the refusal is a construction check, not a re-classification (pinned). It now shares one remote-prefix list with the refusal, and the false comment is replaced with the measured reading.
• README: a paragraph under the auto-detection table, plus a correction to the syncUrl config comment. The mode table never listed the pair.
• Test fixtures: replica-face fixtures that rode :memory: + syncUrl now get a fresh local file per driver (replica-file.testkit.ts), keeping the per-test isolation :memory: gave them. Two tests pinned the defect itself and were replaced (see Acceptance notes).

In-place fold, named per the bounded in-place fix rule. A forced mode: 'local' beside a remote url is not the card's arm, but it reaches the identical toKnexConfig last arm (measured below: 1 row back, 0 after restart). It is the same defect class, caught by the same predicate (the classifier's own remote-prefix list), in the same file, under the same gates. So it is folded into the one guard rather than filed.

Deliberately NOT changed. A url with no mode that is none of file:, :memory: or a lowercase remote scheme, such as an uppercase LIBSQL:// or a bare path, still auto-detects local and still runs on :memory:. That fall-through is recorded at ridesWebSocketTransport as deliberately left alone, and turso-driver-uppercase-ws-scheme-timeout-refusal.test.ts (CONTROL 1) pins it as constructing. Changing it needs its own decision, so it goes back to the seat as a separate finding. planMediaColumnMove and the remote media-column paths are untouched; #19894 remains open.

Measurements, BASE 2c1011b01b

A throwaway probe (not committed) ran initObjects, create and find, then built a fresh driver on the same config (a restart):

configuration	mode	knex engine	rows back	rows after restart
libsql:// + syncUrl + client stub, sync.onConnect: false (the card's repro)	replica	:memory:	1 (the stub held no tables)	0
libsql:// / https:// / wss:// + syncUrl, real client, onConnect: false	replica	:memory:	1	0
libsql:// + syncUrl, real client, default sync	replica	:memory:	connect() rejects SYNC_NOT_SUPPORTED	n/a
libsql:// + mode: 'replica', no syncUrl	replica	:memory:	1	0
libsql:// + mode: 'local'	local	:memory:	1	0
:memory: + syncUrl, real client, default sync	replica	:memory:	connect() rejects URL_INVALID	n/a
:memory: + syncUrl + client stub, onConnect: false	replica	:memory:	1 (the stub held no tables)	0
uppercase LIBSQL://, no mode (not changed here)	local	:memory:	1	0
bare path, no mode (not changed here)	local	:memory:	1; the file was never created	0
CONTROL file: + syncUrl + client stub	replica	the file	1	1
CONTROL file: local	local	the file	1	1

Why @libsql/client@0.17.4 builds no replica here.

• lib-esm/node.js _createClient routes wss/ws to its WebSocket client and https/http to its HTTP client; only anything else reaches sqlite3.js.
• syncUrl is read only in lib-esm/sqlite3.js. A syncUrl grep over http.js and ws.js returns 0; the control grep for authToken returns 6 in each.
• http.js / ws.js sync(): throw new LibsqlError("sync not supported in http mode", "SYNC_NOT_SUPPORTED"), and the ws variant is the same.
• sqlite3.js: if (isInMemory && config.syncUrl) throw new LibsqlError("Embedded replica must use file for local db but URI with in-memory mode were provided instead: …", "URL_INVALID").

Where the config is parsed. Neither factory parses a schema: packages/runtime/src/turso-driver-factory.ts and packages/services/service-datasource/src/default-datasource-driver-factory.ts both go buildTursoDriverConfig then new TursoDriver. So this constructor is the runtime's only gate. The spec-lane TursoConfigSchema is parsed at authoring and wizard time through validateDriverConfig. The driver-local copy has no in-repo parse caller outside its own test. The matching authoring-time refinement is outside this PR's surface (packages/spec untouched) and is handed to the seat.

Verification, HEAD 5fb95579

• pnpm --filter @objectstack/driver-turso typecheck: tsc --noEmit, exit 0. The program covers all 60 test files, including the new pin and testkit (counted with --listFiles).
• pnpm --filter @objectstack/driver-turso test: Test Files 60 passed (60), Tests 1358 passed (1358).
• New pin turso-driver-remote-url-replica-refusal.test.ts, 27 cases:
  • 19 refusal cases assert the envelope (code + status), plus named subjects in the message (the keys, the scheme, url: 'file:) and the absence of an echoed token/host;
  • 8 preservation cases: a file: replica that connects, writes and keeps its row across a restart; the file: / :memory: local and remote faces; detectMode unchanged.
• Reverse verification, direction predicted before running. With the constructor's guard call deleted (scripts/ablation-replace.mjs, anchor hit 1 to 0, blob 07363cdb to 5ee02e4e):
  • Tests 20 failed | 105 passed: all 19 refusal cases plus the converted turso-driver.test.ts case went red, each at "expected the constructor to refuse, and it returned a driver";
  • all 8 preservation cases stayed green;
  • restore proven: blob equals HEAD (07363cdb) and git diff HEAD is empty. The subject resolves from src (relative imports), so no dist leg applies.
• pnpm check:driver-conformance: before OK — 50 covered cell(s), 0 in the DEBT ledger, 0 exempt.; after the same.
• Changeset gates:
  • check-adr-0087-registration: 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition., with this changeset classified [BREAKING+bang+clause-②-narrowing] not-required (no-migration-prescription);
  • check-changeset-no-major: This diff introduces no major bump.;
  • check-empty-changeset: green.
• Gates: dispatch-gates --commands on the real diff derived 61 commands; --ran reconciles 61 derived, 59 run, 2 NOT-MEASURED, 0 UNRUN, and all 59 run exit 0. The four artifact-roster gates whose roster sits under a touched directory were also run, all exit 0.
• NOT MEASURED (both PREREQUISITE NOT MET, needing a whole-workspace build):
  • check:dual-build-cjs-loads. Narrowed stand-in: the built driver-turso CJS and ESM entries both load TursoDriver;
  • check:type-check-debt. Narrowed stand-in: driver-turso has no DEBT, TEST_DEBT or test-typecheck-debt entry, and its tsc --noEmit is clean. CI runs both over the whole tree.
• Lint, narrowed and proven.
  • Population, read from eslint itself: of the 14 changed paths it lints the 12 .ts files and ignores the 2 .md.
  • Count, from --format json: 12 files, 0 errors, 0 warnings.
  • Invariance: eslint.config.mjs never enables type-aware linting (no parserOptions.project, no typed rules; its own header says so), so this diff cannot move any untouched file's verdict.
  • Full pnpm lint is CI's.

Acceptance notes

• Replaced pins:
  • turso-driver.test.ts "should accept remote URL when syncUrl is provided" pinned the defect and now asserts the refusal;
  • its two "detect replica mode" cases for :memory: / libsql:// + syncUrl now pin TursoDriver.detectMode (unchanged) instead of constructing;
  • turso-driver-ws-timeout-refusal.test.ts built a wss:// + syncUrl replica (the card's pair). That half is removed and its successor lives in the new pin file.
• Loader fixtures outside this package still pair url: 'libsql://my-db.turso.io' with syncUrl and mode: 'replica': packages/cli/src/utils/storage-driver.test.ts ("produces a config the real driver accepts"), packages/runtime/src/turso-driver-factory.convergence.test.ts and packages/services/service-datasource/src/__tests__/turso-driver-config.test.ts. They exercise the key-forwarding builder or a capturing constructor, never the real driver, so they stay green. The first title now overstates what the real driver accepts. They are outside this card's file surface; there is no carrier.
• Not measured: whether writes on a file: + syncUrl replica reach the remote primary. Knex writes the file through better-sqlite3, not through the libsql connection. Measuring it needs a live sqld.
• Reach, for the seat's grading:
  • in-repo, no example, template, published skill, hand-written doc or factory default declares a remote url beside syncUrl; the host boot path (OS_DATABASE_URL) passes none;
  • with the driver's own client and the default sync.onConnect, the card's pair failed at connect() rather than silently; silent loss needed sync.onConnect: false, a supplied client, or a forced mode;
  • out-of-repo deployments are not measured.

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-turso, touching 13 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/drivers/driver-turso/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17/17-4.mdx (via TursoDriverConfig (symbol, a top-level interface))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/drivers/driver-turso/README.md) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 — 6 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 2c1011b01bc071c545f72f2761647b8d9ab56375 → packageMentionDocs.

Which tree this was computed on

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

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

⚠️ 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 2c1011b01bc071c545f72f2761647b8d9ab56375 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5fb95579ee5271ee45ecad3e08809db249e9dc90

① Derived judgments

1. A remote url (libsql://, https://, http://, wss://, ws://) beside syncUrl, with no mode, is now refused at construction; before, it constructed as replica on Knex :memory:. RIGHT: the constructor calls localEngineDefect, which returns 'remote-url' via hasRemotePrefix, then refuseNonDurableLocalEngine. A probe refuses all five schemes; pinned in turso-driver-remote-url-replica-refusal.test.ts.
2. A remote url with a forced mode: 'replica' is refused. RIGHT: same predicate; pinned.
3. A remote url with a forced mode: 'local' is refused (the in-place fold). RIGHT: same predicate and the same toKnexConfig last arm; pinned.
4. A replica on :memory:, file::memory: or file::memory:?… beside syncUrl is refused ('replica-without-file'). RIGHT: namesInMemoryDatabase mirrors @libsql/core@0.17.4 isInMemoryConfig; pinned.
5. A non-file: url (bare path) under a forced mode: 'replica' is refused. RIGHT: !url.startsWith('file:'); pinned.
6. Still accepted, unchanged: file: + syncUrl (replica), a file: or :memory: local database, a remote url alone, a remote url with mode: 'remote'. RIGHT: 8 preservation cases, including a file: replica that keeps its row across a restart.
7. Still silently accepted onto Knex :memory:: a bare path or an uppercase scheme with no mode, with or without syncUrl. RIGHT as the PR body states it; WRONG as the changeset states it (③-1).
8. The refusal fires before any Knex or libsql client exists. RIGHT: in the constructor, detectMode runs, then the new guard, then the two timeout refusals, then toKnexConfig and super.
9. The refusal envelope is code: 'VALIDATION_ERROR', status: 400, identical to the two existing timeout refusals. RIGHT.
10. The message withholds the url and any token, naming only the scheme. RIGHT: pinned with an ?authToken= url.
11. detectMode's answers are unchanged. RIGHT: the same five prefixes behind hasRemotePrefix, still case-sensitive; pinned.
12. Published surface: nothing added or removed. RIGHT: exports, src/index.ts and tsup.config.ts are untouched; the new helpers are module-private.
13. Both loaders reach the refusal through the same constructor, with no schema parse in between. RIGHT: turso-driver-factory.ts and default-datasource-driver-factory.ts both run buildTursoDriverConfig, then new TursoDriver.
14. No test pins the defect any more; every refusal test asserts code + status. RIGHT.

② Semver level

Consistent: minor, a ! title, a BREAKING banner and Clause-②: no (narrowing) in the changeset, and the PR body line now matches. The ADR-0087 disposition not-required (no-migration-prescription) holds, because nothing an author writes is renamed or removed. Precedent in this package's CHANGELOG is the timeout and uppercase-scheme refusals. At the reviewer's final poll all seven required contexts were success, and both Check Changeset runs were green.

③ Boundary flags

1. FALSE, changeset refusal bullet 3: "a replica (syncUrl, or mode: 'replica') whose url is not a local file: path". Measured against the head: { url: './data/replica.db', syncUrl } and { url: 'LIBSQL://r.turso.io', syncUrl } both CONSTRUCT, classified local, on Knex :memory:. The replica arm of localEngineDefect fires only when mode === 'replica'. The PR body states this correctly; the changeset, which ships as CHANGELOG text, does not.
2. IMPRECISE, changeset headline: "a local or replica TursoDriver whose engine would have nothing durable behind it is refused". A local driver on a bare path or an uppercase scheme has nothing durable behind it and is not refused. Same root as ③-1.
3. IMPRECISE, README: "and a replica whose url is not a local file: path". This reads true only if "replica" means the detected mode. One clause of precision; not a FAIL on its own.
4. TRUE: every other changeset and README sentence, checked against the code and the @libsql/client@0.17.4 tarball (routing, syncUrl read only in sqlite3.js, SYNC_NOT_SUPPORTED, URL_INVALID, the envelope, the loaders, the blast-radius sentence).
5. Dev open question (the Clause-② line): resolved by the body amendment to no (narrowing).
6. Dev deviations: folding a forced mode: 'local' beside a remote url is legitimate: same predicate, file, arm and envelope, and pinned. The testkit is not published.
7. Dev out-of-scope findings: all REAL. The spec refinement and the mode: 'remote' inert syncUrl are filed as spec: TursoConfigSchema accepts turso configs the driver refuses or ignores — a remote url beside syncUrl or a forced replica/local mode, a non-file: replica, syncUrl/sync under mode: remote #19977. The bare path / uppercase fall-through is filed as driver-turso: a url whose scheme the classifier does not recognise (an uppercase LIBSQL://, a bare path) and no mode falls through to local on a :memory: Knex engine, so every write is lost on restart #19976. The loader-fixture title is noted only. The replica write path to the primary is NOT MEASURED.

Implemented-by: claude/issue-19893-turso-remote-syncurl-replica
Reviewed-by: session_01Bvd69VPa6puiNzzPUroDBx

VERDICT: FAIL

Edits that make it PASS, all prose (no code change is required; the refused set the code implements is the one the PR body describes):

1. In .changeset/19893-turso-remote-url-replica-refusal.md, rewrite refusal bullet 3 to name what is refused. That is a replica on an in-memory url (:memory: or file::memory:, beside syncUrl or under mode: 'replica'), and, under a forced mode: 'replica' only, any url that is not a local file: path.
2. In the "What stays accepted" paragraph, say that a url with no mode that is none of file:, :memory: or a lowercase remote scheme (an uppercase LIBSQL://, or a bare path) still auto-detects 'local' and still runs on :memory:, with or without syncUrl, unchanged here.
3. Narrow the headline to what is refused: a local or replica driver on a remote url, or a replica off a local file.
4. Optional: in packages/drivers/driver-turso/README.md, qualify "a replica" as auto-detected from file: or forced with mode: 'replica'.

Isolated reviewer: a separate contract-review-tier subagent, fed the card, the PR and AGENTS.md only; the seat verified ③-1 against localEngineDefect at the head before adopting.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 7fc737470b73a61f1fb50d37315d24cf0c5f982c

① Derived judgments

0. The delta from the reviewed head 5fb95579 is prose only: one commit, touching .changeset/19893-turso-remote-url-replica-refusal.md and packages/drivers/driver-turso/README.md (+37/−21). No .ts or .json file changed, so localEngineDefect, detectMode, toKnexConfig, the refusal message text, every test, package.json and index.ts are byte-identical to the head already judged in record 5815787919. RIGHT.
1. Every ① judgment of 5815787919 carries over unchanged. Re-probed on this head:
   • a lowercase remote url beside syncUrl, or under a forced mode: 'replica' / 'local', is refused;
   • an in-memory replica (:memory:, file::memory:, file::memory:?…) is refused;
   • a non-file: url under a forced mode: 'replica' only is refused;
   • file: + syncUrl, file: / :memory: local, and a remote url alone or with mode: 'remote' stay accepted;
   • a bare path or uppercase scheme with no mode, with or without syncUrl, and the same url under mode: 'local', still construct on Knex :memory: (tracked as driver-turso: a url whose scheme the classifier does not recognise (an uppercase LIBSQL://, a bare path) and no mode falls through to local on a :memory: Knex engine, so every write is lost on restart #19976);
   • the refusal fires before Knex and any client, with VALIDATION_ERROR / 400;
   • the url is never echoed;
   • detectMode is unchanged, and so is the published surface.
     RIGHT.

② Semver level

Consistent: minor, a ! title, a BREAKING banner, Clause-②: no (narrowing) in both the changeset and the PR body, and an ADR-0087 disposition not-required (no-migration-prescription). Check Changeset is success on this head, including its ADR-0087 and no-major steps. The other required contexts were still in_progress at the reviewer's last poll. The code is byte-identical to 5fb95579, where all seven finished success.

③ Boundary flags

1. Every changeset sentence was re-judged against the unchanged code, and all are TRUE:
   • the narrowed headline;
   • the lowercase-scheme definition of "remote url";
   • refusal bullets 1–4, including the file::memory:?cache=shared literal-file sentence. That one is measured from knex@3.3.0 handing filename to better-sqlite3@13.0.3, which is built with SQLITE_USE_URI=0 and treats only :memory: as anonymous;
   • "names the scheme … never echoes the url";
   • "What stays accepted";
   • the "Not refused, unchanged here" paragraph citing driver-turso: a url whose scheme the classifier does not recognise (an uppercase LIBSQL://, a bare path) and no mode falls through to local on a :memory: Knex engine, so every write is lost on restart #19976;
   • "What an affected author does", which matches the refusal message strings (it omits the mode: 'remote' alternative, an omission, not a falsehood);
   • the connect() failure sentence;
   • the blast-radius census.
2. The README hunk is TRUE. One non-blocking precision note: "auto-detected from a :memory: or file: url beside syncUrl" reads better as ":memory: or file::memory: url".
3. The earlier dev flags stand as answered in 5815787919, and the five out-of-scope findings are real. The fall-through is driver-turso: a url whose scheme the classifier does not recognise (an uppercase LIBSQL://, a bare path) and no mode falls through to local on a :memory: Knex engine, so every write is lost on restart #19976; the spec refinement and the inert mode: 'remote' + syncUrl are spec: TursoConfigSchema accepts turso configs the driver refuses or ignores — a remote url beside syncUrl or a forced replica/local mode, a non-file: replica, syncUrl/sync under mode: remote #19977.

Implemented-by: claude/issue-19893-turso-remote-syncurl-replica
Reviewed-by: session_01Bvd69VPa6puiNzzPUroDBx

VERDICT: PASS

Isolated reviewer: the same contract-review-tier subagent, re-run on the new head; adopted by the seat. Landing condition, outside this record: every check on 7fc73747 must conclude success or be an expected skip.

---

Generated by Claude Code