@catheadowl/dsh-eval 0.1.0 → 0.2.0

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@catheadowl/dsh-eval",
   "description": "Agent eval framework over dsh headless runs: case runner, session-trace assertions, and a scripted mock-LLM layer for plugin intent tests.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./experimental": "./src/experimental.mjs",
+    "./bin/dsh-eval": "./bin/dsh-eval.mjs",
+    "./bin/dsh-review": "./bin/dsh-review.mjs",
+    "./package.json": "./package.json"
+  },
   "peerDependencies": {
     "@deepseek-ai/dsh-llm": "*"
   },
@@ -20,12 +27,15 @@
     "src/",
     "docs/",
     "README.md",
+    "README.zh.md",
     "LICENSE"
   ],
   "scripts": {
     "verify:publish": "node scripts/verify-publish-readiness.mjs",
     "verify:face": "node scripts/verify-manifest-face.mjs",
-    "prepack": "node scripts/verify-manifest-face.mjs && node scripts/verify-publish-readiness.mjs",
-    "test": "node --test --test-isolation=none tests/trace.test.mjs tests/assertions.test.mjs tests/overlay.test.mjs tests/staging.test.mjs tests/runner.test.mjs tests/cli.test.mjs tests/discovery.test.mjs tests/review.test.mjs tests/report.test.mjs tests/config.test.mjs tests/review-report.test.mjs && node scripts/verify-publish-readiness.mjs && node scripts/verify-manifest-face.mjs"
+    "verify:experimental": "node scripts/verify-experimental-face.mjs",
+    "verify:readme-i18n": "node scripts/verify-readme-i18n.mjs",
+    "prepack": "node scripts/verify-manifest-face.mjs && node scripts/verify-publish-readiness.mjs && node scripts/verify-readme-i18n.mjs && node scripts/verify-experimental-face.mjs",
+    "test": "node --test --test-isolation=none tests/trace.test.mjs tests/assertions.test.mjs tests/overlay.test.mjs tests/staging.test.mjs tests/runner.test.mjs tests/cli.test.mjs tests/discovery.test.mjs tests/review.test.mjs tests/report.test.mjs tests/config.test.mjs tests/review-report.test.mjs && node scripts/verify-publish-readiness.mjs && node scripts/verify-manifest-face.mjs && node scripts/verify-readme-i18n.mjs && node scripts/verify-experimental-face.mjs"
   }
 }

package/src/adapters/dsh/review.mjs

