@typeonce/effect-machine 0.3.0 → 0.5.0

package/dist/internal/testing/machine/runtime.js

@@ -0,0 +1,726 @@
+/**
+ * Effect-native command-model testing for live machine references.
+ *
+ * @since 0.4.0
+ */
+import * as Cause from "effect/Cause";
+import * as Data from "effect/Data";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Inspectable from "effect/Inspectable";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import { FastCheck, TestClock } from "effect/testing";
+import * as Machine from "../../../Machine.js";
+import { toArbitraryWithReport } from "./arbitrary.js";
+import { assertRuntimeInvariants } from "./runtimeInvariant.js";
+/**
+ * Constructs a command that sends one public event.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const sendCommand = (event) => ({
+    _tag: "Send",
+    event
+});
+/**
+ * Constructs a command that advances Effect's `TestClock`.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const advanceCommand = (duration) => ({
+    _tag: "Advance",
+    duration
+});
+/**
+ * Constructs an idempotent command that stops the machine.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const stopCommand = () => ({ _tag: "Stop" });
+/**
+ * Constructs a no-op command used to synchronize with work enqueued by earlier
+ * commands. Its behavior is selected by the reference-model step.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const checkpointCommand = (label) => ({
+    _tag: "Checkpoint",
+    label
+});
+/**
+ * Constructors for runtime synchronization policies.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const RuntimeSynchronization = {
+    none: { _tag: "None" },
+    current: { _tag: "Current" },
+    next: { _tag: "Next" },
+    until: (predicate) => ({ _tag: "Until", predicate })
+};
+/**
+ * Failure raised when an expected public change stream observation is absent.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export class RuntimeObservationError extends Data.TaggedError("MachineTestRuntimeObservationError") {
+}
+/**
+ * A typed command-model failure retaining the successfully checked prefix.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export class RuntimeCommandFailure extends Data.TaggedError("MachineTestRuntimeCommandFailure") {
+}
+/**
+ * A typed causal command-model failure retaining the successfully checked
+ * prefix and exact attempted command.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export class CausalRuntimeCommandFailure extends Data.TaggedError("MachineTestCausalRuntimeCommandFailure") {
+}
+const makeFailure = (options) => new RuntimeCommandFailure({
+    ...options,
+    prefix: options.prefix.slice(),
+    attempted: options.attempted
+});
+const executeCommand = (ref, command) => {
+    switch (command._tag) {
+        case "Send":
+            return ref.send(command.event).pipe(Effect.match({
+                onFailure: (error) => ({ _tag: "SendRejected", error }),
+                onSuccess: () => ({ _tag: "SendAccepted" })
+            }));
+        case "Advance":
+            return TestClock.adjust(command.duration).pipe(Effect.as({ _tag: "ClockAdvanced" }));
+        case "Stop":
+            return ref.stop.pipe(Effect.as({ _tag: "Stopped" }));
+        case "Checkpoint":
+            return Effect.succeed({ _tag: "Checkpoint" });
+    }
+};
+const synchronize = (ref, queue, policy, index, timeout) => {
+    const wait = (synchronization, effect) => TestClock.withLive(effect.pipe(Effect.timeout(timeout))).pipe(Effect.mapError((cause) => cause instanceof RuntimeObservationError
+        ? cause
+        : new RuntimeObservationError({
+            index,
+            synchronization,
+            reason: "timeout",
+            message: `timed out after ${Duration.toMillis(timeout)}ms waiting for the expected published snapshot`
+        })));
+    switch (policy._tag) {
+        case "None":
+            return Effect.succeed({ snapshot: undefined, published: [] });
+        case "Current":
+            return ref.snapshot.pipe(Effect.map((snapshot) => ({ snapshot, published: [] })));
+        case "Next":
+            return wait("Next", Queue.take(queue).pipe(Effect.flatMap((entry) => entry._tag === "Snapshot"
+                ? Effect.succeed({ snapshot: entry.snapshot, published: [entry.snapshot] })
+                : Effect.fail(new RuntimeObservationError({
+                    index,
+                    synchronization: "Next",
+                    reason: "ended",
+                    message: "the machine changes stream ended before publishing the expected snapshot"
+                })))));
+        case "Until":
+            return wait("Until", Effect.gen(function* () {
+                const published = [];
+                while (true) {
+                    const entry = yield* Queue.take(queue);
+                    if (entry._tag === "End") {
+                        return yield* Effect.fail(new RuntimeObservationError({
+                            index,
+                            synchronization: "Until",
+                            reason: "ended",
+                            message: "the machine changes stream ended before a published snapshot matched the predicate"
+                        }));
+                    }
+                    published.push(entry.snapshot);
+                    if (policy.predicate(entry.snapshot)) {
+                        return { snapshot: entry.snapshot, published };
+                    }
+                }
+            }));
+    }
+};
+const executeCausalCommand = (probe, command) => {
+    switch (command._tag) {
+        case "Send":
+            return Effect.matchEffect(probe.sendAndAwait(command.event), {
+                onFailure: (error) => error instanceof Machine.StoppedError
+                    ? probe.ref.snapshot.pipe(Effect.flatMap((snapshot) => snapshot.status === "stopped"
+                        ? Effect.succeed({ _tag: "SendRejected", error })
+                        : Effect.fail(error)))
+                    : Effect.fail(error),
+                onSuccess: (step) => Effect.succeed({ _tag: "SendProcessed", step })
+            });
+        case "Advance":
+            return TestClock.adjust(command.duration).pipe(Effect.as({ _tag: "ClockAdvanced" }));
+        case "Stop":
+            return probe.ref.stop.pipe(Effect.as({ _tag: "Stopped" }));
+        case "Checkpoint":
+            return Effect.succeed({ _tag: "Checkpoint" });
+    }
+};
+const awaitCausal = (ref, policy, index, timeout) => {
+    if (policy._tag === "None") {
+        return ref.snapshot.pipe(Effect.map((snapshot) => ({ snapshot, awaited: [] })));
+    }
+    const observation = Effect.scoped(Effect.gen(function* () {
+        const changes = yield* Queue.unbounded();
+        yield* ref.changes.pipe(Stream.runForEach((snapshot) => Queue.offer(changes, { _tag: "Snapshot", snapshot })), Effect.ensuring(Queue.offer(changes, { _tag: "End" })), Effect.forkScoped({ startImmediately: true }));
+        const awaited = [];
+        while (true) {
+            const entry = yield* Queue.take(changes);
+            if (entry._tag === "End") {
+                return yield* Effect.fail(new RuntimeObservationError({
+                    index,
+                    synchronization: "Until",
+                    reason: "ended",
+                    message: "the machine changes stream ended before an awaited snapshot matched the predicate"
+                }));
+            }
+            awaited.push(entry.snapshot);
+            if (policy.predicate(entry.snapshot))
+                return { snapshot: entry.snapshot, awaited };
+        }
+    }));
+    return TestClock.withLive(observation.pipe(Effect.timeout(timeout))).pipe(Effect.mapError((cause) => cause instanceof RuntimeObservationError
+        ? cause
+        : new RuntimeObservationError({
+            index,
+            synchronization: "Until",
+            reason: "timeout",
+            message: `timed out after ${Duration.toMillis(timeout)}ms waiting for an awaited runtime snapshot`
+        })));
+};
+/**
+ * Runs typed commands against a live `MachineRef` and checks them against a
+ * supplied Effect-native reference model.
+ *
+ * The runner observes only public `MachineRef` behavior. In particular, a
+ * successful send means enqueue acceptance, not completed processing. A model
+ * must request `Next`/`Until` only when it predicts a publication, or use an
+ * explicit checkpoint to drain previously enqueued work. Machine emissions can
+ * be captured by the runtime service used by the machine and returned from the
+ * optional `inspect` effect.
+ *
+ * Typed failures and defects from model transitions, command execution,
+ * inspection, and assertions are retained as full `Cause` values. A cause
+ * containing only interruption is propagated as interruption so cancelling a
+ * property run cannot be mistaken for a machine counterexample.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const runEnqueuedCommands = (ref, commands, options) => Effect.scoped(Effect.gen(function* () {
+    const sequence = Array.from(commands);
+    const observationTimeout = options.observationTimeout ?? "1 second";
+    const observationTimeoutMillis = Duration.toMillis(observationTimeout);
+    if (!Number.isFinite(observationTimeoutMillis) || observationTimeoutMillis < 0) {
+        return yield* Effect.die(new Error("MachineTest.runEnqueuedCommands expected observationTimeout to be a finite non-negative duration"));
+    }
+    const changes = yield* Queue.unbounded();
+    const ready = yield* Deferred.make();
+    yield* ref.changes.pipe(Stream.runForEach((snapshot) => Queue.offer(changes, { _tag: "Snapshot", snapshot }).pipe(Effect.andThen(Deferred.succeed(ready, undefined)), Effect.asVoid)), Effect.ensuring(Deferred.succeed(ready, undefined).pipe(Effect.andThen(Queue.offer(changes, { _tag: "End" })), Effect.asVoid)), Effect.forkScoped({ startImmediately: true }));
+    yield* Deferred.await(ready);
+    const initialEntry = yield* Queue.take(changes);
+    const initial = initialEntry._tag === "Snapshot" ? initialEntry.snapshot : yield* ref.snapshot;
+    const records = [];
+    let model = options.initialModel;
+    let lastSynchronized = initial;
+    let outstandingWorkUnknown = false;
+    const capture = (options) => Effect.catchCause(Effect.suspend(options.effect), (cause) => Cause.hasInterruptsOnly(cause)
+        ? Effect.failCause(cause)
+        : Effect.fail(makeFailure({
+            phase: options.phase,
+            index: options.index,
+            command: options.command,
+            cause,
+            prefix: records,
+            ...(options.attempted === undefined ? {} : { attempted: options.attempted })
+        })));
+    for (let index = 0; index < sequence.length; index++) {
+        const command = sequence[index];
+        const step = yield* capture({
+            phase: "model",
+            index,
+            command,
+            effect: () => options.transition(model, command, index)
+        });
+        model = step.model;
+        const result = yield* capture({
+            phase: "execution",
+            index,
+            command,
+            effect: () => executeCommand(ref, command)
+        });
+        const attemptedBeforeObservation = {
+            index,
+            command,
+            model,
+            expected: step.expected,
+            actual: {
+                result,
+                snapshot: undefined,
+                published: [],
+                inspected: undefined
+            }
+        };
+        const synchronized = yield* capture({
+            phase: "observation",
+            index,
+            command,
+            effect: () => synchronize(ref, changes, step.synchronize, index, observationTimeout),
+            attempted: attemptedBeforeObservation
+        });
+        const terminal = synchronized.snapshot !== undefined && synchronized.snapshot.status !== "active";
+        const previouslyOutstanding = outstandingWorkUnknown;
+        switch (step.synchronize._tag) {
+            case "None":
+                if (command._tag === "Advance" || command._tag === "Stop" ||
+                    (command._tag === "Send" && result._tag === "SendAccepted"))
+                    outstandingWorkUnknown = true;
+                break;
+            case "Next":
+                if (synchronized.snapshot !== undefined)
+                    lastSynchronized = synchronized.snapshot;
+                outstandingWorkUnknown = terminal
+                    ? false
+                    : previouslyOutstanding || command._tag === "Advance" ||
+                        (command._tag === "Send" && result._tag === "SendAccepted");
+                break;
+            case "Until":
+                if (synchronized.snapshot !== undefined)
+                    lastSynchronized = synchronized.snapshot;
+                outstandingWorkUnknown = false;
+                break;
+            case "Current":
+                if (terminal)
+                    outstandingWorkUnknown = false;
+                if (!outstandingWorkUnknown && synchronized.snapshot !== undefined)
+                    lastSynchronized = synchronized.snapshot;
+                break;
+        }
+        const inspectionContext = {
+            index,
+            command,
+            result,
+            ref,
+            snapshot: synchronized.snapshot,
+            published: synchronized.published
+        };
+        const attemptedBeforeInspection = {
+            ...attemptedBeforeObservation,
+            actual: {
+                result,
+                snapshot: synchronized.snapshot,
+                published: synchronized.published,
+                inspected: undefined
+            }
+        };
+        const inspected = options.inspect === undefined
+            ? undefined
+            : yield* capture({
+                phase: "inspection",
+                index,
+                command,
+                effect: () => options.inspect(inspectionContext),
+                attempted: attemptedBeforeInspection
+            });
+        const actual = {
+            result,
+            snapshot: synchronized.snapshot,
+            published: synchronized.published,
+            inspected
+        };
+        const record = {
+            index,
+            command,
+            model,
+            expected: step.expected,
+            actual
+        };
+        yield* capture({
+            phase: "assertion",
+            index,
+            command,
+            effect: () => options.assert({
+                ...inspectionContext,
+                model,
+                expected: step.expected,
+                actual
+            }),
+            attempted: record
+        });
+        records.push(record);
+    }
+    return {
+        commands: sequence,
+        initial,
+        records,
+        finalModel: model,
+        final: lastSynchronized,
+        synchronized: !outstandingWorkUnknown
+    };
+}));
+/**
+ * Compatibility alias for enqueue-oriented runtime command execution.
+ *
+ * @deprecated Use `runEnqueuedCommands`. This compatibility name does not
+ * expose whether sends are merely enqueued or causally processed.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const runRuntimeCommands = runEnqueuedCommands;
+/**
+ * Runs typed commands against a probe and checks them against an Effect-native
+ * reference model.
+ *
+ * Every accepted `Send` completes its exact managed runtime macrostep before
+ * inspection, assertion, and the next command. Use `probe.await.until` only
+ * for later asynchronous work such as timer, invoke, or child delivery.
+ * Processing failures are attributed to the exact submitted command and retain
+ * the successfully checked prefix for FastCheck shrinking and replay.
+ *
+ * Use `runEnqueuedCommands` instead when the behavior under test intentionally
+ * depends on burst enqueueing or outstanding mailbox work.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const runCausalCommands = (probe, commands, options) => Effect.gen(function* () {
+    const sequence = Array.from(commands);
+    const observationTimeout = options.observationTimeout ?? "1 second";
+    const observationTimeoutMillis = Duration.toMillis(observationTimeout);
+    if (!Number.isFinite(observationTimeoutMillis) || observationTimeoutMillis < 0) {
+        return yield* Effect.die(new Error("MachineTest.runCausalCommands expected observationTimeout to be a finite non-negative duration"));
+    }
+    const initial = yield* probe.ref.snapshot;
+    const records = [];
+    let model = options.initialModel;
+    let final = initial;
+    const capture = (captureOptions) => Effect.catchCause(Effect.suspend(captureOptions.effect), (cause) => Cause.hasInterruptsOnly(cause)
+        ? Effect.failCause(cause)
+        : Effect.fail(new CausalRuntimeCommandFailure({
+            phase: captureOptions.phase,
+            index: captureOptions.index,
+            command: captureOptions.command,
+            cause,
+            prefix: records.slice(),
+            attempted: captureOptions.attempted
+        })));
+    for (let index = 0; index < sequence.length; index++) {
+        const command = sequence[index];
+        const step = yield* capture({
+            phase: "model",
+            index,
+            command,
+            effect: () => options.transition(model, command, index)
+        });
+        model = step.model;
+        const attemptedBeforeExecution = {
+            index,
+            command,
+            model,
+            expected: step.expected,
+            result: undefined,
+            snapshot: undefined,
+            awaited: [],
+            inspected: undefined
+        };
+        const result = yield* capture({
+            phase: "execution",
+            index,
+            command,
+            effect: () => executeCausalCommand(probe, command),
+            attempted: attemptedBeforeExecution
+        });
+        const attemptedAfterExecution = {
+            ...attemptedBeforeExecution,
+            result
+        };
+        const observation = yield* capture({
+            phase: "observation",
+            index,
+            command,
+            effect: () => awaitCausal(probe.ref, step.await ?? { _tag: "None" }, index, observationTimeout),
+            attempted: attemptedAfterExecution
+        });
+        final = observation.snapshot;
+        const inspectionContext = {
+            index,
+            command,
+            result,
+            probe,
+            ref: probe.ref,
+            snapshot: observation.snapshot,
+            awaited: observation.awaited
+        };
+        const attemptedAfterObservation = {
+            ...attemptedAfterExecution,
+            snapshot: observation.snapshot,
+            awaited: observation.awaited
+        };
+        const inspected = options.inspect === undefined
+            ? undefined
+            : yield* capture({
+                phase: "inspection",
+                index,
+                command,
+                effect: () => options.inspect(inspectionContext),
+                attempted: attemptedAfterObservation
+            });
+        const actual = {
+            result,
+            snapshot: observation.snapshot,
+            awaited: observation.awaited,
+            inspected
+        };
+        const record = {
+            index,
+            command,
+            model,
+            expected: step.expected,
+            actual
+        };
+        yield* capture({
+            phase: "assertion",
+            index,
+            command,
+            effect: () => options.assert({
+                ...inspectionContext,
+                model,
+                expected: step.expected,
+                actual
+            }),
+            attempted: {
+                ...attemptedAfterObservation,
+                inspected
+            }
+        });
+        records.push(record);
+    }
+    return {
+        commands: sequence,
+        initial,
+        records,
+        finalModel: model,
+        final
+    };
+});
+/**
+ * Causally executes commands and checks reusable runtime invariants without
+ * requiring a dummy reference model. Use `runCausalCommands` when exact
+ * expected results come from an application model.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const verifyCausalCommands = (probe, commands, options) => Effect.gen(function* () {
+    const transcript = yield* runCausalCommands(probe, commands, {
+        initialModel: undefined,
+        ...(options.observationTimeout === undefined ? {} : { observationTimeout: options.observationTimeout }),
+        transition: (_model, command, index) => Effect.sync(() => ({
+            model: undefined,
+            expected: undefined,
+            ...(options.await === undefined ? {} : { await: options.await({ index, command, probe }) })
+        })),
+        assert: () => Effect.void
+    });
+    const evidence = {
+        commands: transcript.commands,
+        initial: transcript.initial,
+        records: transcript.records.map(({ actual, command, index }) => ({ index, command, actual })),
+        final: transcript.final
+    };
+    yield* assertRuntimeInvariants(probe.machine, evidence, options.invariants);
+    return evidence;
+});
+const validateCommandLength = (name, value) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`MachineTest.runtimeCommands expected ${name} to be a non-negative safe integer`);
+    }
+};
+/**
+ * Derives a shrinkable command sequence from public event schemas and explicit
+ * clock/stop/checkpoint command choices.
+ *
+ * This deliberately returns ordinary Effect FastCheck arbitraries instead of
+ * adapting the runner through `asyncModelRun`: the latter requires Promise
+ * callbacks and would erase Effect error and service channels.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const runtimeCommands = (machine, options = {}) => {
+    const minCommands = options.minCommands ?? 0;
+    const maxCommands = options.maxCommands ?? 50;
+    validateCommandLength("minCommands", minCommands);
+    validateCommandLength("maxCommands", maxCommands);
+    if (minCommands > maxCommands) {
+        throw new Error("MachineTest.runtimeCommands expected minCommands to be less than or equal to maxCommands");
+    }
+    const reports = [];
+    const eventArbitraries = options.eventArbitrary === undefined
+        ? machine.events.map((schema) => {
+            const derived = toArbitraryWithReport(schema);
+            reports.push(derived.report);
+            return derived.value;
+        })
+        : [];
+    const eventArbitrary = options.eventArbitrary ?? (eventArbitraries.length === 0
+        ? undefined
+        : FastCheck.oneof(...eventArbitraries));
+    const commandArbitraries = [];
+    if (eventArbitrary !== undefined)
+        commandArbitraries.push(eventArbitrary.map(sendCommand));
+    if (options.includeAdvance !== false) {
+        const advanceArbitrary = options.advanceArbitrary ?? FastCheck.nat({ max: 60_000 });
+        commandArbitraries.push(advanceArbitrary.map(advanceCommand));
+    }
+    if (options.includeStop !== false)
+        commandArbitraries.push(FastCheck.constant(stopCommand()));
+    if (options.includeCheckpoint !== false)
+        commandArbitraries.push(FastCheck.constant(checkpointCommand()));
+    commandArbitraries.push(...options.additionalCommands ?? []);
+    if (commandArbitraries.length === 0) {
+        if (minCommands > 0) {
+            throw new Error("MachineTest.runtimeCommands cannot generate a non-empty command sequence without commands");
+        }
+        return {
+            arbitrary: FastCheck.constant([]),
+            diagnostics: {
+                events: options.eventArbitrary !== undefined ? "override" : eventArbitraries.length === 0 ? "none" : "schema",
+                schemaReports: reports,
+                includesAdvance: false,
+                includesStop: false,
+                includesCheckpoint: false
+            }
+        };
+    }
+    return {
+        arbitrary: FastCheck.array(FastCheck.oneof(...commandArbitraries), {
+            minLength: minCommands,
+            maxLength: maxCommands
+        }),
+        diagnostics: {
+            events: options.eventArbitrary !== undefined ? "override" : eventArbitraries.length === 0 ? "none" : "schema",
+            schemaReports: reports,
+            includesAdvance: options.includeAdvance !== false,
+            includesStop: options.includeStop !== false,
+            includesCheckpoint: options.includeCheckpoint !== false
+        }
+    };
+};
+/**
+ * Formats a runtime transcript or failure as replayable line-oriented evidence.
+ *
+ * @category formatting
+ * @since 0.4.0
+ */
+export const formatEnqueuedTranscript = (value) => {
+    const failure = value instanceof RuntimeCommandFailure;
+    const records = failure ? value.prefix : value.records;
+    const lines = [
+        `commands: ${Inspectable.toStringUnknown(failure ?
+            [
+                ...value.prefix.map((record) => record.command),
+                value.command
+            ] :
+            value.commands, 0)}`
+    ];
+    for (const record of records) {
+        lines.push(`command ${record.index}: command=${Inspectable.toStringUnknown(record.command, 0)} ` +
+            `model=${Inspectable.toStringUnknown(record.model, 0)} ` +
+            `expected=${Inspectable.toStringUnknown(record.expected, 0)} ` +
+            `result=${Inspectable.toStringUnknown(record.actual.result, 0)} ` +
+            `snapshot=${Inspectable.toStringUnknown(record.actual.snapshot, 0)} ` +
+            `published=${Inspectable.toStringUnknown(record.actual.published, 0)} ` +
+            `inspected=${Inspectable.toStringUnknown(record.actual.inspected, 0)}`);
+    }
+    if (failure) {
+        if (value.attempted !== undefined) {
+            lines.push(`attempted ${value.attempted.index}: command=${Inspectable.toStringUnknown(value.attempted.command, 0)} ` +
+                `model=${Inspectable.toStringUnknown(value.attempted.model, 0)} ` +
+                `expected=${Inspectable.toStringUnknown(value.attempted.expected, 0)} ` +
+                `result=${Inspectable.toStringUnknown(value.attempted.actual.result, 0)} ` +
+                `snapshot=${Inspectable.toStringUnknown(value.attempted.actual.snapshot, 0)} ` +
+                `published=${Inspectable.toStringUnknown(value.attempted.actual.published, 0)} ` +
+                `inspected=${Inspectable.toStringUnknown(value.attempted.actual.inspected, 0)}`);
+        }
+        lines.push(`failure: phase=${value.phase} index=${value.index} command=${Inspectable.toStringUnknown(value.command, 0)} ` +
+            `cause=${Inspectable.toStringUnknown(value.cause, 0)}`);
+    }
+    else {
+        lines.push(`final: synchronized=${String(value.synchronized)} snapshot=${Inspectable.toStringUnknown(value.final, 0)}`);
+    }
+    return lines.join("\n");
+};
+/**
+ * Compatibility alias for enqueue-oriented transcript formatting.
+ *
+ * @deprecated Use `formatEnqueuedTranscript`.
+ *
+ * @category formatting
+ * @since 0.4.0
+ */
+export const formatRuntimeTranscript = formatEnqueuedTranscript;
+/**
+ * Formats a causal runtime transcript or failure as replayable line-oriented
+ * evidence, including exact probe steps and explicit asynchronous observations.
+ *
+ * @category formatting
+ * @since 0.4.0
+ */
+export const formatCausalTranscript = (value) => {
+    const failure = value instanceof CausalRuntimeCommandFailure;
+    const records = failure ? value.prefix : value.records;
+    const lines = [
+        `commands: ${Inspectable.toStringUnknown(failure
+            ? [
+                ...value.prefix.map((record) => record.command),
+                value.command
+            ]
+            : value.commands, 0)}`
+    ];
+    for (const record of records) {
+        lines.push(`command ${record.index}: command=${Inspectable.toStringUnknown(record.command, 0)} ` +
+            `model=${Inspectable.toStringUnknown(record.model, 0)} ` +
+            `expected=${Inspectable.toStringUnknown(record.expected, 0)} ` +
+            `result=${Inspectable.toStringUnknown(record.actual.result, 0)} ` +
+            `snapshot=${Inspectable.toStringUnknown(record.actual.snapshot, 0)} ` +
+            `awaited=${Inspectable.toStringUnknown(record.actual.awaited, 0)} ` +
+            `inspected=${Inspectable.toStringUnknown(record.actual.inspected, 0)}`);
+    }
+    if (failure) {
+        if (value.attempted !== undefined) {
+            lines.push(`attempted ${value.attempted.index}: command=${Inspectable.toStringUnknown(value.attempted.command, 0)} ` +
+                `model=${Inspectable.toStringUnknown(value.attempted.model, 0)} ` +
+                `expected=${Inspectable.toStringUnknown(value.attempted.expected, 0)} ` +
+                `result=${Inspectable.toStringUnknown(value.attempted.result, 0)} ` +
+                `snapshot=${Inspectable.toStringUnknown(value.attempted.snapshot, 0)} ` +
+                `awaited=${Inspectable.toStringUnknown(value.attempted.awaited, 0)} ` +
+                `inspected=${Inspectable.toStringUnknown(value.attempted.inspected, 0)}`);
+        }
+        lines.push(`failure: phase=${value.phase} index=${value.index} command=${Inspectable.toStringUnknown(value.command, 0)} ` +
+            `cause=${Inspectable.toStringUnknown(value.cause, 0)}`);
+    }
+    else {
+        lines.push(`final: snapshot=${Inspectable.toStringUnknown(value.final, 0)}`);
+    }
+    return lines.join("\n");
+};
+//# sourceMappingURL=runtime.js.map