wip(spec): strip issue ids from tombstones, declare the gate population, regen docs (#14478)

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

Author: os-sales

.changeset/metadata-database-loader-ttl-ms.md

@@ -4,7 +4,7 @@
 
 feat(metadata)!: `DatabaseLoaderOptions.cache.ttl` → `cache.ttlMs` — the read-through cache TTL carries its unit in the key name (#14478)
 
-<!-- adr-0087: not-required (already-registered metadata-manager-config-cache-ttl-unit-in-key) The authorable key this option mirrors — `MetadataManagerConfig.cache.databaseLoader.ttl` → `ttlMs` — is registered by the `@objectstack/spec` changeset of the same change; this package's exported `DatabaseLoaderCacheOptions` interface follows that key one-to-one and has no separate metadata surface to register. -->
+<!-- adr-0087: registered metadata-manager-config-cache-ttl-unit-in-key -->
 
 **BREAKING** rename on the exported `DatabaseLoaderOptions.cache` shape
 (`DatabaseLoaderCacheOptions.ttl` → `ttlMs`), shipped as `minor` under the

content/docs/references/data/driver.mdx

@@ -136,7 +136,7 @@ const result = DriverCapabilitiesSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **transaction** | `any` | optional | Transaction handle |
 | **timeoutMs** | `number` | optional | Operation timeout in milliseconds |
-| **timeout** | `never` | optional | [REMOVED] `DriverOptions.timeout` was removed in @objectstack/spec 17 (#14478) — its unit (milliseconds) lived only in the description. Rename the key to `timeoutMs`; the value (milliseconds) is unchanged. |
+| **timeout** | `never` | optional | [REMOVED] `DriverOptions.timeout` was removed in @objectstack/spec 17 — its unit (milliseconds) lived only in the description. Rename the key to `timeoutMs`; the value (milliseconds) is unchanged. |
 | **skipCache** | `boolean` | optional | Bypass cache |
 | **traceContext** | `Record<string, string>` | optional | OpenTelemetry context or request ID |
 | **tenantId** | `string` | optional | Tenant Isolation identifier |

content/docs/references/kernel/metadata-loader.mdx

@@ -62,7 +62,7 @@ const result = MetadataFallbackStrategySchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **enabled** | `boolean` | optional (default: `true`) | Enable caching |
 | **ttlSeconds** | `integer` | optional (default: `3600`) | Cache TTL in seconds |
-| **ttl** | `never` | optional | [REMOVED] `cache.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 (#14478) — its unit (seconds) lived only in the description, while the nested `cache.databaseLoader.ttl` spelled the same word in milliseconds, so one key name meant two magnitudes 1000× apart. Rename the key to `ttlSeconds`; the value (seconds) is unchanged. |
+| **ttl** | `never` | optional | [REMOVED] `cache.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 — its unit (seconds) lived only in the description, while the nested `cache.databaseLoader.ttl` spelled the same word in milliseconds, so one key name meant two magnitudes 1000× apart. Rename the key to `ttlSeconds`; the value (seconds) is unchanged. |
 | **maxSize** | `integer` | optional | Max cache size in bytes |
 | **databaseLoader** | `{ enabled: boolean; maxSize: integer; ttlMs: integer }` | optional | DatabaseLoader read-through cache |
 

content/docs/references/system/job.mdx

@@ -59,7 +59,7 @@ const result = CronScheduleSchema.parse(data);
 | **handler** | `string` | ✅ | Handler function name (must match a key in `defineStack({ functions })`) |
 | **retryPolicy** | `{ maxRetries?: integer; backoffMs?: integer; backoffMultiplier?: number; maxRetryDelayMs?: integer; … }` | optional | Retry policy: failed runs (including timeouts) are retried with exponential backoff (delay = min(backoffMs * backoffMultiplier^(retry-1), maxRetryDelayMs), optionally jittered) up to maxRetries retries after the initial attempt. Omit the block for a single attempt; declaring it without `maxRetries` also means no retry since 17.0.0 — state a count to opt in. |
 | **timeoutMs** | `integer` | optional | Per-attempt time limit in milliseconds; an over-limit run is recorded with execution status "timeout". The in-flight handler is abandoned, not forcibly cancelled. Omit for no time limit. |
-| **timeout** | `never` | optional | [REMOVED] `job.timeout` was removed in @objectstack/spec 17 (#14478) — its unit (milliseconds) lived only in the description while the sibling `retryPolicy.backoffMs` spells its own, so the same number read as two conventions on one surface. 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. |
+| **timeout** | `never` | optional | [REMOVED] `job.timeout` was removed in @objectstack/spec 17 — its unit (milliseconds) lived only in the description while the sibling `retryPolicy.backoffMs` spells its own, so the same number read as two conventions on one surface. 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. |
 | **enabled** | `boolean` | optional (default: `true`) | Whether the job is enabled |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |

content/docs/references/system/metadata-persistence.mdx

@@ -255,7 +255,7 @@ Metadata file format
 | :--- | :--- | :--- | :--- |
 | **enabled** | `boolean` | optional (default: `true`) | Enable caching |
 | **ttlSeconds** | `integer` | optional (default: `3600`) | Cache TTL in seconds |
-| **ttl** | `never` | optional | [REMOVED] `cache.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 (#14478) — its unit (seconds) lived only in the description, while the nested `cache.databaseLoader.ttl` spelled the same word in milliseconds, so one key name meant two magnitudes 1000× apart. Rename the key to `ttlSeconds`; the value (seconds) is unchanged. |
+| **ttl** | `never` | optional | [REMOVED] `cache.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 — its unit (seconds) lived only in the description, while the nested `cache.databaseLoader.ttl` spelled the same word in milliseconds, so one key name meant two magnitudes 1000× apart. Rename the key to `ttlSeconds`; the value (seconds) is unchanged. |
 | **maxSize** | `integer` | optional | Max cache size in bytes |
 | **databaseLoader** | `{ enabled: boolean; maxSize: integer; ttlMs: integer }` | optional | DatabaseLoader read-through cache |
 

content/docs/references/system/tenant.mdx

@@ -60,7 +60,7 @@ const result = DatabaseLevelIsolationStrategySchema.parse(data);
 | **poolSize** | `integer` | optional (default: `10`) | Connection pool size |
 | **maxActivePools** | `integer` | optional (default: `100`) | Max active pools |
 | **idleTimeoutSeconds** | `integer` | optional (default: `300`) | Idle pool timeout in seconds |
-| **idleTimeout** | `never` | optional | [REMOVED] `connectionPool.idleTimeout` was removed from `DatabaseLevelIsolationStrategy` in @objectstack/spec 17 (#14478) — its unit (seconds) lived in a source comment only and the published description named none, so a reader of the reference page could not tell 300 seconds from 300 milliseconds. Rename the key to `idleTimeoutSeconds`; the value (seconds) is unchanged. |
+| **idleTimeout** | `never` | optional | [REMOVED] `connectionPool.idleTimeout` was removed from `DatabaseLevelIsolationStrategy` in @objectstack/spec 17 — its unit (seconds) lived in a source comment only and the published description named none, so a reader of the reference page could not tell 300 seconds from 300 milliseconds. Rename the key to `idleTimeoutSeconds`; the value (seconds) is unchanged. |
 | **usePooler** | `boolean` | optional (default: `true`) | Use connection pooler |
 
 ### Nested Shape: `DatabaseLevelIsolationStrategy.backup`
@@ -334,7 +334,7 @@ This schema accepts one of the following structures:
 | **poolSize** | `integer` | optional (default: `10`) | Connection pool size |
 | **maxActivePools** | `integer` | optional (default: `100`) | Max active pools |
 | **idleTimeoutSeconds** | `integer` | optional (default: `300`) | Idle pool timeout in seconds |
-| **idleTimeout** | `never` | optional | [REMOVED] `connectionPool.idleTimeout` was removed from `DatabaseLevelIsolationStrategy` in @objectstack/spec 17 (#14478) — its unit (seconds) lived in a source comment only and the published description named none, so a reader of the reference page could not tell 300 seconds from 300 milliseconds. Rename the key to `idleTimeoutSeconds`; the value (seconds) is unchanged. |
+| **idleTimeout** | `never` | optional | [REMOVED] `connectionPool.idleTimeout` was removed from `DatabaseLevelIsolationStrategy` in @objectstack/spec 17 — its unit (seconds) lived in a source comment only and the published description named none, so a reader of the reference page could not tell 300 seconds from 300 milliseconds. Rename the key to `idleTimeoutSeconds`; the value (seconds) is unchanged. |
 | **usePooler** | `boolean` | optional (default: `true`) | Use connection pooler |
 
 ### Nested Shape: `TenantIsolationConfig[strategy='isolated_db'].backup`
@@ -412,7 +412,7 @@ This schema accepts one of the following structures:
 | **requireSSO** | `boolean` | optional (default: `false`) | Require SSO |
 | **ipWhitelist** | `string[]` | optional | Allowed IP addresses |
 | **sessionTimeoutSeconds** | `integer` | optional (default: `3600`) | Session timeout in seconds |
-| **sessionTimeout** | `never` | optional | [REMOVED] `accessControl.sessionTimeout` was removed from `TenantSecurityPolicy` in @objectstack/spec 17 (#14478) — its unit (seconds) lived in a source comment only and the published description named none, so a reader of the reference page could not tell 3600 seconds from 3600 milliseconds. Rename the key to `sessionTimeoutSeconds`; the value (seconds) is unchanged. |
+| **sessionTimeout** | `never` | optional | [REMOVED] `accessControl.sessionTimeout` was removed from `TenantSecurityPolicy` in @objectstack/spec 17 — its unit (seconds) lived in a source comment only and the published description named none, so a reader of the reference page could not tell 3600 seconds from 3600 milliseconds. Rename the key to `sessionTimeoutSeconds`; the value (seconds) is unchanged. |
 
 ### Nested Shape: `TenantSecurityPolicy.compliance`
 

packages/spec/scripts/check-duration-unit-keys.ts

@@ -107,6 +107,18 @@ import ts from 'typescript';
 const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 const SRC_ROOT = join(pkgRoot, 'src');
 
+/**
+ * The dispatch-gates declaration — the `ROOT_DIR_WATCH_HINTS` idiom (#12310).
+ * `scripts/pm/dispatch-gates.mjs` derives which gates a card must run from the
+ * path literals in each gate's source, and `check:declared-population-live`
+ * refuses a gate whose only path-shaped literal names nothing in the tree.
+ * This gate walks exactly one subtree — `packages/spec/src/`, tests excluded —
+ * so that is what it declares, as a LITERAL (the extractor reads source text;
+ * a value computed from `SRC_ROOT` would produce no hint). The self-test holds
+ * the literal against the constant the scan actually reads from.
+ */
+export const ROOT_DIR_WATCH_HINTS = ['packages/spec/src/**'];
+
 /** Canonical unit → every spelling the describe prose or a key token may use. */
 const UNIT_SPELLINGS: Readonly<Record<string, readonly string[]>> = {
   ms: ['ms', 'msec', 'msecs', 'millis', 'millisecond', 'milliseconds'],
@@ -438,6 +450,13 @@ function selfTest(): number {
     rulesOf(`const S = z.object({ a: z.number().describe('Wait 1 second'), b: z.number().describe('A 15-minute window'), c: z.number().describe('Poll every 5 min'), d: z.number().describe('Debounce of 30 ms') });`)
       .join() === 'unit-in-prose-not-in-name,unit-in-prose-not-in-name,unit-in-prose-not-in-name,unit-in-prose-not-in-name');
 
+  // The declared population must be the population the scan reads (the
+  // ROOT_DIR_WATCH_HINTS idiom's coupling, held from this side).
+  const repoRoot = join(pkgRoot, '..', '..');
+  const declared = `${relative(repoRoot, SRC_ROOT).split('\\').join('/')}/**`;
+  expect(`declared population \`${ROOT_DIR_WATCH_HINTS.join(', ')}\` is the subtree the scan walks (\`${declared}\`)`,
+    ROOT_DIR_WATCH_HINTS.length === 1 && ROOT_DIR_WATCH_HINTS[0] === declared);
+
   console.log(failures === 0 ? '\nself-test: all cases pass' : `\nself-test: ${failures} case(s) FAILED`);
   return failures === 0 ? 0 : 1;
 }

packages/spec/src/data/driver.zod.ts

@@ -26,7 +26,7 @@ export const DriverOptionsSchema = lazySchema(() => z.object({
    */
   timeoutMs: z.number().optional().describe('Operation timeout in milliseconds'),
   timeout: retiredKey(
-    '`DriverOptions.timeout` was removed in @objectstack/spec 17 (#14478) — its unit (milliseconds) ' +
+    '`DriverOptions.timeout` was removed in @objectstack/spec 17 — its unit (milliseconds) ' +
     'lived only in the description. Rename the key to `timeoutMs`; the value (milliseconds) is unchanged.',
   ),
 

packages/spec/src/data/hook.zod.ts

@@ -330,7 +330,7 @@ export const HookSchema = lazySchema(() => strictObject(
    */
   timeoutMs: z.number().optional().describe('Maximum execution time in milliseconds before the hook is aborted'),
   timeout: retiredKey(
-    '`hook.timeout` was removed in @objectstack/spec 17 (#14478) — its unit (milliseconds) lived ' +
+    '`hook.timeout` was removed in @objectstack/spec 17 — its unit (milliseconds) lived ' +
     'only in the description, beside a body-level `timeoutMs` and a `retryPolicy.backoffMs` that ' +
     'spell theirs, so the same number read as two conventions on one surface. ' +
     'Rename the key to `timeoutMs`; the value (milliseconds) is unchanged. ' +

packages/spec/src/kernel/metadata-loader.zod.ts

@@ -88,7 +88,7 @@ export const MetadataManagerConfigSchema = lazySchema(() => z.object({
      */
     ttlSeconds: z.number().int().min(0).default(3600).describe('Cache TTL in seconds'),
     ttl: retiredKey(
-      '`cache.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 (#14478) — ' +
+      '`cache.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 — ' +
       'its unit (seconds) lived only in the description, while the nested `cache.databaseLoader.ttl` ' +
       'spelled the same word in milliseconds, so one key name meant two magnitudes 1000× apart. ' +
       'Rename the key to `ttlSeconds`; the value (seconds) is unchanged.',
@@ -109,7 +109,7 @@ export const MetadataManagerConfigSchema = lazySchema(() => z.object({
       ttlMs: z.number().int().min(0).default(60_000).describe('Cache TTL in milliseconds'),
       ttl: retiredKey(
         '`cache.databaseLoader.ttl` was removed from `MetadataManagerConfig` in @objectstack/spec 17 ' +
-        '(#14478) — its unit (milliseconds) lived only in the description, while the outer `cache.ttl` ' +
+        '— its unit (milliseconds) lived only in the description, while the outer `cache.ttl` ' +
         'spelled the same word in seconds, so one key name meant two magnitudes 1000× apart. ' +
         'Rename the key to `ttlMs`; the value (milliseconds) is unchanged.',
       ),