@qvac/harness 0.7.1 → 1.0.0-rc.1

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

@@ -0,0 +1,6 @@
+import { isRecord } from '../guards.ts';
+import type { Patch } from './protocol-types.ts';
+export { isRecord };
+export type { Patch } from './protocol-types.ts';
+export declare function diff(prev: unknown, next: unknown): Patch | undefined;
+export declare function apply(base: unknown, patch: Patch): unknown;

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

@@ -0,0 +1,93 @@
+import { isRecord } from '../guards.js';
+export { isRecord };
+export function diff(prev, next) {
+    if (prev === next)
+        return undefined;
+    if (Array.isArray(prev) && Array.isArray(next)) {
+        let kept = 0;
+        while (kept < prev.length && kept < next.length && same(prev[kept], next[kept])) {
+            kept++;
+        }
+        if (kept === prev.length && kept === next.length) {
+            return undefined;
+        }
+        return { t: kept, a: next.slice(kept) };
+    }
+    if (isRecord(prev) && !Array.isArray(prev) && isRecord(next) && !Array.isArray(next)) {
+        const o = Object.create(null);
+        const d = [];
+        let changed = false;
+        for (const key of Object.keys(next)) {
+            if (next[key] === undefined)
+                continue;
+            const patch = Object.hasOwn(prev, key) && prev[key] !== undefined
+                ? diff(prev[key], next[key])
+                : { $: next[key] };
+            if (patch) {
+                o[key] = patch;
+                changed = true;
+            }
+        }
+        for (const key of Object.keys(prev)) {
+            if (prev[key] !== undefined && (!Object.hasOwn(next, key) || next[key] === undefined)) {
+                d.push(key);
+                changed = true;
+            }
+        }
+        if (!changed) {
+            return undefined;
+        }
+        return d.length ? { o, d } : { o };
+    }
+    return { $: next };
+}
+function same(prev, next) {
+    return prev === next || diff(prev, next) === undefined;
+}
+function isReplacementPatch(patch) {
+    return Object.hasOwn(patch, '$');
+}
+function isArrayPatch(patch) {
+    return Object.hasOwn(patch, 't');
+}
+function isObjectPatch(patch) {
+    return Object.hasOwn(patch, 'o');
+}
+export function apply(base, patch) {
+    if (isReplacementPatch(patch)) {
+        return patch.$;
+    }
+    if (isArrayPatch(patch)) {
+        const arrayPatch = patch;
+        const array = Array.isArray(base) ? base : [];
+        array.length = Math.min(array.length, arrayPatch.t);
+        for (const value of arrayPatch.a) {
+            array.push(value);
+        }
+        return array;
+    }
+    if (!isObjectPatch(patch)) {
+        throw new TypeError('Invalid JSON patch');
+    }
+    const objectPatch = patch;
+    const record = isRecord(base) && !Array.isArray(base) ? base : {};
+    for (const key of objectPatch.d ?? []) {
+        if (Object.hasOwn(record, key)) {
+            delete record[key];
+        }
+    }
+    for (const key of Object.keys(objectPatch.o)) {
+        const child = objectPatch.o[key];
+        if (child === undefined) {
+            continue;
+        }
+        const value = apply(Object.hasOwn(record, key) ? record[key] : undefined, child);
+        Object.defineProperty(record, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true
+        });
+    }
+    return record;
+}

package/dist-lib/lib/run-log/persisted-actor.d.ts

@@ -0,0 +1,18 @@
+import { type AnyStateMachine, type Actor } from 'xstate';
+import { RunJournal } from './run-journal.ts';
+export interface MachineLog {
+    ready(): Promise<void>;
+    readonly length: number;
+    get(index: number): Promise<unknown>;
+    append(value: unknown): Promise<unknown>;
+}
+export interface PersistedActor<Machine extends AnyStateMachine> {
+    actor: Actor<Machine>;
+    persistence: {
+        journal: RunJournal;
+        checkpoint(): Promise<void>;
+        flush(): Promise<void>;
+        dispose(): Promise<void>;
+    };
+}
+export declare function createPersistedActor<Machine extends AnyStateMachine>(core: MachineLog | RunJournal, machine: Machine, onFailure?: (error: Error) => void, now?: () => number): Promise<PersistedActor<Machine>>;

package/dist-lib/lib/run-log/persisted-actor.js

