@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/core/agentRuntime/eventStore.js

@@ -27,10 +27,13 @@
  */
 
 import { promises as fs } from 'node:fs';
+import crypto from 'node:crypto';
 import path from 'node:path';
 
 import { withFileLock } from '../fileOps.js';
 
+import { writeRunArtifact } from './artifacts.js';
+
 import {
   CONTRACT_VERSION,
   OPERATION_STATES,
@@ -569,3 +572,176 @@ export async function migrateJournal(fromDir, outDir, opts = {}) {
   }
   return { migrated: outputs.reduce((n, o) => n + (o.body ? o.body.trimEnd().split('\n').length : 0), 0) };
 }
+
+// --- C89-003: bounded run-artifact resolution (SPEC §5) --------------------
+// `resolveRunArtifact` is the ONLY path that turns an envelope/journal ref
+// back into bytes. Authorization and honesty rules:
+//   - caller must name the run it is entitled to (`caller.runId`); a ref
+//     tagged for another runId resolves `cross_run` and is never read;
+//   - `sensitivity:'sensitive'` refs resolve only for `caller.role:'owner'`
+//     (support/reviewer lanes get `redacted` — the ref may be named but the
+//     content never leaks);
+//   - the lexical path AND the physical realpath must stay inside runRoot —
+//     `..`, absolute escapes, and symlinks out of the run dir all resolve
+//     `path_escape` before a byte is read;
+//   - `sha256` is mandatory on the ref: without it the bytes are
+//     unverifiable, so the ref is `malformed_ref` rather than trusted;
+//   - success returns `{bytes, sha256}` (frozen signature); every failure is
+//     `{status:'unavailable', reason}` — typed, never a throw for ordinary
+//     missing/corrupt evidence so the caller can mark the result `partial`.
+
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+const unavailable = (reason) => ({ status: 'unavailable', reason });
+
+/**
+ * Resolve a bounded run-artifact ref for an authorized caller.
+ *
+ * @param {object} ref `{path, sha256, bytes?, runId?, truncated?, sensitivity?}`
+ * @param {object} scope `{runRoot, caller:{runId, role?}}`
+ * @returns {Promise<{bytes:Uint8Array, sha256:string, truncated?:boolean}
+ *           |{status:'unavailable', reason:string}>}
+ */
+export async function resolveRunArtifact(ref, { runRoot, caller } = {}) {
+  if (!isPlainRecord(caller) || !isNonEmptyString(caller.runId)) {
+    return unavailable('unauthorized');
+  }
+  if (!isPlainRecord(ref) || !isNonEmptyString(ref.path)) {
+    return unavailable('malformed_ref');
+  }
+  if (isNonEmptyString(ref.runId) && ref.runId !== caller.runId) {
+    return unavailable('cross_run');
+  }
+  if (ref.sensitivity === 'sensitive' && caller.role !== 'owner') {
+    return unavailable('redacted');
+  }
+  if (!SHA256_HEX_RE.test(ref.sha256)) {
+    return unavailable('malformed_ref');
+  }
+  if (typeof runRoot !== 'string' || runRoot === '') {
+    return unavailable('unavailable');
+  }
+  const root = path.resolve(runRoot);
+  const resolved = path.isAbsolute(ref.path)
+    ? path.resolve(ref.path)
+    : path.resolve(root, ref.path);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    return unavailable('path_escape');
+  }
+  let real;
+  try {
+    // realpath BOTH sides: tmp dirs and CI roots can themselves be reached
+    // through symlinks (/var → /private/var on macOS), so compare physical
+    // paths — this is also what catches a symlink inside the run dir
+    // pointing outside it.
+    const [realResolved, realRoot] = await Promise.all([
+      fs.realpath(resolved),
+      fs.realpath(root),
+    ]);
+    real = realResolved;
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+      return unavailable('path_escape');
+    }
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return unavailable('missing');
+    return unavailable('unreadable');
+  }
+  let bytes;
+  try {
+    bytes = await fs.readFile(real);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return unavailable('missing');
+    return unavailable('unreadable');
+  }
+  if (Number.isInteger(ref.bytes) && ref.bytes !== bytes.length) {
+    return unavailable('bytes_mismatch');
+  }
+  const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+  if (sha256 !== ref.sha256) {
+    return unavailable('checksum_mismatch');
+  }
+  const out = { bytes, sha256 };
+  if (ref.truncated === true) out.truncated = true;
+  return out;
+}
+
+// --- C89-006: context-manifest persistence (SPEC §7) ------------------------
+// `persistContextManifestRef` lands a built ContextManifest inside the
+// existing journal + artifact machinery: the full manifest goes to the run
+// directory as a checksummed artifact (original retrievable through
+// `resolveRunArtifact` for authorized callers) and a compact `context.manifest`
+// event records only the ref + selection counts in safePayload — item
+// bodies never ride the journal, so secrets stay behind the ref boundary.
+
+const CONTEXT_MANIFEST_EVENT = 'context.manifest';
+const CONTEXT_MANIFEST_PRODUCER = 'ukit-context-manifest';
+const MANIFEST_NAME_RE = /[^A-Za-z0-9._-]/g;
+
+/**
+ * Persist a ContextManifest as a run artifact and journal a compact
+ * `context.manifest` event against `operationId`.
+ *
+ * Commit order: artifact first, then the event — a crash between them leaves
+ * an orphaned artifact (harmless), never an event pointing at a missing
+ * original.
+ *
+ * @param {string} dir store root (same layout as appendEvent)
+ * @param {object} args `{manifest, operationId, runId?, eventId?, now?}`
+ * @returns {Promise<{seq:number, manifestRef:object}>}
+ * @throws {EventStoreError} 'malformed_manifest' before any I/O; journal
+ *   errors propagate typed from appendEvent.
+ */
+export async function persistContextManifestRef(dir, {
+  manifest,
+  operationId,
+  runId,
+  eventId,
+  now,
+} = {}) {
+  const isPlain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  if (!isPlain(manifest) || manifest.version !== 1 || !Array.isArray(manifest.items)
+    || typeof operationId !== 'string' || operationId === '') {
+    throw new EventStoreError('malformed_manifest', 'manifest must be a v1 ContextManifest');
+  }
+  const effectiveRunId = isNonEmptyString(runId)
+    ? runId
+    : (isNonEmptyString(manifest.runId) ? manifest.runId : operationId);
+
+  const bytes = Buffer.from(JSON.stringify(manifest), 'utf8');
+  const name = `context-manifest-${operationId.replace(MANIFEST_NAME_RE, '_')}.json`;
+  const artRef = await writeRunArtifact(dir, name, bytes);
+  // Tag the ref for this run so cross-run resolution is denied at the
+  // resolveRunArtifact boundary (never read, never leaked).
+  const manifestRef = { ...artRef, runId: effectiveRunId, version: 1 };
+
+  const cursor = await loadCursor(dir, operationId);
+  const event = {
+    eventId: isNonEmptyString(eventId)
+      ? eventId
+      : `ctx-manifest-${operationId}-${crypto.randomUUID()}`,
+    operationId,
+    seq: cursor.lastSeq + 1,
+    eventType: CONTEXT_MANIFEST_EVENT,
+    observedAt: typeof now === 'function' ? now() : new Date().toISOString(),
+    producerVersion: CONTEXT_MANIFEST_PRODUCER,
+    contractVersion: CONTRACT_VERSION,
+    privacyClass: 'internal',
+    artifactRefs: [artRef.path],
+    safePayload: {
+      runId: effectiveRunId,
+      mode: isNonEmptyString(manifest.mode) ? manifest.mode : 'unknown',
+      policyVersion: isNonEmptyString(manifest.policyVersion)
+        ? manifest.policyVersion : 'unknown',
+      itemCount: manifest.items.length,
+      includedCount: manifest.items.filter((i) => i && i.included === true).length,
+      excludedCount: manifest.items.filter((i) => i && i.included !== true).length,
+      tokensUsed: Number.isInteger(manifest.tokensUsed) ? manifest.tokensUsed : null,
+      manifestRef,
+    },
+  };
+  const { seq } = await appendEvent(dir, event);
+  return { seq, manifestRef };
+}