@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/dist/lib/trace-projection.js

@@ -3,18 +3,22 @@
  * Zones: causal evidence merge, source filtering, redaction, deterministic ordering
  * Owns public Trace items; source journals and session parsing remain in their domains.
  */
+import { createHash } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import * as ControlProjection from "./control-projection.js";
 import * as ExecutionSessions from "./execution-sessions.js";
 import * as Limits from "./limits.js";
-import { resolveArtifactManifest, } from "./runs-artifacts.js";
+import { createRunRecipeEvidenceRedactor } from "./recipe-projection.js";
+import { describeRunArtifactReferences, observeRunArtifactReference, } from "./runs-artifacts.js";
 import * as RunsControls from "./runs-controls.js";
+import { isRunStopResultCapture } from "./runs-outcomes.js";
 import { tailFile } from "./runs-status.js";
 import * as RunsTrace from "./runs-trace.js";
 import * as SessionEvidence from "./session-evidence.js";
 import { readJsonFileResilient, } from "./state-readers.js";
 export const TRACE_ITEM_SEQUENCE = Symbol("trace-item-sequence");
+export const TRACE_ITEM_CHRONOLOGY = Symbol("trace-item-chronology");
 const LIFECYCLE_PREFIXES = ["run.", "command."];
 const SOURCE_LIMIT = 100;
 const SOURCE_RANK = {
@@ -49,6 +53,69 @@ function compareTraceItems(left, right) {
     return SOURCE_RANK[right.item.source] - SOURCE_RANK[left.item.source] ||
         right.item.id.localeCompare(left.item.id);
 }
+// Read-local metadata only; availability is not an original-history, issuer or work capability.
+class TraceChronologyBuilder {
+    entries = [];
+    bytes = 2;
+    reason;
+    unavailable(reason) { this.reason ??= reason; this.entries.length = 0; }
+    add(item, sourceKey, ordinal) {
+        if (this.reason)
+            return;
+        if (typeof item.id !== "string" || !item.id) {
+            this.unavailable("metadata_unavailable");
+            return;
+        }
+        const projected = redact([item.id, item.ts]);
+        if (projected[0] !== item.id || projected[1] !== item.ts) {
+            this.unavailable("metadata_private");
+            return;
+        }
+        if (typeof item.ts !== "string" || item.ts.length !== 24 || !Number.isFinite(Date.parse(item.ts)) || new Date(item.ts).toISOString() !== item.ts) {
+            this.unavailable("timestamp_unavailable");
+            return;
+        }
+        const entry = { item: { id: item.id, ts: item.ts, source: item.source }, sourceKey, ordinal };
+        this.bytes += Buffer.byteLength(JSON.stringify(entry)) + Number(this.entries.length > 0);
+        if (this.bytes > Limits.TRACE_JOURNAL_MAX_BYTES) {
+            this.unavailable("metadata_too_large");
+            return;
+        }
+        this.entries.push(entry);
+    }
+    finish(items) {
+        const ranks = new Map();
+        if (!this.reason) {
+            this.entries.sort(compareTraceItems);
+            for (const [index, key] of this.entries.entries()) {
+                if (ranks.has(key.item.id)) {
+                    this.unavailable("metadata_ambiguous");
+                    break;
+                }
+                ranks.set(key.item.id, { key, ordinal: this.entries.length - index });
+            }
+        }
+        if (!this.reason && items.some(({ item, sourceKey }) => {
+            const entry = ranks.get(item.id);
+            return !entry || entry.key.sourceKey !== sourceKey || entry.key.item.ts !== item.ts || entry.key.item.source !== item.source;
+        }))
+            this.unavailable("metadata_unavailable");
+        // The legacy same-source ordinal/cross-source rank tie rule is not always a total order.
+        if (!this.reason)
+            for (const source of ["all", ...Object.keys(SOURCE_RANK)]) {
+                let previous = Infinity;
+                const view = items.filter(({ item }) => source === "all" || item.source === source).sort(compareTraceItems);
+                if (view.some(({ item }) => { const rank = ranks.get(item.id).ordinal; const mismatch = rank >= previous; previous = rank; return mismatch; })) {
+                    this.unavailable("metadata_ambiguous");
+                    break;
+                }
+            }
+        for (const { item } of items)
+            Object.defineProperty(item, TRACE_ITEM_CHRONOLOGY, { value: Object.freeze(this.reason
+                    ? { state: "unavailable", basis: "recorded_observations", reason: this.reason }
+                    : { state: "available", basis: "recorded_observations", ordinal: ranks.get(item.id).ordinal, total: ranks.size }) });
+    }
+}
 function latestControlTimestamp(control) {
     return (control.failed_at ??
         control.handled_at ??
@@ -83,9 +150,16 @@ function controlDiagnosticItems(diagnostics) {
         },
     }));
 }
