feat(driver-turso)!: rename the published config timeout to timeoutMs, tombstone on the old spelling (#15682)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G4138K1EG7kQ81FNba5Kp4

Author: claude

.changeset/driver-turso-config-timeout-ms.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/driver-turso": minor
+---
+
+feat(driver-turso)!: the published connection config names its timeout's unit (#15682, ruling B on #14478)
+
+<!-- adr-0087: not-required (already-registered turso-config-timeout-to-timeout-ms) that protocol-18 conversion rewrites `datasources[].config.timeout` to `timeoutMs` for turso datasources, which is the same authored key this package's schema mirrors — a second entry would restate the same rewrite without converting anything more -->
+
+**BREAKING** — `TursoConfigSchema`'s `timeout` is renamed to **`timeoutMs`**. The
+value is unchanged: the same milliseconds, the same `min(0)` bound, the same
+optionality.
+
+`@objectstack/spec`'s own turso contract renamed the same authored key in
+#15680. This package publishes a parallel schema for the same connection config
+— the Spec / Studio metadata a host reads to expose Turso configuration UI — so
+until now the two declarations of one setting disagreed on its spelling. They
+agree again.
+
+The unit was never in the key name, only in the describe prose, while
+`sync.intervalSeconds` — the same shape, three keys above — already spelled its
+own. One published config carrying both conventions is what made the bare name
+dangerous rather than untidy: an author who has just written
+`intervalSeconds: 30` has no reason to read `timeout: 30` as milliseconds, and
+nothing in the schema, the type or the parse would have told them otherwise.
+
+The old spelling is not dropped in silence. `TursoConfigSchema` is a plain
+`z.object`, so a bare deletion would have STRIPPED `timeout` and parsed
+successfully. The key stays declared as a tombstone instead: `tsc` refuses it on
+anything typed `TursoConfig`, and a value that reaches the parse raises a
+message naming `timeoutMs` rather than a generic unrecognised-key error.
+
+```diff
+- TursoConfigSchema.parse({ url: 'libsql://app.turso.io', timeout: 30000 })
++ TursoConfigSchema.parse({ url: 'libsql://app.turso.io', timeoutMs: 30000 })
+```
+
+`TursoDriverConfig` — this package's TypeScript constructor option, a separate
+declaration — keeps its `timeout` spelling and is untouched here.

packages/drivers/driver-turso/src/spec/turso.test.ts

@@ -62,13 +62,13 @@ describe('TursoConfigSchema', () => {
         intervalSeconds: 120,
         onConnect: false,
       },
-      timeout: 30000,
+      timeoutMs: 30000,
       wasm: true,
     });
 
     expect(config.encryptionKey).toBe('my-secret-key-256');
     expect(config.concurrency).toBe(50);
-    expect(config.timeout).toBe(30000);
+    expect(config.timeoutMs).toBe(30000);
     expect(config.wasm).toBe(true);
   });
 
@@ -83,7 +83,7 @@ describe('TursoConfigSchema', () => {
     expect(config.syncUrl).toBeUndefined();
     expect(config.localPath).toBeUndefined();
     expect(config.sync).toBeUndefined();
-    expect(config.timeout).toBeUndefined();
+    expect(config.timeoutMs).toBeUndefined();
     expect(config.wasm).toBeUndefined();
   });
 
@@ -124,13 +124,42 @@ describe('TursoConfigSchema', () => {
     })).toThrow();
   });
 
