@radicool/throughline 0.18.0 → 0.20.0

package/scripts/grep-color-usage.mjs

@@ -6,10 +6,17 @@
 // Usage:
 //   node grep-color-usage.mjs --root <dir> [--config <patterns.json>] [--out <counts.json>]
 //     patterns.json: { "<category>": { "files": "<regex>", "pattern": "<regex with g flag>" }, ... }
-import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
+import { walk, DEFAULT_EXCLUDES, SOURCE_EXT } from './lib/source-scan.mjs';
+
+// This script has exported `walk` and DEFAULT_EXCLUDES since it was written;
+// keep that surface intact now that both live one file over. SOURCE_EXT is not
+// re-exported because it was never exported from here — import it from
+// lib/source-scan.mjs. `walk`'s second parameter is now an options object.
+export { walk, DEFAULT_EXCLUDES };
 
 // The five categories from the case study. Each: which files it applies to, and the
 // (global) match pattern. Tuned defaults — design-system-audit may override per repo.
@@ -36,33 +43,6 @@ export const DEFAULT_CATEGORIES = {
   },
 };
 
-export const DEFAULT_EXCLUDES = [
-  /(^|\/)node_modules(\/|$)/,
-  /(^|\/)generated(\/|$)/,
-  /\.generated\./,
-  /\.test\./,
-  /\.spec\./,
-  /(^|\/)__tests__(\/|$)/,
-  /(^|\/)dist(\/|$)/,
-  /(^|\/)\.next(\/|$)/,
-];
-
-// Source extensions worth opening at all (union of every category's `files`).
-const SOURCE_EXT = /\.(scss|sass|css|tsx?|jsx?|mjs|cjs|vue|svelte|html|svg)$/;
-
-export function* walk(root, excludes = DEFAULT_EXCLUDES) {
-  for (const entry of readdirSync(root)) {
-    const full = join(root, entry);
-    if (excludes.some((re) => re.test(full))) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      yield* walk(full, excludes);
-    } else if (SOURCE_EXT.test(full)) {
-      yield full;
-    }
-  }
-}
-
 // Count matches per category in one file. A category contributes only if its `files`
 // regex matches this path. Returns { <category>: count } for every category key.
 export function scanFile(path, categories) {
@@ -82,7 +62,7 @@ export function grepColorUsage(root, categories = DEFAULT_CATEGORIES, excludes =
   const counts = {};
   for (const key of Object.keys(categories)) counts[key] = 0;
   const byFile = [];
-  for (const file of walk(root, excludes)) {
+  for (const file of walk(root, { excludes, fileFilter: SOURCE_EXT })) {
     const fileCounts = scanFile(file, categories);
     const total = Object.values(fileCounts).reduce((a, b) => a + b, 0);
     if (total > 0) {

package/scripts/guard-token-removal.mjs

@@ -7,34 +7,16 @@
 // Usage:
 //   node guard-token-removal.mjs --root <dir> --symbols <symbols.txt>
 //     symbols file: one symbol per line (blank lines and # comments ignored)
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
+import { walk, DEFAULT_EXCLUDES } from './lib/source-scan.mjs';
 
-export const DEFAULT_EXCLUDES = [
-  /(^|\/)node_modules(\/|$)/,
-  /(^|\/)generated(\/|$)/,
-  /\.generated\./,
-  /\.test\./,
-  /\.spec\./,
-  /(^|\/)__tests__(\/|$)/,
-  /(^|\/)dist(\/|$)/,
-  /(^|\/)\.next(\/|$)/,
-];
-
-export function* walk(root, excludes = DEFAULT_EXCLUDES) {
-  for (const entry of readdirSync(root)) {
-    const full = join(root, entry);
-    if (excludes.some((re) => re.test(full))) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      yield* walk(full, excludes);
-    } else if (/\.tsx?$/.test(full)) {
-      yield full;
-    }
-  }
-}
+// This script has exported `walk` and DEFAULT_EXCLUDES since it was written;
+// keep that surface intact now that both live one file over. `walk`'s second
+// parameter is now an options object.
+export { walk, DEFAULT_EXCLUDES };
 
 export function scanFile(path, symbols) {
   const lines = readFileSync(path, 'utf8').split('\n');
@@ -51,7 +33,9 @@ export function scanFile(path, symbols) {
 
 export function guard(root, symbols, excludes = DEFAULT_EXCLUDES) {
   const findings = [];
-  for (const file of walk(root, excludes)) {
+  // .ts/.tsx is this guard's own contract, so the filter stays here rather
+  // than moving into the shared walker's default.
+  for (const file of walk(root, { excludes, fileFilter: /\.tsx?$/ })) {
     for (const hit of scanFile(file, symbols)) {
       findings.push({ file: relative(root, file), ...hit });
     }

package/scripts/lib/component-states.mjs

@@ -0,0 +1,56 @@
+// The archetype baseline for `state-incomplete` (`docs/specs/2026-09-12-verification-proof-bundle.md`,
+// step 3). Source of truth for the prose is `references/figma-component-standards.md:126-138`.
+//
+// `default` is deliberately excluded from every baseline below: documenting the
+// resting state is not documentation, and the Figma matrix requirement for it is
+// the executor's, not this table's. Conditional states (`loading`, `error`,
+// `success`, `selected`) are deliberately excluded too — whether one applies to a
+// given component is a design judgment, not something a baseline can assert.
+//
+// MAINTENANCE: a change to the prose baseline must change this table.
+
+import { normalizeName } from './source-scan.mjs';
+
+export const ARCHETYPES = ['button', 'input', 'choice', 'card', 'modal', 'badge', 'other'];
+
+export const BASELINE_STATES = {
+  button: ['hover', 'focus', 'active', 'disabled'],
+  input: ['hover', 'focus', 'disabled'],
+  choice: ['hover', 'focus', 'active', 'disabled'],
+  card: [],
+  modal: [],
+  badge: [],
+  other: [],
+};
+
+export const NAME_SYNONYMS = {
+  button: 'button',
+  input: 'input',
+  textfield: 'input',
+  textinput: 'input',
+  checkbox: 'choice',
+  radio: 'choice',
+  toggle: 'choice',
+  switch: 'choice',
+  chip: 'choice',
+  card: 'card',
+  modal: 'modal',
+  dialog: 'modal',
+  badge: 'badge',
+  tag: 'badge',
+};
+
+export function resolveArchetype(record) {
+  if (ARCHETYPES.includes(record.archetype)) return record.archetype;
+  const bySynonym = NAME_SYNONYMS[normalizeName(record.name)];
+  return bySynonym ?? null;
+}
+
+export function missingStates(record) {
+  const archetype = resolveArchetype(record);
+  if (archetype === null) return [];
+  const baseline = BASELINE_STATES[archetype];
+  if (baseline.length === 0) return [];
+  const recordedKeys = new Set(Object.keys(record.states ?? {}).map(normalizeName));
+  return baseline.filter((state) => !recordedKeys.has(normalizeName(state)));
+}

package/scripts/lib/contrast.mjs

@@ -0,0 +1,117 @@
+// The WCAG contrast maths and the semantic colour pair table behind the
+// `color-contrast` rule (`docs/specs/2026-09-12-token-contrast-validation.md`,
+// step 1). Source of truth for the prose contract is
+// `skills/token-builder/SKILL.md:250-265`.
+//
+// MAINTENANCE: a change to the semantic role set must change this table.
+
+export const AA_NORMAL_TEXT = 4.5;
+
+// `text/disabled` is excluded: WCAG 1.4.3 exempts inactive user-interface
+// components from the contrast minimum, and a disabled role is deliberately
+// low-contrast — gating it would fail correct systems.
+//
+// `bg/subtle` and `bg/muted` are deliberately not paired in v1 (Open
+// questions) — a system is free to use those roles for non-text surfaces, so
+// pairing them risks the first false failures in the table.
+//
+// `border/*` needs the 3:1 non-text threshold (WCAG 1.4.11) and is a separate
+// table; this one is text-on-surface only.
+//
+// One threshold is applied to every pair because a colour role does not say
+// what text size it is used at — `text/primary` is body copy as well as
+// headings, so 4.5:1 is the binding requirement for it anyway.
+export const CONTRAST_PAIRS = [
+  {
+    fg: 'color.text.primary',
+    bg: 'color.bg.default',
+    threshold: AA_NORMAL_TEXT,
+    why: 'the default reading pair; if this fails, body copy fails everywhere at once',
+  },
+  {
+    fg: 'color.text.secondary',
+    bg: 'color.bg.default',
+    threshold: AA_NORMAL_TEXT,
+    why: 'secondary text is still text, and still has to clear AA on the same surface primary does',
+  },
+  {
+    fg: 'color.text.link',
+    bg: 'color.bg.default',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a link that fails contrast is a link nobody can find, regardless of colour meaning',
+  },
+  {
+    fg: 'color.text.onEmphasis',
+    bg: 'color.bg.emphasis',
+    threshold: AA_NORMAL_TEXT,
+    why: 'the role exists because it sits on the emphasis fill; that is the whole reason it is not `text/inverse`',
+  },
+  {
+    fg: 'color.text.inverse',
+    bg: 'color.bg.inverse',
+    threshold: AA_NORMAL_TEXT,
+    why: 'the inverse pair flips with the theme, and both sides have to keep clearing together',
+  },
+  {
+    fg: 'color.status.success.text',
+    bg: 'color.status.success.bg',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a status text role exists to sit on that status\'s own background, not any other surface',
+  },
+  {
+    fg: 'color.status.warning.text',
+    bg: 'color.status.warning.bg',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a status text role exists to sit on that status\'s own background, not any other surface',
+  },
+  {
+    fg: 'color.status.danger.text',
+    bg: 'color.status.danger.bg',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a status text role exists to sit on that status\'s own background, not any other surface',
+  },
+];
+
+// WCAG 2.x sRGB relative luminance over 0-255 channels.
+export function relativeLuminance({ r, g, b }) {
+  const linearize = (channel) => {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+// Takes two `#rrggbb` strings (no alpha; the caller composites first) and
+// returns the raw ratio, unrounded.
+export function contrastRatio(hexA, hexB) {
+  const lumA = relativeLuminance(parseHex(hexA));
+  const lumB = relativeLuminance(parseHex(hexB));
+  const lighter = Math.max(lumA, lumB);
+  const darker = Math.min(lumA, lumB);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// `#rrggbb` or `#rrggbbaa` → `{ r, g, b, a }` with `a` in 0-1. `null` for
+// anything else.
+export function parseHex(hex) {
+  if (typeof hex !== 'string') return null;
+  const match = /^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.exec(hex);
+  if (!match) return null;
+  const digits = match[1];
+  const r = parseInt(digits.slice(0, 2), 16);
+  const g = parseInt(digits.slice(2, 4), 16);
+  const b = parseInt(digits.slice(4, 6), 16);
+  const a = digits.length === 8 ? parseInt(digits.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, a };
+}
+
+// The `#rrggbb` of `fg` drawn over `bg` with src-over (`out = fg*a + bg*(1-a)`).
+export function composite(fgHex, bgHex) {
+  const fg = parseHex(fgHex);
+  if (fg.a === 0) return bgHex;
+  if (fg.a === 1) return fgHex.slice(0, 7);
+  const bg = parseHex(bgHex);
+  const mix = (fgChannel, bgChannel) => Math.round(fgChannel * fg.a + bgChannel * (1 - fg.a));
+  const toHex = (value) => value.toString(16).padStart(2, '0');
+  return `#${toHex(mix(fg.r, bg.r))}${toHex(mix(fg.g, bg.g))}${toHex(mix(fg.b, bg.b))}`;
+}

package/scripts/lib/dtcg.mjs

@@ -1,9 +1,12 @@
 // Shared DTCG reading: flatten a token tree to dot-paths, resolve {alias} chains.
-// Zero dependencies. Consumed by validate-crosswalk.mjs and validate-token-output.mjs,
-// and copied alongside both when a skill installs either gate.
+// Zero dependencies. Consumed by validate-crosswalk.mjs, validate-token-output.mjs,
+// validate-adherence.mjs, verify-check.mjs and lib/sd-native.mjs, and copied
+// alongside them when a skill installs any of those.
 
 const REF = /^\{([^}]+)\}$/;
 
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
 // The typographic member names DTCG §9.8 fixes at MUST level, the unit gate a
 // text-role dimension must pass, and this project's $extensions namespace.
 //
@@ -16,6 +19,42 @@ export const TEXT_UNIT_NAMES = new Set(['fontSize', 'letterSpacing', 'lineHeight
 export const TEXT_ROLE_UNIT = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/;
 export const EXT_NS = 'com.radicool.throughline';
 
+// Read this project's $extensions namespace off a node, refusing a shape that
+// cannot hold one.
+//
+// A DTCG $extensions namespace key may hold ANY JSON value, so a source that
+// authored ours as a string is CONFORMANT input this module does not handle —
+// not malformed input. That distinction is why it gets a diagnostic rather than
+// a shrug: the module's contract is that it consumes conformant DTCG.
+//
+// Before #62 the three places that read this namespace all hit the `in`
+// operator on a primitive and threw a bare TypeError naming no token, no path
+// and no value — out of step with every other diagnostic here. nativeSources
+// names the colliding path and both files; the hoist-collision throw names both
+// paths and the value it would overwrite; nativePlatform names the unknown
+// platform and the expected set.
+export function extNamespace(node, path) {
+  const ext = node.$extensions;
+  if (ext === undefined) return undefined;
+  if (!isPlainObject(ext)) {
+    throw new Error(
+      `token "${path}" has a $extensions that is ${JSON.stringify(ext)}, not an object.\n` +
+        'DTCG 5.4 makes $extensions a map of namespace keys. Remove it, or give it the shape ' +
+        `{ "${EXT_NS}": { "nativeUnit": "text" } }.`,
+    );
+  }
+  const ns = ext[EXT_NS];
+  if (ns === undefined) return undefined;
+  if (!isPlainObject(ns)) {
+    throw new Error(
+      `token "${path}" has $extensions["${EXT_NS}"] set to ${JSON.stringify(ns)}, not an object.\n` +
+        `The namespace holds named settings, so a bare value cannot be read. Write ` +
+        `{ "nativeUnit": ${JSON.stringify(ns)} } if that is the setting you meant.`,
+    );
+  }
+  return ns;
+}
+
 // Flatten nested DTCG groups into { "dot.path": rawValue }. Skips $-prefixed meta keys.
 //
 // A node carrying BOTH a $value and children yields its own value AND is descended
@@ -63,6 +102,87 @@ export function flattenDtcgTypes(obj, prefix = [], out = {}, groupType = undefin
   return out;
 }
 
+// DTCG 5.2.2 PLUS the one repair this pipeline applies on top of it, so that
+// anything reasoning about what the build emits reads the same types the build
+// used. flattenDtcgTypes is the spec; this is the spec as this build resolves it.
+//
+// The repair is hoistDualNodes' $type carry. A dual node is a token, not a group
+// (DTCG 6.1), so it is not its children's inheritance source and 5.2.2 gives an
+// untyped child of one no type at all. The hoist then makes that child a sibling
+// of the dual node, which destroys the last relationship it had — so where NO
+// enclosing group supplies a type, the hoist stamps the dual node's own. That is
+// a repair for what the hoist broke, not a reading of the source, which is why
+// it does not belong in flattenDtcgTypes.
+//
+// It has to be modelled somewhere, though, because two things that reason about
+// types could not see it: classification, which runs before the hoist and so
+// declined a child the pipeline goes on to type (#89), and the unitless-dimension
+// advisory, which reads the raw source (#71). Both were silent on shapes the
+// build handles.
+//
+// The conditions mirror hoistDualNodes exactly — an untyped TOKEN child (#67
+// restricted it to those), a dual node that has a $type, no enclosing group type,
+// and a value that is not a whole-value reference. That last one is why this must
+// run on the RAW tree: resolveInPlace rewrites a reference to its literal, and
+// the WeakSet the hoist consults for it does not survive into a fresh call.
+//
+// Keyed on pre-hoist paths, like flattenDtcgTypes, because every consumer of this
+// map runs before the hoist or reports against source paths.
+export function flattenPipelineTypes(dict) {
+  const types = flattenDtcgTypes(dict);
+  (function walk(node, prefix, groupType) {
+    const inherited = '$value' in node ? groupType : (node.$type ?? groupType);
+    for (const [key, val] of Object.entries(node)) {
+      if (key.startsWith('$') || !isPlainObject(val)) continue;
+      const path = [...prefix, key];
+      if ('$value' in val && '$type' in val && inherited === undefined) {
+        for (const [childKey, childVal] of Object.entries(val)) {
+          if (childKey.startsWith('$') || !isPlainObject(childVal)) continue;
+          if ('$value' in childVal && !('$type' in childVal) && !REF.test(String(childVal.$value).trim())) {
+            types[[...path, childKey].join('.')] = val.$type;
+          }
+        }
+      }
+      walk(val, path, inherited);
+    }
+  })(dict, [], undefined);
+  return types;
+}
+
+// Collect nodes carrying BOTH a $value and child tokens or groups.
+//
+// This shape is invalid DTCG. Format Module, Draft Community Group Report of
+// 30 July 2026, §6.1: "The presence of a $value property definitively identifies
+// an object as a token. If an object contains both $value and child
+// tokens/groups, this creates an invalid structure where the object cannot be
+// both a token and a group simultaneously. Tools MUST report this as an error."
+// The prohibition is deliberate rather than an oversight — §6.2 defines $root as
+// the sanctioned way for a group to carry a base value alongside children, which
+// is exactly what a dual node is reaching for.
+//
+// Collecting them is NOT a step towards rejecting them. Figma-derived sources
+// emit dual nodes by the dozen, hoistDualNodes exists precisely to handle them,
+// and refusing them would make this tool useless against the sources it targets.
+// That behaviour is unchanged. What was missing is telling the author their
+// source is non-conforming, which nothing did — so someone hand-authoring
+// text.sm with both a value and a lineHeight child had no way to learn that
+// $root is the blessed spelling.
+//
+// Lives here because flattenDtcg already walks this tree and already descends
+// into dual nodes on purpose, so the knowledge is present and only the reporting
+// was absent.
+export function findDualNodes(obj, prefix = [], out = []) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$') || !isPlainObject(val)) continue;
+    const path = [...prefix, key];
+    if ('$value' in val && Object.entries(val).some(([k, v]) => !k.startsWith('$') && isPlainObject(v))) {
+      out.push(path.join('.'));
+    }
+    findDualNodes(val, path, out);
+  }
+  return out;
+}
+
 // Follow {alias} chains to a leaf literal. Throws on missing or circular refs.
 export function resolveValue(name, flat, seen = new Set()) {
   if (!(name in flat)) throw new Error(`token "${name}" not found in DTCG source`);
@@ -104,7 +224,6 @@ export function findModeCollisions(sources) {
 //
 // Each source is cloned on the way in. Merging the caller's own objects would
 // mutate the token trees it still holds, and the validator reads them again.
-const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
 function mergeInto(target, src) {
   for (const [key, val] of Object.entries(src)) {
@@ -196,7 +315,7 @@ export function textRoleGraph(dict) {
         types[dotted] === 'dimension' &&
         TEXT_ROLE_UNIT.test(String(val.$value).trim()) &&
         !referrers.has(dotted) &&
-        !('nativeUnit' in (val.$extensions?.[EXT_NS] ?? {})) &&
+        !('nativeUnit' in (extNamespace(val, dotted) ?? {})) &&
         inferredGroups.has(group)
       ) {
         unreferencedSiblings.push({ path: dotted, group });

package/scripts/lib/native-literal.mjs

@@ -64,8 +64,28 @@ export const GRAMMAR = {
 // `var` are valid identifiers, and `color-mix` has a rescue in sd-native.mjs
 // that merely did not match this variant. So they must reach the output and
 // fail loudly under no-foreign-syntax, never be silently dropped by a filter.
-// Kept here, beside the grammar, so the build and the gate cannot drift apart.
-export const CSS_CONSTRUCT = /^(?:color-mix|calc|var)\s*\(/;
+// Kept here, beside the grammar, so the build and the gate cannot drift apart —
+// which until #57 was a promise this file made and did not keep. The gate
+// defined its own independent copy of the same alternation, so adding a fourth
+// name here would have taught the filter to keep a construct the gate had never
+// been taught to name. One list now, two anchorings derived from it.
+//
+// The BUILD anchors: only a construct that LEADS the value is exempt from the
+// output filter, because only then is the whole value the unimplemented rescue.
+// The GATE does not anchor: it names the construct wherever it appears.
+//
+// The asymmetry is deliberate and it is a stated limit, not a closed class.
+// `rgba(var(--brand), 0.5)` is dropped by the filter rather than kept, because
+// the module cannot tell an unimplemented rescue nested inside a rescuable
+// function from one nested inside `linear-gradient(...)`, which has no native
+// form at any depth. Closing that needs a notion of which outer functions are
+// rescuable, which does not exist here. What #57 does instead is make the drop
+// NAMED rather than counted — see the unemitted-token report in
+// validate-token-output.mjs.
+export const CSS_CONSTRUCT_NAMES = ['color-mix', 'calc', 'var'];
+const CSS_CONSTRUCT_ALT = CSS_CONSTRUCT_NAMES.join('|');
+export const CSS_CONSTRUCT = new RegExp(`^(?:${CSS_CONSTRUCT_ALT})\\s*\\(`);
+export const CSS_CONSTRUCT_ANYWHERE = new RegExp(`(?:${CSS_CONSTRUCT_ALT})\\s*\\(`);
 
 export function parseLiteral(value, grammar = {}) {
   const s = String(value);

package/scripts/lib/proof.mjs

@@ -0,0 +1,186 @@
+// The proof-bundle store (`docs/specs/2026-09-12-verification-proof-bundle.md`,
+// step 4): load, merge and fingerprint the per-stage files at
+// `design-system/proof/<stage>.json`, and read the manifest's adoption state
+// for each stage. Zero dependencies.
+//
+// See `references/proof-bundle.md` for the file shape and the vocabulary this
+// module defines.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stableStringify, fingerprint } from './doc-record.mjs';
+
+export const PROOF_DIR = 'design-system/proof';
+
+// The stage vocabulary. A change here must also update the stage table in
+// `references/proof-bundle.md`: the constant and the prose are one vocabulary,
+// and a stage this list accepts but the reference does not name is a stage
+// nobody knows how to record.
+//
+// `token-builder` is system-wide. The vocabulary names the places where the
+// negative conditions' evidence is produced, and token creation is now one of
+// them — it is the cheapest place in the system to catch a mode built with poor
+// contrast, because the mode is being defined right then and nothing is built
+// on it yet. Its subject is the whole colour system, never a component.
+export const STAGES = [
+  'component-builder',
+  'storybook-chromatic-builder',
+  'token-sync-layer',
+  'token-builder',
+];
+
+// Which stages are keyed by component (subject = component name) rather than
+// by the system as a whole (subject = "system"). This is the machine-readable
+// copy of the split `references/proof-bundle.md` documents in prose — it is
+// the constant `checkProof` asks "is this stage keyed by component?".
+export const PER_COMPONENT_STAGES = new Set([
+  'component-builder',
+  'storybook-chromatic-builder',
+]);
+
+// Tells the reader (Step 6's `checkProof`) how to compare a recorded derived
+// check against a rerun: a check scoped to "component" is compared per
+// subject; one scoped to "system" is compared once, system-wide, regardless
+// of which subject it was recorded under.
+export const DERIVED_RULE_SCOPE = {
+  'orphan-token': 'system',
+  'state-incomplete': 'component',
+  'name-drift': 'component',
+  // Contrast is a property of the token system as a whole, not of any one
+  // component, so a recorded result is compared against the rerun system-wide —
+  // the same scope orphan-token has.
+  'color-contrast': 'system',
+};
+
+// The names this stage has not yet proven, per the Adoption decision's
+// capture-once-then-shrink rule. A missing `exempt` key is deliberately read
+// as "exempts nothing", not "exempts everything": the only way to reach a
+// stage entry with no `exempt` key is a hand-edited manifest (record mode
+// always writes one for a per-component stage), and the off-switch reading
+// would let a hand-edit silently stop the gate. A missing key must get
+// louder, not quieter.
+export function stageExempt(manifest, stage) {
+  return new Set(manifest.verification?.stages?.[stage]?.exempt ?? []);
+}
+
+// The human-readable "when did this system opt in", written once by record
+// mode and never rewritten. No gate reads it.
+//
+// It is not compared against `components.meta[name].updatedAt`, and `exempt`
+// is a captured list of names rather than a date comparison, for the same
+// reason: `updatedAt` has a second writer.
+// `storybook-chromatic-builder` refreshes it on promotion
+// (`skills/storybook-chromatic-builder/SKILL.md:276-277`), a different stage
+// from the one that owes the entry, so a date gate would fail a pre-existing
+// component the first time an unrelated storying run promotes it.
+//
+// Neither `adoptedAt` nor `exempt` is derived from the stage file's entries,
+// either: `mergeEntry` is latest-wins and replaces a subject's `at`, so "the
+// earliest `at` in the file" would slide forward every time the earliest
+// subject is rebuilt.
+export function stageAdoptedAt(manifest, stage) {
+  return manifest.verification?.stages?.[stage]?.adoptedAt ?? null;
+}
+
+export function stagePath(root, stage) {
+  return join(root, PROOF_DIR, `${stage}.json`);
+}
+
+export function loadStage(root, stage) {
+  const path = stagePath(root, stage);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function stageFingerprint(stageFile) {
+  return fingerprint(stableStringify(stageFile));
+}
+
+const CHECK_METHODS = ['derived', 'attested'];
+const CHECK_RESULTS = ['pass', 'fail'];
+
+export function entryProblems(entry) {
+  const problems = [];
+  if (typeof entry.at !== 'string' || entry.at === '') {
+    problems.push('"at" must be a non-empty string');
+  }
+  if (typeof entry.advancedBecause !== 'string' || entry.advancedBecause === '') {
+    problems.push('"advancedBecause" must be a non-empty string');
+  }
+  if (!Array.isArray(entry.changed) || !entry.changed.every((c) => typeof c === 'string')) {
+    problems.push('"changed" must be an array of strings');
+  }
+  if (!Array.isArray(entry.checks) || entry.checks.length === 0) {
+    problems.push('"checks" must be a non-empty array');
+  } else {
+    entry.checks.forEach((check, i) => {
+      if (!check || typeof check !== 'object') {
+        problems.push(`checks[${i}] must be an object`);
+        return;
+      }
+      if (typeof check.name !== 'string' || check.name === '') {
+        problems.push(`checks[${i}].name must be a non-empty string`);
+      }
+      if (!CHECK_METHODS.includes(check.method)) {
+        problems.push(`checks[${i}].method must be one of ${CHECK_METHODS.join(', ')}`);
+      }
+      if (!CHECK_RESULTS.includes(check.result)) {
+        problems.push(`checks[${i}].result must be one of ${CHECK_RESULTS.join(', ')}`);
+      }
+      if (typeof check.evidence !== 'string') {
+        problems.push(`checks[${i}].evidence must be a string`);
+      }
+      // Optional, and only `contrast-baseline` uses it today — but validated
+      // because it is load-bearing: token-sync-layer subtracts these (fg, bg,
+      // mode) triples from its own gate run's color-contrast failures, so a
+      // malformed one is the difference between a pair the user accepted and a
+      // pair nobody has seen. Reject it here rather than letting the sync
+      // silently match nothing.
+      if (check.accepted !== undefined) {
+        if (!Array.isArray(check.accepted)) {
+          problems.push(`checks[${i}].accepted must be an array when present`);
+        } else {
+          check.accepted.forEach((pair, j) => {
+            const wellFormed =
+              pair &&
+              typeof pair === 'object' &&
+              ['fg', 'bg', 'mode'].every((k) => typeof pair[k] === 'string' && pair[k] !== '');
+            if (!wellFormed) {
+              problems.push(
+                `checks[${i}].accepted[${j}] must carry non-empty "fg", "bg" and "mode" strings`,
+              );
+            }
+          });
+        }
+      }
+    });
+  }
+  if (entry.screenshot !== undefined && typeof entry.screenshot !== 'string') {
+    problems.push('"screenshot" must be a string when present');
+  }
+  return problems;
+}
+
+export function mergeEntry(stageFile, stage, subject, entry) {
+  const subjects = { ...(stageFile?.subjects ?? {}), [subject]: entry };
+  const sortedSubjects = {};
+  for (const key of Object.keys(subjects).sort()) {
+    sortedSubjects[key] = subjects[key];
+  }
+  return { stage, subjects: sortedSubjects };
+}
+
+export function recordedChecks(stageFile) {
+  const out = [];
+  for (const [subject, entry] of Object.entries(stageFile.subjects ?? {})) {
+    for (const check of entry.checks ?? []) {
+      out.push({
+        subject,
+        name: check.name,
+        method: check.method,
+        result: check.result,
+        evidence: check.evidence,
+      });
+    }
+  }
+  return out;
+}