@qvac/harness 0.7.0 → 1.0.0-rc.0

package/dist-lib/lib/run-log/replay.d.ts

@@ -0,0 +1,25 @@
+import { type AnyMachineSnapshot, type AnyStateMachine } from 'xstate';
+import { type Patch } from './patch.ts';
+import type { MachineLog } from './persisted-actor.ts';
+import type { MachineTransitionTrace } from './protocol-types.ts';
+interface ReplayEvent extends Record<string, unknown> {
+    type: string;
+}
+interface ReplayFrame {
+    index: number;
+    event: ReplayEvent;
+    snapshot: AnyMachineSnapshot;
+}
+export declare class ReplayDivergence extends Error {
+    readonly index: number;
+    readonly drift: Patch;
+    constructor(index: number, drift: Patch);
+}
+export declare class ReplayTraceDivergence extends Error {
+    readonly index: number;
+    readonly expected: MachineTransitionTrace[];
+    readonly actual: MachineTransitionTrace[];
+    constructor(index: number, expected: MachineTransitionTrace[], actual: MachineTransitionTrace[]);
+}
+export declare function replayRun(machine: AnyStateMachine, core: MachineLog): AsyncGenerator<ReplayFrame>;
+export {};

package/dist-lib/lib/run-log/replay.js

@@ -0,0 +1,129 @@
+import { createActor, transition } from 'xstate';
+import { diff } from './patch.js';
+import { isRecord } from '../guards.js';
+import { copy, readRunLog } from './run-journal.js';
+import { stableStringify } from '../machine/stable-stringify.js';
+import { transitionName } from './protocol.js';
+export class ReplayDivergence extends Error {
+    index;
+    drift;
+    constructor(index, drift) {
+        super(`Replay diverges from the run log at record ${index}: ${JSON.stringify(drift)}`);
+        this.name = 'ReplayDivergence';
+        this.index = index;
+        this.drift = drift;
+    }
+}
+export class ReplayTraceDivergence extends Error {
+    index;
+    expected;
+    actual;
+    constructor(index, expected, actual) {
+        super(`Transition trace replay diverges from the run log at record ${index}`);
+        this.name = 'ReplayTraceDivergence';
+        this.index = index;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+export async function* replayRun(machine, core) {
+    let current;
+    for await (const { index, record, snapshot, events } of readRunLog(core)) {
+        if (record.type === 'fork' && current) {
+            current = createActor(machine, { snapshot: parsePersistedSnapshot(snapshot) }).getSnapshot();
+            continue;
+        }
+        if (record.type !== 'checkpoint' && record.type !== 'delta') {
+            continue;
+        }
+        if (!current) {
+            if (record.type !== 'checkpoint') {
+                throw new Error('Run log has a delta before any checkpoint');
+            }
+            current = createActor(machine, { snapshot: parsePersistedSnapshot(snapshot) }).getSnapshot();
+            continue;
+        }
+        const parsedEvents = events.map(parseReplayEvent);
+        verifyRecordTrace(machine, {
+            start: current,
+            events: parsedEvents,
+            expected: record.trace ?? [],
+            index
+        });
+        for (const event of parsedEvents) {
+            current = transition(machine, current, event)[0];
+            yield { index, event, snapshot: current };
+        }
+        const drift = diff(view(snapshot), view(machine.getPersistedSnapshot(current)));
+        if (drift) {
+            throw new ReplayDivergence(index, drift);
+        }
+    }
+}
+function verifyRecordTrace(machine, input) {
+    let current = input.start;
+    const actual = [];
+    for (const event of input.events) {
+        actual.push(...transitionTrace(machine, current, event));
+        current = transition(machine, current, event)[0];
+    }
+    assertTrace(input.index, input.expected, actual);
+}
+function transitionTrace(machine, snapshot, event) {
+    return machine.getTransitionData(snapshot, event).map((item) => ({
+        eventType: item.eventType ?? '',
+        sourceIds: [item.source.id],
+        targetIds: item.target?.map((state) => state.id) ?? [],
+        guardNames: item.guard ? [transitionName(item.guard)] : [],
+        actionNames: item.actions.map(transitionName)
+    }));
+}
+function assertTrace(index, expected, actual) {
+    const triggeredExpected = expected.filter((item) => item.eventType !== '');
+    const triggeredActual = actual.filter((item) => item.eventType !== '');
+    if (stableStringify(triggeredExpected) !== stableStringify(triggeredActual)) {
+        throw new ReplayTraceDivergence(index, triggeredExpected, triggeredActual);
+    }
+}
+function view(snapshot) {
+    const detached = copy(snapshot);
+    if (!isRecord(detached)) {
+        throw new Error('Machine replay snapshot is malformed');
+    }
+    const children = detached.children;
+    return {
+        value: detached.value,
+        status: detached.status,
+        context: detached.context,
+        historyValue: detached.historyValue,
+        children: isRecord(children) ? Object.keys(children).sort() : [],
+        output: detached.output,
+        error: detached.error
+    };
+}
+function parsePersistedSnapshot(value) {
+    const snapshot = copy(value);
+    if (!isRecord(snapshot) || !isSnapshotStatus(snapshot.status)) {
+        throw new Error('Machine replay snapshot is malformed');
+    }
+    if ((snapshot.status === 'active' || snapshot.status === 'stopped') &&
+        (snapshot.output !== undefined || snapshot.error !== undefined)) {
+        throw new Error('Machine replay snapshot has output or error for a nonterminal state');
+    }
+    if (snapshot.status === 'done' && snapshot.error !== undefined) {
+        throw new Error('Machine replay snapshot has an error for a done state');
+    }
+    if (snapshot.status === 'error' && snapshot.output !== undefined) {
+        throw new Error('Machine replay snapshot has output for an error state');
+    }
+    return snapshot;
+}
+function parseReplayEvent(value) {
+    if (!isRecord(value) || typeof value.type !== 'string') {
+        throw new Error('Machine replay event is malformed');
+    }
+    return { ...value, type: value.type };
+}
+function isSnapshotStatus(value) {
+    return value === 'active' || value === 'done' || value === 'error' || value === 'stopped';
+}

package/dist-lib/lib/run-log/run-journal.d.ts

@@ -0,0 +1,125 @@
+import type { MachineLog } from './persisted-actor.ts';
+import { RecoveryRequired, type Operation } from '../machine/errors.ts';
+import { type Patch } from './patch.ts';
+import { RUN_LOG_VERSION, pendingCallNames, pendingToolArgs, unsettledRedactedIds, type EngineBoot, type EngineStep, type ForkOrigin, type ForkSegment, type Receipt, type RecoveryResolution, type RunRecord } from './protocol.ts';
+export { RUN_LOG_VERSION, RecoveryRequired, type Operation, pendingCallNames, pendingToolArgs, unsettledRedactedIds };
+export declare const MACHINE_VERSION = 12;
+export declare const XSTATE_VERSION: string;
+export declare const ENGINE_BOUNDARY_BOOT: unique symbol;
+export type { EngineBoot, EngineStep, ForkOrigin, ForkSegment, Receipt, RecoveryResolution, RunRecord };
+export declare class RunIncompatible extends Error {
+    readonly runId: string | undefined;
+    readonly found: number | string;
+    readonly expected: number | string;
+    readonly kind: 'machine' | 'log' | 'xstate';
+    constructor(opts: RunIncompatibleOptions);
+}
+interface RunIncompatibleOptions {
+    runId?: string;
+    found: number | string;
+    expected: number | string;
+    kind: 'machine' | 'log' | 'xstate';
+}
+export type { MachineTransitionTrace } from './protocol.ts';
+export declare function copy<Value>(value: Value): Value;
+export declare function unresolvedWriteIds(receipts: Iterable<Receipt>): string[];
+export declare function forkRepeatsSettledWrite(receipts: Iterable<Receipt>, forkBeforeWrite: ReadonlyMap<string, number>, forkAt: number | null): boolean;
+export declare function safeForkLength(receipts: Iterable<Receipt>, forkBeforeWrite: ReadonlyMap<string, number>, unredactedLength: number): number | null;
+export declare function recoveryAdvice(ids: readonly string[], receipts: Iterable<Receipt>, redactedPendingIds: readonly string[]): string;
+interface OperationFactsAdapter {
+    capture(): unknown;
+    restore(value: unknown): void;
+}
+interface OperationSignal {
+    readonly aborted: boolean;
+}
+export interface ReadRunLogOptions {
+    anyMachine?: boolean;
+    legacyInspection?: boolean;
+}
+export interface RunLogInspectionEntry {
+    index: number;
+    sourceVersion: number;
+    record: RunRecord;
+    snapshot: unknown;
+    events: Record<string, unknown>[];
+}
+export declare class RunJournal {
+    snapshotSavedAt: number | undefined;
+    firstSavedAt: number | undefined;
+    deltasSinceCheckpoint: number;
+    redactedPendingArgs: boolean | null;
+    unredactedLength: number;
+    private restoredRedacted;
+    private readonly forkBeforeWrite;
+    knownLength: number;
+    metadata: Extract<RunRecord, {
+        type: 'metadata';
+    }> | undefined;
+    readonly receipts: Map<string, Receipt>;
+    private readonly intentArgs;
+    private tail;
+    private settledTail;
+    uncertainWrite(): (Operation & {
+        facts?: unknown;
+        status: 'intent' | 'retry';
+    }) | undefined;
+    failure: Error | null;
+    detachedEffects: Promise<void> | null;
+    sealed: boolean;
+    onFailure?: (error: Error) => void;
+    readonly core: MachineLog;
+    restored: boolean;
+    private readonly redact;
+    private readonly redactShared;
+    private readonly redactOperationResult;
+    private readonly redactRecord?;
+    private readonly hasRedactionProvenance;
+    private readonly initialBoot?;
+    private engineBoot;
+    get snapshot(): unknown;
+    get requestHistoryBase(): readonly unknown[] | undefined;
+    compactSnapshot(snapshot: unknown): unknown;
+    constructor(core: MachineLog, opts?: RunJournalOptions);
+    redactValue<Value>(value: Value): Value;
+    restore(): Promise<void>;
+    private assertCompatibleBoot;
+    private allowLegacyFailureResults;
+    private restoreBoot;
+    exportBoot(): EngineBoot;
+    exportSnapshot(): unknown;
+    private trackForkPoint;
+    settledCall(receiptId: string): boolean;
+    private unresolvedWriteIds;
+    redactedPendingCallIds(snapshot: unknown): string[];
+    private safeForkLength;
+    getReceipt(receiptId: string): Receipt | undefined;
+    commitResultFacts(receiptId: string, facts: unknown): Promise<void>;
+    retryLifecycleReceipts(): Receipt[];
+    pendingArgumentsWereRedacted(snapshot: unknown): boolean | null;
+    append(record: RunRecord): Promise<void>;
+    private fail;
+    hasPendingFlush(): boolean;
+    flush(): Promise<void>;
+    resolve(resolutions: readonly RecoveryResolution[]): Promise<void>;
+    operation<Result>(operation: Operation, execute: () => Promise<Result>, facts?: OperationFactsAdapter, signal?: OperationSignal): Promise<Result>;
+}
+interface RunJournalOptions {
+    redact?: <Value>(value: Value) => Value;
+    redactShared?: <Value>(value: Value) => Value;
+    redactOperationResult?: <Value>(operation: Operation, value: Value) => Value;
+    redactRecord?: (record: RunRecord) => RunRecord;
+    boot?: EngineBoot;
+}
+export declare function acquireRun(owner: object, runId: string): () => void;
+export declare class EventCodec {
+    private base;
+    private readonly historyBase;
+    constructor(historyBase?: readonly unknown[]);
+    reset(): void;
+    encode(event: unknown): Patch;
+    decode(patch: Patch): Record<string, unknown>;
+    decodeLegacy(patch: Patch): Record<string, unknown>;
+    private merge;
+}
+export declare function readRunLog(core: MachineLog, opts?: ReadRunLogOptions): AsyncGenerator<RunLogInspectionEntry>;