@3fn/core 14.1.0 → 15.0.0

package/src/tools/integrity/__tests__/consumer-package-mode.test.ts

@@ -1,205 +0,0 @@
-/**
- * @category evergreen
- * @purpose Spec 117 Task 5.2 — the R4 consumer blast-radius regression tests, in PACKAGE mode.
- *
- * The silent-failure surface has TWO halves, and source-repo testing alone exercises neither
- * from the consumer's seat:
- *
- *   (a) configured component-token sources silently DROPPED in package mode. A consumer product
- *       that authors its OWN componentTokens must have them loaded/indexed under package mode
- *       (the prior `tokenSourceMode === 'local'` gate zeroed them). This is the consumer blast
- *       radius design D6 calls out — invisible to source-repo-only testing. Covered here by a
- *       real fixture driven through the REAL loadComponentTokens in package mode.
- *
- *   (b) genuinely-empty sources silently NOT WARNED in package mode. The R4 AC3 "none found"
- *       warning must fire in package mode, not only local. Covered here by exercising runGenerate
- *       with a package-mode config and no discoverable component tokens, asserting console.warn.
- *
- * Neither half alone is sufficient (design Testing Strategy, R4 AC3 note). Task 4 verified
- * reachability empirically (live `generate`); these are the locked-in regression tests.
- */
-
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { loadComponentTokens } from '../../../cli/loadComponentTokens';
-import { jestTsModuleLoader } from '../../../__tests__/helpers/tsModuleLoader';
-import { ComponentTokenRegistry } from '../../../registries/ComponentTokenRegistry';
-import type { ResolvedConfig } from '../../../config/ConfigLoader';
-
-// Spec 118 Task 9.5: half (a) exercises the REAL loadComponentTokens, which now defaults to
-// the production scoped tsx loader (cannot run in jest). Inject the jest-compatible loader.
-// Half (b) jest.doMock's the module entirely, so no injection there. Real scoped resolution
-// in a packed install is certified by the consumer guard.
-
-// Spec 124: fixtures author via defineComponentTokens (and EXPORT the result) so the
-// harvest — which iterates Object.values(mod) and collects branded results — picks them up.
-// A direct ComponentTokenRegistry.register(...) is NOT a branded export and would harvest
-// to zero (false-green); an unexported const likewise harvests to zero.
-const DEFINE_TOKENS_PATH = require.resolve('../../../build/tokens').replace(/\\/g, '/');
-
-/** A package-mode ResolvedConfig (no tokenSource → tokenSourceMode 'package'). */
-function packageModeConfig(overrides: Partial<ResolvedConfig>): ResolvedConfig {
-  return {
-    name: 'ConsumerProduct',
-    abbreviation: 'CP',
-    themes: [],
-    // In package mode the primitive/semantic source root points at the PACKAGE's tokens;
-    // the consumer does not author those. The relevant axis for R4 is componentTokenDirs.
-    tokenSourceRoot: path.join(os.tmpdir(), 'pkg-token-root-does-not-exist'),
-    tokenSourceMode: 'package',
-    componentTokenDirs: [],
-    outputDir: path.join(os.tmpdir(), 'consumer-dist'),
-    configDir: os.tmpdir(),
-    ...overrides,
-  } as ResolvedConfig;
-}
-
-describe('Spec 117 R4 consumer blast radius — half (a): consumer authors own componentTokens (package mode)', () => {
-  let fixtureDir: string;
-
-  beforeEach(() => {
-    ComponentTokenRegistry.clear();
-    fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dp117-consumer-fixture-'));
-  });
-
-  afterEach(() => {
-    ComponentTokenRegistry.clear();
-    fs.rmSync(fixtureDir, { recursive: true, force: true });
-  });
-
-  /**
-   * Writes a consumer's own *.tokens.ts that authors a component token via
-   * defineComponentTokens AND exports the result — the exact shape a real consumer
-   * authors, and the shape the branded-return harvest collects.
-   *
-   * `name` is the full token name (e.g. 'consumerwidget.inset.md'); the harvest lowercases
-   * the component, so the token key passed to defineComponentTokens is the suffix after the
-   * lowercased component prefix.
-   */
-  function writeConsumerComponentToken(name: string, value: number): string {
-    const dir = path.join(fixtureDir, 'components', 'Consumer-Widget');
-    fs.mkdirSync(dir, { recursive: true });
-    const file = path.join(dir, 'consumerWidget.tokens.ts');
-    const tokenKey = name.replace(/^consumerwidget\./, '');
-    fs.writeFileSync(
-      file,
-      [
-        '// @ts-nocheck',
-        `const { defineComponentTokens } = require('${DEFINE_TOKENS_PATH}');`,
-        'export const ConsumerWidgetTokens = defineComponentTokens({',
-        "  component: 'ConsumerWidget',",
-        "  family: 'spacing',",
-        '  tokens: {',
-        `    '${tokenKey}': { value: ${value}, reasoning: 'consumer-authored component token' },`,
-        '  },',
-        '});',
-      ].join('\n'),
-    );
-    return path.join(fixtureDir, 'components');
-  }
-
-  test('a package-mode consumer\'s OWN component tokens ARE loaded and indexed (not silently dropped)', () => {
-    const componentsRoot = writeConsumerComponentToken('consumerwidget.inset.md', 16);
-    const config = packageModeConfig({ componentTokenDirs: [componentsRoot] });
-
-    // The corrected loader keys on SOURCE PRESENCE, not tokenSourceMode. In package mode
-    // the consumer's componentTokenDirs must still be discovered + loaded.
-    const loaded = loadComponentTokens(config, jestTsModuleLoader);
-
-    const names = loaded.map((t) => t.name);
-    expect(names).toContain('consumerwidget.inset.md');
-    const tok = ComponentTokenRegistry.get('consumerwidget.inset.md');
-    expect(tok?.value).toBe(16);
-  });
-
-  test('multiple consumer-authored tokens across files are all indexed in package mode', () => {
-    writeConsumerComponentToken('consumerwidget.inset.md', 16);
-    // A second file in the same tree.
-    const dir2 = path.join(fixtureDir, 'components', 'Consumer-Panel');
-    fs.mkdirSync(dir2, { recursive: true });
-    fs.writeFileSync(
-      path.join(dir2, 'consumerPanel.tokens.ts'),
-      [
-        '// @ts-nocheck',
-        `const { defineComponentTokens } = require('${DEFINE_TOKENS_PATH}');`,
-        'export const ConsumerPanelTokens = defineComponentTokens({',
-        "  component: 'ConsumerPanel',",
-        "  family: 'spacing',",
-        "  tokens: { 'gap.sm': { value: 8, reasoning: 'consumer' } },",
-        '});',
-      ].join('\n'),
-    );
-
-    const config = packageModeConfig({ componentTokenDirs: [path.join(fixtureDir, 'components')] });
-    const loaded = loadComponentTokens(config, jestTsModuleLoader);
-    const names = loaded.map((t) => t.name).sort();
-    expect(names).toContain('consumerwidget.inset.md');
-    expect(names).toContain('consumerpanel.gap.sm');
-  });
-});
-
-describe('Spec 117 R4 consumer blast radius — half (b): "none found" warning fires in PACKAGE mode', () => {
-  // The warning lives in runGenerate (designerpunk.ts), fired when loadComponentTokens
-  // returns []. We drive runGenerate with everything mocked except the warning path, and a
-  // package-mode config, asserting the warning is emitted in package mode (not only local).
-  let warnSpy: jest.SpyInstance;
-
-  beforeEach(() => {
-    jest.resetModules();
-    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-    jest.spyOn(console, 'log').mockImplementation(() => {});
-    jest.spyOn(console, 'error').mockImplementation(() => {});
-    jest.spyOn(process, 'exit').mockImplementation((() => {}) as never);
-  });
-
-  afterEach(() => {
-    jest.restoreAllMocks();
-    jest.resetModules();
-  });
-
-  test('runGenerate emits the "No component token files found" warning in package mode when none are discovered', async () => {
-    jest.doMock('../../../generators/generateTokenFiles', () => ({
-      generateTokenFiles: jest.fn().mockReturnValue({
-        resolvedLight: [],
-        resolvedDark: [],
-        themeVaryingTokens: new Set<string>(),
-        primitiveOklch: new Map(),
-      }),
-    }));
-    jest.doMock('../../../generators/generateTokenIndex', () => ({ generateTokenIndex: jest.fn() }));
-    jest.doMock('../../../cli/generateProductTokens', () => ({ generateProductTokens: jest.fn() }));
-    jest.doMock('../../../cli/resolveTokens', () => ({
-      resolveTokens: jest.fn().mockReturnValue({ primitiveTokens: [], semanticTokens: [] }),
-    }));
-    jest.doMock('../../../cli/staleness', () => ({ isProductTokenStale: jest.fn().mockReturnValue(false) }));
-    jest.doMock('../../../registries/ComponentTokenRegistry', () => ({
-      ComponentTokenRegistry: { getAll: () => [] },
-    }));
-    // The decisive part: loadComponentTokens returns [] (no sources discovered),
-    // and the config is PACKAGE mode.
-    jest.doMock('../../../cli/loadComponentTokens', () => ({
-      loadComponentTokens: jest.fn().mockReturnValue([]),
-    }));
-    jest.doMock('../../../config/ConfigLoader', () => ({
-      loadConfig: jest.fn().mockResolvedValue({
-        name: 'Consumer',
-        abbreviation: 'C',
-        themes: [],
-        tokenSourceRoot: '/pkg/tokens',
-        tokenSourceMode: 'package',
-        componentTokenDirs: [],
-        outputDir: '/tmp/consumer-dist',
-        configDir: '/tmp',
-      }),
-    }));
-
-    const { runGenerate } = require('../../../cli/designerpunk');
-    await runGenerate();
-
-    const warned = warnSpy.mock.calls.some((args) =>
-      String(args[0]).includes('No component token files found'),
-    );
-    expect(warned).toBe(true);
-  });
-});

