feat(spec): govern dataset + bind the analytics high-risk class (ADR-0054)

claude · claude · commit 556c12560b32 · 2026-06-19T10:29:38.000Z
Unlocks the analytics binding that was previously blocked because its authorable surface wasn't governed. - Govern the `dataset` metadata type: new liveness/dataset.json classifies all 19 authorable props with file:line evidence from the analytics service consumer audit (26 live, 1 dead — measures.certified has no runtime consumer). `dataset` added to GOVERNED in check-liveness.mts. - Bind the analytics class: dataset.dimensions.dateGranularity carries the tz-bucketing proof (#1982/#2018) — the property whose org-timezone day-bucket behavior the proof asserts. proof-registry.mts flips analytics to bound. - Four high-risk classes now CI-enforced: field types, RLS, flow nodes, analytics. - README governed-types + high-risk tables updated; changeset description updated. Verified: liveness gate green (dataset 27 classified); 17 registry tests; the analytics proof runs green; full dogfood suite 59/59. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XVdnfUAx85amkerym26vdx
diff --git a/.changeset/liveness-prove-it-runs.md b/.changeset/liveness-prove-it-runs.md
@@ -2,4 +2,4 @@
 "@objectstack/spec": patch
 ---
 
-Add the ADR-0054 "prove-it-runs" proof field + ratchet to the spec liveness gate. A `live` ledger entry may now carry a `proof` — a reference (`<file>#<proof-id>`) to a dogfood test that asserts the property's runtime behavior. For the high-risk classes bound this phase (field types → `field.type`; RLS → `permission.rowLevelSecurity.using`), a `live` classification must carry a valid proof, validated statically by the liveness gate (the file exists and declares the matching `@proof:` tag). The authoritative high-risk-class list lives in `scripts/liveness/proof-registry.mts`; see `liveness/README.md`.
+Add the ADR-0054 "prove-it-runs" proof field + ratchet to the spec liveness gate. A `live` ledger entry may now carry a `proof` — a reference (`<file>#<proof-id>`) to a dogfood test that asserts the property's runtime behavior. A bound high-risk `live` property must carry a valid proof, validated statically by the liveness gate (the file exists and declares the matching `@proof:` tag). Four high-risk classes are bound this phase: field types (`field.type`), RLS (`permission.rowLevelSecurity.using`), flow nodes (`flow.nodes.type`), and analytics (`dataset.dimensions.dateGranularity`). The `dataset` metadata type is now governed (new `liveness/dataset.json`). The authoritative high-risk-class list lives in `scripts/liveness/proof-registry.mts`; see `liveness/README.md`.
diff --git a/packages/spec/liveness/README.md b/packages/spec/liveness/README.md
@@ -78,8 +78,8 @@ binding lands one class at a time (ADR-0054 §3), never as a big-bang backfill.
 | Field types | ✅ enforced | `field.type` | `field-zoo-roundtrip.dogfood.test.ts#field-type-roundtrip` |
 | RLS / sharing | ✅ enforced | `permission.rowLevelSecurity.using` | `rls-fixture.dogfood.test.ts#rls-by-id-write` |
 | Flow nodes | ✅ enforced | `flow.nodes.type` | `flow-node.dogfood.test.ts#flow-node-execution` |
-| Analytics dims/measures | ⛔ pending | — | `analytics-timezone.dogfood.test.ts#analytics-tz-bucketing` (proof exists; surface `dataset`/`report` not yet governed) |
-| Form layout/section/widget | ⛔ pending | — | none yet (Phase 2) |
+| Analytics dims/measures | ✅ enforced | `dataset.dimensions.dateGranularity` | `analytics-timezone.dogfood.test.ts#analytics-tz-bucketing` |
+| Form layout/section/widget | ⛔ pending | — | none yet (form surface not yet governed) |
 
 To bind a pending class: add its dogfood proof + `@proof:` tag, set `bound: true` and
 its `ledgerBindings` in `proof-registry.mts`, add the `proof` to the ledger entry, and
@@ -172,7 +172,8 @@ The governed set is `GOVERNED` at the top of `check-liveness.mts`. To add a type
 | agent | 18 | 4 | 5 | access/permissions/visibility dead (chat route hardcodes perms); autonomy experimental |
 | tool | 13 | 1 | 5 | write-only metadata; runtime uses a parallel AIToolDefinition |
 | skill | 15 | – | 2 | triggerPhrases dead (no matcher); permissions dead |
