@animalabs/agent-framework 0.19.0 → 0.21.0

package/dist/src/mcpl/push-coalescer.js

@@ -0,0 +1,709 @@
+export const PUSH_COALESCING_SUPPORT = {
+    pushEvents: true, channelsIncoming: true, deferred: true, channelScopedPush: true,
+    retryWindowMs: 3_600_000,
+};
+export const COALESCE_OUTCOMES = ['first', 'replaced', 'appended', 'retracted', 'noted', 'consumed'];
+class CancelledRender extends Error {
+}
+export class CoalesceError extends Error {
+    field;
+    code;
+    constructor(field, message, code = -32602) {
+        super(message);
+        this.field = field;
+        this.code = code;
+        this.name = 'CoalesceError';
+    }
+}
+export function coalescingSubjectKey(serverId, binding, scope, key) {
+    return JSON.stringify([serverId, binding, scope.kind, scope.id, key]);
+}
+export function coalescingReceiptKey(serverId, binding, eventId) {
+    return JSON.stringify([serverId, binding, eventId]);
+}
+/** Merge identity fields, never letting an absent field erase a known one (§3.1). */
+function mergeIdentity(prior, next) {
+    const out = { ...prior };
+    for (const [k, v] of Object.entries(next ?? {}))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Validate wire content before it is stored, rendered or converted. */
+export function validateCoalescedContent(content, maxBytes = 1024 * 1024) {
+    if (!Array.isArray(content))
+        throw new CoalesceError('payload.content', 'content must be an array');
+    for (const b of content) {
+        if (!b || typeof b !== 'object' || Array.isArray(b))
+            throw new CoalesceError('payload.content', 'invalid content block');
+        if (b.type === 'text' && typeof b.text === 'string')
+            continue;
+        if (b.type === 'resource' && typeof b.uri === 'string')
+            continue;
+        if ((b.type === 'image' || b.type === 'audio')
+            && (typeof b.uri === 'string' || (typeof b.data === 'string' && typeof b.mimeType === 'string')))
+            continue;
+        throw new CoalesceError('payload.content', 'invalid content block');
+    }
+    if (Buffer.byteLength(JSON.stringify(content)) > maxBytes)
+        throw new CoalesceError('payload.content', 'content exceeds host byte limit');
+}
+/** Validate the `coalesce` member of either lane (§13). */
+export function validateCoalesceMember(c, lane, maxDataBytes = 4096) {
+    if (!c || typeof c !== 'object' || Array.isArray(c))
+        throw new CoalesceError('coalesce', 'coalesce must be an object');
+    const m = c;
+    if (typeof m.key !== 'string' || !Buffer.byteLength(m.key) || Buffer.byteLength(m.key) > 256) {
+        throw new CoalesceError('coalesce.key', 'key must be 1..256 UTF-8 bytes');
+    }
+    for (const field of ['deferred', 'retract', 'initial']) {
+        if (m[field] !== undefined && typeof m[field] !== 'boolean')
+            throw new CoalesceError(`coalesce.${field}`, 'expected boolean');
+    }
+    if (m.channelId !== undefined && (typeof m.channelId !== 'string' || !m.channelId)) {
+        throw new CoalesceError('coalesce.channelId', 'channelId must be a non-empty string');
+    }
+    if (lane === 'channel' && ('channelId' in m || 'deferred' in m)) {
+        throw new CoalesceError('coalesce', 'channel messages cannot select scope or deferred mode');
+    }
+    if (m.deferred && m.retract)
+        throw new CoalesceError('coalesce', 'deferred and retract are exclusive');
+    if (m.initial && m.retract)
+        throw new CoalesceError('coalesce', 'initial and retract are exclusive');
+    if (m.data !== undefined && !m.deferred)
+        throw new CoalesceError('coalesce.data', 'data requires deferred');
+    if (m.data !== undefined && Buffer.byteLength(JSON.stringify(m.data)) > maxDataBytes) {
+        throw new CoalesceError('coalesce.data', `data exceeds ${maxDataBytes} bytes`);
+    }
+}
+export class PushCoalescer {
+    host;
+    options;
+    subjects = new Map();
+    /** `committed`: the durability barrier succeeded after this receipt was
+     *  written. An uncommitted receipt deduplicates effects but is not an
+     *  acknowledgement until a commit succeeds. */
+    receipts = new Map();
+    retryWindowMs;
+    maxSubjects;
+    maxNotices;
+    /** Outstanding push/render RPCs per server, including cancelled ones (§10.7). */
+    rendersInFlight = new Map();
+    /**
+     * The ONE critical section. Every state transition — an admission, the
+     * freezing of a batch for rendering, the settlement of a render's result —
+     * runs under it, awaits included (fork spawn, durability commit, delivery).
+     * Only the push/render RPC itself runs outside, so it stays cancellable.
+     * An admission therefore never observes a half-done assembly transition,
+     * and an assembly never acts on a batch an admission moved on from.
+     */
+    serial = Promise.resolve();
+    /** Liveness after a failed freeze: a bounded, backed-off re-wake per
+     *  subject. `attempt` outlives the armed timer: it counts consecutive
+     *  failures and resets only on success or disposal of the pending work. */
+    recovery = new Map();
+    suspended = false;
+    constructor(host, options = {}) {
+        this.host = host;
+        this.options = options;
+        this.retryWindowMs = options.retryWindowMs ?? PUSH_COALESCING_SUPPORT.retryWindowMs;
+        this.maxSubjects = options.maxSubjects ?? 4_096;
+        this.maxNotices = options.maxNotices ?? 64;
+    }
+    now() { return this.host.now?.() ?? Date.now(); }
+    locked(fn) {
+        const run = this.serial.then(fn, fn);
+        this.serial = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    // ---------------------------------------------------------------------------
+    // Observation
+    // ---------------------------------------------------------------------------
+    /** The unread occupant's or batch's placement/identity, for routing continuity. */
+    identity(subject) {
+        return this.subjects.get(subject)?.identity;
+    }
+    pendingBatches() {
+        let n = 0;
+        for (const s of this.subjects.values())
+            if (s.batch)
+                n++;
+        return n;
+    }
+    /** §10.7: a server handling push/render must not issue inference/request —
+     *  including a render whose batch was cancelled while the RPC is outstanding. */
+    isRendering(serverId) {
+        return (this.rendersInFlight.get(serverId) ?? 0) > 0;
+    }
+    receipt(serverId, binding, eventId) {
+        const entry = this.receiptEntry(coalescingReceiptKey(serverId, binding, eventId));
+        return entry && structuredClone(entry.result);
+    }
+    receiptEntry(key) {
+        const entry = this.receipts.get(key);
+        if (!entry)
+            return undefined;
+        if (this.now() - entry.at > this.retryWindowMs) {
+            this.receipts.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    /** Acknowledge a receipt: durable first. A receipt whose commit failed is
+     *  committed now (no effects are repeated); if that fails again, so does
+     *  the acknowledgement, and the producer retries once more. */
+    async acknowledge(key, entry, subject, eventId) {
+        if (!entry.committed) {
+            try {
+                await this.host.commit?.();
+                entry.committed = true;
+            }
+            catch (error) {
+                this.host.audit({ kind: 'persist-failed', subject, eventId, error: String(error) });
+                throw new CoalesceError('eventId', 'host could not make the acceptance durable; retry', -32000);
+            }
+        }
+        return structuredClone(entry.result);
+    }
+    // ---------------------------------------------------------------------------
+    // Admission
+    // ---------------------------------------------------------------------------
+    /**
+     * Admit an occurrence that has already passed the lane's ordinary checks and
+     * the coalesce-member validation. Returns the wire result, performing the
+     * host effects (replace / remove / deliver) synchronously so a create, edit
+     * and delete cannot overtake one another.
+     */
+    accept(occurrence) {
+        return this.locked(() => this.admit(occurrence));
+    }
+    async admit(occurrence) {
+        if (this.suspended)
+            throw new CoalesceError('serverId', 'host is stopping', -32000);
+        const subject = coalescingSubjectKey(occurrence.serverId, occurrence.binding, occurrence.scope, occurrence.key);
+        const duplicate = this.receiptEntry(coalescingReceiptKey(occurrence.serverId, occurrence.binding, occurrence.eventId));
+        if (duplicate) {
+            // A producer retrying acknowledged work is also a chance to notice a
+            // batch left asleep by a failed freeze: wake it now, without effects.
+            const state = this.subjects.get(subject);
+            if (state?.batch && !state.rendering) {
+                this.disarmRecovery(subject);
+                await this.host.wakeForBatch(state.batch.latest);
+            }
+            return this.acknowledge(coalescingReceiptKey(occurrence.serverId, occurrence.binding, occurrence.eventId), duplicate, subject, occurrence.eventId);
+        }
+        const born = this.subjects.has(subject) ? undefined : (occurrence.initial && !occurrence.retract ? 'none' : 'unknown');
+        const state = this.subjectFor(subject, occurrence);
+        const occupantUnread = this.refreshOccupant(state);
+        const priorEventId = state.occupant?.eventId ?? state.batch?.latest.eventId ?? state.rendering?.batch.latest.eventId ?? state.consumedEventId;
+        this.host.audit({ kind: 'received', subject, eventId: occurrence.eventId, retract: occurrence.retract, deferred: occurrence.deferred });
+        let outcome;
+        if (occurrence.retract) {
+            outcome = await this.retract(subject, state, occurrence, occupantUnread);
+        }
+        else if (occurrence.deferred) {
+            outcome = await this.acceptDeferred(subject, state, occurrence, occupantUnread);
+        }
+        else {
+            outcome = await this.acceptPlain(subject, state, occurrence, occupantUnread);
+        }
+        if (occurrence.scope.kind === 'channel' && occurrence.identity && !occurrence.retract) {
+            state.identity = mergeIdentity(state.identity, occurrence.identity);
+        }
+        state.touchedAt = this.now();
+        const result = { accepted: true, coalesce: { outcome, ...(priorEventId ? { priorEventId } : {}) } };
+        const receiptKey = coalescingReceiptKey(occurrence.serverId, occurrence.binding, occurrence.eventId);
+        const entry = { result: structuredClone(result), at: this.now(), committed: false };
+        try {
+            this.host.recordReceipt?.({
+                key: receiptKey, result: entry.result, at: entry.at, subject, ...(born ? { born } : {}),
+                batch: state.batch ? structuredClone({ latest: state.batch.latest, notices: state.batch.notices, dropped: state.batch.dropped }) : null,
+            });
+        }
+        catch (error) {
+            // Not acknowledged: the work would be lost while its receipt suppressed
+            // a retry. The producer retries within the window.
+            this.host.audit({ kind: 'persist-failed', subject, eventId: occurrence.eventId, error: String(error) });
+            throw new CoalesceError('eventId', 'host could not persist the acceptance; retry', -32000);
+        }
+        this.receipts.set(receiptKey, entry);
+        this.prune();
+        this.persist();
+        // Written but not yet durable: the in-memory receipt deduplicates a retry
+        // while this process lives, and the retry commits it (acknowledge); after
+        // a kill nothing of it exists and the retry is a fresh acceptance.
+        return this.acknowledge(receiptKey, entry, subject, occurrence.eventId);
+    }
+    subjectFor(subject, occurrence) {
+        let state = this.subjects.get(subject);
+        if (!state) {
+            // §3.3: an untracked subject is `unknown` unless the producer marks the
+            // birth of the subject. A retraction is never a birth.
+            state = { history: occurrence.initial && !occurrence.retract ? 'none' : 'unknown', touchedAt: this.now() };
+            this.subjects.set(subject, state);
+        }
+        return state;
+    }
+    /** Re-check the occupant against the host: consumed occupants become history. */
+    refreshOccupant(state) {
+        if (!state.occupant)
+            return false;
+        if (this.host.isUnread(state.occupant.placement))
+            return true;
+        state.history = 'some';
+        state.consumedEventId = state.occupant.eventId;
+        state.occupant = undefined;
+        return false;
+    }
+    scheduleRecovery(subject, state) {
+        const prior = this.recovery.get(subject);
+        if (prior?.timer)
+            clearTimeout(prior.timer);
+        const attempt = (prior?.attempt ?? 0) + 1;
+        const base = this.options.recoveryBackoffMs ?? 1_000;
+        const delay = Math.min(base * 2 ** (attempt - 1), base * 60);
+        const entry = { attempt };
+        entry.timer = setTimeout(() => {
+            // Disarm, but keep the attempt count: a freeze that fails again backs
+            // off further. The count resets only on success or disposal.
+            if (this.recovery.get(subject) === entry)
+                entry.timer = undefined;
+            if (this.suspended || this.subjects.get(subject) !== state || !state.batch || state.rendering)
+                return;
+            // Authority and wake policy are the host's, re-evaluated at fire time.
+            if (!this.host.authorized(state.batch.latest))
+                return;
+            this.host.audit({ kind: 'recovery-wake', subject, eventId: state.batch.latest.eventId, attempt, delayMs: delay });
+            void this.host.wakeForBatch(state.batch.latest).catch(() => { });
+        }, delay);
+        entry.timer.unref?.();
+        this.recovery.set(subject, entry);
+    }
+    /** Disarm the timer only (a producer retry wakes now; the count stands). */
+    disarmRecovery(subject) {
+        const prior = this.recovery.get(subject);
+        if (prior?.timer) {
+            clearTimeout(prior.timer);
+            prior.timer = undefined;
+        }
+    }
+    /** Success or disposal of the pending work: forget the failure series. */
+    clearRecovery(subject) {
+        const prior = this.recovery.get(subject);
+        if (prior?.timer)
+            clearTimeout(prior.timer);
+        this.recovery.delete(subject);
+    }
+    dropBatches(subject, state) {
+        this.clearRecovery(subject);
+        let dropped = false;
+        if (state.batch) {
+            this.host.audit({ kind: 'displaced', subject, eventId: state.batch.latest.eventId, batch: true });
+            state.batch = undefined;
+            dropped = true;
+        }
+        if (state.rendering) {
+            this.host.audit({ kind: 'render-cancelled', subject, eventId: state.rendering.batch.latest.eventId });
+            state.rendering.cancelled = true;
+            state.rendering = undefined;
+            dropped = true;
+        }
+        return dropped;
+    }
+    async retract(subject, state, occurrence, occupantUnread) {
+        if (occupantUnread && state.occupant) {
+            this.host.audit({ kind: 'removed', subject, eventId: state.occupant.eventId });
+            if (!this.host.remove(state.occupant.placement)) {
+                // Still in context and possibly about to be read: say so, append the notice.
+                this.host.audit({ kind: 'remove-failed', subject, eventId: state.occupant.eventId });
+                state.history = 'unknown';
+            }
+        }
+        state.occupant = undefined;
+        this.dropBatches(subject, state);
+        this.host.cancelWake(subject);
+        state.consumedEventId = undefined;
+        if (state.history === 'none')
+            return 'retracted';
+        if (!occurrence.content.length)
+            return 'consumed';
+        // The notice is an ordinary occurrence: it rides the normal delivery path
+        // (tags → gate policy → wake) and is consumed like any message — in the
+        // context that read a version, never a new one (§3.2).
+        const placement = await this.host.deliver({ ...occurrence, deliverTo: state.audienceAgent });
+        if (placement) {
+            state.occupant = { eventId: occurrence.eventId, placement };
+            state.audienceAgent = placement.agent;
+        }
+        return 'noted';
+    }
+    async acceptPlain(subject, state, occurrence, occupantUnread) {
+        const hadBatch = this.dropBatches(subject, state);
+        if (occupantUnread && state.occupant) {
+            const prior = state.occupant;
+            this.host.audit({ kind: 'displaced', subject, eventId: prior.eventId });
+            if (this.host.remove(prior.placement)) {
+                this.host.cancelWake(subject);
+                // The replacement follows the prior delivery's audience (§3.2).
+                const placement = await this.host.deliver({ ...occurrence, deliverTo: prior.placement.agent });
+                state.occupant = placement ? { eventId: occurrence.eventId, placement } : undefined;
+                if (placement)
+                    state.audienceAgent = placement.agent;
+                return 'replaced';
+            }
+            // Could not remove: the prior may still be read. Append, as for consumed.
+            this.host.audit({ kind: 'remove-failed', subject, eventId: prior.eventId });
+            state.history = 'unknown';
+            state.consumedEventId = prior.eventId;
+            state.occupant = undefined;
+        }
+        if (hadBatch)
+            this.host.cancelWake(subject);
+        const placement = await this.host.deliver(occurrence);
+        state.occupant = placement ? { eventId: occurrence.eventId, placement } : undefined;
+        if (placement)
+            state.audienceAgent = placement.agent;
+        if (hadBatch)
+            return 'replaced';
+        return state.consumedEventId || state.history !== 'none' ? 'appended' : 'first';
+    }
+    async acceptDeferred(subject, state, occurrence, occupantUnread) {
+        let outcome = 'first';
+        if (occupantUnread && state.occupant) {
+            // §5.1: a notice displaces an unread plain occurrence and opens a batch
+            // — in the audience that held the plain occurrence (§3.2).
+            this.host.audit({ kind: 'displaced', subject, eventId: state.occupant.eventId });
+            if (this.host.remove(state.occupant.placement)) {
+                outcome = 'replaced';
+                occurrence = { ...occurrence, deliverTo: state.occupant.placement.agent };
+            }
+            else {
+                this.host.audit({ kind: 'remove-failed', subject, eventId: state.occupant.eventId });
+                state.history = 'unknown';
+            }
+            this.host.cancelWake(subject);
+            state.occupant = undefined;
+        }
+        else if (state.batch?.latest.deliverTo) {
+            // Later notices stay in the batch's audience.
+            occurrence = { ...occurrence, deliverTo: state.batch.latest.deliverTo };
+        }
+        const notice = { eventId: occurrence.eventId, timestamp: occurrence.timestamp, ...(occurrence.data !== undefined ? { data: structuredClone(occurrence.data) } : {}) };
+        if (state.batch) {
+            state.batch.notices.push(notice);
+            if (state.batch.notices.length > this.maxNotices) {
+                state.batch.notices.shift();
+                state.batch.dropped++;
+            }
+            state.batch.latest = occurrence;
+            outcome = 'replaced';
+        }
+        else {
+            // Rule 1: a notice during a render opens a NEW batch ("first").
+            state.batch = { latest: occurrence, notices: [notice], dropped: 0 };
+        }
+        await this.host.wakeForBatch(occurrence);
+        return outcome;
+    }
+    // ---------------------------------------------------------------------------
+    // Assembly (deferred batches only — plain content is already in context)
+    // ---------------------------------------------------------------------------
+    /**
+     * Render and materialize every pending batch whose audience includes
+     * `agentName`. Called by the host at a turn's assembly boundary, before the
+     * compile. Bounded by the host's render timeout; a failed or late render
+     * materializes the admitted fallback (§5.3).
+     */
+    async assemble(agentName) {
+        if (this.suspended)
+            return;
+        const work = [];
+        for (const subject of [...this.subjects.keys()]) {
+            // The handle is wrapped: a bare promise returned through `locked` would
+            // be flattened by `then`, holding the lock until the render settled —
+            // and the settlement itself needs the lock.
+            const started = await this.locked(() => this.freeze(subject, agentName));
+            if (started)
+                work.push(started.done);
+        }
+        await Promise.all(work);
+        this.persist();
+    }
+    /**
+     * Under the lock: decide whether `subject`'s batch renders for `agentName`,
+     * freeze it, make the render-start durable, re-check authority, and start
+     * the RPC. Returns the render's completion (shared by every assembly that
+     * waits on this batch, vector 25) or undefined when nothing was started.
+     */
+    async freeze(subject, agentName) {
+        const state = this.subjects.get(subject);
+        if (!state || this.suspended)
+            return undefined;
+        if (state.rendering) {
+            // Another assembly froze this batch; share its outcome (vector 25).
+            const rendering = state.rendering;
+            return (await this.host.audience(rendering.batch.latest)).includes(agentName) && state.rendering === rendering ? { done: rendering.done } : undefined;
+        }
+        const batch = state.batch;
+        if (!batch)
+            return undefined;
+        // The audience lookup may spawn a fork. Under the lock no admission can
+        // move the subject on meanwhile; the identity check guards the host.
+        const audience = await this.host.audience(batch.latest);
+        if (!audience.includes(agentName) || state.batch !== batch || state.rendering)
+            return undefined;
+        state.batch = undefined;
+        this.host.cancelWake(subject);
+        if (!this.host.authorized(batch.latest)) {
+            this.host.audit({ kind: 'revoked', subject, eventId: batch.latest.eventId });
+            return undefined;
+        }
+        const rendering = { batch, cancelled: false, done: Promise.resolve() };
+        state.rendering = rendering;
+        // The render-start boundary is recoverable BEFORE the RPC: a restart
+        // then takes the fallback instead of asking the server a second time.
+        try {
+            if (this.host.saveNow)
+                this.host.saveNow(this.snapshot());
+            else
+                this.persist();
+            await this.host.commit?.();
+        }
+        catch (error) {
+            this.host.audit({ kind: 'persist-failed', subject, eventId: batch.latest.eventId, error: String(error) });
+            state.rendering = undefined;
+            batch.noRender = true; // cannot prove a render never started → fallback
+            state.batch = batch;
+            // The wake was withdrawn above; acknowledged work must not sleep until
+            // unrelated traffic happens by. Re-wake with backoff, so a persistent
+            // storage outage does not become a tight loop of model turns.
+            this.scheduleRecovery(subject, state);
+            return undefined;
+        }
+        this.clearRecovery(subject);
+        if (this.suspended) {
+            state.rendering = undefined;
+            state.batch = batch;
+            return undefined;
+        }
+        // Authority (grant, registration, binding) is re-checked immediately
+        // before dispatch: a server id reassigned to another endpoint during the
+        // commit must not receive this batch's notices.
+        if (!this.host.authorized(batch.latest)) {
+            this.host.audit({ kind: 'revoked', subject, eventId: batch.latest.eventId });
+            state.rendering = undefined;
+            return undefined;
+        }
+        rendering.done = this.render(subject, state, rendering, agentName);
+        return { done: rendering.done };
+    }
+    async render(subject, state, rendering, assemblingFor) {
+        const { batch } = rendering;
+        const occurrence = batch.latest;
+        let content = occurrence.content;
+        let timestamp = occurrence.timestamp;
+        let source = 'fallback';
+        if (!batch.noRender) {
+            const params = {
+                featureSet: occurrence.featureSet ?? (occurrence.scope.kind === 'featureSet' ? occurrence.scope.id : ''),
+                ...(occurrence.scope.kind === 'channel' ? { channelId: occurrence.scope.id } : {}),
+                key: occurrence.key, eventId: occurrence.eventId,
+                notices: structuredClone(batch.notices), dropped: batch.dropped,
+            };
+            this.rendersInFlight.set(occurrence.serverId, (this.rendersInFlight.get(occurrence.serverId) ?? 0) + 1);
+            try {
+                const result = await this.host.render(occurrence, params);
+                if (rendering.cancelled) {
+                    this.host.audit({ kind: 'late-render', subject, eventId: occurrence.eventId, discarded: true });
+                }
+                else
+                    validateCoalescedContent(result?.content, this.options.maxContentBytes);
+                if (rendering.cancelled)
+                    throw new CancelledRender();
+                content = result.content;
+                timestamp = typeof result.timestamp === 'string' ? result.timestamp : new Date().toISOString();
+                source = 'render';
+            }
+            catch (error) {
+                if (!(error instanceof CancelledRender))
+                    this.host.audit({ kind: 'render-failed', subject, eventId: occurrence.eventId, error: String(error) });
+            }
+            finally {
+                const left = (this.rendersInFlight.get(occurrence.serverId) ?? 1) - 1;
+                if (left > 0)
+                    this.rendersInFlight.set(occurrence.serverId, left);
+                else
+                    this.rendersInFlight.delete(occurrence.serverId);
+            }
+        }
+        // Settlement runs under the lock: between the RPC's return and the state
+        // update no admission can withdraw or replace what is being published.
+        await this.locked(async () => {
+            try {
+                if (rendering.cancelled || state.rendering !== rendering || this.suspended)
+                    return;
+                // Rule 4: authority is re-checked at response.
+                if (!this.host.authorized(occurrence)) {
+                    this.host.audit({ kind: 'revoked', subject, eventId: occurrence.eventId });
+                    return;
+                }
+                this.host.audit({ kind: 'rendered', subject, eventId: occurrence.eventId, source, empty: content.length === 0 });
+                if (!content.length)
+                    return; // §5.2: nothing happened
+                const placement = await this.host.deliver({ ...occurrence, timestamp, content }, content, assemblingFor);
+                if (placement?.deferredId) {
+                    // Landed in another agent's deferred queue (its turn is alive): still
+                    // unread there, so it stays replaceable and withdrawable.
+                    state.occupant = { eventId: occurrence.eventId, placement };
+                    state.audienceAgent = placement.agent;
+                    return;
+                }
+                // The materialized occurrence is consumed by the request being assembled.
+                state.history = 'some';
+                state.consumedEventId = occurrence.eventId;
+                state.occupant = undefined;
+                if (placement)
+                    state.audienceAgent = placement.agent;
+            }
+            finally {
+                if (state.rendering === rendering)
+                    state.rendering = undefined;
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    restore(snapshot) {
+        if (!snapshot || snapshot.version !== 1)
+            return;
+        const now = this.now();
+        for (const [key, entry] of snapshot.receipts) {
+            if (now - entry.at <= this.retryWindowMs)
+                this.receipts.set(key, { ...entry, committed: true });
+        }
+        for (const s of snapshot.subjects) {
+            const state = {
+                // A stored occupant is in context and will be in the next request:
+                // it counts as read from here on (the watermark restarts at the head).
+                history: s.occupant ? 'some' : s.history,
+                consumedEventId: s.occupant?.eventId ?? s.consumedEventId,
+                identity: s.identity,
+                audienceAgent: s.audienceAgent ?? s.occupant?.placement.agent,
+                touchedAt: now,
+            };
+            if (s.batch) {
+                // An interrupted render is not replayed (§3.2): a batch that was
+                // RENDERING keeps its fallback; a batch that was only pending renders
+                // normally at the next assembly.
+                state.batch = { latest: s.batch.latest, notices: s.batch.notices, dropped: s.batch.dropped, ...(s.batch.rendering ? { noRender: true } : {}) };
+            }
+            this.subjects.set(s.subject, state);
+        }
+        this.settlePublished();
+    }
+    /**
+     * A batch restored as RENDERING may already have been published (its
+     * result or fallback is a durable context message; only the completion
+     * snapshot was lost). Recovery then marks it consumed instead of
+     * delivering the fallback a second time.
+     */
+    settlePublished() {
+        if (!this.host.wasPublished)
+            return;
+        for (const [subject, state] of this.subjects) {
+            const batch = state.batch;
+            if (!batch?.noRender)
+                continue;
+            if (this.host.wasPublished(subject, batch.latest.eventId)) {
+                state.batch = undefined;
+                state.history = 'some';
+                state.consumedEventId = batch.latest.eventId;
+            }
+        }
+    }
+    /** Apply receipts written since the last snapshot (crash-window bridge). */
+    restoreReceipts(records) {
+        const now = this.now();
+        for (const r of records) {
+            if (now - r.at > this.retryWindowMs)
+                continue;
+            this.receipts.set(r.key, { result: r.result, at: r.at, committed: true });
+            if (r.born && !this.subjects.has(r.subject))
+                this.subjects.set(r.subject, { history: r.born, touchedAt: now });
+            // A birth fact is not proof the subject is still unread: the plain
+            // occurrence this record acknowledged is in context (durable before the
+            // record) and counts as read from recovery on, like a snapshot occupant.
+            let eventId;
+            try {
+                eventId = JSON.parse(r.key)[2];
+            }
+            catch { /* malformed key: no settlement */ }
+            if (eventId && this.host.wasPublished?.(r.subject, eventId)) {
+                const state = this.subjects.get(r.subject) ?? { history: 'unknown', touchedAt: now };
+                state.history = 'some';
+                state.consumedEventId = eventId;
+                this.subjects.set(r.subject, state);
+            }
+            if (r.batch === undefined)
+                continue; // pre-round-3 record: no batch information
+            // The subject's batch AFTER that acceptance, newer than the snapshot:
+            // the accepted deferred work itself, or null for a withdrawal /
+            // replacement that cleared it. It never began rendering before the
+            // record was written, but the snapshot cannot say whether it did
+            // afterwards: take the fallback.
+            const state = this.subjects.get(r.subject) ?? { history: 'unknown', touchedAt: now };
+            state.batch = r.batch
+                ? { latest: r.batch.latest, notices: r.batch.notices, dropped: r.batch.dropped, noRender: true }
+                : undefined;
+            this.subjects.set(r.subject, state);
+        }
+        this.settlePublished();
+    }
+    snapshot() {
+        return {
+            version: 1,
+            receipts: [...this.receipts],
+            subjects: [...this.subjects].map(([subject, s]) => ({
+                subject, history: s.history, consumedEventId: s.consumedEventId, identity: s.identity,
+                ...(s.audienceAgent ? { audienceAgent: s.audienceAgent } : {}),
+                ...(s.occupant ? { occupant: s.occupant } : {}),
+                ...(s.batch ? { batch: { latest: s.batch.latest, notices: s.batch.notices, dropped: s.batch.dropped, ...(s.batch.noRender ? { rendering: true } : {}) } }
+                    : s.rendering ? { batch: { latest: s.rendering.batch.latest, notices: s.rendering.batch.notices, dropped: s.rendering.batch.dropped, rendering: true } }
+                        : {}),
+            })),
+        };
+    }
+    /** Batches whose wake should be re-queued after a restart (their fallback is pending). */
+    pendingBatchOccurrences() {
+        return [...this.subjects.values()].flatMap(s => s.batch ? [s.batch.latest] : []);
+    }
+    suspend() {
+        this.suspended = true;
+        for (const subject of [...this.recovery.keys()])
+            this.clearRecovery(subject);
+        for (const [subject, state] of this.subjects) {
+            if (state.rendering) {
+                state.rendering.cancelled = true;
+                this.host.audit({ kind: 'render-cancelled', subject, eventId: state.rendering.batch.latest.eventId, reason: 'suspend' });
+            }
+        }
+    }
+    persist() { this.host.save(() => this.snapshot()); }
+    prune() {
+        const now = this.now();
+        if (this.receipts.size > 4 * this.maxSubjects) {
+            for (const [key, entry] of this.receipts)
+                if (now - entry.at > this.retryWindowMs)
+                    this.receipts.delete(key);
+        }
+        if (this.subjects.size <= this.maxSubjects)
+            return;
+        // Evict the oldest idle subjects; their history degrades to `unknown`
+        // (an untracked subject) which is the conservative outcome (§3.3).
+        const idle = [...this.subjects].filter(([, s]) => !s.occupant && !s.batch && !s.rendering).sort((a, b) => a[1].touchedAt - b[1].touchedAt);
+        for (const [key] of idle.slice(0, Math.max(0, this.subjects.size - this.maxSubjects)))
+            this.subjects.delete(key);
+    }
+}
+//# sourceMappingURL=push-coalescer.js.map