@@ -0,0 +1,33 @@
+---
+'@objectstack/driver-turso': minor
+'@objectstack/spec': patch
+---
+
+fix(driver-turso)!: `new TursoDriver` refuses `syncUrl` under a forced `mode: 'remote'`, and `sync` with no `syncUrl`, instead of building and ignoring them
+
+Clause-②: no (narrowing) — nothing is widened. No key is added, removed or renamed, and no exported symbol moves. Two driver configurations that the turso driver used to build and then ignore a key of are now refused when it is built.
+
+`new TursoDriver()` accepted `syncUrl` beside a forced `mode: 'remote'`. Remote mode sends every read and write straight to `url`, and the remote client is created without `syncUrl`, so no replica is built and no sync ever runs. Measured on the built driver before this change, a `libsql://` or `file:` url under `mode: 'remote'` with `syncUrl` and `sync` constructed and connected, and `isSyncEnabled()` answered `true`. No sync interval started, and the sync call rejected with `SYNC_NOT_SUPPORTED` (`SyncNotSupported("File")` on the `file:` url). It also accepted `sync` with no `syncUrl`, in any mode, where nothing reads it. `@objectstack/spec`'s `TursoConfigSchema` already refused both at authoring. A datasource row stored before that, or a config a host builds itself, reached the constructor unparsed and ran with a sync setting that did nothing.
+
+**BREAKING** accept-set narrowing on a published constructor, shipped as `minor` under the repo's launch-window convention for breaking changes (`scripts/check-changeset-no-major.mjs`). Refused now with `VALIDATION_ERROR` / 400, before any client or database is opened:
+
+- `syncUrl` under a forced `mode: 'remote'`. A remote url beside `syncUrl` with no `mode` was already refused, as a replica on a remote url;
+- `sync` with no `syncUrl` (or with an empty one), in local, replica and remote mode alike.
+
+Each refusal's message is the spec contract's issue message for that key, byte for byte, so authoring and boot say the same thing. A test holds the copies equal. The spec's `syncUrl` message said the driver "runs no sync, so the setting changes nothing". It now reads "the turso driver refuses this configuration when it starts", like its sibling refusals, and the driver's own `TursoConfigSchema` mirror follows (`@objectstack/spec` patch: message text only). The ADR-0087 entry `turso-config-transport-mismatch-refused` now also records that the constructor refuses these two shapes at boot.
+
+Left accepted on purpose: `mode: 'replica'` on a `file:` url with no `syncUrl` (and no `sync`). It still runs as a plain local database. Refusing it in the constructor alone would refuse a config both schemas accept, so it is tracked separately.
+
+### Migration: FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `url: 'libsql://my-db.turso.io', mode: 'remote', syncUrl: …` (with or without `sync`) | a remote database: drop `syncUrl` and `sync`. An embedded replica: `url: 'file:./data/replica.db', syncUrl: 'libsql://my-db.turso.io'` and no `mode` |
+| `url: 'file:./data/app.db', mode: 'remote', syncUrl: …` | the same two ways out |
+| `sync: { … }` with no `syncUrl` | name the remote in `syncUrl` (with a `file:` url), or drop `sync` |
+
+A datasource row stored with one of these shapes is not re-parsed when it loads, so it now fails when the driver is built. `factory.create` throws the refusal. The connection service records the datasource as `failed-degraded` with the message, and a test connection answers `ok: false` ("Failed to build driver: …"). Under ADR-0062 D5, the boot fails fast when objects bind to that datasource or are routed to it, or when it is boot-critical, unless `OS_ALLOW_DRIVER_CONNECT_FAILURE` is set. Otherwise it is left unconnected with a warning. Before this change the same row booted, reported sync as enabled and never synced. The way out is the table above: drop `syncUrl` / `sync` from a remote config, or use a `file:` url with the remote in `syncUrl`.
+
+Blast radius, measured on this tree: no example, template, published skill or hand-written doc authors either shape, and no in-repo caller reads `isSyncEnabled()` or calls the driver's sync outside `@objectstack/driver-turso`'s own tests. Whether any out-of-repo deployment declares such a config is NOT measured and is not claimed to be zero.
+
+<!-- adr-0087: not-required (already-registered turso-config-transport-mismatch-refused) that entry is this family's semantic TODO (the turso transport refusals, registered with the authoring half), and this diff updates its stored-row sentence to cover the constructor half: syncUrl under a forced remote mode and sync with no syncUrl are refused at boot as well -->
@@ -10,18 +10,24 @@
  *  3. this package's own `TursoConfigSchema` mirror (`./turso.zod.ts`).
  *
  * The two schemas used to accept every combination below, so a datasource the
