@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/runs/transcript-facts.js

@@ -0,0 +1,193 @@
+/**
+ * Incremental transcript facts for delivery and delegation reconciliation. Keep history
+ * authoritative and sidecars rebuildable; avoid whole-transcript reads on hot paths.
+ */
+import { logPrefix } from '../home/display.js';
+import { randomBytes } from 'node:crypto';
+import { renameSync, rmSync, writeFileSync } from 'node:fs';
+import { historyPaths, historyStat } from './history-file.js';
+export { emptyFacts, foldEvent, foldText, stampOf, PROSE_HUMAN_GATE, workerOutcomeKey } from './transcript-facts-fold.js';
+import { emptyFacts, foldEvent, sameStamp, stampOf } from './transcript-facts-fold.js';
+import { readFactsSidecar } from './transcript-facts-load.js';
+import { REFRESH_FACTS, TranscriptFactsQueue } from './transcript-facts-queue.js';
+/**
+ * Per-run facts sidecar, updated on append and validated by plain byte length or archive
+ * identity. Rebuild unreadable or stale cache state from history.
+ */
+export class TranscriptFactsIndex {
+    dataDir;
+    readOnly;
+    entries = new Map();
+    warnedWrite = new Set();
+    stopped = false;
+    queue;
+    constructor(dataDir, readOnly = false) {
+        this.dataDir = dataDir;
+        this.readOnly = readOnly;
+        this.queue = new TranscriptFactsQueue(dataDir, (id, loaded, serialized) => this.accept(id, loaded, serialized), (id) => this.peek(id) ? this.entries.get(id) : undefined);
+    }
+    /** Read only an already-current entry or exact sidecar; never decode/fold history. */
+    peek(runId) {
+        const cached = this.entries.get(runId);
+        if (cached && this.current(runId, cached.facts))
+            return cached.facts;
+        const stored = readFactsSidecar(historyPaths(this.dataDir, runId).facts);
+        if (stored && this.current(runId, stored)) {
+            this.entries.set(runId, { facts: stored, written: stored.bytes });
+            return stored;
+        }
+        // No transcript at all (a run that has not emitted yet) has empty facts and nothing to
+        // decode — the answer `loadTranscriptFacts` gives, settled here with one stat. Sending it to
+        // the worker cost a whole Worker boot per run (hearsay-tools/cezarion#1059).
+        if (!this.hasTranscript(runId)) {
+            const facts = emptyFacts();
+            this.entries.set(runId, { facts, written: 0 });
+            return facts;
+        }
+        return undefined;
+    }
+    /** True when the run has a plain or archived transcript, or when that cannot be told. */
+    hasTranscript(runId) {
+        try {
+            const { plainSize, archive } = historyStat(this.dataDir, runId);
+            return plainSize !== undefined || archive !== undefined;
+        }
+        catch {
+            return true;
+        }
+    }
+    async ready(runId) {
+        if (this.stopped)
+            throw new Error('Transcript facts index stopped');
+        // An in-flight owner remains authoritative even if a sidecar appears meanwhile.
+        if (!this.queue.has(runId)) {
+            const facts = this.peek(runId);
+            if (facts)
+                return facts;
+        }
+        return (await this.queue.request(runId))?.facts;
+    }
+    /** Undefined only when the transcript exists but cannot be read; that answer is not cached. */
+    get(runId) {
+        return this.entry(runId)?.facts;
+    }
+    /** After `line` (of `lineBytes` bytes) was appended to the plain transcript. */
+    append(runId, event, lineBytes) {
+        const cached = this.entries.get(runId);
+        // A first load reads the transcript, which already holds this line. So does a reload when
+        // the transcript is not exactly the cached bytes plus this line: another writer got there.
+        if (!cached || historyStat(this.dataDir, runId).plainSize !== cached.facts.bytes + lineBytes) {
+            this.entries.delete(runId);
+            this.entry(runId);
+            return;
+        }
+        delete cached.facts.archive;
+        const changed = foldEvent(cached.facts, event);
+        cached.facts.bytes += lineBytes;
+        if (changed)
+            this.persist(runId, cached);
+    }
+    /** The compressor archived `plain` as a `.br` with `stamp`. */
+    adoptArchive(runId, plain, stamp) {
+        if (this.stopped)
+            return;
+        const entry = this.entries.get(runId);
+        if (!entry || entry.facts.bytes !== plain.length) {
+            this.entries.delete(runId);
+            // The compressor callback runs on the parent loop. Keep an active job's ownership:
+            // its old snapshot will fail validation and refresh from the newly committed archive.
+            // Without an owner, queue the rebuild too; never decode/fold the compressor's buffer here.
+            void this.queue.request(runId, false).catch(() => undefined);
+            return;
+        }
+        entry.facts.archive = stamp;
+        this.persist(runId, entry);
+    }
+    /** Persist every entry whose byte count moved since its last write. */
+    flush() {
+        for (const [runId, entry] of this.entries)
+            if (entry.written !== entry.facts.bytes)
+                this.persist(runId, entry);
+    }
+    forget(runId) {
+        this.entries.delete(runId);
+        this.queue.forget(runId);
+    }
+    /** Register all IDs without reading history; requested runs can overtake background work. */
+    async warm(runIds) {
+        if (this.stopped)
+            return;
+        await Promise.all([...new Set(runIds)].map((id) => this.queue.request(id, false)));
+    }
+    /** Stop warming (store close). */
+    stop() {
+        this.stopped = true;
+        this.queue.stop();
+    }
+    entry(runId) {
+        const cached = this.entries.get(runId);
+        if (cached && this.current(runId, cached.facts))
+            return cached;
+        // Another process may have written the transcript since: reload from the sidecar and tail.
+        if (cached)
+            this.entries.delete(runId);
+        if (this.stopped)
+            return undefined;
+        return this.queue.join(runId);
+    }
+    accept(runId, loaded, serialized) {
+        const newer = this.entries.get(runId);
+        if (newer && this.current(runId, newer.facts))
+            return newer;
+        if (!loaded)
+            return undefined;
+        if (!this.current(runId, loaded.facts))
+            return REFRESH_FACTS;
+        const entry = { facts: loaded.facts, written: loaded.written };
+        try {
+            if (loaded.needsWrite)
+                this.persist(runId, entry, serialized);
+        }
+        catch {
+            return undefined;
+        }
+        this.entries.set(runId, entry);
+        return entry;
+    }
+    /** A cache hit costs one stat (two once archived): the run may have changed hands (a second
+     *  process on the project, an adopted family) since these facts were cached. */
+    current(runId, facts) {
+        try {
+            const { plainSize, archive } = historyStat(this.dataDir, runId);
+            if (plainSize !== undefined)
+                return plainSize === facts.bytes;
+            if (archive)
+                return sameStamp(facts.archive, stampOf(archive));
+            return facts.bytes === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    persist(runId, entry, serialized) {
+        if (this.readOnly) {
+            entry.written = entry.facts.bytes;
+            return;
+        }
+        const path = historyPaths(this.dataDir, runId).facts;
+        const tmp = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+        try {
+            writeFileSync(tmp, serialized ?? JSON.stringify(entry.facts), { mode: 0o600 });
+            renameSync(tmp, path);
+            entry.written = entry.facts.bytes;
+        }
+        catch (error) {
+            rmSync(tmp, { force: true });
+            if (!this.warnedWrite.has(runId)) {
+                this.warnedWrite.add(runId);
+                console.warn(`${logPrefix()} could not save transcript facts for ${runId}: ${error.message}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=transcript-facts.js.map

package/dist/runs/transcript-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-facts.js","sourceRoot":"","sources":["../../src/runs/transcript-facts.ts"],"names":[],"mappings":"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"}

package/dist/runs/ui-event-sink.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persist meaningful v2 snapshots and usage changes; coalesce deltas onto the live wire only.
+ * appendEvent fans persisted events out once. Output failures remain best-effort so additive v2
+ * cannot fail the v1 session.
+ */
+import type { StopReason, UiEvent } from '../core/ui-events.ts';
+/** Spec guardrail: coalesce `item.delta` at ~30–50 ms boundaries. */
+export declare const DELTA_FLUSH_MS = 40;
+/**
+ * Persisted v1/v2 lines share sequence allocation but use run-event/ui-event SSE names. Dotted
+ * types identify v2; raw v2 image data is dropped in favor of the v1 file-backed image pipeline.
+ */
+export declare function isV2WireEventType(type: string): boolean;
+/** A loose event as the store consumes it (the sink adds no seq/ts — the
+ *  store stamps those). */
+type WireEvent = {
+    type: string;
+    [key: string]: unknown;
+};
+export interface UiEventSinkOutput {
+    /** Append to the run's NDJSON file (which also fans out live). */
+    persist(event: WireEvent): void;
+    /** Fan out live only — never written to disk (coalesced deltas). */
+    emitLive(event: WireEvent): void;
+    /** Every event the sink handles, before coalescing: the tool activity tracker's feed. */
+    observe?(event: UiEvent): void;
+}
+export declare class UiEventSink {
+    private readonly out;
+    private readonly flushMs;
+    /** Pending delta text per open item, per streamed field (insertion order
+     *  preserved so a flush replays fields in first-arrival order). */
+    private readonly buffers;
+    private readonly timers;
+    /** Last persisted non-streamed shape per item — the `item.updated`
+     *  meaningful-change filter. */
+    private readonly shapes;
+    private lastUsage;
+    private ended;
+    constructor(out: UiEventSinkOutput, flushMs?: number);
+    /** Fold one runner-emitted v2 event into the persist/live outputs. */
+    handle(event: UiEvent): void;
+    /**
+     * Session close, called by the RunManager exactly once when the v1 session
+     * settles: flush everything, then persist v2 `session.error` (fatal) when
+     * the session failed, and `session.ended` — the v2 counterparts of v1's
+     * `done`/`error`, which the mappers deliberately left to the RunManager.
+     */
+    sessionEnded(reason: StopReason, errorMessage?: string): void;
+    /** Flush every open coalescer now (turn end, session settle). */
+    flushAll(): void;
+    private bufferDelta;
+    /** Emit one merged `item.delta` per buffered field of the item, live only. */
+    private flushItem;
+    private persist;
+    private observe;
+    private emitLive;
+}
+export {};

package/dist/runs/ui-event-sink.js

@@ -0,0 +1,197 @@
+/**
+ * Persist meaningful v2 snapshots and usage changes; coalesce deltas onto the live wire only.
+ * appendEvent fans persisted events out once. Output failures remain best-effort so additive v2
+ * cannot fail the v1 session.
+ */
+/** Spec guardrail: coalesce `item.delta` at ~30–50 ms boundaries. */
+export const DELTA_FLUSH_MS = 40;
+/** Backstop so one item can never buffer unboundedly within a window. */
+const MAX_DELTA_BUFFER = 64_000;
+/**
+ * Persisted v1/v2 lines share sequence allocation but use run-event/ui-event SSE names. Dotted
+ * types identify v2; raw v2 image data is dropped in favor of the v1 file-backed image pipeline.
+ */
+export function isV2WireEventType(type) {
+    return type.includes('.');
+}
+export class UiEventSink {
+    out;
+    flushMs;
+    /** Pending delta text per open item, per streamed field (insertion order
+     *  preserved so a flush replays fields in first-arrival order). */
+    buffers = new Map();
+    timers = new Map();
+    /** Last persisted non-streamed shape per item — the `item.updated`
+     *  meaningful-change filter. */
+    shapes = new Map();
+    lastUsage = null;
+    ended = false;
+    constructor(out, flushMs = DELTA_FLUSH_MS) {
+        this.out = out;
+        this.flushMs = flushMs;
+    }
+    /** Fold one runner-emitted v2 event into the persist/live outputs. */
+    handle(event) {
+        if (this.ended)
+            return;
+        this.observe(event);
+        switch (event.type) {
+            case 'item.delta':
+                this.bufferDelta(event);
+                return;
+            case 'item.started':
+                this.shapes.set(event.item.id, itemShape(event.item));
+                this.persist(event);
+                return;
+            case 'item.updated': {
+                // Chronology: the item's buffered deltas reach the live wire before
+                // the snapshot that supersedes them.
+                this.flushItem(event.item.id);
+                const shape = itemShape(event.item);
+                if (this.shapes.get(event.item.id) === shape) {
+                    // Streamed-content-only growth — live consumers still get the
+                    // snapshot, the disk stays at snapshot-change frequency.
+                    this.emitLive(event);
+                    return;
+                }
+                this.shapes.set(event.item.id, shape);
+                this.persist(event);
+                return;
+            }
+            case 'item.completed':
+                this.flushItem(event.item.id);
+                this.shapes.delete(event.item.id);
+                this.persist(event);
+                return;
+            case 'turn.completed':
+                this.flushAll();
+                this.persist(event);
+                return;
+            case 'usage.updated': {
+                if (this.lastUsage !== null &&
+                    this.lastUsage.total === event.usage.total &&
+                    this.lastUsage.costUsd === event.costUsd) {
+                    return;
+                }
+                this.lastUsage = { total: event.usage.total, costUsd: event.costUsd };
+                this.persist(event);
+                return;
+            }
+            case 'image':
+                // The v1 image pipeline already persists the screenshot as a file
+                // and re-emits a URL — persisting this raw-base64 twin would write
+                // the payload to the NDJSON file. Dropped until R3 links images to
+                // items by `itemId`.
+                return;
+            default:
+                // session.*, turn.started, plan.updated, permission.* — plain
+                // snapshot/lifecycle lines, persisted as they come. (`session.ended`
+                // and fatal `session.error` are normally minted by `sessionEnded()`;
+                // mapper-emitted ones — e.g. opencode's non-fatal session.error —
+                // pass through here.)
+                this.persist(event);
+                return;
+        }
+    }
+    /**
+     * Session close, called by the RunManager exactly once when the v1 session
+     * settles: flush everything, then persist v2 `session.error` (fatal) when
+     * the session failed, and `session.ended` — the v2 counterparts of v1's
+     * `done`/`error`, which the mappers deliberately left to the RunManager.
+     */
+    sessionEnded(reason, errorMessage) {
+        if (this.ended)
+            return;
+        this.flushAll();
+        if (errorMessage !== undefined) {
+            this.persist({ type: 'session.error', message: errorMessage, fatal: true });
+            this.persist({ type: 'session.ended', reason, message: errorMessage });
+        }
+        else {
+            this.persist({ type: 'session.ended', reason });
+        }
+        this.ended = true;
+    }
+    /** Flush every open coalescer now (turn end, session settle). */
+    flushAll() {
+        for (const itemId of [...this.buffers.keys()])
+            this.flushItem(itemId);
+    }
+    // ---- internals -----------------------------------------------------------
+    bufferDelta(event) {
+        let fields = this.buffers.get(event.itemId);
+        if (!fields) {
+            fields = new Map();
+            this.buffers.set(event.itemId, fields);
+        }
+        const pending = (fields.get(event.field) ?? '') + event.delta;
+        fields.set(event.field, pending);
+        if (pending.length >= MAX_DELTA_BUFFER) {
+            this.flushItem(event.itemId);
+            return;
+        }
+        if (!this.timers.has(event.itemId)) {
+            const timer = setTimeout(() => this.flushItem(event.itemId), this.flushMs);
+            timer.unref?.();
+            this.timers.set(event.itemId, timer);
+        }
+    }
+    /** Emit one merged `item.delta` per buffered field of the item, live only. */
+    flushItem(itemId) {
+        const timer = this.timers.get(itemId);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.timers.delete(itemId);
+        }
+        const fields = this.buffers.get(itemId);
+        if (!fields)
+            return;
+        this.buffers.delete(itemId);
+        for (const [field, delta] of fields) {
+            if (delta !== '')
+                this.emitLive({ type: 'item.delta', itemId, field, delta });
+        }
+    }
+    // UiEvent members carry no index signature; they are plain JSON objects at
+    // runtime, so widening them to the store's loose event shape is safe.
+    persist(event) {
+        try {
+            this.out.persist(event);
+        }
+        catch {
+            // best effort — v2 must never disturb the v1 stream
+        }
+    }
+    observe(event) {
+        try {
+            this.out.observe?.(event);
+        }
+        catch {
+            // best effort — an observer must never disturb the stream
+        }
+    }
+    emitLive(event) {
+        try {
+            this.out.emitLive(event);
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+/** The item minus its delta-streamed content field — what "meaningful
+ *  snapshot change" compares. Mappers build items with stable key order, so
+ *  JSON equality is a faithful (and cheap) identity; a false negative merely
+ *  persists one extra snapshot. */
+function itemShape(item) {
+    if (item.kind === 'tool') {
+        const { output: _output, ...rest } = item;
+        return JSON.stringify(rest);
+    }
+    // Hooks arrive once, complete, and never stream a field.
+    if (item.kind === 'hook')
+        return JSON.stringify(item);
+    const { text: _text, ...rest } = item;
+    return JSON.stringify(rest);
+}
+//# sourceMappingURL=ui-event-sink.js.map

package/dist/runs/ui-event-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-event-sink.js","sourceRoot":"","sources":["../../src/runs/ui-event-sink.ts"],"names":[],"mappings":"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"}

package/dist/runs/wait-capacity.d.ts

@@ -0,0 +1,8 @@
+import type { RunRecord } from './store.ts';
+export declare class WaitCapacityError extends Error {
+    constructor();
+}
+/** Replacing a known entry consumes no additional capacity. */
+export declare function assertWaitCapacity(run: Pick<RunRecord, 'waits'>, waitId?: string): void;
+/** Silent callers refuse only capacity errors; other failures still escape. */
+export declare function waitCapacityAvailable(run: Pick<RunRecord, 'waits'>, waitId?: string): boolean;

package/dist/runs/wait-capacity.js

@@ -0,0 +1,28 @@
+import { WAIT_LIMIT } from '../contract/index.js';
+export class WaitCapacityError extends Error {
+    constructor() {
+        super(`open wait limit reached (${WAIT_LIMIT})`);
+        this.name = 'WaitCapacityError';
+    }
+}
+/** Replacing a known entry consumes no additional capacity. */
+export function assertWaitCapacity(run, waitId) {
+    const waits = run.waits ?? [];
+    if (waitId !== undefined && waits.some(wait => wait.id === waitId))
+        return;
+    if (waits.filter(wait => wait.phase === 'open').length >= WAIT_LIMIT)
+        throw new WaitCapacityError();
+}
+/** Silent callers refuse only capacity errors; other failures still escape. */
+export function waitCapacityAvailable(run, waitId) {
+    try {
+        assertWaitCapacity(run, waitId);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof WaitCapacityError)
+            return false;
+        throw error;
+    }
+}
+//# sourceMappingURL=wait-capacity.js.map

package/dist/runs/wait-capacity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-capacity.js","sourceRoot":"","sources":["../../src/runs/wait-capacity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAGhE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C;QACE,KAAK,CAAC,4BAA4B,UAAU,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB,CAAC,GAA6B,EAAE,MAAe;IAC/E,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC;QAAE,OAAO;IAC3E,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,MAAM,IAAI,UAAU;QAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;AACtG,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,qBAAqB,CAAC,GAA6B,EAAE,MAAe;IAClF,IAAI,CAAC;QAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IACrD,OAAO,KAAK,EAAE,CAAC;QAAC,IAAI,KAAK,YAAY,iBAAiB;YAAE,OAAO,KAAK,CAAC;QAAC,MAAM,KAAK,CAAC;IAAC,CAAC;AACtF,CAAC"}

package/dist/runs/wait-phases.d.ts

@@ -0,0 +1,4 @@
+import type { Wait } from '../contract/index.js';
+import type { RunRecord } from './store.ts';
+/** Check the entry a store write puts in place; an undeclared write still lands. */
+export declare function checkWaitWrite(run: Pick<RunRecord, 'waits' | 'lastWaits'>, entry: Wait): void;

package/dist/runs/wait-phases.js

@@ -0,0 +1,11 @@
+import { WAIT_PHASES } from '../workflows/run-states.js';
+import { reportStoreViolation } from './run-exits.js';
+/** Check the entry a store write puts in place; an undeclared write still lands. */
+export function checkWaitWrite(run, entry) {
+    const prior = run.waits?.find(wait => wait.id === entry.id);
+    const from = prior?.phase ?? (run.lastWaits?.some(wait => wait.id === entry.id) ? 'settled' : 'new');
+    if (prior ? WAIT_PHASES[prior.phase].some(row => row.to === entry.phase) : from === 'new' && entry.phase === 'open')
+        return;
+    reportStoreViolation(`undeclared wait transition: ${entry.kind} wait ${entry.id} from ${from} to ${entry.phase} (declare it in workflows/run-states.ts WAIT_PHASES)`);
+}
+//# sourceMappingURL=wait-phases.js.map

package/dist/runs/wait-phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-phases.js","sourceRoot":"","sources":["../../src/runs/wait-phases.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGtD,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,GAA2C,EAAE,KAAW;IACrF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACrG,IAAI,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO;IAC5H,oBAAoB,CAAC,+BAA+B,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,EAAE,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,sDAAsD,CAAC,CAAC;AACxK,CAAC"}

package/dist/runs/wait-registration-write.d.ts

@@ -0,0 +1,5 @@
+import { type Wait, type WaitRegistrationReceipt } from '../contract/index.js';
+import { type AgentInput } from '../contract/index.js';
+import type { RunRecord } from './store.ts';
+export declare function registeredWaitRecord(run: RunRecord, wait: Wait, input?: AgentInput, registration?: WaitRegistrationReceipt): RunRecord;
+export declare function registeredReceiptRecord(run: RunRecord, receipt: WaitRegistrationReceipt): RunRecord;

package/dist/runs/wait-registration-write.js

@@ -0,0 +1,35 @@
+import { waitSchema, waitRegistrationReceiptSchema } from '../contract/index.js';
+import { agentInputSchema } from '../contract/index.js';
+import { assertWaitCapacity } from './wait-capacity.js';
+import { checkWaitWrite } from './wait-phases.js';
+function matchingReceipt(run, registration, waitId) {
+    const prior = run.waitRegistrations?.find(row => row.operationId === registration.operationId);
+    if (!prior)
+        return false;
+    if (prior.requestHash !== registration.requestHash || prior.wait.id !== waitId)
+        throw Object.assign(new Error('conflicting registration operation'), { code: 'operation_conflict' });
+    return true;
+}
+export function registeredWaitRecord(run, wait, input, registration) {
+    if (registration && matchingReceipt(run, registration, wait.id))
+        return run;
+    const entry = waitSchema.parse(wait);
+    if (entry.phase !== 'open' && entry.phase !== 'resolved')
+        throw new Error('a settled wait is committed through its delivery or cancellation');
+    const waits = run.waits ?? [];
+    const known = waits.some(row => row.id === entry.id);
+    if (entry.phase === 'open')
+        assertWaitCapacity(run, entry.id);
+    checkWaitWrite(run, entry);
+    const agentInput = input ? agentInputSchema.parse(input) : undefined;
+    const receiptRun = registration ? registeredReceiptRecord(run, registration) : run;
+    return { ...receiptRun, waits: known ? waits.map(row => row.id === entry.id ? entry : row) : [...waits, entry], lastWaitsError: undefined,
+        ...(agentInput ? { agentInputs: run.agentInputs?.some(row => row.id === agentInput.id) ? run.agentInputs : [...run.agentInputs ?? [], agentInput] } : {}) };
+}
+export function registeredReceiptRecord(run, receipt) {
+    const parsed = waitRegistrationReceiptSchema.parse(receipt);
+    if (matchingReceipt(run, parsed, parsed.wait.id))
+        return run;
+    return { ...run, waitRegistrations: [...run.waitRegistrations ?? [], parsed] };
+}
+//# sourceMappingURL=wait-registration-write.js.map

package/dist/runs/wait-registration-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-registration-write.js","sourceRoot":"","sources":["../../src/runs/wait-registration-write.ts"],"names":[],"mappings":"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"}