@3fn/core 13.0.0

package/src/config/ConfigLoader.ts

@@ -0,0 +1,143 @@
+/**
+ * Configuration Loader
+ *
+ * Loads `designerpunk.config.ts` from the working directory.
+ * Falls back to defaults when no config file exists.
+ * Resolves all paths relative to the config file's directory.
+ *
+ * @see Spec 094 design.md § "ConfigLoader"
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import type { DesignerPunkConfig, ConfigTheme } from './defineConfig';
+import { scopedTsRequire } from './scopedTsRequire';
+import { resolvePackageRoot } from '../cli/shared/resolvePackageRoot';
+
+/** Fully resolved configuration with absolute paths. */
+export interface ResolvedConfig {
+  /** Product name for generated type names. */
+  name: string;
+  /** Short form for environment keys. */
+  abbreviation: string;
+  /** Registered themes from config. */
+  themes: ConfigTheme[];
+  /** Resolved absolute path to token source root. */
+  tokenSourceRoot: string;
+  /** Whether token source is local (from config) or package (default). */
+  tokenSourceMode: 'local' | 'package';
+  /** Resolved absolute paths to component token directories. */
+  componentTokenDirs: string[];
+  /** Resolved absolute path to output directory. */
+  outputDir: string;
+  /** Directory the config file was loaded from (or cwd for defaults). */
+  configDir: string;
+  /** Resolved absolute path to product tokens directory, or undefined if not configured. */
+  productTokens?: string;
+}
+
+const DEFAULTS = {
+  name: 'DesignerPunk',
+  abbreviation: 'DP',
+  themes: [] as ConfigTheme[],
+  componentTokens: [] as string[],
+  output: 'dist',
+};
+
+/**
+ * Loads a config module at runtime and returns its module namespace object
+ * (the caller unwraps `.default`). The injectable resolution seam for
+ * {@link loadConfig} — see {@link defaultConfigModuleLoader}.
+ */
+export type ConfigModuleLoader = (configPath: string) => unknown | Promise<unknown>;
+
+/**
+ * Default config-module loader — **Approach A** (Spec 118 Task 1 selection):
+ * `tsx/cjs/api` namespaced `register` + scoped synchronous `require`.
+ *
+ * Spec 118 Task 9.5: this delegates to the SHARED {@link scopedTsRequire} primitive —
+ * the single runtime-TS resolution mechanism behind all three per-site scoped seams
+ * (config, `resolveTokens`, `loadComponentTokens`), replacing three inline copies of the
+ * register/require/unregister cycle. The mechanism is unchanged: `register()` mutates
+ * `module._resolveFilename` / `module._extensions` process-globally; the namespace scopes
+ * requests; `unregister()` (in `finally`, inside `scopedTsRequire`) restores global state —
+ * load-bearing for the no-ambient-residue criterion. (Task 1: `findings/loader-selection.md`.)
+ *
+ * Anchored at `__filename` so transitive relative imports inside the config resolve as
+ * before. Returns synchronously; the loader type stays `Promise`-compatible for callers.
+ *
+ * Constraint: this loader **cannot run inside a jest process** — tsx's scoped require
+ * appends a `?namespace=` tag that jest's module resolver rejects (ENOENT). In-process
+ * jest tests must inject a jest-compatible loader via `loadConfig`'s `loadModule`
+ * parameter (e.g. `(p) => import(p)`, `jestConfigModuleLoader`). Production (real-node)
+ * execution uses this default unconditionally — there is deliberately NO test-environment
+ * detection in this path.
+ */
+export const defaultConfigModuleLoader: ConfigModuleLoader = (configPath: string) =>
+  scopedTsRequire(configPath, __filename);
+
+/**
+ * Load and resolve a DesignerPunk configuration.
+ *
+ * @param cwd - Working directory to search for config file. Defaults to process.cwd().
+ * @param loadModule - Injectable config-module loader (resolution seam). Defaults to
+ *   {@link defaultConfigModuleLoader} (Approach A). In-process jest tests inject a
+ *   jest-compatible loader because Approach A cannot run inside jest (see that loader's docs).
+ * @returns Fully resolved configuration with absolute paths.
+ */
+export async function loadConfig(
+  cwd: string = process.cwd(),
+  loadModule: ConfigModuleLoader = defaultConfigModuleLoader,
+): Promise<ResolvedConfig> {
+  const configPath = path.resolve(cwd, 'designerpunk.config.ts');
+  let userConfig: DesignerPunkConfig = {};
+  let configDir = cwd;
+
+  if (fs.existsSync(configPath)) {
+    try {
+      // Resolution seam — production default is Approach A (tsx/cjs/api); see
+      // defaultConfigModuleLoader. In-process jest tests inject a jest-compatible
+      // loader. No test-environment detection lives in this path.
+      const loaded = await loadModule(configPath);
+      userConfig = (loaded as { default?: DesignerPunkConfig } & DesignerPunkConfig).default || (loaded as DesignerPunkConfig);
+      configDir = path.dirname(configPath);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Failed to load ${configPath}: ${message}`);
+    }
+  }
+
+  const name = userConfig.name || DEFAULTS.name;
+  const abbreviation = userConfig.abbreviation || DEFAULTS.abbreviation;
+  const themes = userConfig.themes || DEFAULTS.themes;
+  const output = userConfig.output || DEFAULTS.output;
+  const componentTokenPaths = userConfig.componentTokens || DEFAULTS.componentTokens;
+
+  // Resolve token source: configured local path or package's src/tokens/.
+  // Package-mode default routes through the shared resolvePackageRoot() (Spec 118 Task
+  // 9.5.2, Class C / B1) rather than `path.resolve(__dirname, '../tokens')`. The bare
+  // __dirname form breaks under compile-to-dist (dist/config → dist/tokens, where no raw
+  // .ts token source exists); resolving from the self-checking package root finds the
+  // package's `src/tokens` regardless of whether this module runs from `src/` (tsx) or
+  // `dist/` (compiled), so it survives the target model's compile-and-ship step.
+  const tokenSourceMode: 'local' | 'package' = userConfig.tokenSource ? 'local' : 'package';
+  const tokenSourceRoot = userConfig.tokenSource
+    ? path.resolve(configDir, userConfig.tokenSource)
+    : path.resolve(resolvePackageRoot(__dirname), 'src/tokens');
+
+  // Resolve paths relative to config directory
+  const outputDir = path.resolve(configDir, output);
+  const componentTokenDirs = componentTokenPaths.map(p => path.resolve(configDir, p));
+
+  return {
+    name,
+    abbreviation,
+    themes,
+    tokenSourceRoot,
+    tokenSourceMode,
+    componentTokenDirs,
+    outputDir,
+    configDir,
+    productTokens: userConfig.productTokens ? path.resolve(configDir, userConfig.productTokens) : undefined,
+  };
+}

package/src/config/__resolution-matrix__/README.md

@@ -0,0 +1,76 @@
+# Resolution-Matrix Harness (Spec 118, Task 1)
+
+Empirically determines which TS-aware loader `loadConfig` (`src/config/ConfigLoader.ts`)
+should use, by exercising candidate loaders against a faithful reproduction of the
+config-load failure — in **real `node` subprocesses, NOT under jest**.
+
+## Re-run
+
+```
+npm run test:resolution-matrix
+# or:  node src/config/__resolution-matrix__/run-matrix.js
+# subset: node src/config/__resolution-matrix__/run-matrix.js A      (only approach A)
+#         node src/config/__resolution-matrix__/run-matrix.js none A B
+```
+
+A single cell can be run directly:
+
+```
+node src/config/__resolution-matrix__/runner.js <none|A|B|C> <fixtureDir> <expectedSentinel>
+```
+
+## THE critical constraint — why this is NOT a jest test
+
+Under ts-jest, jest intercepts `await import()` via its own module registry and
+**never hits Node's strict-ESM resolver** — so a jest-hosted matrix goes *green
+against the very bug*. This is proven in-repo: `src/config/__tests__/ConfigLoader.test.ts`
+writes configs as `module.exports` in `.ts` files and passes today even though the
+production config-load path is broken. Therefore every cell here runs in a real
+`node` process (`runner.js`, plain CommonJS) that faithfully reproduces
+`loadConfig`'s load locus (CJS context: `__dirname`/`__filename`, no `import.meta`;
+`loaded.default || loaded` unwrap; fail-loud `try/catch`). The candidate loader is
+the only thing that can make a `.ts` config resolve.
+
+## The matrix
+
+Rows (each in BOTH ESM-authored and CJS-authored form — R2 AC4 forward-compat):
+
+- **source-directory import** — config imports a directory (`./src/config`) with no
+  explicit `/index.ts`. Bare-Node fails `Directory import not supported` (ESM) /
+  `Cannot find module` (CJS).
+- **faithful-consumer** — config does a compiled import (`./compiled/defineConfig.js`,
+  modeling `@3fn/core/config` → dist) PLUS a transitive relative raw-`.ts` override
+  `./my-overrides`. Bare-Node fails `Cannot find module ... ./my-overrides`.
+
+Fixtures use **real** authoring (`export default` + ESM imports / real `require()`),
+never `module.exports`-in-`.ts` (a jest-transform artifact that is neither faithful
+CJS nor ESM). The sentinel asserted is one **only the transitive `./my-overrides`
+import produces** (positive sentinel — never "not DEFAULTS").
+
+## Candidate loaders
+
+- **A** — `tsx/cjs/api` `register({namespace})` + scoped synchronous `require`,
+  with mandatory `unregister()` after the load (A mutates `module._resolveFilename`
+  process-globally; namespace only scopes requests, so `unregister()` is what
+  satisfies the no-residue criterion).
+- **B** — `tsImport` via `await import('tsx/esm/api')` with `parentURL` from
+  `pathToFileURL(__filename)`.
+- **C** — `jiti` (NOT installed; only exercised if both A and B fail; would be a
+  budgeted dependency add).
+
+## Accept-criteria
+
+(a) failing rows green; (b) both CJS- and ESM-authored configs; (c) operates in
+`loadConfig`'s CJS context incl. transitive relative raw-`.ts` (OQ-1); (d) preserves
+`loaded.default || loaded` + fail-loud (resolution failure THROWS, never partial);
+(e) leaves no ambient/global residue after the call.
+
+## Result (see `findings/loader-selection.md` for the dated record)
+
+A passes all rows in both directions with no residue; B fails all rows (the OQ-1
+CJS-host/ESM-loader boundary — `tsImport` does not resolve the transitive raw-`.ts`
+from a CJS host, and leaves residue). **Selected: A.** jiti was not needed.
+
+> This harness is the Task-1 selection evidence. The *standing* preventive guard is
+> the Task-3 subprocess consumer guard (pack → install → `npx designerpunk generate`);
+> this harness is a re-runnable selection/regression tool, not the CI release gate.

package/src/config/__resolution-matrix__/fixtures/faithful-cjs/compiled/defineConfig.js

@@ -0,0 +1,9 @@
+/**
+ * COMPILED require target (models `@3fn/core/config` → dist CJS output).
+ * Pure CJS; required by the CJS-authored config via require('./compiled/defineConfig.js').
+ */
+'use strict';
+function defineConfig(config) {
+  return config;
+}
+module.exports = { defineConfig };

package/src/config/__resolution-matrix__/fixtures/faithful-cjs/designerpunk.config.ts

@@ -0,0 +1,20 @@
+/**
+ * Matrix row: faithful-consumer (CJS-authored).
+ *
+ * Faithful CJS authoring of the same conjunction the ESM variant exercises:
+ *   (1) `.ts` config (typeless package),
+ *   (2) a COMPILED `require('./compiled/defineConfig.js')` (models dist), and
+ *   (3) a TRANSITIVE relative raw-`.ts` override `require('./my-overrides')`
+ *       (no extension) — the require that, without a TS-aware loader, fails
+ *       `Cannot find module ... ./my-overrides`.
+ *
+ * Sentinel produced ONLY by the transitive `./my-overrides` raw-`.ts` require.
+ */
+const { defineConfig } = require('./compiled/defineConfig.js');
+const { overrideSentinel } = require('./my-overrides');
+
+module.exports = defineConfig({
+  name: 'FaithfulCJS',
+  abbreviation: 'FC',
+  sentinel: overrideSentinel,
+});

package/src/config/__resolution-matrix__/fixtures/faithful-cjs/my-overrides.ts

@@ -0,0 +1,8 @@
+/**
+ * Transitive relative raw-`.ts` override (CJS). Required by the config as
+ * `require('./my-overrides')` (no extension). Carries the sentinel that ONLY
+ * this module produces — the positive-sentinel target for the faithful-consumer
+ * CJS row.
+ */
+const overrideSentinel = 'faithful-cjs:my-overrides-resolved';
+module.exports = { overrideSentinel };

package/src/config/__resolution-matrix__/fixtures/faithful-esm/compiled/defineConfig.js

@@ -0,0 +1,11 @@
+/**
+ * COMPILED import target (models `@3fn/core/config` → dist CJS output).
+ * Pure CJS (`module.exports`), as the project's dist is CJS. The ESM-authored
+ * config imports it via `import { defineConfig } from './compiled/defineConfig.js'`,
+ * exercising the ESM->CJS named-import interop that the real workflow relies on.
+ */
+'use strict';
+function defineConfig(config) {
+  return config;
+}
+module.exports = { defineConfig };

package/src/config/__resolution-matrix__/fixtures/faithful-esm/designerpunk.config.ts

@@ -0,0 +1,23 @@
+/**
+ * Matrix row: faithful-consumer (ESM-authored).
+ *
+ * Reproduces the documented theme-override workflow's failure conjunction:
+ *   (1) ESM-syntax `.ts` config under a typeless package,
+ *   (2) a COMPILED import (`./compiled/defineConfig.js`, modeling
+ *       `@3fn/core/config` → dist), and
+ *   (3) a TRANSITIVE relative raw-`.ts` override import (`./my-overrides`)
+ *       — no extension — which hits Node's strict-ESM resolver and fails
+ *       `Cannot find module ... ./my-overrides`.
+ *
+ * The sentinel is produced ONLY by the transitive `./my-overrides` raw-`.ts`
+ * import (Lina SF-A: positive sentinel, never "not DEFAULTS"), so the row is
+ * green only if the transitive raw-`.ts` require actually resolved.
+ */
+import { defineConfig } from './compiled/defineConfig.js';
+import { overrideSentinel } from './my-overrides';
+
+export default defineConfig({
+  name: 'FaithfulESM',
+  abbreviation: 'FE',
+  sentinel: overrideSentinel,
+});

package/src/config/__resolution-matrix__/fixtures/faithful-esm/my-overrides.ts

@@ -0,0 +1,6 @@
+/**
+ * Transitive relative raw-`.ts` override (ESM). Imported by the config as
+ * `./my-overrides` (no extension). Carries the sentinel that ONLY this module
+ * produces — the positive-sentinel target for the faithful-consumer ESM row.
+ */
+export const overrideSentinel = 'faithful-esm:my-overrides-resolved';

package/src/config/__resolution-matrix__/fixtures/source-dir-cjs/designerpunk.config.ts

@@ -0,0 +1,11 @@
+/**
+ * Matrix row: source-directory import (CJS-authored).
+ *
+ * Faithful CJS authoring: real `require()` of a DIRECTORY (`./src/config`) with
+ * no explicit `/index.ts`, exported via `module.exports`. Exercises the same
+ * directory-index resolution as the ESM variant but through the CJS require path,
+ * proving the loader does not silently assume a direction (R2 AC4).
+ */
+const { makeConfig, SENTINEL } = require('./src/config');
+
+module.exports = makeConfig({ sentinel: SENTINEL });

package/src/config/__resolution-matrix__/fixtures/source-dir-cjs/src/config/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Directory-import target (CJS). Resolved only via the bare directory specifier
+ * `require('./src/config')` from the config — exercises directory-index resolution.
+ */
+const SENTINEL = 'source-dir-cjs:index-resolved';
+
+function makeConfig(opts) {
+  return {
+    name: 'SourceDirCJS',
+    abbreviation: 'SDC',
+    sentinel: opts.sentinel,
+  };
+}
+
+module.exports = { SENTINEL, makeConfig };

package/src/config/__resolution-matrix__/fixtures/source-dir-esm/designerpunk.config.ts

@@ -0,0 +1,15 @@
+/**
+ * Matrix row: source-directory import (ESM-authored).
+ *
+ * Faithfully reproduces the "source-directory import" failure: an ESM-syntax
+ * `.ts` config under a typeless package that imports a DIRECTORY (`./src/config`)
+ * with no explicit `/index.ts`. Under Node's strict-ESM resolver this fails with
+ * `Directory import ... is not supported`. A TS-aware loader must resolve the
+ * directory to its index module.
+ *
+ * The sentinel (`SENTINEL`) is produced ONLY by the directory's index module,
+ * so a positive sentinel assertion proves the directory import actually resolved.
+ */
+import { makeConfig, SENTINEL } from './src/config';
+
+export default makeConfig({ sentinel: SENTINEL });

package/src/config/__resolution-matrix__/fixtures/source-dir-esm/src/config/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Directory-import target (ESM). Resolved only via the bare directory specifier
+ * `./src/config` from the config — exercises directory-index resolution.
+ */
+export const SENTINEL = 'source-dir-esm:index-resolved';
+
+export function makeConfig(opts: { sentinel: string }) {
+  return {
+    name: 'SourceDirESM',
+    abbreviation: 'SDE',
+    sentinel: opts.sentinel,
+  };
+}

package/src/config/__resolution-matrix__/run-matrix.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Resolution-matrix ORCHESTRATOR (Spec 118, Task 1).
+ *
+ * Spawns a REAL `node` subprocess per (approach x row x authoring-direction)
+ * cell via runner.js, collects the structured JSON result, and prints a
+ * green/red table. NOTHING here runs under jest — each cell is a faithful
+ * `loadConfig`-locus reproduction executed by `node` directly, so the candidate
+ * loader is the only thing that can resolve a `.ts` config (THE critical
+ * constraint: jest's module registry would otherwise mask the bug).
+ *
+ * Re-run with:  npm run test:resolution-matrix
+ *           or: node src/config/__resolution-matrix__/run-matrix.js
+ *           or: node src/config/__resolution-matrix__/run-matrix.js A B   (subset)
+ *
+ * Exit code 0 only if every selected non-baseline approach behaves as the
+ * accept-criteria require for at least one fully-passing approach; otherwise 1.
+ * (The orchestrator is a reporting harness, not a release gate — the standing
+ * CI gate is the Task-3 subprocess consumer guard. This exits nonzero if NO
+ * approach passes all rows, so a regression that breaks the selected loader is
+ * visible when the harness is re-run.)
+ */
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const RUNNER = path.resolve(__dirname, 'runner.js');
+
+// row id -> { dir, sentinel, direction }
+const ROWS = [
+  { id: 'source-directory import', direction: 'ESM', dir: 'fixtures/source-dir-esm', sentinel: 'source-dir-esm:index-resolved' },
+  { id: 'source-directory import', direction: 'CJS', dir: 'fixtures/source-dir-cjs', sentinel: 'source-dir-cjs:index-resolved' },
+  { id: 'faithful-consumer',       direction: 'ESM', dir: 'fixtures/faithful-esm',   sentinel: 'faithful-esm:my-overrides-resolved' },
+  { id: 'faithful-consumer',       direction: 'CJS', dir: 'fixtures/faithful-cjs',   sentinel: 'faithful-cjs:my-overrides-resolved' },
+];
+
+// Default approaches: baseline + A + B. C only if explicitly requested AND jiti installed.
+const requested = process.argv.slice(2);
+const APPROACHES = requested.length ? requested : ['none', 'A', 'B'];
+
+function runCell(approach, row) {
+  const res = spawnSync('node', [RUNNER, approach, path.resolve(__dirname, row.dir), row.sentinel], {
+    encoding: 'utf-8',
+    cwd: __dirname,
+  });
+  let parsed = null;
+  const line = (res.stdout || '').trim().split('\n').filter(Boolean).pop();
+  try { parsed = JSON.parse(line); } catch { /* runner crashed before emitting */ }
+  if (!parsed) {
+    return { ok: false, sentinel: null, residue: { changed: false }, error: (res.stderr || 'no output').trim().split('\n')[0] };
+  }
+  return parsed;
+}
+
+const results = {}; // approach -> row-index -> cell
+
+for (const approach of APPROACHES) {
+  results[approach] = ROWS.map((row) => runCell(approach, row));
+}
+
+// ---- Print the table ----
+function cellGlyph(cell) {
+  if (cell.ok && !cell.residue.changed) return 'green';
+  if (cell.ok && cell.residue.changed) return 'green*';   // resolved but left residue
+  return 'red';
+}
+
+const label = (r) => `${r.id} [${r.direction}]`;
+const labelW = Math.max(...ROWS.map((r) => label(r).length));
+
+console.log('\n=== Spec 118 Resolution Matrix (real node subprocesses, NOT jest) ===\n');
+const header = ['row'.padEnd(labelW), ...APPROACHES.map((a) => a.padEnd(8))].join(' | ');
+console.log(header);
+console.log('-'.repeat(header.length));
+ROWS.forEach((row, i) => {
+  const cells = APPROACHES.map((a) => cellGlyph(results[a][i]).padEnd(8));
+  console.log([label(row).padEnd(labelW), ...cells].join(' | '));
+});
+
+console.log('\nLegend: green = resolved + sentinel matched + no residue;');
+console.log('        green* = resolved + sentinel matched BUT left global residue (fails criterion e);');
+console.log('        red = resolution failed (fail-loud threw) or sentinel mismatch.\n');
+
+// Per-approach accept-criteria summary.
+console.log('=== Accept-criteria summary (per approach) ===\n');
+const summary = {};
+for (const approach of APPROACHES) {
+  if (approach === 'none') continue;
+  const cells = results[approach];
+  const allResolved = cells.every((c) => c.ok);                // (a)(b)(c) rows green both directions
+  const noResidue = cells.every((c) => !c.residue.changed);    // (e)
+  summary[approach] = { allResolved, noResidue };
+  console.log(`Approach ${approach}:`);
+  console.log(`  (a) failing rows green ......... ${cells.filter(c=>c.ok).length}/${cells.length}`);
+  console.log(`  (b) both CJS & ESM authored .... ${allResolved ? 'PASS' : 'FAIL'}`);
+  console.log(`  (e) no ambient/global residue .. ${noResidue ? 'PASS' : 'FAIL'}`);
+  cells.forEach((c, i) => {
+    if (!c.ok) console.log(`      red [${label(ROWS[i])}]: ${(c.error||'').split('\n')[0]}`);
+    else if (c.residue.changed) console.log(`      residue [${label(ROWS[i])}]: module._resolveFilename not restored`);
+  });
+  console.log('');
+}
+
+// Exit nonzero if no non-baseline approach fully passes (a)(b)(c)+(e).
+const anyFullPass = Object.values(summary).some((s) => s.allResolved && s.noResidue);
+process.exit(anyFullPass ? 0 : 1);

package/src/config/__resolution-matrix__/runner.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Resolution-matrix RUNNER (Spec 118, Task 1).
+ *
+ * Runs ONE candidate loader against ONE fixture config, inside a FAITHFUL
+ * reproduction of `loadConfig`'s load locus, in a REAL `node` process.
+ *
+ * WHY a real `node` subprocess (THE critical constraint): under ts-jest, jest
+ * intercepts `await import()` via its own module registry and never hits Node's
+ * strict-ESM resolver — so a jest-hosted matrix goes green against the very bug
+ * (proven in-repo by ConfigLoader.test.ts passing today despite the production
+ * config-load path being broken). This runner is plain CJS executed by `node`
+ * directly (NOT jest, NOT ts-node), so the candidate loader is the ONLY thing
+ * that can make a `.ts` config resolve.
+ *
+ * This file is itself CommonJS (`module.exports` style, `__dirname`/`__filename`
+ * present, no `import.meta`) so it reproduces loadConfig's CJS execution context
+ * (ConfigLoader.ts:78) — the OQ-1 CJS-host boundary.
+ *
+ * Contract reproduced from ConfigLoader.ts:57-65 EXACTLY:
+ *   - the load locus is a single load call wrapped in try/catch
+ *   - unwrap is `loaded.default || loaded`
+ *   - failure is RE-WRAPPED and THROWN (fail-loud) — never a partial/empty config
+ *
+ * Usage:
+ *   node runner.js <approach:none|A|B|C> <fixtureDir> <expectedSentinel>
+ *
+ * Output (always, on stdout): a single JSON line:
+ *   { approach, fixtureDir, ok, sentinel, expectedSentinel, residue, error }
+ * Exit code 0 if ok && sentinel matches && no residue; non-zero otherwise.
+ */
+'use strict';
+
+const path = require('path');
+
+const [, , approach, fixtureDirArg, expectedSentinel] = process.argv;
+
+if (!approach || !fixtureDirArg) {
+  process.stderr.write('usage: node runner.js <approach> <fixtureDir> <expectedSentinel>\n');
+  process.exit(2);
+}
+
+const fixtureDir = path.resolve(fixtureDirArg);
+const configPath = path.resolve(fixtureDir, 'designerpunk.config.ts');
+
+/**
+ * The faithful reproduction of loadConfig's load locus.
+ * `doLoad(configPath)` MUST throw on resolution failure (fail-loud) and
+ * return the unwrapped userConfig on success.
+ */
+async function loadWith(approach, configPath) {
+  let loaded;
+
+  if (approach === 'none') {
+    // BASELINE: the current production locus, verbatim (ConfigLoader.ts:59).
+    // No TS-aware loader registered → reproduces the bug.
+    loaded = await import(configPath);
+  } else if (approach === 'A') {
+    // Approach A: tsx/cjs/api register({namespace}) + scoped (synchronous) require.
+    // register mutates module._resolveFilename + module._extensions PROCESS-GLOBALLY;
+    // the namespace only scopes requests. So A MUST call unregister() after the load
+    // to leave no residue (accept-criterion (e)). A's scoped require is SYNCHRONOUS
+    // (ScopedRequire) — `await` on it is harmless (Ada SF-2: do not "fix" it).
+    const { register } = require('tsx/cjs/api');
+    const ns = `dp-matrix-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const unregister = register({ namespace: ns });
+    try {
+      // The NamespacedUnregister carries a scoped `require(id, fromFile)`.
+      loaded = unregister.require(configPath, __filename);
+    } finally {
+      // Mandatory lifecycle: restore module._resolveFilename (residue criterion).
+      unregister.unregister();
+    }
+  } else if (approach === 'B') {
+    // Approach B: tsImport from tsx/esm/api, invoked from THIS CJS host.
+    // `__filename` exists in CJS so parentURL is clean. tsImport self-scopes
+    // (internal register({namespace: Date.now()}) per call) → no persistent
+    // global hook. OQ-1: does dynamic import() inside the ESM-loader hook
+    // resolve when the host is CJS, incl. the transitive relative raw-`.ts`?
+    const { pathToFileURL } = require('url');
+    const { tsImport } = await import('tsx/esm/api');
+    loaded = await tsImport(configPath, { parentURL: pathToFileURL(__filename).href });
+  } else if (approach === 'C') {
+    // Approach C: jiti (NOT installed unless explicitly added). Budgeted dep.
+    const { createJiti } = require('jiti');
+    const jiti = createJiti(__filename);
+    loaded = await jiti.import(configPath, { default: false });
+  } else {
+    throw new Error(`unknown approach: ${approach}`);
+  }
+
+  // Preserved unwrap (ConfigLoader.ts:60).
+  return loaded && (loaded.default || loaded);
+}
+
+/**
+ * Residue probe (accept-criterion (e)): capture module._resolveFilename and the
+ * set of registered require extensions BEFORE the load, and confirm they are
+ * restored AFTER. A non-restored hook = ambient/global residue.
+ */
+function snapshotResolver() {
+  const Module = require('module');
+  return {
+    resolveFilename: Module._resolveFilename,
+    extensions: Object.keys(Module._extensions).sort().join(','),
+  };
+}
+
+(async () => {
+  const result = {
+    approach,
+    fixtureDir,
+    ok: false,
+    sentinel: null,
+    expectedSentinel: expectedSentinel || null,
+    residue: null,
+    error: null,
+  };
+
+  const before = snapshotResolver();
+
+  try {
+    // Faithful reproduction of ConfigLoader.ts:57-65 (the try/catch + re-wrap).
+    let userConfig;
+    try {
+      const loaded = await loadWith(approach, configPath);
+      userConfig = loaded;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Failed to load ${configPath}: ${message}`);
+    }
+
+    result.sentinel = userConfig ? userConfig.sentinel : undefined;
+    result.ok = !!userConfig && result.sentinel === expectedSentinel;
+  } catch (err) {
+    result.error = err instanceof Error ? err.message : String(err);
+    result.ok = false;
+  }
+
+  // Residue check after the call (criterion (e)).
+  const after = snapshotResolver();
+  const residueChanged =
+    after.resolveFilename !== before.resolveFilename ||
+    after.extensions !== before.extensions;
+  result.residue = residueChanged
+    ? { changed: true, beforeExtensions: before.extensions, afterExtensions: after.extensions,
+        resolveFilenameChanged: after.resolveFilename !== before.resolveFilename }
+    : { changed: false };
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+  // Exit nonzero on any failure incl. residue (so the orchestrator and CI see it).
+  process.exit(result.ok && !result.residue.changed ? 0 : 1);
+})();