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

package/dist-lib/lib/{run-log-inspect.js → run-log/inspect.js}

@@ -1,5 +1,9 @@
-import { MACHINE_VERSION, XSTATE_VERSION, createCompletionMachine, replayRun, ReplayDivergence, ReplayTraceDivergence, readRunLog } from './machine/index.js';
-import { errorMessage, isRecord } from './guards.js';
+import { CompletionMachine } from '../machine/index.js';
+import { replayRun, ReplayDivergence, ReplayTraceDivergence } from './replay.js';
+import { RUN_LOG_VERSION, XSTATE_VERSION, readRunLog } from './run-journal.js';
+import { requestMessages } from './history-codec.js';
+import { RequestDecoder } from './request-codec.js';
+import { errorMessage, isRecord } from '../guards.js';
 function isPositionedInspectionCore(core) {
     return 'records' in core && typeof core.records === 'function';
 }
@@ -70,7 +74,10 @@ async function inspectionLog(core) {
             throw new TypeError(`Run export nextSeq ${exportNextSeq} does not match last positioned step boundary ${actualNextSeq}`);
         }
     }
-    const log = {
+    return { log: recordLog(values), positions, exportPhysicalLength };
+}
+export function recordLog(values) {
+    return {
         get length() {
             return values.length;
         },
@@ -85,28 +92,28 @@ async function inspectionLog(core) {
             values.push(value);
         }
     };
-    return { log, positions, exportPhysicalLength };
 }
 const MAX_JSON = 300;
 function json(value, limit = MAX_JSON) {
     const text = JSON.stringify(value) ?? 'undefined';
     return text.length > limit ? `${text.slice(0, limit)}…` : text;
 }
