@ngockhoale/ukit 3.0.7 → 3.0.9

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to UKit are documented here.
 
+## 3.0.9 - 2026-09-25
+
+- **ukit-memory stack (cycles C57–C62, waves W1–W6)** — the full v2 memory layer lands behind staged rollout flags:
+  - **Record store v2**: versioned `records.json` store (`src/core/memory/storeV2.js`, `recordStore.js`, `records.js`) with tombstones, generation counters, fingerprint dedupe, and a locked read-modify-write path in `mutateMemory`; automatic v1→v2 migration (`migrate.js`, `migrateMapping.js`) with `autoMigrate` config.
+  - **Retrieval**: deny-by-default eligibility policy (`policy.js` — status/expiry/provenance/trust-tier/project-binding), generation-bound in-memory `recordIndex`, ranked hits (`memoryHit.js`, `retrieval.js`), and labeled `## Previous Context` injection that renders record text as data, never instructions.
+  - **Freshness**: `memoryFreshness.js` resolves `evidence[].locator` with `lstat`+`realpath` containment — symlinks escaping `projectRoot` report `locator-unverifiable`, never `fresh`.
+  - **Write safety**: `writeGuard.js`/`writeClassification.js` reject secret-bearing payloads before persist; `sensitiveValueScanner` shared.
+  - **Backup/restore/purge**: `storeBackup.js` byte-copy backups with sha256 manifest (mode 0600), manifest boundary check (`backup-file-out-of-boundary`), tombstone precedence on restore; CLI `memory purge/export` lanes sweep `deletePromptCacheEntries` so purged content cannot resurrect from the prompt cache.
+  - **Rollout flags (W6)**: `memoryV2.{eligibility,writer,index,decision}.stage` on the shared `off→shadow→canary→default` ladder, `canaryProjects`, and absolute `killSwitch` — read live on every operation, config-only reversal, no storage-format change. Ships at `default` for eligibility/writer/index, `off` for decision, `killSwitch: false`.
+  - **Security review (W6)**: `tests/security/memorySecurity.test.js` (11 tests) — fixed symlink-follow in `resolveLocator` and manifest path escape in `restoreBackup`; 0 open high-severity findings.
+  - **Gate G6**: canary delta clean (0 hit/query divergence on 2000-record seeded corpus), kill-switch drill pass on read and write legs — verdict **GO** (`docs/AI_HANDOFF/inventory/g6-verdict.md`).
+  - **Installed mirror**: `template_project/.claude/ukit/runtime/memory-{flags,freshness,policy}.mjs` shipped for hook-side parity.
+
+## 3.0.8 - 2026-09-24
+
+- Re-release of the 3.0.7 content: npm staged-publish left 3.0.7 in limbo (E409 "previously staged version"); re-published as 3.0.8. Tag v3.0.7 exists on the same tree.
+
 ## 3.0.7 - 2026-09-24
 
 - **Data foundation & flight recorder (cycle C54)** — new `src/core/observability/` pipeline, all behind `observability.stage` (default `off`, staged `off→shadow→canary→default` per seam with kill switch):
@@ -105,7 +122,7 @@ All notable changes to UKit are documented here.
 ## 2.7.8 - 2026-09-22
 
 Stall/hang fixes — cycle C43 (TASK-001..008): the indefinite-stall producers
-root-caused in `docs/AI_REPORT/2026-09-21-NORMAL_CHAT_STALL.md` are fixed
+root-caused in `docs/AI_REPORT/archive/2026-09-21-NORMAL_CHAT_STALL.md` are fixed
 across Claude Code, omp, and Codex runtimes.
 
 - **CX-8**: route-state writes are atomic + locked — torn `skill-router-state.json`

package/manifests/documentation.yaml

@@ -763,6 +763,17 @@ entries:
     validation: [manual]
     archive_policy: immutable
     notes: vendor evidence extracted from docs/PROMPT_CACHING.md (DOC-206, TASK-212)
