@nodetool-ai/reliability-harness 0.8.1

package/dist/core/invariants/status-sets.js

@@ -0,0 +1,51 @@
+/**
+ * Shared status vocabulary for the lifecycle/terminal-uniqueness invariants.
+ * Not itself a §6 family — just the constants both modules need to stay in
+ * sync on what counts as "terminal" for a node vs. a job.
+ */
+/**
+ * `node_update` statuses that end an invocation. The kernel actor
+ * (`packages/kernel/src/actor.ts`) emits `"completed"`, `"error"`, and
+ * `"suspended"` — no node-level `"cancelled"`, since a cancelled run
+ * interrupts actors rather than walking each one to a terminal status; a
+ * `"cancelled"` node status is accepted too, for surfaces/fakes that do emit
+ * one. `"warning"` and `"running"` are deliberately excluded: `"warning"` is
+ * a mid-run aside, not a terminal status.
+ */
+export const NODE_TERMINAL_STATUSES = new Set([
+    "completed",
+    "error",
+    "failed",
+    "cancelled",
+    "suspended"
+]);
+/** `job_update` statuses that end a run. `"running"`/`"queued"` are not terminal. */
+export const JOB_TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "suspended"
+]);
+/**
+ * Terminal precedence, most to least important (`runner.ts:625`): cancel >
+ * suspend > failed > completed. Index doubles as precedence rank (lower
+ * wins).
+ */
+export const TERMINAL_PRECEDENCE = [
+    "cancelled",
+    "suspended",
+    "failed",
+    "completed"
+];
+/** Normalizes a status to the `TERMINAL_PRECEDENCE` vocabulary (`"error"` reads as `"failed"`). */
+export function canonicalTerminalStatus(status) {
+    return status === "error" ? "failed" : status;
+}
+function messageRecord(message) {
+    return message ?? {};
+}
+export function asString(message, key) {
+    const value = messageRecord(message)[key];
+    return typeof value === "string" ? value : undefined;
+}
+//# sourceMappingURL=status-sets.js.map

package/dist/core/invariants/status-sets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-sets.js","sourceRoot":"","sources":["../../../src/core/invariants/status-sets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IACjE,WAAW;IACX,OAAO;IACP,QAAQ;IACR,WAAW;IACX,WAAW;CACZ,CAAC,CAAC;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAC;IAChE,WAAW;IACX,QAAQ;IACR,WAAW;IACX,WAAW;CACZ,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,WAAW;IACX,WAAW;IACX,QAAQ;IACR,WAAW;CACZ,CAAC;AAEF,mGAAmG;AACnG,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CACpB,OAA4C;IAE5C,OAAO,OAAO,IAAI,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,OAA4C,EAC5C,GAAW;IAEX,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC"}

package/dist/core/invariants/terminal-uniqueness.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Terminal-uniqueness invariants (docs/RELIABILITY_ARCHITECTURE.md §6
+ * "Lifecycle"):
+ *
+ * - Exactly one terminal `job_update` per run, and nothing follows it on
+ *   that job's stream.
+ * - Terminal precedence is exactly cancel > suspend > failed > completed
+ *   (`runner.ts:625`) — asserted, not assumed.
+ *
+ * Split from `lifecycle.ts` (which covers the node-level running/terminal
+ * pairing) so each §6 bullet stays independently attributable.
+ *
+ * Frames a driver tagged `redundant` (see `RunFrame.redundant`) are discounted
+ * here: they are that surface's documented client-convenience repeats (the
+ * ws-server's eager "running" ack and its authoritative terminal snapshot),
+ * recognized one-by-one by the driver that speaks the protocol. Every other
+ * duplicate is untagged and therefore still a violation — which is the point
+ * of recording repeats instead of dropping them at the driver.
+ */
+import type { RunRecord } from "../record.js";
+import type { Violation } from "./types.js";
+export declare function checkTerminalUniqueness(record: RunRecord): Violation[];
+//# sourceMappingURL=terminal-uniqueness.d.ts.map

package/dist/core/invariants/terminal-uniqueness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-uniqueness.d.ts","sourceRoot":"","sources":["../../../src/core/invariants/terminal-uniqueness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAY5C,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,CAyGtE"}

package/dist/core/invariants/terminal-uniqueness.js