package/src/tools/integrity/cli/run-audit.ts

@@ -1,150 +0,0 @@
-/**
- * Audit runner (Task 1.2 — empirical phase).
- *
- * Runs the GenerationIntegrityCheck over the full inventory (committed = cwd,
- * fresh = a worktree dir generated via the ts-node workaround) and prints a
- * structured evidence digest for classification (Ada, Task 1.2 interpretive phase).
- *
- * It runs TWO check types because they catch different findings:
- *   1. committed-vs-fresh reproduction  → catches Findings 3a (component drop)
- *      and 3b (theme-varying drift), where fresh DIFFERS from committed.
- *   2. absolute invariant scan (rgba)   → catches Finding 1, which is INVISIBLE
- *      to (1) because fresh reproduces committed (both legacy rgba); the defect
- *      is token-index-vs-dist-CSS, correctTarget = neither.
- *
- * Usage: npx tsx src/tools/integrity/cli/run-audit.ts <worktree-path>
- *
- * This runner does NOT classify (four-bucket / correctTarget / shared-root-cause)
- * — that is Ada's Rosetta-domain phase. It produces the raw evidence only.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { GenerationIntegrityCheckImpl } from '../GenerationIntegrityCheck';
-import { DiskFreshGenerator } from '../DiskFreshGenerator';
-import { INVENTORY } from '../inventory';
-import { EMPTY_MANIFEST } from '../manifest';
-import { ArtifactDiff } from '../types';
-import { assertTokenIndexInvariants, rgbaColorPrimitives, themeVaryingTrueKeys } from '../Invariants';
-
-const worktree = process.argv[2] || process.env.AUDIT_WORKTREE;
-if (!worktree) {
-  console.error('usage: run-audit <worktree-path>');
-  process.exit(1);
-}
-
-const repo = process.cwd();
-// Provenance (Task 5.3 trust gate): post-Spec-118 the documented CLI runs end-to-end,
-// so a documented-CLI fresh generate is NON-provisional (design P7). Default reflects that.
-// Override to the historical ts-node workaround for comparison with `AUDIT_VIA=ts-node-workaround`.
-const via = process.env.AUDIT_VIA === 'ts-node-workaround' ? 'ts-node-workaround' : 'documented-cli';
-const provisional = via === 'ts-node-workaround';
-const fresh = new DiskFreshGenerator(path.resolve(worktree), via, provisional);
-const result = new GenerationIntegrityCheckImpl(fresh, repo).run({
-  inventory: INVENTORY,
-  manifest: EMPTY_MANIFEST,
-});
-
-console.log('============================================================');
-console.log('  GENERATION-INTEGRITY AUDIT — RAW EVIDENCE (Task 1.2a)');
-console.log(`  generatedVia: ${result.generatedVia}   provisional: ${result.provisional}`);
-console.log(`  allEqual: ${result.allEqual}`);
-console.log('============================================================\n');
-
-console.log('--- CHECK 1: committed-vs-fresh reproduction ---\n');
-for (const diff of result.diffs) {
-  const tag = diff.status === 'equal' ? '   equal' : `✗  ${diff.status}`;
-  console.log(`${tag.padEnd(20)} ${diff.artifact.path}  (${diff.divergences.length} divergences)`);
-}
-
-console.log('\n--- divergence detail (by artifact) ---');
-for (const diff of result.diffs) {
-  if (diff.status === 'equal') continue;
-  console.log(`\n### ${diff.artifact.path} — ${diff.status} — ${diff.divergences.length} divergences`);
-  console.log(`    dimensions: ${dimensionBreakdown(diff)}`);
-  const sample = diff.divergences.slice(0, 8);
-  for (const d of sample) {
-    console.log(`    • ${d.locator}  [${d.dimension}]  committed=${trunc(d.committedValue)}  fresh=${trunc(d.freshValue)}`);
-  }
-  if (diff.divergences.length > sample.length) {
-    console.log(`    … +${diff.divergences.length - sample.length} more`);
-  }
-}
-
-console.log('\n\n--- CHECK 2: absolute invariant scan (P3 — catches Finding 1) ---\n');
-rgbaScan('token-index/primitives.yaml');
-rgbaScan('token-index/semantics.yaml');
-oklchVsRgba('dist/DesignTokens.web.css');
-
-// CHECK 3 (Task 5.1) — the absolute correctness-property assertions the re-diff cannot catch:
-//   P3 (no rgba except the shadow allowlist) and P5 (theme-varying = base-scoped 5, not registry-wide 10).
-// Run against the COMMITTED token-index (repo cwd) — these must hold regardless of drift.
-console.log('\n--- CHECK 3: token-index invariants (P3 no-legacy-color, P5 theme-varying-base-scoped) ---\n');
-const primitivesYaml = readMaybe(path.resolve(repo, 'token-index/primitives.yaml'));
-const semanticsYaml = readMaybe(path.resolve(repo, 'token-index/semantics.yaml'));
-let invariantViolations: ReturnType<typeof assertTokenIndexInvariants> = [];
-if (primitivesYaml === null || semanticsYaml === null) {
-  console.log('  ⚠ token-index primitives/semantics absent — cannot assert invariants');
-} else {
-  console.log(`  rgba color primitives (expect 4 shadow only): ${rgbaColorPrimitives(primitivesYaml).join(', ')}`);
-  console.log(`  themeVarying:true keys (expect 5 base): ${themeVaryingTrueKeys(semanticsYaml).join(', ')}`);
-  invariantViolations = assertTokenIndexInvariants({ primitivesYaml, semanticsYaml });
-  console.log(`  P3 + P5: ${invariantViolations.length === 0 ? '✅ hold' : `✗ ${invariantViolations.length} VIOLATION(S)`}`);
-  for (const v of invariantViolations) console.log(`    • [${v.invariant}] ${v.locator}: ${v.detail}`);
-}
-
-// Trust-gate verdict (Task 5.3 / P7): non-provisional certification requires a documented-CLI
-// fresh generate, all-equal re-diff, AND the invariants holding.
-const certifiable = result.allEqual && invariantViolations.length === 0 && !provisional;
-console.log('\n============================================================');
-console.log(`  VERDICT: allEqual=${result.allEqual}  invariants=${invariantViolations.length === 0 ? 'hold' : 'VIOLATED'}  via=${via}  provisional=${provisional}`);
-console.log(`  ${certifiable ? '✅ TRUST GATE MET — ready to certify non-provisionally (pending ratification)' : '⛔ NOT certifiable as-is'}`);
-console.log('============================================================');
-process.exitCode = certifiable ? 0 : 1;
-
-function dimensionBreakdown(diff: ArtifactDiff): string {
-  const counts: Record<string, number> = {};
-  for (const d of diff.divergences) counts[d.dimension] = (counts[d.dimension] ?? 0) + 1;
-  return Object.entries(counts)
-    .map(([k, v]) => `${k}=${v}`)
-    .join(', ');
-}
-
-function trunc(v: unknown): string {
-  const s = typeof v === 'string' ? v : JSON.stringify(v);
-  if (s === undefined) return 'undefined';
-  return s.length > 60 ? `${s.slice(0, 57)}…` : s;
-}
-
-function rgbaScan(rel: string): void {
-  const committed = readMaybe(path.resolve(repo, rel));
-  const freshContent = fresh.read(rel);
-  const cR = count(committed, /rgba\(/g);
-  const fR = count(freshContent, /rgba\(/g);
-  const cO = count(committed, /oklch\(/g);
-  const fO = count(freshContent, /oklch\(/g);
-  console.log(`  ${rel}:`);
-  console.log(`     committed: rgba(=${cR}  oklch(=${cO}      fresh: rgba(=${fR}  oklch(=${fO})`);
-}
-
-function oklchVsRgba(rel: string): void {
-  const committed = readMaybe(path.resolve(repo, rel));
-  const freshContent = fresh.read(rel);
-  console.log(`  ${rel} (the canonical color output to compare token-index against):`);
-  console.log(`     committed: rgba(=${count(committed, /rgba\(/g)}  oklch(=${count(committed, /oklch\(/g)}` +
-    `      fresh: rgba(=${count(freshContent, /rgba\(/g)}  oklch(=${count(freshContent, /oklch\(/g)})`);
-}
-
-function readMaybe(p: string): string | null {
-  try {
-    return fs.readFileSync(p, 'utf-8');
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
-    throw err;
-  }
-}
-
-function count(s: string | null, re: RegExp): number {
-  if (s === null) return -1; // -1 signals "file absent"
-  return (s.match(re) ?? []).length;
-}

package/src/tools/integrity/inventory.ts

@@ -1,51 +0,0 @@
-/**
- * The generation-integrity inventory (R1 AC1).
- *
- * Every artifact a fresh `generate` produces, materialized as ArtifactRef[].
- *
- * Blend utilities are intentionally EXCLUDED. Design R1 enumerated dist/BlendUtilities.*
- * (from the Rosetta-architecture doc), but the Task 1.2 audit found `generate` produces
- * no such artifact at any extension (the real paths are *.ts/.swift/.kt per
- * TokenFileGenerator, and even those are absent — the blend-write path is not exercised).
- * Tracked as deferred finding 117-N1 (out of scope: Spec 117 is token-index integrity,
- * not blend-generator wiring). See .kiro/issues/issues-registry.md.
- *
- * Theme-aware output is embedded within the DesignTokens.* files (the theme
- * blocks), so it is covered by those entries rather than a separate artifact.
- *
- * Product tokens are `optional: true` — present only when a product configures
- * `productTokens` (Integration Guide); their absence on both sides is not a divergence.
- *
- * Task 5.1 confirmation: this inventory reflects the corrected post-Task-3/4 set —
- * BlendUtilities removed (N1 deferred), components.yaml carries the corrected 33-token
- * baseline, and dist/ComponentTokens.* are listed (N2 populated). The full-inventory
- * re-diff against a documented-CLI fresh generate is ALL-EQUAL (Task 5.3).
- */
-
-import { ArtifactRef } from './types';
-
-export const INVENTORY: ArtifactRef[] = [
-  // Token-index (Application MCP source of truth) — no volatile header; pure semantic compare.
-  { path: 'token-index/primitives.yaml', kind: 'yaml', optional: false },
-  { path: 'token-index/semantics.yaml', kind: 'yaml', optional: false },
-  { path: 'token-index/components.yaml', kind: 'yaml', optional: false },
-
-  // Platform design-token outputs.
-  { path: 'dist/DesignTokens.web.css', kind: 'css', optional: false },
-  { path: 'dist/DesignTokens.ios.swift', kind: 'swift', optional: false },
-  { path: 'dist/DesignTokens.android.kt', kind: 'kotlin', optional: false },
-  { path: 'dist/DesignTokens.dtcg.json', kind: 'json', optional: false },
-  { path: 'dist/DesignTokens.figma.json', kind: 'json', optional: false },
-
-  // Component-token outputs (the R4-central tier).
-  { path: 'dist/ComponentTokens.web.css', kind: 'css', optional: false },
-  { path: 'dist/ComponentTokens.ios.swift', kind: 'swift', optional: false },
-  { path: 'dist/ComponentTokens.android.kt', kind: 'kotlin', optional: false },
-
-  // Blend utilities omitted — see header note (deferred finding 117-N1).
-
-  // Product tokens — only when configured.
-  { path: 'dist/product/ProductTokens.web.css', kind: 'css', optional: true },
-  { path: 'dist/product/ProductTokens.ios.swift', kind: 'swift', optional: true },
-  { path: 'dist/product/ProductTokens.android.kt', kind: 'kotlin', optional: true },
-];

