@smthrs/gateway 0.35.0 → 1.0.0-rc.3

package/dist/esm/EngineTrace.js

@@ -0,0 +1,548 @@
+/**
+ * Recorded native evidence, decoded through the contracts that wrote it.
+ *
+ * @since 1.0.0
+ */
+import { RunState } from "@smthrs/engine-store/RunState";
+import { ResultEncoded } from "@smthrs/flow/Flow";
+import * as EngineEvent from "@smthrs/journal/EngineEvent";
+import * as JournalEvent from "@smthrs/journal/JournalEvent";
+import { Option, Schema } from "effect";
+import { inspectLabel } from "./internal/inspectLabels.js";
+// This is the private control bridge's envelope, not another engine contract.
+const Envelope = Schema.Struct({
+    version: Schema.Literal(1),
+    executionId: JournalEvent.RunId,
+    generation: JournalEvent.NonNegativeQuantity,
+    sequence: JournalEvent.Seq,
+    eventId: Schema.String,
+    sourceId: JournalEvent.SourceId,
+    sourceSequence: JournalEvent.SourceSeq,
+    emittedAtMs: JournalEvent.TimestampMs,
+    eventType: Schema.NonEmptyString,
+    payload: Schema.Json,
+    meta: Schema.Json
+});
+const decodeEnvelope = Schema.decodeUnknownOption(Envelope);
+const decodeGraph = Schema.decodeUnknownOption(EngineEvent.NodeGraph);
+const decodeScheduled = Schema.decodeUnknownOption(EngineEvent.NodeScheduledPayload);
+const decodeSettled = Schema.decodeUnknownOption(EngineEvent.NodeSettledPayload);
+const decodeAttempt = Schema.decodeUnknownOption(EngineEvent.AttemptPayload, { onExcessProperty: "error" });
+const decodeState = Schema.decodeUnknownOption(EngineEvent.StatePayload, { onExcessProperty: "error" });
+const decodeMarker = Schema.decodeUnknownOption(EngineEvent.CurrentAttempt);
+const stateDecisions = [
+    "created",
+    "resumed",
+    "transitioned",
+    "handed-off",
+    "lineage-exhausted",
+    "round-invalid",
+    "quarantined",
+    "interrupt-released"
+];
+const decodeDecision = Schema.decodeUnknownOption(Schema.Struct({
+    decision: Schema.Literals(stateDecisions),
+    status: Schema.optionalKey(Schema.Literals(["pending", "running", "suspended", "completed", "failed", "cancelled"])),
+    state: RunState
+}));
+// RunDriver's durable cancellation record has no run-decision counterpart.
+const decodeCancellation = Schema.decodeUnknownOption(Schema.Struct({
+    outcome: Schema.Literal("cancelled"),
+    interruptedAtMs: JournalEvent.TimestampMs,
+    owner: Schema.String,
+    cascadedTo: Schema.optionalKey(Schema.Array(JournalEvent.RunId))
+}));
+const decodeResult = Schema.decodeUnknownOption(ResultEncoded, { onExcessProperty: "error" });
+const json = (value) => typeof value === "string" ? value : JSON.stringify(value);
+const identity = (...parts) => parts.map((part) => encodeURIComponent(String(part))).join(":");
+const span = (id, kind, label, at, detail) => ({
+    id,
+    kind,
+    label,
+    status: "recorded",
+    startedAt: at,
+    children: [],
+    detail
+});
+const detail = (row, envelope) => ({
+    sequence: row.sequence,
+    event: envelope.eventType,
+    fields: { ...envelope }
+});
+const decodeProjection = Schema.decodeUnknownOption(Schema.Struct({
+    version: Schema.Literal(1),
+    executionId: JournalEvent.RunId,
+    generation: JournalEvent.NonNegativeQuantity
+}));
+/**
+ * Observation completion is separate from the control run's terminal verdict.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const engineProjectionPending = (records = []) => {
+    const states = new Map();
+    for (const row of [...records].sort((left, right) => (left.sequence ?? 0) - (right.sequence ?? 0))) {
+        if (row.kind === "control.engine.projection-gap") {
+            // The gap is rendered as missing evidence. Stop polling rather than
+            // disguising an observation failure as an indefinitely running task.
+            for (const state of states.values())
+                state.pending = false;
+            continue;
+        }
+        if (row.kind !== "control.engine.projection-started" && row.kind !== "control.engine.projection-settled")
+            continue;
+        const decoded = decodeProjection(row.payload);
+        if (Option.isNone(decoded))
+            continue;
+        const { executionId, generation } = decoded.value;
+        const current = states.get(executionId);
+        if (row.kind === "control.engine.projection-started") {
+            if (current === undefined || generation > current.generation) {
+                states.set(executionId, { generation, pending: true });
+            }
+        }
+        else if (current?.generation === generation)
+            current.pending = false;
+    }
+    return [...states.values()].some((state) => state.pending);
+};
+/**
+ * Generations never share attempt identity. Native timestamps describe native
+ * work; the outer control sequence still determines the historical UI cursor.
+ * Only recorded parent IDs can nest executions. Ambiguous parent generations
+ * remain beside the root instead of guessing which historical parent owned them.
+ */
+const foldEngineJournal = (records) => {
+    const executions = new Map();
+    const attempts = new Map();
+    const notices = [];
+    const nodes = new Map();
+    const instances = new Map();
+    const seen = new Map();
+    for (const row of records) {
+        if (row.kind === "control.engine.projection-gap") {
+            const notice = span(`engine-gap:${row.sequence ?? notices.length}`, "event", "Engine evidence gap", row.occurredAt ?? 0, {
+                sequence: row.sequence,
+                event: row.kind,
+                fields: { evidence: row.payload }
+            });
+            notice.status = "unknown";
+            notice.endedAt = notice.startedAt;
+            notices.push(notice);
+            continue;
+        }
+        if (row.kind !== "control.engine.event")
+            continue;
+        const decoded = decodeEnvelope(row.payload);
+        if (Option.isNone(decoded)) {
+            const notice = span(`engine-invalid:${row.sequence ?? notices.length}`, "event", "Unreadable engine evidence", row.occurredAt ?? 0, {
+                sequence: row.sequence,
+                event: row.kind,
+                fields: { evidence: row.payload }
+            });
+            notice.status = "unknown";
+            notice.endedAt = notice.startedAt;
+            notices.push(notice);
+            continue;
+        }
+        const envelope = decoded.value;
+        const key = identity(envelope.executionId, envelope.generation);
+        const eventKey = identity(key, envelope.sequence);
+        const previous = seen.get(eventKey);
+        if (previous !== undefined) {
+            if (previous !== JSON.stringify(envelope)) {
+                const conflict = executions.get(key);
+                conflict.coherent = false;
+            }
+            continue;
+        }
+        seen.set(eventKey, JSON.stringify(envelope));
+        let execution = executions.get(key);
+        if (execution === undefined) {
+            execution = {
+                envelope,
+                coherent: true,
+                span: span(`engine:${key}`, "execution", envelope.executionId, envelope.emittedAtMs, detail(row, envelope))
+            };
+            executions.set(key, execution);
+        }
+        const parent = (parentId) => {
+            if (execution.parentKnown && execution.parentExecutionId !== parentId)
+                execution.coherent = false;
+            execution.parentKnown = true;
+            execution.parentExecutionId = parentId;
+            execution.parentId = parentId;
+        };
+        const result = (value) => {
+            if (Number.isSafeInteger(row.sequence) && row.sequence >= 0) {
+                execution.result = { value, sequence: row.sequence };
+            }
+        };
+        const failure = (kind, value) => {
+            if (Number.isSafeInteger(row.sequence) && row.sequence >= 0) {
+                execution.failure = { kind, value, sequence: row.sequence };
+            }
+        };
+        const generic = () => {
+            const event = span(`engine-event:${eventKey}`, "event", envelope.eventType, envelope.emittedAtMs, detail(row, envelope));
+            event.endedAt = event.startedAt;
+            execution.span.children.push(event);
+        };
+        const attempt = (step, number) => {
+            const attemptKey = identity(key, step, number);
+            let current = attempts.get(attemptKey);
+            if (current === undefined) {
+                current = span(`engine-attempt:${attemptKey}`, "attempt", `attempt ${number} · ${step.slice(0, 12)}`, envelope.emittedAtMs, detail(row, envelope));
+                attempts.set(attemptKey, current);
+                execution.span.children.push(current);
+            }
+            return current;
+        };
+        if (envelope.eventType === EngineEvent.nodeEventTypes.planRecorded || envelope.eventType === EngineEvent.nodeEventTypes.subgraphAppended) {
+            const payload = envelope.payload;
+            const graph = decodeGraph(payload?.graph);
+            if (Option.isSome(graph)) {
+                const nodes = new Map(execution.graph?.nodes.map(node => [node.id, node]));
+                for (const node of graph.value.nodes)
+                    nodes.set(node.id, node);
+                execution.graph = { ...graph.value, nodes: [...nodes.values()] };
+            }
+            generic();
+            continue;
+        }
+        if (envelope.eventType === EngineEvent.nodeEventTypes.nodeScheduled || envelope.eventType === EngineEvent.nodeEventTypes.nodeSettled) {
+            const scheduled = envelope.eventType === EngineEvent.nodeEventTypes.nodeScheduled
+                ? decodeScheduled(envelope.payload) : Option.none();
+            const settled = envelope.eventType === EngineEvent.nodeEventTypes.nodeSettled
+                ? decodeSettled(envelope.payload) : Option.none();
+            const recorded = Option.isSome(scheduled) ? scheduled.value : Option.isSome(settled) ? settled.value : undefined;
+            if (recorded === undefined) {
+                generic();
+                continue;
+            }
+            const nodeKey = identity(key, recorded.nodeId);
+            const action = recorded.action ?? execution.graph?.nodes.find(node => node.id === recorded.nodeId)?.action;
+            let node = nodes.get(nodeKey);
+            if (node === undefined || Option.isSome(scheduled)) {
+                const instance = (instances.get(nodeKey) ?? 0) + 1;
+                instances.set(nodeKey, instance);
+                node = span(`engine-node:${nodeKey}#${instance}`, "call", inspectLabel(action ?? recorded.nodeId), envelope.emittedAtMs, detail(row, envelope));
+                nodes.set(nodeKey, node);
+                execution.span.children.push(node);
+            }
+            if (action !== undefined)
+                node.label = inspectLabel(action);
+            node.detail = { ...detail(row, envelope), sequence: node.detail.sequence };
+            if (Option.isSome(scheduled)) {
+                node.status = "running";
+            }
+            else {
+                const value = Option.getOrThrow(settled);
+                node.status = value.outcome === "failed" ? "failed"
+                    : value.outcome === "deferred" ? "waiting"
+                        : value.outcome === "skipped" ? "skipped" : "completed";
+                if (value.outcome !== "deferred")
+                    node.endedAt = envelope.emittedAtMs;
+                // The redacted preview is evidence, including when truncated. Never
+                // evaluate it, or mistake a JSON prefix for a complete return value.
+                if (value.result !== undefined)
+                    node.detail = { ...node.detail, output: value.result.preview };
+            }
+            continue;
+        }
+        if (envelope.eventType === "flows.engine.attempt-started" || envelope.eventType === "flows.engine.attempt-finished") {
+            const marker = decodeMarker({ eventType: envelope.eventType, payload: envelope.payload });
+            if (Option.isNone(marker) || marker.value.payload.runId !== envelope.executionId) {
+                generic();
+                continue;
+            }
+            const current = attempt(marker.value.payload.stepKeyDigest, marker.value.payload.attempt);
+            if (marker.value.eventType === "flows.engine.attempt-started")
+                current.status = "running";
+            else {
+                current.status = marker.value.payload.state === "succeeded" ? "completed" : "failed";
+                current.endedAt = envelope.emittedAtMs;
+            }
+            current.detail = { ...current.detail, fields: { ...envelope } };
+            continue;
+        }
+        if (envelope.eventType === EngineEvent.attemptEventType) {
+            const recorded = decodeAttempt(envelope.payload);
+            if (Option.isNone(recorded) || recorded.value.executionId !== envelope.executionId) {
+                execution.coherent = false;
+                generic();
+                continue;
+            }
+            const { lifecycle, lineage, stepKeyDigest, attempt: number } = recorded.value;
+            // Lineage may describe a trampoline predecessor, not a spawned parent.
+            // Product ancestry comes only from RunState.parentExecutionId below.
+            execution.parentId = lineage.parentRunId ?? undefined;
+            const current = attempt(stepKeyDigest, number);
+            current.startedAt = lifecycle.startedAtMs;
+            current.status = lifecycle.state === "succeeded"
+                ? "completed"
+                : lifecycle.state === "suspended"
+                    ? "waiting"
+                    : lifecycle.state;
+            current.detail = { ...detail(row, envelope), sequence: current.detail.sequence };
+            if (lifecycle.state === "succeeded" || lifecycle.state === "failed") {
+                current.endedAt = lifecycle.finishedAtMs;
+                current.detail = {
+                    ...current.detail,
+                    ...(lifecycle.result._tag === "Success"
+                        ? { output: json(lifecycle.result.value) }
+                        : { message: json(lifecycle.result.detail) })
+                };
+            }
+            continue;
+        }
+        if (envelope.eventType === EngineEvent.stateEventType) {
+            const recorded = decodeState(envelope.payload);
+            if (Option.isNone(recorded) || recorded.value.executionId !== envelope.executionId) {
+                execution.coherent = false;
+                generic();
+                continue;
+            }
+            execution.parentId = recorded.value.lineage.parentRunId ?? undefined;
+            const registerWait = (waitId, kind) => {
+                const waits = execution.waits ??= new Map();
+                const id = identity(key, waitId);
+                const existing = waits.get(id);
+                if (existing === undefined)
+                    waits.set(id, { id: `engine-wait:${id}`, kind, since: envelope.emittedAtMs });
+                // A later clock record refines a generic deferred identity without
+                // restarting the wait or dropping its recorded settlement.
+                else if (kind === "sleep")
+                    existing.kind = kind;
+            };
+            if (recorded.value.event._tag === "Execution" && recorded.value.event.lifecycle.state !== "completed") {
+                for (const wait of recorded.value.event.lifecycle.waits)
+                    registerWait(wait.waitId, wait._tag === "Clock" ? "sleep" : "signal");
+            }
+            if (recorded.value.event._tag === "ClockScheduled") {
+                registerWait(recorded.value.event.waitId, "sleep");
+            }
+            else if (recorded.value.event._tag === "DeferredCompleted") {
+                const wait = execution.waits?.get(identity(key, recorded.value.event.waitId));
+                if (wait !== undefined && wait.settledAt === undefined)
+                    wait.settledAt = envelope.emittedAtMs;
+            }
+            if (recorded.value.event._tag !== "Execution") {
+                generic();
+                continue;
+            }
+            const { lifecycle } = recorded.value.event;
+            execution.result = undefined;
+            execution.failure = undefined;
+            execution.span.detail = {
+                ...detail(row, envelope),
+                sequence: execution.span.detail.sequence,
+                input: execution.span.detail.input
+            };
+            if (lifecycle.state === "completed") {
+                execution.span.status = lifecycle.result._tag === "Success" ? "completed" : "failed";
+                execution.span.endedAt = envelope.emittedAtMs;
+                execution.span.detail = {
+                    ...execution.span.detail,
+                    ...(lifecycle.result._tag === "Success"
+                        ? { output: json(lifecycle.result.value) }
+                        : { message: json(lifecycle.result.detail) })
+                };
+                if (lifecycle.result._tag === "Success")
+                    result(lifecycle.result.value);
+                else
+                    failure(lifecycle.result.reason, lifecycle.result.detail);
+            }
+            else
+                execution.span.status = lifecycle.state === "suspended" ? "waiting" : "running";
+            continue;
+        }
+        if (envelope.eventType === "flows.engine.interrupted") {
+            const cancelled = decodeCancellation(envelope.payload);
+            if (Option.isNone(cancelled)) {
+                generic();
+                continue;
+            }
+            execution.result = undefined;
+            execution.failure = undefined;
+            execution.span.status = "cancelled";
+            execution.span.endedAt = cancelled.value.interruptedAtMs;
+            execution.span.detail = {
+                ...detail(row, envelope),
+                sequence: execution.span.detail.sequence,
+                input: execution.span.detail.input
+            };
+            continue;
+        }
+        if (envelope.eventType === "flows.engine.run-decision") {
+            const decision = decodeDecision(envelope.payload);
+            if (Option.isNone(decision)) {
+                const payload = envelope.payload;
+                // Claim, owner-fence, wake and child-policy decisions deliberately do
+                // not carry RunState. Keep them visible without losing valid state
+                // evidence; malformed state-bearing decisions still refuse claims.
+                if (typeof payload === "object" && payload !== null &&
+                    ("state" in payload || ("decision" in payload && stateDecisions.some((name) => name === payload.decision)))) {
+                    execution.coherent = false;
+                }
+                generic();
+                continue;
+            }
+            const { state, status } = decision.value;
+            if (execution.flowName !== undefined && execution.flowName !== state.flowName)
+                execution.coherent = false;
+            execution.flowName = state.flowName;
+            execution.span.label = inspectLabel(state.flowName);
+            parent(state.parentExecutionId);
+            execution.result = undefined;
+            execution.failure = undefined;
+            execution.span.detail = {
+                ...detail(row, envelope),
+                sequence: execution.span.detail.sequence,
+                input: state.payload
+            };
+            if (decision.value.decision === "created")
+                execution.span.status = "pending";
+            // RunDriver commits this decision with suspended even when its payload
+            // omits status/result (a released host scope can retain no suspension).
+            else if (decision.value.decision === "interrupt-released")
+                execution.span.status = "waiting";
+            else if (status === "running" || status === "pending" || status === "suspended") {
+                execution.span.status = status === "suspended" ? "waiting" : status;
+            }
+            else if (status !== undefined) {
+                const decodedResult = decodeResult(state.result);
+                if (Option.isSome(decodedResult) && decodedResult.value._tag === "Handoff" && status === "completed" &&
+                    decision.value.decision === "handed-off") {
+                    // A round handed off; its raw result describes the successor, not an output.
+                    execution.span.status = "completed";
+                    execution.span.endedAt = envelope.emittedAtMs;
+                    continue;
+                }
+                if (Option.isNone(decodedResult) || decodedResult.value._tag !== "Complete" ||
+                    (status === "completed") !== (decodedResult.value.exit._tag === "Success")) {
+                    execution.coherent = false;
+                    execution.span.status = "unknown";
+                    generic();
+                    continue;
+                }
+                execution.span.status = status;
+                execution.span.endedAt = envelope.emittedAtMs;
+                execution.span.detail = {
+                    ...execution.span.detail,
+                    ...(decodedResult.value.exit._tag === "Success"
+                        ? { output: json(decodedResult.value.exit.value) }
+                        : { message: json(decodedResult.value.exit.cause) })
+                };
+                if (decodedResult.value.exit._tag === "Success")
+                    result(decodedResult.value.exit.value);
+                else
+                    failure("cause", decodedResult.value.exit.cause);
+            }
+            continue;
+        }
+        generic();
+    }
+    const byExecution = new Map();
+    for (const current of executions.values()) {
+        const generations = byExecution.get(current.envelope.executionId) ?? [];
+        generations.push(current);
+        byExecution.set(current.envelope.executionId, generations);
+    }
+    const roots = [];
+    for (const current of executions.values()) {
+        const parents = current.parentId === undefined ? [] : byExecution.get(current.parentId) ?? [];
+        // Build only a forest. Malformed cycles remain separate evidence rows.
+        const ancestors = new Set([current.envelope.executionId]);
+        let parent = parents.length === 1 ? parents[0] : undefined;
+        let cursor = parent;
+        while (cursor !== undefined) {
+            if (ancestors.has(cursor.envelope.executionId)) {
+                parent = undefined;
+                break;
+            }
+            ancestors.add(cursor.envelope.executionId);
+            const next = cursor.parentId === undefined ? [] : byExecution.get(cursor.parentId) ?? [];
+            cursor = next.length === 1 ? next[0] : undefined;
+        }
+        if (parent === undefined)
+            roots.push(current.span);
+        else
+            parent.span.children.push(current.span);
+    }
+    const evidence = [...executions.values()].map((current) => ({
+        executionId: current.envelope.executionId,
+        generation: current.envelope.generation,
+        spanId: current.span.id,
+        parentExecutionId: current.parentExecutionId,
+        parentKnown: current.parentKnown === true,
+        flowName: current.flowName,
+        input: current.span.detail.input,
+        coherent: current.coherent,
+        graph: current.graph,
+        status: current.span.status,
+        waits: [...current.waits?.values() ?? []],
+        result: current.result,
+        failure: current.failure
+    }));
+    return { trace: [...roots, ...notices], evidence };
+};
+/**
+ * Folds native executions and attempts into trace spans with recorded ancestry.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const engineTraceFromJournal = (records) => foldEngineJournal(records).trace;
+/**
+ * Product claims use these typed facts, never text rendered into trace details.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const engineExecutionEvidence = (records) => foldEngineJournal(records).evidence;
+/**
+ * Same recorded native ancestry and historical cursor for every product result projection.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const engineRunEvidence = (records, rootId, cursorSeq) => {
+    const visible = records
+        .filter((row) => Number.isSafeInteger(row.sequence) && Number(row.sequence) >= 0 &&
+        (cursorSeq === undefined || Number(row.sequence) <= cursorSeq))
+        .sort((left, right) => Number(left.sequence) - Number(right.sequence));
+    const executions = engineExecutionEvidence(visible);
+    const generations = new Map();
+    for (const execution of executions) {
+        const found = generations.get(execution.executionId) ?? [];
+        found.push(execution);
+        generations.set(execution.executionId, found);
+    }
+    const current = (execution) => execution.coherent &&
+        execution.generation === Math.max(...generations.get(execution.executionId).map((row) => row.generation));
+    const belongs = (execution, ownerId = rootId) => {
+        const visited = new Set();
+        let candidate = execution;
+        while (true) {
+            if (!candidate.coherent || !candidate.parentKnown || visited.has(candidate.executionId))
+                return false;
+            visited.add(candidate.executionId);
+            if (candidate.executionId === ownerId)
+                return ownerId !== rootId || candidate.parentExecutionId === undefined;
+            if (candidate.parentExecutionId === undefined)
+                return false;
+            const parents = generations.get(candidate.parentExecutionId) ?? [];
+            // A child names a native parent ID, not its generation. Never infer a
+            // parent generation from arrival time after a rewind.
+            if (parents.length !== 1)
+                return false;
+            candidate = parents[0];
+        }
+    };
+    const owned = executions.filter((row) => current(row) && belongs(row));
+    const completed = owned.filter((row) => row.status === "completed" && row.result !== undefined);
+    return { executions: owned, completed, belongs };
+};
+//# sourceMappingURL=EngineTrace.js.map