@ngockhoale/ukit 3.0.8 → 3.0.10

package/src/core/agentRuntime/adapters.js

@@ -0,0 +1,254 @@
+/**
+ * agentRuntime/adapters.js — decision-first-runtime G5 (DR-07), semantic
+ * output adapters (SPEC §2 G5-FR01/02/03, §4).
+ *
+ * `adaptOutput` converts raw tool output (async-iterable stream or chunk
+ * array) into contract-valid `SemanticEvent[]` (`eventType:
+ * 'tool.output.summary'`) whose `safePayload` stays under
+ * `MAX_SAFE_PAYLOAD_BYTES`. Raw output never enters an event payload:
+ * the full bytes are reachable only through `artifactStore` refs.
+ *
+ * Profiles (`TOOL_PROFILES`):
+ *   - `generic` — exit code + byte count + bounded tail digest (any tool).
+ *   - `vitest`  — test files/tests passed/failed counts, bounded failed
+ *     test names, duration.
+ *
+ * No fabricated PASS: when pass/fail cannot be established the summary
+ * emits `status: 'indeterminate'` — never `passed`. A vitest profile that
+ * cannot parse its input degrades to the generic event with a
+ * `parseFallback` marker (`parseStatus: 'parse_fallback'`).
+ *
+ * Secret-shaped lines (`SECRET=...`, `*_KEY=...`, `*_TOKEN=...`,
+ * `PASSWORD=...`, `AUTHORIZATION: ...`) are redacted before any payload
+ * or digest is built.
+ *
+ * Pure module: no imports of context/completionGate/qualityComparison.
+ * `now` and `artifactStore` are injectable for tests.
+ *
+ * `artifactStore` protocol (injected): `put(buffer)` →
+ * `Promise<string | { path: string }>`; the returned ref is recorded on
+ * `event.artifactRefs` and in the result `artifactRefs` list.
+ */
+
+import crypto from 'node:crypto';
+
+import {
+  validateSemanticEvent,
+  CONTRACT_VERSION,
+  MAX_SAFE_PAYLOAD_BYTES,
+} from './contract.js';
+
+export const TOOL_PROFILES = Object.freeze(['generic', 'vitest']);
+
+const PRODUCER_VERSION = '3.0.8';
+const PRIVACY_CLASS = 'internal';
+const EVENT_TYPE = 'tool.output.summary';
+
+/** Bounded tail digest: last 1 KiB of redacted text, line-sliced. */
+const TAIL_DIGEST_BYTES = 1024;
+/** Cap on failed test names surfaced in safePayload. */
+const MAX_FAILED_NAMES = 20;
+const MAX_FAILED_NAME_LEN = 200;
+
+const SECRET_LINE_RE =
+  /^(?:.*\b)?(?:SECRET|PASSWORD|TOKEN|API_KEY|PRIVATE_KEY|ACCESS_KEY|AUTH(?:ORIZATION)?|CREDENTIAL)[\w.-]*\s*[:=][^\n]*$/i;
+const SECRET_INLINE_RE =
+  /\b(?:SECRET|PASSWORD|TOKEN|API_KEY|PRIVATE_KEY|ACCESS_KEY|AUTHORIZATION|CREDENTIAL)[\w.-]*\s*[:=]\s*\S+/gi;
+
+function redactSecrets(text) {
+  return text
+    .split('\n')
+    .map((line) =>
+      SECRET_LINE_RE.test(line.trim()) ? '[REDACTED]' : line,
+    )
+    .join('\n')
+    .replace(SECRET_INLINE_RE, '[REDACTED]');
+}
+
+async function collectInput({ stream, chunks }) {
+  const parts = [];
+  const source = chunks ?? stream;
+  if (source == null) return Buffer.alloc(0);
+  if (Array.isArray(source)) {
+    for (const c of source) {
+      parts.push(Buffer.isBuffer(c) ? c : Buffer.from(String(c)));
+    }
+    return Buffer.concat(parts);
+  }
+  for await (const c of source) {
+    parts.push(Buffer.isBuffer(c) ? c : Buffer.from(String(c)));
+  }
+  return Buffer.concat(parts);
+}
+
+function makeEvent(operationId, seq, safePayload, artifactRefs, now) {
+  return {
+    eventId: `${operationId}-output-${seq}`,
+    operationId,
+    seq,
+    eventType: EVENT_TYPE,
+    observedAt: now(),
+    producerVersion: PRODUCER_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    privacyClass: PRIVACY_CLASS,
+    artifactRefs,
+    safePayload,
+  };
+}
+
+function tailDigest(text) {
+  const buf = Buffer.from(text, 'utf8');
+  const tail = buf.length > TAIL_DIGEST_BYTES ? buf.subarray(buf.length - TAIL_DIGEST_BYTES) : buf;
+  const str = tail.toString('utf8').replace(/\n{3,}/g, '\n\n').trim();
+  // Drop a partial first line.
+  const idx = str.indexOf('\n');
+  return idx >= 0 ? str.slice(idx + 1) : str;
+}
+
+function genericStatus(exitCode) {
+  if (!Number.isInteger(exitCode)) return 'indeterminate';
+  return exitCode === 0 ? 'passed' : 'failed';
+}
+
+function genericPayload({ raw, redacted, exitCode, parseFallback, profile }) {
+  return {
+    profile,
+    status: genericStatus(exitCode),
+    exitCode: Number.isInteger(exitCode) ? exitCode : null,
+    byteCount: raw.length,
+    sha256: crypto.createHash('sha256').update(raw).digest('hex'),
+    tailDigest: tailDigest(redacted),
+    ...(parseFallback ? { parseFallback: true } : {}),
+  };
+}
+
+const RE_FILES =
+  /Test Files\s+(?:(\d+)\s+failed\s*\|)?\s*(\d+)\s+passed(?:\s*\(\d+\))?/;
+const RE_TESTS =
+  /Tests\s+(?:(\d+)\s+failed\s*\|)?\s*(\d+)\s+passed(?:\s*\(\d+\))?/;
+const RE_DURATION = /Duration\s+([\d.]+)\s*(ms|s)/;
+const RE_FAIL_NAME = /^\s*FAIL\s+(.+?)\s*$/gm;
+
+function parseVitest(redacted) {
+  const files = RE_FILES.exec(redacted);
+  const tests = RE_TESTS.exec(redacted);
+  if (!files || !tests) return null;
+
+  const filesFailed = files[1] ? Number(files[1]) : 0;
+  const filesPassed = Number(files[2]);
+  const testsFailed = tests[1] ? Number(tests[1]) : 0;
+  const testsPassed = Number(tests[2]);
+
+  const dur = RE_DURATION.exec(redacted);
+  const durationMs = dur
+    ? Math.round(Number(dur[1]) * (dur[2] === 's' ? 1000 : 1))
+    : null;
+
+  const failedNames = [];
+  for (const m of redacted.matchAll(RE_FAIL_NAME)) {
+    if (failedNames.length >= MAX_FAILED_NAMES) break;
+    const name = m[1].trim().slice(0, MAX_FAILED_NAME_LEN);
+    if (name) failedNames.push(name);
+  }
+
+  return {
+    profile: 'vitest',
+    status: testsFailed > 0 || filesFailed > 0 ? 'failed' : 'passed',
+    filesPassed,
+    filesFailed,
+    testsPassed,
+    testsFailed,
+    failedNames,
+    durationMs,
+  };
+}
+
+async function storeArtifact(artifactStore, buf) {
+  if (!artifactStore || typeof artifactStore.put !== 'function') return [];
+  try {
+    const ref = await artifactStore.put(buf);
+    const out = typeof ref === 'string' ? ref : ref?.path;
+    return out ? [out] : [];
+  } catch {
+    // Artifact persistence failure must not fabricate or drop the verdict —
+    // emit the bounded event without a ref.
+    return [];
+  }
+}
+
+/**
+ * @param {object} args
+ * @param {AsyncIterable<Buffer|string>} [args.stream] async-iterable output.
+ * @param {Array<Buffer|string>} [args.chunks] buffered output chunks.
+ * @param {string} [args.toolProfile] 'generic'|'vitest' (unknown → generic).
+ * @param {string} args.operationId
+ * @param {number} [args.exitCode] child exit code when known.
+ * @param {() => string} [args.now] injectable clock (ISO string).
+ * @param {{put: (buf: Buffer) => Promise<string|{path:string}>}} [args.artifactStore]
+ * @returns {Promise<{events: object[], artifactRefs: string[],
+ *   parseStatus: 'parsed'|'generic'|'parse_fallback'}>}
+ */
+export async function adaptOutput({
+  stream,
+  chunks,
+  toolProfile = 'generic',
+  operationId,
+  exitCode,
+  now = () => new Date().toISOString(),
+  artifactStore,
+} = {}) {
+  const raw = await collectInput({ stream, chunks });
+  const redacted = redactSecrets(raw.toString('utf8'));
+  const artifactRefs = await storeArtifact(artifactStore, raw);
+
+  const profile = TOOL_PROFILES.includes(toolProfile) ? toolProfile : 'generic';
+
+  let safePayload;
+  let parseStatus;
+  if (profile === 'vitest') {
+    const parsed = parseVitest(redacted);
+    if (parsed) {
+      safePayload = parsed;
+      parseStatus = 'parsed';
+    } else {
+      safePayload = genericPayload({
+        raw,
+        redacted,
+        exitCode,
+        parseFallback: true,
+        profile: 'generic',
+      });
+      parseStatus = 'parse_fallback';
+    }
+  } else {
+    safePayload = genericPayload({
+      raw,
+      redacted,
+      exitCode,
+      parseFallback: false,
+      profile: 'generic',
+    });
+    parseStatus = 'generic';
+  }
+
+  const event = makeEvent(
+    String(operationId ?? 'unknown'),
+    0,
+    safePayload,
+    artifactRefs,
+    now,
+  );
+
+  // Defensive: never emit an unvalidated envelope.
+  const v = validateSemanticEvent(event);
+  if (!v.ok) {
+    event.safePayload = {
+      profile: 'generic',
+      status: 'indeterminate',
+      byteCount: raw.length,
+      shrinkReason: v.code,
+    };
+  }
+
+  return { events: [event], artifactRefs, parseStatus };
+}

