@zhin.js/agent 1.1.13 → 1.1.14

package/lib/workroom/remote-dispatch-outbox.js

@@ -0,0 +1,765 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link as nodeLink, mkdir as nodeMkdir, open as nodeOpen, readFile as nodeReadFile, readdir as nodeReaddir, unlink as nodeUnlink, } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { compareCanonicalWorkroomText, canonicalWorkroomJson as stableJson, deepFreezeWorkroomValue as deepFreeze, } from './canonical-value.js';
+import { assertWorkroomRemoteDispatchRetry, createWorkroomRemoteDispatchOutboxItem, } from './remote-dispatch.js';
+const nodeFileSystem = Object.freeze({
+    mkdir: async (path) => {
+        await nodeMkdir(path);
+    },
+    readdir: async (path) => await nodeReaddir(path),
+    readFile: async (path, encoding) => await nodeReadFile(path, encoding),
+    open: async (path, flags) => await nodeOpen(path, flags),
+    link: async (existingPath, newPath) => await nodeLink(existingPath, newPath),
+    unlink: async (path) => await nodeUnlink(path),
+});
+export class WorkroomRemoteDispatchOutboxSequenceConflictError extends Error {
+    dispatchId;
+    expectedSequence;
+    actualSequence;
+    constructor(dispatchId, expectedSequence, actualSequence) {
+        super(`Workroom Remote Dispatch Outbox ${dispatchId} sequence conflict: `
+            + `expected ${expectedSequence}, actual ${actualSequence}`);
+        this.dispatchId = dispatchId;
+        this.expectedSequence = expectedSequence;
+        this.actualSequence = actualSequence;
+        this.name = 'WorkroomRemoteDispatchOutboxSequenceConflictError';
+    }
+}
+export class MemoryWorkroomRemoteDispatchOutboxRepository {
+    #events = new Map();
+    async read(dispatchId) {
+        return project(this.#events.get(identifier(dispatchId, 'dispatchId')) ?? []);
+    }
+    async listRunnable(now) {
+        const trustedNow = timestamp(now, 'now');
+        return Object.freeze([...this.#events.values()]
+            .map(events => project(events))
+            .filter((entry) => entry !== undefined && isRunnable(entry, trustedNow))
+            .sort((left, right) => compareCanonicalWorkroomText(left.dispatchId, right.dispatchId)));
+    }
+    async listGovernanceBlocked(input) {
+        return Object.freeze([...this.#events.values()]
+            .map(events => project(events))
+            .filter((entry) => entry?.status === 'blocked'
+            && entry.item.envelope.projectId === input.projectId
+            && entry.item.envelope.runId === input.runId
+            && entry.item.envelope.taskKey === input.taskKey
+            && entry.item.envelope.taskRevision === input.taskRevision)
+            .sort(compareBlockedDispatch));
+    }
+    async append(dispatchId, expectedSequence, drafts) {
+        const id = identifier(dispatchId, 'dispatchId');
+        const current = this.#events.get(id) ?? [];
+        const appended = materializeAppend(id, current, expectedSequence, drafts);
+        if (appended.length > 0 && appended.some(event => event.sequence >= current.length)) {
+            this.#events.set(id, Object.freeze([...current, ...appended]));
+        }
+        return appended;
+    }
+    async enqueue(item, expectedSequence, enqueuedAt) {
+        return enqueue(this, item, expectedSequence, enqueuedAt);
+    }
+    async claim(input) {
+        return claim(this, input);
+    }
+    async recordTransportObservation(input) {
+        return recordTransportObservation(this, input);
+    }
+    async recordGovernanceBlock(input) {
+        return recordGovernanceBlock(this, input);
+    }
+    async recover(input) {
+        return recover(this, input);
+    }
+}
+/**
+ * Durable adapter. Each append is an immutable segment and the first sequence
+ * path is claimed with a hard link, making expectedSequence a filesystem CAS.
+ */
+export class FileWorkroomRemoteDispatchOutboxRepository {
+    directory;
+    fileSystem;
+    constructor(directory, fileSystem = nodeFileSystem) {
+        this.directory = directory;
+        this.fileSystem = fileSystem;
+    }
+    async read(dispatchId) {
+        return project(await this.#readEvents(identifier(dispatchId, 'dispatchId')));
+    }
+    async listRunnable(now) {
+        const trustedNow = timestamp(now, 'now');
+        return Object.freeze((await this.#readAllProjections())
+            .filter(entry => isRunnable(entry, trustedNow)));
+    }
+    async listGovernanceBlocked(input) {
+        const entries = await this.#readAllProjections();
+        return Object.freeze(entries.filter(entry => entry.status === 'blocked'
+            && entry.item.envelope.projectId === input.projectId
+            && entry.item.envelope.runId === input.runId
+            && entry.item.envelope.taskKey === input.taskKey
+            && entry.item.envelope.taskRevision === input.taskRevision)
+            .sort(compareBlockedDispatch));
+    }
+    async #readAllProjections() {
+        let names;
+        try {
+            names = (await this.fileSystem.readdir(this.directory)).filter(name => name.endsWith('.json')).sort();
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return [];
+            throw error;
+        }
+        const byDispatch = new Map();
+        for (const name of names) {
+            const value = JSON.parse(await this.fileSystem.readFile(join(this.directory, name), 'utf8'));
+            if (!Array.isArray(value))
+                throw new Error('Remote Dispatch Outbox segment must be an event array');
+            for (const event of value.map(parseEvent)) {
+                if (!name.startsWith(`${digest(event.dispatchId)}.`)) {
+                    throw new Error('Remote Dispatch Outbox segment identity does not match its filename');
+                }
+                const stream = byDispatch.get(event.dispatchId) ?? [];
+                stream.push(event);
+                byDispatch.set(event.dispatchId, stream);
+            }
+        }
+        return [...byDispatch.entries()]
+            .sort(([left], [right]) => compareCanonicalWorkroomText(left, right))
+            .map(([, events]) => project(events.sort((left, right) => left.sequence - right.sequence)))
+            .filter((entry) => entry !== undefined);
+    }
+    async append(dispatchId, expectedSequence, drafts) {
+        const id = identifier(dispatchId, 'dispatchId');
+        const current = await this.#readEvents(id);
+        const appended = materializeAppend(id, current, expectedSequence, drafts);
+        if (appended.length === 0 || appended.every(event => event.sequence < current.length)) {
+            if (current.length > 0)
+                await this.#syncDirectory();
+            return appended;
+        }
+        await this.#ensureDurableOutboxDirectory();
+        const segment = this.#segmentPath(id, appended[0].sequence);
+        const temporary = `${segment}.${randomUUID()}.tmp`;
+        let temporaryExists = false;
+        try {
+            const handle = await this.fileSystem.open(temporary, 'wx');
+            temporaryExists = true;
+            try {
+                await handle.writeFile(JSON.stringify(appended), 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await this.fileSystem.link(temporary, segment);
+            await this.fileSystem.unlink(temporary);
+            temporaryExists = false;
+            await this.#syncDirectory();
+        }
+        catch (error) {
+            if (temporaryExists) {
+                await this.fileSystem.unlink(temporary).catch(cleanupError => {
+                    if (!isMissingFile(cleanupError))
+                        throw cleanupError;
+                });
+                temporaryExists = false;
+            }
+            if (isAlreadyExists(error)) {
+                const winner = await this.#readEvents(id);
+                const replay = materializeAppend(id, winner, expectedSequence, drafts);
+                await this.#syncDirectory();
+                if (replay.length > 0 && replay.every(event => event.sequence < winner.length)) {
+                    return replay;
+                }
+                throw new WorkroomRemoteDispatchOutboxSequenceConflictError(id, expectedSequence, winner.at(-1)?.sequence ?? -1);
+            }
+            throw error;
+        }
+        finally {
+            if (temporaryExists) {
+                await this.fileSystem.unlink(temporary).catch(error => {
+                    if (!isMissingFile(error))
+                        throw error;
+                });
+            }
+        }
+        return appended;
+    }
+    async enqueue(item, expectedSequence, enqueuedAt) {
+        return enqueue(this, item, expectedSequence, enqueuedAt);
+    }
+    async claim(input) {
+        return claim(this, input);
+    }
+    async recordTransportObservation(input) {
+        return recordTransportObservation(this, input);
+    }
+    async recordGovernanceBlock(input) {
+        return recordGovernanceBlock(this, input);
+    }
+    async recover(input) {
+        return recover(this, input);
+    }
+    async #readEvents(dispatchId) {
+        const prefix = `${digest(dispatchId)}.`;
+        let names;
+        try {
+            names = (await this.fileSystem.readdir(this.directory))
+                .filter(name => name.startsWith(prefix) && name.endsWith('.json'))
+                .sort();
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return [];
+            throw error;
+        }
+        const events = (await Promise.all(names.map(async (name) => {
+            const value = JSON.parse(await this.fileSystem.readFile(join(this.directory, name), 'utf8'));
+            if (!Array.isArray(value))
+                throw new Error('Remote Dispatch Outbox segment must be an event array');
+            return value.map(parseEvent);
+        }))).flat().sort((left, right) => left.sequence - right.sequence);
+        if (events.some(event => event.dispatchId !== dispatchId)) {
+            throw new Error('Remote Dispatch Outbox dispatch identity collision');
+        }
+        assertContiguous(events);
+        return Object.freeze(events);
+    }
+    #segmentPath(dispatchId, firstSequence) {
+        return join(this.directory, `${digest(dispatchId)}.${String(firstSequence).padStart(16, '0')}.json`);
+    }
+    async #syncDirectory() {
+        await this.#syncDirectoryPath(this.directory);
+    }
+    async #ensureDurableOutboxDirectory() {
+        try {
+            await this.fileSystem.mkdir(this.directory);
+        }
+        catch (error) {
+            if (!isAlreadyExists(error)) {
+                if (isMissingFile(error)) {
+                    throw new Error(`Remote Dispatch Outbox requires a pre-existing durable parent directory: `
+                        + dirname(this.directory), { cause: error });
+                }
+                throw error;
+            }
+        }
+        // Repeating this for an already-live empty leaf is intentional: a prior
+        // parent fsync may have failed, so existence alone is not durability proof.
+        await this.#syncDirectoryPath(dirname(this.directory));
+    }
+    async #syncDirectoryPath(path) {
+        const handle = await this.fileSystem.open(path, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+async function enqueue(repository, item, expectedSequence, enqueuedAt) {
+    const normalized = normalizeItem(item);
+    const [event] = await repository.append(normalized.dispatchId, expectedSequence, [{
+            eventId: `${normalized.dispatchId}:enqueued`,
+            occurredAt: timestamp(enqueuedAt, 'enqueuedAt'),
+            type: 'dispatch.enqueued',
+            payload: { item: normalized },
+        }]);
+    return event;
+}
+async function claim(repository, input) {
+    const dispatchId = identifier(input.dispatchId, 'dispatchId');
+    const state = await repository.read(dispatchId);
+    if (!state)
+        throw new Error(`Remote Dispatch Outbox item does not exist: ${dispatchId}`);
+    const replayingInitialClaim = state.status === 'leased'
+        && state.attemptCount === 1
+        && state.observations.length === 0
+        && state.lease?.ownerId === input.ownerId
+        && state.lease.leaseId === input.leaseId
+        && state.lease.leaseFence === input.leaseFence
+        && state.lease.claimedAt === input.now
+        && state.lease.expiresAt === input.leaseExpiresAt;
+    if ((state.status !== 'pending' || state.lease) && !replayingInitialClaim) {
+        throw new Error('Remote Dispatch Outbox item is not available for an initial claim');
+    }
+    const now = timestamp(input.now, 'now');
+    const lease = normalizeLease({
+        ownerId: input.ownerId,
+        leaseId: input.leaseId,
+        leaseFence: input.leaseFence,
+        claimedAt: now,
+        expiresAt: input.leaseExpiresAt,
+    });
+    if (lease.leaseFence !== 1) {
+        throw new Error('Initial Remote Dispatch Outbox leaseFence must be 1');
+    }
+    if (lease.expiresAt <= now) {
+        throw new Error('Remote Dispatch Outbox lease must expire after now');
+    }
+    const [event] = await repository.append(dispatchId, input.expectedSequence, [{
+            eventId: `${dispatchId}:claimed:${lease.leaseFence}:${encodeURIComponent(lease.leaseId)}`,
+            occurredAt: now,
+            type: 'dispatch.claimed',
+            payload: { lease },
+        }]);
+    return event;
+}
+async function recordTransportObservation(repository, input) {
+    const dispatchId = identifier(input.dispatchId, 'dispatchId');
+    const observationId = identifier(input.observationId, 'observationId');
+    const [event] = await repository.append(dispatchId, input.expectedSequence, [{
+            eventId: `${dispatchId}:transport-observed:${encodeURIComponent(observationId)}`,
+            occurredAt: timestamp(input.now, 'now'),
+            type: 'dispatch.transport_observed',
+            payload: {
+                leaseId: identifier(input.leaseId, 'leaseId'),
+                leaseFence: positiveSequence(input.leaseFence, 'leaseFence'),
+                observationId,
+                observation: normalizeTransportObservation(input.observation),
+            },
+        }]);
+    return event;
+}
+async function recordGovernanceBlock(repository, input) {
+    const dispatchId = identifier(input.dispatchId, 'dispatchId');
+    const reason = identifier(input.reason, 'governance reason');
+    const manifestDigest = sha(input.manifestDigest, 'manifestDigest');
+    const [event] = await repository.append(dispatchId, input.expectedSequence, [{
+            eventId: `${dispatchId}:governance-blocked:${input.attempt}:${input.assignmentFence}`,
+            occurredAt: timestamp(input.now, 'now'),
+            type: 'dispatch.governance_blocked',
+            payload: {
+                reason,
+                manifestDigest,
+                attempt: positiveSequence(input.attempt, 'attempt'),
+                assignmentFence: positiveSequence(input.assignmentFence, 'assignmentFence'),
+            },
+        }]);
+    return event;
+}
+async function recover(repository, input) {
+    const dispatchId = identifier(input.dispatchId, 'dispatchId');
+    const state = await repository.read(dispatchId);
+    if (!state)
+        throw new Error(`Remote Dispatch Outbox item does not exist: ${dispatchId}`);
+    const now = timestamp(input.now, 'now');
+    let cause;
+    if (state.status === 'reconcile_required')
+        cause = 'outcome_unknown';
+    else if (state.status === 'retryable')
+        cause = 'transport_failed';
+    else if (state.status === 'leased' && state.lease && now >= state.lease.expiresAt) {
+        cause = 'lease_expired';
+    }
+    else if (state.status === 'leased'
+        && state.lease?.leaseId === input.leaseId
+        && state.lease.leaseFence === input.leaseFence
+        && state.lastRecoveryCause) {
+        cause = state.lastRecoveryCause;
+    }
+    else {
+        throw new Error('Remote Dispatch Outbox item is not eligible for recovery');
+    }
+    const lease = normalizeLease({
+        ownerId: input.ownerId,
+        leaseId: input.leaseId,
+        leaseFence: input.leaseFence,
+        claimedAt: now,
+        expiresAt: input.leaseExpiresAt,
+    });
+    if (lease.expiresAt <= now)
+        throw new Error('Remote Dispatch Outbox lease must expire after now');
+    const [event] = await repository.append(dispatchId, input.expectedSequence, [{
+            eventId: `${dispatchId}:recovered:${lease.leaseFence}:${encodeURIComponent(lease.leaseId)}`,
+            occurredAt: now,
+            type: 'dispatch.recovered',
+            payload: { lease, cause },
+        }]);
+    return event;
+}
+function materializeAppend(dispatchId, current, expectedSequence, drafts) {
+    sequence(expectedSequence, 'expectedSequence');
+    const normalized = deduplicateDrafts(drafts.map(normalizeDraft));
+    const byEventId = new Map(current.map(event => [event.eventId, event]));
+    const replayed = [];
+    for (const draft of normalized) {
+        const existing = byEventId.get(draft.eventId);
+        if (!existing)
+            continue;
+        if (stableJson({
+            occurredAt: existing.occurredAt,
+            type: existing.type,
+            payload: existing.payload,
+        }) !== stableJson({
+            occurredAt: draft.occurredAt,
+            type: draft.type,
+            payload: draft.payload,
+        })) {
+            throw new Error(`Remote Dispatch Outbox eventId payload conflict: ${draft.eventId}`);
+        }
+        replayed.push(existing);
+    }
+    if (replayed.length > 0) {
+        if (replayed.length !== normalized.length) {
+            throw new Error('Remote Dispatch Outbox append cannot mix replayed and new events');
+        }
+        return Object.freeze(replayed);
+    }
+    const actualSequence = current.at(-1)?.sequence ?? -1;
+    if (actualSequence !== expectedSequence) {
+        throw new WorkroomRemoteDispatchOutboxSequenceConflictError(dispatchId, expectedSequence, actualSequence);
+    }
+    const appended = Object.freeze(normalized.map((draft, index) => deepFreeze({
+        ...draft,
+        version: 1,
+        dispatchId,
+        sequence: expectedSequence + index + 1,
+    })));
+    project(Object.freeze([...current, ...appended]));
+    return appended;
+}
+function normalizeDraft(draft) {
+    const eventId = identifier(draft.eventId, 'eventId');
+    const occurredAt = timestamp(draft.occurredAt, 'occurredAt');
+    if (draft.type === 'dispatch.enqueued') {
+        return deepFreeze({
+            eventId,
+            occurredAt,
+            type: draft.type,
+            payload: { item: normalizeItem(draft.payload?.item) },
+        });
+    }
+    if (draft.type === 'dispatch.claimed') {
+        return deepFreeze({
+            eventId,
+            occurredAt,
+            type: draft.type,
+            payload: { lease: normalizeLease(draft.payload?.lease) },
+        });
+    }
+    if (draft.type === 'dispatch.transport_observed') {
+        return deepFreeze({
+            eventId,
+            occurredAt,
+            type: draft.type,
+            payload: {
+                leaseId: identifier(draft.payload?.leaseId, 'leaseId'),
+                leaseFence: positiveSequence(draft.payload?.leaseFence, 'leaseFence'),
+                observationId: identifier(draft.payload?.observationId, 'observationId'),
+                observation: normalizeTransportObservation(draft.payload?.observation),
+            },
+        });
+    }
+    if (draft.type === 'dispatch.governance_blocked') {
+        return deepFreeze({
+            eventId,
+            occurredAt,
+            type: draft.type,
+            payload: {
+                reason: identifier(draft.payload?.reason, 'governance reason'),
+                manifestDigest: sha(draft.payload?.manifestDigest, 'manifestDigest'),
+                attempt: positiveSequence(draft.payload?.attempt, 'attempt'),
+                assignmentFence: positiveSequence(draft.payload?.assignmentFence, 'assignmentFence'),
+            },
+        });
+    }
+    if (draft.type === 'dispatch.recovered') {
+        return deepFreeze({
+            eventId,
+            occurredAt,
+            type: draft.type,
+            payload: {
+                lease: normalizeLease(draft.payload?.lease),
+                cause: recoveryCause(draft.payload?.cause),
+            },
+        });
+    }
+    throw new Error('Invalid Remote Dispatch Outbox event type');
+}
+function parseEvent(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid Remote Dispatch Outbox event');
+    }
+    const event = value;
+    const draft = normalizeDraft(event);
+    return deepFreeze({
+        ...draft,
+        version: event.version === 1 ? 1 : fail('Invalid Remote Dispatch Outbox event version'),
+        dispatchId: identifier(event.dispatchId, 'dispatchId'),
+        sequence: sequence(event.sequence, 'sequence'),
+    });
+}
+function project(events) {
+    if (events.length === 0)
+        return undefined;
+    assertContiguous(events);
+    const first = events[0];
+    if (first.type !== 'dispatch.enqueued' || first.sequence !== 0) {
+        throw new Error('Remote Dispatch Outbox must begin with dispatch.enqueued');
+    }
+    if (first.dispatchId !== first.payload.item.dispatchId) {
+        throw new Error('Remote Dispatch Outbox item identity does not match stream identity');
+    }
+    assertDeterministicEventId(first);
+    let status = 'pending';
+    let lease;
+    let lastLeaseFence;
+    let attemptCount = 0;
+    const observations = [];
+    const observationIds = new Set();
+    let lastRecoveryCause;
+    let governanceBlock;
+    for (const event of events.slice(1)) {
+        assertDeterministicEventId(event);
+        if (event.type === 'dispatch.claimed') {
+            if (status !== 'pending') {
+                throw new Error(`Invalid Remote Dispatch Outbox transition: ${event.type}`);
+            }
+            if (event.payload.lease.leaseFence !== 1
+                || event.payload.lease.claimedAt !== event.occurredAt) {
+                throw new Error('Invalid initial Remote Dispatch Outbox lease/fence');
+            }
+            lease = event.payload.lease;
+            lastLeaseFence = lease.leaseFence;
+            status = 'leased';
+            attemptCount += 1;
+            continue;
+        }
+        if (event.type === 'dispatch.transport_observed') {
+            if (status !== 'leased' || !lease
+                || event.payload.leaseId !== lease.leaseId
+                || event.payload.leaseFence !== lease.leaseFence) {
+                throw new Error('Remote Dispatch Outbox observation does not match the active lease/fence');
+            }
+            if (event.occurredAt >= lease.expiresAt) {
+                throw new Error('Remote Dispatch Outbox observation arrived after lease expiry');
+            }
+            if (observationIds.has(event.payload.observationId)) {
+                throw new Error(`Remote Dispatch Outbox observationId conflict: ${event.payload.observationId}`);
+            }
+            observationIds.add(event.payload.observationId);
+            observations.push(deepFreeze({
+                observationId: event.payload.observationId,
+                observedAt: event.occurredAt,
+                leaseId: event.payload.leaseId,
+                leaseFence: event.payload.leaseFence,
+                ...event.payload.observation,
+            }));
+            status = event.payload.observation.outcome === 'delivered'
+                ? 'delivered'
+                : event.payload.observation.outcome === 'outcome_unknown'
+                    ? 'reconcile_required'
+                    : 'retryable';
+            lease = undefined;
+            continue;
+        }
+        if (event.type === 'dispatch.governance_blocked') {
+            if (status !== 'pending' && status !== 'retryable') {
+                throw new Error('Invalid Remote Dispatch governance block transition');
+            }
+            if (event.payload.attempt !== first.payload.item.envelope.attempt
+                || event.payload.assignmentFence !== first.payload.item.envelope.fence
+                || event.payload.manifestDigest
+                    !== first.payload.item.envelope.disclosureManifest.manifest.digest) {
+                throw new Error('Remote Dispatch governance block escaped exact Assignment/Manifest authority');
+            }
+            status = 'blocked';
+            governanceBlock = deepFreeze({ ...event.payload, blockedAt: event.occurredAt });
+            lease = undefined;
+            continue;
+        }
+        if (event.type === 'dispatch.recovered') {
+            const expectedCause = status === 'reconcile_required'
+                ? 'outcome_unknown'
+                : status === 'retryable'
+                    ? 'transport_failed'
+                    : status === 'leased' && lease && event.occurredAt >= lease.expiresAt
+                        ? 'lease_expired'
+                        : undefined;
+            if (!expectedCause || event.payload.cause !== expectedCause) {
+                throw new Error('Invalid Remote Dispatch Outbox recovery transition');
+            }
+            if (lastLeaseFence === undefined || event.payload.lease.leaseFence !== lastLeaseFence + 1) {
+                throw new Error('Remote Dispatch Outbox recovery must increase the lease fence by one');
+            }
+            if (event.payload.lease.claimedAt !== event.occurredAt) {
+                throw new Error('Remote Dispatch Outbox recovery lease does not match Kernel clock input');
+            }
+            lease = event.payload.lease;
+            lastLeaseFence = lease.leaseFence;
+            lastRecoveryCause = event.payload.cause;
+            status = 'leased';
+            attemptCount += 1;
+            continue;
+        }
+        throw new Error(`Invalid Remote Dispatch Outbox transition: ${event.type}`);
+    }
+    return deepFreeze({
+        version: 1,
+        dispatchId: first.dispatchId,
+        sequence: events.at(-1).sequence,
+        status,
+        item: first.payload.item,
+        attemptCount,
+        observations: Object.freeze(observations),
+        ...(lease ? { lease } : {}),
+        ...(lastLeaseFence === undefined ? {} : { lastLeaseFence }),
+        ...(lastRecoveryCause === undefined ? {} : { lastRecoveryCause }),
+        ...(governanceBlock === undefined ? {} : { governanceBlock }),
+    });
+}
+function isRunnable(projection, now) {
+    return projection.status === 'pending'
+        || projection.status === 'retryable'
+        || (projection.status === 'leased'
+            && projection.lease !== undefined
+            && now >= projection.lease.expiresAt);
+}
+function compareBlockedDispatch(left, right) {
+    return right.item.envelope.attempt - left.item.envelope.attempt
+        || right.item.envelope.fence - left.item.envelope.fence
+        || compareCanonicalWorkroomText(left.dispatchId, right.dispatchId);
+}
+function assertDeterministicEventId(event) {
+    const expected = event.type === 'dispatch.enqueued'
+        ? `${event.dispatchId}:enqueued`
+        : event.type === 'dispatch.claimed'
+            ? `${event.dispatchId}:claimed:${event.payload.lease.leaseFence}:`
+                + encodeURIComponent(event.payload.lease.leaseId)
+            : event.type === 'dispatch.transport_observed'
+                ? `${event.dispatchId}:transport-observed:`
+                    + encodeURIComponent(event.payload.observationId)
+                : event.type === 'dispatch.governance_blocked'
+                    ? `${event.dispatchId}:governance-blocked:${event.payload.attempt}:`
+                        + event.payload.assignmentFence
+                    : `${event.dispatchId}:recovered:${event.payload.lease.leaseFence}:`
+                        + encodeURIComponent(event.payload.lease.leaseId);
+    if (event.eventId !== expected) {
+        throw new Error(`Remote Dispatch Outbox event identity is not deterministic: ${event.eventId}`);
+    }
+}
+function normalizeLease(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid Remote Dispatch Outbox lease');
+    }
+    const lease = value;
+    const claimedAt = timestamp(lease.claimedAt, 'lease.claimedAt');
+    const expiresAt = timestamp(lease.expiresAt, 'lease.expiresAt');
+    if (expiresAt <= claimedAt)
+        throw new Error('Remote Dispatch Outbox lease expiry is invalid');
+    return deepFreeze({
+        ownerId: identifier(lease.ownerId, 'lease.ownerId'),
+        leaseId: identifier(lease.leaseId, 'lease.leaseId'),
+        leaseFence: positiveSequence(lease.leaseFence, 'lease.leaseFence'),
+        claimedAt,
+        expiresAt,
+    });
+}
+function normalizeTransportObservation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid Remote Dispatch Outbox transport observation');
+    }
+    const observation = value;
+    if (!['delivered', 'outcome_unknown', 'failed'].includes(observation.outcome ?? '')) {
+        throw new Error('Invalid Remote Dispatch Outbox transport outcome');
+    }
+    return deepFreeze({
+        outcome: observation.outcome,
+        receiptId: identifier(observation.receiptId, 'observation.receiptId'),
+        ...optionalIdentifier(observation.remoteTaskId, 'observation.remoteTaskId'),
+        ...optionalIdentifier(observation.remoteContextId, 'observation.remoteContextId'),
+        ...optionalIdentifier(observation.reason, 'observation.reason'),
+    });
+}
+function recoveryCause(value) {
+    if (!['outcome_unknown', 'transport_failed', 'lease_expired'].includes(String(value))) {
+        throw new Error('Invalid Remote Dispatch Outbox recovery cause');
+    }
+    return value;
+}
+function optionalIdentifier(value, name) {
+    if (value === undefined)
+        return {};
+    const key = name.slice(name.lastIndexOf('.') + 1);
+    return { [key]: identifier(value, name) };
+}
+function normalizeItem(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid Remote Dispatch Outbox item');
+    }
+    const item = value;
+    const { version: _version, dispatchId: _dispatchId, messageId: _messageId, ...input } = item.envelope;
+    const canonical = createWorkroomRemoteDispatchOutboxItem(input);
+    assertWorkroomRemoteDispatchRetry(canonical, item);
+    if (item.version !== 1
+        || item.dispatchId !== item.envelope.dispatchId
+        || item.messageId !== item.envelope.messageId) {
+        throw new Error('Remote Dispatch Outbox item identity does not match its envelope');
+    }
+    return canonical;
+}
+function deduplicateDrafts(drafts) {
+    const result = [];
+    const byId = new Map();
+    for (const draft of drafts) {
+        const existing = byId.get(draft.eventId);
+        if (existing) {
+            if (stableJson(existing) !== stableJson(draft)) {
+                throw new Error(`Remote Dispatch Outbox eventId payload conflict: ${draft.eventId}`);
+            }
+            continue;
+        }
+        byId.set(draft.eventId, draft);
+        result.push(draft);
+    }
+    return Object.freeze(result);
+}
+function assertContiguous(events) {
+    events.forEach((event, index) => {
+        if (event.sequence !== index)
+            throw new Error('Remote Dispatch Outbox sequence is not contiguous');
+    });
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function identifier(value, name) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+function sha(value, name) {
+    const normalized = identifier(value, name);
+    if (!/^sha256:[a-f0-9]{64}$/u.test(normalized))
+        throw new Error(`Invalid ${name}`);
+    return normalized;
+}
+function timestamp(value, name) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+function sequence(value, name) {
+    if (!Number.isSafeInteger(value) || value < -1)
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+function positiveSequence(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+function fail(message) {
+    throw new Error(message);
+}
+function isMissingFile(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+function isAlreadyExists(error) {
+    return error instanceof Error && 'code' in error && error.code === 'EEXIST';
+}
+//# sourceMappingURL=remote-dispatch-outbox.js.map