@@ -0,0 +1,218 @@
+import { createActor } from 'xstate';
+import { EventCodec, RUN_LOG_VERSION, RunJournal } from './run-journal.js';
+import { diff, isRecord } from './patch.js';
+import { brandCapturedRecord, isCapturedJson, transitionName } from './protocol.js';
+const CHECKPOINT_EVERY = 64;
+const ROOT_ACTOR_ID = 'qvac-completion-machine';
+const UNRECORDED = new Set(['OUTPUT', 'xstate.stop']);
+const noClock = () => 0;
+export async function createPersistedActor(core, machine, onFailure, now = noClock) {
+    const journal = core instanceof RunJournal ? core : new RunJournal(core);
+    if (!journal.restored) {
+        await journal.restore();
+    }
+    let observeChild;
+    const codec = new EventCodec(journal.requestHistoryBase);
+    const events = [];
+    const trace = [];
+    let fresh = true;
+    const recordedBase = Object.create(machine);
+    const recorded = Object.assign(recordedBase, {
+        transition(...args) {
+            if (!UNRECORDED.has(args[1].type)) {
+                events.push(codec.encode(journal.redactValue(args[1])));
+            }
+            return machine.transition(...args);
+        }
+    });
+    let rootActor;
+    const isRootActor = (ref) => rootActor !== undefined && ref === rootActor;
+    const actorRefId = (ref) => {
+        if (typeof ref !== 'object' || ref === null || !('id' in ref)) {
+            return undefined;
+        }
+        return typeof ref.id === 'string' ? ref.id : undefined;
+    };
+    const isInitialRootMicrostep = (event) => actorRefId(event.actorRef) === ROOT_ACTOR_ID &&
+        event._transitions.some((transition) => transition.source.id === machine.id || transition.source.id.startsWith(`${machine.id}.`));
+    const observeTrace = (event) => {
+        for (const step of traceFromMicrostep(event)) {
+            trace.push(step);
+        }
+    };
+    const actor = createActor(recorded, {
+        id: ROOT_ACTOR_ID,
+        snapshot: journal.snapshot,
+        inspect: (event) => {
+            if (event.type === '@xstate.microstep' &&
+                (isRootActor(event.actorRef) || isInitialRootMicrostep(event))) {
+                observeTrace(event);
+            }
+            if (event.type === '@xstate.snapshot' &&
+                !isRootActor(event.actorRef) &&
+                event.snapshot.status === 'active') {
+                observeChild?.();
+            }
+        }
+    });
+    rootActor = actor;
+    let base = journal.exportSnapshot();
+    let deltas = journal.deltasSinceCheckpoint;
+    let seenContext;
+    let seenStatus;
+    let seenValue;
+    let seenChildren;
+    let seenChildCount = 0;
+    let seenChildSnapshots = new WeakMap();
+    let disposed = false;
+    const previousOnFailure = journal.onFailure;
+    const fail = (error) => {
+        journal.failure ??= error;
+        actor.stop();
+        onFailure?.(error);
+    };
+    journal.onFailure = (error) => {
+        previousOnFailure?.(error);
+        fail(error);
+    };
+    const checkpoint = () => {
+        if (disposed || journal.failure) {
+            return journal.flush();
+        }
+        if (isDoneSnapshot(base)) {
+            return journal.flush();
+        }
+        try {
+            const live = actor.getSnapshot();
+            const children = live.children;
+            let childCount = 0;
+            let childrenUnchanged = true;
+            for (const id in children) {
+                if (!Object.hasOwn(children, id))
+                    continue;
+                childCount++;
+                const child = children[id];
+                if (seenChildSnapshots.get(child) !== child.getSnapshot()) {
+                    childrenUnchanged = false;
+                }
+            }
+            if (live.context === seenContext &&
+                live.status === seenStatus &&
+                live.value === seenValue &&
+                live.children === seenChildren &&
+                childCount === seenChildCount &&
+                childrenUnchanged &&
+                events.length === 0 &&
+                trace.length === 0) {
+                return journal.flush();
+            }
+            seenContext = live.context;
+            seenStatus = live.status;
+            seenValue = live.value;
+            seenChildren = live.children;
+            seenChildCount = childCount;
+            seenChildSnapshots = new WeakMap();
+            for (const id in children) {
+                if (!Object.hasOwn(children, id))
+                    continue;
+                const child = children[id];
+                seenChildSnapshots.set(child, child.getSnapshot());
+            }
+            const snapshot = actor.getPersistedSnapshot();
+            const recordedSnapshot = journal.compactSnapshot(journal.redactValue(snapshot));
+            const savedAt = now();
+            const redactedPendingArgs = journal.pendingArgumentsWereRedacted(snapshot);
+            const redactedIds = journal.redactedPendingCallIds(snapshot);
+            const reset = fresh ? true : undefined;
+            if (base === undefined || deltas >= CHECKPOINT_EVERY) {
+                base = recordedSnapshot;
+                deltas = 0;
+                fresh = false;
+                const appended = journal.append({
+                    version: RUN_LOG_VERSION,
+                    type: 'checkpoint',
+                    snapshot: recordedSnapshot,
+                    savedAt,
+                    redactedPendingArgs: redactedPendingArgs ?? undefined,
+                    redactedPendingIds: redactedIds,
+                    events: events.splice(0),
+                    trace: trace.length ? trace.splice(0) : undefined,
+                    reset
+                });
+                codec.reset();
+                return appended;
+            }
+            const patch = diff(base, recordedSnapshot);
+            if (!patch && events.length === 0 && trace.length === 0) {
+                return journal.flush();
+            }
+            base = recordedSnapshot;
+            deltas++;
+            fresh = false;
+            return journal.append({
+                version: RUN_LOG_VERSION,
+                type: 'delta',
+                patch: patch && isCapturedJson(recordedSnapshot)
+                    ? brandCapturedRecord(patch)
+                    : (patch ?? undefined),
+                savedAt,
+                redactedPendingArgs: redactedPendingArgs ?? undefined,
+                redactedPendingIds: redactedIds,
+                events: events.splice(0),
+                trace: trace.length ? trace.splice(0) : undefined,
+                reset
+            });
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            fail(failure);
+            return Promise.reject(failure);
+        }
+    };
+    observeChild = () => {
+        void checkpoint().catch(noop);
+    };
+    const subscription = actor.subscribe({
+        next: () => {
+            void checkpoint().catch(noop);
+        },
+        error: (error) => fail(error instanceof Error ? error : new Error(String(error)))
+    });
+    return {
+        actor,
+        persistence: {
+            journal,
+            checkpoint,
+            flush: () => journal.flush(),
+            async dispose() {
+                if (!disposed) {
+                    disposed = true;
+                    subscription.unsubscribe();
+                    actor.stop();
+                }
+                await journal.flush();
+            }
+        }
+    };
+}
+function traceFromMicrostep(event) {
+    if (UNRECORDED.has(event.event.type))
+        return [];
+    const trace = [];
+    for (const transition of event._transitions) {
+        if (UNRECORDED.has(transition.eventType))
+            continue;
+        trace.push({
+            eventType: transition.eventType,
+            sourceIds: [transition.source.id],
+            targetIds: transition.target?.map((state) => state.id) ?? [],
+            guardNames: transition.guard ? [transitionName(transition.guard)] : [],
+            actionNames: transition.actions.map(transitionName)
+        });
+    }
+    return trace;
+}
+function isDoneSnapshot(value) {
+    return isRecord(value) && value.status === 'done';
+}
+function noop() { }