@@ -1,192 +1,157 @@
-/** dsh-headless execution adapter for model-independent review experiments. */
-
-import { spawn } from 'node:child_process'
-import {
-  chmodSync,
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  rmSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs'
-import { homedir, tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { executeReviewExperiment } from '../../experiment/review.mjs'
-import { stageProfileStore } from '../../runner.mjs'
-import { loadTraceDir } from '../../trace.mjs'
-import { validateToolBoundary, renderToolBoundaryEvidence } from '../../tool-validation.mjs'
-
-/**
- * Model-facing tool rows every shipped dsh profile mounts from `dsh-base`.
- * The overlay disables all host tool rows as a supplementary guard; the
- * primary isolation comes from the sterile review profile (dsh-base +
- * dsh-headless only, no out-of-tree plugins).  Post-run tool boundary
- * validation (see `validateToolBoundary`) detects any residual drift.
- */
-const REVIEW_DISABLED_TOOL_ROWS = [
-  'tool-bash',
-  'tool-pwsh',
-  'tool-jobs',
-  'tool-fs',
-  'tool-fs-search',
-  'tool-skill',
-  'tool-todo',
-  'tool-goal',
-  'tool-ralph',
-  'tool-str-replace-editor',
-  'tool-web',
-  'tool-subagent-control',
-  'tool-subagent-list-agents',
-  'tool-subagent',
-  'tool-subagent-fork',
-  'tool-subagent-report',
-  'tool-workflow',
-]
-
-/** Serialize the tool-less overlay: disable every host model-facing tool row. */
-function buildReviewOverlayYaml() {
-  return REVIEW_DISABLED_TOOL_ROWS.map((id) => `- id: ${id}\n  disabled: true\n`).join('\n')
-}
-
-/** Resolve and validate the compiled dsh CLI entry point. */
-export function resolveDshCli(dshRepoDir) {
-  const repoDir = resolve(dshRepoDir)
-  const cli = join(repoDir, 'apps', 'cli', 'lib', 'bin.js')
-  if (!existsSync(cli)) {
-    throw new Error(`no compiled dsh CLI at '${cli}' (build deepseek-harness first)`)
-  }
-  return cli
-}
-
-/** The CLI entry for an executor: explicit cliPath (C6 chain result) wins;
- * otherwise fall back to the legacy repo form. Neither being set is a caller
- * bug the CLI bins already catch — this guard serves direct API consumers. */
-function executorCli(options) {
-  if (options.cliPath !== undefined) return resolve(options.cliPath)
-  if (options.dshRepoDir !== undefined) return resolveDshCli(options.dshRepoDir)
-  throw new Error('review adapter needs a CLI location: pass cliPath (C6 chain result) or dshRepoDir')
-}
-
-/**
- * Create an executor compatible with executeReviewExperiment.
- *
- * The executor boots a sterile review profile (default: the host's
- * `headless` template, bundles = dsh-base + dsh-headless, no out-of-tree
- * plugins) in an isolated DSH_HOME, disables every host tool row via
- * overlay, and validates the tool boundary after the run.  `options.profile`
- * must name a profile whose installed plugin set is empty or review-safe.
- *
- * @param {object} options
- * @param {string} [options.profile='headless'] - the sterile review profile.
- * @param {Set<string>} [options.allowedTools] - tool names permitted in the reviewer's session (default: empty).
- */
-export function createDshHeadlessReviewExecutor(options) {
-  const cli = executorCli(options)
-  const profile = options.profile ?? 'headless'
-  if (typeof profile !== 'string' || profile.length === 0) {
-    throw new TypeError('dsh review adapter requires a profile')
-  }
-  const timeoutMs = options.timeoutMs ?? 300_000
-  const allowedTools = options.allowedTools ?? new Set()
-
-  return async function executeWithDsh(task) {
-    // A fresh process alone is not enough: dsh also stores settings, titles,
-    // and sessions below DSH_HOME. Reuse the behavior harness's proven profile
-    // staging strategy so every reviewer receives an isolated runtime state
-    // while retaining the selected profile's model config and plugin links.
-    const runDir = mkdtempSync(join(tmpdir(), 'dsh-review-'))
-    const dshHome = join(runDir, 'dsh-home')
-    const overlayPath = join(runDir, 'review-overlay.yml')
-    writeFileSync(overlayPath, buildReviewOverlayYaml(), 'utf8')
-    const realHome = options.dshHome
-      ?? ((process.env.DSH_HOME ?? '').trim() !== '' ? process.env.DSH_HOME : join(homedir(), '.dsh'))
-    mkdirSync(dshHome, { recursive: true })
-    const junctions = stageProfileStore(realHome, dshHome, profile)
-    const realCredentials = join(realHome, '.credentials.yaml')
-    if (existsSync(realCredentials)) {
-      const credentialsCopy = join(dshHome, '.credentials.yaml')
-      copyFileSync(realCredentials, credentialsCopy)
-      try { chmodSync(credentialsCopy, 0o600) } catch { /* best-effort */ }
-    }
-
-    try {
-      const child = spawn(process.execPath, [cli, '--profile', profile, '--patch', overlayPath, task], {
-        cwd: options.cwd ?? runDir,
-        env: {
-          ...process.env,
-          ...options.env,
-          DSH_HOME: dshHome,
-          DSH_TELEMETRY_DISABLED: '1',
-        },
-      })
-      let stdout = ''
-      let stderr = ''
-      child.stdout.on('data', chunk => { stdout += chunk })
-      child.stderr.on('data', chunk => { stderr += chunk })
-
-      let timedOut = false
-      const timer = setTimeout(() => {
-        timedOut = true
-        child.kill('SIGTERM')
-      }, timeoutMs)
-      let exitCode
-      try {
-        exitCode = await new Promise((resolveExit, reject) => {
-          child.on('error', reject)
-          child.on('exit', code => resolveExit(code ?? 1))
-        })
-      } finally {
-        clearTimeout(timer)
-      }
-
-      const result = { stdout, stderr, exitCode, timedOut, profile, cli, runDir }
-      if (exitCode !== 0 || timedOut) {
-        const error = new Error(`dsh reviewer exited with code ${exitCode}${timedOut ? ' after timeout' : ''}`)
-        error.result = result
-        throw error
-      }
-
-      // Post-run tool boundary check: parse the session
-      // trace, verify no unexpected tools were mounted in the reviewer's
-      // session, fail the run on violation.  An absent session log skips
-      // the check gracefully (accepted fail-open).
-      // Validation inspects the main session only (buildTrace selects
-      // non-subagent logs); plugin tools leaking in a subagent session
-      // would not be caught — irrelevant in review where the overlay
-      // disables every subagent tool row.
-      const trace = loadTraceDir(join(dshHome, 'sessions'))
-      if (trace) {
-        const validation = validateToolBoundary(trace, { allowedTools })
-        result.toolValidation = validation
-        if (!validation.ok) {
-          // Attach evidence for the caller to persist (the adapter's
-          // runDir is ephemeral — removed by the finally block).  The
-          // bin writes this to `.runs/<id>/tool-boundary-evidence.json`.
-          result.toolBoundaryEvidence = renderToolBoundaryEvidence(validation, { runDir, profile })
-          const boundaryError = new Error(
-            `tool boundary violation: unexpected tools [${validation.unexpected.join(', ')}]`,
-          )
-          boundaryError.result = result
-          throw boundaryError
-        }
-      }
-
-      return result
-    } finally {
-      if (process.env.DSH_REVIEW_KEEP_TMP !== '1') {
-        for (const junction of junctions) {
-          try { unlinkSync(junction) } catch { /* already absent */ }
-        }
-        rmSync(runDir, { recursive: true, force: true })
-      }
-    }
-  }
-}
-
-/** Run a review experiment through fresh dsh headless processes. */
-export async function runDshReviewExperiment(experiment, options) {
-  const executor = createDshHeadlessReviewExecutor(options)
-  return executeReviewExperiment(experiment, executor, { runs: options.runs })
-}
+/** dsh-headless execution adapter for model-independent review experiments. */
+
+import { existsSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { executeReviewExperiment } from '../../experiment/review.mjs'
+import { CLI_RELATIVE_PATH } from '../../cli.mjs'
+import { overlayDisableRows } from '../../overlay.mjs'
+import {
+  resolveRealDshHome, stageSandboxHome, teardownSandbox, spawnHeadlessDsh,
+} from '../../sandbox.mjs'
+import { loadTraceDir } from '../../trace.mjs'
+import { validateToolBoundary, renderToolBoundaryEvidence } from '../../tool-validation.mjs'
+
+/**
+ * Model-facing tool rows every shipped dsh profile mounts from `dsh-base`.
+ * The overlay disables all host tool rows as a supplementary guard; the
+ * primary isolation comes from the sterile review profile (dsh-base +
+ * dsh-headless only, no out-of-tree plugins).  Post-run tool boundary
+ * validation (see `validateToolBoundary`) detects any residual drift.
+ */
+const REVIEW_DISABLED_TOOL_ROWS = [
+  'tool-bash',
+  'tool-pwsh',
+  'tool-jobs',
+  'tool-fs',
+  'tool-fs-search',
+  'tool-skill',
+  'tool-todo',
+  'tool-goal',
+  'tool-ralph',
+  'tool-str-replace-editor',
+  'tool-web',
+  'tool-subagent-control',
+  'tool-subagent-list-agents',
+  'tool-subagent',
+  'tool-subagent-fork',
+  'tool-subagent-report',
+  'tool-workflow',
+]
+
+/** Serialize the tool-less overlay: disable every host model-facing tool row. */
+function buildReviewOverlayYaml() {
+  return overlayDisableRows(REVIEW_DISABLED_TOOL_ROWS)
+}
+
+/** Resolve and validate the compiled dsh CLI entry point. */
+export function resolveDshCli(dshRepoDir) {
+  const repoDir = resolve(dshRepoDir)
+  const cli = join(repoDir, ...CLI_RELATIVE_PATH.split(/[\\/]/))
+  if (!existsSync(cli)) {
+    throw new Error(`no compiled dsh CLI at '${cli}' (build deepseek-harness first)`)
+  }
+  return cli
+}
+
+/** The CLI entry for an executor: explicit cliPath (C6 chain result) wins;
+ * otherwise fall back to the legacy repo form. Neither being set is a caller
+ * bug the CLI bins already catch — this guard serves direct API consumers. */
+function executorCli(options) {
+  if (options.cliPath !== undefined) return resolve(options.cliPath)
+  if (options.dshRepoDir !== undefined) return resolveDshCli(options.dshRepoDir)
+  throw new Error('review adapter needs a CLI location: pass cliPath (C6 chain result) or dshRepoDir')
+}
+
+/**
+ * Create an executor compatible with executeReviewExperiment.
+ *
+ * The executor boots a sterile review profile (default: the host's
+ * `headless` template, bundles = dsh-base + dsh-headless, no out-of-tree
+ * plugins) in an isolated DSH_HOME (staging/teardown mechanics shared with
+ * the behavior runner via sandbox.mjs), disables every host tool row via
+ * overlay, and validates the tool boundary after the run.  `options.profile`
+ * must name a profile whose installed plugin set is empty or review-safe.
+ *
+ * @param {object} options
+ * @param {string} [options.profile='headless'] - the sterile review profile.
+ * @param {Set<string>} [options.allowedTools] - tool names permitted in the reviewer's session (default: empty).
+ */
+export function createDshHeadlessReviewExecutor(options) {
+  const cli = executorCli(options)
+  const profile = options.profile ?? 'headless'
+  if (typeof profile !== 'string' || profile.length === 0) {
+    throw new TypeError('dsh review adapter requires a profile')
+  }
+  const timeoutMs = options.timeoutMs ?? 300_000
+  const allowedTools = options.allowedTools ?? new Set()
+
+  return async function executeWithDsh(task) {
+    // A fresh process alone is not enough: dsh also stores settings, titles,
+    // and sessions below DSH_HOME. Reuse the behavior harness's sandbox
+    // (sandbox.mjs) so every reviewer receives an isolated runtime state
+    // while retaining the selected profile's model config and plugin links.
+    const runDir = mkdtempSync(join(tmpdir(), 'dsh-review-'))
+    const dshHome = join(runDir, 'dsh-home')
+    const overlayPath = join(runDir, 'review-overlay.yml')
+    writeFileSync(overlayPath, buildReviewOverlayYaml(), 'utf8')
+    stageSandboxHome(options.dshHome ?? resolveRealDshHome(), dshHome, profile)
+
+    try {
+      const { stdout, stderr, exitCode, timedOut } = await spawnHeadlessDsh({
+        cli,
+        cliArgs: ['--profile', profile, '--patch', overlayPath, task],
+        cwd: options.cwd ?? runDir,
+        env: {
+          ...process.env,
+          ...options.env,
+          DSH_HOME: dshHome,
+          DSH_TELEMETRY_DISABLED: '1',
+        },
+        timeoutMs,
+      })
+
+      const result = { stdout, stderr, exitCode, timedOut, profile, cli, runDir }
+      if (exitCode !== 0 || timedOut) {
+        const error = new Error(`dsh reviewer exited with code ${exitCode}${timedOut ? ' after timeout' : ''}`)
+        error.result = result
+        throw error
+      }
+
+      // Post-run tool boundary check: parse the session
+      // trace, verify no unexpected tools were mounted in the reviewer's
+      // session, fail the run on violation.  An absent session log skips
+      // the check gracefully (accepted fail-open).
+      // Validation inspects the main session only (buildTrace selects
+      // non-subagent logs); plugin tools leaking in a subagent session
+      // would not be caught — irrelevant in review where the overlay
+      // disables every subagent tool row.
+      const trace = loadTraceDir(join(dshHome, 'sessions'))
+      if (trace) {
+        const validation = validateToolBoundary(trace, { allowedTools })
+        result.toolValidation = validation
+        if (!validation.ok) {
+          // Attach evidence for the caller to persist (the adapter's
+          // runDir is ephemeral — removed by the finally block).  The
+          // bin writes this to `.runs/<id>/tool-boundary-evidence.json`.
+          result.toolBoundaryEvidence = renderToolBoundaryEvidence(validation, { runDir, profile })
+          const boundaryError = new Error(
+            `tool boundary violation: unexpected tools [${validation.unexpected.join(', ')}]`,
+          )
+          boundaryError.result = result
+          throw boundaryError
+        }
+      }
+
+      return result
+    } finally {
+      teardownSandbox(runDir, { keep: process.env.DSH_REVIEW_KEEP_TMP === '1' })
+    }
+  }
+}
+
+/** Run a review experiment through fresh dsh headless processes. */
+export async function runDshReviewExperiment(experiment, options) {
+  const executor = createDshHeadlessReviewExecutor(options)
+  return executeReviewExperiment(experiment, executor, { runs: options.runs })
+}

package/src/cli.mjs

@@ -1,16 +1,15 @@
 /**
- * Host CLI resolution chain (release-plan C6 / spec host-checkout-resolution).
+ * Host CLI resolution chain.
  *
  * Locating the compiled dsh CLI follows the same two-layer model as package
  * imports: committed files carry no real host-checkout path — the machine's
- * resolution layer (node_modules, junction-built by the relink anchor tool)
- * absorbs it. Precedence, first hit wins:
+ * resolution layer (node_modules) absorbs it. Precedence, first hit wins:
  *
  *   1. explicit `--repo <dir>` flag — the documented escape hatch;
  *   2. resolution layer — `node_modules/@deepseek-ai/dsh/lib/bin.js`
  *      (the CLI package's own bin target) reachable upward from startDir;
  *   3. config `repo` key (legacy) — kept working for existing checked-in
- *      `dsh-eval.config.mjs` files until the repo split retires them.
+ *      `dsh-eval.config.mjs` files.
  *
  * Every miss fails loud with a fingerprint and placeholder-only guidance —
  * no machine-specific example paths, no silent fallback to guessing.
@@ -29,10 +28,11 @@ const PACKAGED_CLI_PATH = join('node_modules', '@deepseek-ai', 'dsh', 'lib', 'bi
 export const NO_CLI_GUIDANCE = [
   'no dsh CLI found. In order:',
   "  1) pass --repo <host-checkout> explicitly;",
-  '  2) or make the resolution layer provide it: node_modules/@deepseek-ai/dsh/lib/bin.js',
-  '     (run the repo relink script to (re)build the junction tree from DSH_REPO,',
-  '     then build the host checkout if lib/ is missing);',
-  '  3) or set repo in dsh-eval.config.mjs (legacy, retired at repo split).',
+  '  2) or provide the CLI through the resolution layer:',
+  '     node_modules/@deepseek-ai/dsh/lib/bin.js — install the @deepseek-ai/dsh',
+  '     package (or link a built deepseek-harness checkout into node_modules',
+  '     and build it so lib/bin.js exists);',
+  '  3) or set repo in dsh-eval.config.mjs (legacy).',
 ].join('\n')
 
 /** Validate a repo-style candidate: return the CLI path or undefined. */

package/src/config.mjs

@@ -1,5 +1,5 @@
 /**
- * Shared `dsh-eval.config.mjs` discovery and loading (EVAL-008).
+ * Shared `dsh-eval.config.mjs` discovery and loading.
  *
  * Both CLIs (`dsh-eval`, `dsh-review`) repeat `--profile/--repo` wiring in
  * every consumer's package scripts. A per-package config file removes that

package/src/discovery.mjs

@@ -39,6 +39,23 @@ export function discoverFiles(path, suffix, out = []) {
   return out
 }
 
+/**
+ * Validate a `disableRows` declaration (case-level or ad-hoc): an array of
+ * non-empty loader row id strings. An EMPTY array is legal and means
+ * "disable nothing, explicitly" — it overrides a `disableRows` default
+ * from `dsh-eval.config.mjs`. Throws with `label` context. Shared by
+ * `validateEvalCase` (load time) and `runEvalCase` (execution time) so both
+ * report the identical message.
+ * @param {unknown} disableRows - the value to validate.
+ * @param {string} label - error-message context (e.g. `case '<id>'`).
+ */
+export function validateDisableRows(disableRows, label) {
+  if (!Array.isArray(disableRows)
+    || disableRows.some(row => typeof row !== 'string' || row === '')) {
+    throw new Error(`${label}: disableRows must be a string[] of loader row ids (empty = explicit none, overriding config; got '${JSON.stringify(disableRows)}')`)
+  }
+}
+
 /**
  * Validate one eval case's shape. Throws with a descriptive message on
  * the first violation found. Checks:
@@ -51,6 +68,10 @@ export function discoverFiles(path, suffix, out = []) {
  *   "disable nothing, explicitly" — it overrides a `disableRows` default
  *   from `dsh-eval.config.mjs`, which is how gate-interaction cases opt
  *   back in inside a package that disables the gate row by default.
+ * - `rowConfig` (if present) maps loader row ids to config objects whose
+ *   leaf values are scalars or arrays of scalars (see `validateRowConfig`).
+ *   The overlay REPLACES the row's whole config — restate any keys the row
+ *   needs, not just the ones being changed.
  * - `expect` is an array; every element has `describe` (string) and `check` (function).
  * - mock mode requires a `script` with `steps` array.
  *
@@ -74,10 +95,10 @@ export function validateEvalCase(evalCase, file) {
     throw new Error(`${file}: case '${evalCase.id}': the 'gates' field was removed — declare disableRows: ['gates'] instead`)
   }
   if (evalCase.disableRows !== undefined) {
-    if (!Array.isArray(evalCase.disableRows)
-      || evalCase.disableRows.some(row => typeof row !== 'string' || row === '')) {
-      throw new Error(`${file}: case '${evalCase.id}': disableRows must be a string[] of loader row ids (empty = explicit none, overriding config; got '${JSON.stringify(evalCase.disableRows)}')`)
-    }
+    validateDisableRows(evalCase.disableRows, `${file}: case '${evalCase.id}'`)
+  }
+  if (evalCase.rowConfig !== undefined) {
+    validateRowConfig(evalCase.rowConfig, `case '${evalCase.id}'`)
   }
   if (!Array.isArray(evalCase.expect)) {
     throw new Error(`${file}: case '${evalCase.id}': expect must be a Matcher[]`)
@@ -95,6 +116,36 @@ export function validateEvalCase(evalCase, file) {
   }
 }
 
+/**
+ * Validate a `rowConfig` mapping (case-level or ad-hoc): keys are loader row
+ * ids, values are config objects whose leaf values must be scalars (string /
+ * number / boolean) or arrays of scalars. Nested objects are rejected — the
+ * overlay emitter only handles flat config keys. Throws with `label` context.
+ * @param {unknown} rowConfig - the value to validate.
+ * @param {string} label - error-message context (e.g. `case '<id>'`).
+ */
+export function validateRowConfig(rowConfig, label) {
+  if (rowConfig === null || typeof rowConfig !== 'object' || Array.isArray(rowConfig)) {
+    throw new Error(`${label}: rowConfig must be an object mapping row ids to config objects (got '${JSON.stringify(rowConfig)}')`)
+  }
+  for (const [rowId, config] of Object.entries(rowConfig)) {
+    if (rowId === '') throw new Error(`${label}: rowConfig row id must be a non-empty string`)
+    if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+      throw new Error(`${label}: rowConfig['${rowId}'] must be a config object (got '${JSON.stringify(config)}')`)
+    }
+    for (const [key, value] of Object.entries(config)) {
+      if (key === '') throw new Error(`${label}: rowConfig['${rowId}'] has an empty config key`)
+      if (Array.isArray(value)) {
+        if (value.some(item => item === null || typeof item === 'object')) {
+          throw new Error(`${label}: rowConfig['${rowId}']['${key}'] must be an array of scalars`)
+        }
+      } else if (value === null || typeof value === 'object') {
+        throw new Error(`${label}: rowConfig['${rowId}']['${key}'] must be a scalar or scalar array (nested objects are not supported)`)
+      }
+    }
+  }
+}
+
 /**
  * Detect duplicate case ids across a flat case list. Throws on the first
  * duplicate found, naming both source files.

package/src/experimental.mjs

@@ -0,0 +1,39 @@
+/**
+ * Escape-hatch entry: mechanism primitives for ad-hoc diagnostic scripts and
+ * self-built execution faces. Reachable as `<pkg>/experimental`.
+ *
+ * Contract: NO compatibility promise — symbols here may change or move in
+ * any minor release. The stable surface for eval/review case authors is the
+ * package root entry (src/index.mjs); import from here only when you are
+ * building your own runner/driver and accept the follow-up cost.
+ */
+
+// --- host CLI resolution (modern three-segment chain) ---
+export { resolveDshCliChain } from './cli.mjs'
+
+// --- sandbox / overlay mechanism ---
+export { stageProfileStore } from './sandbox.mjs'
+export { buildOverlayYaml, overlayDisableRows } from './overlay.mjs'
+
+// --- session-trace primitives ---
+export { parseSessionLog, buildTrace, loadTraceDir } from './trace.mjs'
+
+// --- review experiment execution layer ---
+export {
+  executeReviewExperiment,
+  materializeReviewExperiment,
+  renderObservationSections,
+  OBSERVATIONS_PLACEHOLDER,
+} from './experiment/review.mjs'
+
+// --- dsh review executors ---
+export {
+  createDshHeadlessReviewExecutor,
+  runDshReviewExperiment,
+} from './adapters/dsh/review.mjs'
+
+// --- tool-boundary validation ---
+export {
+  validateToolBoundary,
+  renderToolBoundaryEvidence,
+} from './tool-validation.mjs'