fix(spec): address contract review — card id out of the refusal string, prescription module-private, docblock adjacency (#17296)

R1: `check:doc-authoring` reds on an internal issue id inside a customer-facing
string. The refusal now reads `(ADR-0049 enforce-or-remove)`, matching how
driver-memory's twin already spells it. No pin asserted the id.

R2: `timeUpdateIntervalRefusalMessage` had zero consumers outside its own error
map, so it is module-private now — the `CRYPTO_HASH_RETIRED` shape an enum-value
narrowing takes. `RETIRED_SUB_DAY_INTERVALS` stays exported; it has real
cross-package readers. Both inventories regenerated.

R3: the new conversion had been inserted between an existing docblock and the
symbol it documents. It moves below `metricFiltersRemoved`; the
`CONVERSIONS_BY_MAJOR` order is unchanged.

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

Author: os-bill

packages/spec/api-surface/data.json

@@ -827,7 +827,6 @@
     "suggestDefaultValueToken (function)",
     "suggestFieldTypeForSqlType (function)",
     "textOperatorDoorVerdict (function)",
-    "timeUpdateIntervalRefusalMessage (function)",
     "unprovisionedInjectedColumns (function)",
     "urlCredentialQueryParams (function)",
     "urlUserinfoPassword (function)",

packages/spec/export-origins/data.json

@@ -814,7 +814,6 @@
     "suggestDefaultValueToken": "src/data/default-value-shape.ts#suggestDefaultValueToken (function)",
     "suggestFieldTypeForSqlType": "src/data/type-compat.ts#suggestFieldTypeForSqlType (function)",
     "textOperatorDoorVerdict": "src/data/filter-text-operator-declared-type.ts#textOperatorDoorVerdict (function)",
-    "timeUpdateIntervalRefusalMessage": "src/data/analytics.zod.ts#timeUpdateIntervalRefusalMessage (function)",
     "unprovisionedInjectedColumns": "src/data/injected-system-column-provenance.ts#unprovisionedInjectedColumns (function)",
     "urlCredentialQueryParams": "src/data/driver/common.zod.ts#urlCredentialQueryParams (function)",
     "urlUserinfoPassword": "src/data/driver/common.zod.ts#urlUserinfoPassword (function)",

packages/spec/src/conversions/registry.ts

@@ -7391,6 +7391,80 @@ const fieldColumnListsCanonicalized: MetadataConversion = {
  * cube's `measures` RECORD (keyed by name), one level below the collection
  * item, so the top-level-only `stripKeys` runs per metric, not per cube.
  */
+const metricFiltersRemoved: MetadataConversion = {
+  id: 'metric-filters-removed',
+  toMajor: 18,
+  retiredFromLoadPath: true,
+  surface: 'analyticsCubes[].measures.<metric>.filters',
+  summary:
+    "cube metric key 'filters' removed (#10414, ADR-0049 — no strategy ever read it: the "
+    + 'authored raw-SQL condition was parsed and dropped, and the query returned the '
+    + "unfiltered aggregate. Filter at query time with `where`, fold the condition into the "
+    + "metric's own `sql` expression, or use an ADR-0021 dataset measure's structured `filter`)",
+  apply(stack, emit) {
+    return mapCollection(stack, 'analyticsCubes', (cube, path) => {
+      const measures = cube.measures;
+      if (!isDict(measures)) return cube;
+      let touched = false;
+      const nextMeasures: Record<string, unknown> = { ...measures };
+      for (const [name, metric] of Object.entries(measures)) {
+        if (!isDict(metric)) continue;
+        const stripped = stripKeys(metric, ['filters'], emit, `${path}.measures.${name}`);
+        if (stripped === metric) continue;
+        nextMeasures[name] = stripped;
+        touched = true;
+      }
+      if (!touched) return cube;
+      return { ...cube, measures: nextMeasures };
+    });
+  },
+  fixture: {
+    before: {
+      analyticsCubes: [{
+        name: 'orders',
+        sql: 'orders',
+        measures: {
+          // The card's measured shape: parsed, registered, returned unfiltered.
+          closed_won_revenue: {
+            name: 'closed_won_revenue',
+            label: 'Closed-Won Revenue',
+            type: 'sum',
+            sql: 'amount',
+            filters: [{ sql: "stage = 'closed_won'" }],
+          },
+          // A metric WITHOUT the key rides through untouched — the strip
+          // dispatches on key presence, and the copy-on-write contract keeps
+          // the reference.
+          order_count: { name: 'order_count', label: 'Orders', type: 'count', sql: 'id' },
+        },
+        dimensions: {
+          stage: { name: 'stage', label: 'Stage', type: 'string', sql: 'stage' },
+        },
+      }],
+    },
+    after: {
+      analyticsCubes: [{
+        name: 'orders',
+        sql: 'orders',
+        measures: {
+          closed_won_revenue: {
+            name: 'closed_won_revenue',
+            label: 'Closed-Won Revenue',
+            type: 'sum',
+            sql: 'amount',
+          },
+          order_count: { name: 'order_count', label: 'Orders', type: 'count', sql: 'id' },
+        },
+        dimensions: {
+          stage: { name: 'stage', label: 'Stage', type: 'string', sql: 'stage' },
+        },
+      }],
+    },
+    // One notice: the single metric carrying `filters`.
+    expectedNotices: 1,
+  },
+};
+
 /**
  * `dimensions.<dim>.granularities` — the three sub-day names `TimeUpdateInterval`
  * declared until protocol 18 (#17296, ADR-0049 enforce-or-remove).
@@ -7497,80 +7571,6 @@ const cubeSubDayGranularitiesRemoved: MetadataConversion = {
   },
 };
 
-const metricFiltersRemoved: MetadataConversion = {
-  id: 'metric-filters-removed',
-  toMajor: 18,
-  retiredFromLoadPath: true,
-  surface: 'analyticsCubes[].measures.<metric>.filters',
-  summary:
-    "cube metric key 'filters' removed (#10414, ADR-0049 — no strategy ever read it: the "
-    + 'authored raw-SQL condition was parsed and dropped, and the query returned the '
-    + "unfiltered aggregate. Filter at query time with `where`, fold the condition into the "
-    + "metric's own `sql` expression, or use an ADR-0021 dataset measure's structured `filter`)",
-  apply(stack, emit) {
-    return mapCollection(stack, 'analyticsCubes', (cube, path) => {
-      const measures = cube.measures;
-      if (!isDict(measures)) return cube;
-      let touched = false;
-      const nextMeasures: Record<string, unknown> = { ...measures };
-      for (const [name, metric] of Object.entries(measures)) {
-        if (!isDict(metric)) continue;
-        const stripped = stripKeys(metric, ['filters'], emit, `${path}.measures.${name}`);
-        if (stripped === metric) continue;
-        nextMeasures[name] = stripped;
-        touched = true;
-      }
-      if (!touched) return cube;
-      return { ...cube, measures: nextMeasures };
-    });
-  },
-  fixture: {
-    before: {
-      analyticsCubes: [{
-        name: 'orders',
-        sql: 'orders',
-        measures: {
-          // The card's measured shape: parsed, registered, returned unfiltered.
-          closed_won_revenue: {
-            name: 'closed_won_revenue',
-            label: 'Closed-Won Revenue',
-            type: 'sum',
-            sql: 'amount',
-            filters: [{ sql: "stage = 'closed_won'" }],
-          },
-          // A metric WITHOUT the key rides through untouched — the strip
-          // dispatches on key presence, and the copy-on-write contract keeps
-          // the reference.
-          order_count: { name: 'order_count', label: 'Orders', type: 'count', sql: 'id' },
-        },
-        dimensions: {
-          stage: { name: 'stage', label: 'Stage', type: 'string', sql: 'stage' },
-        },
-      }],
-    },
-    after: {
-      analyticsCubes: [{
-        name: 'orders',
-        sql: 'orders',
-        measures: {
-          closed_won_revenue: {
-            name: 'closed_won_revenue',
-            label: 'Closed-Won Revenue',
-            type: 'sum',
-            sql: 'amount',
-          },
-          order_count: { name: 'order_count', label: 'Orders', type: 'count', sql: 'id' },
-        },
-        dimensions: {
-          stage: { name: 'stage', label: 'Stage', type: 'string', sql: 'stage' },
-        },
-      }],
-    },
-    // One notice: the single metric carrying `filters`.
-    expectedNotices: 1,
-  },
-};
-
 /**
  * `record:highlights` highlight-field `icon` — a declared, advertised key with
  * zero read points (#10054, ADR-0049 enforce-or-remove; maintainer ruling

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

@@ -98,13 +98,23 @@ export const RETIRED_SUB_DAY_INTERVALS = ['second', 'minute', 'hour'] as const;
  * - a RETIRED sub-day name is a value this enum used to declare, so the
  *   prescription is the retirement — what replaced it and the migrate line;
  * - anything else was never declared, so the prescription is the vocabulary.
+ *
+ * **Module-private**, which is the shape this kind of retirement takes:
+ * `hook-body.zod.ts`'s `CRYPTO_HASH_RETIRED` is the matching precedent — a
+ * prescription an enum's own error map consumes and nothing else does. The
+ * sibling {@link analyticsDateRangeRefusalMessage} is exported because a
+ * cross-file pin asserts `toBe(...)` against it, so the export IS the single
+ * source of that expected string; this one has no such consumer, and
+ * `driver-memory`'s door deliberately words its own sentence for its own
+ * surface rather than re-emitting this one. An export with no reader is a
+ * published surface the next narrowing has to keep.
  */
-export function timeUpdateIntervalRefusalMessage(input: unknown): string {
+function timeUpdateIntervalRefusalMessage(input: unknown): string {
   const received = typeof input === 'string' ? `'${input}'` : JSON.stringify(input) ?? String(input);
   const declared = DateGranularity.options.join(', ');
   if (typeof input === 'string' && (RETIRED_SUB_DAY_INTERVALS as readonly string[]).includes(input)) {
     return (
-      `Time interval ${received} was retired in protocol 18 (#17296, ADR-0049 enforce-or-remove). `
+      `Time interval ${received} was retired in protocol 18 (ADR-0049 enforce-or-remove). `
       + 'No backend ever bucketed it and none could advertise it: the canonical bucket-key '
       + 'vocabulary and `supports.queryDateGranularity` both stop at '
       + `${declared}, so the name resolved to a refusal or to one group per distinct timestamp. `