agentskeptic 0.1.1

package/dist/failureAnalysis.test.js

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { buildFailureAnalysis } from "./failureAnalysis.js";
+import { createEmptyVerificationRunContext } from "./verificationRunContext.js";
+const strongPolicy = {
+    consistencyMode: "strong",
+    verificationWindowMs: 0,
+    pollIntervalMs: 0,
+};
+function step(partial) {
+    return {
+        intendedEffect: { narrative: "" },
+        observedExecution: { paramsCanonical: "{}" },
+        verificationRequest: null,
+        reasons: [],
+        evidenceSummary: {},
+        repeatObservationCount: 1,
+        evaluatedObservationOrdinal: 1,
+        ...partial,
+    };
+}
+function engine(partial) {
+    const { verificationRunContext: ctx, ...rest } = partial;
+    return {
+        schemaVersion: 8,
+        workflowId: "w",
+        status: "incomplete",
+        runLevelReasons: [],
+        verificationPolicy: strongPolicy,
+        eventSequenceIntegrity: { kind: "normal" },
+        steps: [],
+        verificationRunContext: ctx ?? createEmptyVerificationRunContext(),
+        ...rest,
+    };
+}
+describe("buildFailureAnalysis precedence", () => {
+    it("P0: run-level NO_STEPS beats step failure", () => {
+        const a = buildFailureAnalysis(engine({
+            status: "inconsistent",
+            runLevelReasons: [{ code: "NO_STEPS_FOR_WORKFLOW", message: "m" }],
+            steps: [
+                step({
+                    seq: 0,
+                    toolId: "t",
+                    status: "missing",
+                    reasons: [{ code: "ROW_ABSENT", message: "x" }],
+                    failureDiagnostic: "workflow_execution",
+                }),
+            ],
+        }));
+        expect(a?.primaryOrigin).toBe("workflow_flow");
+        expect(a?.evidence[0]?.scope).toBe("run_level");
+    });
+    it("P1: retrieval error before failing tool → retrieval", () => {
+        const ctx = {
+            maxWireSchemaVersion: 2,
+            retrievalEvents: [
+                { ingestIndex: 0, runEventId: "r1", source: "kb", status: "error" },
+            ],
+            controlEvents: [],
+            modelTurnEvents: [],
+            toolSkippedEvents: [],
+            toolObservedIngestIndexBySeq: { "0": 2 },
+            firstToolObservedIngestIndex: 2,
+            hasRunCompletedControl: false,
+            lastRunEvent: { ingestIndex: 2, type: "tool_observed" },
+        };
+        const a = buildFailureAnalysis(engine({
+            status: "inconsistent",
+            verificationRunContext: ctx,
+            steps: [
+                step({
+                    seq: 0,
+                    toolId: "t",
+                    status: "missing",
+                    verificationRequest: {
+                        kind: "sql_row",
+                        table: "t",
+                        identityEq: [{ column: "id", value: "1" }],
+                        requiredFields: {},
+                    },
+                    reasons: [{ code: "ROW_ABSENT", message: "m" }],
+                    failureDiagnostic: "workflow_execution",
+                }),
+            ],
+        }));
+        expect(a?.primaryOrigin).toBe("retrieval");
+        expect(a?.confidence).toBe("high");
+    });
+    it("P1 wins over P2 when both upstream signals exist", () => {
+        const ctx = {
+            maxWireSchemaVersion: 2,
+            retrievalEvents: [{ ingestIndex: 0, runEventId: "r1", source: "s", status: "error" }],
+            controlEvents: [],
+            modelTurnEvents: [{ ingestIndex: 1, runEventId: "m1", status: "error" }],
+            toolSkippedEvents: [],
+            toolObservedIngestIndexBySeq: { "0": 3 },
+            firstToolObservedIngestIndex: 3,
+            hasRunCompletedControl: false,
+            lastRunEvent: { ingestIndex: 3, type: "tool_observed" },
+        };
+        const a = buildFailureAnalysis(engine({
+            status: "inconsistent",
+            verificationRunContext: ctx,
+            steps: [
+                step({
+                    seq: 0,
+                    toolId: "t",
+                    status: "missing",
+                    verificationRequest: {
+                        kind: "sql_row",
+                        table: "t",
+                        identityEq: [{ column: "id", value: "1" }],
+                        requiredFields: {},
+                    },
+                    reasons: [{ code: "ROW_ABSENT", message: "m" }],
+                    failureDiagnostic: "workflow_execution",
+                }),
+            ],
+        }));
+        expect(a?.primaryOrigin).toBe("retrieval");
+    });
+    it("P2: model_turn error before failing tool → decision_making", () => {
+        const ctx = {
+            maxWireSchemaVersion: 2,
+            retrievalEvents: [],
+            controlEvents: [],
+            modelTurnEvents: [{ ingestIndex: 0, runEventId: "m1", status: "error" }],
+            toolSkippedEvents: [],
+            toolObservedIngestIndexBySeq: { "0": 1 },
+            firstToolObservedIngestIndex: 1,
+            hasRunCompletedControl: false,
+            lastRunEvent: { ingestIndex: 1, type: "tool_observed" },
+        };
+        const a = buildFailureAnalysis(engine({
+            status: "inconsistent",
+            verificationRunContext: ctx,
+            steps: [
+                step({
+                    seq: 0,
+                    toolId: "t",
+                    status: "missing",
+                    verificationRequest: {
+                        kind: "sql_row",
+                        table: "t",
+                        identityEq: [{ column: "id", value: "1" }],
+                        requiredFields: {},
+                    },
+                    reasons: [{ code: "ROW_ABSENT", message: "m" }],
+                    failureDiagnostic: "workflow_execution",
+                }),
+            ],
+        }));
+        expect(a?.primaryOrigin).toBe("decision_making");
+    });
+    it("ROW_ABSENT carries alternatives", () => {
+        const a = buildFailureAnalysis(engine({
+            status: "inconsistent",
+            steps: [
+                step({
+                    seq: 0,
+                    toolId: "t",
+                    status: "missing",
+                    verificationRequest: {
+                        kind: "sql_row",
+                        table: "t",
+                        identityEq: [{ column: "id", value: "1" }],
+                        requiredFields: {},
+                    },
+                    reasons: [{ code: "ROW_ABSENT", message: "m" }],
+                    failureDiagnostic: "workflow_execution",
+                }),
+            ],
+        }));
+        expect(a?.primaryOrigin).toBe("downstream_system_state");
+        expect(a?.alternativeHypotheses).toHaveLength(2);
+    });
+    it("complete → null", () => {
+        expect(buildFailureAnalysis(engine({
+            status: "complete",
+            steps: [
+                step({
+                    seq: 0,
+                    toolId: "t",
+                    status: "verified",
+                    verificationRequest: {
+                        kind: "sql_row",
+                        table: "t",
+                        identityEq: [{ column: "id", value: "1" }],
+                        requiredFields: {},
+                    },
+                }),
+            ],
+        }))).toBeNull();
+    });
+});
+//# sourceMappingURL=failureAnalysis.test.js.map