package/dist-lib/lib/run-log/protocol-types.d.ts

@@ -0,0 +1,153 @@
+export interface Operation {
+    id: string;
+    name: string;
+    args: unknown;
+    effect: 'read' | 'write';
+    reason?: string;
+}
+export interface RunBudget {
+    readonly deadlineMs: number;
+    outputBytesUsed: number;
+}
+export type Patch = {
+    $: unknown;
+} | {
+    o: Record<string, Patch>;
+    d?: string[];
+} | {
+    t: number;
+    a: unknown[];
+};
+export interface HistoryReference {
+    $qvacHistory: {
+        version: 1;
+        base: 'request.messages';
+        items: ({
+            index: number;
+        } | {
+            inline: unknown;
+        })[];
+    };
+}
+export type RecoveryResolution = {
+    operationId: string;
+    decision: 'retry';
+} | {
+    operationId: string;
+    decision: 'result';
+    result: unknown;
+} | {
+    operationId: string;
+    decision: 'skip';
+};
+export interface ForkOrigin {
+    runId: string;
+    length: number;
+    key?: string;
+}
+export interface ForkSegment {
+    key: string;
+    length: number;
+}
+export interface MachineTransitionTrace {
+    eventType: string;
+    sourceIds: string[];
+    targetIds: string[];
+    guardNames: string[];
+    actionNames: string[];
+}
+export type Receipt = (Operation & {
+    facts?: unknown;
+    status: 'intent' | 'retry';
+}) | {
+    id: string;
+    name: string;
+    effect: Operation['effect'];
+    facts?: unknown;
+    status: 'result';
+    result: unknown;
+    resultUndefined?: true;
+    abandoned?: true;
+};
+export type RunRecord = {
+    version: 5;
+    type: 'metadata';
+    runId: string;
+    request: unknown;
+    requestDigest?: string;
+    digestRunId?: string;
+    budget: RunBudget;
+    machine: number;
+    definition?: unknown;
+    xstate?: string;
+    forkedFrom?: ForkOrigin;
+    startedAt?: number;
+} | {
+    version: 5;
+    type: 'fork';
+    runId: string;
+    forkedFrom: ForkOrigin;
+    request?: Record<string, unknown>;
+    segments?: ForkSegment[];
+} | {
+    version: 5;
+    type: 'checkpoint';
+    snapshot: unknown;
+    savedAt: number;
+    redactedPendingArgs?: boolean;
+    redactedPendingIds?: string[];
+    events?: Patch[];
+    trace?: MachineTransitionTrace[];
+    reset?: true;
+} | {
+    version: 5;
+    type: 'delta';
+    patch?: Patch;
+    savedAt: number;
+    redactedPendingArgs?: boolean;
+    redactedPendingIds?: string[];
+    events: Patch[];
+    trace?: MachineTransitionTrace[];
+    reset?: true;
+} | {
+    version: 5;
+    type: 'operation';
+    receipt: Receipt;
+};
+export interface EngineStep {
+    seq: number;
+    expectedLength: number;
+    records: readonly RunRecord[];
+}
+export interface EngineBoot {
+    protocolVersion: 1;
+    length: number;
+    nextSeq: number;
+    machineVersion: number | null;
+    xstateVersion: string | null;
+    metadata: Extract<RunRecord, {
+        type: 'metadata';
+    }> | null;
+    snapshot?: unknown;
+    eventState: unknown | null;
+    snapshotSavedAt?: number;
+    firstSavedAt?: number;
+    deltasSinceCheckpoint: number;
+    redactedPendingArgs: boolean | null;
+    redactedPendingIds: string[];
+    unredactedLength: number;
+    restoredRedacted: boolean;
+    forkBeforeWrite: Array<[string, number]>;
+    receipts: Receipt[];
+    intentArgs: Array<[string, unknown]>;
+}
+export interface HostRunLogLease {
+    generation: string;
+    boot?: EngineBoot;
+    digestKey: Uint8Array;
+}
+export interface HostRunLog {
+    begin(runId: string): Promise<HostRunLogLease>;
+    append(runId: string, generation: string, step: EngineStep): Promise<void>;
+    release(runId: string, generation: string): Promise<void>;
+}