package/src/core/agentRuntime/artifacts.js

@@ -0,0 +1,192 @@
+/**
+ * agentRuntime/artifacts.js — decision-first-runtime G2 bounded output
+ * artifact writer (SPEC §2 G2-FR02/G2-FR09, §4).
+ *
+ * Streams child stdout/stderr into bounded artifact files under `dir`:
+ * per-stream and total byte caps (over-cap input is dropped, the file is
+ * marked `truncated:true`), SHA-256 over the bytes actually written, and
+ * typed `ArtifactError` on write failure (ENOSPC/EIO) — never an unhandled
+ * rejection. Pure I/O module: no policy, no transitions.
+ *
+ * Interface (frozen this cycle):
+ *   createArtifactWriter(dir, limits, deps?) -> writer
+ *   writer.open(operationId) -> { stdout, stderr, close() }
+ *   close() -> Promise<ArtifactRef[]>
+ *   ref: { path, sha256, bytes, truncated, stream, error? }
+ *
+ * `deps` exists for fault injection in tests: { openImpl, writeImpl,
+ * fsyncImpl, closeImpl, mkdirImpl } default to fs.promises equivalents.
+ */
+
+import { promises as fs } from 'node:fs';
+import { Writable } from 'node:stream';
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+export class ArtifactError extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = 'ArtifactError';
+    this.code = code;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+const DEFAULT_LIMITS = Object.freeze({
+  maxOutputBytes: 4 * 1024 * 1024,
+  maxStderrBytes: 4 * 1024 * 1024,
+  maxTotalBytes: Infinity,
+});
+
+const STREAMS = ['stdout', 'stderr'];
+const PER_STREAM_LIMIT = { stdout: 'maxOutputBytes', stderr: 'maxStderrBytes' };
+
+function toArtifactError(err) {
+  if (err instanceof ArtifactError) return err;
+  const code = err && err.code === 'ENOSPC' ? 'enospc' : 'artifact_write_failed';
+  return new ArtifactError(
+    code,
+    `artifact write failed: ${err?.message ?? err}`,
+    err,
+  );
+}
+
+export function createArtifactWriter(dir, limits = {}, deps = {}) {
+  const lim = { ...DEFAULT_LIMITS, ...limits };
+  const d = {
+    mkdirImpl: deps.mkdirImpl ?? ((p) => fs.mkdir(p, { recursive: true })),
+    openImpl: deps.openImpl ?? ((p) => fs.open(p, 'w')),
+    writeImpl: deps.writeImpl ?? ((h, b) => h.write(b)),
+    fsyncImpl: deps.fsyncImpl ?? ((h) => h.fsync()),
+    closeImpl: deps.closeImpl ?? ((h) => h.close()),
+  };
+
+  function open(operationId) {
+
+    // Shared total-bytes budget across both streams.
+    let totalBytes = 0;
+
+    const streams = {};
+    for (const stream of STREAMS) {
+      const filePath = path.join(dir, `${operationId}.${stream}.log`);
+      const cap = lim[PER_STREAM_LIMIT[stream]];
+      const state = {
+        stream,
+        path: filePath,
+        handle: null,
+        handleReady: null,
+        hash: crypto.createHash('sha256'),
+        bytes: 0,
+        truncated: false,
+        error: null,
+        finished: null,
+      };
+
+      state.handleReady = (async () => {
+        try {
+          await d.mkdirImpl(dir);
+          state.handle = await d.openImpl(filePath);
+        } catch (err) {
+          throw toArtifactError(err);
+        }
+      })();
+      // Mark handled so a failed open never surfaces as an unhandled
+      // rejection before write()/close() await it; awaiters still reject.
+      state.handleReady.catch(() => {});
+
+      const writable = new Writable({
+        async write(chunk, _enc, cb) {
+          try {
+            await state.handleReady;
+            const perStreamRoom = Math.max(0, cap - state.bytes);
+            const totalRoom = Math.max(0, lim.maxTotalBytes - totalBytes);
+            const room = Math.min(perStreamRoom, totalRoom);
+            if (room <= 0) {
+              state.truncated = true;
+              cb();
+              return;
+            }
+            const slice =
+              chunk.length > room ? chunk.subarray(0, room) : chunk;
+            if (chunk.length > room) state.truncated = true;
+            try {
+              await d.writeImpl(state.handle, slice);
+            } catch (err) {
+              throw toArtifactError(err);
+            }
+            state.hash.update(slice);
+            state.bytes += slice.length;
+            totalBytes += slice.length;
+            cb();
+          } catch (err) {
+            cb(err instanceof ArtifactError ? err : toArtifactError(err));
+          }
+        },
+      });
+
+      // Keep a record of the first stream error without leaving an unhandled
+      // 'error' event (Writable emits asynchronously). Consumers attaching
+      // their own listener (pipeline) still receive it.
+      state.finished = new Promise((resolve) => {
+        writable.on('error', (err) => {
+          if (!state.error) {
+            state.error =
+              err instanceof ArtifactError ? err : toArtifactError(err);
+          }
+          resolve();
+        });
+        writable.on('finish', () => resolve());
+      });
+
+      streams[stream] = { writable, state };
+    }
+
+    async function close() {
+      const refs = [];
+      for (const stream of STREAMS) {
+        const { writable, state } = streams[stream];
+        if (!writable.destroyed && !writable.writableEnded) {
+          writable.end();
+        }
+        await state.finished;
+        // Whatever was written must be durable before refs are returned —
+        // fsync + close even when a write error was recorded (partial file).
+        try {
+          await state.handleReady;
+          if (state.handle) {
+            try {
+              await d.fsyncImpl(state.handle);
+            } catch (err) {
+              if (!state.error) state.error = toArtifactError(err);
+            }
+            try {
+              await d.closeImpl(state.handle);
+            } catch (err) {
+              if (!state.error) state.error = toArtifactError(err);
+            }
+          }
+        } catch (err) {
+          // open itself failed — nothing to fsync; record the typed error.
+          if (!state.error) {
+            state.error =
+              err instanceof ArtifactError ? err : toArtifactError(err);
+          }
+        }
+        const ref = {
+          path: state.path,
+          sha256: state.hash.digest('hex'),
+          bytes: state.bytes,
+          truncated: state.truncated,
+          stream: state.stream,
+        };
+        if (state.error) ref.error = state.error;
+        refs.push(ref);
+      }
+      return refs;
+    }
+
+    return { stdout: streams.stdout.writable, stderr: streams.stderr.writable, close };
+  }
+
+  return { open };
+}