package/dist/failureAnalysis.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureAnalysis.test.js","sourceRoot":"","sources":["../src/failureAnalysis.test.ts"],"names":[],"mappings":"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"}

package/dist/failureCatalog.d.ts

@@ -0,0 +1,26 @@
+import { CLI_OPERATIONAL_CODES, type OperationalCode } from "./cliOperationalCodes.js";
+import type { Reason } from "./types.js";
+/** Re-export for existing importers of `failureCatalog.js`. */
+export { CLI_OPERATIONAL_CODES, type OperationalCode };
+/** CLI operational error envelope (stderr, exit 3). */
+export declare const CLI_ERROR_SCHEMA_VERSION: 2;
+export declare const CLI_ERROR_KIND: "execution_truth_layer_error";
+export declare const OPERATIONAL_MESSAGE_MAX_CHARS = 2048;
+/** Same literal as step `incomplete_verification` for divergent retries (SSOT + registry validation). */
+export declare const RETRY_OBSERVATIONS_DIVERGE_MESSAGE = "Multiple observations for this seq do not all match the last observation (toolId and canonical params).";
+export declare const RUN_LEVEL_MESSAGES: {
+    readonly MALFORMED_EVENT_LINE: "Event line was missing, invalid JSON, or failed schema validation for a tool observation.";
+    readonly NO_STEPS_FOR_WORKFLOW: "No tool_observed events for this workflow id after filtering.";
+};
+export declare function runLevelIssue(code: keyof typeof RUN_LEVEL_MESSAGES): Reason;
+/** SSOT for WorkflowResult.eventSequenceIntegrity.reasons (machine codes + messages). */
+export declare const EVENT_SEQUENCE_MESSAGES: {
+    readonly CAPTURE_ORDER_NOT_MONOTONIC_IN_SEQ: "Capture order was not non-decreasing in seq; planning and verification used seq-sorted order, not arrival order.";
+};
+export type EventSequenceIssueCode = keyof typeof EVENT_SEQUENCE_MESSAGES;
+export declare function eventSequenceIssue(code: EventSequenceIssueCode): Reason;
+/** First adjacent pair in seq-sorted order with decreasing parsed timestamps (seq values from those events). */
+export declare function eventSequenceTimestampNotMonotonicReason(seqBefore: number, seqAfter: number): Reason;
+export declare function formatOperationalMessage(raw: string): string;
+export declare function cliErrorEnvelope(code: string, message: string): string;
+//# sourceMappingURL=failureCatalog.d.ts.map