+  - id: docs-decision-runtime-replay
+    path: docs/decision-runtime-replay.md
+    class: canonical
+    audience: [maintainer, user]
+    owner: runtime
+    source_of_truth: docs/decision-runtime-replay.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: C69 G7 operator doc — timeline render, support bundle contents/exclusions, replay limits
 
 # Declared complexity→docs mapping consumed by the router's `docs=` summary segment
 # (src/index/taskRouting.js CONTEXT_LAYER_DOCS mirrors this block; DOC-201 FR-001/002).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/scripts/audit/decision-coverage.mjs

@@ -200,6 +200,17 @@ function scanFiles(root, extraScan) {
       if (entry.endsWith('.js')) files.push(path.join(absDir, entry));
     }
   }
+  for (const extra of extraScan) {
+    let stat;
+    try {
+      stat = fs.statSync(extra);
+    } catch (error) {
+      return { error: `extra-scan path is not a file: ${extra} (${error.code ?? error.message})` };
+    }
+    if (!stat.isFile()) {
+      return { error: `extra-scan path is not a file: ${extra}` };
+    }
+  }
   files.push(...extraScan);
   return { files };
 }
@@ -260,7 +271,16 @@ function main() {
       console.error(`decision-coverage: scan file missing: ${path.relative(args.root, file)}`);
       process.exit(1);
     }
-    const source = fs.readFileSync(file, 'utf8');
+    let source;
+    try {
+      source = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      const rel = path.relative(args.root, file);
+      console.error(
+        `decision-coverage: cannot read ${rel}: ${error.code ?? error.message}`,
+      );
+      process.exit(1);
+    }
     discovered.push(...discoverInSource(source, path.basename(file)));
   }
 
@@ -292,4 +312,11 @@ function main() {
   );
 }
 
-main();
+try {
+  main();
+} catch (error) {
+  console.error(
+    `decision-coverage: ${error instanceof Error ? error.message : String(error)}`,
+  );
+  process.exit(1);
+}

package/scripts/bench/data-foundation.mjs

@@ -7,6 +7,8 @@
 //   --evaluate   Replay the golden corpus (tests/fixtures/observability/golden/cases.json)
 //                under both pre-registered policies and print paired scorecards +
 //                a fixed-seed variance report (TASK-014).
+//   --perturb    Inject seeded synthetic mutations into corpus summaries and measure
+//                detection through computeFingerprint/detectOpportunities (TASK-002).
 //
 // The corpus is a synthetic, seeded fixture: no real user content. Records are
 // envelope-shaped per SPEC §7 (DF-FR01) but intentionally NOT schema-validated —
@@ -521,6 +523,43 @@ async function runEvaluateBench() {
   return failed ? 1 : 0;
 }
 
+// --perturb: summarize the corpus, inject seeded synthetic mutations via
+// mutateSummaries, then measure detection through the real
+// computeFingerprint/detectOpportunities path. Exit 0 when every injected
+// mutation is detected; 1 when missed[] is non-empty or the corpus is
+// unloadable. Deterministic at SEED; evaluation is offline — no model calls.
+export async function runPerturb({ quiet = false } = {}) {
+  const { summarizeTrace } = await import('../../src/core/observability/analytics/summary.js');
+  const { mutateSummaries, detectPerturbations } = await import(
+    '../../src/core/observability/evaluation/perturbation.js'
+  );
+
+  let corpus;
+  try {
+    corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`--perturb: cannot load ${corpusPath}: ${err && err.message}\n`);
+    return { code: 1, report: null };
+  }
+
+  const baseline = corpus.traces.map((t) => summarizeTrace(t.records));
+  const { summaries: mutated, manifest } = mutateSummaries(baseline, { seed: SEED });
+  const outcome = detectPerturbations(mutated, baseline, manifest);
+
+  const report = {
+    metric_version: METRIC_VERSION,
+    bench: 'perturb',
+    seed: SEED,
+    corpus: path.relative(repoRoot, corpusPath),
+    injected: outcome.injected,
+    detected: outcome.detected,
+    missed: outcome.missed,
+    manifest,
+  };
+  if (!quiet) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  return { code: outcome.missed.length > 0 ? 1 : 0, report };
+}
+
 function main(argv) {
   const flag = argv[2];
   switch (flag) {
@@ -550,13 +589,23 @@ function main(argv) {
           return 1;
         },
       );
+    case '--perturb':
+      return runPerturb().then(
+        ({ code }) => code,
+        (err) => {
+          process.stderr.write(`--perturb failed: ${err && err.message}\n`);
+          return 1;
+        },
+      );
     default:
       process.stderr.write(
-        `usage: node scripts/bench/data-foundation.mjs --fixture|--recorder|--analytics|--evaluate\n`,
+        `usage: node scripts/bench/data-foundation.mjs --fixture|--recorder|--analytics|--evaluate|--perturb\n`,
       );
       return 2;
   }
 }
