@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/dist-lib/lib/run-log/history-codec.js

@@ -1,15 +1,18 @@
 import { isRecord } from './patch.js';
-import { stableStringify } from '../machine/stable-stringify.js';
+import { stableStringify } from '../helpers/stable-stringify.js';
+import { isCompactedLength } from '../helpers/failure-result.js';
 const marker = '$qvacHistory';
 const failureResultType = 'qvac-failure-result-ref';
-export const FAILURE_RESULT_REF_MACHINE_VERSION = 8;
 const baseIndexCache = new WeakMap();
+const exactBaseIndexCache = new WeakMap();
 const compactHistoryCache = new WeakMap();
+const frozenHistoryCache = new WeakMap();
 const materializedCache = new WeakMap();
 const materializedValueCache = new WeakMap();
 const messageKeyCache = new WeakMap();
 const deepFrozenCache = new WeakMap();
 const validatedHistoryCache = new WeakMap();
+const idlessBaseCache = new WeakMap();
 const MATERIALIZED_HISTORY_CACHE_LIMIT = 16;
 export function requestMessages(request) {
     if (!isRecord(request) || !Array.isArray(request.messages))
@@ -19,29 +22,100 @@ export function requestMessages(request) {
             throw new Error('Request message uses the reserved failure-result reference type');
         }
     }
-    return request.messages;
+    return withoutHostIds(request.messages);
 }