@@ -0,0 +1,99 @@
+import { JOB_TERMINAL_STATUSES, TERMINAL_PRECEDENCE, canonicalTerminalStatus, asString } from "./status-sets.js";
+function isCancelCommand(message) {
+    return message["command"] === "cancel_job";
+}
+export function checkTerminalUniqueness(record) {
+    const violations = [];
+    const terminalIndices = [];
+    record.frames.forEach((frame, index) => {
+        if (frame.redundant !== undefined)
+            return;
+        const message = frame.message;
+        if (asString(message, "type") !== "job_update")
+            return;
+        const status = asString(message, "status");
+        if (status !== undefined && JOB_TERMINAL_STATUSES.has(status)) {
+            terminalIndices.push(index);
+        }
+    });
+    if (terminalIndices.length === 0) {
+        violations.push({
+            invariant: "terminal-uniqueness.missing",
+            message: "no terminal job_update found in the record"
+        });
+        return violations;
+    }
+    if (terminalIndices.length > 1) {
+        violations.push({
+            invariant: "terminal-uniqueness.multiple",
+            message: `${terminalIndices.length} terminal job_update frames found (expected exactly 1)`,
+            details: { frameIndices: terminalIndices }
+        });
+    }
+    const firstTerminal = terminalIndices[0];
+    const framesAfter = record.frames
+        .slice(firstTerminal + 1)
+        .filter((frame) => frame.redundant === undefined &&
+        asString(frame.message, "type") === "job_update");
+    if (framesAfter.length > 0) {
+        violations.push({
+            invariant: "terminal-uniqueness.frames-after-terminal",
+            message: `${framesAfter.length} job_update frame(s) appear after the terminal job_update at frame ${firstTerminal}`,
+            frameIndex: firstTerminal,
+            details: { count: framesAfter.length }
+        });
+    }
+    // Terminal precedence: cancel > suspend > failed > completed.
+    const terminalMessage = record.frames[firstTerminal].message;
+    const terminalStatus = asString(terminalMessage, "status") ?? "";
+    const hasCancelRequest = record.frames.some((frame) => frame.direction === "client_to_server" &&
+        isCancelCommand(frame.message));
+    const hasSuspendedNode = record.frames.some((frame) => {
+        const message = frame.message;
+        return asString(message, "type") === "node_update" && asString(message, "status") === "suspended";
+    });
+    const hasNodeError = record.frames.some((frame) => {
+        const message = frame.message;
+        if (asString(message, "type") !== "node_update")
+            return false;
+        const status = asString(message, "status");
+        return status === "error" || status === "failed";
+    });
+    // Task D3: some failures never reach a per-node lifecycle event at all —
+    // e.g. an unresolvable executor (a Python bridge that failed to connect,
+    // `python-node-workflow`'s `bridge-never-ready`/`bridge-epipe`/
+    // `bridge-version-mismatch` faults) throws while *resolving* the node,
+    // before the actor ever emits its own `node_update running`. That's a
+    // legitimate "failed" terminal with real evidence — the terminal
+    // `job_update` itself carries a non-empty `error` string explaining why —
+    // just not evidence `hasNodeError` (a `node_update` scan) can see. Gated on
+    // `terminalStatus === "failed"` already being the actual value, so this can
+    // only ever confirm an already-"failed" terminal as expected — it can never
+    // flip what a "completed"/"cancelled"/"suspended" run expects.
+    const hasJobLevelError = terminalStatus === "failed" &&
+        typeof terminalMessage["error"] === "string" &&
+        terminalMessage["error"].trim().length > 0;
+    let expected;
+    if (hasCancelRequest)
+        expected = "cancelled";
+    else if (hasSuspendedNode)
+        expected = "suspended";
+    else if (hasNodeError || hasJobLevelError)
+        expected = "failed";
+    else
+        expected = "completed";
+    const actual = canonicalTerminalStatus(terminalStatus);
+    if (actual !== expected) {
+        violations.push({
+            invariant: "terminal-uniqueness.precedence",
+            message: `terminal job_update status is "${terminalStatus}" but precedence ` +
+                `(${TERMINAL_PRECEDENCE.join(" > ")}) expects "${expected}" given ` +
+                `the record's evidence (cancelRequest=${hasCancelRequest}, ` +
+                `suspendedNode=${hasSuspendedNode}, nodeError=${hasNodeError})`,
+            frameIndex: firstTerminal,
+            details: { actual: terminalStatus, expected, hasCancelRequest, hasSuspendedNode, hasNodeError }
+        });
+    }
+    return violations;
+}
+//# sourceMappingURL=terminal-uniqueness.js.map