package/dist-lib/lib/run-log/protocol-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+import type { EngineBoot, EngineStep, Receipt, RunRecord } from './protocol-types.ts';
+export declare const RUN_LOG_PROTOCOL_VERSION: 1;
+export declare const RUN_LOG_VERSION: 5;
+export type { EngineBoot, EngineStep, ForkOrigin, ForkSegment, HostRunLog, HostRunLogLease, HistoryReference, MachineTransitionTrace, Operation, Patch, Receipt, RecoveryResolution, RunBudget, RunRecord } from './protocol-types.ts';
+export declare function transitionName(named: unknown): string;
+export declare class InvalidEngineStep extends Error {
+    constructor(message: string);
+}
+export declare function pendingToolArgs(snapshot: unknown, settled?: (receiptId: string) => boolean): unknown[];
+export declare function pendingCallNames(snapshot: unknown): Map<string, string>;
+export declare function pendingCallArgs(snapshot: unknown, settled?: (receiptId: string) => boolean): Map<string, unknown>;
+export declare function unsettledRedactedIds(redactedPendingIds: readonly string[], receipts: Iterable<Receipt>): string[];
+export declare function createEngineBoot(): EngineBoot;
+export declare function prepareEngineBoot(value?: EngineBoot): EngineBoot;
+export declare function captureRunRecord(record: unknown): RunRecord;
+export declare function brandCapturedRecord<Value>(value: Value): Value;
+export declare function isCapturedJson(value: unknown): boolean;
+export declare function createEngineStep(seq: number, expectedLength: number, records: readonly RunRecord[]): EngineStep;
+export declare function captureEngineStep(step: EngineStep): EngineStep;
+export declare function requestFromBoot(boot: EngineBoot): unknown;
+export declare function contextFromBoot(boot: EngineBoot): unknown;
+export interface BuildEngineBootOptions {
+    nextSeq: number;
+}
+export declare function buildEngineBoot(records: readonly RunRecord[], opts: BuildEngineBootOptions): EngineBoot;
+export declare function applyEngineStep(boot: EngineBoot, step: EngineStep): EngineBoot;
+export declare function validateEngineBoot(boot: EngineBoot): void;