-function traceEventItems(stateDir) {
-    const read = RunsTrace.readRunTraceJournal(stateDir);
+function traceEventItems(read, recipe, projectEvidence = recipe ? createRunRecipeEvidenceRedactor(recipe) : redact, chronology) {
     const summary = RunsTrace.summarizeRunTraceJournal(read);
+    if (!summary.history_complete)
+        chronology?.unavailable("history_incomplete");
+    if (chronology)
+        for (const { event, ordinal } of read.events) {
+            if (redact(event.kind) !== event.kind)
+                chronology.unavailable("metadata_private");
+            chronology.add({ id: event.id, ts: event.ts, source: sourceForEvent(event) }, "trace", ordinal);
+        }
     const sequenceOffset = summary.dropped_events + Math.max(0, summary.compactions_total - 1);
     const retained = read.events.slice(-SOURCE_LIMIT);
     const projected = retained.map(({ event, ordinal }) => ordered({
@@ -93,9 +167,9 @@ function traceEventItems(stateDir) {
         ts: event.ts,
         source: sourceForEvent(event),
         kind: event.kind,
-        summary: event.summary ?? event.kind,
+        summary: projectEvidence(event.summary ?? event.kind),
         ...(event.level ? { level: event.level } : {}),
-        detail: redact({
+        detail: projectEvidence({
             ...(event.attention ? { attention: event.attention } : {}),
             ...(event.data !== undefined ? { data: event.data } : {}),
         }),
@@ -119,8 +193,34 @@ function traceEventItems(stateDir) {
     }
     return [...projected, ...diagnostics];
 }
-function controlItems(stateDir) {
+function controlItems(stateDir, chronology) {
     const read = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    if (read.diagnostics.length)
+        chronology?.unavailable("metadata_unavailable");
+    let terminal = 0;
+    if (chronology)
+        for (const [index, raw] of read.records.entries()) {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                chronology.unavailable("metadata_unavailable");
+                continue;
+            }
+            const record = raw;
+            if (![record.id, record.action, record.run_instance_id, record.queued_at].every(value => typeof value === "string") || !record.id || !record.run_instance_id ||
+                !["queued", "delivered", "claimed", "handled", "failed"].includes(record.status)) {
+                chronology.unavailable("metadata_unavailable");
+                continue;
+            }
+            if (record.status === "handled" || record.status === "failed")
+                terminal++;
+            const metadata = { id: record.id, action: record.action, run_instance_id: record.run_instance_id, queued_at: record.queued_at, status: record.status,
+                ...Object.fromEntries(["failed_at", "handled_at", "claimed_at", "delivered_at"].flatMap(field => typeof raw[field] === "string" ? [[field, raw[field]]] : [])) };
+            const value = ControlProjection.projectRunControl(metadata);
+            if (value.id !== record.id || latestControlTimestamp(value) !== latestControlTimestamp(record))
+                chronology.unavailable("metadata_unavailable");
+            chronology.add({ id: `control:${value.id}`, ts: latestControlTimestamp(value), source: "control" }, "control", index + 1);
+        }
+    if (terminal >= Limits.RUN_CONTROL_TERMINAL_LIMIT)
+        chronology?.unavailable("control_history_unproven");
     const start = Math.max(0, read.records.length - SOURCE_LIMIT);
     const projected = read.records.slice(start).map((control, index) => {
         const value = ControlProjection.projectRunControl(control);
@@ -139,14 +239,41 @@ function controlItems(stateDir) {
         ...controlDiagnosticItems(read.diagnostics).map((item, index) => ordered(item, "control", read.records.length + index + 1)),
     ];
 }
-function agentItems(stateDir) {
-    return ExecutionSessions.readExecutionTurns(stateDir)
-        .slice(-SOURCE_LIMIT)
-        .map((turn) => {
+function agentIdentity(commandId, sessionFile, index, admitted) {
+    const namespace = redact([commandId, sessionFile]);
+    const identity = namespace[0] === commandId && namespace[1] === sessionFile ? admitted : undefined;
+    const basis = identity?.basis ?? "legacy";
+    const key = createHash("sha256").update(JSON.stringify([
+        "agent-turn-v1", ...namespace, identity ?? { basis, ordinal: index },
+    ])).digest("hex");
+    return `agent:${basis}:${key}`;
+}
+function agentItems(stateDir, chronology) {
+    const turns = ExecutionSessions.readExecutionTurns(stateDir);
+    const metadata = turns[ExecutionSessions.EXECUTION_CHRONOLOGY];
+    if (!metadata || metadata.state !== "available")
+        chronology?.unavailable("metadata_unavailable");
+    else
+        for (const entry of metadata.entries)
+            chronology?.add({
+                id: agentIdentity(entry.commandId, entry.sessionFile, entry.ordinal, entry.identity), ts: entry.timestamp, source: "agent",
+            }, "agent", entry.ordinal);
+    return turns.slice(-SOURCE_LIMIT).map((turn) => {
         const text = turn.assistantText ?? turn.userText ?? "Agent turn";
-        const summary = text.replaceAll(/\s+/g, " ").trim().slice(0, 160);
+        const compact = text.replaceAll(/\s+/g, " ").trim();
+        let summary = compact;
+        if (Buffer.from(compact).toString("utf8") !== compact) {
+            summary = "Agent turn [omitted: unknown] (malformed retained text)";
+        }
+        else if (compact.length > 160) {
+            const last = compact.charCodeAt(159), next = compact.charCodeAt(160);
+            const end = last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff ? 159 : 160;
+            // Only this normalized retained suffix supplies a count; upstream source loss stays unknown.
+            const omitted = Array.from(compact.slice(end)).length;
+            summary = `${compact.slice(0, end)}… [omitted: ${omitted} chars] from normalized retained turn; upstream [omitted: unknown]`;
+        }
         return ordered({
-            id: `agent:${turn.commandId}:${turn.sessionFile}:${turn.index}`,
+            id: agentIdentity(turn.commandId, turn.sessionFile, turn.index, turn[SessionEvidence.SESSION_TURN_IDENTITY]),
             ts: turn.timestamp ?? new Date(0).toISOString(),
             source: "agent",
             kind: "agent.turn",
@@ -184,51 +311,73 @@ function resultItems(stateDir) {
     }
     const stat = statSync(path);
     const failed = Number(read.value.code ?? 0) !== 0;
+    const captured = isRunStopResultCapture(read.value);
     return [ordered({
             id: "process:result",
             ts: typeof read.value.completedAt === "string"
                 ? read.value.completedAt
                 : stat.mtime.toISOString(),
             source: "process",
-            kind: failed ? "process.failed" : "process.result",
-            summary: failed ? "Run process failed" : "Run process completed",
+            kind: captured ? "process.result_captured" : failed ? "process.failed" : "process.result",
+            summary: captured ? "Workload result captured while stopping" : failed ? "Run process failed" : "Run process completed",
             ...(failed ? { level: "error" } : {}),
             detail: redact(read.value),
         }, "process:result", 1, 2), ...diagnosticItems(read.diagnostics).map((item, index) => ordered(item, "process:result", index + 2))];
 }
-function artifactItems(stateDir, declarations) {
-    const manifest = resolveArtifactManifest(declarations);
-    if (!manifest)
+function artifactItems(stateDir, declarations, chronology) {
+    const described = describeRunArtifactReferences(declarations, process.cwd());
+    if (described.state !== "available") {
+        if (declarations)
+            chronology?.unavailable("metadata_unavailable");
         return [];
-    return Object.entries(manifest).slice(0, SOURCE_LIMIT).map(([name, artifact], index) => ordered({
-        id: `artifact:${name}`,
-        ts: artifact.exists && existsSync(artifact.path)
-            ? statSync(artifact.path).mtime.toISOString()
-            : new Date(0).toISOString(),
-        source: "artifact",
-        kind: artifact.exists ? "artifact.ready" : "artifact.missing",
-        summary: `${name}: ${artifact.exists ? "ready" : "missing"}`,
-        ...(artifact.required && !artifact.exists ? { level: "warning" } : {}),
-        detail: redact({
-            exists: artifact.exists,
-            path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
-            required: artifact.required,
-            ...(artifact.size !== undefined ? { size: artifact.size } : {}),
-        }),
-    }, "artifact", index + 1, index));
+    }
+    if (described.references.length > SOURCE_LIMIT)
+        chronology?.unavailable("metadata_unavailable");
+    return described.references.slice(0, SOURCE_LIMIT).map((reference, index) => {
+        const artifact = observeRunArtifactReference(reference);
+        const exists = artifact.availability === "available";
+        if (!artifact.modified_at)
+            chronology?.unavailable("timestamp_unavailable");
+        return ordered({
+            id: `artifact:${artifact.name}`,
+            ts: artifact.modified_at ?? new Date(0).toISOString(),
+            source: "artifact",
+            kind: exists ? "artifact.ready" : artifact.availability === "missing" ? "artifact.missing" : "artifact.unavailable",
+            summary: redact(`${artifact.name}: ${exists ? "ready" : artifact.availability}`),
+            ...(artifact.required && !exists ? { level: "warning" } : {}),
+            detail: redact({
+                ...(artifact.availability !== "unavailable" ? { exists } : {}),
+                availability: artifact.availability,
+                path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
+                required: artifact.required,
+                ...(artifact.bytes_total !== undefined ? { size: artifact.bytes_total } : {}),
+                ...(artifact.reason ? { reason: artifact.reason } : {}),
+            }),
+        }, "artifact", index + 1, index);
+    });
+}
+/** Data-only canonical-journal projection; captured Recipe context supplies privacy, never lifecycle/work authority. */
+export function projectRunTraceJournal(read, options = {}) {
+    return traceEventItems(read, options.recipe, options.redactEvidence).sort(compareTraceItems)
+        .slice(0, Math.max(1, Math.min(options.limit ?? 100, 200))).map(({ item }) => item);
 }
 export function projectRunTrace(stateDir, options = {}) {
     const source = options.source ?? "all";
-    const items = [
-        ...traceEventItems(stateDir),
-        ...controlItems(stateDir),
-        ...agentItems(stateDir),
-        ...processItems(stateDir),
-        ...resultItems(stateDir),
-        ...artifactItems(stateDir, options.artifacts),
-    ]
-        .filter(({ item }) => source === "all" || item.source === source)
-        .sort(compareTraceItems);
+    const chronology = new TraceChronologyBuilder();
+    const entries = [
+        ...traceEventItems(RunsTrace.readRunTraceJournal(stateDir), undefined, undefined, chronology),
+        ...controlItems(stateDir, chronology),
+        ...agentItems(stateDir, chronology),
+    ];
+    const snapshots = [...processItems(stateDir), ...resultItems(stateDir), ...artifactItems(stateDir, options.artifacts, chronology)];
+    for (const entry of snapshots) {
+        if (entry.item.kind === "state.read_error")
+            chronology.unavailable("metadata_unavailable");
+        chronology.add(entry.item, entry.sourceKey, entry.ordinal);
+    }
+    const all = [...entries, ...snapshots];
+    chronology.finish(all);
+    const items = all.filter(({ item }) => source === "all" || item.source === source).sort(compareTraceItems);
     return items
         .slice(0, Math.max(1, Math.min(options.limit ?? 100, 200)))
         .map(({ item }) => item);