package/dist/core/invariants/terminal-uniqueness.js.map

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

package/dist/core/invariants/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared shape for §6 invariant modules (docs/RELIABILITY_ARCHITECTURE.md §6,
+ * §12). Each module in this directory is a pure `(record: RunRecord) =>
+ * Violation[]` — no IO, no driver dependency, so the same check runs
+ * identically in CI, in `nodetool reliability`, and over a `RunRecord`
+ * recovered from a user's field debug bundle.
+ */
+import type { RunRecord } from "../record.js";
+export interface Violation {
+    /** Stable id for the specific rule that failed, e.g.
+     * "lifecycle.unmatched-running" or "protocol-validity.schema-mismatch" —
+     * `<module>.<rule>` so a report can group by module. */
+    invariant: string;
+    /** Human-readable explanation, safe to print directly in a report. */
+    message: string;
+    /** Index into `record.frames`, when the violation is anchored to one frame. */
+    frameIndex?: number;
+    /** Node id the violation concerns, when applicable. */
+    nodeId?: string;
+    /** Free-form extra context (offending values, counts, schema issues, …). */
+    details?: Record<string, unknown>;
+}
+/** The shape every invariant module exports. */
+export type InvariantCheck = (record: RunRecord) => Violation[];
+//# sourceMappingURL=types.d.ts.map

package/dist/core/invariants/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/invariants/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB;;4DAEwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC"}

package/dist/core/invariants/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/invariants/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/invariants/types.ts"],"names":[],"mappings":""}