-  it('should reject config with negative timeout', () => {
+  it('should reject config with negative timeoutMs', () => {
     expect(() => TursoConfigSchema.parse({
       url: ':memory:',
-      timeout: -1,
+      timeoutMs: -1,
     })).toThrow();
   });
 
+  // [#15682, ruling B on #14478] The rename's tombstone. Asserted on the
+  // REFUSAL ENVELOPE — which key was refused and what the message prescribes —
+  // rather than on `toThrow()` alone: a bare `toThrow()` here stays green for a
+  // schema that lost the tombstone entirely and simply required `url`, and it
+  // would stay green for a strip that never refused at all. What must hold is
+  // that the old spelling is REFUSED and that the refusal names the new key.
+  it('refuses the retired `timeout` spelling, and the refusal names `timeoutMs`', () => {
+    const result = TursoConfigSchema.safeParse({ url: ':memory:', timeout: 30000 });
+
+    expect(result.success).toBe(false);
+    const issue = result.error!.issues.find((i) => i.path.join('.') === 'timeout');
+    expect(issue).toBeDefined();
+    expect(issue!.message).toContain('timeoutMs');
+    expect(issue!.message).toContain('milliseconds');
+    // The standardized closing sentence — the one channel an upgrading author
+    // is guaranteed to hit carries the command, not just the diagnosis.
+    expect(issue!.message).toContain('os migrate meta --from 17');
+  });
+
+  // The other half of the tombstone: it refuses a VALUE, it does not make the
+  // whole config unparseable. A tombstone that took the object down with it
+  // would read identically in the case above.
+  it('the tombstone leaves a config that never wrote `timeout` untouched', () => {
+    const config = TursoConfigSchema.parse({ url: ':memory:', timeoutMs: 5000 });
+
+    expect(config.timeoutMs).toBe(5000);
+    expect('timeout' in config).toBe(false);
+  });
+
   it('should accept config with environment variable patterns', () => {
     const config = TursoConfigSchema.parse({
       url: '${TURSO_DATABASE_URL}',
@@ -150,13 +179,13 @@ describe('TursoConfigSchema', () => {
     expect(config.concurrency).toBe(100);
   });
 
-  it('should accept zero timeout (no timeout)', () => {
+  it('should accept zero timeoutMs (no timeout)', () => {
     const config = TursoConfigSchema.parse({
       url: ':memory:',
-      timeout: 0,
+      timeoutMs: 0,
     });
 
-    expect(config.timeout).toBe(0);
+    expect(config.timeoutMs).toBe(0);
   });
 });
 

packages/drivers/driver-turso/src/spec/turso.zod.ts

@@ -46,6 +46,22 @@ export const TursoSyncConfigSchema = lazySchema(() => z.object({
 // 2. Connection Configuration
 // ==========================================================================
 
+/**
+ * The prescription the retired `timeout` key raises, and the text `tsc` and the
+ * parse both carry. Standardized closing sentence — the `os migrate meta`
+ * wording states a property of the TOOL and is not a choice (see
+ * `retired-key.ts` in `@objectstack/spec`, whose header owns that ruling).
+ *
+ * ⛔ No internal issue id in this string: it is customer-facing text and
+ * `check:doc-authoring` refuses one. The ids live in the comments beside the
+ * keys below.
+ */
+const TIMEOUT_RETIRED =
+  '`turso config.timeout` was renamed to `timeoutMs` in @objectstack/driver-turso 17 — the unit of a '
+  + 'duration-shaped number lives in the key name, not only in the describe prose. Rename the key to '
+  + '`timeoutMs`; the value (milliseconds) is unchanged. '
+  + 'Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.';
+
 export const TursoConfigSchema = lazySchema(() => z.object({
   /**
    * Database URL.
@@ -100,8 +116,34 @@ export const TursoConfigSchema = lazySchema(() => z.object({
 
   /**
    * Timeout for database operations in milliseconds.
+   *
+   * Renamed from `timeout` (#15682, ruling B on #14478): the unit lived only in
+   * the describe prose, while `sync.intervalSeconds` — the same shape, three
+   * keys above — already spelled ITS unit. One published connection config
+   * carrying both conventions is what made the bare name dangerous rather than
+   * untidy. `@objectstack/spec`'s own turso contract renamed the same authored
+   * key in #15680; this mirror now agrees with it, and with the ADR-0087
+   * conversion (`turso-config-timeout-to-timeout-ms`) that rewrites the stored
+   * spelling on load.
+   */
+  timeoutMs: z.number().int().min(0).optional().describe('Operation timeout in milliseconds'),
+
+  /**
+   * Tombstone for the rename above (#15682, ruling B on #14478).
+   *
+   * This is a plain `z.object`, so zod's default STRIP posture would make a
+   * bare deletion SILENT: an author's `timeout: 30000` would vanish and the
+   * parse would still succeed. `z.never()` keeps the key DECLARED and
+   * unwritable, so the old spelling raises the prescription instead of
+   * disappearing — the two channels an upgrading author actually meets (`tsc`
+   * sees `never` at the authoring site; the parse raises the text itself).
+   *
+   * Spelled inline rather than through `@objectstack/spec`'s `retiredKey()`:
+   * that helper is internal to the spec package and is not on its published
+   * `./shared` entry point, so this package cannot import it. The shape is the
+   * same one-liner.
    */
-  timeout: z.number().int().min(0).optional().describe('Operation timeout in milliseconds'),
+  timeout: z.never({ error: () => TIMEOUT_RETIRED }).optional().describe(`[REMOVED] ${TIMEOUT_RETIRED}`),
 
   /**
    * Enable WASM mode.

packages/spec/src/conversions/registry.ts

@@ -8945,10 +8945,15 @@ const memoryPersistenceAutoSaveIntervalToMs: MetadataConversion = {
  * The neighbour is why this key was worth the rename: `sync.intervalSeconds`,
  * two keys above, already spelled ITS unit. One shape, both conventions.
  *
- * ⚠️ This converts the SPEC's turso contract. The driver package ships its own
- * parallel `turso.zod.ts` whose `timeout` is outside this card's declared
- * population; it is renamed by the card that widens that population, and until
- * then the two declarations disagree by design.
+ * ⚠️ This converts the SPEC's turso contract. `@objectstack/driver-turso` ships
+ * its own parallel `turso.zod.ts` declaring the same authored key, which was
+ * outside this gate's declared population when this entry was written. #15682
+ * widened that population to every workspace package's zod schemas and renamed
+ * the mirror in the same PR, so both declarations now spell `timeoutMs` and
+ * this ONE conversion covers the authored surface for both. The mirror
+ * registers no second entry: it would restate the same rewrite in
+ * `spec-changes.json` and the upgrade guide without converting anything the
+ * rename above has not already converted.
  */
 const tursoConfigTimeoutToTimeoutMs: MetadataConversion = {
   id: 'turso-config-timeout-to-timeout-ms',