@ngockhoale/ukit 3.0.8 → 3.0.10

package/src/core/agentRuntime/evaluation.js

@@ -0,0 +1,163 @@
+// src/core/agentRuntime/evaluation.js
+// G6 paired A/B evaluation gate (SPEC §2 G6-FR04/06, §4 GateComparison, §5).
+//
+// computeGateComparison({baseline, variant, scoreFloor?}) → GateComparison:
+//   { forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta,
+//     verdict, comparable, envMismatch, reasons }  (frozen)
+//
+// Verdict naming is spec-frozen (SPEC §4) and intentionally inverted relative
+// to intuition: 'non-inferior' means the variant FAILED the pre-registered
+// non-inferiority contract — i.e. it is *not* non-inferior. Verdict order
+// implements SPEC §5 exactly:
+//   1. forbiddenFailures > 0 in any compared run  → 'non-inferior' (hard gate)
+//   2. quality score UNKNOWN / env mismatch / smoke sample → 'unknown'
+//      (never waived, never coerced into a number)
+//   3. variant.score < baseline.score - scoreFloor → 'non-inferior'
+//   4. variant p95 > baseline p95                 → 'non-inferior' (wall target)
+//   5. otherwise                                  → 'pass'
+// p50 is reported, never gated (SPEC §5).
+//
+// Pure module: no I/O, no config reads. Malformed/absent report inputs throw
+// a typed EvaluationError — a fabricated 'pass' is impossible by construction.
+
+import { UNKNOWN } from '../../../scripts/bench/decision-runtime-metrics.mjs';
+
+// Pre-registered non-inferiority score floor (metric-spec §6, SPEC §5).
+// Frozen before any variant existed; callers may narrow it, never widen it.
+export const QUALITY_SCORE_FLOOR = 0.05;
+
+// Sample that makes a comparison valid (metric-spec §3): 9 runs per scenario.
+// Below this the run is a smoke/dev loop and is non-comparable.
+export const COMPARABLE_RUNS = 9;
+
+const ENV_FIELDS = Object.freeze(['sha', 'package', 'node', 'os', 'arch', 'fs']);
+
+export class EvaluationError extends Error {
+  constructor(message, code = 'evaluation_error') {
+    super(message);
+    this.name = 'EvaluationError';
+    this.code = code;
+  }
+}
+
+function isObj(v) {
+  return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isNumber(v) {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+function isCount(v) {
+  return isNumber(v) && v >= 0;
+}
+
+/** Require an FR-006-shaped report; throw EvaluationError otherwise. */
+function requireReport(report, label) {
+  if (!isObj(report)) {
+    throw new EvaluationError(`${label} report missing or not an object`, 'report_malformed');
+  }
+  if (!isObj(report.summary)) {
+    throw new EvaluationError(`${label} report missing summary`, 'report_malformed');
+  }
+  return report;
+}
+
+function compareEnv(baselineEnv, variantEnv) {
+  const mismatched = [];
+  for (const field of ENV_FIELDS) {
+    const a = baselineEnv?.[field];
+    const b = variantEnv?.[field];
+    if (a == null || b == null) continue; // absent field: recorded elsewhere, not compared
+    if (a !== b) mismatched.push(field);
+  }
+  return mismatched;
+}
+
+function delta(variantValue, baselineValue) {
+  if (!isNumber(variantValue) || !isNumber(baselineValue)) return UNKNOWN;
+  // Round to 1e-6 so reports carry exact deltas, not float residue.
+  return Math.round((variantValue - baselineValue) * 1e6) / 1e6;
+}
+
+/**
+ * Compute the pre-registered G6 GateComparison between a baseline report and
+ * a variant report (both FR-006 shape with `summary.forbiddenFailures`).
+ *
+ * @param {{baseline: object, variant: object, scoreFloor?: number}} input
+ * @returns {object} frozen GateComparison
+ */
+export function computeGateComparison(input = {}) {
+  if (!isObj(input)) {
+    throw new EvaluationError('comparison input missing or not an object', 'input_malformed');
+  }
+  const { baseline, variant } = input;
+  const scoreFloor = isNumber(input.scoreFloor) && input.scoreFloor >= 0
+    ? input.scoreFloor
+    : QUALITY_SCORE_FLOOR;
+
+  const b = requireReport(baseline, 'baseline');
+  const v = requireReport(variant, 'variant');
+
+  const bs = b.summary;
+  const vs = v.summary;
+  const reasons = [];
+
+  const forbiddenFailures = isCount(vs.forbiddenFailures) ? vs.forbiddenFailures : 0;
+  const qualityDelta = delta(vs.qualityScore, bs.qualityScore);
+  const wallP50Delta = delta(vs.p50, bs.p50);
+  const wallP95Delta = delta(vs.p95, bs.p95);
+
+  // Comparability is recorded separately from the verdict: a smoke run or an
+  // environment drift yields valid deltas that must never promote a stage.
+  const envMismatch = compareEnv(b.env, v.env);
+  let comparable = true;
+  if (envMismatch.length > 0) {
+    comparable = false;
+    reasons.push(`env:${envMismatch.join(',')}`);
+  }
+  const baselineRuns = isCount(b.runs) ? b.runs : 0;
+  const variantRuns = isCount(v.runs) ? v.runs : 0;
+  if (baselineRuns < COMPARABLE_RUNS || variantRuns < COMPARABLE_RUNS) {
+    comparable = false;
+    reasons.push('sample:smoke');
+  }
+
+  // 1. Hard gate: any forbidden failure → non-inferior, no margin applies.
+  if (forbiddenFailures > 0) {
+    reasons.push('gate:forbidden-failure');
+    return freezeResult({ forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta, verdict: 'non-inferior', comparable, envMismatch, reasons });
+  }
+
+  // 2. UNKNOWN quality on either side cannot establish non-inferiority —
+  //    never waived (metric-spec §6); non-comparable env/sample → unknown.
+  if (qualityDelta === UNKNOWN || !comparable) {
+    if (qualityDelta === UNKNOWN) reasons.push('gate:quality-unknown');
+    return freezeResult({ forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta, verdict: 'unknown', comparable, envMismatch, reasons });
+  }
+
+  // 3. Soft quality floor: variant must stay within scoreFloor of baseline.
+  if (vs.qualityScore < bs.qualityScore - scoreFloor - Number.EPSILON) {
+    reasons.push('gate:score-floor');
+    return freezeResult({ forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta, verdict: 'non-inferior', comparable, envMismatch, reasons });
+  }
+
+  // 4. Wall/resource target: variant p95 ≤ baseline p95. An UNKNOWN wall
+  //    target cannot establish a pass → unknown.
+  if (wallP95Delta === UNKNOWN) {
+    reasons.push('gate:wall-unknown');
+    return freezeResult({ forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta, verdict: 'unknown', comparable, envMismatch, reasons });
+  }
+  if (wallP95Delta > 0) {
+    reasons.push('gate:wall-p95');
+    return freezeResult({ forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta, verdict: 'non-inferior', comparable, envMismatch, reasons });
+  }
+
+  // 5. Within every pre-registered bound → pass.
+  reasons.push('gate:pass');
+  return freezeResult({ forbiddenFailures, qualityDelta, wallP50Delta, wallP95Delta, verdict: 'pass', comparable, envMismatch, reasons });
+}
+
+function freezeResult(result) {
+  return Object.freeze(result);
+}

package/src/core/agentRuntime/eventStore.js

@@ -0,0 +1,404 @@
+/**
+ * agentRuntime/eventStore.js — decision-first-runtime G1 storage prototype
+ * (SPEC §4, §5 G1-FR03/05/06, §6 crash windows).
+ *
+ * Layout under `dir`:
+ *   events/<operationId>.jsonl  append-only SemanticEvent journal (truth)
+ *   state/<operationId>.json    guarded operation state (cache — replay wins)
+ *   continuations.jsonl         durable continuation registrations
+ *   consumptions.jsonl          durable consumptionKey records
+ *
+ * Crash windows (SPEC §6):
+ *   - continuation registration: appended to continuations.jsonl BEFORE the
+ *     operation is started — the API has no "start"; a registered continuation
+ *     whose operation journal never appears is `orphaned` and never auto-fires.
+ *   - event append: a crash mid-line leaves a truncated tail; readers discard
+ *     the tail and the last good seq remains the cursor.
+ *   - transition commit: state file is a cache; replay derives state from the
+ *     journal — no event is ever lost to a missing state write.
+ *   - consumption commit: consumptionKey records are checked before
+ *     consumption; a re-delivery of the same consuming event is an idempotent
+ *     no-op (duplicate), never a second consumption.
+ *   - migration: output is written to temp files then atomically renamed;
+ *     corrupt input fails closed before any output is produced.
+ *
+ * Prototype scope (omp, flag-gated by TASK-004 — this module performs no
+ * config reads and writes nothing unless called).
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import {
+  CONTRACT_VERSION,
+  validateSemanticEvent,
+  validateEventOrder,
+} from './contract.js';
+
+export class EventStoreError extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.name = 'EventStoreError';
+    this.code = code;
+  }
+}
+
+const JOURNAL_DIR = 'events';
+const STATE_DIR = 'state';
+const CONTINUATIONS_FILE = 'continuations.jsonl';
+const CONSUMPTIONS_FILE = 'consumptions.jsonl';
+
+const journalPath = (dir, operationId) =>
+  path.join(dir, JOURNAL_DIR, `${operationId}.jsonl`);
+const statePath = (dir, operationId) =>
+  path.join(dir, STATE_DIR, `${operationId}.json`);
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Atomic write: temp file + fsync + rename (SPEC §6 migration/state windows). */
+async function writeFileAtomic(target, data) {
+  const tmp = `${target}.tmp-${process.pid}`;
+  const handle = await fs.open(tmp, 'w');
+  try {
+    await handle.writeFile(data, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await fs.rename(tmp, target);
+}
+
+/** Append one line and fsync. */
+async function appendLine(file, obj) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const handle = await fs.open(file, 'a');
+  try {
+    await handle.writeFile(`${JSON.stringify(obj)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Parse raw JSONL text. A final line without a terminating newline that fails
+ * to parse is a crash-truncated tail → discarded, `truncatedTail: true`
+ * (logged by caller). A malformed line mid-file is corruption → throws
+ * journal_corrupt. Shared by journal files and JSONL sidecars so both follow
+ * the same torn-tail/fail-closed contract.
+ */
+function parseJsonLines(raw, label) {
+  const endsWithNewline = raw.endsWith('\n');
+  const lines = raw.split('\n');
+  if (endsWithNewline) lines.pop(); // trailing empty segment
+
+  const records = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line === '') continue;
+    const isLast = i === lines.length - 1;
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      if (isLast && !endsWithNewline) {
+        // crash mid-write: truncated tail is recoverable
+        return { records, truncatedTail: true };
+      }
+      throw new EventStoreError(
+        'journal_corrupt',
+        `corrupt journal line ${i + 1} in ${label}`,
+      );
+    }
+  }
+  return { records, truncatedTail: false };
+}
+
+/**
+ * Parse a journal file. Returns `{ events, truncatedTail }`:
+ * - a final line without a terminating newline or with unparseable JSON is a
+ *   crash-truncated tail → discarded, `truncatedTail: true` (logged by caller).
+ * - a malformed line mid-file is corruption → throws journal_corrupt.
+ */
+async function parseJournalFile(file) {
+  if (!(await pathExists(file))) return { events: [], truncatedTail: false };
+  const raw = await fs.readFile(file, 'utf8');
+  if (raw.length === 0) return { events: [], truncatedTail: false };
+  const { records: events, truncatedTail } = parseJsonLines(raw, file);
+  return { events, truncatedTail };
+}
+
+/**
+ * Scan the journal and build the ordering cursor. Mirrors readJournal's
+ * semantics: truncated tail is skipped; mid-file corruption throws.
+ */
+async function loadCursor(dir, operationId) {
+  const { events, truncatedTail } = await parseJournalFile(journalPath(dir, operationId));
+  if (truncatedTail) {
+    // eslint-disable-next-line no-console
+    console.warn(`eventStore: discarded truncated tail line in journal for ${operationId}`);
+  }
+  const cursor = { lastSeq: 0, seenEventIds: new Set() };
+  for (const event of events) {
+    const v = validateEventOrder(event, cursor);
+    if (!v.ok) {
+      throw new EventStoreError(v.code, `journal seq violation at seq ${event.seq}`);
+    }
+  }
+  return cursor;
+}
+
+/**
+ * Append a validated SemanticEvent to the operation journal. Envelope and
+ * ordering are validated against contract.js; duplicate eventId/seq is an
+ * idempotent no-op; a future seq rejects out_of_order. The line is fsync'd
+ * before returning — once this resolves, the event survives a crash.
+ *
+ * @param {string} dir store root
+ * @param {object} event SemanticEvent (contract v1)
+ * @param {object} [opts] `{ hooks: { afterAppend } }` — test fault injection
+ * @returns {Promise<{seq:number, duplicate?:boolean}>}
+ */
+export async function appendEvent(dir, event, opts = {}) {
+  const shape = validateSemanticEvent(event);
+  if (!shape.ok) throw new EventStoreError(shape.code, shape.code);
+
+  const cursor = await loadCursor(dir, event.operationId);
+  const order = validateEventOrder(event, cursor);
+  if (!order.ok) throw new EventStoreError(order.code, order.code);
+  if (order.duplicate) return { seq: event.seq, duplicate: true };
+
+  await appendLine(journalPath(dir, event.operationId), event);
+  await opts.hooks?.afterAppend?.(event);
+  return { seq: event.seq };
+}
+
+/**
+ * Read an operation journal in seq order. Truncated tail lines are discarded
+ * (crash-mid-write); mid-file corruption throws journal_corrupt.
+ *
+ * @param {string} dir
+ * @param {string} operationId
+ * @returns {AsyncIterable<object>}
+ */
+export async function* readJournal(dir, operationId) {
+  const { events, truncatedTail } = await parseJournalFile(journalPath(dir, operationId));
+  if (truncatedTail) {
+    // eslint-disable-next-line no-console
+    console.warn(`eventStore: discarded truncated tail line in journal for ${operationId}`);
+  }
+  for (const event of events) {
+    const shape = validateSemanticEvent(event);
+    if (!shape.ok) {
+      throw new EventStoreError('journal_corrupt', `invalid event envelope at seq ${event?.seq}`);
+    }
+    yield event;
+  }
+}
+
+/**
+ * Write the guarded operation state file (cache only — the journal is truth).
+ * Atomic temp+rename+fsync.
+ *
+ * @param {string} dir
+ * @param {string} operationId
+ * @param {object} state `{ state, ...meta }`
+ * @param {object} [opts] `{ hooks: { beforeWrite } }` — test fault injection
+ */
+export async function writeOperationState(dir, operationId, state, opts = {}) {
+  await opts.hooks?.beforeWrite?.();
+  const file = statePath(dir, operationId);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await writeFileAtomic(file, `${JSON.stringify({ operationId, ...state, contractVersion: CONTRACT_VERSION })}\n`);
+}
+
+/**
+ * Derive operation state by replaying `operation.transition` events. Proves
+ * the state file is a cache: a crash between event append and state write
+ * loses nothing.
+ *
+ * @returns {Promise<{state:string|null, lastSeq:number}>}
+ */
+export async function deriveOperationState(dir, operationId) {
+  let state = null;
+  let lastSeq = 0;
+  for await (const event of readJournal(dir, operationId)) {
+    lastSeq = event.seq;
+    if (event.eventType === 'operation.transition' && event.safePayload?.to) {
+      state = event.safePayload.to;
+    }
+  }
+  return { operationId, state, lastSeq };
+}
+
+/**
+ * Durably register a continuation BEFORE the operation it waits on can be
+ * started (register-before-start invariant — this module exposes no "start"
+ * API, so registration always precedes any operation activity a caller
+ * performs). Appended fsync'd to continuations.jsonl.
+ *
+ * @param {string} dir
+ * @param {object} continuation `{continuationId, planVersion, nodeId, operationId, afterSeq, selector, consumptionKey}`
+ */
+export async function registerContinuation(dir, continuation) {
+  for (const f of ['continuationId', 'operationId', 'nodeId', 'consumptionKey']) {
+    if (typeof continuation?.[f] !== 'string' || continuation[f] === '') {
+      throw new EventStoreError('malformed_continuation', `missing ${f}`);
+    }
+  }
+  const record = { ...continuation, status: 'registered' };
+  await appendLine(path.join(dir, CONTINUATIONS_FILE), record);
+  return record;
+}
+
+/**
+ * Read a JSONL sidecar (continuations/consumptions). Same contract as
+ * parseJournalFile: a crash-torn final line is discarded; mid-file
+ * corruption throws journal_corrupt — never a raw SyntaxError.
+ */
+async function readRecords(file) {
+  if (!(await pathExists(file))) return [];
+  const raw = await fs.readFile(file, 'utf8');
+  if (raw.length === 0) return [];
+  const { records, truncatedTail } = parseJsonLines(raw, file);
+  if (truncatedTail) {
+    // eslint-disable-next-line no-console
+    console.warn(`eventStore: discarded truncated tail line in ${path.basename(file)}`);
+  }
+  return records;
+}
+
+/**
+ * Recovery pass: registered continuations whose operation journal never
+ * appeared are marked `orphaned` and never auto-fire (SPEC §6 row 1).
+ *
+ * @returns {Promise<object[]>} continuations with resolved status
+ */
+export async function recoverContinuations(dir) {
+  const records = await readRecords(path.join(dir, CONTINUATIONS_FILE));
+  const out = [];
+  for (const c of records) {
+    const hasJournal = await pathExists(journalPath(dir, c.operationId));
+    out.push({ ...c, status: hasJournal ? c.status : 'orphaned' });
+  }
+  return out;
+}
+
+/**
+ * Consume a continuation for a delivered event. Idempotent on
+ * `consumptionKey` plus the consuming event's `eventId`: a re-delivery of the
+ * same event is a duplicate no-op even if the crash window hit between
+ * consumption and the key record (SPEC §6 row 4).
+ *
+ * @returns {Promise<{consumed:boolean, duplicate?:boolean}>}
+ */
+export async function consumeContinuation(dir, continuationId, event) {
+  const records = await readRecords(path.join(dir, CONTINUATIONS_FILE));
+  const cont = records.find((c) => c.continuationId === continuationId);
+  if (!cont) throw new EventStoreError('unknown_continuation', continuationId);
+  if (cont.status === 'orphaned') {
+    throw new EventStoreError('orphaned_continuation', continuationId);
+  }
+
+  const consumptionFile = path.join(dir, CONSUMPTIONS_FILE);
+  const consumed = await readRecords(consumptionFile);
+  const hit = consumed.find(
+    (r) => r.consumptionKey === cont.consumptionKey || r.eventId === event.eventId,
+  );
+  if (hit) return { consumed: false, duplicate: true };
+
+  await appendLine(consumptionFile, {
+    continuationId,
+    consumptionKey: cont.consumptionKey,
+    eventId: event.eventId,
+    seq: event.seq,
+    consumedAt: new Date().toISOString(),
+  });
+  return { consumed: true };
+}
+
+/**
+ * Migration prototype v0→v1. Reads a v0 journal dir (`<op>.jsonl` files with
+ * `{id,op,n,kind,at,data}` lines), emits contract-v1 SemanticEvent JSONL files
+ * in `outDir`. Deterministic: key order fixed, file order sorted → N runs on
+ * the same input are byte-identical. Corrupt input fails closed BEFORE any
+ * output is written; output lands via temp file + atomic rename per journal.
+ *
+ * @param {string} fromDir directory containing v0 `<op>.jsonl` files
+ * @param {string} outDir output directory
+ * @param {object} opts `{ from: 0, to: 1 }`
+ * @returns {Promise<{migrated:number}>}
+ */
+export async function migrateJournal(fromDir, outDir, opts = {}) {
+  const { from = 0, to = CONTRACT_VERSION } = opts;
+  if (from !== 0 || to !== CONTRACT_VERSION) {
+    throw new EventStoreError('unsupported_migration', `v${from}→v${to}`);
+  }
+
+  let names;
+  try {
+    names = (await fs.readdir(fromDir)).filter((n) => n.endsWith('.jsonl')).sort();
+  } catch {
+    throw new EventStoreError('journal_missing', fromDir);
+  }
+
+  // Phase 1: fully transform all input in memory — fail closed before any
+  // output write (no partial migration state).
+  const outputs = [];
+  for (const name of names) {
+    // raced unlink between readdir and read → typed error, not raw fs error
+    let raw;
+    try {
+      raw = await fs.readFile(path.join(fromDir, name), 'utf8');
+    } catch (err) {
+      throw new EventStoreError('journal_missing', `${name}: ${err.message}`);
+    }
+    const lines = raw.split('\n').filter((l) => l !== '');
+    const events = [];
+    for (let i = 0; i < lines.length; i += 1) {
+      let rec;
+      try {
+        rec = JSON.parse(lines[i]);
+      } catch {
+        throw new EventStoreError('journal_corrupt', `${name} line ${i + 1}`);
+      }
+      if (
+        typeof rec?.id !== 'string' || typeof rec?.op !== 'string'
+        || !Number.isInteger(rec?.n) || typeof rec?.kind !== 'string'
+        || typeof rec?.at !== 'string'
+      ) {
+        throw new EventStoreError('journal_corrupt', `${name} line ${i + 1}: malformed v0 record`);
+      }
+      events.push({
+        eventId: rec.id,
+        operationId: rec.op,
+        seq: rec.n,
+        eventType: rec.kind === 'transition' ? 'operation.transition' : rec.kind,
+        observedAt: rec.at,
+        producerVersion: 'migrated-v0',
+        contractVersion: CONTRACT_VERSION,
+        privacyClass: 'internal',
+        artifactRefs: [],
+        safePayload: rec.data ?? {},
+      });
+      const shape = validateSemanticEvent(events[events.length - 1]);
+      if (!shape.ok) {
+        throw new EventStoreError('journal_corrupt', `${name} line ${i + 1}: ${shape.code}`);
+      }
+    }
+    outputs.push({ name, body: events.map((e) => JSON.stringify(e)).join('\n') + (events.length ? '\n' : '') });
+  }
+
+  // Phase 2: write each output via temp + atomic rename.
+  await fs.mkdir(outDir, { recursive: true });
+  for (const { name, body } of outputs) {
+    await writeFileAtomic(path.join(outDir, name), body);
+  }
+  return { migrated: outputs.reduce((n, o) => n + (o.body ? o.body.trimEnd().split('\n').length : 0), 0) };
+}

package/src/core/agentRuntime/liveness.js

@@ -0,0 +1,60 @@
+// src/core/agentRuntime/liveness.js
+// Pure observation classifier for the owned-process supervisor (SPEC §4, §6).
+// Classifies one sampled observation into a *non-operation-terminal* state:
+//   'live_progressing' | 'silent_live' | 'stalled' | 'exited' | 'timeout'
+// 'exited'/'timeout' describe the sample, not the operation — the supervisor
+// owns the real terminal transition via validateTransition.
+// No I/O, no clock: every time value is passed in via the sample.
+
+const CLASSES = Object.freeze([
+  'live_progressing',
+  'silent_live',
+  'stalled',
+  'exited',
+  'timeout',
+]);
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+/**
+ * @param {object} sample  { processAlive, bytesWritten, lastOutputAt, startedAt, now }
+ * @param {object} [prev]  previous sample (bytesWritten used for delta)
+ * @param {object} [policy] { silentAfterMs, stallTimeoutMs, wallTimeoutMs, stallAction }
+ * @returns {'live_progressing'|'silent_live'|'stalled'|'exited'|'timeout'}
+ */
+export function classifyObservation(sample, prev, policy) {
+  if (sample == null || typeof sample !== 'object') return 'silent_live';
+
+  const now = num(sample.now);
+  const startedAt = num(sample.startedAt);
+  const lastOutputAt = num(sample.lastOutputAt);
+  const bytes = num(sample.bytesWritten);
+  const alive = sample.processAlive !== false;
+
+  const p = policy && typeof policy === 'object' ? policy : {};
+  const wallTimeoutMs = num(p.wallTimeoutMs) ?? Number.POSITIVE_INFINITY;
+  const stallTimeoutMs = num(p.stallTimeoutMs) ?? Number.POSITIVE_INFINITY;
+  const silentAfterMs = num(p.silentAfterMs) ?? Number.POSITIVE_INFINITY;
+
+  // Malformed clock fields → conservative non-terminal observation.
+  if (now == null) return 'silent_live';
+
+  // Wall-clock timeout dominates every other observation, including exit.
+  if (startedAt != null && now - startedAt >= wallTimeoutMs) return 'timeout';
+
+  if (!alive) return 'exited';
+
+  // Progress: byte delta vs previous sample, or provably fresh output.
+  const prevBytes = prev && typeof prev === 'object' ? num(prev.bytesWritten) : null;
+  if (bytes != null && prevBytes != null && bytes > prevBytes) return 'live_progressing';
+
+  // Silence age unknown → treat as fresh (still within the silent window).
+  const silenceAge = lastOutputAt != null ? Math.max(0, now - lastOutputAt) : 0;
+  if (silenceAge >= stallTimeoutMs) return 'stalled';
+  if (silenceAge >= silentAfterMs) return 'silent_live';
+  return 'live_progressing';
+}
+
+export const LIVENESS_CLASSES = CLASSES;