package/dist/core/journey.d.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+/** Execution surfaces a journey may run on (§12 drivers). */
+export declare const journeySurfaceSchema: z.ZodEnum<{
+    "app-headless": "app-headless";
+    browser: "browser";
+    cli: "cli";
+    electron: "electron";
+    kernel: "kernel";
+    packaged: "packaged";
+    "ws-server": "ws-server";
+}>;
+export type JourneySurface = z.infer<typeof journeySurfaceSchema>;
+/**
+ * A scripted interaction. `at` names the event to anchor on (e.g.
+ * `"chunk:2"`, `"node_update:upper1:completed"`) — never a wall-clock delay,
+ * per §4's "event-anchored, not time-anchored" rule.
+ */
+export declare const journeyInteractionSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        cancel: "cancel";
+        end_input_stream: "end_input_stream";
+        reconnect: "reconnect";
+        run: "run";
+        stream_input: "stream_input";
+    }>;
+    at: z.ZodOptional<z.ZodString>;
+    nodeId: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type JourneyInteraction = z.infer<typeof journeyInteractionSchema>;
+/** One entry in the fault matrix (§9). */
+export declare const journeyFaultSchema: z.ZodObject<{
+    surface: z.ZodOptional<z.ZodEnum<{
+        "app-headless": "app-headless";
+        browser: "browser";
+        cli: "cli";
+        electron: "electron";
+        kernel: "kernel";
+        packaged: "packaged";
+        "ws-server": "ws-server";
+    }>>;
+    type: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type JourneyFault = z.infer<typeof journeyFaultSchema>;
+/**
+ * What a journey asserts beyond "the run reached a terminal status". At
+ * least one of these must be non-trivial (§4's last rule).
+ */
+export declare const journeyAssertionsSchema: z.ZodObject<{
+    invariants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    outputs: z.ZodDefault<z.ZodBoolean>;
+    streamShape: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type JourneyAssertions = z.infer<typeof journeyAssertionsSchema>;
+export declare const journeyManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strip>;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    interactions: z.ZodDefault<z.ZodString>;
+    surfaces: z.ZodArray<z.ZodEnum<{
+        "app-headless": "app-headless";
+        browser: "browser";
+        cli: "cli";
+        electron: "electron";
+        kernel: "kernel";
+        packaged: "packaged";
+        "ws-server": "ws-server";
+    }>>;
+    faults: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        surface: z.ZodOptional<z.ZodEnum<{
+            "app-headless": "app-headless";
+            browser: "browser";
+            cli: "cli";
+            electron: "electron";
+            kernel: "kernel";
+            packaged: "packaged";
+            "ws-server": "ws-server";
+        }>>;
+        type: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    assertions: z.ZodObject<{
+        invariants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        outputs: z.ZodDefault<z.ZodBoolean>;
+        streamShape: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type JourneyManifest = z.infer<typeof journeyManifestSchema>;
+export declare class JourneyValidationError extends Error {
+    readonly issues: string[];
+    constructor(message: string, issues?: string[]);
+}
+/** A fully loaded journey: manifest, graph, interactions, and expected fixtures. */
+export interface Journey {
+    dir: string;
+    manifest: JourneyManifest;
+    workflow: Record<string, unknown>;
+    interactions: JourneyInteraction[];
+    expected: {
+        streamShape: unknown | null;
+        outputs: unknown | null;
+    };
+}
+/** True when a manifest asserts something beyond "completed" (§4's last rule). */
+export declare function assertsSomething(assertions: JourneyAssertions): boolean;
+/**
+ * Parses and validates a raw `journey.json` payload. Split out from
+ * {@link loadJourney} so the "asserts nothing" rejection is unit-testable
+ * without touching the filesystem.
+ */
+export declare function parseJourneyManifest(raw: unknown): JourneyManifest;
+/** Loads and validates a journey directory (§4 layout). */
+export declare function loadJourney(journeyDir: string): Promise<Journey>;
+/** Directory a journey ref lives in, given its manifest path — small helper for drivers. */
+export declare function journeyDirOf(manifestPath: string): string;
+//# sourceMappingURL=journey.d.ts.map

package/dist/core/journey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey.d.ts","sourceRoot":"","sources":["../../src/core/journey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB;;;;;;;;EAQ/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;iBAWnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,0CAA0C;AAC1C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;iBAK7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;iBAOlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAchC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE;IAF3B,YACE,OAAO,EAAE,MAAM,EACN,MAAM,GAAE,MAAM,EAAO,EAI/B;CACF;AAED,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,QAAQ,EAAE;QACR,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;QAC5B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;KACzB,CAAC;CACH;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAMvE;AAWD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAgBlE;AAED,2DAA2D;AAC3D,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8DtE;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/core/journey.js

@@ -0,0 +1,166 @@
+/**
+ * Journey manifest loader (docs/RELIABILITY_ARCHITECTURE.md §4).
+ *
+ * A journey is a directory under `reliability/journeys/<name>/` carrying
+ * `journey.json` (the manifest), `workflow.json` (or a ref to a shipped
+ * example), `interactions.json` (scripted actions), and `expected/` (the
+ * normalized stream shape + terminal outputs a passing run must match).
+ *
+ * The loader is Zod-validated and refuses a journey that asserts nothing
+ * beyond "completed" — every journey must declare at least one invariant
+ * family, or opt into an outputs/stream-shape comparison (§4's last rule).
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+/** Execution surfaces a journey may run on (§12 drivers). */
+export const journeySurfaceSchema = z.enum([
+    "kernel",
+    "ws-server",
+    "cli",
+    "browser",
+    "app-headless",
+    "packaged",
+    "electron"
+]);
+/**
+ * A scripted interaction. `at` names the event to anchor on (e.g.
+ * `"chunk:2"`, `"node_update:upper1:completed"`) — never a wall-clock delay,
+ * per §4's "event-anchored, not time-anchored" rule.
+ */
+export const journeyInteractionSchema = z.object({
+    action: z.enum([
+        "run",
+        "cancel",
+        "stream_input",
+        "end_input_stream",
+        "reconnect"
+    ]),
+    at: z.string().optional(),
+    nodeId: z.string().optional(),
+    value: z.unknown().optional()
+});
+/** One entry in the fault matrix (§9). */
+export const journeyFaultSchema = z.object({
+    /** Restrict the fault to one surface; omitted = every surface that runs it. */
+    surface: journeySurfaceSchema.optional(),
+    type: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).optional()
+});
+/**
+ * What a journey asserts beyond "the run reached a terminal status". At
+ * least one of these must be non-trivial (§4's last rule).
+ */
+export const journeyAssertionsSchema = z.object({
+    /** §6 invariant family names (e.g. "lifecycle-pairing", "terminal-uniqueness"). */
+    invariants: z.array(z.string()).default([]),
+    /** Compare terminal outputs against `expected/outputs.json`. */
+    outputs: z.boolean().default(false),
+    /** Compare the normalized message stream against `expected/stream.shape.json`. */
+    streamShape: z.boolean().default(false)
+});
+export const journeyManifestSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+    workflow: z.object({
+        /** Path to a workflow JSON file (relative to the journey dir), or a shipped-example ref. */
+        ref: z.string().min(1)
+    }),
+    params: z.record(z.string(), z.unknown()).default({}),
+    /** Filename (relative to the journey dir) carrying scripted interactions. */
+    interactions: z.string().default("interactions.json"),
+    surfaces: z.array(journeySurfaceSchema).min(1),
+    faults: z.array(journeyFaultSchema).default([]),
+    timeoutMs: z.number().positive().default(30000),
+    assertions: journeyAssertionsSchema
+});
+export class JourneyValidationError extends Error {
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.issues = issues;
+        this.name = "JourneyValidationError";
+    }
+}
+/** True when a manifest asserts something beyond "completed" (§4's last rule). */
+export function assertsSomething(assertions) {
+    return (assertions.invariants.length > 0 ||
+        assertions.outputs ||
+        assertions.streamShape);
+}
+async function readJsonIfExists(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Parses and validates a raw `journey.json` payload. Split out from
+ * {@link loadJourney} so the "asserts nothing" rejection is unit-testable
+ * without touching the filesystem.
+ */
+export function parseJourneyManifest(raw) {
+    const result = journeyManifestSchema.safeParse(raw);
+    if (!result.success) {
+        throw new JourneyValidationError("journey.json failed schema validation", result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`));
+    }
+    if (!assertsSomething(result.data.assertions)) {
+        throw new JourneyValidationError(`journey "${result.data.name}" asserts nothing beyond "completed" — ` +
+            "declare at least one invariant family (assertions.invariants), or " +
+            "opt into assertions.outputs / assertions.streamShape (§4).");
+    }
+    return result.data;
+}
+/** Loads and validates a journey directory (§4 layout). */
+export async function loadJourney(journeyDir) {
+    const dir = resolve(journeyDir);
+    const manifestPath = join(dir, "journey.json");
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new JourneyValidationError(`no journey.json in ${dir}`);
+        }
+        throw err;
+    }
+    const manifest = parseJourneyManifest(raw);
+    const workflowPath = resolve(dir, manifest.workflow.ref);
+    const workflow = JSON.parse(await readFile(workflowPath, "utf8"));
+    const interactionsPath = join(dir, manifest.interactions);
+    const interactionsRaw = await readJsonIfExists(interactionsPath);
+    const interactionsResult = z
+        .array(journeyInteractionSchema)
+        .safeParse(interactionsRaw ?? []);
+    if (!interactionsResult.success) {
+        throw new JourneyValidationError(`${interactionsPath} failed schema validation`, interactionsResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`));
+    }
+    const expectedDir = join(dir, "expected");
+    const streamShape = await readJsonIfExists(join(expectedDir, "stream.shape.json"));
+    const outputs = await readJsonIfExists(join(expectedDir, "outputs.json"));
+    if (manifest.assertions.streamShape && streamShape === null) {
+        throw new JourneyValidationError(`journey "${manifest.name}" declares assertions.streamShape but has no ` +
+            "expected/stream.shape.json");
+    }
+    if (manifest.assertions.outputs && outputs === null) {
+        throw new JourneyValidationError(`journey "${manifest.name}" declares assertions.outputs but has no ` +
+            "expected/outputs.json");
+    }
+    return {
+        dir,
+        manifest,
+        workflow,
+        interactions: interactionsResult.data,
+        expected: { streamShape, outputs }
+    };
+}
+/** Directory a journey ref lives in, given its manifest path — small helper for drivers. */
+export function journeyDirOf(manifestPath) {
+    return dirname(manifestPath);
+}
+//# sourceMappingURL=journey.js.map