package/dist/failureCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureCatalog.d.ts","sourceRoot":"","sources":["../src/failureCatalog.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,+DAA+D;AAC/D,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,CAAC;AAEvD,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,EAAG,CAAU,CAAC;AACnD,eAAO,MAAM,cAAc,EAAG,6BAAsC,CAAC;AAErE,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,yGAAyG;AACzG,eAAO,MAAM,kCAAkC,4GAC4D,CAAC;AAE5G,eAAO,MAAM,kBAAkB;;;CAIrB,CAAC;AAEX,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,OAAO,kBAAkB,GAAG,MAAM,CAE3E;AAED,yFAAyF;AACzF,eAAO,MAAM,uBAAuB;;CAG1B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,uBAAuB,CAAC;AAE1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAEvE;AAID,gHAAgH;AAChH,wBAAgB,wCAAwC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpG;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQtE"}

package/dist/failureCatalog.js

@@ -0,0 +1,51 @@
+import { CLI_OPERATIONAL_CODES, } from "./cliOperationalCodes.js";
+import { buildOperationalFailureDiagnosis } from "./operationalFailureDiagnosis.js";
+/** Re-export for existing importers of `failureCatalog.js`. */
+export { CLI_OPERATIONAL_CODES };
+/** CLI operational error envelope (stderr, exit 3). */
+export const CLI_ERROR_SCHEMA_VERSION = 2;
+export const CLI_ERROR_KIND = "execution_truth_layer_error";
+export const OPERATIONAL_MESSAGE_MAX_CHARS = 2048;
+/** Same literal as step `incomplete_verification` for divergent retries (SSOT + registry validation). */
+export const RETRY_OBSERVATIONS_DIVERGE_MESSAGE = "Multiple observations for this seq do not all match the last observation (toolId and canonical params).";
+export const RUN_LEVEL_MESSAGES = {
+    MALFORMED_EVENT_LINE: "Event line was missing, invalid JSON, or failed schema validation for a tool observation.",
+    NO_STEPS_FOR_WORKFLOW: "No tool_observed events for this workflow id after filtering.",
+};
+export function runLevelIssue(code) {
+    return { code, message: RUN_LEVEL_MESSAGES[code] };
+}
+/** SSOT for WorkflowResult.eventSequenceIntegrity.reasons (machine codes + messages). */
+export const EVENT_SEQUENCE_MESSAGES = {
+    CAPTURE_ORDER_NOT_MONOTONIC_IN_SEQ: "Capture order was not non-decreasing in seq; planning and verification used seq-sorted order, not arrival order.",
+};
+export function eventSequenceIssue(code) {
+    return { code, message: EVENT_SEQUENCE_MESSAGES[code] };
+}
+const TIMESTAMP_NOT_MONOTONIC_CODE = "TIMESTAMP_NOT_MONOTONIC_WITH_SEQ_SORT_ORDER";
+/** First adjacent pair in seq-sorted order with decreasing parsed timestamps (seq values from those events). */
+export function eventSequenceTimestampNotMonotonicReason(seqBefore, seqAfter) {
+    return {
+        code: TIMESTAMP_NOT_MONOTONIC_CODE,
+        message: `In seq-sorted order, timestamp decreased between seq ${seqBefore} and seq ${seqAfter}.`,
+    };
+}
+export function formatOperationalMessage(raw) {
+    let s = raw.replace(/\t|\r|\n/g, " ");
+    s = s.replace(/ +/g, " ").trim();
+    const max = OPERATIONAL_MESSAGE_MAX_CHARS;
+    if (s.length > max) {
+        return `${s.slice(0, max - 3)}...`;
+    }
+    return s;
+}
+export function cliErrorEnvelope(code, message) {
+    return JSON.stringify({
+        schemaVersion: CLI_ERROR_SCHEMA_VERSION,
+        kind: CLI_ERROR_KIND,
+        code,
+        message: formatOperationalMessage(message),
+        failureDiagnosis: buildOperationalFailureDiagnosis(code),
+    });
+}
+//# sourceMappingURL=failureCatalog.js.map

