@ngockhoale/ukit 3.0.8 → 3.0.9

package/src/core/agentRuntime/context.js

@@ -0,0 +1,149 @@
+// Bounded runtime-context compiler (G5 / TASK-002).
+// Pure module: no I/O, no runtimeConfig reads, no adapter/gate imports.
+// Compiles goal / verified state / evidence / memory records into a frozen
+// BoundedContext under a hard byte budget that includes framing and
+// provenance labels. Every included item carries {source, ref, bytes, age?};
+// every dropped item is listed in omitted[] with {source, ref, reason} —
+// omission is always visible, never silent.
+//
+// Memory records pass through src/core/memory/policy.js eligible();
+// ineligible records are excluded (omitted with the policy reason), and
+// eligible-but-unverified records are labeled 'unverified' and quoted —
+// never injected as instruction.
+
+import { eligible } from '../memory/policy.js';
+
+const STALE_MS = 15 * 60 * 1000; // default freshness window for evidence
+
+const HEADER = '# UKit runtime context';
+const FOOTER = '# end context';
+
+function byteLen(s) {
+  return Buffer.byteLength(s, 'utf8');
+}
+
+function oneLine(text) {
+  return String(text).split('\n').join(' ');
+}
+
+// Each candidate: { source, ref, label|null, age?, line, required }
+function renderLine(c) {
+  const label = c.label ? ` ${c.label}` : '';
+  const age = c.age != null ? ` age=${c.age}ms` : '';
+  const prefix = c.label === 'unverified' ? '> ' : '';
+  return `${prefix}[${c.source}${label} ref=${c.ref}${age}] ${oneLine(c.text)}`;
+}
+
+export function compileRuntimeContext({
+  task,
+  verifiedState,
+  evidence,
+  memoryRecords,
+  budget,
+  now,
+} = {}) {
+  const nowMs = typeof now === 'number' ? now : Date.now();
+
+  if (typeof budget !== 'number' || !Number.isFinite(budget) || budget <= 0) {
+    return { ok: false, code: 'malformed_input' };
+  }
+  if (task == null || typeof task !== 'object' || typeof task.goal !== 'string' || task.goal.length === 0) {
+    return { ok: false, code: 'malformed_input' };
+  }
+  if (evidence != null && !Array.isArray(evidence)) {
+    return { ok: false, code: 'malformed_input' };
+  }
+  if (memoryRecords != null && !Array.isArray(memoryRecords)) {
+    return { ok: false, code: 'malformed_input' };
+  }
+
+  const candidates = [];
+  const omitted = [];
+  const push = (c, required = false) => candidates.push({ ...c, required });
+  const omit = (source, ref, reason) =>
+    omitted.push(Object.freeze({ source, ref, reason }));
+
+  // Goal is always required — a context with no goal is not a context.
+  push({ source: 'task', ref: task.id != null ? String(task.id) : 'task', text: `goal: ${task.goal}` }, true);
+
+  if (verifiedState != null) {
+    const text = typeof verifiedState === 'string' ? verifiedState : verifiedState.summary;
+    if (typeof text === 'string' && text.length > 0) {
+      push({ source: 'verified-state', ref: verifiedState.ref != null ? String(verifiedState.ref) : 'state', text }, true);
+    }
+  }
+
+  for (const ev of evidence || []) {
+    if (ev == null || typeof ev !== 'object' || typeof ev.content !== 'string') {
+      omit('evidence', ev && ev.ref != null ? String(ev.ref) : 'unknown', 'malformed_input');
+      continue;
+    }
+    const source = typeof ev.source === 'string' ? ev.source : 'evidence';
+    const ref = ev.ref != null ? String(ev.ref) : 'unknown';
+    const ttl = typeof ev.ttlMs === 'number' ? ev.ttlMs : STALE_MS;
+    const age = typeof ev.observedAt === 'number' ? nowMs - ev.observedAt : null;
+    if (age != null && age > ttl) {
+      omit(source, ref, 'stale');
+      continue;
+    }
+    push({ source, ref, text: ev.content, age });
+  }
+
+  const memContext = {
+    projectId:
+      (verifiedState && typeof verifiedState.projectId === 'string' ? verifiedState.projectId : null)
+      ?? (typeof task.projectId === 'string' ? task.projectId : null),
+    now: nowMs,
+  };
+
+  for (const rec of memoryRecords || []) {
+    const ref = rec && rec.id != null ? String(rec.id) : 'memory';
+    const verdict = eligible(rec, memContext);
+    if (!verdict.ok) {
+      omit('memory', ref, verdict.reason);
+      continue;
+    }
+    const text = typeof rec.content === 'string' ? rec.content
+      : typeof rec.text === 'string' ? rec.text
+      : null;
+    if (text == null) {
+      omit('memory', ref, 'malformed_input');
+      continue;
+    }
+    const unverified = rec.verified !== true && rec.trust_tier !== 'verified';
+    push({ source: 'memory', ref, text, label: unverified ? 'unverified' : null });
+  }
+
+  const framingBytes = byteLen(`${HEADER}\n\n${FOOTER}\n`);
+  let used = framingBytes;
+  const includedLines = [];
+  const included = [];
+
+  for (const c of candidates) {
+    const line = renderLine(c);
+    const lineBytes = byteLen(line) + 1; // trailing newline
+    if (used + lineBytes <= budget) {
+      used += lineBytes;
+      includedLines.push(line);
+      const item = { source: c.source, ref: c.ref, bytes: lineBytes };
+      if (c.age != null) item.age = c.age;
+      if (c.label) item.label = c.label;
+      included.push(Object.freeze(item));
+    } else if (c.required) {
+      // A required element cannot fit: nothing useful can be emitted.
+      return { ok: false, code: 'over_budget' };
+    } else {
+      omit(c.source, c.ref, 'over_budget');
+    }
+  }
+
+  const packet = `${HEADER}\n${includedLines.join('\n')}\n${FOOTER}\n`;
+  return {
+    ok: true,
+    context: Object.freeze({
+      packet,
+      included: Object.freeze(included),
+      omitted: Object.freeze(omitted),
+    }),
+  };
+}

