feat(spec): add prove-it-runs proof field + ratchet to liveness gate (ADR-0054 #1)

ADR-0054 follow-up (1): the liveness ledger's `live` meant only a static
consumer pointer — necessary but not sufficient, since a property can be live at
every layer yet broken end-to-end. This adds the third leg: high-risk authorable
properties must carry a `proof` (a dogfood test reference) that asserts the
runtime outcome.

- proof-registry.mts: the authoritative high-risk-class list (field types,
  analytics, RLS, flow nodes, form widgets) + which classes the ratchet enforces
  this phase. Field types and RLS are bound (matrix exists AND surface governed);
  analytics/flow/form are listed-but-blocked with honest reasons (their surface
  isn't governed yet / no proof yet — Phase 2).
- check-liveness.mts: a bound `live` entry must carry a valid `proof` of its own
  class. Validation is STATIC (file exists + declares the `@proof: <id>` tag) so
  the gate stays seconds-cheap; running the proof remains the dogfood gate's job.
  Reverse check flags unregistered `@proof:` tags.
- Ledger: field.type → field-zoo proof; permission.rowLevelSecurity.using →
  #1994 RLS proof. Dogfood proofs self-declare their `@proof:` tag.
- Gate now also triggers on packages/dogfood/** so deleting/renaming a proof
  re-runs the check and the dangling reference is caught.
- 15 unit + wiring tests; README documents the contract and ratchet.

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

Author: claude

.github/workflows/spec-liveness-check.yml

@@ -6,12 +6,18 @@ name: Spec Liveness Check
 # property of a GOVERNED type to declare a liveness status with evidence in
 # packages/spec/liveness/<type>.json. A new unclassified property fails the check (the
 # ratchet: no new undeclared surface). See packages/spec/liveness/README.md.
+#
+# ADR-0054 (prove-it-runs): bound high-risk 'live' properties must carry a `proof`
+# pointing to a dogfood test that declares the matching `@proof:` tag. The gate also
+# triggers on packages/dogfood/** so deleting/renaming a proof re-runs this check and
+# the dangling reference is caught (the proof files live outside packages/spec/).
 
 on:
   pull_request:
     types: [opened, synchronize, reopened]
     paths:
       - 'packages/spec/**'
+      - 'packages/dogfood/**'
 
 permissions:
   contents: read

packages/dogfood/test/analytics-timezone.dogfood.test.ts

@@ -3,6 +3,12 @@
 // GOLDEN REGRESSION for #1982 / #2018 — "organization timezone drives analytics
 // date bucketing", exercised end-to-end through the real HTTP + service stack.
 //
+// @proof: analytics-tz-bucketing
+// ADR-0054 runtime proof for the analytics high-risk class. Registered in
+// proof-registry.mts but NOT yet ledger-bound: the authorable surface
+// (dataset/report dimensions+measures) is not a GOVERNED liveness type yet, so
+// there is no entry to carry the proof. Binds once dataset/report are governed.
+//
 // This is the test that would have caught #2018 before merge. That bug passed
 // every static gate: it lived in the *integration* of NativeSQLStrategy routing
 // + in-memory count + REST execution-context resolution. Only booting the app

packages/dogfood/test/field-zoo-roundtrip.dogfood.test.ts

@@ -3,6 +3,11 @@
 // CAPABILITY-MATRIX golden test — every authorable field type must survive a
 // real HTTP write → read round-trip.
 //
+// @proof: field-type-roundtrip
+// ADR-0054 runtime proof for the field-type high-risk class. Referenced by the
+// liveness ledger entry `field.type` (packages/spec/liveness/field.json); the
+// spec liveness gate fails if this tag is removed. See proof-registry.mts.
+//
 // `showcase_field_zoo` carries one field of (almost) every protocol FieldType.
 // Until now it was only *static*-checked (the metadata bundle registers it);
 // nothing wrote a record and read it back. But the platform's value is that an

packages/dogfood/test/rls-fixture.dogfood.test.ts

@@ -2,6 +2,12 @@
 //
 // The HARD, revert-provable #1994 gate.
 //
+// @proof: rls-by-id-write
+// ADR-0054 runtime proof for the RLS / sharing high-risk class. Referenced by the
+// liveness ledger entry `permission.rowLevelSecurity.using`
+// (packages/spec/liveness/permission.json); the spec liveness gate fails if this
+// tag is removed. See proof-registry.mts.
+//
 // `auto-verify-rls.dogfood.test.ts` runs the cross-owner runner over the real
 // apps, but single-tenant boot strips the tenant policy so every object is
 // `member-visible` — the by-id-write path is never exercised. This test boots a

packages/spec/liveness/README.md

@@ -35,6 +35,57 @@ Resolution per property: **ledger entry → spec `.describe()` marker → UNCLAS
 Framework provenance/lock fields (`_lock*`, `_provenance`, `_packageId/Version`,
 `protection` — ADR-0010) are auto-classified `live`.
 
+## Runtime proofs — prove-it-runs (ADR-0054)
+
+`live` today means only *a static pointer to a consumer* — proof that something
+*reads* the property. That is necessary but not sufficient: a property can be live
+at every layer yet **broken end-to-end** (the break lives in the integration —
+engine ↔ driver ↔ service ↔ HTTP). [ADR-0054](../../../docs/adr/0054-runtime-proof-for-authorable-surface.md)
+adds the third leg: for a defined class of **high-risk** authorable properties, a
+`live` entry must carry a **`proof`** — a reference to a `@objectstack/dogfood` test
+that authors the property against the real in-process stack and asserts the runtime
+outcome.
+
+```jsonc
+"type": {
+  "status": "live",
+  "evidence": "packages/objectql/src/engine.ts",
+  "proof": "packages/dogfood/test/field-zoo-roundtrip.dogfood.test.ts#field-type-roundtrip"
+}
+```
+
+**The contract.** A `proof` is `"<repo-relative-file>#<proof-id>"`. The dogfood test
+self-declares the id with a greppable tag near its top:
+
+```ts
+// @proof: field-type-roundtrip
+```
+
+The gate validates **statically** (it never runs the test — that's the dogfood
+gate's job, keeping this gate seconds-cheap): the file must exist **and** declare the
+`@proof: <id>` tag. A bound entry must point at *its own class's* proof. The reverse
+is also checked: a `@proof:` tag under `packages/dogfood/test/**` that isn't
+registered in `../scripts/liveness/proof-registry.mts` is flagged (warning) so a new
+proof gets wired in.
+
+**The ratchet (the authoritative high-risk-class list).** Defined in
+`../scripts/liveness/proof-registry.mts`. A class is **CI-enforced** (`bound`) only
+once it has *both* a runtime proof *and* a governed ledger entry to carry it — the
+binding lands one class at a time (ADR-0054 §3), never as a big-bang backfill.
+
+| High-risk class | Bound? | Ledger binding | Proof |
+|---|---|---|---|
+| 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` |
+| Analytics dims/measures | ⛔ pending | — | `analytics-timezone.dogfood.test.ts#analytics-tz-bucketing` (proof exists; surface `dataset`/`report` not yet governed) |
+| Flow nodes | ⛔ pending | `flow.nodes.type` (candidate) | none yet (Phase 2) |
+| Form layout/section/widget | ⛔ pending | — | none yet (Phase 2) |
+
+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
+confirm the gate is green. Because the gate also triggers on `packages/dogfood/**`,
+deleting or renaming a proof re-runs this check and the dangling reference is caught.
+
 ## Author warnings — closing the loop (`authorWarn`)
 
 Classification is also fed back to the *author* at build time. The CLI `compile`

packages/spec/liveness/field.json

@@ -12,7 +12,9 @@
     },
     "type": {
       "status": "live",
-      "evidence": "packages/objectql/src/engine.ts"
+      "evidence": "packages/objectql/src/engine.ts",
+      "proof": "packages/dogfood/test/field-zoo-roundtrip.dogfood.test.ts#field-type-roundtrip",
+      "note": "ADR-0054 high-risk class (field types): the proof writes one record of (almost) every field type over the real HTTP API and asserts each reads back with type fidelity (rating/slider→number, toggle→boolean) — guarding the persistence + read-coercion integration that #2025 fixed."
     },
     "description": {
       "status": "live",

packages/spec/liveness/permission.json

@@ -92,7 +92,8 @@
         "using": {
           "status": "live",
           "evidence": "packages/plugins/plugin-security/src/rls-compiler.ts",
-          "note": "compiled into find + analytics SQL."
+          "proof": "packages/dogfood/test/rls-fixture.dogfood.test.ts#rls-by-id-write",
+          "note": "compiled into find + analytics SQL. ADR-0054 high-risk class (RLS): the proof boots an owner-isolated fixture so a fresh member cannot read an admin-created row, then asserts the runner's verdict in both directions — `rls-consistent` when the owner predicate also gates the by-id write (#1994 pre-image check) and `rls-hole` when it doesn't. Guards read AND by-id-write enforcement, not just the read predicate."
         },
         "check": {
           "status": "live",

packages/spec/scripts/liveness/check-liveness.mts

@@ -22,17 +22,30 @@
 // Statuses: live | experimental | planned | dead.  Resolution per property:
 //   ledger entry → spec `.describe()` marker ([EXPERIMENTAL — not enforced]) → UNCLASSIFIED
 //
+// PROVE-IT-RUNS (ADR-0054): a `live` entry may carry a `proof` (a dogfood test
+// reference `<file>#<proof-id>`). For the HIGH-RISK classes bound this phase
+// (see proof-registry.mts), a `live` classification MUST carry a valid proof —
+// the file must exist and declare the `@proof: <id>` tag. CI fails otherwise.
+//
 // Usage:
 //   tsx check-liveness.mts                 # check all governed types
 //   tsx check-liveness.mts --dump <type>   # inventory a type's properties (seeding aid)
 //   tsx check-liveness.mts --json          # machine-readable report
 
 process.env.OS_EAGER_SCHEMAS = '1';
 
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { getMetadataTypeSchema, listMetadataTypeSchemaTypes } from '../../src/kernel/metadata-type-schemas';
+import {
+  BOUND_PROOF_PATHS,
+  HIGH_RISK_CLASSES,
+  KNOWN_PROOF_IDS,
+  extractProofTags,
+  parseProofRef,
+  validateProofRef,
+} from './proof-registry.mts';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const specRoot = resolve(here, '../..'); // packages/spec
@@ -131,7 +144,17 @@ if (dumpIdx !== -1) {
 
 // ---- check ----
 const asJson = args.includes('--json');
-const report: any = { types: {}, totals: { byStatus: {} as Record<string, number> }, unclassified: [] as string[], staleEvidence: [] as string[] };
+const report: any = {
+  types: {},
+  totals: { byStatus: {} as Record<string, number> },
+  unclassified: [] as string[],
+  staleEvidence: [] as string[],
+  proofErrors: [] as string[], // a `proof` ref that doesn't resolve (missing file / missing tag / malformed)
+  proofMissing: [] as string[], // a bound high-risk `live` entry with no proof at all
+  orphanProofs: [] as string[], // a dogfood `@proof:` tag not registered in proof-registry.mts
+};
+
+const proofFs = { existsSync, readFileSync };
 
 function classify(type: string, path: string, status: string, led: any, cat: any) {
   cat.classified++;
@@ -141,6 +164,50 @@ function classify(type: string, path: string, status: string, led: any, cat: any
     const file = String(led.evidence).split(':')[0];
     if (/\//.test(file) && !existsSync(join(repoRoot, file))) report.staleEvidence.push(`${type}/${path} → ${led.evidence}`);
   }
+  // ── ADR-0054 prove-it-runs ──
+  const boundClass = BOUND_PROOF_PATHS.get(`${type}/${path}`);
+  if (led?.proof !== undefined) {
+    // Any declared proof is validated (no silent rot), bound or not.
+    const v = validateProofRef(led.proof, { repoRoot, fs: proofFs, join });
+    if (!v.ok) report.proofErrors.push(`${type}/${path} → ${v.error}`);
+    else if (boundClass) {
+      // A bound entry must point at ITS class's proof, not just any valid proof.
+      const id = parseProofRef(led.proof)?.id;
+      if (id !== boundClass.proofId) {
+        report.proofErrors.push(
+          `${type}/${path} → proof "${id}" is not the bound ${boundClass.label} proof ("${boundClass.proofId}")`,
+        );
+      }
+    }
+  } else if (boundClass && status === 'live') {
+    report.proofMissing.push(
+      `${type}/${path} (${boundClass.label}) — high-risk live property requires a proof: expected "${boundClass.proofRef}"`,
+    );
+  }
+}
+
+// Reverse integrity: every `@proof:` tag declared under the dogfood proof tree
+// must be registered in proof-registry.mts. An orphan tag means a proof was
+// written but never wired into the high-risk-class list — flag it (warning).
+function scanOrphanProofs() {
+  const proofDir = join(repoRoot, 'packages/dogfood/test');
+  if (!existsSync(proofDir)) return; // spec may be consumed standalone (published)
+  const walk = (dir: string): string[] => {
+    const out: string[] = [];
+    for (const ent of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) out.push(...walk(full));
+      else if (ent.isFile() && ent.name.endsWith('.ts')) out.push(full);
+    }
+    return out;
+  };
+  for (const file of walk(proofDir)) {
+    for (const tag of extractProofTags(readFileSync(file, 'utf8'))) {
+      if (!KNOWN_PROOF_IDS.has(tag)) {
+        report.orphanProofs.push(`@proof: ${tag} (in ${file.slice(repoRoot.length + 1)}) — not registered in proof-registry.mts`);
+      }
+    }
+  }
 }
 
 for (const type of GOVERNED) {
@@ -169,7 +236,11 @@ for (const type of GOVERNED) {
   report.types[type] = cat;
 }
 
+scanOrphanProofs();
+
 const totalUnclassified = report.unclassified.length;
+const totalProofFailures = report.proofErrors.length + report.proofMissing.length;
+const failed = totalUnclassified > 0 || totalProofFailures > 0;
 if (asJson) {
   process.stdout.write(JSON.stringify(report, null, 2) + '\n');
 } else {
@@ -178,15 +249,30 @@ if (asJson) {
     const parts = Object.entries(v.byStatus).map(([s, n]) => `${s} ${n}`).join(', ');
     console.log(`  ${t.padEnd(11)} ${v.classified} classified (${parts || '—'})${v.unclassified ? `, ${v.unclassified} UNCLASSIFIED` : ''}`);
   }
+  const boundClasses = HIGH_RISK_CLASSES.filter((c) => c.bound).map((c) => c.label);
+  console.log(`\nprove-it-runs (ADR-0054): proof REQUIRED for bound high-risk classes — ${boundClasses.join(', ') || 'none'}`);
   if (report.staleEvidence.length) {
     console.log(`\n⚠ ${report.staleEvidence.length} 'live' entr(ies) cite a missing file:`);
     report.staleEvidence.forEach((s: string) => console.log(`    ${s}`));
   }
+  if (report.orphanProofs.length) {
+    console.log(`\n⚠ ${report.orphanProofs.length} unregistered dogfood proof tag(s) — add to proof-registry.mts:`);
+    report.orphanProofs.forEach((s: string) => console.log(`    ${s}`));
+  }
+  if (report.proofMissing.length) {
+    console.log(`\n✗ ${report.proofMissing.length} high-risk 'live' propert(ies) missing a runtime proof:`);
+    report.proofMissing.forEach((s: string) => console.log(`    ${s}`));
+  }
+  if (report.proofErrors.length) {
+    console.log(`\n✗ ${report.proofErrors.length} proof reference(s) do not resolve:`);
+    report.proofErrors.forEach((s: string) => console.log(`    ${s}`));
+  }
   if (totalUnclassified) {
     console.log(`\n✗ ${totalUnclassified} UNCLASSIFIED — classify in packages/spec/liveness/<type>.json:`);
     report.unclassified.forEach((s: string) => console.log(`    ${s}`));
-  } else {
-    console.log('\n✓ all governed-type properties are classified.');
+  }
+  if (!failed) {
+    console.log('\n✓ all governed-type properties are classified; all bound high-risk proofs resolve.');
   }
 }
-process.exit(totalUnclassified > 0 ? 1 : 0);
+process.exit(failed ? 1 : 0);