package/dist/failureCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureCatalog.js","sourceRoot":"","sources":["../src/failureCatalog.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAEtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gCAAgC,EAAE,MAAM,kCAAkC,CAAC;AAGpF,+DAA+D;AAC/D,OAAO,EAAE,qBAAqB,EAAwB,CAAC;AAEvD,uDAAuD;AACvD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAU,CAAC;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,6BAAsC,CAAC;AAErE,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAElD,yGAAyG;AACzG,MAAM,CAAC,MAAM,kCAAkC,GAC7C,yGAAyG,CAAC;AAE5G,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,oBAAoB,EAClB,2FAA2F;IAC7F,qBAAqB,EAAE,+DAA+D;CAC9E,CAAC;AAEX,MAAM,UAAU,aAAa,CAAC,IAAqC;IACjE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,kCAAkC,EAChC,kHAAkH;CAC5G,CAAC;AAIX,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC7D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,4BAA4B,GAAG,6CAAsD,CAAC;AAE5F,gHAAgH;AAChH,MAAM,UAAU,wCAAwC,CAAC,SAAiB,EAAE,QAAgB;IAC1F,OAAO;QACL,IAAI,EAAE,4BAA4B;QAClC,OAAO,EAAE,wDAAwD,SAAS,YAAY,QAAQ,GAAG;KAClG,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,6BAA6B,CAAC;IAC1C,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC5D,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,aAAa,EAAE,wBAAwB;QACvC,IAAI,EAAE,cAAc;QACpB,IAAI;QACJ,OAAO,EAAE,wBAAwB,CAAC,OAAO,CAAC;QAC1C,gBAAgB,EAAE,gCAAgC,CAAC,IAAI,CAAC;KACzD,CAAC,CAAC;AACL,CAAC"}

package/dist/failureCatalog.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=failureCatalog.test.d.ts.map

package/dist/failureCatalog.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureCatalog.test.d.ts","sourceRoot":"","sources":["../src/failureCatalog.test.ts"],"names":[],"mappings":""}

package/dist/failureCatalog.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import { CLI_OPERATIONAL_CODES, OPERATIONAL_MESSAGE_MAX_CHARS, formatOperationalMessage, runLevelIssue, } from "./failureCatalog.js";
+describe("failureCatalog", () => {
+    it("CLI_OPERATIONAL_CODES values are unique", () => {
+        const values = Object.values(CLI_OPERATIONAL_CODES);
+        expect(new Set(values).size).toBe(values.length);
+    });
+    it("formatOperationalMessage normalizes whitespace and truncates", () => {
+        expect(formatOperationalMessage("a\tb\nc")).toBe("a b c");
+        expect(formatOperationalMessage("  x  y  ")).toBe("x y");
+        const long = "a".repeat(OPERATIONAL_MESSAGE_MAX_CHARS + 100);
+        const out = formatOperationalMessage(long);
+        expect(out.length).toBe(OPERATIONAL_MESSAGE_MAX_CHARS);
+        expect(out.endsWith("...")).toBe(true);
+    });
+    it("runLevelIssue returns fixed literals", () => {
+        const m = runLevelIssue("MALFORMED_EVENT_LINE");
+        expect(m.code).toBe("MALFORMED_EVENT_LINE");
+        expect(m.message).toContain("tool observation");
+        const n = runLevelIssue("NO_STEPS_FOR_WORKFLOW");
+        expect(n.code).toBe("NO_STEPS_FOR_WORKFLOW");
+        expect(n.message).toBe("No tool_observed events for this workflow id after filtering.");
+    });
+});
+//# sourceMappingURL=failureCatalog.test.js.map

