@@ -0,0 +1,30 @@
+---
+'@objectstack/spec': minor
+'@objectstack/driver-turso': minor
+---
+
+fix(spec,driver-turso)!: a turso config that forces `mode: 'local'` beside a `syncUrl` is refused where it is written and when the driver is built, instead of running as an embedded replica under a `local` label
+
+Clause-②: yes (narrowing) — the accept set of the `turso` `datasource.config` contract narrows by one combination. No key is added, removed or renamed, and no exported symbol moves.
+
+A `syncUrl` names the remote an embedded replica syncs with. A config that forced `mode: 'local'` on a `file:` url (or `:memory:`) beside a non-empty `syncUrl` was accepted by `@objectstack/spec`'s `TursoConfigSchema`, by the published mirror in `@objectstack/driver-turso`, and by `new TursoDriver()`. Measured on the driver source before this change, with a client that counts syncs: it constructed with `transportMode` `'local'`, then synced on connect, started the sync interval, and `isSyncEnabled()` answered `true` — exactly what the same config with no `mode` (a replica) did. A datasource declared local was kept in sync with a remote, and only a label said otherwise.
+
+**BREAKING** accept-set narrowing on a published schema and a published constructor, shipped as `minor` under the repo's launch-window convention for breaking changes (`scripts/check-changeset-no-major.mjs`). Refused now, at both doors together, with one message whose prescription names both ways out:
+
+- **at authoring**, as one `custom` issue on `mode` (`config.mode` on a datasource): `DatasourceSchema`, `validateDriverConfig`, `defineStack` / `os validate`, and a save or test connection through the datasource admin service;
+- **at construction**, `VALIDATION_ERROR` / 400 from `new TursoDriver()` (and `createTursoDriver()`), before any client or database is opened.
+
+The message is the same text at both doors, and a test holds the constructor's copy equal to the schema's issue byte for byte. It is the twin of the forced `mode: 'replica'`-without-`syncUrl` refusal, the other way round: honouring `mode: 'local'` by skipping the sync would ignore a declared `syncUrl` instead, which is the same defect with the keys swapped. The sibling refusals keep their order: a forced local mode on a remote url or a bare path still meets its `url` refusal first. An empty `syncUrl` is unset and is still accepted. The driver mirror declares no `mode` key and strips an authored one, so it cannot see a forced mode: this refusal reaches it only as byte-identical text, and the spec contract and the constructor are the two doors that judge it.
+
+### Migration: FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `url: 'file:./data/replica.db', mode: 'local', syncUrl: 'libsql://my-db.turso.io'` | an embedded replica: drop `mode` (`url` and `syncUrl` select the replica) |
+| the same | a plain local database: drop `syncUrl` (and `sync`), keeping `url: 'file:./data/app.db'` with or without `mode: 'local'` |
+
+A datasource row stored in this shape 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 and synced with the remote under a `local` label. The way out is the table above.
+
+Blast radius, measured on this tree: no example, template, published skill or hand-written doc authors the shape, and no host default or environment variable sets `mode` or `syncUrl` (a turso `mode` reaches the driver only from an authored `datasource.config`). Whether any out-of-repo deployment declares such a config is NOT measured and is not claimed to be zero.
+
+<!-- adr-0087: registered turso-config-forced-local-with-sync-url-refused -->
@@ -0,0 +1,54 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+// A forced local mode beside a remote to replicate from, refused at both doors
+// together: the datasource contract (on mode) and the turso driver's
+// constructor, in one message. The driver used to label it local and run it as
+// an embedded replica anyway. The twin of
+// turso-config-forced-replica-without-sync-url-refused, the other way round. A
+// structured TODO, not a D2 conversion: whether the author meant an embedded
+// replica of that remote or a plain local file is intent no artifact records.
+export const entry: SemanticMigration = {
+  id: 'turso-config-forced-local-with-sync-url-refused',
+  // No backticks in `surface` — build-upgrade-guide renders it inside a code
+  // span already, and a nested backtick would close it.
+  surface:
+    'data.TursoConfig (a turso / libsql datasource.config) and the TursoDriver constructor of '
+    + '@objectstack/driver-turso — mode local beside a non-empty syncUrl is now refused, on mode at '
+    + 'authoring and at construction. The published TursoConfigSchema mirror of '
+    + '@objectstack/driver-turso carries the same text for parity but declares no mode key and strips '
+    + 'an authored one, so it cannot see a forced mode and still accepts the config as a replica',
+  replacement:
+    'the configuration the author meant. An embedded replica drops mode: keep the file: url and '
+    + 'syncUrl, for example url file:./data/replica.db with syncUrl naming the remote, and the url '
+    + 'and syncUrl select the replica. A plain local database drops syncUrl and sync: a file: url '
+    + '(or :memory:) with no syncUrl is a local database, with or without mode local',
+  reason:
+    'A syncUrl names the remote an embedded replica syncs with, and the turso driver syncs whenever '
+    + 'it is set on a local engine, whatever mode says. The triage ruling of 2026-09-29 weighed '
+    + 'refusing this shape against honouring mode local by skipping the sync, and refused it: '
+    + 'honouring it would ignore a declared syncUrl, the same defect with the keys swapped, and a '
+    + 'loud contradiction is the author\'s to resolve. A forced mode local beside a syncUrl parsed '
+    + 'clean at authoring, and the driver built it with a local transport label and then ran it as '
+    + 'a replica: it synced on connect, started the sync interval and answered true to the '
+    + 'sync-enabled check, exactly as the same config with no mode did (measured on the driver '
+    + 'source). A declared mode the runtime ignores is the declared-but-not-enforced shape ADR-0049 '
+    + 'does not ship, so the datasource contract and the constructor now refuse it together, with '
+    + 'one message, which names both ways out. The sibling refusals keep their order: a forced '
+    + 'local mode on a remote url or a bare path meets its url refusal first. An empty syncUrl is '
+    + 'unset and is not refused. Stored datasource rows are not re-parsed when they load, so a '
+    + 'stored row in this shape now fails when its driver is built: the connection service records '
+    + 'it as failed-degraded, a test connection answers ok false, and under ADR-0062 D5 the boot '
+    + 'fails fast when objects bind to that datasource, unless OS_ALLOW_DRIVER_CONNECT_FAILURE is '
+    + 'set. Measured on this tree at the change: no example, template, published skill or '
+    + 'hand-written doc authors the shape, and no host default or environment variable sets mode '
+    + 'or syncUrl. ADR-0049 / ADR-0087 / ADR-0112.',
+  acceptanceCriteria:
+    'Validate every stack and re-save every turso datasource: os validate or defineStack, and a '
+    + 'save or test connection through the datasource admin service, report a forced local mode '
+    + 'beside a syncUrl at config.mode with both ways out. Decide per datasource whether it is an '
+    + 'embedded replica (drop mode) or a local file (drop syncUrl and sync). Done when every turso '
+    + 'datasource parses, the driver builds from it, and no datasource that declares mode local '
+    + 'carries a syncUrl.',
+};
@@ -16982,6 +16982,56 @@ const step18: MigrationStep = {
         + '(`@objectstack/service-settings`’s `settingsBuiltinTranslations`) — ⛔ do not re-add '
         + 'app-side copy at either door, which is refused.',
     },