- * driver refuses at construction (or constructs and ignores) was accepted at
- * authoring and failed a boot later. Each row states the constructor's verdict
+ * driver refuses at construction (or, until #20200, constructed and ignored)
+ * was accepted at authoring and failed a boot later. Each row states the constructor's verdict
  * and the schemas' verdict, and the test asserts all three against it:
  *
  *  - a row the constructor REFUSES is refused by both schemas, on the key the
  *    row names, with one `custom` issue;
- *  - a row the constructor ACCEPTS is accepted by both — except the `inert`
- *    rows, which the constructor builds and then ignores a key of (`syncUrl`
- *    under a forced `mode: 'remote'`; `sync` with no `syncUrl`). Those are
- *    refused at authoring only, because a declared setting that changes
- *    nothing is the shape ADR-0049 does not ship;
- *  - the two schemas' messages are byte-identical wherever both judge a row.
+ *  - a row the constructor ACCEPTS is accepted by both — except an `inert`
+ *    row, one the constructor would build and then ignore a key of, refused at
+ *    authoring only. [#20200] There are none left, and the table pins that at
+ *    exactly zero: the four there were (`syncUrl` under a forced
+ *    `mode: 'remote'`; `sync` with no `syncUrl`) are refused by the
+ *    constructor now, because a declared setting that changes nothing is the
+ *    shape ADR-0049 does not ship. A new `inert` row is a new ignored key —
+ *    fix the constructor, or argue it on the card, before moving the floor;
+ *  - the two schemas' messages are byte-identical wherever both judge a row;
+ *  - [#20200] where the constructor refuses on `syncUrl` or `sync`, its message
+ *    is the spec contract's issue message, byte for byte: those two texts are
+ *    copies in `../turso-driver.ts`, and this is the pin that holds them equal.
  *
  * ⚠️ The mirror declares no `mode`, so zod strips an authored one before its
  * refinement runs: rows that FORCE a mode are judged by the constructor and the
@@ -69,7 +75,7 @@ interface Row {
   ctor: 'accept' | 'refuse';
   /** The key both schemas refuse on, or `undefined` when they accept. */
   refusedOn?: 'url' | 'syncUrl' | 'timeoutMs' | 'sync';
-  /** The constructor accepts it and ignores a key: refused at authoring only. */
+  /** The constructor accepts it and ignores a key: refused at authoring only. None today (#20200). */
   inert?: true;
 }
 
@@ -134,13 +140,22 @@ const ROWS: Row[] = [
   { name: 'timeoutMs beside an uppercase WS://', config: { url: 'WS://127.0.0.1:8080', timeoutMs: 5000 }, ctor: 'refuse', refusedOn: 'timeoutMs' },
   { name: "timeoutMs beside wss:// under a forced mode: 'remote'", config: { url: 'wss://db.example.turso.io', timeoutMs: 5000, mode: 'remote' }, ctor: 'refuse', refusedOn: 'timeoutMs' },
 
-  // ── accepted by the constructor, ignored by the driver: refused at authoring ──
-  { name: "syncUrl under a forced mode: 'remote'", config: { url: REMOTE, mode: 'remote', syncUrl: REMOTE }, ctor: 'accept', refusedOn: 'syncUrl', inert: true },
-  { name: "syncUrl + sync under a forced mode: 'remote'", config: { url: REMOTE, mode: 'remote', syncUrl: REMOTE, sync: { intervalSeconds: 60 } }, ctor: 'accept', refusedOn: 'syncUrl', inert: true },
-  { name: "file: + syncUrl under a forced mode: 'remote'", config: { url: FILE, mode: 'remote', syncUrl: REMOTE }, ctor: 'accept', refusedOn: 'syncUrl', inert: true },
-  { name: 'sync with no syncUrl', config: { url: FILE, sync: { intervalSeconds: 60 } }, ctor: 'accept', refusedOn: 'sync', inert: true },
+  // ── sync keys the driver would ignore: refused at construction and at authoring (#20200) ──
+  { name: "syncUrl under a forced mode: 'remote'", config: { url: REMOTE, mode: 'remote', syncUrl: REMOTE }, ctor: 'refuse', refusedOn: 'syncUrl' },
+  { name: "syncUrl + sync under a forced mode: 'remote'", config: { url: REMOTE, mode: 'remote', syncUrl: REMOTE, sync: { intervalSeconds: 60 } }, ctor: 'refuse', refusedOn: 'syncUrl' },
+  { name: "file: + syncUrl under a forced mode: 'remote'", config: { url: FILE, mode: 'remote', syncUrl: REMOTE }, ctor: 'refuse', refusedOn: 'syncUrl' },
+  { name: 'sync with no syncUrl', config: { url: FILE, sync: { intervalSeconds: 60 } }, ctor: 'refuse', refusedOn: 'sync' },
+  { name: 'sync with no syncUrl on a remote url', config: { url: REMOTE, sync: { intervalSeconds: 60 } }, ctor: 'refuse', refusedOn: 'sync' },
+  { name: "sync with no syncUrl under a forced mode: 'remote'", config: { url: REMOTE, mode: 'remote', sync: { onConnect: true } }, ctor: 'refuse', refusedOn: 'sync' },
+  { name: "sync with no syncUrl under a forced mode: 'replica'", config: { url: FILE, mode: 'replica', sync: { intervalSeconds: 60 } }, ctor: 'refuse', refusedOn: 'sync' },
+  { name: 'sync beside an empty syncUrl (unset)', config: { url: FILE, syncUrl: '', sync: { intervalSeconds: 60 } }, ctor: 'refuse', refusedOn: 'sync' },
 ];
 
+/** The rows the constructor refuses on a sync key: its message is a copy of the spec's (#20200). */
+const SYNC_KEY_REFUSALS = ROWS.filter(
+  (r) => r.ctor === 'refuse' && (r.refusedOn === 'syncUrl' || r.refusedOn === 'sync'),
+);
+
 /**
  * The driver config a datasource loader builds from an authored one — the
  * reading `buildTursoDriverConfig` / `resolveTursoUrl` in
@@ -159,15 +174,15 @@ function driverConfigOf(authored: Authored): TursoDriverConfig {
   };
 }
 
-function constructorVerdict(authored: Authored): 'accept' | 'refuse' {
+function constructorVerdict(authored: Authored): { verdict: 'accept' | 'refuse'; message?: string } {
   try {
     new TursoDriver(driverConfigOf(authored));
-    return 'accept';
+    return { verdict: 'accept' };
   } catch (error) {
     // A refusal is the ADR-0112 envelope, never some other throw.
     expect((error as { code?: string }).code).toBe('VALIDATION_ERROR');
     expect((error as { status?: number }).status).toBe(400);
-    return 'refuse';
+    return { verdict: 'refuse', message: (error as Error).message };
   }
 }
 
@@ -192,18 +207,24 @@ describe('turso config: the constructor, the spec contract and this mirror agree
     expect(ROWS.filter((r) => r.ctor === 'accept' && !r.refusedOn).length).toBeGreaterThanOrEqual(20);
     expect(ROWS.filter((r) => r.refusedOn === 'url').length).toBeGreaterThanOrEqual(25);
     expect(ROWS.filter((r) => r.refusedOn === 'timeoutMs').length).toBeGreaterThanOrEqual(3);
-    expect(ROWS.filter((r) => r.inert).length).toBeGreaterThanOrEqual(4);
+    expect(ROWS.filter((r) => r.refusedOn === 'syncUrl').length).toBeGreaterThanOrEqual(3);
+    expect(ROWS.filter((r) => r.refusedOn === 'sync').length).toBeGreaterThanOrEqual(5);
+    expect(SYNC_KEY_REFUSALS.length).toBeGreaterThanOrEqual(8);
+    // [#20200] Exactly zero, not a floor: every key the constructor used to
+    // build and ignore is refused at construction now (see the header).
+    expect(ROWS.filter((r) => r.inert).length).toBe(0);
     expect(ROWS.filter((r) => !r.config.mode).length).toBeGreaterThanOrEqual(35);
   });
 
   describe.each(ROWS)('$name', (row) => {
     it(`the constructor ${row.ctor}s it`, () => {
-      expect(constructorVerdict(row.config)).toBe(row.ctor);
+      expect(constructorVerdict(row.config).verdict).toBe(row.ctor);
     });
 
+
     it(row.refusedOn ? `the spec contract refuses it on \`${row.refusedOn}\`` : 'the spec contract accepts it', () => {
       // Authoring refuses what construction refuses, and nothing it accepts
-      // but the declared-and-ignored keys.
+      // but an `inert` row's declared-and-ignored key (none since #20200).
       expect(Boolean(row.refusedOn)).toBe(row.ctor === 'refuse' || Boolean(row.inert));
       const verdict = schemaVerdict(SpecTursoConfigSchema, row.config);
       expect(verdict.refusedOn, verdict.message).toBe(row.refusedOn);
@@ -219,4 +240,16 @@ describe('turso config: the constructor, the spec contract and this mirror agree
       expect(mirror).toEqual(spec);
     });
   });
+
+  // [#20200] The two sync refusals are copies of the spec contract's texts in
+  // `../turso-driver.ts` (the spec keeps them module-local); this is the pin
+  // that holds each copy equal to the schema's issue, byte for byte.
+  describe.each(SYNC_KEY_REFUSALS)('$name', (row) => {
+    it("the constructor's message is the spec contract's, byte for byte (#20200)", () => {
+      const spec = schemaVerdict(SpecTursoConfigSchema, row.config);
+      expect(spec.refusedOn).toBe(row.refusedOn);
+      expect(spec.message).toBeTypeOf('string');
+      expect(constructorVerdict(row.config).message).toBe(spec.message);
+    });
+  });
 });
@@ -82,13 +82,14 @@ const WASM_RETIRED =
   + 'Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.';
 
 // ==========================================================================
-// 2a. Transport coherence — what `new TursoDriver` refuses or ignores
+// 2a. Transport coherence — what `new TursoDriver` refuses
 // ==========================================================================
 //
 // #19977. Each key below parsed on its own, so this mirror accepted
 // combinations the driver in this very package refuses at construction
-// (`VALIDATION_ERROR` / 400), or constructs and ignores. It now refuses them,
-// with the supported spelling in the message. The predicates and the messages
+// (`VALIDATION_ERROR` / 400), or, until #20200, constructed and ignored. It
+// now refuses them, with the supported spelling in the message. The
+// predicates and the messages
 // are the ones `@objectstack/spec`'s own turso contract
 // (`packages/spec/src/data/driver/turso.zod.ts`, `tursoTransportIssues`)
 // carries, byte for byte: the helper is internal to that package and not on
@@ -260,8 +261,8 @@ function tursoTransportIssues(cfg: TursoTransportKeys): TursoTransportIssue[] {
       path: 'syncUrl',
       message:
         "`syncUrl` configures an embedded replica, but `mode: 'remote'` sends every read and write "
-        + 'straight to `url` and builds no replica: the turso driver never hands `syncUrl` to the '
-        + 'remote client and runs no sync, so the setting changes nothing. For a remote database, '
+        + 'straight to `url` and builds no replica: the turso driver refuses this configuration when '
+        + 'it starts. For a remote database, '
         + `drop ${syncUrlKeys}. For an embedded replica, drop \`mode\` and point \`url\` at a local `
         + "file beside `syncUrl`: `url: 'file:./data/replica.db'`.",
     });
@@ -390,8 +391,8 @@ export const TursoConfigSchema = lazySchema(() => z.object({
         + 'nothing.',
     });
   }
-  // What the driver refuses at construction, or constructs and ignores —
-  // see `tursoTransportIssues` above.
+  // What the driver refuses at construction — see `tursoTransportIssues`
+  // above.
   for (const issue of tursoTransportIssues(cfg)) {
     ctx.addIssue({ code: 'custom', path: [issue.path], message: issue.message });
   }