@ngockhoale/ukit 3.0.6 → 3.0.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 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):
+  - **Schema + privacy**: versioned record envelope (`schema_version: 1`), semantic/reason-code registry, and a two-gate privacy boundary — `sanitizeObserved` before any persistent write (allowlist + deny-list + redaction), `sanitizeForSupport` as an independent default-deny second gate.
+  - **Recorder + segments**: bounded non-blocking `emit()` with live stage gate, span tracking, deadline-bounded flush, and append-only JSONL segments with rotation/retention and partial-tail recovery.
+  - **Analytics**: deterministic trace summaries (p50/p95/p99, causal critical path, retry/drop/cache metrics), honest `telemetry_complete=false` on drops/gaps/UNKNOWN host usage, and rebuild-from-segments recovery.
+  - **Support view**: `UKit Support` materialized projection under the OS-native Documents folder — bundle-local pseudonyms, atomic writes, byte caps, failure-promoted digests, and a validated import path (manifest/checksums/traversal/decompression bounds).
+  - **Evaluation**: offline evaluator packet (summary → anomalies → digest → evidence) and an optimization knowledge base recording hypothesis → experiment → guardrails → decision → rollback.
+  - **Rollout**: `resolveSeamStages`/`resolveSeamConfig`/`killSwitch` in `src/core/observability/rollout.js` — recorder activates at `shadow`, support projection at `canary`, evaluation at `default`; per-seam overrides are restrictive-only so a global `off` is an absolute kill.
+  - **Privacy fix**: `error_detail` added to the deny-list (free-form text, not a code) and `REDACTION_VERSION` bumped to `df-redact-3` — fixture secrets can no longer persist in canonical segments.
+  - **unic-decision docs**: `docs/pstack/UNIC_DECISION_GUIDE.md` documents the local Lava/JEV decision model (not an LLM), checkpoint IDs, typed `tool_calls` contract, and `modelRoles.decision` binding for omp.
+
 ## 3.0.6 - 2026-09-24
 
 - Clarified the project owner's `unic-decision` contract in owner instructions, project memory, the technical spec, and shipped internals: a local Lava/JEV model in UNIC Provider, not an LLM; the OpenAI-compatible API is transport for convenient integration, not evidence of remote hosting or generative-model pricing.

package/package.json

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

package/scripts/bench/data-foundation.mjs