+    // A forced local mode beside a remote to replicate from, refused at both doors
+    // together: the datasource contract (on mode) and the turso driver's
+    // constructor, in one message. The driver used to label it local and run it as
+    // an embedded replica anyway. The twin of
+    // turso-config-forced-replica-without-sync-url-refused, the other way round. A
+    // structured TODO, not a D2 conversion: whether the author meant an embedded
+    // replica of that remote or a plain local file is intent no artifact records.
+    {
+      id: 'turso-config-forced-local-with-sync-url-refused',
+      // No backticks in `surface` — build-upgrade-guide renders it inside a code
+      // span already, and a nested backtick would close it.
+      surface:
+        'data.TursoConfig (a turso / libsql datasource.config) and the TursoDriver constructor of '
+        + '@objectstack/driver-turso — mode local beside a non-empty syncUrl is now refused, on mode at '
+        + 'authoring and at construction. The published TursoConfigSchema mirror of '
+        + '@objectstack/driver-turso carries the same text for parity but declares no mode key and strips '
+        + 'an authored one, so it cannot see a forced mode and still accepts the config as a replica',
+      replacement:
+        'the configuration the author meant. An embedded replica drops mode: keep the file: url and '
+        + 'syncUrl, for example url file:./data/replica.db with syncUrl naming the remote, and the url '
+        + 'and syncUrl select the replica. A plain local database drops syncUrl and sync: a file: url '
+        + '(or :memory:) with no syncUrl is a local database, with or without mode local',
+      reason:
+        'A syncUrl names the remote an embedded replica syncs with, and the turso driver syncs whenever '
+        + 'it is set on a local engine, whatever mode says. The triage ruling of 2026-09-29 weighed '
+        + 'refusing this shape against honouring mode local by skipping the sync, and refused it: '
+        + 'honouring it would ignore a declared syncUrl, the same defect with the keys swapped, and a '
+        + 'loud contradiction is the author\'s to resolve. A forced mode local beside a syncUrl parsed '
+        + 'clean at authoring, and the driver built it with a local transport label and then ran it as '
+        + 'a replica: it synced on connect, started the sync interval and answered true to the '
+        + 'sync-enabled check, exactly as the same config with no mode did (measured on the driver '
+        + 'source). A declared mode the runtime ignores is the declared-but-not-enforced shape ADR-0049 '
+        + 'does not ship, so the datasource contract and the constructor now refuse it together, with '
+        + 'one message, which names both ways out. The sibling refusals keep their order: a forced '
+        + 'local mode on a remote url or a bare path meets its url refusal first. An empty syncUrl is '
+        + 'unset and is not refused. Stored datasource rows are not re-parsed when they load, so a '
+        + 'stored row in this shape now fails when its driver is built: the connection service records '
+        + 'it as failed-degraded, a test connection answers ok false, and under ADR-0062 D5 the boot '
+        + 'fails fast when objects bind to that datasource, unless OS_ALLOW_DRIVER_CONNECT_FAILURE is '
+        + 'set. Measured on this tree at the change: no example, template, published skill or '
+        + 'hand-written doc authors the shape, and no host default or environment variable sets mode '
+        + 'or syncUrl. ADR-0049 / ADR-0087 / ADR-0112.',
+      acceptanceCriteria:
+        'Validate every stack and re-save every turso datasource: os validate or defineStack, and a '
+        + 'save or test connection through the datasource admin service, report a forced local mode '
+        + 'beside a syncUrl at config.mode with both ways out. Decide per datasource whether it is an '
+        + 'embedded replica (drop mode) or a local file (drop syncUrl and sync). Done when every turso '
+        + 'datasource parses, the driver builds from it, and no datasource that declares mode local '
+        + 'carries a syncUrl.',
+    },
     // A forced embedded replica with no remote to replicate from, refused at both
     // doors together: the datasource contract (on mode) and the turso driver's
     // constructor, in one message. The driver used to build it as a replica that