package/src/core/agentRuntime/contract.js

@@ -0,0 +1,247 @@
+/**
+ * agentRuntime/contract.js — decision-first-runtime G1 (DR-02), contract v1.
+ *
+ * Pure validators for the versioned operation state machine, the SemanticEvent
+ * envelope, and side-effect/retry permission rules. No I/O, no host calls.
+ * Every rejection is a typed result `{ ok:false, code }` — never a throw.
+ *
+ * Spec: docs/AI_HANDOFF/SPEC.md §2 (G1-FR01/02/04), §4, §5.
+ */
+
+export const CONTRACT_VERSION = 1;
+
+export const OPERATION_STATES = Object.freeze([
+  'queued',
+  'starting',
+  'running',
+  'cancel_pending',
+  'retry_pending',
+  'recovery_required',
+  'completed',
+  'failed',
+  'cancelled',
+]);
+
+export const TERMINAL_STATES = Object.freeze(['completed', 'failed', 'cancelled']);
+
+const TERMINAL_SET = new Set(TERMINAL_STATES);
+const STATE_SET = new Set(OPERATION_STATES);
+
+/**
+ * Legal edges. `recovery_required` is reachable from every non-terminal state
+ * and resolves to exactly one terminal state — it never re-enters `running`.
+ */
+const TRANSITIONS = Object.freeze({
+  queued: new Set(['starting', 'recovery_required']),
+  starting: new Set(['running', 'cancel_pending', 'recovery_required']),
+  running: new Set(['completed', 'failed', 'cancel_pending', 'retry_pending', 'recovery_required']),
+  cancel_pending: new Set(['cancelled', 'recovery_required']),
+  retry_pending: new Set(['running', 'cancel_pending', 'recovery_required']),
+  recovery_required: new Set(TERMINAL_STATES),
+  completed: new Set(),
+  failed: new Set(),
+  cancelled: new Set(),
+});
+
+export const SIDE_EFFECT_CLASSES = Object.freeze([
+  'pure',
+  'read_only',
+  'idempotent_write',
+  'write',
+  'network',
+  'destructive',
+]);
+
+/** Classes that MAY auto-retry under bounded attempts + backoff (SPEC §5). */
+const AUTO_RETRYABLE = new Set(['pure', 'read_only', 'idempotent_write']);
+
+const DEFAULT_MAX_ATTEMPTS = 1;
+export const MAX_SAFE_PAYLOAD_BYTES = 32 * 1024;
+
+const ok = () => ({ ok: true });
+const reject = (code) => ({ ok: false, code });
+
+export function isTerminal(state) {
+  return TERMINAL_SET.has(state);
+}
+
+/**
+ * Validate an operation state transition.
+ *
+ * @param {string} prev current state
+ * @param {string} next requested next state
+ * @param {object} ctx transition context; MUST carry `fencingEpoch` (monotonic
+ *   owner epoch). When `ctx.ownerEpoch` is provided, `fencingEpoch` must be
+ *   >= ownerEpoch; a lower or absent epoch is a stale-owner reject.
+ * @returns {{ok:true}|{ok:false, code:string}}
+ */
+export function validateTransition(prev, next, ctx = {}) {
+  if (!STATE_SET.has(prev) || !STATE_SET.has(next)) {
+    return reject('unknown_state');
+  }
+
+  const { fencingEpoch, ownerEpoch } = ctx ?? {};
+  if (
+    !Number.isInteger(fencingEpoch)
+    || fencingEpoch < 0
+    || (ownerEpoch !== undefined && fencingEpoch < ownerEpoch)
+  ) {
+    return reject('stale_owner');
+  }
+
+  if (isTerminal(prev)) {
+    return reject('terminal_reentry');
+  }
+
+  if (!TRANSITIONS[prev].has(next)) {
+    return reject('invalid_transition');
+  }
+
+  return ok();
+}
+
+const REQUIRED_EVENT_FIELDS = Object.freeze([
+  'eventId',
+  'operationId',
+  'seq',
+  'eventType',
+  'observedAt',
+  'producerVersion',
+  'contractVersion',
+  'privacyClass',
+  'artifactRefs',
+  'safePayload',
+]);
+
+/**
+ * Validate a versioned SemanticEvent envelope (SPEC §2 G1-FR02).
+ * Ordering (`seq` cursor, duplicate/gap handling) is enforced by the journal
+ * reader — this validator checks envelope shape only.
+ *
+ * @param {object} event
+ * @returns {{ok:true}|{ok:false, code:string}}
+ */
+export function validateSemanticEvent(event) {
+  if (event === null || typeof event !== 'object' || Array.isArray(event)) {
+    return reject('malformed_event');
+  }
+
+  for (const field of REQUIRED_EVENT_FIELDS) {
+    if (!(field in event)) {
+      return reject('malformed_event');
+    }
+  }
+
+  if (typeof event.eventId !== 'string' || event.eventId.length === 0) {
+    return reject('malformed_event');
+  }
+  if (typeof event.operationId !== 'string' || event.operationId.length === 0) {
+    return reject('malformed_event');
+  }
+  if (!Number.isInteger(event.seq) || event.seq < 0) {
+    return reject('malformed_event');
+  }
+  if (typeof event.eventType !== 'string' || event.eventType.length === 0) {
+    return reject('malformed_event');
+  }
+  if (typeof event.observedAt !== 'string' || Number.isNaN(Date.parse(event.observedAt))) {
+    return reject('malformed_event');
+  }
+  if (typeof event.producerVersion !== 'string' || event.producerVersion.length === 0) {
+    return reject('malformed_event');
+  }
+  if (event.contractVersion !== CONTRACT_VERSION) {
+    return reject('unsupported_contract_version');
+  }
+  if (typeof event.privacyClass !== 'string' || event.privacyClass.length === 0) {
+    return reject('malformed_event');
+  }
+  if (!Array.isArray(event.artifactRefs)) {
+    return reject('malformed_event');
+  }
+
+  // safePayload is bounded and must never carry raw output (SPEC §2).
+  let payloadBytes;
+  try {
+    payloadBytes = Buffer.byteLength(JSON.stringify(event.safePayload ?? null), 'utf8');
+  } catch {
+    return reject('malformed_event');
+  }
+  if (payloadBytes > MAX_SAFE_PAYLOAD_BYTES) {
+    return reject('payload_too_large');
+  }
+
+  return ok();
+}
+
+/**
+ * Validate a SemanticEvent against the per-operation ordering cursor
+ * (SPEC §2): `seq` is the causal cursor — strictly monotonic, gap-free.
+ * A duplicate `eventId` or already-seen `seq` is an idempotent no-op
+ * (`{ok:true, duplicate:true}`); a future `seq` is a typed reject
+ * `out_of_order` — never a silent reorder.
+ *
+ * `cursor` is the caller-owned per-operation state:
+ * `{ lastSeq: number, seenEventIds?: Set<string> }`. It is mutated only on a
+ * non-duplicate accept (`lastSeq` advances, `eventId` recorded).
+ *
+ * @param {object} event event already accepted by validateSemanticEvent
+ * @param {object} cursor
+ * @returns {{ok:true, duplicate?:boolean}|{ok:false, code:string}}
+ */
+export function validateEventOrder(event, cursor) {
+  if (cursor === null || typeof cursor !== 'object' || !Number.isInteger(cursor.lastSeq) || cursor.lastSeq < 0) {
+    return reject('malformed_cursor');
+  }
+
+  const seen = cursor.seenEventIds instanceof Set ? cursor.seenEventIds : null;
+  if (seen?.has(event.eventId) || event.seq <= cursor.lastSeq) {
+    return { ok: true, duplicate: true };
+  }
+
+  if (event.seq !== cursor.lastSeq + 1) {
+    return reject('out_of_order');
+  }
+
+  cursor.lastSeq = event.seq;
+  seen?.add(event.eventId);
+  return ok();
+}
+
+/**
+ * Validate whether an attempt is permitted for a side-effect class.
+ *
+ * `attempt` is 1-based: attempt 1 is the initial execution and is always
+ * allowed; attempt >= 2 is a replay and is only permitted for auto-retryable
+ * classes within `policy.maxAttempts`. `write`/`network`/`destructive` and any
+ * unrecognized class fall into the most conservative bucket: no auto-replay —
+ * post-crash they resolve to `recovery_required` (SPEC §5).
+ *
+ * @param {string} sideEffectClass
+ * @param {number} attempt 1-based attempt number
+ * @param {object} [policy] `{ maxAttempts }` — total attempts allowed
+ * @returns {{ok:true}|{ok:false, code:string}}
+ */
+export function validateRetry(sideEffectClass, attempt, policy = {}) {
+  if (!Number.isInteger(attempt) || attempt < 1) {
+    return reject('invalid_attempt');
+  }
+
+  const maxAttempts = Number.isInteger(policy?.maxAttempts) && policy.maxAttempts >= 1
+    ? policy.maxAttempts
+    : DEFAULT_MAX_ATTEMPTS;
+
+  if (attempt === 1) {
+    return ok();
+  }
+
+  if (!AUTO_RETRYABLE.has(sideEffectClass)) {
+    return reject('retry_unsafe');
+  }
+
+  if (attempt > maxAttempts) {
+    return reject('retry_exhausted');
+  }
+
+  return ok();
+}