-export function compactSnapshotHistory(snapshot, base) {
+function withoutHostIds(messages) {
+    if (!messages.some((message) => isRecord(message) && Object.hasOwn(message, 'id'))) {
+        return messages;
+    }
+    const cached = idlessBaseCache.get(messages);
+    if (cached) {
+        return cached;
+    }
+    const frozen = Object.isFrozen(messages);
+    const idless = messages.map((message) => {
+        if (!isRecord(message) || !Object.hasOwn(message, 'id'))
+            return message;
+        const { id: _id, ...rest } = message;
+        return frozen ? Object.freeze(rest) : rest;
+    });
+    idlessBaseCache.set(messages, frozen ? Object.freeze(idless) : idless);
+    return idless;
+}
+export function compactRequestHistory(messages, base) {
+    if (!base?.length || !messages.length)
+        return messages;
+    const indexes = exactBaseIndexes(base);
+    let references = 0;
+    const items = messages.map((message) => {
+        const index = indexes.get(JSON.stringify(message));
+        if (index === undefined) {
+            return { inline: message };
+        }
+        references++;
+        return { index };
+    });
+    return references === 0
+        ? messages
+        : { [marker]: { version: 1, base: 'request.messages', items } };
+}
+export function materializeRequestHistory(value, base) {
+    if (Array.isArray(value))
+        return value;
+    if (!isHistoryReference(value)) {
+        throw new Error('Malformed request history');
+    }
+    return materializeHistory(value, base);
+}
+export function validateRequestHistory(value, base) {
+    validateHistoryList(value, base, new Set());
+}
+function exactBaseIndexes(base) {
+    const cached = exactBaseIndexCache.get(base);
+    if (cached) {
+        return cached;
+    }
+    const indexes = new Map();
+    base.forEach((message, index) => {
+        if (isFailureResultReference(message))
+            return;
+        const key = JSON.stringify(message);
+        if (!indexes.has(key)) {
+            indexes.set(key, index);
+        }
+    });
+    if (isDeepFrozen(base)) {
+        exactBaseIndexCache.set(base, indexes);
+    }
+    return indexes;
+}
+export function compactSnapshotHistory(snapshot, base, previous) {
     if (!isRecord(snapshot) ||
         !isRecord(snapshot.context) ||
         !Array.isArray(snapshot.context.history)) {
         return snapshot;
     }
     const refs = snapshotFailureResultRefs(snapshot);
-    const history = compactHistory(snapshot.context.history, base, refs);
+    const prior = isRecord(previous) && isRecord(previous.context) && Array.isArray(previous.context.history)
+        ? previous.context.history
+        : undefined;
+    const history = compactHistory(snapshot.context.history, base, {
+        failureRefs: refs,
+        previous: prior
+    });
     if (history === snapshot.context.history) {
         return snapshot;
     }
     return replacePath(snapshot, ['context', 'history'], history);
 }
-export function materializeSnapshotHistory(snapshot, base, allowLegacyInlineFailureResults = false) {
+export function materializeSnapshotHistory(snapshot, base) {
     if (!isRecord(snapshot) || !isRecord(snapshot.context))
         return snapshot;
     const history = snapshot.context.history;
     if (!isHistoryReference(history)) {
         return snapshot;
     }
-    const refs = snapshotFailureResultRefs(snapshot, allowLegacyInlineFailureResults);
+    const refs = snapshotFailureResultRefs(snapshot);
     const full = materializeHistory(history, base, refs);
     return replacePath(snapshot, ['context', 'history'], full);
 }
@@ -68,14 +142,11 @@ export function materializeMachineEvent(event, base) {
     return materialized;
 }
 export function validateSnapshotHistory(snapshot, base, options = {}) {
-    const allowLegacyInlineFailureResults = options.allowLegacyInlineFailureResults ?? false;
     const validateMachineContext = options.validateMachineContext ?? true;
     if (!isRecord(snapshot) || !isRecord(snapshot.context)) {
         return;
     }
-    const refs = validateMachineContext
-        ? snapshotFailureResultRefs(snapshot, allowLegacyInlineFailureResults)
-        : undefined;
+    const refs = validateMachineContext ? snapshotFailureResultRefs(snapshot) : undefined;
     const referenced = new Set();
     if (Object.hasOwn(snapshot.context, 'history')) {
         for (const ref of validateHistoryList(snapshot.context.history, base, refs)) {
@@ -109,14 +180,13 @@ export function validateSnapshotHistory(snapshot, base, options = {}) {
         }
     }
 }
-export function snapshotFailureResultRefs(snapshot, allowLegacyInlineFailureResults = false) {
+export function snapshotFailureResultRefs(snapshot) {
     if (!isRecord(snapshot) || !isRecord(snapshot.context)) {
         return new Set();
     }
     const { context } = snapshot;
     const refs = new Set();
-    const hasFailureResults = Object.hasOwn(context, 'failureResults');
-    if (hasFailureResults) {
+    if (Object.hasOwn(context, 'failureResults')) {
         if (!isRecord(context.failureResults) || Array.isArray(context.failureResults)) {
             throw new Error('Malformed failure result table');
         }
@@ -136,12 +206,6 @@ export function snapshotFailureResultRefs(snapshot, allowLegacyInlineFailureResu
             if (!isRecord(value)) {
                 throw new Error('Failed call points outside the canonical failure result table');
             }
-            if (allowLegacyInlineFailureResults &&
-                !Object.hasOwn(value, 'resultRef') &&
-                !hasFailureResults &&
-                Object.hasOwn(value, 'result')) {
-                continue;
-            }
             if (typeof value.resultRef !== 'string' ||
                 !refs.has(value.resultRef) ||
                 !isRecord(value.outcome) ||
@@ -238,8 +302,14 @@ function materializeSplice(value, base) {
         return value;
     return replaceOwn(value, 'messages', materializeHistory(value.messages, base));
 }
-function compactHistory(messages, base, failureRefs) {
-    validateHistoryList(messages, base, failureRefs);
+function compactHistory(messages, base, scope = {}) {
+    if (base?.length &&
+        !isHistoryReference(messages) &&
+        isDeepFrozen(base) &&
+        isDeepFrozen(messages)) {
+        return compactFrozenHistory(messages, base, scope);
+    }
+    validateHistoryList(messages, base, scope.failureRefs);
     if (!base?.length || isHistoryReference(messages)) {
         return messages;
     }
@@ -261,20 +331,13 @@ function compactHistory(messages, base, failureRefs) {
     const indexes = indexBase(base);
     let references = 0;
     const items = messages.map((message, offset) => {
-        if (isFailureResultReference(message)) {
-            return { inline: message };
-        }
-        const key = keys[offset];
-        const indexedItem = indexes.get(key);
-        if (indexedItem === undefined) {
-            return { inline: message };
+        const item = historyItem(message, keys[offset], indexes);
+        if (!('inline' in item)) {
+            references++;
         }
-        references++;
-        return typeof indexedItem === 'number' ? { index: indexedItem } : indexedItem;
+        return item;
     });
-    const value = references === 0
-        ? messages
-        : { [marker]: { version: 1, base: 'request.messages', items } };
+    const value = historyValue(messages, items, references);
     if (cacheable) {
         const memo = cachedByBase ?? new WeakMap();
         memo.set(base, { keys, value });
@@ -284,6 +347,73 @@ function compactHistory(messages, base, failureRefs) {
     }
     return value;
 }
+function compactFrozenHistory(messages, base, { failureRefs, previous }) {
+    const cachedByBase = frozenHistoryCache.get(messages);
+    const cached = cachedByBase?.get(base);
+    if (cached) {
+        validateFailureReferenceSet(cached.failureRefs, failureRefs);
+        return cached.value;
+    }
+    const prior = previous?.length && extendsHistory(messages, previous)
+        ? frozenHistoryCache.get(previous)?.get(base)
+        : undefined;
+    const start = prior ? prior.items.length : 0;
+    const items = prior ? prior.items.slice() : [];
+    let references = prior ? prior.references : 0;
+    const refs = prior
+        ? appendedFailureRefs(prior.failureRefs, messages, start)
+        : validateHistoryList(messages, base);
+    validateFailureReferenceSet(refs, failureRefs);
+    const indexes = indexBase(base);
+    for (let index = start; index < messages.length; index++) {
+        const item = historyItem(messages[index], messageKey(messages[index]), indexes);
+        if (!('inline' in item)) {
+            references++;
+        }
+        items.push(item);
+    }
+    const value = historyValue(messages, items, references);
+    const memo = cachedByBase ?? new WeakMap();
+    memo.set(base, { items, references, failureRefs: refs, value });
+    if (!cachedByBase) {
+        frozenHistoryCache.set(messages, memo);
+    }
+    return value;
+}
+function appendedFailureRefs(previous, messages, start) {
+    const refs = new Set(previous);
+    for (let index = start; index < messages.length; index++) {
+        const ref = validateHistoryEntry(messages[index]);
+        if (ref) {
+            refs.add(ref);
+        }
+    }
+    return [...refs];
+}
+function extendsHistory(messages, previous) {
+    if (previous.length > messages.length)
+        return false;
+    for (let index = 0; index < previous.length; index++) {
+        if (messages[index] !== previous[index])
+            return false;
+    }
+    return true;
+}
+function historyItem(message, key, indexes) {
+    if (isFailureResultReference(message)) {
+        return { inline: message };
+    }
+    const indexedItem = indexes.get(key);
+    if (indexedItem === undefined) {
+        return { inline: message };
+    }
+    return typeof indexedItem === 'number' ? { index: indexedItem } : indexedItem;
+}
+function historyValue(messages, items, references) {
+    return references === 0
+        ? messages
+        : { [marker]: { version: 1, base: 'request.messages', items } };
+}
 function indexBase(base) {
     const cacheable = isDeepFrozen(base);
     const cached = cacheable ? baseIndexCache.get(base) : undefined;
@@ -515,7 +645,7 @@ function outputHistoryPatch(patch) {
     const objectPatch = patch;
     const o = Object.create(null);
     const d = [];
-    for (const key of ['history', 'preparation', 'preload', 'failed']) {
+    for (const key of ['history', 'preparation', 'step', 'failed']) {
         if (Object.hasOwn(objectPatch.o, key)) {
             const filtered = key === 'failed'
                 ? failureOutputPatch(objectPatch.o[key])
@@ -570,7 +700,7 @@ function projectionFromOutput(output) {
     if (Object.hasOwn(output, 'failed')) {
         result.failed = projectFailureOutput(output.failed);
     }
-    for (const key of ['preparation', 'preload']) {
+    for (const key of ['preparation', 'step']) {
         if (!Object.hasOwn(output, key))
             continue;
         result[key] = slotProjection(output[key]);
@@ -613,17 +743,14 @@ function mergeProjection(previous, event) {
 export function validateHistoryProjection(value, options) {
     if (!isRecord(value) || !isRecord(value.output))
         return;
-    const { base, failureRefs, validateFailureOutputs = true } = options;
+    const { base, failureRefs } = options;
     const actor = typeof value.type === 'string' ? completedActorName(value.type) : undefined;
     const output = value.output;
-    if (validateFailureOutputs &&
-        failureRefs !== undefined &&
-        actor !== undefined &&
-        FAILURE_RESULT_OUTPUT_ACTORS.has(actor)) {
+    if (failureRefs !== undefined && actor !== undefined && FAILURE_RESULT_OUTPUT_ACTORS.has(actor)) {
         validateFailureOutput(output, failureRefs);
     }
     if (actor === 'preparing') {
-        for (const key of ['preparation', 'preload']) {
+        for (const key of ['preparation', 'step']) {
             validateSlotHistoryProjection(output, key, { base, failureRefs });
         }
     }
@@ -714,7 +841,8 @@ function isFailureResultReference(value) {
         return false;
     }
     const keys = Object.keys(value);
-    return (keys.length === 3 &&
+    const compacted = keys.length === 4 && keys.includes('compactedTo') && isCompactedLength(value.compactedTo);
+    return ((keys.length === 3 || compacted) &&
         keys.includes('type') &&
         keys.includes('ref') &&
         keys.includes('callId') &&
@@ -819,20 +947,21 @@ function hasSamePrimitiveFields(value, fields) {
     });
 }
 const HISTORY_OUTPUT_ACTORS = new Set([
-    'preloading',
+    'prepareRunning',
     'generating',
     'resolving',
     'rejecting',
     'executing',
+    'batching',
     'wrapping',
-    'loadingSkill'
+    'retrieving'
 ]);
 const FAILURE_RESULT_OUTPUT_ACTORS = new Set(['rejecting', 'executing']);
 function eventHistoryPaths(actor) {
     if (actor === 'preparing') {
         return [
             ['output', 'preparation', 'history'],
-            ['output', 'preload', 'history']
+            ['output', 'step', 'history']
         ];
     }
     if (actor !== undefined && HISTORY_OUTPUT_ACTORS.has(actor)) {

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

@@ -0,0 +1,46 @@
+import { inspectRun, recordLog, renderRunLogHtml } from './inspect.ts';
+import { RunLogWatch } from './live.ts';
+import { createRunLogRedactor } from './redact.ts';
+import { parsePersistedSnapshot, replayRun } from './replay.ts';
+import { createPersistedActor } from './persisted-actor.ts';
+import { boundaryBoot, openBoundaryJournal } from './boundary.ts';
+import { applyEngineStep, buildEngineBoot, contextFromBoot, createEngineBoot, requestFromBoot, validateEngineBoot } from './protocol.ts';
+import { RunJournal, acquireRun, forkRepeatsSettledWrite, readRequests, readRunLog, recoveryAdvice, safeForkLength, unresolvedWriteIds, unsettledRedactedIds } from './run-journal.ts';
+export declare class RunLog extends RunJournal {
+    static VERSION: 1;
+    static PROTOCOL_VERSION: 1;
+    static XSTATE_VERSION: string;
+    static read: typeof readRunLog;
+    static fromRecords: typeof recordLog;
+    static requests: typeof readRequests;
+    static replay: typeof replayRun;
+    static parseSnapshot: typeof parsePersistedSnapshot;
+    static inspect: typeof inspectRun;
+    static renderHtml: typeof renderRunLogHtml;
+    static watch: () => RunLogWatch;
+    static createRedactor: typeof createRunLogRedactor;
+    static createEngineBoot: typeof createEngineBoot;
+    static buildEngineBoot: typeof buildEngineBoot;
+    static validateEngineBoot: typeof validateEngineBoot;
+    static applyEngineStep: typeof applyEngineStep;
+    static contextFromBoot: typeof contextFromBoot;
+    static requestFromBoot: typeof requestFromBoot;
+    static safeForkLength: typeof safeForkLength;
+    static recoveryAdvice: typeof recoveryAdvice;
+    static unresolvedWriteIds: typeof unresolvedWriteIds;
+    static unsettledRedactedIds: typeof unsettledRedactedIds;
+    static forkRepeatsSettledWrite: typeof forkRepeatsSettledWrite;
+    static openBoundary: typeof openBoundaryJournal;
+    static boundaryBoot: typeof boundaryBoot;
+    static createPersistedActor: typeof createPersistedActor;
+    static acquireRun: typeof acquireRun;
+}
+export { InvalidEngineStep } from './protocol.ts';
+export { RunIncompatible } from './run-journal.ts';
+export type { RunLogInspectionEntry } from './run-journal.ts';
+export { ReplayDivergence, ReplayTraceDivergence } from './replay.ts';
+export type { EngineBoot, EngineStep, ForkOrigin, ForkSegment, HistoryReference, HostRunLog, HostRunLogLease, LoggedRequest, MachineLog, ModelRequest, MachineTransitionTrace, Patch, Receipt, RecoveryResolution, RunRecord } from './protocol-types.ts';
+export type { PositionedRunRecord } from './inspect.ts';
+export type { RunLogView, RunLogWatch } from './live.ts';
+export type { RunLogRedactor } from './redact.ts';
+export type { RunLogBoundaryOptions } from './boundary.ts';

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

@@ -0,0 +1,40 @@
+import { inspectRun, recordLog, renderRunLogHtml } from './inspect.js';
+import { RunLogWatch } from './live.js';
+import { createRunLogRedactor } from './redact.js';
+import { parsePersistedSnapshot, replayRun } from './replay.js';
+import { createPersistedActor } from './persisted-actor.js';
+import { boundaryBoot, openBoundaryJournal } from './boundary.js';
+import { RUN_LOG_PROTOCOL_VERSION, RUN_LOG_VERSION, applyEngineStep, buildEngineBoot, contextFromBoot, createEngineBoot, requestFromBoot, validateEngineBoot } from './protocol.js';
+import { XSTATE_VERSION, RunJournal, acquireRun, forkRepeatsSettledWrite, readRequests, readRunLog, recoveryAdvice, safeForkLength, unresolvedWriteIds, unsettledRedactedIds } from './run-journal.js';
+export class RunLog extends RunJournal {
+    static VERSION = RUN_LOG_VERSION;
+    static PROTOCOL_VERSION = RUN_LOG_PROTOCOL_VERSION;
+    static XSTATE_VERSION = XSTATE_VERSION;
+    static read = readRunLog;
+    static fromRecords = recordLog;
+    static requests = readRequests;
+    static replay = replayRun;
+    static parseSnapshot = parsePersistedSnapshot;
+    static inspect = inspectRun;
+    static renderHtml = renderRunLogHtml;
+    static watch = () => new RunLogWatch();
+    static createRedactor = createRunLogRedactor;
+    static createEngineBoot = createEngineBoot;
+    static buildEngineBoot = buildEngineBoot;
+    static validateEngineBoot = validateEngineBoot;
+    static applyEngineStep = applyEngineStep;
+    static contextFromBoot = contextFromBoot;
+    static requestFromBoot = requestFromBoot;
+    static safeForkLength = safeForkLength;
+    static recoveryAdvice = recoveryAdvice;
+    static unresolvedWriteIds = unresolvedWriteIds;
+    static unsettledRedactedIds = unsettledRedactedIds;
+    static forkRepeatsSettledWrite = forkRepeatsSettledWrite;
+    static openBoundary = openBoundaryJournal;
+    static boundaryBoot = boundaryBoot;
+    static createPersistedActor = createPersistedActor;
+    static acquireRun = acquireRun;
+}
+export { InvalidEngineStep } from './protocol.js';
+export { RunIncompatible } from './run-journal.js';
+export { ReplayDivergence, ReplayTraceDivergence } from './replay.js';

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

@@ -0,0 +1,53 @@
+import { type RunLogInspectionEntry, type RunRecord } from './run-journal.ts';
+import type { MachineLog } from './protocol-types.ts';
+interface InspectionOptions {
+    recordLimit?: number;
+    contextRecord?: number;
+    requestRecord?: number;
+    physicalLength?: number;
+    contextPhysicalLength?: number;
+    expectedMachineVersion?: number;
+    expectedXstateVersion?: string;
+}
+export interface PositionedRunRecord {
+    recordIndex: number;
+    stepSeq: number;
+    physicalLength: number;
+    record: RunRecord;
+}
+interface PositionedInspectionEnvelope {
+    records: () => AsyncIterable<PositionedRunRecord>;
+    physicalLength?: unknown;
+    logicalLength?: unknown;
+    nextSeq?: unknown;
+}
+type InspectionCore = MachineLog | PositionedInspectionEnvelope;
+type Position = Pick<PositionedRunRecord, 'stepSeq' | 'physicalLength'>;
+export declare function recordLog(values: RunRecord[]): MachineLog;
+export declare function stateValue(snapshot: unknown): unknown;
+export declare function contextValue(snapshot: unknown): unknown;
+interface RecordLineOptions {
+    position?: Position;
+    context?: boolean;
+    expectedMachineVersion?: number;
+    expectedXstateVersion?: string;
+    requestRecord?: number;
+}
+export declare class RecordLines {
+    private previous;
+    private base;
+    private readonly requests;
+    printedRequest: boolean;
+    render(entry: RunLogInspectionEntry, opts?: RecordLineOptions): string[];
+    private transitionLines;
+}
+export declare function verificationLine(core: MachineLog, machine: number | undefined, xstate: string | undefined): Promise<string>;
+export declare function inspectRun(core: InspectionCore, opts?: InspectionOptions): AsyncGenerator<string>;
+export declare function escapeHtml(value: string): string;
+export declare function activeStatePaths(definition: unknown, value: unknown): string[];
+export declare const HTML_HEAD: string;
+export declare const HTML_RECORDS_END = "</pre>";
+export declare const HTML_TAIL = "</body></html>";
+export declare function htmlRunStart(definition: unknown): string;
+export declare function renderRunLogHtml(core: InspectionCore, opts?: InspectionOptions): Promise<string>;
+export {};