package/src/tools/integrity/manifest.ts

@@ -1,56 +0,0 @@
-/**
- * Intentional-divergence manifest (Design Decision D2).
- *
- * Encodes the human-ratified set of divergences that are intentional and
- * acceptable, so R2 AC3 ("every divergence classifiable and intentional")
- * is *repeatable* rather than re-judged each run. Every entry carries
- * `approvedBy` + `date` under ballot governance.
- *
- * Task 1.1 shipped an EMPTY seed: until the baseline audit (Task 1.2) and the
- * checkpoint ran, nothing was yet ratified as intentional — an empty manifest
- * means "no divergence is pre-approved," which was the correct starting posture.
- *
- * TASK 5.1 — RATIFIED END-STATE: the manifest stays EMPTY. This is not a
- * not-yet-populated placeholder; it is the confirmed correct final state.
- * Tasks 3 and 4 corrected the committed baselines to match a fresh generate
- * (Task 3: token-index OKLCH + base-scoped theme-varying; Task 4: components.yaml
- * 27→33, the 6 silently-dropped tokens recovered). With the baselines corrected,
- * the full-inventory committed-vs-fresh re-diff comes back ALL-EQUAL (0
- * divergences across all 14 artifacts — confirmed empirically in Task 5.3),
- * so there is NO intentional divergence to ratify.
- *
- * Two candidate "exceptions" were deliberately kept OUT of this manifest:
- *   - The shadow color family carrying rgba(): not a divergence at all (committed
- *     == fresh == dist; the index faithfully reproduces dist). Scoped out in the
- *     P3 invariant (see Invariants.ts), not allowlisted here. Tracked as a
- *     token-foundation follow-on:
- *     .kiro/issues/2026-06-24-oklch-shadow-color-family-not-migrated.md.
- *   - The 6 recovered component tokens: the committed baseline was CORRECTED to
- *     include them (Task 4), so committed == fresh — not an allowlisted exception.
- *
- * An empty-but-ratified manifest is the right outcome: a correct generation
- * pipeline has nothing to forgive. If a genuine intentional divergence is ever
- * introduced, add an entry here with `approvedBy` + `date` + `reason` under
- * ballot governance.
- */
-
-import { minimatch } from 'minimatch';
-import { Divergence, IntentionalDivergenceManifest } from './types';
-
-/** Empty seed manifest — no divergence is pre-approved until ratified (Task 5.1). */
-export const EMPTY_MANIFEST: IntentionalDivergenceManifest = {
-  version: '1.0.0',
-  entries: [],
-};
-
-/**
- * True when a divergence is allowlisted by a ratified manifest entry.
- * Matches `${artifactPath}#${locator}` against each entry's glob matcher.
- */
-export function matchesManifest(
-  divergence: Divergence,
-  manifest: IntentionalDivergenceManifest,
-): boolean {
-  const key = `${divergence.artifactPath}#${divergence.locator}`;
-  return manifest.entries.some((entry) => minimatch(key, entry.matcher));
-}