package/dist/failureCatalog.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureCatalog.test.js","sourceRoot":"","sources":["../src/failureCatalog.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,wBAAwB,EACxB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;QACpD,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACtE,MAAM,CAAC,wBAAwB,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1D,MAAM,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,6BAA6B,GAAG,GAAG,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,aAAa,CAAC,sBAAsB,CAAC,CAAC;QAChD,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAC5C,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;QAChD,MAAM,CAAC,GAAG,aAAa,CAAC,uBAAuB,CAAC,CAAC;QACjD,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAC7C,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/failureExplanation.d.ts

@@ -0,0 +1,52 @@
+import type { FailureExplanationV1, WorkflowEngineResult, WorkflowTruthReport } from "./types.js";
+export type FailureExplanationInvariantCode = "EXPLANATION_VERIFICATION_POLICY_INVALID" | "EXPLANATION_EVIDENCE_CODES_EMPTY" | "EXPLANATION_PRIMARY_EVIDENCE_SCOPE_EFFECT" | "EXPLANATION_STEP_TRUTH_MISMATCH" | "EXPLANATION_RUN_CONTEXT_INDEX_MISSING";
+export declare class FailureExplanationInvariantError extends Error {
+    readonly code: FailureExplanationInvariantCode;
+    constructor(code: FailureExplanationInvariantCode, message: string);
+}
+/** Exported for doc parity tests; placeholders use angle brackets in the string. */
+export declare const FE_RUN_LEVEL_EXPECTED = "Verification expected a valid captured run for workflowId=<workflowId> under policy [<P>] with no run-level ingest or planning failures.";
+export declare const FE_RUN_LEVEL_OBSERVED = "Run-level failure: code=<firstCode> detail=<detail>.";
+export declare const FE_RUN_LEVEL_DIVERGENCE = "Divergence at run_level: code=<firstCode> meaning=<meaning>";
+export declare const FE_EVENT_SEQUENCE_EXPECTED = "Verification expected monotonic, well-formed event capture for workflowId=<workflowId> under policy [<P>].";
+export declare const FE_EVENT_SEQUENCE_OBSERVED = "Event-sequence irregularity: code=<firstCode> detail=<detail>.";
+export declare const FE_EVENT_SEQUENCE_DIVERGENCE = "Divergence at event_sequence: code=<firstCode> meaning=<meaning>";
+export declare const FE_RUN_CONTEXT_EXPECTED = "Verification expected upstream run context through ingest_index=<ingestIndex> to allow fair evaluation of the failing tool observation under policy [<P>].";
+export declare const FE_RUN_CONTEXT_OBSERVED = "Run-context signal before the failing observation: code=<C> <detail>.";
+export declare const FE_RUN_CONTEXT_DIVERGENCE = "Divergence at run_context before the failing tool observation: code=<C> meaning=<meaning>";
+export declare const FE_STEP_EXPECTED = "Verification expected post-execution database state to satisfy verify_target \"<verifyTargetOrLiteralNull>\" and intended_effect \"<narrative>\" for seq=<seq> toolId=<toolId> under policy [<P>].";
+export declare const FE_STEP_OBSERVED = "Step verification outcome: code=<primaryCode> detail=<detail><suffix>";
+export declare const FE_STEP_DIVERGENCE = "Divergence at step seq=<seq> toolId=<toolId>: primary_code=<primaryCode> meaning=<meaning>";
+export declare const FE_NO_STEPS_OBSERVED = "No tool_observed steps were produced for workflowId=<workflowId>.";
+export declare const FE_NO_STEPS_DIVERGENCE = "Divergence: no steps to verify against the database under policy [<P>]";
+/** All branch template literals (doc fences must match these). */
+export declare const FAILURE_EXPLANATION_BRANCH_TEMPLATES: {
+    readonly runLevel: {
+        readonly expected: "Verification expected a valid captured run for workflowId=<workflowId> under policy [<P>] with no run-level ingest or planning failures.";
+        readonly observed: "Run-level failure: code=<firstCode> detail=<detail>.";
+        readonly divergence: "Divergence at run_level: code=<firstCode> meaning=<meaning>";
+    };
+    readonly eventSequence: {
+        readonly expected: "Verification expected monotonic, well-formed event capture for workflowId=<workflowId> under policy [<P>].";
+        readonly observed: "Event-sequence irregularity: code=<firstCode> detail=<detail>.";
+        readonly divergence: "Divergence at event_sequence: code=<firstCode> meaning=<meaning>";
+    };
+    readonly runContext: {
+        readonly expected: "Verification expected upstream run context through ingest_index=<ingestIndex> to allow fair evaluation of the failing tool observation under policy [<P>].";
+        readonly observed: "Run-context signal before the failing observation: code=<C> <detail>.";
+        readonly divergence: "Divergence at run_context before the failing tool observation: code=<C> meaning=<meaning>";
+    };
+    readonly step: {
+        readonly expected: "Verification expected post-execution database state to satisfy verify_target \"<verifyTargetOrLiteralNull>\" and intended_effect \"<narrative>\" for seq=<seq> toolId=<toolId> under policy [<P>].";
+        readonly observed: "Step verification outcome: code=<primaryCode> detail=<detail><suffix>";
+        readonly divergence: "Divergence at step seq=<seq> toolId=<toolId>: primary_code=<primaryCode> meaning=<meaning>";
+    };
+    readonly noSteps: {
+        readonly expected: "Verification expected a valid captured run for workflowId=<workflowId> under policy [<P>] with no run-level ingest or planning failures.";
+        readonly observed: "No tool_observed steps were produced for workflowId=<workflowId>.";
+        readonly divergence: "Divergence: no steps to verify against the database under policy [<P>]";
+    };
+};
+export declare function policyFragment(engine: WorkflowEngineResult): string;
+export declare function buildFailureExplanation(engine: WorkflowEngineResult, truth: Omit<WorkflowTruthReport, "failureExplanation" | "correctnessDefinition" | "schemaVersion">): FailureExplanationV1 | null;
+//# sourceMappingURL=failureExplanation.d.ts.map