package/src/core/agentRuntime/completionGate.js

@@ -0,0 +1,176 @@
+// Deterministic completion-evidence evaluator (G5 / TASK-003).
+// Pure module: no I/O, no runtimeConfig reads, no adapter/context imports.
+// Maps requirements × checks × operationRefs (+ optional G4 vmStatus,
+// optional modelJudgment) to a frozen CompletionVerdict with precedence
+// FAILED > FIX_REQUIRED > MORE_EVIDENCE > PASS.
+//
+// The installed execution-ledger.mjs remains the completion authority —
+// its evaluateCompletion result shape may be fed here as a fixture, but it
+// is never imported and never edited. A model-review layer may only ask for
+// more evidence: `modelJudgment` is recorded on the verdict and can
+// *downgrade* a PASS to MORE_EVIDENCE, but never converts FAIL→PASS.
+
+import { isTerminal } from './contract.js';
+
+export const COMPLETION_VERDICTS = Object.freeze([
+  'PASS',
+  'MORE_EVIDENCE',
+  'FIX_REQUIRED',
+  'FAILED',
+]);
+
+// vm terminal states that mean the run itself failed — not merely unproven.
+const VM_FAILED_STATES = new Set(['failed', 'cancelled']);
+// vm states that mean evidence is unusable until recovery completes.
+const VM_FIX_STATES = new Set(['recovery_required']);
+
+const PASS_STATUSES = new Set(['passed', 'pass', 'ok', 'success']);
+const FAIL_STATUSES = new Set(['failed', 'fail', 'error']);
+const WARN_STATUSES = new Set(['warning', 'warn', 'skipped', 'indeterminate']);
+
+function normStatus(status) {
+  const s = typeof status === 'string' ? status.toLowerCase() : '';
+  if (PASS_STATUSES.has(s)) return 'passed';
+  if (FAIL_STATUSES.has(s)) return 'failed';
+  if (WARN_STATUSES.has(s)) return 'warning';
+  return 'unproven';
+}
+
+// A check proves a requirement when ids match: check.requirementId → req.id,
+// or req.checkId → check.checkId. Either direction is accepted so callers may
+// key evidence from whichever side they own.
+function checkFor(req, checks) {
+  return checks.find(
+    (c) =>
+      c != null
+      && typeof c === 'object'
+      && ((typeof c.requirementId === 'string' && c.requirementId === req.id)
+        || (typeof req.checkId === 'string' && c.checkId === req.checkId)),
+  );
+}
+
+// Evidence is stale when it was produced against a different patch/head than
+// the operation now carries. Stale ≠ missing: the work must be re-verified,
+// which is rework (FIX_REQUIRED), not just more evidence.
+function isStale(check, operationRefs) {
+  if (!check || !operationRefs || typeof operationRefs !== 'object') return false;
+  if (operationRefs.patchId != null && check.patchId != null
+    && check.patchId !== operationRefs.patchId) return true;
+  if (operationRefs.head != null && check.head != null
+    && check.head !== operationRefs.head) return true;
+  return false;
+}
+
+export function evaluateCompletionEvidence({
+  requirements,
+  checks,
+  operationRefs,
+  vmStatus,
+  modelJudgment,
+  now,
+} = {}) {
+  const nowMs = typeof now === 'number' ? now : Date.now();
+  const reqs = Array.isArray(requirements) ? requirements : [];
+  const checkList = Array.isArray(checks) ? checks : [];
+  const refs = operationRefs != null && typeof operationRefs === 'object'
+    ? operationRefs
+    : null;
+
+  const satisfied = [];
+  const missing = [];
+  const unprovenRequirements = [];
+  const failedChecks = [];
+  const staleEvidence = [];
+  const warnings = [];
+
+  for (const req of reqs) {
+    const reqId = req != null && req.id != null ? String(req.id) : 'unknown';
+    const check = checkFor(req, checkList);
+
+    if (!check) {
+      missing.push(reqId);
+      unprovenRequirements.push(reqId);
+      continue;
+    }
+
+    const status = normStatus(check.status);
+    const stale = isStale(check, refs);
+
+    if (stale) {
+      staleEvidence.push(Object.freeze({
+        checkId: check.checkId != null ? String(check.checkId) : reqId,
+        evidenceRef: check.evidenceRef != null ? String(check.evidenceRef) : null,
+        patchId: check.patchId != null ? check.patchId : null,
+      }));
+      unprovenRequirements.push(reqId);
+      continue;
+    }
+
+    if (status === 'failed') {
+      failedChecks.push(Object.freeze({
+        checkId: check.checkId != null ? String(check.checkId) : reqId,
+        evidenceRef: check.evidenceRef != null ? String(check.evidenceRef) : null,
+      }));
+      continue;
+    }
+
+    if (status === 'warning') {
+      warnings.push(reqId);
+      unprovenRequirements.push(reqId);
+      continue;
+    }
+
+    if (status === 'passed') {
+      satisfied.push(reqId);
+      continue;
+    }
+
+    unprovenRequirements.push(reqId);
+  }
+
+  // vm state never permits PASS: terminal failure → FAILED, recovery →
+  // rework, any other non-terminal state → the operation is still in flight
+  // so evidence cannot yet prove completion.
+  const vmFailed = typeof vmStatus === 'string' && VM_FAILED_STATES.has(vmStatus);
+  const vmRecovery = typeof vmStatus === 'string' && VM_FIX_STATES.has(vmStatus);
+  const vmInFlight = typeof vmStatus === 'string'
+    && !vmFailed && !vmRecovery && !isTerminal(vmStatus) && vmStatus !== 'completed';
+
+  // Non-zero exit status = failed verification run → rework required.
+  const exitFailed = refs != null
+    && typeof refs.exitStatus === 'number'
+    && refs.exitStatus !== 0;
+
+  let verdict = 'PASS';
+  if (missing.length > 0 || unprovenRequirements.length > 0 || vmInFlight) {
+    verdict = 'MORE_EVIDENCE';
+  }
+  if (staleEvidence.length > 0 || exitFailed || vmRecovery) {
+    verdict = 'FIX_REQUIRED';
+  }
+  if (failedChecks.length > 0 || vmFailed) {
+    verdict = 'FAILED';
+  }
+
+  // modelJudgment may only request more evidence, never promote.
+  const judgment = modelJudgment != null
+    ? (typeof modelJudgment === 'string' ? modelJudgment : String(modelJudgment))
+    : null;
+  if (verdict === 'PASS' && judgment != null && judgment !== 'pass') {
+    verdict = 'MORE_EVIDENCE';
+  }
+
+  return Object.freeze({
+    verdict,
+    satisfied: Object.freeze(satisfied),
+    missing: Object.freeze(missing),
+    failedChecks: Object.freeze(failedChecks),
+    unprovenRequirements: Object.freeze(unprovenRequirements),
+    staleEvidence: Object.freeze(staleEvidence),
+    warnings: Object.freeze(warnings),
+    patchId: refs != null && refs.patchId != null ? refs.patchId : undefined,
+    vmStatus: typeof vmStatus === 'string' ? vmStatus : undefined,
+    modelJudgment: judgment != null ? judgment : undefined,
+    evaluatedAt: nowMs,
+  });
+}