-
-Promise.resolve(main(process.argv)).then((code) => process.exit(code));
+const invokedAs = process.argv[1] ? path.resolve(process.argv[1]) : '';
+if (invokedAs === fileURLToPath(import.meta.url)) {
+  Promise.resolve(main(process.argv)).then((code) => process.exit(code));
+}
 

package/scripts/bench/decision-runtime-baseline.mjs

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+// TASK-004 — DR-01b decision-runtime baseline runner (SPEC §5 FR-006, §8, §10).
+//
+// Replays the versioned synthetic corpus (docs/AI_HANDOFF/benchmark/corpus.yaml)
+// through the TASK-003 metric module and writes a schema-valid JSON report:
+//   {version, env{sha,package,node,os,arch,fs}, runs,
+//    scenarios[{id,verdict,wallMs,wakes,eligible,quality,tokens}],
+//    summary{externalWakeRate,qualityScore,p50,p95}}
+//
+// The baseline replays deterministic inline commands only — no model/agent
+// wake is ever made — so `wakes` is measured as 0 and `tokens` is 'UNKNOWN'
+// (no provider data source exists; never 0 or an estimate, metric-spec §5).
+//
+// Exit codes: 0 = ran to completion (verdicts are data), 2 = malformed
+// corpus/args or harness crash. Per-step timeout default 30s.
+
+import { spawn, execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'yaml';
+
+import {
+  UNKNOWN,
+  computeExternalWakeRate,
+  computeQualityScore,
+  summarizeRuns,
+} from './decision-runtime-metrics.mjs';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const DEFAULT_RUNS = 9;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const ORACLE_TYPES = ['exit-code', 'output-match', 'file-exists'];
+
+const USAGE = `Usage: node scripts/bench/decision-runtime-baseline.mjs --corpus <file.yaml> --out <file.json> [options]
+
+Replays the DR-01b synthetic corpus and writes a schema-valid JSON report
+(SPEC §5 FR-006). Verdicts are data: a failing scenario does not fail the run.
+
+Options:
+  --corpus <file.yaml>   Corpus path (required)
+  --out <file.json>      Report output path (required)
+  --runs <n>             Repetitions per scenario (default ${DEFAULT_RUNS})
+  --timeout <ms>         Per-step timeout (default ${DEFAULT_TIMEOUT_MS})
+  --help                 Show this help
+
+Exit codes: 0 = completed, 2 = malformed corpus/args or crash.`;
+
+// ---------- args ----------
+
+function parseArgs(argv) {
+  const opts = { runs: DEFAULT_RUNS, timeoutMs: DEFAULT_TIMEOUT_MS };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    const takeValue = () => {
+      i += 1;
+      if (i >= argv.length) throw new Error(`Missing value for ${arg}`);
+      return argv[i];
+    };
+    if (arg === '--corpus') opts.corpus = takeValue();
+    else if (arg === '--out') opts.out = takeValue();
+    else if (arg === '--runs') opts.runs = Number(takeValue());
+    else if (arg === '--timeout') opts.timeoutMs = Number(takeValue());
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return opts;
+}
+
+// ---------- corpus loading + validation ----------
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function isNonNegativeInt(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+/** Validate a parsed corpus doc; returns problem strings (empty = valid). */
+function validateCorpus(doc) {
+  const problems = [];
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    return ['corpus is not an object'];
+  }
+  if (doc.version !== 1) problems.push('missing or invalid `version` (must be 1)');
+  const scenarios = doc.scenarios;
+  if (!Array.isArray(scenarios) || scenarios.length === 0) {
+    problems.push('`scenarios` must be a non-empty array');
+    return problems;
+  }
+  const seen = new Set();
+  scenarios.forEach((sc, idx) => {
+    const where = `scenarios[${idx}]`;
+    if (!sc || typeof sc !== 'object') {
+      problems.push(`${where}: not an object`);
+      return;
+    }
+    const label = isNonEmptyString(sc.id) ? `scenario ${sc.id}` : where;
+    if (!isNonEmptyString(sc.id)) problems.push(`${where}: missing required field \`id\``);
+    else if (seen.has(sc.id)) problems.push(`duplicate scenario id: ${sc.id}`);
+    else seen.add(sc.id);
+    if (!isNonEmptyString(sc.class)) problems.push(`${label}: missing required field \`class\``);
+    if (!isNonEmptyString(sc.description)) problems.push(`${label}: missing required field \`description\``);
+    if (!Array.isArray(sc.steps) || sc.steps.length === 0) {
+      problems.push(`${label}: \`steps\` must be a non-empty array`);
+    } else {
+      sc.steps.forEach((step, sIdx) => {
+        if (!step || typeof step !== 'object' || !isNonEmptyString(step.run)) {
+          problems.push(`${label} steps[${sIdx}]: missing required field \`run\``);
+        } else if (step.expectExit !== undefined && !Number.isInteger(step.expectExit)) {
+          problems.push(`${label} steps[${sIdx}]: \`expectExit\` must be an integer`);
+        }
+      });
+    }
+    const oracle = sc.oracle;
+    if (!oracle || typeof oracle !== 'object' || !ORACLE_TYPES.includes(oracle.type)) {
+      problems.push(`${label}: \`oracle.type\` must be one of ${ORACLE_TYPES.join('|')}`);
+    } else if (oracle.type === 'exit-code' && !Number.isInteger(oracle.expect)) {
+      problems.push(`${label}: exit-code oracle requires integer \`expect\``);
+    } else if (oracle.type === 'output-match' && !isNonEmptyString(oracle.pattern)) {
+      problems.push(`${label}: output-match oracle requires \`pattern\``);
+    } else if (oracle.type === 'file-exists' && !isNonEmptyString(oracle.path)) {
+      problems.push(`${label}: file-exists oracle requires \`path\``);
+    }
+    if (!isNonNegativeInt(sc.eligibleTransitions)) {
+      problems.push(`${label}: missing required field \`eligibleTransitions\` (non-negative integer)`);
+    }
+    if (!isNonNegativeInt(sc.expectedExternalWakes)) {
+      problems.push(`${label}: missing required field \`expectedExternalWakes\` (non-negative integer)`);
+    }
+  });
+  return problems;
+}
+
+function loadCorpus(corpusPath) {
+  if (!fs.existsSync(corpusPath)) {
+    throw new Error(`corpus not found: ${corpusPath}`);
+  }
+  let doc;
+  try {
+    doc = yaml.parse(fs.readFileSync(corpusPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`corpus YAML parse error: ${error.message}`);
+  }
+  const problems = validateCorpus(doc);
+  if (problems.length > 0) {
+    throw new Error(`malformed corpus:\n  - ${problems.join('\n  - ')}`);
+  }
+  return doc;
+}
+
+// ---------- step execution ----------
+
+const SHELL = process.platform === 'win32'
+  ? { cmd: 'cmd.exe', args: ['/d', '/s', '/c'] }
+  : { cmd: '/bin/sh', args: ['-c'] };
+
+/** Run one inline step command; captures output for output-match oracles. */
+function runStep(run, { cwd, timeoutMs }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    let timedOut = false;
+    let spawnError = null;
+    let output = '';
+    let child;
+    try {
+      // Bounded child: `timeout` arms the spawn-level deadline (SIGTERM) and
+      // the watchdog timer below escalates to SIGKILL — a wedged step can
+      // never hang the runner.
+      child = spawn(SHELL.cmd, [...SHELL.args, run], {
+        cwd,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+      });
+    } catch (error) {
+      resolve({ exitCode: -1, durationMs: Date.now() - started, timedOut: false, error: String(error?.message ?? error), output: '' });
+      return;
+    }
+    // Watchdog: escalates the spawn timeout's SIGTERM to SIGKILL so a step
+    // that ignores termination still dies at the deadline.
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.stderr.on('data', (chunk) => { output += chunk; });
+    child.on('error', (error) => { spawnError = error; });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: timedOut || code == null ? -1 : code,
+        durationMs: Date.now() - started,
+        timedOut,
+        error: spawnError ? String(spawnError.message ?? spawnError) : null,
+        output,
+      });
+    });
+  });
+}
+
+// ---------- oracle ----------
+
+function checkOracle(oracle, { lastExit, output, cwd }) {
+  switch (oracle.type) {
+    case 'exit-code':
+      return lastExit === oracle.expect;
+    case 'output-match':
+      return output.includes(oracle.pattern);
+    case 'file-exists':
+      return fs.existsSync(path.resolve(cwd, oracle.path));
+    default:
+      return false;
+  }
+}
+
+// ---------- scenario replay ----------
+
+/**
+ * Replay one scenario `runs` times. Each run executes steps in order and stops
+ * at the first step whose exit code differs from `expectExit` (default 0) or
+ * that times out — a crash mid-operation means later declared-eligible
+ * transitions are never reached (coverage gap, metric-spec §1).
+ */
+async function replayScenario(scenario, { runs, timeoutMs, workDir }) {
+  const durations = [];
+  let oraclePasses = 0;
+  let forbiddenFailures = 0;
+  let reachedTransitions = 0;
+  let stepMismatches = 0;
+  let stepTimeouts = 0;
+
+  for (let r = 0; r < runs; r += 1) {
+    const runDir = path.join(workDir, `run-${r}`);
+    fs.mkdirSync(runDir, { recursive: true });
+    const started = Date.now();
+    let lastExit = -1;
+    let output = '';
+    let stepsOk = true;
+    let reached = 0;
+
+    for (const step of scenario.steps) {
+      const expected = step.expectExit ?? 0;
+      const result = await runStep(step.run, { cwd: runDir, timeoutMs });
+      lastExit = result.exitCode;
+      output += result.output;
+      if (result.timedOut) stepTimeouts += 1;
+      if (result.exitCode !== expected || result.timedOut || result.error) {
+        stepsOk = false;
+        stepMismatches += 1;
+        break;
+      }
+      reached += 1;
+    }
+
+    durations.push(Date.now() - started);
+    reachedTransitions += Math.min(reached, scenario.eligibleTransitions);
+
+    const oraclePass = checkOracle(scenario.oracle, { lastExit, output, cwd: runDir });
+    if (oraclePass) oraclePasses += 1;
+    // Forbidden failure (metric-spec §2): every step completed as declared
+    // (exit-code success) while the oracle rejects the run — false completion.
+    if (stepsOk && !oraclePass) forbiddenFailures += 1;
+  }
+
+  const quality = computeQualityScore({
+    satisfied: oraclePasses,
+    eligible: runs,
+    forbiddenFailures,
+  });
+  const { p50, p95 } = summarizeRuns(durations);
+  const coverageGap = Math.max(0, scenario.eligibleTransitions * runs - reachedTransitions);
+
+  return {
+    entry: {
+      id: scenario.id,
+      class: scenario.class,
+      verdict: quality.verdict,
+      wallMs: { n: runs, p50, p95 },
+      wakes: 0,
+      eligible: reachedTransitions,
+      coverageGap,
+      quality: {
+        score: quality.score,
+        satisfied: oraclePasses,
+        eligible: runs,
+        forbiddenFailures,
+      },
+      tokens: UNKNOWN,
+      stepMismatches,
+      stepTimeouts,
+    },
+    durations,
+  };
+}
+
+// ---------- env ----------
+
+function detectFsType(dir) {
+  try {
+    if (typeof fs.statfsSync === 'function') {
+      const stats = fs.statfsSync(dir);
+      if (stats && typeof stats.type === 'number') {
+        return `0x${stats.type.toString(16)}`;
+      }
+    }
+  } catch { /* fall through */ }
+  return 'local';
+}
+
+function collectEnv() {
+  const env = {
+    sha: 'unknown',
+    package: 'unknown',
+    node: process.version,
+    os: process.platform,
+    arch: process.arch,
+    fs: detectFsType(REPO_ROOT),
+  };
+  try {
+    env.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8', timeout: 10_000 }).trim();
+  } catch { /* leave 'unknown' */ }
+  try {
+    env.package = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version ?? 'unknown';
+  } catch { /* leave 'unknown' */ }
+  return env;
+}
+
+// ---------- main ----------
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[decision-runtime-baseline] ${error.message}\n\n${USAGE}`);
+    process.exit(2);
+  }
+  if (opts.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!opts.corpus || !opts.out) {
+    console.error(`[decision-runtime-baseline] --corpus and --out are required.\n\n${USAGE}`);
+    process.exit(2);
+  }
+  if (!Number.isInteger(opts.runs) || opts.runs < 1) {
+    console.error('[decision-runtime-baseline] --runs must be a positive integer.');
+    process.exit(2);
+  }
+  if (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs < 1) {
+    console.error('[decision-runtime-baseline] --timeout must be a positive number of ms.');
+    process.exit(2);
+  }
+
+  let corpus;
+  try {
+    corpus = loadCorpus(path.resolve(opts.corpus));
+  } catch (error) {
+    console.error(`[decision-runtime-baseline] ${error.message}`);
+    process.exit(2);
+  }
+
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-dr-baseline-'));
+  const scenarios = [];
+  const allDurations = [];
+  for (const scenario of corpus.scenarios) {
+    const workDir = path.join(tmpRoot, scenario.id);
+    fs.mkdirSync(workDir, { recursive: true });
+    const { entry, durations } = await replayScenario(scenario, {
+      runs: opts.runs,
+      timeoutMs: opts.timeoutMs,
+      workDir,
+    });
+    scenarios.push(entry);
+    allDurations.push(...durations);
+  }
+
+  const totals = scenarios.reduce((acc, sc) => ({
+    wakes: acc.wakes + sc.wakes,
+    eligible: acc.eligible + sc.eligible,
+    satisfied: acc.satisfied + sc.quality.satisfied,
+    qualityEligible: acc.qualityEligible + sc.quality.eligible,
+    forbiddenFailures: acc.forbiddenFailures + sc.quality.forbiddenFailures,
+  }), { wakes: 0, eligible: 0, satisfied: 0, qualityEligible: 0, forbiddenFailures: 0 });
+
+  const wallSummary = summarizeRuns(allDurations);
+  const summaryQuality = computeQualityScore({
+    satisfied: totals.satisfied,
+    eligible: totals.qualityEligible,
+    forbiddenFailures: totals.forbiddenFailures,
+  });
+
+  const report = {
+    version: 1,
+    env: collectEnv(),
+    corpus: { path: path.resolve(opts.corpus), version: corpus.version, scenarios: corpus.scenarios.length },
+    runs: opts.runs,
+    scenarios,
+    summary: {
+      externalWakeRate: computeExternalWakeRate({
+        externalWakes: totals.wakes,
+        eligibleTransitions: totals.eligible,
+      }),
+      qualityScore: summaryQuality.score,
+      qualityVerdict: summaryQuality.verdict,
+      p50: wallSummary.p50,
+      p95: wallSummary.p95,
+    },
+  };
+
+  const outPath = path.resolve(opts.out);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`);
+
+  console.log(`[decision-runtime-baseline] report written: ${outPath}`);
+  console.log(`[decision-runtime-baseline] scenarios=${scenarios.length} runs=${opts.runs} `
+    + `externalWakeRate=${report.summary.externalWakeRate} quality=${report.summary.qualityScore}`);
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error(`[decision-runtime-baseline] harness crash: ${error?.stack ?? error}`);
+  process.exit(2);
+});