package/dist/failureExplanation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureExplanation.d.ts","sourceRoot":"","sources":["../src/failureExplanation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAKV,oBAAoB,EAIpB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,+BAA+B,GACvC,yCAAyC,GACzC,kCAAkC,GAClC,2CAA2C,GAC3C,iCAAiC,GACjC,uCAAuC,CAAC;AAE5C,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;gBACnC,IAAI,EAAE,+BAA+B,EAAE,OAAO,EAAE,MAAM;CAKnE;AAkED,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,6IAC0G,CAAC;AAC7I,eAAO,MAAM,qBAAqB,yDAAyD,CAAC;AAC5F,eAAO,MAAM,uBAAuB,gEAAgE,CAAC;AAErG,eAAO,MAAM,0BAA0B,+GACuE,CAAC;AAC/G,eAAO,MAAM,0BAA0B,mEAAmE,CAAC;AAC3G,eAAO,MAAM,4BAA4B,qEAC2B,CAAC;AAErE,eAAO,MAAM,uBAAuB,+JAC0H,CAAC;AAC/J,eAAO,MAAM,uBAAuB,0EAA0E,CAAC;AAC/G,eAAO,MAAM,yBAAyB,8FACuD,CAAC;AAE9F,eAAO,MAAM,gBAAgB,uMACyK,CAAC;AACvM,eAAO,MAAM,gBAAgB,0EAA0E,CAAC;AACxG,eAAO,MAAM,kBAAkB,+FAC+D,CAAC;AAE/F,eAAO,MAAM,oBAAoB,sEAAsE,CAAC;AACxG,eAAO,MAAM,sBAAsB,2EACuC,CAAC;AAE3E,kEAAkE;AAClE,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBvC,CAAC;AAyBX,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA4BnE;AA6HD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,GAAG,uBAAuB,GAAG,eAAe,CAAC,GACjG,oBAAoB,GAAG,IAAI,CAqJ7B"}

package/dist/failureExplanation.failureAnalysisMock.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=failureExplanation.failureAnalysisMock.test.d.ts.map

package/dist/failureExplanation.failureAnalysisMock.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureExplanation.failureAnalysisMock.test.d.ts","sourceRoot":"","sources":["../src/failureExplanation.failureAnalysisMock.test.ts"],"names":[],"mappings":""}

package/dist/failureExplanation.failureAnalysisMock.test.js