@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+// data-foundation bench harness (C54 / DF-00)
+//
+//   --fixture    Regenerate tests/fixtures/observability/corpus.json deterministically (seed=42).
+//   --recorder   Emit the corpus through createRecorder into a temp segment store.
+//   --analytics  Rebuild the derived index from retained segments and print summaries.
+//   --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).
+//
+// 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 —
+// TASK-003 owns validation. Unknown host measurements are marked UNKNOWN, never 0.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SEMANTIC_REGISTRY } from '../../src/core/observability/schema/registry.js';
+import { PRIVACY_CLASSES } from '../../src/core/observability/schema/constants.js';
+
+const SEED = 42;
+const METRIC_VERSION = 'df-m1';
+const SCHEMA_VERSION = 1;
+const BOOT_ID = 'boot-fixture-0001';
+const WRITER_ID = 'writer-fixture-0001';
+const SESSION_ID = 'session-fixture-0001';
+const PROJECT_REF = 'project-fixture-0001';
+const WALL_EPOCH_MS = Date.UTC(2026, 0, 1, 0, 0, 0); // fixed epoch → deterministic wall_time_utc
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const corpusPath = path.join(repoRoot, 'tests/fixtures/observability/corpus.json');
+
+// Records may raise privacy above the registry floor but never lower it —
+// validateSemanticRecord (TASK-003) rejects below-floor classes, so the
+// fixture clamps each record's declared class up to the registry floor.
+function clampToRegistryFloor(semanticName, privacyClass) {
+  const floor = SEMANTIC_REGISTRY[semanticName]?.privacy_class;
+  if (!floor) return privacyClass;
+  return PRIVACY_CLASSES.indexOf(privacyClass) < PRIVACY_CLASSES.indexOf(floor) ? floor : privacyClass;
+}
+
+// Deterministic PRNG (mulberry32) — used only for token counts; IDs are counters.
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function next() {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function makeCtx() {
+  const rand = mulberry32(SEED);
+  let seq = 0;
+  let rec = 0;
+  let span = 0;
+  let trace = 0;
+  let clockMs = 0;
+  return {
+    nextSeq: () => ++seq,
+    recordId: () => `rec-${String(++rec).padStart(4, '0')}`,
+    spanId: () => `span-${String(++span).padStart(4, '0')}`,
+    traceId: () => `trace-${String(++trace).padStart(4, '0')}`,
+    // advance the deterministic clock by `ms` and return { wall_time_utc, monotonic_ns }
+    tick: (ms) => {
+      clockMs += ms;
+      return {
+        wall_time_utc: new Date(WALL_EPOCH_MS + clockMs).toISOString(),
+        monotonic_ns: clockMs * 1e6,
+      };
+      },
+    tokens: (lo, hi) => lo + Math.floor(rand() * (hi - lo + 1)),
+  };
+}
+
+function record(ctx, { semanticName, traceId, spanId, parentSpanId, executionId, importance, privacyClass, payload, dtMs }) {
+  const t = ctx.tick(dtMs);
+  return {
+    record_type: 'fact',
+    semantic_name: semanticName,
+    schema_version: SCHEMA_VERSION,
+    record_id: ctx.recordId(),
+    trace_id: traceId,
+    span_id: spanId,
+    parent_span_id: parentSpanId,
+    execution_id: executionId,
+    session_id: SESSION_ID,
+    project_ref: PROJECT_REF,
+    boot_id: BOOT_ID,
+    writer_id: WRITER_ID,
+    sequence: ctx.nextSeq(),
+    wall_time_utc: t.wall_time_utc,
+    monotonic_ns: t.monotonic_ns,
+    importance,
+    privacy_class: clampToRegistryFloor(semanticName, privacyClass),
+    payload,
+  };
+}
+
+function execSpan(ctx, traceId, executionId, privacyClass) {
+  const spanId = ctx.spanId();
+  return {
+    spanId,
+    started: record(ctx, {
+      semanticName: 'execution.started',
+      traceId,
+      spanId,
+      parentSpanId: null,
+      executionId,
+      importance: 'normal',
+      privacyClass,
+      payload: { operation: 'task', duration_ms: null },
+      dtMs: 10,
+    }),
+  };
+}
+
+function modelAttempt(ctx, { traceId, parentSpanId, executionId, attemptIndex, status, resource, privacyClass, extra = {} }) {
+  const spanId = ctx.spanId();
+  const started = record(ctx, {
+    semanticName: 'model.started',
+    traceId,
+    spanId,
+    parentSpanId,
+    executionId,
+    importance: 'normal',
+    privacyClass,
+    payload: { attempt_index: attemptIndex, ...extra },
+    dtMs: 5,
+  });
+  const completed = record(ctx, {
+    semanticName: status === 'ok' ? 'model.completed' : 'model.failed',
+    traceId,
+    spanId,
+    parentSpanId,
+    executionId,
+    importance: 'normal',
+    privacyClass,
+    payload: {
+      attempt_index: attemptIndex,
+      duration_ms: 120 + attemptIndex * 30,
+      resource,
+      ...(status === 'ok' ? {} : { error_code: extra.error_code || 'MODEL_ERROR' }),
+      ...extra,
+    },
+    dtMs: 120 + attemptIndex * 30,
+  });
+  return [started, completed];
+}
+
+function execEnd(ctx, { traceId, spanId, executionId, status, privacyClass, extra = {} }) {
+  return record(ctx, {
+    semanticName: `execution.${status}`,
+    traceId,
+    spanId,
+    parentSpanId: null,
+    executionId,
+    importance: 'normal',
+    privacyClass,
+    payload: { duration_ms: 0, ...extra },
+    dtMs: 10,
+  });
+}
+
+function sumUsage(attempts) {
+  const values = attempts
+    .map((r) => r.payload.resource)
+    .filter((res) => res && typeof res.value === 'number')
+    .map((res) => res.value);
+  return values.length ? values.reduce((a, b) => a + b, 0) : null;
+}
+
+function buildTrace(ctx, { scenario, privacyClass, build }) {
+  const traceId = ctx.traceId();
+  const executionId = `exec-${traceId}`;
+  const exec = execSpan(ctx, traceId, executionId, privacyClass);
+  const { records, attempts, succeeded } = build({ traceId, executionId, execSpanId: exec.spanId });
+  const all = [exec.started, ...records];
+  return {
+    trace_id: traceId,
+    scenario,
+    privacy_class: privacyClass,
+    records: all,
+    metrics: {
+      metric_version: METRIC_VERSION,
+      tokens_to_success: succeeded ? sumUsage(attempts) : null,
+      correction_observed: scenario === 'retry',
+    },
+  };
+}
+
+function buildCorpus() {
+  const ctx = makeCtx();
+  const traces = [];
+
+  // success: single attempt, provider-reported usage.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'success',
+      privacyClass: 'public',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const resource = { value: ctx.tokens(800, 1200), source: 'PROVIDER' };
+        const attempts = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 1, status: 'ok', resource, privacyClass: 'public',
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, status: 'completed',
+          privacyClass: 'public', extra: { outcome: 'success' },
+        });
+        return { records: [...attempts, end], attempts, succeeded: true };
+      },
+    }),
+  );
+
+  // retry: user correction observed → second attempt; tokens_to_success sums both.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'retry',
+      privacyClass: 'public',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const res1 = { value: ctx.tokens(400, 700), source: 'PROVIDER' };
+        const res2 = { value: ctx.tokens(500, 900), source: 'PROVIDER' };
+        const a1 = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 1, status: 'ok', resource: res1, privacyClass: 'public',
+        });
+        const correction = record(ctx, {
+          semanticName: 'context.item.injected',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          importance: 'high', privacyClass: 'public',
+          payload: { kind: 'user_correction', correction_observed: true },
+          dtMs: 15,
+        });
+        const a2 = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 2, status: 'ok', resource: res2, privacyClass: 'public',
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, status: 'completed',
+          privacyClass: 'public', extra: { outcome: 'success', attempts: 2 },
+        });
+        return { records: [...a1, correction, ...a2, end], attempts: [...a1, ...a2], succeeded: true };
+      },
+    }),
+  );
+
+  // failure: host-blind — usage UNKNOWN (never 0), execution failed.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'failure',
+      privacyClass: 'public',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const resource = { value: null, source: 'UNKNOWN' };
+        const attempts = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 1, status: 'error', resource, privacyClass: 'public',
+          extra: { error_code: 'TOOL_TIMEOUT' },
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, status: 'failed',
+          privacyClass: 'public', extra: { outcome: 'failure', error_code: 'TOOL_TIMEOUT' },
+        });
+        return { records: [...attempts, end], attempts, succeeded: false };
+      },
+    }),
+  );
+
+  // dropped: queue overflow — telemetry.dropped counted, telemetry_complete=false.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'dropped',
+      privacyClass: 'public',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const resource = { value: ctx.tokens(300, 600), source: 'PROVIDER' };
+        const attempts = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 1, status: 'ok', resource, privacyClass: 'public',
+        });
+        const dropped = record(ctx, {
+          semanticName: 'telemetry.dropped',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          importance: 'high', privacyClass: 'public',
+          payload: { reason_code: 'QUEUE_OVERFLOW', dropped_count: 3, telemetry_complete: false },
+          dtMs: 5,
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, status: 'completed',
+          privacyClass: 'public', extra: { outcome: 'success', telemetry_complete: false },
+        });
+        return { records: [...attempts, dropped, end], attempts, succeeded: true };
+      },
+    }),
+  );
+
+  // secret: payload carries a synthetic fixture secret (never a real credential);
+  // host-blind usage → UNKNOWN. TASK-004 leak tests scan for the marker string.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'secret',
+      privacyClass: 'sensitive',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const resource = { value: null, source: 'UNKNOWN' };
+        const attempts = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 1, status: 'error', resource, privacyClass: 'sensitive',
+          extra: {
+            error_code: 'AUTH_FAILED',
+            error_detail: 'credential rejected: FIXTURE_SECRET_DO_NOT_LEAK_7f3a9c',
+          },
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, status: 'failed',
+          privacyClass: 'sensitive', extra: { outcome: 'failure', error_code: 'AUTH_FAILED' },
+        });
+        return { records: [...attempts, end], attempts, succeeded: false };
+      },
+    }),
+  );
+
+  return {
+    metric_version: METRIC_VERSION,
+    seed: SEED,
+    generated_by: 'scripts/bench/data-foundation.mjs --fixture',
+    metric_definitions: {
+      tokens_to_success: {
+        metric_version: METRIC_VERSION,
+        unit: 'tokens',
+        definition:
+          'Sum of numeric resource.value across all model attempts in the episode; null when no attempt reported a numeric value or the episode did not succeed.',
+      },
+      correction_observed: {
+        metric_version: METRIC_VERSION,
+        unit: 'boolean',
+        definition:
+          'True when a user correction was injected mid-episode and the episode required ≥2 model attempts.',
+      },
+    },
+    traces,
+  };
+}
+
+function writeFixture() {
+  const corpus = buildCorpus();
+  fs.mkdirSync(path.dirname(corpusPath), { recursive: true });
+  fs.writeFileSync(corpusPath, `${JSON.stringify(corpus, null, 2)}\n`);
+  process.stdout.write(`wrote ${path.relative(repoRoot, corpusPath)} (seed=${SEED}, traces=${corpus.traces.length})\n`);
+  return 0;
+}
+
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, idx)];
+}
+
+// --recorder: emit the whole corpus through createRecorder into a temp
+// segment root, measure per-emit latency distribution + flush outcome, then
+// read the store back to prove the round-trip. Exit 0 on success, 1 when the
+// pipeline loses or corrupts records.
+async function runRecorderBench() {
+  const { createRecorder } = await import('../../src/core/observability/emit/recorder.js');
+  const { readSegments } = await import('../../src/core/observability/segments/readSegments.js');
+
+  const corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  const inputs = corpus.traces.flatMap((t) => t.records);
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-bench-rec-'));
+  try {
+    const recorder = createRecorder({
+      root,
+      config: { observability: { stage: 'default' } },
+    });
+
+    const latenciesMs = [];
+    let accepted = 0;
+    let dropped = 0;
+    for (const record of inputs) {
+      const t0 = process.hrtime.bigint();
+      const r = recorder.emit(record);
+      latenciesMs.push(Number(process.hrtime.bigint() - t0) / 1e6);
+      if (r.status === 'accepted') accepted += 1;
+      else dropped += 1;
+    }
+
+    const flushStart = process.hrtime.bigint();
+    const flush = await recorder.flush({ deadlineMs: 60_000 });
+    const flushMs = Number(process.hrtime.bigint() - flushStart) / 1e6;
+
+    let readBack = 0;
+    const it = readSegments(root);
+    for await (const _record of it) readBack += 1;
+
+    latenciesMs.sort((a, b) => a - b);
+    const summary = {
+      metric_version: METRIC_VERSION,
+      bench: 'recorder',
+      records: inputs.length,
+      accepted,
+      dropped,
+      written: flush.written,
+      read_back: readBack,
+      flush_status: flush.status,
+      flush_ms: Number(flushMs.toFixed(3)),
+      emit_latency_ms: {
+        p50: Number(percentile(latenciesMs, 50).toFixed(4)),
+        p95: Number(percentile(latenciesMs, 95).toFixed(4)),
+        p99: Number(percentile(latenciesMs, 99).toFixed(4)),
+        max: Number((latenciesMs[latenciesMs.length - 1] || 0).toFixed(4)),
+      },
+      health: recorder.health(),
+    };
+    process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+    const okRun = flush.status === 'ok' && readBack === accepted && dropped === 0;
+    return okRun ? 0 : 1;
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// --analytics: emit the corpus through createRecorder into a temp segment
+// root, rebuild the derived index from retained facts, and print the
+// per-trace summaries + coverage denominators. Exit 0 when the rebuild is
+// complete and equivalent to direct summarization of the corpus records.
+async function runAnalyticsBench() {
+  const { createRecorder } = await import('../../src/core/observability/emit/recorder.js');
+  const { rebuildIndex } = await import('../../src/core/observability/analytics/rebuild.js');
+  const { summarizeTrace } = await import('../../src/core/observability/analytics/summary.js');
+
+  const corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  const inputs = corpus.traces.flatMap((t) => t.records);
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-bench-analytics-'));
+  try {
+    const recorder = createRecorder({
+      root,
+      config: { observability: { stage: 'default' } },
+    });
+    for (const record of inputs) recorder.emit(record);
+    const flush = await recorder.flush({ deadlineMs: 60_000 });
+
+    const started = process.hrtime.bigint();
+    const index = await rebuildIndex(root);
+    const rebuildMs = Number(process.hrtime.bigint() - started) / 1e6;
+
+    // Equivalence: rebuild-from-retained-facts must reproduce the same
+    // summaries as direct analysis of the corpus records (sanitization only
+    // rewrites sensitive free-text, never metric fields).
+    const direct = corpus.traces
+      .map((t) => summarizeTrace(t.records))
+      .sort((a, b) => a.trace_id.localeCompare(b.trace_id));
+    const equivalent = JSON.stringify(index.summaries) === JSON.stringify(direct);
+
+    const report = {
+      metric_version: METRIC_VERSION,
+      bench: 'analytics',
+      records: inputs.length,
+      flush_status: flush.status,
+      rebuild_ms: Number(rebuildMs.toFixed(3)),
+      equivalent_to_direct: equivalent,
+      coverage: index.coverage,
+      summaries: index.summaries,
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    const okRun = flush.status === 'ok' && index.ok && equivalent
+      && index.summaries.length === corpus.traces.length;
+    return okRun ? 0 : 1;
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// --evaluate: replay the golden case set under every pre-registered policy,
+// print each Scorecard plus the paired comparison (fixed-seed bootstrap
+// variance). Exit 0 when no cohort verdict is 'fail'; 1 on fail verdict or
+// an unloadable corpus. Evaluation is offline — no model calls, no writes.
+async function runEvaluateBench() {
+  const { evaluateVariant, compareScorecards } = await import(
+    '../../src/core/observability/evaluation/scorecard.js'
+  );
+
+  const goldenPath = path.join(repoRoot, 'tests/fixtures/observability/golden/cases.json');
+  let corpus;
+  try {
+    corpus = JSON.parse(fs.readFileSync(goldenPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`--evaluate: cannot load ${goldenPath}: ${err && err.message}\n`);
+    return 1;
+  }
+
+  const policies = Object.keys(
+    (corpus.pre_registered && corpus.pre_registered.policies) || {},
+  ).sort();
+  if (policies.length === 0) {
+    process.stderr.write('--evaluate: corpus declares no pre_registered.policies\n');
+    return 1;
+  }
+
+  const scorecards = {};
+  for (const policyId of policies) {
+    scorecards[policyId] = evaluateVariant(corpus, policyId);
+  }
+  const comparison = policies.length >= 2
+    ? compareScorecards(scorecards[policies[0]], scorecards[policies[1]], { seed: SEED })
+    : null;
+
+  const report = {
+    metric_version: METRIC_VERSION,
+    bench: 'evaluate',
+    seed: SEED,
+    corpus: path.relative(repoRoot, goldenPath),
+    policies,
+    scorecards,
+    comparison,
+  };
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  const failed = Object.values(scorecards).some((sc) => sc.verdict === 'fail');
+  return failed ? 1 : 0;
+}
+
+function main(argv) {
+  const flag = argv[2];
+  switch (flag) {
+    case '--fixture':
+      return writeFixture();
+    case '--recorder':
+      return runRecorderBench().then(
+        (code) => code,
+        (err) => {
+          process.stderr.write(`--recorder failed: ${err && err.message}\n`);
+          return 1;
+        },
+      );
+    case '--analytics':
+      return runAnalyticsBench().then(
+        (code) => code,
+        (err) => {
+          process.stderr.write(`--analytics failed: ${err && err.message}\n`);
+          return 1;
+        },
+      );
+    case '--evaluate':
+      return runEvaluateBench().then(
+        (code) => code,
+        (err) => {
+          process.stderr.write(`--evaluate failed: ${err && err.message}\n`);
+          return 1;
+        },
+      );
+    default:
+      process.stderr.write(
+        `usage: node scripts/bench/data-foundation.mjs --fixture|--recorder|--analytics|--evaluate\n`,
+      );
+      return 2;
+  }
+}
+
+Promise.resolve(main(process.argv)).then((code) => process.exit(code));
+

package/src/core/observability/adapters/common.js

@@ -0,0 +1,75 @@
+// common.js (TASK-010, SPEC §5 DF-FR07/DF-FR08) — shared internals for the
+// provenance adapters. Adapters are read-only importers: they join safe
+// metadata from existing owners (route audit, exec-ledger, decision
+// receipts, context items) into semantic records. Every emitted record
+// passes validateSemanticRecord + sanitizeObserved before returning — a
+// record that fails either gate is dropped, never emitted dirty.
+
+import crypto from 'node:crypto';
+
+import { SCHEMA_VERSION } from '../schema/constants.js';
+import { SEMANTIC_REGISTRY } from '../schema/registry.js';
+import { validateSemanticRecord } from '../schema/validate.js';
+import { sanitizeObserved } from '../privacy/sanitizeObserved.js';
+
+export function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function asString(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+export function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === 'string' && v.length > 0).slice(0, 32);
+}
+
+export function asIsoTime(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d.toISOString();
+  }
+  if (typeof value === 'string' && !Number.isNaN(Date.parse(value))) return value;
+  return null;
+}
+
+/**
+ * Per-adapt-call identity state. boot_id/writer_id/sequence give emitted
+ * records a stable, total-ordered provenance within one adaptation run;
+ * callers may inject fixed ids for deterministic tests/corpora.
+ */
+export function createAdapterContext({ writerId, bootId, clock } = {}) {
+  return {
+    boot_id: asString(bootId) ?? `boot-${crypto.randomUUID()}`,
+    writer_id: asString(writerId) ?? `adapter-${crypto.randomUUID()}`,
+    sequence: 0,
+    now: typeof clock === 'function' ? clock : () => new Date().toISOString(),
+  };
+}
+
+/**
+ * Fill the envelope, validate, sanitize. Returns the sanitized record or
+ * null — adapters emit only records that survive the canonical gate.
+ */
+export function emitRecord(ctx, record) {
+  const out = { ...record };
+  if (out.record_type === undefined || out.record_type === null) out.record_type = 'fact';
+  if (out.schema_version === undefined || out.schema_version === null) {
+    out.schema_version = SCHEMA_VERSION;
+  }
+  if (!asString(out.record_id)) out.record_id = `rec-${crypto.randomUUID()}`;
+  out.boot_id = ctx.boot_id;
+  out.writer_id = ctx.writer_id;
+  out.sequence = ++ctx.sequence;
+  if (!asIsoTime(out.wall_time_utc)) out.wall_time_utc = ctx.now();
+  if (typeof out.importance !== 'string') out.importance = 'normal';
+  if (typeof out.privacy_class !== 'string') {
+    const entry = SEMANTIC_REGISTRY[out.semantic_name];
+    out.privacy_class = entry ? entry.privacy_class : 'internal';
+  }
+  const validation = validateSemanticRecord(out);
+  if (!validation.ok) return null;
+  const clean = sanitizeObserved(out);
+  return clean.ok ? clean.record : null;
+}