@3fn/core 14.0.0 → 15.0.0

package/application-mcp-server/src/indexer/TokenIndexer.ts

@@ -11,6 +11,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import { TokenRefResolver } from './TokenRefResolver';
+import { parseSemanticOverrides, OverrideRefs } from './SemanticOverrideReader';
+import { resolveThemeTierRoot } from './resolveThemeTierRoot';
 
 export interface TokenIndexEntry {
   name: string;
@@ -40,7 +42,74 @@ export interface ResolvedValueTriple {
   resolutionDepth: 'full' | 'partial' | null;
 }
 
-export type TokenDetails = TokenIndexEntry & ResolvedValueTriple;
+/**
+ * Per-theme resolution of a Level 2 semantic override (issue 2026-09-12).
+ *
+ * WHAT PROBLEM THIS SOLVES
+ * ------------------------
+ * The `ResolvedValueTriple` above resolves a token's BASE `primitiveReferences` only. For a
+ * token with a Level 2 dark override (`src/tokens/themes/dark/SemanticOverrides.ts` — e.g.
+ * `color.structure.canvas` → `gray400`), the base triple therefore describes the LIGHT
+ * resolution. Worse, legacy colour primitives carry identical `light.base` and `dark.base`
+ * slots, so even the `dark` slot INSIDE `resolvedValue` repeats the light value. A consumer
+ * reading `resolvedValue.dark.base` for a Level 2 token gets the wrong answer.
+ *
+ * `ThemeResolution` is the theme-scoped answer, emitted ADDITIVELY. The base triple's
+ * meaning is unchanged: it remains the base (light) resolution.
+ *
+ * FIELDS
+ * - `primitiveReferences` — the override's refs verbatim (what the theme swaps to).
+ * - `resolvedValue` — the override's chain-resolved terminal value, following the SAME shape
+ *   rules as the base triple (a colour primitive resolves to its full mode bundle).
+ * - `resolvedUnitType` / `resolutionDepth` — same contract as the base triple.
+ * - `modeValue` — convenience scalar: the `dark.base` slot of `resolvedValue` when the
+ *   terminal value is a mode bundle; `null` otherwise (composite overrides, non-bundle
+ *   values, unresolvable refs). This is the single unambiguous "what is it in dark" answer.
+ *
+ * COMPOSITE OVERRIDES (e.g. `color.structure.border.subtle` → `{ color, opacity }`)
+ * are NOT collapsed into one value — there is no honest single terminal value for a
+ * colour+opacity pair. They mirror the base triple's multi-ref branch: `resolutionDepth`
+ * `'partial'`, `resolvedValue` the token's own name, `modeValue` null — with the full
+ * `primitiveReferences` exposed so each part can be resolved individually.
+ */
+export interface ThemeResolution {
+  primitiveReferences: Record<string, string>;
+  resolvedValue: number | string | Record<string, unknown> | null;
+  resolvedUnitType: string | null;
+  resolutionDepth: 'full' | 'partial' | null;
+  modeValue: string | number | null;
+}
+
+/**
+ * Theme-scoped resolutions attached to `get_token_details`.
+ *
+ * NULL/ABSENCE CONTRACT (additive, Spec-121-style):
+ * - `themeResolutions` is ALWAYS present on a `get_token_details` response, for every tier.
+ * - `themeResolutions.dark` is `null` when — and only when — the token has no Level 2 dark
+ *   override. `null` therefore means "dark resolves exactly like the base triple", which is
+ *   the correct answer for Level 1 and mode-invariant tokens, for all primitives, and for
+ *   all component tokens (overrides exist only at the semantic tier).
+ * - If the theme file itself cannot be read, every token reports `dark: null` — which is
+ *   indistinguishable from "no override" at the field level. That case is surfaced as an
+ *   index WARNING (`getWarnings()` → component health), so the degraded state is visible
+ *   rather than silent.
+ * - `themeResolutions` is emitted on `get_token_details` ONLY — `search`, `getFamily`, and
+ *   `getConsumers` keep their existing lightweight shapes.
+ *
+ * WCAG THEMES ARE DELIBERATELY ABSENT (not an oversight): `wcag` resolution is not one value
+ * but a matrix — `src/tokens/themes/wcag/` and `src/tokens/themes/dark-wcag/` layer over the
+ * dark theme with their own precedence, AND every primitive carries its own `.wcag` slot
+ * inside each mode. That needs its own design pass (deferred to the Semantic Contrast &
+ * Theme Coverage spec). This object is the extension point: adding a `wcag` key later is
+ * additive in exactly the way `dark` is today.
+ */
+export interface ThemeResolutions {
+  dark: ThemeResolution | null;
+}
+
+export type TokenDetails = TokenIndexEntry & ResolvedValueTriple & {
+  themeResolutions: ThemeResolutions;
+};
 
 export interface TokenConsumer {
   component: string;
@@ -53,6 +122,23 @@ export interface TokenHealth {
   componentTokens: number;
 }
 
+/**
+ * Pull the dark-mode base slot out of a resolved colour value.
+ *
+ * Colour primitives in the token index carry a mode bundle:
+ *   `{ light: { base, wcag }, dark: { base, wcag } }`
+ * For those, the single scalar a consumer actually wants for dark mode is `dark.base`.
+ * Anything that is not such a bundle (scalars, composites, nulls) yields null — the
+ * `modeValue` field is a convenience, never a guess.
+ */
+function extractDarkModeValue(value: unknown): string | number | null {
+  if (!value || typeof value !== 'object') return null;
+  const dark = (value as Record<string, unknown>).dark;
+  if (!dark || typeof dark !== 'object') return null;
+  const base = (dark as Record<string, unknown>).base;
+  return typeof base === 'string' || typeof base === 'number' ? base : null;
+}
+
 export class TokenIndexer {
   private primitives = new Map<string, TokenIndexEntry>();
   private semantics = new Map<string, TokenIndexEntry>();
@@ -62,14 +148,33 @@ export class TokenIndexer {
   // Chain-resolver for the get_token_details resolved-value triple (Spec 121 Req 2). Reads the
   // same token-index/*.yaml corpus as the tier maps; loaded alongside them in indexTokens().
   private resolver: TokenRefResolver | undefined;
+  // Level 2 dark overrides, text-parsed from src/tokens/themes/dark/SemanticOverrides.ts
+  // (issue 2026-09-12). Empty map = no overrides loaded; see the ThemeResolutions contract.
+  private darkOverrides = new Map<string, OverrideRefs>();
 
-  async indexTokens(tokenIndexDir: string): Promise<void> {
+  /**
+   * @param tokenIndexDir Directory holding primitives/semantics/components.yaml. Also where
+   *                      `meta.json`'s `tierDir` is read from (Spec 123 Task 1.5, DD24) —
+   *                      the AUTHORITATIVE theme-root source when present.
+   * @param projectRoot   LEGACY fallback used only when neither `meta.json` nor
+   *                      `explicitTierDir` resolves a tier. Defaults to the token index's
+   *                      parent (`<root>/token-index` is the standard layout).
+   * @param explicitTierDir The caller's own resolved tier (e.g. `DesignSystemRoot.tierDir`),
+   *                      used when `meta.json` is absent (a pre-1.5 index) — second
+   *                      precedence, per `resolveThemeTierRoot`.
+   */
+  async indexTokens(tokenIndexDir: string, projectRoot?: string, explicitTierDir?: string): Promise<void> {
     this.primitives.clear();
     this.semantics.clear();
     this.componentTokens.clear();
     this.consumerIndex.clear();
+    this.darkOverrides.clear();
     this.warnings = [];
 
+    this.loadThemeOverrides(
+      resolveThemeTierRoot(tokenIndexDir, explicitTierDir, projectRoot ?? path.resolve(tokenIndexDir, '..'))
+    );
+
     if (!fs.existsSync(tokenIndexDir)) {
       this.warnings.push(`Token index directory not found: ${tokenIndexDir}`);
       return;
@@ -114,7 +219,12 @@ export class TokenIndexer {
     // Additively attach the resolved-value triple (Spec 121 Req 2). Existing keys —
     // including the unchanged platforms{} object and the absent `value` key on semantics —
     // are preserved exactly; the triple is layered on top.
-    return { ...entry, ...this.resolveTriple(name) };
+    //
+    // `themeResolutions` (issue 2026-09-12) is layered on the same way: purely additive, the
+    // base triple keeps its meaning (the BASE/light resolution), and the dark answer gets its
+    // own clearly-named home instead of being smuggled into an existing field.
+    const triple = this.resolveTriple(name);
+    return { ...entry, ...triple, themeResolutions: this.resolveThemeResolutions(name, triple) };
   }
 
   /**
@@ -136,6 +246,88 @@ export class TokenIndexer {
     };
   }
 
+  /**
+   * Build the theme-scoped resolutions for a token (issue 2026-09-12).
+   * Currently one theme: `dark`. See the ThemeResolutions doc for the null contract and for
+   * why wcag/dark-wcag are deliberately not resolved here.
+   *
+   * @param baseTriple the token's base resolution — used only as the unitType fallback, so the
+   *                   theme branch and the base branch agree on unit typing without
+   *                   duplicating TokenRefResolver's category→unit table.
+   */
+  private resolveThemeResolutions(name: string, baseTriple: ResolvedValueTriple): ThemeResolutions {
+    const refs = this.darkOverrides.get(name);
+    if (!refs) return { dark: null };
+    return { dark: this.resolveOverride(name, refs, baseTriple) };
+  }
+
+  /**
+   * Resolve one override's primitiveReferences through the same chain the base triple uses.
+   * Primary-ref extraction mirrors TokenRefResolver.extractPrimaryRef exactly (single key →
+   * that key; multi-key with `value` → `value`; otherwise composite → partial).
+   */
+  private resolveOverride(name: string, refs: OverrideRefs, baseTriple: ResolvedValueTriple): ThemeResolution {
+    const keys = Object.keys(refs);
+    const primaryRef = keys.length === 1 ? refs[keys[0]] : ('value' in refs ? refs.value : null);
+
+    // Composite override (e.g. { color, opacity }) — no honest single terminal value.
+    if (primaryRef == null) {
+      return {
+        primitiveReferences: { ...refs },
+        resolvedValue: name,
+        resolvedUnitType: baseTriple.resolvedUnitType,
+        resolutionDepth: 'partial',
+        modeValue: null,
+      };
+    }
+
+    const resolved = this.resolver?.resolve(primaryRef) ?? null;
+    if (!resolved) {
+      // The override points at a literal or an unknown token — report it, flagged partial.
+      return {
+        primitiveReferences: { ...refs },
+        resolvedValue: primaryRef,
+        resolvedUnitType: baseTriple.resolvedUnitType,
+        resolutionDepth: 'partial',
+        modeValue: null,
+      };
+    }
+
+    return {
+      primitiveReferences: { ...refs },
+      resolvedValue: resolved.value,
+      resolvedUnitType: resolved.unitType,
+      resolutionDepth: resolved.depth,
+      modeValue: extractDarkModeValue(resolved.value),
+    };
+  }
+
+  /**
+   * Load theme override files. Text-parsed — no coupling to the token pipeline.
+   * A missing file is WARNED (not silent): without it every token reports `dark: null`,
+   * which is indistinguishable from "no override" at the field level.
+   *
+   * @param tierRoot The resolved theme TIER ROOT (`resolveThemeTierRoot`'s return) — NOT a
+   *   project root. `themes/dark/SemanticOverrides.ts` is read directly under it (Spec 123
+   *   Task 1.5, DD24).
+   */
+  private loadThemeOverrides(tierRoot: string): void {
+    const darkPath = path.join(tierRoot, 'themes/dark/SemanticOverrides.ts');
+    const { overrides, fileFound } = parseSemanticOverrides(darkPath);
+    if (!fileFound) {
+      this.warnings.push(
+        `Dark theme overrides not found: ${darkPath} — get_token_details will report themeResolutions.dark = null for every token`
+      );
+      return;
+    }
+    if (overrides.size === 0) {
+      this.warnings.push(
+        `Dark theme overrides parsed to 0 entries: ${darkPath} — the file exists but no override entries matched (parser may be stale)`
+      );
+    }
+    this.darkOverrides = overrides;
+  }
+
   getFamily(family: string): TokenIndexEntry[] {
     const f = family.toLowerCase();
     const results: TokenIndexEntry[] = [];

package/application-mcp-server/src/indexer/__tests__/MultiRootIndexing.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @category evergreen
+ * @purpose Pin the component indexer's multi-root behavior (Spec 123 Task 1.4 — design C3 "Indexer")
+ *
+ * Interactions under test (tasks.md Task 1, subtask 1.4):
+ *   (i)   the consumer ∪ package UNION is applied at PASS 1; precedence keys on the DECLARED
+ *         component name; the legacy `core/` level under the consumer root is recognized (L-D8);
+ *   (iii) pass 3's composed-token resolution runs across BOTH roots;
+ *   (iv)  the token reindex path anchors on `bornRoot` (the explicit anchor), never a stale /
+ *         component-root-derived `lastProjectRoot`.
+ * Interaction (ii) — watcher + StalenessGate over the consumer root — is exercised on the
+ * application server in `src/__tests__/consumerRootLiveReindex.test.ts`.
+ *
+ * Fixture shape mirrors a real consumer install: the package root sits under
+ * `node_modules/@3fn/core/src/components/core`, the consumer root at `src/components`.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { ComponentIndexer } from '../ComponentIndexer';
+import { buildConsumerFixture, writeComponent, ConsumerFixture } from './fixtures/consumerFixture';
+
+describe('ComponentIndexer — multi-root (Spec 123 Task 1.4)', () => {
+  let fx: ConsumerFixture;
+
+  beforeEach(() => {
+    fx = buildConsumerFixture('dp-multiroot-');
+  });
+
+  afterEach(() => {
+    fs.rmSync(fx.base, { recursive: true, force: true });
+  });
+
+  // (i) ---------------------------------------------------------------------
+  it('(i) applies the union at pass 1: a fork with a different directory name, inheriting a package parent, resolves and wins on its DECLARED name', async () => {
+    const indexer = new ComponentIndexer();
+    await indexer.indexComponents([fx.consumerRoot, fx.packageRoot], undefined, undefined, undefined, undefined, { projectRoot: fx.base });
+
+    // Asserted count: 3 package + 2 consumer, minus the 1 package component the fork shadows.
+    const catalog = indexer.getCatalog();
+    expect(catalog.map(c => c.name).sort()).toEqual(['Card-Consumer', 'Panel-Base', 'Widget-Base', 'Widget-Primary']);
+    expect(catalog.filter(c => c.name === 'Widget-Primary')).toHaveLength(1);
+
+    const fork = indexer.getComponent('Widget-Primary')!;
+    // The fork won (its directory name `widget-primary-fork` differs from the declared name).
+    expect(fork.description).toBe('FORK');
+    expect(fork.tokens).toEqual(['color.fork']);
+    // ...and its inheritance of the PACKAGE parent resolved at pass 1.
+    expect(fork.contracts.inheritsFrom).toBe('Widget-Base');
+    expect(fork.contracts.active.interaction_pressable?.source).toBe('inherited');
+    expect(fork.contracts.active.visual_fork_marker?.source).toBe('own');
+    expect(fork.contracts.active.visual_package_marker).toBeUndefined();
+    expect(fork.warnings.filter(w => w.includes('Unresolved inheritance'))).toEqual([]);
+  });
+
+  it('(i) recognizes a legacy core/ level under the consumer root, with a named warning on each load', async () => {
+    writeComponent(path.join(fx.consumerRoot, 'core'), { dir: 'Legacy-Thing', name: 'Legacy-Thing', contracts: ['visual_legacy'] });
+    const indexer = new ComponentIndexer();
+    for (let load = 0; load < 2; load++) {
+      await indexer.indexComponents([fx.consumerRoot, fx.packageRoot], undefined, undefined, undefined, undefined, { projectRoot: fx.base });
+      expect(indexer.getComponent('Legacy-Thing')).not.toBeNull();
+      const legacyWarnings = indexer.getHealth().warnings.filter(w => w.startsWith('Legacy component level:'));
+      expect(legacyWarnings).toHaveLength(1);
+      expect(legacyWarnings[0]).toContain(path.join(fx.consumerRoot, 'core'));
+      // `core/` itself is a level, not a component — no "has no schema.yaml" warning for it.
+      expect(indexer.getHealth().warnings.filter(w => w.includes('has no schema.yaml: core'))).toEqual([]);
+    }
+    expect(indexer.getCatalog()).toHaveLength(5);
+  });
+
+  it('(i) a legacy core/ level that IS another root in the set (steward layout) is left to that root — no duplicates, no warning', async () => {
+    // Steward shape: consumer root = <repo>/src/components, package root = <repo>/src/components/core.
+    const stewardComponents = path.join(fx.base, 'steward', 'src', 'components');
+    const stewardCore = path.join(stewardComponents, 'core');
+    writeComponent(stewardCore, { dir: 'Steward-Thing', name: 'Steward-Thing', contracts: ['visual_steward'] });
+    const indexer = new ComponentIndexer();
+    await indexer.indexComponents([stewardComponents, stewardCore]);
+    expect(indexer.getCatalog().map(c => c.name)).toEqual(['Steward-Thing']);
+    expect(indexer.getHealth().warnings.filter(w => w.startsWith('Legacy component level:'))).toEqual([]);
+  });
+
+  // (iii) -------------------------------------------------------------------
+  it('(iii) pass 3 resolves composed tokens across both roots', async () => {
+    const indexer = new ComponentIndexer();
+    await indexer.indexComponents([fx.consumerRoot, fx.packageRoot], undefined, undefined, undefined, undefined, { projectRoot: fx.base });
+
+    // Consumer component composing a PACKAGE child.
+    const card = indexer.getComponent('Card-Consumer')!;
+    expect(card.resolvedTokens.composed).toEqual({ 'Widget-Base': ['space100'] });
+    expect(card.warnings.filter(w => w.includes('not indexed'))).toEqual([]);
+
+    // Package component composing a child the CONSUMER forked → the fork's tokens (precedence holds in pass 3).
+    const panel = indexer.getComponent('Panel-Base')!;
+    expect(panel.resolvedTokens.composed).toEqual({ 'Widget-Primary': ['color.fork'] });
+    expect(panel.warnings.filter(w => w.includes('not indexed'))).toEqual([]);
+  });
+
+  // (iv) --------------------------------------------------------------------
+  it('(iv) the token reindex path anchors on bornRoot — never a component-root derivation, never a stale anchor', async () => {
+    const indexer = new ComponentIndexer();
+    const tokenIndexer = indexer.getTokenIndexer();
+    const spy = jest.spyOn(tokenIndexer, 'indexTokens').mockResolvedValue(undefined);
+
+    const bornA = fx.base;
+    await indexer.indexComponents([fx.consumerRoot, fx.packageRoot], undefined, undefined, undefined, undefined, { projectRoot: bornA });
+    await indexer.reindexTokens('/tokens-a');
+    // Spec 123 Task 1.5: `reindexTokens` now also threads `explicitTierDir` (the
+    // `options.tierDir` from the last full index — `undefined` here, since none was
+    // passed) as indexTokens' third argument (DD24 — the theme root resolution).
+    expect(spy).toHaveBeenLastCalledWith('/tokens-a', bornA, undefined);
+    // Non-vacuity: the pre-123 derivation from the consumer root would NOT have been bornA.
+    expect(path.resolve(fx.consumerRoot, '..', '..', '..')).not.toBe(bornA);
+
+    // A later full index with a different anchor → the reindex path follows it (no stale reuse).
+    const bornB = path.join(fx.base, 'elsewhere');
+    await indexer.indexComponents([fx.consumerRoot, fx.packageRoot], undefined, undefined, undefined, undefined, { projectRoot: bornB });
+    await indexer.reindexTokens('/tokens-b');
+    expect(spy).toHaveBeenLastCalledWith('/tokens-b', bornB, undefined);
+    spy.mockRestore();
+  });
+
+  // Watcher-path precedence (supports interaction (ii)) ---------------------
+  it('reindexComponent respects precedence: a shadowed package dir does not overwrite the fork; only the reindexed dir\'s own entry is replaced', async () => {
+    const indexer = new ComponentIndexer();
+    await indexer.indexComponents([fx.consumerRoot, fx.packageRoot], undefined, undefined, undefined, undefined, { projectRoot: fx.base });
+    const before = indexer.getCatalog().map(c => c.name).sort();
+
+    await indexer.reindexComponent(path.join(fx.packageRoot, 'Widget-Primary'));
+    expect(indexer.getComponent('Widget-Primary')!.description).toBe('FORK');
+
+    await indexer.reindexComponent(path.join(fx.consumerRoot, 'Card-Consumer'));
+    expect(indexer.getCatalog().map(c => c.name).sort()).toEqual(before);
+  });
+});

package/application-mcp-server/src/indexer/__tests__/ThemeResolution.test.ts

@@ -0,0 +1,241 @@
+/**
+ * @category evergreen
+ * @purpose Pin get_token_details' DARK resolution for Level 2 theme-varying tokens
+ *
+ * REGRESSION UNDER TEST (.kiro/issues/2026-09-12-mcp-token-details-dark-value-stale.md)
+ * -------------------------------------------------------------------------------------
+ * `get_token_details` resolved a token's BASE `primitiveReferences` only, so every token
+ * carrying a Level 2 dark override (src/tokens/themes/dark/SemanticOverrides.ts) was reported
+ * with its LIGHT value — including inside the `dark` slot of the resolved colour bundle,
+ * because legacy colour primitives have identical light.base and dark.base. The MCP is the
+ * agents' source of truth; it was authoritative and wrong for every theme-varying token.
+ *
+ * These tests run against the LIVE corpus (repo token-index + the real dark theme file) —
+ * that is deliberate: the defect was a disagreement between two real files, and a synthetic
+ * fixture could not have caught it. Fixture-backed cases below cover the null/absence and
+ * missing-file contracts, which the live corpus cannot exercise.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { TokenIndexer } from '../TokenIndexer';
+import { parseSemanticOverrides } from '../SemanticOverrideReader';
+
+/** __tests__ → indexer → src → application-mcp-server → repo root */
+const REPO_ROOT = path.resolve(__dirname, '../../../../');
+const TOKEN_INDEX_DIR = path.join(REPO_ROOT, 'token-index');
+const DARK_OVERRIDES = path.join(REPO_ROOT, 'src/tokens/themes/dark/SemanticOverrides.ts');
+
+/**
+ * Snapshot literals for the primitives these tests pin. If a primitive's value legitimately
+ * changes, update the literal here AND confirm the change was intended — the point of the
+ * literal is that a silent light/dark mix-up cannot hide behind a relational assertion
+ * (legacy primitives have light.base === dark.base, so relational checks alone are blind).
+ */
+const GRAY400_DARK_BASE = 'oklch(0.42 0.018 260)';
+const WHITE100_DARK_BASE = 'oklch(1 0 260)';
+const WHITE300_DARK_BASE = 'oklch(0.9 0.01 260)';
+
+describe('get_token_details — dark theme resolution (live corpus)', () => {
+  let indexer: TokenIndexer;
+
+  beforeAll(async () => {
+    indexer = new TokenIndexer();
+    await indexer.indexTokens(TOKEN_INDEX_DIR, REPO_ROOT);
+  });
+
+  it('loads the live corpus without theme-override warnings', () => {
+    expect(fs.existsSync(DARK_OVERRIDES)).toBe(true);
+    expect(indexer.getWarnings()).toEqual([]);
+  });
+
+  // -------------------------------------------------------------------------
+  // THE REPORTED BUG — color.structure.canvas (dark override → gray400 since Spec 050)
+  // -------------------------------------------------------------------------
+  describe('color.structure.canvas', () => {
+    it('reports the dark override (gray400), NOT the light base (white100)', () => {
+      const details = indexer.getDetails('color.structure.canvas')!;
+      expect(details.themeResolutions.dark).not.toBeNull();
+
+      const dark = details.themeResolutions.dark!;
+      expect(dark.primitiveReferences).toEqual({ value: 'gray400' });
+      expect(dark.resolutionDepth).toBe('full');
+      expect(dark.resolvedUnitType).toBe('color');
+      // The assertion the bug would have failed: dark value is gray400's, not white100's.
+      expect(dark.modeValue).toBe(GRAY400_DARK_BASE);
+      expect(dark.modeValue).not.toBe(WHITE100_DARK_BASE);
+    });
+
+    it('leaves the base triple untouched (still the LIGHT resolution — additive fix)', () => {
+      const details = indexer.getDetails('color.structure.canvas')!;
+      expect(details.primitiveReferences).toEqual({ value: 'white100' });
+      expect(details.resolutionDepth).toBe('full');
+      expect((details.resolvedValue as any).light.base).toBe(WHITE100_DARK_BASE);
+    });
+
+    it('exposes the full primitive bundle on the dark resolution (same shape rules as base)', () => {
+      const dark = indexer.getDetails('color.structure.canvas')!.themeResolutions.dark!;
+      expect((dark.resolvedValue as any).dark.base).toBe(GRAY400_DARK_BASE);
+      expect((dark.resolvedValue as any).light.base).toBe(GRAY400_DARK_BASE);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // The 2026-09-13 dark text-hierarchy overrides (WCAG AA interim remediation)
+  // -------------------------------------------------------------------------
+  describe('text hierarchy overrides (2026-09-13)', () => {
+    it('color.text.default resolves dark to white100', () => {
+      const dark = indexer.getDetails('color.text.default')!.themeResolutions.dark!;
+      expect(dark.primitiveReferences).toEqual({ value: 'white100' });
+      expect(dark.modeValue).toBe(WHITE100_DARK_BASE);
+      expect(dark.resolutionDepth).toBe('full');
+    });
+
+    it('color.text.muted resolves dark to white300', () => {
+      const dark = indexer.getDetails('color.text.muted')!.themeResolutions.dark!;
+      expect(dark.primitiveReferences).toEqual({ value: 'white300' });
+      expect(dark.modeValue).toBe(WHITE300_DARK_BASE);
+    });
+
+    it('color.feedback.success.text resolves dark to green300 (Spec 112 F4)', () => {
+      const dark = indexer.getDetails('color.feedback.success.text')!.themeResolutions.dark!;
+      expect(dark.primitiveReferences).toEqual({ value: 'green300' });
+      expect(dark.resolutionDepth).toBe('full');
+      expect(dark.modeValue).not.toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Composite override — documented partial behaviour, not a silent mishandle
+  // -------------------------------------------------------------------------
+  it('composite override (color.structure.border.subtle) reports partial + both refs', () => {
+    const dark = indexer.getDetails('color.structure.border.subtle')!.themeResolutions.dark!;
+    expect(dark.primitiveReferences).toEqual({ color: 'gray500', opacity: 'opacity048' });
+    // No honest single terminal value for colour+opacity — mirrors the base triple's
+    // multi-ref branch rather than silently collapsing to one of the two refs.
+    expect(dark.resolutionDepth).toBe('partial');
+    expect(dark.resolvedValue).toBe('color.structure.border.subtle');
+    expect(dark.modeValue).toBeNull();
+  });
+
+  // -------------------------------------------------------------------------
+  // NULL CONTRACT — dark === null means "dark resolves like the base triple"
+  // -------------------------------------------------------------------------
+  describe('null contract for non-overridden tokens', () => {
+    it('a wcag-only override (color.action.primary) reports dark: null — correctly', () => {
+      // color.action.primary IS overridden in src/tokens/themes/wcag (cyan300 → teal300) but
+      // NOT in dark. dark: null is therefore the right answer today. It also shows why the
+      // wcag theme was deferred rather than folded in: the index's own `themeVarying` flag is
+      // computed from the DARK override union only, so wcag overrides are invisible here too.
+      const details = indexer.getDetails('color.action.primary')!;
+      expect(details.themeVarying).toBe(false);
+      expect(details.themeResolutions.dark).toBeNull();
+    });
+
+    it('a non-colour semantic (space.grouped.normal) reports dark: null', () => {
+      const details = indexer.getDetails('space.grouped.normal');
+      expect(details).not.toBeNull();
+      expect(details!.themeResolutions.dark).toBeNull();
+    });
+
+    it('a primitive (white100) reports dark: null — overrides are semantic-tier only', () => {
+      expect(indexer.getDetails('white100')!.themeResolutions.dark).toBeNull();
+    });
+
+    it('themeResolutions is ALWAYS present, never omitted', () => {
+      for (const name of ['white100', 'color.action.primary', 'color.structure.canvas']) {
+        const details = indexer.getDetails(name)!;
+        expect(Object.prototype.hasOwnProperty.call(details, 'themeResolutions')).toBe(true);
+      }
+    });
+  });
+
+  it('every dark override key in the theme file resolves to a non-null dark resolution', () => {
+    const { overrides } = parseSemanticOverrides(DARK_OVERRIDES);
+    expect(overrides.size).toBeGreaterThan(0);
+    for (const name of Array.from(overrides.keys())) {
+      const details = indexer.getDetails(name);
+      expect(details).not.toBeNull();
+      expect(details!.themeResolutions.dark).not.toBeNull();
+    }
+  });
+});
+
+// ===========================================================================
+// Fixture-backed: the cases the live corpus cannot exercise
+// ===========================================================================
+
+describe('dark theme resolution — missing theme file (degraded, but NOT silent)', () => {
+  let tmpDir: string;
+  let indexer: TokenIndexer;
+
+  beforeAll(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dp-theme-res-'));
+    const tokenDir = path.join(tmpDir, 'token-index');
+    fs.mkdirSync(tokenDir, { recursive: true });
+    fs.writeFileSync(path.join(tokenDir, 'primitives.yaml'), yaml.dump({
+      tokens: { gray400: { family: 'color', value: { light: { base: 'L' }, dark: { base: 'D' } }, platforms: { web: '--gray-400', ios: 'gray400', android: 'gray_400' } } },
+    }));
+    fs.writeFileSync(path.join(tokenDir, 'semantics.yaml'), yaml.dump({
+      tokens: { 'color.structure.canvas': { category: 'color', primitiveReferences: { value: 'gray400' }, themeVarying: true, platforms: { web: '--x', ios: 'x', android: 'x' } } },
+    }));
+
+    indexer = new TokenIndexer();
+    await indexer.indexTokens(tokenDir, tmpDir); // tmpDir has no src/tokens/themes/**
+  });
+
+  afterAll(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+  it('warns when the dark theme file is absent', () => {
+    expect(indexer.getWarnings().some(w => w.includes('Dark theme overrides not found'))).toBe(true);
+  });
+
+  it('still answers, with dark: null (never throws, never invents a value)', () => {
+    expect(indexer.getDetails('color.structure.canvas')!.themeResolutions.dark).toBeNull();
+  });
+});
+
+describe('SemanticOverrideReader', () => {
+  it('parses the live dark theme file: keys + refs', () => {
+    const { overrides, fileFound } = parseSemanticOverrides(DARK_OVERRIDES);
+    expect(fileFound).toBe(true);
+    expect(overrides.get('color.structure.canvas')).toEqual({ value: 'gray400' });
+    expect(overrides.get('color.structure.border.subtle')).toEqual({ color: 'gray500', opacity: 'opacity048' });
+  });
+
+  it('ignores commented-out (fallback) entries — only the exported map counts', () => {
+    const { overrides } = parseSemanticOverrides(DARK_OVERRIDES);
+    // Present as a commented Level 1 fallback line in the theme file, not in the exported map.
+    expect(overrides.has('color.identity.human')).toBe(false);
+  });
+
+  it('reports fileFound: false for a missing file (no throw)', () => {
+    const { overrides, fileFound } = parseSemanticOverrides('/nonexistent/SemanticOverrides.ts');
+    expect(fileFound).toBe(false);
+    expect(overrides.size).toBe(0);
+  });
+
+  it('handles multi-line and nested-brace entries via balanced-brace extraction', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dp-override-parse-'));
+    const file = path.join(dir, 'SemanticOverrides.ts');
+    fs.writeFileSync(file, [
+      "export const x: SemanticOverrideMap = {",
+      "  'a.multi.line': {",
+      "    primitiveReferences: {",
+      "      value: 'gray400',",
+      "    },",
+      "  },",
+      "  'b.composite': { primitiveReferences: { color: 'gray500', opacity: 'opacity048' } },",
+      "};",
+      "",
+    ].join('\n'));
+
+    const { overrides } = parseSemanticOverrides(file);
+    expect(overrides.get('a.multi.line')).toEqual({ value: 'gray400' });
+    expect(overrides.get('b.composite')).toEqual({ color: 'gray500', opacity: 'opacity048' });
+
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});