package/scripts/bench/decision-runtime-metrics.mjs

@@ -0,0 +1,67 @@
+// TASK-003 — DR-01a metric computation module (SPEC §5 FR-004, §8, §10).
+//
+// Pure ESM, `node:` builtins only (in fact no imports at all). The baseline
+// runner (TASK-004) and every later gate import these functions so all metric
+// math is computed by exactly one implementation — see
+// docs/AI_HANDOFF/benchmark/metric-spec.md for the pre-registered definitions.
+//
+// UNKNOWN semantics: the literal string 'UNKNOWN' is returned wherever the
+// denominator or source data is absent/invalid. It is never 0, NaN, Infinity,
+// or an estimate — a string cannot silently coerce into numeric aggregates.
+
+export const UNKNOWN = 'UNKNOWN';
+
+function isValidCount(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * external_wake_rate = external_reasoning_continuations / eligible_known_transitions.
+ *
+ * @param {{externalWakes: number, eligibleTransitions: number}} input
+ * @returns {number|'UNKNOWN'} ratio in [0,1], or 'UNKNOWN' when the denominator
+ *   is <= 0 or either input is not a finite non-negative number.
+ */
+export function computeExternalWakeRate({ externalWakes, eligibleTransitions } = {}) {
+  if (!isValidCount(externalWakes) || !isValidCount(eligibleTransitions)) return UNKNOWN;
+  if (eligibleTransitions <= 0) return UNKNOWN;
+  // wakes > eligible means instrumentation error upstream; clamp to keep the
+  // contract range [0,1] rather than emitting an impossible rate.
+  return Math.min(1, externalWakes / eligibleTransitions);
+}
+
+/**
+ * Quality score = satisfied / eligible requirements; verdict is 'fail' when any
+ * forbidden failure occurred (false completion, fabricated support, estimated
+ * metric) regardless of score, and fail-closed when the score is UNKNOWN.
+ *
+ * @param {{satisfied: number, eligible: number, forbiddenFailures: number}} input
+ * @returns {{score: number|'UNKNOWN', verdict: 'pass'|'fail'}}
+ */
+export function computeQualityScore({ satisfied, eligible, forbiddenFailures } = {}) {
+  const forbidden = isValidCount(forbiddenFailures) ? forbiddenFailures : 0;
+  const verdict = forbidden > 0 ? 'fail' : 'pass';
+  if (!isValidCount(satisfied) || !isValidCount(eligible) || eligible <= 0) {
+    // Fail-closed: an unmeasurable quality score never passes.
+    return { score: UNKNOWN, verdict: 'fail' };
+  }
+  return { score: Math.min(1, satisfied / eligible), verdict };
+}
+
+/**
+ * Nearest-rank percentiles over run durations (same convention as
+ * scripts/bench/memory-baseline.mjs). Non-finite or negative entries are
+ * dropped; `n` counts valid durations only.
+ *
+ * @param {number[]} durations
+ * @returns {{n: number, p50: number|'UNKNOWN', p95: number|'UNKNOWN'}}
+ */
+export function summarizeRuns(durations) {
+  const valid = Array.isArray(durations)
+    ? durations.filter((d) => typeof d === 'number' && Number.isFinite(d) && d >= 0)
+    : [];
+  if (valid.length === 0) return { n: 0, p50: UNKNOWN, p95: UNKNOWN };
+  const sorted = [...valid].sort((a, b) => a - b);
+  const rank = (q) => sorted[Math.max(1, Math.ceil((q / 100) * sorted.length)) - 1];
+  return { n: sorted.length, p50: rank(50), p95: rank(95) };
+}