-function stateValue(snapshot) {
+export function stateValue(snapshot) {
     return isRecord(snapshot) ? snapshot.value : undefined;
 }
-function contextValue(snapshot) {
+export function contextValue(snapshot) {
     return isRecord(snapshot) ? snapshot.context : undefined;
 }
 function isRunRecord(value) {
-    if (!isRecord(value) || value.version !== 5) {
+    if (!isRecord(value) || value.version !== RUN_LOG_VERSION) {
         return false;
     }
     return (value.type === 'metadata' ||
         value.type === 'fork' ||
         value.type === 'checkpoint' ||
         value.type === 'delta' ||
-        value.type === 'operation');
+        value.type === 'operation' ||
+        value.type === 'request');
 }
 function changedValues({ patch, before, after, path = '', out = [] }) {
     if (!isRecord(patch))
@@ -161,9 +168,109 @@ function operationLine(index, record) {
     const detail = receipt.status === 'result' ? ` result=${json(receipt.result)}` : ` args=${json(receipt.args)}`;
     return `recordIndex ${index} ${receipt.status} ${receipt.effect} ${receipt.name}${detail}`;
 }
+function metadataLines(index, record, opts) {
+    const lines = [
+        `recordIndex ${index} run ${record.runId} log v${record.version} machine v${record.machine} xstate ${record.xstate ?? '?'}`
+    ];
+    if (opts.position) {
+        lines.push(positionLine(index, opts.position));
+    }
+    if (CompletionMachine.VERSION !== record.machine) {
+        lines.push(`recordIndex ${index} machine drift: local v${CompletionMachine.VERSION}; recorded v${record.machine}; recorded definition and snapshots remain authoritative`);
+    }
+    if (XSTATE_VERSION !== record.xstate) {
+        lines.push(`recordIndex ${index} XState drift: local ${XSTATE_VERSION}; recorded ${record.xstate ?? '?'}; recorded definition and snapshots remain authoritative`);
+    }
+    if (opts.expectedMachineVersion !== undefined &&
+        opts.expectedMachineVersion !== CompletionMachine.VERSION) {
+        lines.push(`recordIndex ${index} caller expected machine v${opts.expectedMachineVersion}; this inspector runs v${CompletionMachine.VERSION}`);
+    }
+    if (opts.expectedXstateVersion !== undefined && opts.expectedXstateVersion !== XSTATE_VERSION) {
+        lines.push(`recordIndex ${index} caller expected XState ${opts.expectedXstateVersion}; this inspector runs ${XSTATE_VERSION}`);
+    }
+    if (opts.context) {
+        lines.push(`recordIndex ${index} context undefined (no checkpoint yet)`);
+    }
+    return lines;
+}
+function positionLine(index, position) {
+    return `recordIndex ${index} stepSeq ${position.stepSeq} physicalLength ${position.physicalLength}`;
+}
+export class RecordLines {
+    previous;
+    base;
+    requests = new RequestDecoder();
+    printedRequest = false;
+    render(entry, opts = {}) {
+        const { index, record, snapshot } = entry;
+        if (record.type === 'metadata') {
+            this.base = requestMessages(record.request);
+            return metadataLines(index, record, opts);
+        }
+        const lines = opts.position ? [positionLine(index, opts.position)] : [];
+        if (record.type === 'operation') {
+            lines.push(operationLine(index, record));
+        }
+        else if (record.type === 'fork') {
+            lines.push(`recordIndex ${index} fork ${record.runId} of ${record.forkedFrom.runId} at recordIndex ${record.forkedFrom.length}`);
+        }
+        else if (record.type === 'request') {
+            lines.push(requestLine(index, record));
+            const params = this.requests.decode(record, this.base);
+            if (opts.requestRecord === index) {
+                this.printedRequest = true;
+                lines.push(`recordIndex ${index} request params ${JSON.stringify(params)}`);
+            }
+        }
+        else {
+            lines.push(...this.transitionLines(entry));
+        }
+        if (opts.context) {
+            lines.push(`recordIndex ${index} context ${JSON.stringify(contextValue(snapshot)) ?? 'undefined'}`);
+        }
+        if (record.type !== 'operation' && record.type !== 'request') {
+            this.previous = snapshot;
+        }
+        return lines;
+    }
+    transitionLines({ index, record, snapshot, events }) {
+        if (record.type !== 'checkpoint' && record.type !== 'delta') {
+            return [];
+        }
+        const previous = this.previous;
+        const lines = [
+            `recordIndex ${index} ${record.type} state ${json(stateValue(previous))} -> ${json(stateValue(snapshot))}`
+        ];
+        for (const trace of record.trace ?? []) {
+            lines.push(`recordIndex ${index} ${traceLine(trace)}`);
+        }
+        if (!record.trace?.length && events.length) {
+            lines.push(`recordIndex ${index} transition trace unavailable; decoded events are shown`);
+        }
+        for (const event of events) {
+            lines.push(`recordIndex ${index} event ${json(event)}`);
+        }
+        if (record.type === 'delta' && record.patch) {
+            const paths = changedValues({ patch: record.patch, before: previous, after: snapshot });
+            if (paths.length) {
+                lines.push(`recordIndex ${index} changed ${paths.join('; ')}`);
+            }
+        }
+        return lines;
+    }
+}
+function requestLine(index, record) {
+    const messages = record.messages;
+    const appended = '$qvacHistory' in messages ? messages.$qvacHistory.items.length : messages.length;
+    const tools = record.tools
+        ? ` tools ${record.tools.ref.slice(0, 12)}${record.tools.block ? ' inline' : ''}`
+        : '';
+    return `recordIndex ${index} request round ${record.round} attempt ${record.attempt} droppedTurns ${record.droppedTurns} keep ${record.keep} +${appended}${tools}`;
+}
 async function* readInspection(source, opts) {
     validateIndex('recordLimit', opts.recordLimit);
     validateIndex('contextRecord', opts.contextRecord);
+    validateIndex('requestRecord', opts.requestRecord);
     validateIndex('physicalLength', opts.physicalLength);
     validateIndex('contextPhysicalLength', opts.contextPhysicalLength);
     if (opts.contextRecord !== undefined && opts.contextPhysicalLength !== undefined) {
@@ -189,10 +296,9 @@ async function* readInspection(source, opts) {
             throw new RangeError(`contextRecord ${opts.contextRecord} is beyond physicalLength ${opts.physicalLength}`);
         }
     }
-    let previous;
+    const lines = new RecordLines();
     let recordedMachine;
     let recordedXstate;
-    let hasLegacyRecords = false;
     let physicalContextRecord;
     if (positions && exportPhysicalLength === undefined) {
         yield {
@@ -242,7 +348,7 @@ async function* readInspection(source, opts) {
             line: `physicalLength ${opts.physicalLength} is not a represented step boundary; rows show the latest committed steps at or before it, not a validated physical prefix`
         };
     }
-    for await (const item of readRunLog(core, { anyMachine: true, legacyInspection: true })) {
+    for await (const item of readRunLog(core, { anyMachine: true })) {
         if (opts.recordLimit !== undefined && item.index >= opts.recordLimit)
             break;
         const itemPosition = positions?.get(item.index);
@@ -251,133 +357,45 @@ async function* readInspection(source, opts) {
             itemPosition.physicalLength > opts.physicalLength) {
             break;
         }
-        const { index, sourceVersion, record, snapshot, events } = item;
-        if (sourceVersion !== 5) {
-            hasLegacyRecords = true;
-        }
+        const { record } = item;
         if (record.type === 'metadata') {
             recordedMachine = record.machine;
             recordedXstate = record.xstate;
-            yield {
-                line: `recordIndex ${index} run ${record.runId} log v${sourceVersion}${sourceVersion === 4 ? ' (read-only)' : ''} machine v${record.machine} xstate ${record.xstate ?? '?'}`,
-                definition: record.definition
-            };
-            if (sourceVersion === 4) {
-                yield {
-                    line: `recordIndex ${index} v4 records are normalized only for read-only inspection; resume and replay use strict current-version checks`
-                };
-            }
-            const position = positions?.get(index);
-            if (position) {
-                yield {
-                    line: `recordIndex ${index} stepSeq ${position.stepSeq} physicalLength ${position.physicalLength}`
-                };
-            }
-            if (MACHINE_VERSION !== record.machine) {
-                yield {
-                    line: `recordIndex ${index} machine drift: local v${MACHINE_VERSION}; recorded v${record.machine}; recorded definition and snapshots remain authoritative`
-                };
-            }
-            if (XSTATE_VERSION !== record.xstate) {
-                yield {
-                    line: `recordIndex ${index} XState drift: local ${XSTATE_VERSION}; recorded ${record.xstate ?? '?'}; recorded definition and snapshots remain authoritative`
-                };
-            }
-            if (opts.expectedMachineVersion !== undefined &&
-                opts.expectedMachineVersion !== MACHINE_VERSION) {
-                yield {
-                    line: `recordIndex ${index} caller expected machine v${opts.expectedMachineVersion}; this inspector runs v${MACHINE_VERSION}`
-                };
-            }
-            if (opts.expectedXstateVersion !== undefined &&
-                opts.expectedXstateVersion !== XSTATE_VERSION) {
-                yield {
-                    line: `recordIndex ${index} caller expected XState ${opts.expectedXstateVersion}; this inspector runs ${XSTATE_VERSION}`
-                };
-            }
-            if (contextRecord === index) {
-                yield { line: `recordIndex ${index} context undefined (no checkpoint yet)` };
-            }
-            continue;
         }
-        const position = positions?.get(index);
-        if (position) {
-            yield {
-                line: `recordIndex ${index} stepSeq ${position.stepSeq} physicalLength ${position.physicalLength}`
-            };
-        }
-        if (record.type === 'operation') {
-            yield { line: operationLine(index, record) };
-            if (contextRecord === index) {
-                const context = contextValue(snapshot);
-                yield { line: `recordIndex ${index} context ${JSON.stringify(context) ?? 'undefined'}` };
-            }
-            continue;
-        }
-        if (record.type === 'fork') {
-            yield {
-                line: `recordIndex ${index} fork ${record.runId} of ${record.forkedFrom.runId} at recordIndex ${record.forkedFrom.length}`
-            };
-            if (contextRecord === index) {
-                const context = contextValue(snapshot);
-                yield { line: `recordIndex ${index} context ${JSON.stringify(context) ?? 'undefined'}` };
-            }
-            previous = snapshot;
-            continue;
-        }
-        const before = stateValue(previous);
-        const after = stateValue(snapshot);
-        yield {
-            line: `recordIndex ${index} ${record.type} state ${json(before)} -> ${json(after)}`
-        };
-        for (const trace of record.trace ?? []) {
-            yield { line: `recordIndex ${index} ${traceLine(trace)}` };
-        }
-        if (!record.trace?.length && events.length) {
-            yield {
-                line: sourceVersion === 4
-                    ? `recordIndex ${index} legacy v4 has no recorded microstep guard/action trace; decoded events are shown`
-                    : `recordIndex ${index} transition trace unavailable; decoded events are shown`
-            };
-        }
-        for (const event of events) {
-            yield { line: `recordIndex ${index} event ${json(event)}` };
-        }
-        if (record.type === 'delta' && record.patch) {
-            const paths = changedValues({ patch: record.patch, before: previous, after: snapshot });
-            if (paths.length) {
-                yield { line: `recordIndex ${index} changed ${paths.join('; ')}` };
-            }
-        }
-        if (contextRecord === index) {
-            const context = contextValue(snapshot);
-            yield { line: `recordIndex ${index} context ${JSON.stringify(context) ?? 'undefined'}` };
+        const rendered = lines.render(item, {
+            position: positions?.get(item.index),
+            context: contextRecord === item.index,
+            requestRecord: opts.requestRecord,
+            expectedMachineVersion: opts.expectedMachineVersion,
+            expectedXstateVersion: opts.expectedXstateVersion
+        });
+        for (const [i, line] of rendered.entries()) {
+            yield i === 0 && record.type === 'metadata'
+                ? { line, definition: record.definition }
+                : { line };
         }
-        previous = snapshot;
+    }
+    if (opts.requestRecord !== undefined && !lines.printedRequest) {
+        yield { line: `recordIndex ${opts.requestRecord} is not a request record in this selection` };
     }
     if (opts.recordLimit !== undefined || opts.physicalLength !== undefined) {
         yield {
             line: 'replay verification skipped: a recordIndex or physicalLength limit selected a prefix; recorded snapshots remain authoritative'
         };
     }
-    else if (recordedMachine !== undefined && recordedXstate !== undefined) {
-        if (hasLegacyRecords ||
-            recordedMachine !== MACHINE_VERSION ||
-            recordedXstate !== XSTATE_VERSION) {
-            yield {
-                line: 'replay verification skipped: recorded log, machine, or XState version differs from this implementation; stored snapshots and recorded transition traces remain authoritative'
-            };
-        }
-        else {
-            yield { line: await replayVerificationLine(core) };
-        }
-    }
     else {
-        yield {
-            line: 'state/context replay unavailable: run metadata does not record both machine and XState versions'
-        };
+        yield { line: await verificationLine(core, recordedMachine, recordedXstate) };
     }
 }
+export async function verificationLine(core, machine, xstate) {
+    if (machine === undefined || xstate === undefined) {
+        return 'state/context replay unavailable: run metadata does not record both machine and XState versions';
+    }
+    if (machine !== CompletionMachine.VERSION || xstate !== XSTATE_VERSION) {
+        return 'replay verification skipped: recorded machine or XState version differs from this implementation; stored snapshots and recorded transition traces remain authoritative';
+    }
+    return await replayVerificationLine(core);
+}
 function selectPhysicalContext(positions, requestedLength, exportPhysicalLength) {
     if (!positions) {
         return {
@@ -427,7 +445,7 @@ function selectPhysicalContext(positions, requestedLength, exportPhysicalLength)
 async function replayVerificationLine(core) {
     try {
         let checked = 0;
-        for await (const _step of replayRun(createCompletionMachine(), core)) {
+        for await (const _step of replayRun(CompletionMachine.create(), core)) {
             checked++;
         }
         return `state/context replay and event-triggered guard/action traces matched for ${checked} recorded event${checked === 1 ? '' : 's'}; eventless guard/action traces are not replay-verified; stored snapshots remain authoritative`;
@@ -452,7 +470,7 @@ export async function* inspectRun(core, opts = {}) {
         yield line;
     }
 }
-function escapeHtml(value) {
+export function escapeHtml(value) {
     return value
         .replace(/&/g, '&')
         .replace(/</g, '&lt;')
@@ -477,6 +495,29 @@ function transitionParts(event, transition) {
 function stateDefinition(value) {
     return isRecord(value) ? value : undefined;
 }
+function nodeLabel(node, fallbackId) {
+    return typeof node.id === 'string' ? graphText(node.id) : graphText(fallbackId);
+}
+export function activeStatePaths(definition, value) {
+    const root = stateDefinition(definition);
+    if (!root) {
+        return [];
+    }
+    const out = [];
+    const walk = (node, path) => {
+        if (typeof node === 'string') {
+            out.push(`${path}.${node}`);
+        }
+        else if (isRecord(node)) {
+            for (const [key, child] of Object.entries(node)) {
+                out.push(`${path}.${key}`);
+                walk(child, `${path}.${key}`);
+            }
+        }
+    };
+    walk(value, nodeLabel(root, 'root'));
+    return out;
+}
 function renderTransitionPaths(node, context) {
     const paths = [];
     for (const item of node.events) {
@@ -508,16 +549,15 @@ function renderDefinition(definition) {
         return '<p>No machine definition was recorded.</p>';
     }
     const nodes = [];
-    const work = [
-        { node: root, fallbackId: 'root', depth: 0 }
-    ];
+    const work = [{ node: root, fallbackId: 'root', depth: 0 }];
     while (work.length && nodes.length < MAX_GRAPH_NODES) {
         const entry = work.pop();
         if (!entry) {
             continue;
         }
         const index = nodes.length;
-        const id = typeof entry.node.id === 'string' ? graphText(entry.node.id) : graphText(entry.fallbackId);
+        const id = nodeLabel(entry.node, entry.fallbackId);
+        const path = entry.path ?? id;
         const events = [];
         const transitions = isRecord(entry.node.on) ? entry.node.on : {};
         for (const [event, listed] of Object.entries(transitions)) {
@@ -533,6 +573,7 @@ function renderDefinition(definition) {
         nodes.push({
             index,
             id,
+            path,
             depth: entry.depth,
             parent: entry.parent,
             events,
@@ -550,7 +591,13 @@ function renderDefinition(definition) {
             const [key, child] = childEntry;
             const childDefinition = stateDefinition(child);
             if (childDefinition) {
-                work.push({ node: childDefinition, fallbackId: key, depth: entry.depth + 1, parent: index });
+                work.push({
+                    node: childDefinition,
+                    fallbackId: key,
+                    path: `${path}.${key}`,
+                    depth: entry.depth + 1,
+                    parent: index
+                });
             }
         }
     }
@@ -589,7 +636,7 @@ function renderDefinition(definition) {
     for (const node of nodes) {
         const nx = x(node);
         const ny = y(node);
-        parts.push(`<g class="state"><rect x="${nx}" y="${ny}" width="${nodeWidth}" height="${nodeHeight}" rx="6"/><text x="${nx + 9}" y="${ny + 25}">${escapeHtml(node.id)}</text></g>`);
+        parts.push(`<g class="state" data-state="${escapeHtml(node.path)}"><rect x="${nx}" y="${ny}" width="${nodeWidth}" height="${nodeHeight}" rx="6"/><text x="${nx + 9}" y="${ny + 25}">${escapeHtml(node.id)}</text></g>`);
         for (const invoke of node.invokes) {
             parts.push(`<text class="invoke" x="${nx + 4}" y="${ny + nodeHeight + 17}">invoke ${escapeHtml(invoke)}</text>`);
         }
@@ -608,6 +655,18 @@ function renderDefinition(definition) {
     }
     return parts.join('');
 }
+export const HTML_HEAD = '<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">' +
+    '<title>Run log inspection</title><style>body{font:14px system-ui;margin:2rem;line-height:1.5}' +
+    'pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#f4f4f4;padding:1rem}' +
+    'svg{max-height:75vh;background:#fafbfc;border:1px solid #d5dae0}svg .hierarchy{stroke:#a8b0bc;stroke-width:1.4}svg .transition{fill:none;stroke:#526071;stroke-width:1.5}svg .state rect{fill:#fff;stroke:#435168;stroke-width:1.5}svg text{font:12px system-ui;fill:#17212e}svg .edge-label{font-size:10px;fill:#39485c}svg .invoke,svg .unresolved{font-size:10px;fill:#536176}' +
+    '</style></head><body>';
+export const HTML_RECORDS_END = '</pre>';
+export const HTML_TAIL = '</body></html>';
+export function htmlRunStart(definition) {
+    return ('<h1>Recorded machine definition</h1>' +
+        renderDefinition(definition) +
+        '<h1>Run records</h1><pre>');
+}
 export async function renderRunLogHtml(core, opts = {}) {
     let definition;
     const lines = [];
@@ -617,11 +676,9 @@ export async function renderRunLogHtml(core, opts = {}) {
             definition = item.definition;
         }
     }
-    return ('<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">' +
-        '<title>Run log inspection</title><style>body{font:14px system-ui;margin:2rem;line-height:1.5}' +
-        'pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#f4f4f4;padding:1rem}' +
-        'svg{max-height:75vh;background:#fafbfc;border:1px solid #d5dae0}svg .hierarchy{stroke:#a8b0bc;stroke-width:1.4}svg .transition{fill:none;stroke:#526071;stroke-width:1.5}svg .state rect{fill:#fff;stroke:#435168;stroke-width:1.5}svg text{font:12px system-ui;fill:#17212e}svg .edge-label{font-size:10px;fill:#39485c}svg .invoke,svg .unresolved{font-size:10px;fill:#536176}' +
-        '</style></head><body><h1>Recorded machine definition</h1>' +
-        renderDefinition(definition) +
-        `<h1>Run records</h1><pre>${escapeHtml(lines.join('\n'))}</pre></body></html>`);
+    return (HTML_HEAD +
+        htmlRunStart(definition) +
+        escapeHtml(lines.join('\n')) +
+        HTML_RECORDS_END +
+        HTML_TAIL);
 }

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

@@ -0,0 +1,37 @@
+import type { CompletionContext } from '../machine/index.ts';
+import type { EngineStep, HostRunLog, MachineTransitionTrace } from './protocol-types.ts';
+export interface RunLogView {
+    runId: string;
+    seq: number;
+    index: number;
+    state: unknown;
+    trace: MachineTransitionTrace[];
+    lines: string[];
+    approval: CompletionContext['approval'] | null;
+    pendingCall: CompletionContext['pendingCall'];
+    currentCall: CompletionContext['currentCall'];
+    toolQueue: CompletionContext['toolQueue'];
+    outcome: CompletionContext['outcome'];
+    error?: string;
+}
+export declare class RunLogWatch {
+    private readonly viewFeed;
+    private readonly htmlFeed;
+    private readonly runs;
+    private open;
+    private graphs;
+    private started;
+    private ended;
+    private pending;
+    step(step: EngineStep): void;
+    views(): AsyncIterable<RunLogView>;
+    html(): AsyncIterable<string>;
+    host(inner: HostRunLog): HostRunLog;
+    end(): Promise<void>;
+    private feed;
+    private record;
+    private show;
+    private start;
+    private close;
+    private write;
+}