package/src/core/agentRuntime/diagnostics.js

@@ -0,0 +1,244 @@
+/**
+ * agentRuntime/diagnostics.js — decision-first-runtime G7 (DR-10),
+ * explainable trace/replay readers (SPEC §2 G7-FR01/02, §4, §5, §7).
+ *
+ * Two pure readers over the operation journal:
+ *   renderOperationTimeline → deterministic frozen SanitizedTimeline
+ *   replayOperation         → read-only frozen ReplayResult
+ *
+ * Privacy contract (SPEC §5): `summary` strings are assembled from the
+ * eventType plus a whitelist of enumerated code/state fields — raw
+ * `safePayload` text is NEVER copied into output. Values must match a
+ * bounded code pattern; anything else is dropped silently.
+ *
+ * Read-only guarantee: this module performs no writes, spawns, signals,
+ * or enqueues. Journal + contract are the only inputs. It performs no
+ * config reads (same convention as eventStore.js).
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import {
+  CONTRACT_VERSION,
+  OPERATION_STATES,
+  isTerminal,
+  validateTransition,
+} from './contract.js';
+import { readJournal, EventStoreError } from './eventStore.js';
+
+export class DiagnosticsError extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.name = 'DiagnosticsError';
+    this.code = code;
+  }
+}
+
+const JOURNAL_DIR = 'events';
+const STATE_SET = new Set(OPERATION_STATES);
+
+const journalPath = (dir, operationId) =>
+  path.join(dir, JOURNAL_DIR, `${operationId}.jsonl`);
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Bounded code pattern — states, codes, digests only; never free text. */
+const CODE_RE = /^[a-z0-9_.:-]{1,64}$/;
+
+/** Whitelisted safePayload fields whose values are enumerated codes. */
+const CODE_FIELDS = Object.freeze(['code', 'reason', 'status', 'kind', 'attempt']);
+const NUMERIC_FIELDS = Object.freeze(['seq', 'step', 'attempt', 'count', 'durationMs']);
+
+function codeValue(v) {
+  return typeof v === 'string' && CODE_RE.test(v) ? v : null;
+}
+
+/**
+ * Build a sanitized summary from eventType + enumerated code fields only.
+ * `from`/`to` are emitted only when they are known contract states.
+ */
+function summarize(event) {
+  const parts = [event.eventType];
+  const p = event.safePayload;
+  if (p !== null && typeof p === 'object' && !Array.isArray(p)) {
+    for (const f of ['from', 'to']) {
+      if (STATE_SET.has(p[f])) parts.push(`${f}=${p[f]}`);
+    }
+    for (const f of CODE_FIELDS) {
+      const v = codeValue(p[f]);
+      if (v !== null) parts.push(`${f}=${v}`);
+    }
+    for (const f of NUMERIC_FIELDS) {
+      if (Number.isFinite(p[f]) && !['from', 'to'].includes(f) && !CODE_FIELDS.includes(f)) {
+        parts.push(`${f}=${p[f]}`);
+      }
+    }
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Read + validate the journal; throws DiagnosticsError('journal_missing')
+ * when absent and detects the truncated-tail flag the reader discards.
+ */
+async function loadJournal(dir, operationId) {
+  const file = journalPath(dir, operationId);
+  if (!(await pathExists(file))) {
+    throw new DiagnosticsError('journal_missing', `no journal for ${operationId}`);
+  }
+  let raw;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      throw new DiagnosticsError('journal_missing', `no journal for ${operationId}`);
+    }
+    throw new DiagnosticsError('journal_unreadable', err && err.code ? err.code : 'read_failed');
+  }
+  const truncatedTail = !raw.endsWith('\n');
+  const events = [];
+  try {
+    for await (const e of readJournal(dir, operationId)) events.push(e);
+  } catch (err) {
+    if (err instanceof EventStoreError) {
+      throw new DiagnosticsError('malformed_event', err.code);
+    }
+    if (err && err.code === 'ENOENT') {
+      // file raced away after the guarded pre-read — same contract as :102
+      throw new DiagnosticsError('journal_missing', `no journal for ${operationId}`);
+    }
+    if (err && typeof err.code === 'string' && err.code !== '') {
+      // fs failure inside readJournal's own readFile (e.g. EACCES/EIO) —
+      // the DiagnosticsError contract covers the whole loadJournal surface
+      throw new DiagnosticsError('journal_unreadable', err.code);
+    }
+    throw err;
+  }
+  for (const e of events) {
+    if (e.contractVersion !== CONTRACT_VERSION) {
+      throw new DiagnosticsError(
+        'unsupported_contract_version',
+        `event seq ${e.seq} contractVersion ${e.contractVersion}`,
+      );
+    }
+  }
+  return { events, truncatedTail };
+}
+
+const gap = (seq, code, detail) => Object.freeze({ seq, code, detail });
+
+/**
+ * Fold transition events through validateTransition. Returns
+ * { derivedState, lastSeq, gaps, boundarySeq } — folding stops at the
+ * first replay boundary; events after it are recorded as gaps, never
+ * used to infer state (SPEC §7).
+ */
+function foldTransitions(events) {
+  const gaps = [];
+  let state = null;
+  let lastSeq = 0;
+  let boundarySeq = null;
+
+  for (const e of events) {
+    lastSeq = e.seq;
+    if (/^(model\.|tool\.)/.test(e.eventType)) {
+      gaps.push(gap(e.seq, 'external_input', `${e.eventType} output is nondeterministic; not re-derived`));
+      continue;
+    }
+    if (boundarySeq !== null) {
+      // everything past the boundary is display-only, never inferred
+      if (e.eventType === 'operation.transition') {
+        gaps.push(gap(e.seq, 'replay_boundary', 'transition after recovery boundary ignored'));
+      }
+      continue;
+    }
+    if (e.eventType !== 'operation.transition') continue;
+    const to = e.safePayload?.to;
+    if (!STATE_SET.has(to)) {
+      gaps.push(gap(e.seq, 'replay_boundary', 'transition missing target state'));
+      boundarySeq = e.seq;
+      continue;
+    }
+    const prev = state === null ? (STATE_SET.has(e.safePayload?.from) ? e.safePayload.from : 'queued') : state;
+    const ctx = { fencingEpoch: Number.isInteger(e.safePayload?.fencingEpoch) ? e.safePayload.fencingEpoch : e.seq };
+    const v = validateTransition(prev, to, ctx);
+    if (!v.ok) {
+      gaps.push(gap(e.seq, 'replay_boundary', `transition ${prev}→${to} rejected: ${v.code}`));
+      boundarySeq = e.seq;
+      continue;
+    }
+    state = to;
+    if (to === 'recovery_required') {
+      gaps.push(gap(e.seq, 'recovery_boundary', 'recovery_required is never resolved by replay alone'));
+      boundarySeq = e.seq;
+    }
+  }
+  return { derivedState: state, lastSeq, gaps, boundarySeq };
+}
+
+function classifyReplayable(derivedState, gaps, events) {
+  if (derivedState === null) {
+    return events.length === 0 ? 'none' : 'partial'; // start_unconfirmed window
+  }
+  if (isTerminal(derivedState) && gaps.length === 0) return 'full';
+  return 'partial';
+}
+
+/**
+ * G7-FR01 — deterministic frozen SanitizedTimeline.
+ *
+ * @param {string} dir store root
+ * @param {string} operationId
+ * @returns {Promise<object>} SanitizedTimeline (SPEC §4)
+ */
+export async function renderOperationTimeline(dir, operationId, _opts = {}) {
+  const { events, truncatedTail } = await loadJournal(dir, operationId);
+  const steps = events.map((e) => Object.freeze({
+    seq: e.seq,
+    eventType: e.eventType,
+    observedAt: e.observedAt,
+    summary: summarize(e),
+    artifactRefs: Object.freeze(
+      (Array.isArray(e.artifactRefs) ? e.artifactRefs : []).filter((r) => typeof r === 'string'),
+    ),
+  }));
+  const { derivedState, gaps } = foldTransitions(events);
+  return Object.freeze({
+    version: 1,
+    operationId,
+    steps: Object.freeze(steps),
+    terminalState: isTerminal(derivedState) ? derivedState : null,
+    journalTruncated: truncatedTail,
+    gaps: Object.freeze(gaps),
+  });
+}
+
+/**
+ * G7-FR02 — read-only logical replay. MUST NOT spawn, signal, write, or
+ * enqueue; the returned frozen object is the only output (SPEC §7).
+ *
+ * @param {string} dir store root
+ * @param {string} operationId
+ * @returns {Promise<object>} ReplayResult (SPEC §4)
+ */
+export async function replayOperation(dir, operationId, _opts = {}) {
+  const { events } = await loadJournal(dir, operationId);
+  const { derivedState, lastSeq, gaps } = foldTransitions(events);
+  const replayable = classifyReplayable(derivedState, gaps, events);
+  return Object.freeze({
+    version: 1,
+    operationId,
+    derivedState: derivedState ?? 'unknown',
+    lastSeq,
+    replayable,
+    gaps: Object.freeze(gaps),
+  });
+}