+| dataset | 26 | – | 1 | analytics semantic layer (compiled to a Cube); `measures.certified` dead; `dimensions.dateGranularity` carries the org-tz bucketing proof |
 
 The `dead` set across types is the enforce-or-remove worklist (ADR-0049). Not yet governed
-(rollout): view, page, dashboard, app, report, dataset, job, datasource, translation,
+(rollout): view, page, dashboard, app, report, job, datasource, translation,
 email_template, doc, book, validation, seed.
diff --git a/packages/spec/liveness/dataset.json b/packages/spec/liveness/dataset.json
@@ -0,0 +1,109 @@
+{
+  "type": "dataset",
+  "_note": "DatasetSchema (analytics semantic layer). Consumer: @objectstack/service-analytics — compileDataset() turns a dataset into a Cube, DatasetExecutor runs the query. Seeded from a dataset-property consumer audit (file:line evidence in service-analytics). ADR-0054: dimensions.dateGranularity carries the org-timezone date-bucketing proof (#1982/#2018). Framework provenance/lock fields auto-live.",
+  "props": {
+    "name": {
+      "status": "live",
+      "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:178",
+      "note": "registry key + compiled Cube name."
+    },
+    "label": {
+      "status": "live",
+      "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:179",
+      "note": "compiled into Cube title for presentations."
+    },
+    "description": {
+      "status": "live",
+      "note": "display/doc metadata (presentations); not read by analytics execution."
+    },
+    "object": {
+      "status": "live",
+      "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:180",
+      "note": "base table — Cube sql + join resolution + draft-rows resolver."
+    },
+    "include": {
+      "status": "live",
+      "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:92",
+      "note": "compiled into Cube joins + the NativeSQLStrategy join allowlist (ADR-0021)."
+    },
+    "filter": {
+      "status": "live",
+      "evidence": "packages/services/service-analytics/src/dataset-executor.ts:205",
+      "note": "dataset-level WHERE, ANDed with runtime + measure-scoped filters."
+    },
+    "dimensions": {
+      "children": {
+        "name": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:141",
+          "note": "dimension identifier (Cube dimension key)."
+        },
+        "label": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:142",
+          "note": "compiled into Cube dimension for presentations."
+        },
+        "field": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:144",
+          "note": "emitted as the dimension's SQL column reference (relationship-validated)."
+        },
+        "type": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:143",
+          "note": "dimensionType() maps to Cube time/number/boolean/string; drives grouping."
+        },
+        "dateGranularity": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:146",
+          "proof": "packages/dogfood/test/analytics-timezone.dogfood.test.ts#analytics-tz-bucketing",
+          "note": "ADR-0054 high-risk class (analytics): a time dimension's single granularity auto-buckets at query time (dataset-executor.ts:272-287); the proof asserts the day bucket SHIFTS with the org timezone (2024-03-01T03:00Z buckets to 2024-02-29 in America/Los_Angeles) — guarding the analytics-strategy ↔ in-memory count ↔ REST exec-context integration that #2018 fixed."
+        }
+      }
+    },
+    "measures": {
+      "children": {
+        "name": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:166",
+          "note": "measure identifier + derived-measure reference."
+        },
+        "label": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/analytics-service.ts:479",
+          "note": "compiled into Cube metric + enriched onto result fields."
+        },
+        "aggregate": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:60",
+          "note": "aggregateToMetricType() → Cube metric type (sum/count/avg/…); unsupported aggregates throw."
+        },
+        "field": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-compiler.ts:170",
+          "note": "SQL aggregate operand (count omits field → '*'); relationship-validated."
+        },
+        "filter": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-executor.ts:225",
+          "note": "measure-scoped WHERE, applied via a supplementary per-measure query."
+        },
+        "format": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/analytics-service.ts:480",
+          "note": "compiled into Cube metric + enriched onto result fields for the renderer."
+        },
+        "certified": {
+          "status": "dead",
+          "evidence": "no runtime consumer — analytics execution never reads it; not compiled into the Cube",
+          "note": "measure trust/governance flag, declared but unenforced (ADR-0049 enforce-or-remove candidate). Not authorWarn'd: it may surface as an objectui badge, so it is not necessarily misleading."
+        },
+        "derived": {
+          "status": "live",
+          "evidence": "packages/services/service-analytics/src/dataset-executor.ts:247",
+          "note": "post-aggregation arithmetic (ratio/sum/difference/product) over base measures; {op, of} both consumed."
+        }
+      }
+    }
+  }
+}
diff --git a/packages/spec/scripts/liveness/check-liveness.mts b/packages/spec/scripts/liveness/check-liveness.mts
@@ -53,7 +53,7 @@ const repoRoot = resolve(specRoot, '../..');
 const ledgerRoot = join(specRoot, 'liveness');
 
 // Governed metadata types, rolled out highest-frequency / highest-risk first.