@@ -0,0 +1,200 @@
+/**
+ * Isolated file: `vi.mock("./failureAnalysis.js")` must not run with tests that need the real analyzer.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { FailureExplanationInvariantError } from "./failureExplanation.js";
+import { buildWorkflowTruthReport } from "./workflowTruthReport.js";
+import { createEmptyVerificationRunContext } from "./verificationRunContext.js";
+vi.mock("./failureAnalysis.js", async (importOriginal) => {
+    const orig = await importOriginal();
+    return { ...orig, buildFailureAnalysis: vi.fn() };
+});
+import { buildFailureAnalysis } from "./failureAnalysis.js";
+const strongPolicy = {
+    consistencyMode: "strong",
+    verificationWindowMs: 0,
+    pollIntervalMs: 0,
+};
+function missingStep() {
+    return {
+        seq: 0,
+        toolId: "t",
+        intendedEffect: { narrative: "n" },
+        observedExecution: { paramsCanonical: "{}" },
+        verificationRequest: {
+            kind: "sql_row",
+            table: "contacts",
+            identityEq: [{ column: "id", value: "1" }],
+            requiredFields: {},
+        },
+        status: "missing",
+        reasons: [{ code: "ROW_ABSENT", message: "absent" }],
+        evidenceSummary: {},
+        repeatObservationCount: 1,
+        evaluatedObservationOrdinal: 1,
+        failureDiagnostic: "workflow_execution",
+    };
+}
+const stepPrimaryFa = {
+    summary: "Primary failure at seq 0 tool t (code ROW_ABSENT); origin: downstream_system_state.",
+    primaryOrigin: "downstream_system_state",
+    confidence: "medium",
+    unknownReasonCodes: [],
+    evidence: [{ scope: "step", seq: 0, toolId: "t", codes: ["ROW_ABSENT"] }],
+};
+beforeEach(() => {
+    vi.mocked(buildFailureAnalysis).mockReset();
+});
+describe("failure explanation invariants (mocked buildFailureAnalysis)", () => {
+    it("I1: primary evidence scope effect throws EXPLANATION_PRIMARY_EVIDENCE_SCOPE_EFFECT", () => {
+        const engine = {
+            schemaVersion: 8,
+            workflowId: "w",
+            status: "inconsistent",
+            runLevelReasons: [],
+            verificationPolicy: strongPolicy,
+            eventSequenceIntegrity: { kind: "normal" },
+            verificationRunContext: createEmptyVerificationRunContext(),
+            steps: [missingStep()],
+        };
+        vi.mocked(buildFailureAnalysis)
+            .mockImplementationOnce(() => stepPrimaryFa)
+            .mockImplementationOnce(() => ({
+            ...stepPrimaryFa,
+            evidence: [{ scope: "effect", effectId: "e1", seq: 0, codes: ["VALUE_MISMATCH"] }],
+        }));
+        try {
+            buildWorkflowTruthReport(engine);
+            expect.fail("expected throw");
+        }
+        catch (e) {
+            expect(e).toBeInstanceOf(FailureExplanationInvariantError);
+            expect(e.code).toBe("EXPLANATION_PRIMARY_EVIDENCE_SCOPE_EFFECT");
+        }
+    });
+    it("I2: empty primary codes throws EXPLANATION_EVIDENCE_CODES_EMPTY", () => {
+        const engine = {
+            schemaVersion: 8,
+            workflowId: "w",
+            status: "inconsistent",
+            runLevelReasons: [],
+            verificationPolicy: strongPolicy,
+            eventSequenceIntegrity: { kind: "normal" },
+            verificationRunContext: createEmptyVerificationRunContext(),
+            steps: [missingStep()],
+        };
+        vi.mocked(buildFailureAnalysis)
+            .mockImplementationOnce(() => stepPrimaryFa)
+            .mockImplementationOnce(() => ({
+            ...stepPrimaryFa,
+            evidence: [{ scope: "step", seq: 0, toolId: "t", codes: [] }],
+        }));
+        try {
+            buildWorkflowTruthReport(engine);
+            expect.fail("expected throw");
+        }
+        catch (e) {
+            expect(e).toBeInstanceOf(FailureExplanationInvariantError);
+            expect(e.code).toBe("EXPLANATION_EVIDENCE_CODES_EMPTY");
+        }
+    });
+    it("I4: run_context without ingestIndex throws EXPLANATION_RUN_CONTEXT_INDEX_MISSING", () => {
+        const engine = {
+            schemaVersion: 8,
+            workflowId: "w",
+            status: "inconsistent",
+            runLevelReasons: [],
+            verificationPolicy: strongPolicy,
+            eventSequenceIntegrity: { kind: "normal" },
+            verificationRunContext: createEmptyVerificationRunContext(),
+            steps: [missingStep()],
+        };
+        vi.mocked(buildFailureAnalysis)
+            .mockImplementationOnce(() => stepPrimaryFa)
+            .mockImplementationOnce(() => ({
+            ...stepPrimaryFa,
+            primaryOrigin: "retrieval",
+            evidence: [{ scope: "run_context", codes: ["RETRIEVAL_ERROR"] }],
+        }));
+        try {
+            buildWorkflowTruthReport(engine);
+            expect.fail("expected throw");
+        }
+        catch (e) {
+            expect(e).toBeInstanceOf(FailureExplanationInvariantError);
+            expect(e.code).toBe("EXPLANATION_RUN_CONTEXT_INDEX_MISSING");
+        }
+    });
+    it("G12: unknown_reason_code rows sort by value UTF-16 (AA before ZZ)", () => {
+        const fa = {
+            summary: "Run-level ingest or planning issue (MALFORMED_EVENT_LINE, ZZ, AA); origin: workflow_flow.",
+            primaryOrigin: "workflow_flow",
+            confidence: "low",
+            unknownReasonCodes: ["ZZ", "AA"],
+            evidence: [{ scope: "run_level", codes: ["MALFORMED_EVENT_LINE", "ZZ", "AA"] }],
+        };
+        const engine = {
+            schemaVersion: 8,
+            workflowId: "w",
+            status: "incomplete",
+            runLevelReasons: [
+                { code: "MALFORMED_EVENT_LINE", message: "m1" },
+                { code: "ZZ", message: "m2" },
+                { code: "AA", message: "m3" },
+            ],
+            verificationPolicy: strongPolicy,
+            eventSequenceIntegrity: { kind: "normal" },
+            verificationRunContext: createEmptyVerificationRunContext(),
+            steps: [],
+        };
+        vi.mocked(buildFailureAnalysis).mockImplementation(() => fa);
+        const truth = buildWorkflowTruthReport(engine);
+        const unknownReasonRows = truth.failureExplanation.unknowns.filter((u) => u.id === "unknown_reason_code");
+        expect(unknownReasonRows).toHaveLength(2);
+        expect(unknownReasonRows[0].value.localeCompare(unknownReasonRows[1].value)).toBeLessThan(0);
+        expect(unknownReasonRows[0].value).toContain("code=AA|");
+        expect(unknownReasonRows[1].value).toContain("code=ZZ|");
+    });
+    it("G14: run_context digest gap yields run_context_record_missing=true in observed", () => {
+        const fa = {
+            summary: "A retrieval step failed before the failing tool observation (src); origin: retrieval.",
+            primaryOrigin: "retrieval",
+            confidence: "high",
+            unknownReasonCodes: [],
+            evidence: [
+                {
+                    scope: "run_context",
+                    ingestIndex: 9,
+                    source: "src",
+                    runEventId: "r1",
+                    codes: ["RETRIEVAL_ERROR"],
+                },
+            ],
+        };
+        const engine = {
+            schemaVersion: 8,
+            workflowId: "w",
+            status: "inconsistent",
+            runLevelReasons: [],
+            verificationPolicy: strongPolicy,
+            eventSequenceIntegrity: { kind: "normal" },
+            verificationRunContext: {
+                maxWireSchemaVersion: 2,
+                retrievalEvents: [],
+                controlEvents: [],
+                modelTurnEvents: [],
+                toolSkippedEvents: [],
+                toolObservedIngestIndexBySeq: { "0": 2 },
+                firstToolObservedIngestIndex: 2,
+                hasRunCompletedControl: false,
+                lastRunEvent: { ingestIndex: 2, type: "tool_observed" },
+            },
+            steps: [missingStep()],
+        };
+        vi.mocked(buildFailureAnalysis).mockImplementation(() => fa);
+        const truth = buildWorkflowTruthReport(engine);
+        expect(truth.failureExplanation.observed).toContain("run_context_record_missing=true");
+        expect(truth.failureExplanation.observed).toContain("code=RETRIEVAL_ERROR");
+    });
+});
+//# sourceMappingURL=failureExplanation.failureAnalysisMock.test.js.map

package/dist/failureExplanation.failureAnalysisMock.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureExplanation.failureAnalysisMock.test.js","sourceRoot":"","sources":["../src/failureExplanation.failureAnalysisMock.test.ts"],"names":[],"mappings":"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"}

package/dist/failureExplanation.golden.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=failureExplanation.golden.test.d.ts.map

package/dist/failureExplanation.golden.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureExplanation.golden.test.d.ts","sourceRoot":"","sources":["../src/failureExplanation.golden.test.ts"],"names":[],"mappings":""}