package/src/tools/integrity/types/index.ts

@@ -1,183 +0,0 @@
-/**
- * Shared types for the Generation-Integrity tool (Spec 117).
- *
- * Transcribes the interface contracts from
- * `.kiro/specs/117-token-index-generation-integrity/design.md`
- * (§ Components and Interfaces, § Data Models).
- *
- * Organized into three sections:
- *   1. Verification engine (R2 — Thurgood, test infrastructure)
- *   2. Audit / classification (R1 — Thurgood, audit methodology)
- *   3. Governance artifact (the post-investigation DecisionRecord)
- *
- * NOTE on ownership: this module defines the full type surface so that
- * Task 1.2 (audit run + DivergenceClassifier + AuditReport assembly) and
- * Task 1.3 (DecisionRecord) implement against stable contracts. Task 1.1
- * implements only the comparison engine (Normalizer, SemanticComparator,
- * GenerationIntegrityCheck), the inventory, and the manifest scaffold.
- */
-
-// ============================================================
-// 1. VERIFICATION ENGINE — GenerationIntegrityCheck (R2)
-// ============================================================
-
-/** File kind, drives parsing + normalization strategy. */
-export type ArtifactKind = 'yaml' | 'css' | 'swift' | 'kotlin' | 'json';
-
-/** A single generated artifact under integrity comparison. */
-export interface ArtifactRef {
-  /** Repo-relative path, e.g. "token-index/primitives.yaml". */
-  path: string;
-  kind: ArtifactKind;
-  /** True when the artifact only exists if configured (e.g. dist/product/*). */
-  optional: boolean;
-}
-
-/** Dimension tag for triage — refined by the DivergenceClassifier (Task 1.2). */
-export type DivergenceDimension =
-  | 'color-format'
-  | 'component-presence'
-  | 'theme-varying'
-  | 'other';
-
-/** One semantic difference between committed and fresh for an artifact. */
-export interface Divergence {
-  /** Stable, derived from `${artifactPath}#${locator}` — used for manifest matching. */
-  id: string;
-  artifactPath: string;
-  /** Token name / key path within the artifact (e.g. "tokens.gray100.value.light.base"). */
-  locator: string;
-  committedValue: unknown;
-  freshValue: unknown;
-  dimension: DivergenceDimension;
-}
-
-export type ArtifactDiffStatus = 'equal' | 'diverged' | 'missing-committed' | 'missing-fresh';
-
-/** Result of comparing one artifact, committed vs. fresh. */
-export interface ArtifactDiff {
-  artifact: ArtifactRef;
-  status: ArtifactDiffStatus;
-  /** Empty when status === 'equal'. */
-  divergences: Divergence[];
-}
-
-export type GeneratedVia = 'documented-cli' | 'ts-node-workaround';
-
-/** Outcome of the whole check. */
-export interface IntegrityResult {
-  diffs: ArtifactDiff[];
-  /** True only if every diff is 'equal' OR every divergence is allowlisted by the manifest. */
-  allEqual: boolean;
-  /** True until documented-CLI reproduction (R2 AC4 / P7). */
-  provisional: boolean;
-  generatedVia: GeneratedVia;
-}
-
-/**
- * Adapter that supplies fresh-generate content for comparison.
- *
- * Task 1.1 ships only test doubles for this. The real implementation —
- * running `generate` to a scratch tree (documented CLI when available, else
- * the ts-node workaround) — lands in Task 1.2, where `provisional` and
- * `generatedVia` reflect how the generate actually ran.
- */
-export interface FreshGenerator {
-  readonly generatedVia: GeneratedVia;
-  readonly provisional: boolean;
-  /** Fresh content for an artifact path, or null if the fresh generate did not produce it. */
-  read(path: string): string | null;
-}
-
-/** Normalization applied before comparison — defines "semantic equality" (Design D1). */
-export interface NormalizationRule {
-  appliesTo: ArtifactKind[] | 'all';
-  description: string;
-  /** Transform parsed (structured) or raw (text) content, removing/canonicalizing volatile elements. */
-  apply(value: unknown, kind: ArtifactKind): unknown;
-}
-
-/** Explicit, human-ratified set of divergences that are intentional and acceptable (Design D2). */
-export interface IntentionalDivergenceManifestEntry {
-  /** `${artifactPath}#${locator}` glob, matched with minimatch. */
-  matcher: string;
-  reason: string;
-  /** Human ratification (ballot governance). */
-  approvedBy: string;
-  date: string;
-}
-
-export interface IntentionalDivergenceManifest {
-  version: string;
-  entries: IntentionalDivergenceManifestEntry[];
-}
-
-/** The core engine: compare committed artifacts against a fresh generate (semantic equality). */
-export interface GenerationIntegrityCheck {
-  run(opts: {
-    inventory: ArtifactRef[];
-    manifest: IntentionalDivergenceManifest;
-  }): IntegrityResult;
-}
-
-// ============================================================
-// 2. AUDIT / CLASSIFICATION — R1 (types only in Task 1.1; impl in Task 1.2)
-// ============================================================
-
-export type ProvenanceBucket =
-  | 'migration-gap' // (a) generator never updated
-  | 'generation-bug' // (b) wrong output for current config
-  | 'config-drift' // (c) committed predates a config change (stale-but-correct)
-  | 'hand-assembly'; // (d) manually edited
-
-export interface Classification {
-  divergence: Divergence;
-  bucket: ProvenanceBucket;
-  /** id of another classification (e.g. a (b) that causes this (c)). */
-  causedBy?: string;
-  rationale: string;
-  /** Which side the fix should converge toward — surfaces the "committed = correct" assumption (P6). */
-  correctTarget: 'committed' | 'fresh' | 'neither' | 'unknown';
-}
-
-export interface TriagedFinding {
-  summary: string;
-  disposition: 'in-scope' | 'deferred';
-  /** Issues-registry entry when deferred. */
-  issueRef?: string;
-  /** Why / where / impact (deferral rationale standard). */
-  rationale: string;
-}
-
-export interface AuditReport {
-  inventory: ArtifactRef[];
-  classifications: Classification[];
-  /** Exported but never imported by a non-test / non-generation module on the OKLCH surface (R1 AC4). */
-  orphanedHelpers: string[];
-  /** Findings beyond the 3 originals (R1 AC5) — logged, never silently carried. */
-  newFindings: TriagedFinding[];
-  finding2: {
-    documentedCliRuns: boolean;
-    configLoadEquivalentToWorkaround: boolean | 'unverified';
-  };
-  /** True iff every inventory artifact is both diffed AND classified (P2). */
-  complete: boolean;
-  provisional: boolean;
-}
-
-// ============================================================
-// 3. GOVERNANCE ARTIFACT — post-investigation DecisionRecord (R1 AC8/AC9)
-// ============================================================
-
-export interface DecisionRecord {
-  /** Dated (AC9). */
-  date: string;
-  auditReportRef: string;
-  perRequirement: Array<{
-    requirement: 'R3' | 'R4' | 'R5';
-    determination: 'kept' | 'revised' | 'rescoped';
-    rationale: string;
-  }>;
-  /** The Finding 1 ↔ R5 shared-code-root-cause hypothesis (Decision 4). */
-  sharedRootCauseConfirmed: boolean | 'refuted';
-}