feat: add the declared-fact registry and drift audit

.github/workflows/ci.yml

@@ -308,6 +308,9 @@ jobs:
       - name: Audit CI path filters
         run: npm run audit:ci-paths
 
+      - name: Audit declared facts
+        run: npm run audit:facts
+
       - name: Audit agent surfaces
         run: npm run audit:agents
 

AGENTS.md

@@ -15,6 +15,7 @@ This document provides an overview for AI agents working across the OpenIAP mono
 | Docs Patterns           | [`knowledge/internal/05-docs-patterns.md`](knowledge/internal/05-docs-patterns.md)                                                                                         |
 | Git & Deployment        | [`knowledge/internal/06-git-deployment.md`](knowledge/internal/06-git-deployment.md)                                                                                       |
 | Docs Consistency / SSOT | [`knowledge/internal/07-docs-consistency.md`](knowledge/internal/07-docs-consistency.md) (run `bun audit:docs` before pushing API/Type doc edits)                          |
+| Fact Graph (Declared Facts) | [`knowledge/internal/08-fact-graph.md`](knowledge/internal/08-fact-graph.md) (run `bun audit:facts` after bumping a tool version or runner image) |
 
 ## Monorepo Structure
 
@@ -370,3 +371,4 @@ All comprehensive rules are documented in [`knowledge/internal/`](knowledge/inte
 5. **05-docs-patterns.md** - React modal patterns, component organization
 6. **06-git-deployment.md** - Commit format, deployment workflows
 7. **07-docs-consistency.md** - Docs/API/type consistency audits
+8. **08-fact-graph.md** - Declared-fact registry and drift audit

knowledge/_agent-context/context.md

@@ -1,7 +1,7 @@
 # OpenIAP Project Context
 
 > **Auto-generated shared context for AI assistants**
-> Last updated: 2026-08-18T17:50:47.669Z
+> Last updated: 2026-08-20T15:02:26.238Z
 >
 > Canonical file: `knowledge/_agent-context/context.md`
 
@@ -2806,6 +2806,110 @@ bun run audit:docs
 Exit code 1 means at least one drift; 0 means clean.
 
 
+---
+
+<!-- Source: internal/08-fact-graph.md -->
+
+# Fact Graph — Declared-Fact Consistency
+
+One cross-cutting scalar (a tool version, a runner image) gets declared in
+many files. When someone bumps most of them, the leftover breaks — usually in
+the one lane nobody runs until a release. This system makes that class of
+drift fail CI instead.
+
+Real incidents this system would have caught (all shipped 2026-08-20):
+
+- `release-godot.yml` still on `macos-15` after six other release lanes moved
+  to `macos-26` — surfaced as a 9-minute runner wait during a live release.
+- `Example/project.godot` declaring Godot 4.5 features while the Makefile and
+  every CI lane pinned 4.7.1 — the editor rewrote the file on every open.
+
+## Model
+
+`scripts/facts.mjs` is the registry. Each **fact** declares:
+
+- `values` — named roles for the values that may legitimately coexist
+  (`{ current: "4.7.1", minimum: "4.3" }`). One role means uniformity.
+- `scanners` — regexes with one capture group, run over file sets.
+
+`scripts/audit-facts.mjs` enforces two rules:
+
+1. Every occurrence a scanner finds must be one of the declared values.
+2. Every declared value must still occur somewhere.
+
+Rule 2 is what makes bumps atomic: change the registry and every stale
+occurrence fails; change a file and the unregistered value fails. There is
+deliberately **no per-site list** — an unlisted site cannot drift silently
+because the scanner sees it anyway.
+
+`DERIVED` relations express one declaration computed from another
+(`project.godot` features = major.minor of `godot.version.current`) instead of
+duplicating the value.
+
+## Querying impact
+
+`bun run graph:impact <fact-key>` answers "what does bumping this touch?"
+before you start: every declaring file with line numbers, declarations derived
+from the fact, and the CI jobs that run when those files change (via the same
+path-filter model `audit-ci-path-filters` proves against CI). Read-only —
+`--list` names the registered facts.
+
+## Authority direction
+
+The registry is authoritative; files follow it. When the audit fails, the fix
+is to finish the bump — never to edit the registry to match a stray file
+unless the stray file is the intended new value.
+
+## Boundaries (do not absorb these)
+
+| Domain                              | Owner                                         |
+| ----------------------------------- | --------------------------------------------- |
+| Generated type files source→targets | `packages/gql/generated-sync-manifest.mjs`    |
+| Package/spec version floor          | `openiap-versions.json` + release-state audit |
+| API surface parity across languages | `scripts/audit-non-godot-parity.mjs`          |
+| Change→job routing                  | `scripts/audit-ci-path-filters.mjs`           |
+
+The fact graph holds scalar declarations only, and it is deliberately
+**additive**: it changes no existing guard. Where a parity-audit needle pins
+the same scalar today, both guards run — they cannot contradict each other,
+since both compare against the same files, but a bump touches both until the
+consolidation phase below. Removing the single CI step disables the whole
+system; nothing else depends on it.
+
+## Authoring rules
+
+- Anchor patterns to structural keys (`java-version:`), never bare numbers.
+- A deliberately divergent value (Node 20 for builds, 24 for npm publish) is
+  either two roles in one fact or out of scope — never an unexplained skip.
+- **Every new fact ships with a planted-violation test** in
+  `scripts/audit-facts.test.mjs`: edit a real file in memory, assert the audit
+  reports it. A guard that has never seen its bug fire is unverified
+  (the release-sync guard shipped broken exactly this way).
+
+## Limits
+
+Agreement is not correctness: `supported_platforms` was consistent across all
+four copies and every copy was wrong, because Godot never read the key. The
+fact graph catches drift between declarations; it cannot tell whether the
+declaration means anything. Semantic validity stays with tests and e2e.
+
+Coverage is bounded by the scanners: a declaration in a file no scanner
+reads, or in a shape no pattern captures, is invisible. "An unlisted site
+cannot drift silently" holds within scanned files only — when a fact grows a
+new home (a shell script embedding a version, a new manifest), extend the
+scanner in the same change.
+
+## Roadmap
+
+1. **Done** — toolchain facts (Xcode, macOS image, JDK, Bun, Godot) plus the
+   Example-project derivation.
+2. Consolidate: move parity-audit needles that assert scalar pins into the
+   registry, shrinking `audit-non-godot-parity.mjs` toward behavior-only
+   assertions. Opt-in, after the registry has caught real drift in practice.
+3. Derive CI path-filter expectations from a package→path→job edge list
+   instead of asserting them post hoc.
+
+
 ---
 
 <!-- Source: internal/sandbox-subscription-billing-issue.md -->

knowledge/internal/08-fact-graph.md

@@ -0,0 +1,98 @@
+# Fact Graph — Declared-Fact Consistency
+
+One cross-cutting scalar (a tool version, a runner image) gets declared in
+many files. When someone bumps most of them, the leftover breaks — usually in
+the one lane nobody runs until a release. This system makes that class of
+drift fail CI instead.
+
+Real incidents this system would have caught (all shipped 2026-08-20):
+
+- `release-godot.yml` still on `macos-15` after six other release lanes moved
+  to `macos-26` — surfaced as a 9-minute runner wait during a live release.
+- `Example/project.godot` declaring Godot 4.5 features while the Makefile and
+  every CI lane pinned 4.7.1 — the editor rewrote the file on every open.
+
+## Model
+
+`scripts/facts.mjs` is the registry. Each **fact** declares:
+
+- `values` — named roles for the values that may legitimately coexist
+  (`{ current: "4.7.1", minimum: "4.3" }`). One role means uniformity.
+- `scanners` — regexes with one capture group, run over file sets.
+
+`scripts/audit-facts.mjs` enforces two rules:
+
+1. Every occurrence a scanner finds must be one of the declared values.
+2. Every declared value must still occur somewhere.
+
+Rule 2 is what makes bumps atomic: change the registry and every stale
+occurrence fails; change a file and the unregistered value fails. There is
+deliberately **no per-site list** — an unlisted site cannot drift silently
+because the scanner sees it anyway.
+
+`DERIVED` relations express one declaration computed from another
+(`project.godot` features = major.minor of `godot.version.current`) instead of
+duplicating the value.
+
+## Querying impact
+
+`bun run graph:impact <fact-key>` answers "what does bumping this touch?"
+before you start: every declaring file with line numbers, declarations derived
+from the fact, and the CI jobs that run when those files change (via the same
+path-filter model `audit-ci-path-filters` proves against CI). Read-only —
+`--list` names the registered facts.
+
+## Authority direction
+
+The registry is authoritative; files follow it. When the audit fails, the fix
+is to finish the bump — never to edit the registry to match a stray file
+unless the stray file is the intended new value.
+
+## Boundaries (do not absorb these)
+
+| Domain                              | Owner                                         |
+| ----------------------------------- | --------------------------------------------- |
+| Generated type files source→targets | `packages/gql/generated-sync-manifest.mjs`    |
+| Package/spec version floor          | `openiap-versions.json` + release-state audit |
+| API surface parity across languages | `scripts/audit-non-godot-parity.mjs`          |
+| Change→job routing                  | `scripts/audit-ci-path-filters.mjs`           |
+
+The fact graph holds scalar declarations only, and it is deliberately
+**additive**: it changes no existing guard. Where a parity-audit needle pins
+the same scalar today, both guards run — they cannot contradict each other,
+since both compare against the same files, but a bump touches both until the
+consolidation phase below. Removing the single CI step disables the whole
+system; nothing else depends on it.
+
+## Authoring rules
+
+- Anchor patterns to structural keys (`java-version:`), never bare numbers.
+- A deliberately divergent value (Node 20 for builds, 24 for npm publish) is
+  either two roles in one fact or out of scope — never an unexplained skip.
+- **Every new fact ships with a planted-violation test** in
+  `scripts/audit-facts.test.mjs`: edit a real file in memory, assert the audit
+  reports it. A guard that has never seen its bug fire is unverified
+  (the release-sync guard shipped broken exactly this way).
+
+## Limits
+
+Agreement is not correctness: `supported_platforms` was consistent across all
+four copies and every copy was wrong, because Godot never read the key. The
+fact graph catches drift between declarations; it cannot tell whether the
+declaration means anything. Semantic validity stays with tests and e2e.
+
+Coverage is bounded by the scanners: a declaration in a file no scanner
+reads, or in a shape no pattern captures, is invisible. "An unlisted site
+cannot drift silently" holds within scanned files only — when a fact grows a
+new home (a shell script embedding a version, a new manifest), extend the
+scanner in the same change.
+
+## Roadmap
+
+1. **Done** — toolchain facts (Xcode, macOS image, JDK, Bun, Godot) plus the
+   Example-project derivation.
+2. Consolidate: move parity-audit needles that assert scalar pins into the
+   registry, shrinking `audit-non-godot-parity.mjs` toward behavior-only
+   assertions. Opt-in, after the registry has caught real drift in practice.
+3. Derive CI path-filter expectations from a package→path→job edge list
+   instead of asserting them post hoc.

package.json

@@ -30,7 +30,9 @@
     "deploy": "./scripts/deploy.sh",
     "deploy:kit": "cd packages/kit && npx convex deploy",
     "prepare": "husky",
-    "audit:release-sync": "node --test scripts/audit-release-sync-script.test.mjs && node scripts/audit-release-sync-script.mjs"
+    "audit:release-sync": "node --test scripts/audit-release-sync-script.test.mjs && node scripts/audit-release-sync-script.mjs",
+    "audit:facts": "node --test scripts/audit-facts.test.mjs scripts/graph-impact.test.mjs && node scripts/audit-facts.mjs",
+    "graph:impact": "node scripts/graph-impact.mjs"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",

scripts/audit-facts.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Enforce the declared-fact registry in scripts/facts.mjs: every occurrence a
+// scanner finds must be one of the fact's declared values, and every declared
+// value must still occur — a bumped fact with stale occurrences fails, and so
+// does a dead declaration. See knowledge/internal/08-fact-graph.md.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { FACTS, DERIVED } from "./facts.mjs";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const WORKFLOW_GLOB = "/*.{yml,yaml}";
+
+function listRepoDir(dir) {
+  return readdirSync(join(REPO_ROOT, dir));
+}
+
+export function expandFiles(specs, listDir = listRepoDir) {
+  const files = [];
+  for (const spec of specs) {
+    if (!spec.endsWith(WORKFLOW_GLOB)) {
+      files.push(spec);
+      continue;
+    }
+    const dir = spec.slice(0, -WORKFLOW_GLOB.length);
+    for (const entry of listDir(dir)) {
+      if (entry.endsWith(".yml") || entry.endsWith(".yaml")) {
+        files.push(`${dir}/${entry}`);
+      }
+    }
+  }
+  return files;
+}
+
+// Every occurrence of a fact's shape, as {file, line, value} — shared by the
+// audit and the impact query so they can never disagree about what exists.
+export function scanFact(fact, readFile) {
+  const occurrences = [];
+  const missing = [];
+  for (const scanner of fact.scanners) {
+    for (const file of expandFiles(scanner.files)) {
+      const text = readFile(file);
+      if (text === null) {
+        missing.push(file);
+        continue;
+      }
+      for (const match of text.matchAll(scanner.pattern)) {
+        occurrences.push({
+          file,
+          line: text.slice(0, match.index).split("\n").length,
+          value: match[1],
+        });
+      }
+    }
+  }
+  return { occurrences, missing };
+}
+
+export function auditFacts(readFile) {
+  const failures = [];
+
+  for (const fact of FACTS) {
+    const allowed = new Map(
+      Object.entries(fact.values).map(([role, value]) => [value, role]),
+    );
+    const seen = new Set();
+
+    const { occurrences, missing } = scanFact(fact, readFile);
+    for (const file of missing) {
+      failures.push(`${fact.key}: scanned file is missing: ${file}`);
+    }
+    for (const { file, line, value } of occurrences) {
+      if (!allowed.has(value)) {
+        failures.push(
+          `${fact.key}: ${file}:${line} declares "${value}" but the ` +
+            `registry allows ${JSON.stringify(fact.values)}`,
+        );
+      }
+      seen.add(value);
+    }
+
+    for (const [value, role] of allowed) {
+      if (!seen.has(value)) {
+        failures.push(
+          `${fact.key}: declared ${role}="${value}" no longer occurs anywhere — ` +
+            `update or remove it from scripts/facts.mjs`,
+        );
+      }
+    }
+  }
+
+  for (const relation of DERIVED) {
+    const fact = FACTS.find((entry) => entry.key === relation.from.fact);
+    const expected = relation.derive(fact.values[relation.from.value]);
+    const text = readFile(relation.file);
+    if (text === null) {
+      failures.push(`${relation.key}: file is missing: ${relation.file}`);
+      continue;
+    }
+    const match = relation.pattern.exec(text);
+    if (!match) {
+      failures.push(
+        `${relation.key}: ${relation.file} does not match ${relation.pattern}`,
+      );
+    } else if (match[1] !== expected) {
+      failures.push(
+        `${relation.key}: ${relation.file} declares "${match[1]}" but ` +
+          `${relation.from.fact}.${relation.from.value} derives "${expected}"`,
+      );
+    }
+  }
+
+  return failures;
+}
+
+export function readRepoFile(file) {
+  try {
+    return readFileSync(join(REPO_ROOT, file), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  const failures = auditFacts(readRepoFile);
+  if (failures.length) {
+    console.error("Declared-fact audit failed:");
+    for (const failure of failures) console.error(`- ${failure}`);
+    process.exit(1);
+  }
+  console.log(
+    `Declared-fact audit passed (${FACTS.length} facts, ${DERIVED.length} derived).`,
+  );
+}