package/dist/core/journey.js.map

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

package/dist/core/normalize.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Stream normalization (§4, §12): strips/canonicalizes timestamps, remaps
+ * ids (job/node/edge/asset ids) to stable placeholders, and canonicalizes
+ * durations and asset URLs, so two runs of the same journey on different
+ * surfaces — with different job ids, different wall-clock timing, different
+ * asset storage paths — normalize to the same shape and diff clean.
+ *
+ * Declarative: the field lists below are the whole policy. A driver that
+ * needs an extra field normalized adds it here, once, for every consumer
+ * (diff, invariants, `nodetool reliability`).
+ */
+import type { RunFrame, RunRecord } from "./record.js";
+/** Field names (anywhere in a message, at any depth) treated as ids that get
+ * remapped to a stable `<class:N>` placeholder, keyed by their remap class. */
+export declare const ID_FIELD_CLASSES: Readonly<Record<string, string>>;
+/** Field names replaced wholesale with `<ts>` — the value never matters, only presence. */
+export declare const TIMESTAMP_FIELDS: readonly string[];
+/** Field names replaced wholesale with `<duration>`. */
+export declare const DURATION_FIELDS: readonly string[];
+/**
+ * Field values treated as interchangeable "nothing here" signals (added by
+ * C2): a node with zero declared `@prop` fields (the harness's own fixture
+ * nodes in `drivers/fixture-nodes.ts` — no shipped node has none) serializes
+ * its `properties` as `null` on the raw kernel stream but as `{}` once
+ * relayed through the ws-server. Canonicalizing `null` to `{}` for these
+ * keys make the two the same "no properties" value.
+ */
+export declare const NULLABLE_OBJECT_FIELDS: readonly string[];
+/**
+ * Top-level fields the WebSocket transport stamps on a frame so a dropped
+ * client can replay what it missed (`job-run-registry.ts`,
+ * `chat-turn-registry.ts`). They describe the delivery, not the run, and the
+ * raw kernel stream has no counterpart — dropped from the comparison view so
+ * a resumable surface still diffs clean against a non-resumable one.
+ */
+export declare const TRANSPORT_ONLY_FIELDS: readonly string[];
+/**
+ * Node type prefixes whose `node_update`/`generation_complete` frames are
+ * dropped from comparison (added by C2). This mirrors a real, documented,
+ * intentional ws-server behavior (`websocket-client-session.ts`: "Skip
+ * messages for constant/input nodes — they produce trivial outputs that
+ * don't need to be relayed to the frontend") that the raw kernel stream has
+ * no equivalent for — the kernel emits every node's lifecycle unconditionally.
+ * Normalizing both sides down to what a real frontend actually receives is
+ * the honest comparison; dropping the frames here (not filtering in
+ * `diff.ts`) keeps the diff itself surface-agnostic.
+ */
+export declare const TRIVIAL_NODE_TYPE_PREFIXES: readonly string[];
+/**
+ * Assigns each distinct original id value a stable, order-of-first-sight
+ * placeholder within one normalization pass. Two records normalized
+ * independently line up as long as ids first appear in the same relative
+ * order — which is exactly the "same journey, different surface" case this
+ * exists for.
+ */
+export declare class IdMapper {
+    private readonly maps;
+    placeholderFor(cls: string, value: string): string;
+}
+/** Normalizes one message (a frame's payload) in place-equivalent (returns a new object). */
+export declare function normalizeMessage(message: Record<string, unknown>, mapper: IdMapper): Record<string, unknown>;
+export interface NormalizedRunFrame {
+    seq: number;
+    channel: string;
+    direction: RunFrame["direction"];
+    surface: string;
+    message: Record<string, unknown>;
+}
+export interface NormalizedRunRecord {
+    journeyId?: string;
+    surface: string;
+    status: string;
+    error: string | null;
+    jobId: string | null;
+    workflowId: string | null;
+    frames: NormalizedRunFrame[];
+}
+/**
+ * Normalizes a whole `RunRecord`: every frame's message, plus the record's
+ * own `jobId`/`workflowId` (through the same mapper, so they match the
+ * placeholders used inside the frames). `startedAt`/`finishedAt`/`durationMs`
+ * are dropped — wall-clock fields carry no comparison value once
+ * normalized, per §4.
+ */
+export declare function normalizeRunRecord(record: RunRecord, mapper?: IdMapper): NormalizedRunRecord;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/core/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/core/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD;+EAC+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7D,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAK7C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAI5C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAmB,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAGlD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAGvD,CAAC;AAqBF;;;;;;GAMG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;IAE/D,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYjD;CACF;AA+CD,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,QAAQ,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,GAAE,QAAyB,GAChC,mBAAmB,CA+BrB"}