-const GOVERNED = ['object', 'field', 'flow', 'action', 'hook', 'permission', 'role', 'agent', 'tool', 'skill'];
+const GOVERNED = ['object', 'field', 'flow', 'action', 'hook', 'permission', 'role', 'agent', 'tool', 'skill', 'dataset'];
 
 // ADR-0010 provenance/lock overlay fields — system-stamped, on every type; auto-live.
 const FRAMEWORK_FIELDS = new Set([
diff --git a/packages/spec/scripts/liveness/proof-registry.mts b/packages/spec/scripts/liveness/proof-registry.mts
@@ -81,14 +81,11 @@ export const HIGH_RISK_CLASSES: HighRiskClass[] = [
     label: 'Analytics dimensions / measures',
     summary: 'date-dimension bucketing / aggregation under the org timezone (#1982/#2018).',
     proofId: 'analytics-tz-bucketing',
-    // The proof EXISTS (golden tz-bucketing regression) and is tagged, so it is a
-    // known proof — but it cannot be BOUND yet (see blockedReason).
     proofRef: 'packages/dogfood/test/analytics-timezone.dogfood.test.ts#analytics-tz-bucketing',
-    bound: false,
-    ledgerBindings: [],
-    blockedReason:
-      'the authorable surface (dataset/report dimensions+measures) is not yet a GOVERNED ledger type, ' +
-      'so there is no entry to carry the proof. Bind once dataset/report are governed.',
+    bound: true,
+    // The org-timezone shift acts on a time dimension's bucketing granularity —
+    // the property whose end-to-end correctness the tz proof guards.
+    ledgerBindings: [{ type: 'dataset', path: 'dimensions.dateGranularity' }],
   },
   {
     id: 'flow-node',
diff --git a/packages/spec/scripts/liveness/proof-registry.test.ts b/packages/spec/scripts/liveness/proof-registry.test.ts
@@ -102,7 +102,12 @@ describe('registry invariants', () => {
 
   it('BOUND_PROOF_PATHS maps the expected entries this phase', () => {
     expect([...BOUND_PROOF_PATHS.keys()].sort()).toEqual(
-      ['field/type', 'flow/nodes.type', 'permission/rowLevelSecurity.using'].sort(),
+      [
+        'field/type',
+        'flow/nodes.type',
+        'permission/rowLevelSecurity.using',
+        'dataset/dimensions.dateGranularity',
+      ].sort(),
     );
   });
 
@@ -120,6 +125,7 @@ describe('real proof wiring resolves', () => {
     field: 'packages/spec/liveness/field.json',
     permission: 'packages/spec/liveness/permission.json',
     flow: 'packages/spec/liveness/flow.json',
+    dataset: 'packages/spec/liveness/dataset.json',
   };
 
   function ledgerEntry(type: string, path: string): any {
@@ -144,8 +150,10 @@ describe('real proof wiring resolves', () => {
     }
   }
 
-  it('the analytics proof file exists and declares its tag (registered, pending bind)', () => {
-    const analytics = HIGH_RISK_CLASSES.find((c) => c.id === 'analytics')!;
-    expect(validateProofRef(analytics.proofRef, { repoRoot, fs, join })).toEqual({ ok: true });
+  it('no bound class is left with an unresolved proof or a blockedReason', () => {
+    for (const cls of HIGH_RISK_CLASSES.filter((c) => c.bound)) {
+      expect(cls.blockedReason, `${cls.id} is bound but still records a blockedReason`).toBeUndefined();
+      expect(validateProofRef(cls.proofRef, { repoRoot, fs, join })).toEqual({ ok: true });
+    }
   });
 });
