@ngockhoale/ukit 3.0.8 → 3.0.9

package/src/core/agentRuntime/planCompiler.js

@@ -0,0 +1,322 @@
+/**
+ * agentRuntime/planCompiler.js — decision-first-runtime G4 (DR-06), IR v1.
+ *
+ * Pure plan compiler: validates a small DAG IR (frozen opcode set: RUN,
+ * WAIT_EVENT, BRANCH, COMPLETE, ESCALATE) and emits an immutable
+ * ValidatedPlan { planVersion, nodes, entryNodes, order }.
+ *
+ * No I/O, no runtimeConfig reads, no imports of vmEngine. The only
+ * dependency is the read-only SIDE_EFFECT_CLASSES table from contract.js.
+ *
+ * SPEC: docs/AI_HANDOFF/SPEC.md §2 G4-FR01/02, §4, §8.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { SIDE_EFFECT_CLASSES } from './contract.js';
+
+export const PLAN_OPS = Object.freeze([
+  'RUN',
+  'WAIT_EVENT',
+  'BRANCH',
+  'COMPLETE',
+  'ESCALATE',
+]);
+
+const OP_SET = new Set(PLAN_OPS);
+const SIDE_EFFECT_SET = new Set(SIDE_EFFECT_CLASSES);
+
+/** Classes that may auto-retry under bounded attempts (mirrors G1). */
+const AUTO_RETRYABLE = new Set(['pure', 'read_only', 'idempotent_write']);
+
+const DEFAULT_MAX_NODES = 8;
+const DEFAULT_MAX_ATTEMPTS = 1;
+const MAX_ATTEMPTS_CEILING = 3;
+const SELECTOR_OPS = new Set(['eq', 'neq', 'in', 'exists']);
+const PATH_TRAVERSAL = /(^|\/)\.\.(\/|$)/;
+
+function err(errors, code, nodeId, detail) {
+  errors.push({ code, nodeId, detail });
+}
+
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+const isPositiveFinite = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+
+/**
+ * Canonical serialization for content hashing: keys sorted recursively so
+ * identical IR always produces identical bytes.
+ */
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(',')}]`;
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function deepFreeze(value) {
+  if (isPlainObject(value) || Array.isArray(value)) {
+    for (const key of Object.keys(value)) {
+      deepFreeze(value[key]);
+    }
+  }
+  return Object.freeze(value);
+}
+
+function validateSelector(selector, nodeId, errors) {
+  if (!isPlainObject(selector)) {
+    err(errors, 'invalid_selector', nodeId, 'selector must be an object');
+    return;
+  }
+  if (!isNonEmptyString(selector.eventType)) {
+    err(errors, 'invalid_selector', nodeId, 'selector.eventType required');
+    return;
+  }
+  if (selector.op !== undefined && !SELECTOR_OPS.has(selector.op)) {
+    err(errors, 'invalid_selector', nodeId, `selector.op ${JSON.stringify(selector.op)} unsupported`);
+    return;
+  }
+  if (selector.fields !== undefined) {
+    if (!Array.isArray(selector.fields) || selector.fields.some((f) => !isNonEmptyString(f))) {
+      err(errors, 'invalid_selector', nodeId, 'selector.fields must be non-empty strings');
+    }
+  }
+}
+
+function validateSpec(spec, nodeId, errors) {
+  if (!isPlainObject(spec)) {
+    err(errors, 'permission_escalation', nodeId, 'RUN node requires a spec');
+    return;
+  }
+  const declared = Array.isArray(spec.sideEffects) ? spec.sideEffects : [];
+  for (const cls of declared) {
+    if (!SIDE_EFFECT_SET.has(cls)) {
+      err(errors, 'unknown_side_effect_class', nodeId, `spec.sideEffects ${JSON.stringify(cls)}`);
+    }
+  }
+  // Write targets must stay inside declared allowedPaths, if provided.
+  const writes = Array.isArray(spec.writes) ? spec.writes : [];
+  const allowed = Array.isArray(spec.allowedPaths) ? spec.allowedPaths : null;
+  for (const target of writes) {
+    if (!isNonEmptyString(target)) {
+      err(errors, 'permission_escalation', nodeId, 'spec.writes entries must be paths');
+      continue;
+    }
+    if (PATH_TRAVERSAL.test(target)) {
+      err(errors, 'permission_escalation', nodeId, `write ${target} escapes via '..'`);
+      continue;
+    }
+    if (allowed && !allowed.some((prefix) => isNonEmptyString(prefix) && target.startsWith(prefix))) {
+      err(errors, 'permission_escalation', nodeId, `write ${target} outside allowedPaths`);
+    }
+  }
+  return declared;
+}
+
+function validateRetryPolicy(retry, nodeId, declaredEffects, errors) {
+  if (retry === undefined) return undefined;
+  if (!isPlainObject(retry)) {
+    err(errors, 'invalid_retry', nodeId, 'retry must be an object');
+    return undefined;
+  }
+
+  const cls = retry.sideEffectClass;
+  if (!SIDE_EFFECT_SET.has(cls)) {
+    err(errors, 'unknown_side_effect_class', nodeId, `retry.sideEffectClass ${JSON.stringify(cls)}`);
+    return undefined;
+  }
+
+  // A RUN node may not retry a side-effect class its spec never declared.
+  if (Array.isArray(declaredEffects) && !declaredEffects.includes(cls)) {
+    err(errors, 'permission_escalation', nodeId, `retry class ${cls} not in spec.sideEffects`);
+  }
+
+  const maxAttempts = retry.maxAttempts === undefined ? DEFAULT_MAX_ATTEMPTS : retry.maxAttempts;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    err(errors, 'invalid_retry', nodeId, 'maxAttempts must be an integer >= 1');
+    return undefined;
+  }
+  if (maxAttempts > MAX_ATTEMPTS_CEILING) {
+    err(errors, 'invalid_retry', nodeId, `maxAttempts ${maxAttempts} exceeds ceiling 3`);
+    return undefined;
+  }
+  if (maxAttempts > 1 && !AUTO_RETRYABLE.has(cls)) {
+    err(errors, 'invalid_retry', nodeId, `class ${cls} is not auto-retryable`);
+    return undefined;
+  }
+  if (retry.backoffMs !== undefined
+    && (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0)) {
+    err(errors, 'invalid_retry', nodeId, 'backoffMs must be a finite number >= 0');
+    return undefined;
+  }
+
+  return { sideEffectClass: cls, maxAttempts, backoffMs: retry.backoffMs ?? 0 };
+}
+
+/**
+ * compilePlan(ir, opts) — SPEC §4.
+ *
+ * @param {object} ir `{ nodes: [...] }`
+ * @param {{maxNodes?:number, allowedOps?:string[]}} [opts]
+ * @returns {{ok:true, plan:object}|{ok:false, errors:object[]}}
+ */
+export function compilePlan(ir, opts = {}) {
+  const errors = [];
+  const maxNodes = Number.isInteger(opts.maxNodes) && opts.maxNodes > 0
+    ? opts.maxNodes
+    : DEFAULT_MAX_NODES;
+  const allowedOps = Array.isArray(opts.allowedOps)
+    ? new Set(opts.allowedOps)
+    : OP_SET;
+
+  const rawNodes = Array.isArray(ir?.nodes) ? ir.nodes : [];
+  if (rawNodes.length === 0) {
+    err(errors, 'empty_plan', undefined, 'ir.nodes must be a non-empty array');
+    return { ok: false, errors };
+  }
+  if (rawNodes.length > maxNodes) {
+    err(errors, 'too_many_nodes', undefined, `${rawNodes.length} nodes exceeds maxNodes ${maxNodes}`);
+  }
+
+  const ids = new Set();
+  for (const node of rawNodes) {
+    const id = node?.id;
+    if (!isNonEmptyString(id) || ids.has(id)) {
+      err(errors, 'invalid_node', node?.id, 'node ids must be unique non-empty strings');
+      continue;
+    }
+    ids.add(id);
+  }
+
+  const compiled = new Map();
+
+  for (const node of rawNodes) {
+    const nodeId = node?.id;
+    if (!ids.has(nodeId)) continue;
+
+    const op = node.op;
+    if (!OP_SET.has(op) || !allowedOps.has(op)) {
+      err(errors, 'unknown_op', nodeId, `op ${JSON.stringify(op)} not allowed`);
+      continue;
+    }
+
+    const deps = node.deps === undefined ? [] : node.deps;
+    if (!Array.isArray(deps) || deps.some((d) => !isNonEmptyString(d))) {
+      err(errors, 'missing_ref', nodeId, 'deps must be an array of node ids');
+      continue;
+    }
+    for (const dep of deps) {
+      if (!ids.has(dep)) {
+        err(errors, 'missing_ref', nodeId, `dep ${dep} not in plan`);
+      }
+      if (dep === nodeId) {
+        err(errors, 'cycle', nodeId, 'self-dependency');
+      }
+    }
+
+    if (node.timeoutMs !== undefined && !isPositiveFinite(node.timeoutMs)) {
+      err(errors, 'unbounded_timeout', nodeId, 'timeoutMs must be a finite positive number');
+    }
+
+    let declaredEffects;
+    if (op === 'RUN') {
+      if (!isPositiveFinite(node.timeoutMs)) {
+        err(errors, 'unbounded_timeout', nodeId, 'RUN requires finite timeoutMs');
+      }
+      declaredEffects = validateSpec(node.spec, nodeId, errors);
+    }
+
+    if (op === 'WAIT_EVENT') {
+      if (!isPositiveFinite(node.timeoutMs)) {
+        err(errors, 'unbounded_timeout', nodeId, 'WAIT_EVENT requires finite timeoutMs');
+      }
+      validateSelector(node.selector, nodeId, errors);
+    }
+
+    let branches;
+    if (op === 'BRANCH') {
+      validateSelector(node.selector, nodeId, errors);
+      branches = node.branches;
+      if (!isPlainObject(branches) || Object.keys(branches).length === 0) {
+        err(errors, 'missing_ref', nodeId, 'BRANCH requires non-empty branches map');
+      } else {
+        for (const target of Object.values(branches)) {
+          if (!ids.has(target)) {
+            err(errors, 'missing_ref', nodeId, `branch target ${JSON.stringify(target)} not in plan`);
+          }
+        }
+      }
+    }
+
+    const retry = validateRetryPolicy(node.retry, nodeId, declaredEffects, errors);
+
+    const compiledNode = {
+      id: nodeId,
+      op,
+      deps: [...deps],
+      ...(retry ? { retry } : {}),
+      ...(node.selector !== undefined ? { selector: deepFreeze({ ...node.selector }) } : {}),
+      ...(node.timeoutMs !== undefined ? { timeoutMs: node.timeoutMs } : {}),
+      ...(node.spec !== undefined ? { spec: deepFreeze({ ...node.spec }) } : {}),
+      ...(branches !== undefined ? { branches: deepFreeze({ ...branches }) } : {}),
+    };
+    compiled.set(nodeId, compiledNode);
+  }
+
+  // Topological order (Kahn). Deterministic: process in input order.
+  const indegree = new Map();
+  const dependents = new Map();
+  for (const node of compiled.values()) {
+    indegree.set(node.id, node.deps.filter((d) => compiled.has(d)).length);
+    for (const dep of node.deps) {
+      if (!compiled.has(dep)) continue;
+      if (!dependents.has(dep)) dependents.set(dep, []);
+      dependents.get(dep).push(node.id);
+    }
+  }
+
+  const order = [];
+  const queue = rawNodes
+    .map((n) => n?.id)
+    .filter((id) => compiled.has(id) && indegree.get(id) === 0);
+  const entryNodes = [...queue];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    order.push(id);
+    for (const next of dependents.get(id) ?? []) {
+      indegree.set(next, indegree.get(next) - 1);
+      if (indegree.get(next) === 0) queue.push(next);
+    }
+  }
+  if (order.length < compiled.size) {
+    err(errors, 'cycle', undefined, 'dependency cycle detected');
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  const planVersion = createHash('sha256')
+    .update(canonicalize(order.map((id) => compiled.get(id))), 'utf8')
+    .digest('hex')
+    .slice(0, 16);
+
+  const nodes = new Map();
+  for (const id of order) {
+    nodes.set(id, deepFreeze(compiled.get(id)));
+  }
+
+  const plan = Object.freeze({
+    planVersion,
+    nodes: Object.freeze(nodes),
+    entryNodes: Object.freeze(entryNodes),
+    order: Object.freeze(order),
+  });
+  return { ok: true, plan };
+}

package/src/core/agentRuntime/promotion.js

@@ -0,0 +1,53 @@
+// src/core/agentRuntime/promotion.js
+// Pure caller-wait promotion decision (SPEC §2 G6-FR01/02, §4).
+// selectWaitPolicy(profile, operation, resources) → frozen
+//   { mode: 'foreground'|'handle', reason: string }
+// 'handle' is permitted only when the injected frozen DurationProfile records
+// the operation class as long-running (promoteAfterMs: number) AND
+// resources.pressure is not 'critical'. Every other input resolves
+// 'foreground' with a typed reason — never throws, never returns undefined.
+// Promotion changes caller waiting semantics only: this module performs no
+// I/O, reads no config, and never spawns/signals an OS process.
+
+const PROFILE_VERSION = 1;
+
+function isObj(v) {
+  return v != null && typeof v === 'object';
+}
+
+function policy(mode, reason) {
+  return Object.freeze({ mode, reason });
+}
+
+function foreground(reason) {
+  return policy('foreground', reason);
+}
+
+/**
+ * @param {object} profile   DurationProfile {version:1, classes:{<name>:{promoteAfterMs:number|null}}, fallback:'foreground'}
+ * @param {object} operation {class: string}
+ * @param {object} resources {pressure: 'normal'|'elevated'|'critical'}
+ * @returns {{mode:'foreground'|'handle', reason:string}} frozen
+ */
+export function selectWaitPolicy(profile, operation, resources) {
+  if (!isObj(profile) || !isObj(profile.classes)) return foreground('profile:absent');
+  if (profile.version !== PROFILE_VERSION) return foreground('profile:version');
+
+  const cls = isObj(operation) && typeof operation.class === 'string'
+    ? operation.class
+    : null;
+  const entry = cls != null ? profile.classes[cls] : undefined;
+  if (cls == null || !isObj(entry)) return foreground('class:unknown');
+
+  const pressure = isObj(resources) && typeof resources.pressure === 'string'
+    ? resources.pressure
+    : 'normal';
+  if (pressure === 'critical') return foreground('pressure:critical');
+
+  const promoteAfterMs = entry.promoteAfterMs;
+  if (typeof promoteAfterMs !== 'number' || !Number.isFinite(promoteAfterMs)) {
+    return foreground(`class:${cls}`);
+  }
+
+  return policy('handle', `class:${cls}:promoteAfterMs:${promoteAfterMs}`);
+}

package/src/core/agentRuntime/qualityComparison.js

@@ -0,0 +1,112 @@
+// Shadow quality-comparison harness (G5 / TASK-004, G5-FR06).
+// Pure replay: re-runs recorded evidence inputs through the completion-evidence
+// gate and compares against the recorded ledger evaluateCompletion() result.
+// No ledger writes, no VM spawns, no model calls — the gate evaluator is
+// injected (defaults to a dynamic import of ./completionGate.js so this module
+// lands safely when TASK-003 ships in the same wave).
+//
+// Ledger verdict semantics (template_project/.claude/ukit/runtime/execution-ledger.mjs):
+//   complete:true        → released (all evidence satisfied)
+//   continue:true        → blocked (unfinished work keeps recovering)
+//   continue:false (loud release, no complete flag) → released
+// Gate verdict semantics (SPEC §4):
+//   PASS → released; MORE_EVIDENCE | FIX_REQUIRED | FAILED → blocked.
+// Comparison kinds:
+//   agree        — both released or both blocked
+//   stricter     — ledger released where the gate blocks (counted as
+//                  falsePassBlocks: a ledger release the gate would have held)
+//   looser       — gate released where the ledger blocked
+//   unverifiable — recorded data insufficient; never guessed.
+
+export const VERDICT_KINDS = Object.freeze(['agree', 'stricter', 'looser', 'unverifiable']);
+
+const BLOCKING_VERDICTS = new Set(['MORE_EVIDENCE', 'FIX_REQUIRED', 'FAILED']);
+
+function gateReleased(verdict) {
+  return verdict === 'PASS';
+}
+
+// Ledger released = explicit completion OR a loud release without continuation.
+// `continue` must be a boolean; `complete` is optional.
+function ledgerVerdict(ledger) {
+  if (ledger == null || typeof ledger !== 'object') return null;
+  if (typeof ledger.continue !== 'boolean') return null;
+  const released = ledger.complete === true || ledger.continue === false;
+  return { complete: ledger.complete === true, continue: ledger.continue, released };
+}
+
+async function defaultEvaluator(evidence) {
+  const mod = await import('./completionGate.js');
+  return mod.evaluateCompletionEvidence(evidence);
+}
+
+function freezeRow(row) {
+  return Object.freeze({ ...row, ledger: Object.freeze({ ...row.ledger }) });
+}
+
+export async function runQualityShadow({ fixtures, evaluator } = {}) {
+  const evaluate = typeof evaluator === 'function' ? evaluator : defaultEvaluator;
+  const list = Array.isArray(fixtures) ? fixtures : [];
+
+  const rows = [];
+  const summary = { total: 0, agreements: 0, disagreements: 0, falsePassBlocks: 0, unverifiable: 0 };
+
+  for (const fx of list) {
+    const id = fx && fx.id != null ? String(fx.id) : `fixture-${rows.length}`;
+    const ledgerV = ledgerVerdict(fx && fx.ledger);
+    const evidence = fx && fx.evidence;
+
+    let verdict = null;
+    let evalOk = evidence != null;
+    if (evalOk) {
+      try {
+        const result = await evaluate(evidence);
+        verdict = result && typeof result.verdict === 'string' ? result.verdict : null;
+        evalOk = verdict === 'PASS' || BLOCKING_VERDICTS.has(verdict);
+      } catch {
+        evalOk = false;
+      }
+    }
+
+    let row;
+    if (!evalOk || ledgerV === null) {
+      row = freezeRow({
+        id,
+        gate: 'unverifiable',
+        ledger: { complete: ledgerV ? ledgerV.complete : false, continue: ledgerV ? ledgerV.continue : false },
+        agreement: false,
+        kind: 'unverifiable',
+      });
+      summary.unverifiable += 1;
+    } else {
+      const released = gateReleased(verdict);
+      let kind;
+      let agreement;
+      if (released === ledgerV.released) {
+        kind = 'agree';
+        agreement = true;
+      } else {
+        kind = ledgerV.released ? 'stricter' : 'looser';
+        agreement = false;
+      }
+      row = freezeRow({
+        id,
+        gate: verdict,
+        ledger: { complete: ledgerV.complete, continue: ledgerV.continue },
+        agreement,
+        kind,
+      });
+      if (agreement) {
+        summary.agreements += 1;
+      } else {
+        summary.disagreements += 1;
+        if (kind === 'stricter') summary.falsePassBlocks += 1;
+      }
+    }
+
+    rows.push(row);
+    summary.total += 1;
+  }
+
+  return { rows: Object.freeze(rows), summary: Object.freeze(summary) };
+}