@zq-silk/yui 0.6.0 → 0.6.2

package/dist/controller/runtimeEventProcessor.js

@@ -1,4 +1,5 @@
-/** Folds immutable Hook facts one at a time before acknowledging them. */
+const DEFAULT_MAX_RUNTIME_EVENTS_PER_DRAIN = 64;
+/** Folds immutable Hook facts in one bounded transaction before acknowledging them. */
 export class FileRuntimeEventProcessor {
     inbox;
     observer;
@@ -17,48 +18,128 @@ export class FileRuntimeEventProcessor {
             events = this.inbox.list();
         }
         catch (error) {
-            return { acknowledgedEventIds, deferred, failed: [{ error }] };
+            return emptyDrainFailure(error);
         }
-        for (const event of events) {
+        const coalesced = coalesceRuntimeProgress(events);
+        const maximum = positiveInteger(this.options.maxEventsPerDrain, DEFAULT_MAX_RUNTIME_EVENTS_PER_DRAIN);
+        const selected = selectDrainBatch(coalesced, maximum);
+        let stateTransactions = 0;
+        if (selected.length > 0 && this.observer.withRuntimeEventTransaction !== undefined) {
             try {
-                if (event.type === "native-turn-completed") {
-                    const outcome = this.applyCodex(event, now);
-                    if (outcome === "deferred") {
-                        deferred.push(event);
-                        continue;
-                    }
+                stateTransactions += 1;
+                const folded = this.observer.withRuntimeEventTransaction(() => (selected.map((candidate) => this.foldOne(candidate, now))));
+                for (const result of folded) {
+                    this.finalizeOne(result, acknowledgedEventIds, deferred, failed);
                 }
-                else if (event.type === "claude-stop-failure") {
-                    this.applyClaudeStopFailure(event, now);
-                }
-                else if (event.type === "native-session-lifecycle") {
-                    const outcome = this.applySessionLifecycle(event, now);
-                    if (outcome === "deferred") {
-                        deferred.push(event);
-                        continue;
+            }
+            catch {
+                // A failed aggregate transaction commits nothing. Retry each candidate
+                // independently so one bad event cannot strand unrelated facts.
+                for (const candidate of selected) {
+                    try {
+                        stateTransactions += 1;
+                        const folded = this.observer.withRuntimeEventTransaction(() => (this.foldOne(candidate, now)));
+                        this.finalizeOne(folded, acknowledgedEventIds, deferred, failed);
                     }
-                }
-                else if (event.type === "native-turn-progress") {
-                    const outcome = this.applyProviderTurnProgress(event, now);
-                    if (outcome === "deferred") {
-                        deferred.push(event);
-                        continue;
+                    catch (candidateError) {
+                        failed.push({ eventId: candidate.event.id, error: candidateError });
                     }
                 }
-                else {
-                    const outcome = this.applyPromptAccepted(event, now);
-                    if (outcome === "deferred") {
-                        deferred.push(event);
-                        continue;
-                    }
+            }
+        }
+        else {
+            for (const candidate of selected) {
+                try {
+                    const folded = this.foldOne(candidate, now);
+                    this.finalizeOne(folded, acknowledgedEventIds, deferred, failed);
+                }
+                catch (error) {
+                    failed.push({ eventId: candidate.event.id, error });
                 }
-                this.acknowledge(event.id, acknowledgedEventIds);
             }
-            catch (error) {
-                failed.push({ eventId: event.id, error });
+        }
+        const progressEventsSelected = selected.filter(({ event }) => (event.type === "native-turn-progress")).length;
+        const representedEventCount = selected.reduce((count, candidate) => (count + candidate.representedEventIds.length), 0);
+        const acknowledged = new Set(acknowledgedEventIds);
+        const remaining = events.filter(({ id }) => !acknowledged.has(id));
+        const remainingProgressEventCount = remaining.filter(({ type }) => (type === "native-turn-progress")).length;
+        return {
+            acknowledgedEventIds,
+            deferred,
+            failed,
+            remainingEventCount: Math.max(0, events.length - acknowledgedEventIds.length),
+            metrics: {
+                listedEventCount: events.length,
+                selectedEventCount: selected.length,
+                semanticEventsSelected: selected.length - progressEventsSelected,
+                progressEventsSelected,
+                progressEventsCoalesced: representedEventCount - selected.length,
+                stateTransactions,
+                remainingSemanticEventCount: remaining.length - remainingProgressEventCount,
+                remainingProgressEventCount
             }
+        };
+    }
+    foldOne(candidate, now) {
+        const event = candidate.event;
+        let outcome = "applied";
+        if (event.type === "native-turn-completed") {
+            outcome = this.applyCodex(event, now);
+        }
+        else if (event.type === "claude-stop-failure") {
+            this.applyClaudeStopFailure(event, now);
+        }
+        else if (event.type === "native-session-lifecycle") {
+            outcome = this.applySessionLifecycle(event, now);
+        }
+        else if (event.type === "native-turn-progress") {
+            outcome = this.applyProviderTurnProgress(event, now);
+        }
+        else if (event.type === "durable-job-terminal") {
+            // f7/rr5: The supervisor already transitioned the job and
+            // enqueued the Leader wakeup. This event is the durable terminal
+            // channel: acknowledge it so the Controller's event pipeline
+            // converges without re-processing. No state change to apply.
+            this.applyDurableJobTerminal(event);
+        }
+        else {
+            outcome = this.applyPromptAccepted(event, now);
+        }
+        return {
+            candidate,
+            outcome,
+            notifyTaskRuntime: outcome === "applied" && (event.type === "native-session-lifecycle"
+                || event.type === "native-prompt-accepted"
+                || (event.type === "native-turn-completed" && event.scope === "task"))
+        };
+    }
+    finalizeOne(folded, acknowledged, deferred, failed) {
+        const { candidate, outcome } = folded;
+        try {
+            if (outcome === "deferred") {
+                deferred.push(candidate.event);
+                this.acknowledge(candidate.representedEventIds.filter((id) => id !== candidate.event.id), acknowledged);
+                return;
+            }
+            if (folded.notifyTaskRuntime) {
+                const event = candidate.event;
+                if (event.scope === "task" && event.taskId !== undefined && event.type !== "durable-job-terminal") {
+                    this.options.onTaskRuntimeApplied?.({
+                        taskId: event.taskId,
+                        roleName: event.roleName,
+                        agentId: event.agentId,
+                        adapterId: event.adapterId,
+                        ...(event.launchId === undefined ? {} : { launchId: event.launchId }),
+                        nativeSessionId: event.nativeSessionId,
+                        ...(event.runId === undefined ? {} : { runId: event.runId })
+                    });
+                }
+            }
+            this.acknowledge(candidate.representedEventIds, acknowledged);
+        }
+        catch (error) {
+            failed.push({ eventId: candidate.event.id, error });
         }
-        return { acknowledgedEventIds, deferred, failed };
     }
     applySessionLifecycle(event, now) {
         const task = this.observer.getTask(event.taskId);
@@ -77,12 +158,6 @@ export class FileRuntimeEventProcessor {
             ...(event.runId === undefined ? {} : { runId: event.runId }),
             ...(event.sessionSource === undefined ? {} : { sessionSource: event.sessionSource })
         }, now);
-        if (outcome === "applied") {
-            this.options.onTaskRuntimeApplied?.({
-                taskId: event.taskId,
-                roleName: event.roleName
-            });
-        }
         return outcome === "deferred" ? "deferred" : outcome;
     }
     applyPromptAccepted(event, now) {
@@ -102,14 +177,19 @@ export class FileRuntimeEventProcessor {
             runId: event.runId,
             receiptId: event.receiptId
         }, now);
-        if (outcome === "applied") {
-            this.options.onTaskRuntimeApplied?.({
-                taskId: event.taskId,
-                roleName: event.roleName
-            });
-        }
         return outcome === "deferred" ? "deferred" : outcome;
     }
+    /**
+     * f7/rr5: Acknowledge a durable-job-terminal event. The supervisor
+     * already committed the terminal transition and the Leader wakeup;
+     * this event only needs to be acknowledged so it leaves the inbox.
+     */
+    applyDurableJobTerminal(event) {
+        // The event is a notification of a committed state change. No observer
+        // call is needed — the Leader wakeup was enqueued in the same
+        // transaction as the terminal transition.
+        void event;
+    }
     applyProviderTurnProgress(event, now) {
         const task = this.observer.getTask(event.taskId);
         if (task === null || task.status !== "active")
@@ -164,10 +244,6 @@ export class FileRuntimeEventProcessor {
                 this.recordObsolete(event, "runtime-cleanup-or-stopped-session", now);
                 return "obsolete";
             }
-            this.options.onTaskRuntimeApplied?.({
-                taskId: event.taskId,
-                roleName: event.roleName
-            });
             return "applied";
         }
         const input = {
@@ -224,6 +300,10 @@ export class FileRuntimeEventProcessor {
     recordObsolete(event, reason, now) {
         if (event.scope !== "task" || event.taskId === undefined)
             return;
+        // durable-job-terminal events have no provider identity; they are never
+        // recorded as obsolete.
+        if (!("roleName" in event) || !("nativeSessionId" in event))
+            return;
         this.observer.observeObsoleteRuntimeEvent?.({
             eventId: event.id,
             eventType: event.type,
@@ -236,10 +316,129 @@ export class FileRuntimeEventProcessor {
             reason
         }, now);
     }
-    acknowledge(id, acknowledged) {
-        this.inbox.acknowledge(id);
-        acknowledged.push(id);
+    acknowledge(ids, acknowledged) {
+        if (this.inbox.acknowledgeMany !== undefined) {
+            acknowledged.push(...this.inbox.acknowledgeMany(ids));
+            return;
+        }
+        for (const id of ids) {
+            if (this.inbox.acknowledge(id))
+                acknowledged.push(id);
+        }
+    }
+}
+export function coalesceRuntimeProgress(events, instrumentation = {}) {
+    const result = [];
+    let segment = [];
+    const flush = () => {
+        if (segment.length === 0)
+            return;
+        const frontiers = new Map();
+        for (let index = 0; index < segment.length; index += 1) {
+            instrumentation.onProgressVisit?.();
+            const event = segment[index];
+            const key = progressStreamKey(event);
+            const frontier = frontiers.get(key);
+            if (frontier === undefined || event.receivedAt > frontier.latestReceivedAt) {
+                frontiers.set(key, {
+                    latestReceivedAt: event.receivedAt,
+                    ...(event.sequence === undefined
+                        ? {}
+                        : {
+                            greatestSequence: event.sequence,
+                            firstGreatestSequenceIndex: index
+                        }),
+                    firstLatestIndex: index
+                });
+            }
+            else if (event.receivedAt === frontier.latestReceivedAt
+                && event.sequence !== undefined
+                && (frontier.greatestSequence === undefined
+                    || event.sequence > frontier.greatestSequence)) {
+                frontiers.set(key, {
+                    ...frontier,
+                    greatestSequence: event.sequence,
+                    firstGreatestSequenceIndex: index
+                });
+            }
+        }
+        const representedByIndex = new Map();
+        for (let index = 0; index < segment.length; index += 1) {
+            instrumentation.onProgressVisit?.();
+            const event = segment[index];
+            const frontier = frontiers.get(progressStreamKey(event));
+            const strictlyDominated = event.receivedAt < frontier.latestReceivedAt
+                || (event.receivedAt === frontier.latestReceivedAt
+                    && event.sequence !== undefined
+                    && frontier.greatestSequence !== undefined
+                    && event.sequence < frontier.greatestSequence);
+            const representativeIndex = strictlyDominated
+                ? frontier.firstGreatestSequenceIndex ?? frontier.firstLatestIndex
+                : index;
+            const represented = representedByIndex.get(representativeIndex) ?? [];
+            represented.push(event.id);
+            representedByIndex.set(representativeIndex, represented);
+        }
+        for (let index = 0; index < segment.length; index += 1) {
+            const representedEventIds = representedByIndex.get(index);
+            if (representedEventIds === undefined)
+                continue;
+            result.push({ event: segment[index], representedEventIds });
+        }
+        segment = [];
+    };
+    for (const event of events) {
+        if (event.type !== "native-turn-progress") {
+            flush();
+            result.push({ event, representedEventIds: [event.id] });
+            continue;
+        }
+        segment.push(event);
     }
+    flush();
+    return result;
+}
+function selectDrainBatch(events, maximum) {
+    // A batch is always an arrival-order prefix. Admission and drain coalescing
+    // keep a progress flood bounded without allowing a later semantic fact to
+    // overtake an earlier progress fence from another Run.
+    return events.slice(0, maximum);
+}
+function progressStreamKey(event) {
+    return JSON.stringify([
+        event.taskId,
+        event.roleName,
+        event.agentId,
+        event.adapterId,
+        event.launchId,
+        event.nativeSessionId,
+        event.runId
+    ]);
+}
+function emptyDrainFailure(error) {
+    return {
+        acknowledgedEventIds: [],
+        deferred: [],
+        failed: [{ error }],
+        remainingEventCount: 0,
+        metrics: {
+            listedEventCount: 0,
+            selectedEventCount: 0,
+            semanticEventsSelected: 0,
+            progressEventsSelected: 0,
+            progressEventsCoalesced: 0,
+            stateTransactions: 0,
+            remainingSemanticEventCount: 0,
+            remainingProgressEventCount: 0
+        }
+    };
+}
+function positiveInteger(value, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new TypeError("Runtime event drain limit must be a positive integer.");
+    }
+    return resolved;
 }
 function isObsoleteRuntimeTurnObservation(value) {
     return typeof value === "object"
@@ -290,7 +489,7 @@ export class AsyncRuntimeEventProcessor {
             events = this.inbox.list();
         }
         catch (error) {
-            return { acknowledgedEventIds, deferred, failed: [{ error }] };
+            return emptyDrainFailure(error);
         }
         for (const event of events) {
             try {
@@ -318,6 +517,12 @@ export class AsyncRuntimeEventProcessor {
                         continue;
                     }
                 }
+                else if (event.type === "durable-job-terminal") {
+                    // f7/rr5: The supervisor already transitioned the job and
+                    // enqueued the Leader wakeup. This event is the durable terminal
+                    // channel: acknowledge it so the pipeline converges without
+                    // re-processing. No state change to apply.
+                }
                 else {
                     const outcome = await this.applyPromptAccepted(event, now);
                     if (outcome === "deferred") {
@@ -331,7 +536,26 @@ export class AsyncRuntimeEventProcessor {
                 failed.push({ eventId: event.id, error });
             }
         }
-        return { acknowledgedEventIds, deferred, failed };
+        const acknowledged = new Set(acknowledgedEventIds);
+        const remaining = events.filter(({ id }) => !acknowledged.has(id));
+        const progressEventsSelected = events.filter(({ type }) => (type === "native-turn-progress")).length;
+        const remainingProgressEventCount = remaining.filter(({ type }) => (type === "native-turn-progress")).length;
+        return {
+            acknowledgedEventIds,
+            deferred,
+            failed,
+            remainingEventCount: remaining.length,
+            metrics: {
+                listedEventCount: events.length,
+                selectedEventCount: events.length,
+                semanticEventsSelected: events.length - progressEventsSelected,
+                progressEventsSelected,
+                progressEventsCoalesced: 0,
+                stateTransactions: 0,
+                remainingSemanticEventCount: remaining.length - remainingProgressEventCount,
+                remainingProgressEventCount
+            }
+        };
     }
     async applySessionLifecycle(event, now) {
         const task = await this.observer.getTask(event.taskId);
@@ -353,7 +577,12 @@ export class AsyncRuntimeEventProcessor {
         if (outcome === "applied") {
             this.options.onTaskRuntimeApplied?.({
                 taskId: event.taskId,
-                roleName: event.roleName
+                roleName: event.roleName,
+                agentId: event.agentId,
+                adapterId: event.adapterId,
+                launchId: event.launchId,
+                nativeSessionId: event.nativeSessionId,
+                ...(event.runId === undefined ? {} : { runId: event.runId })
             });
         }
         return outcome === "deferred" ? "deferred" : outcome;
@@ -378,7 +607,12 @@ export class AsyncRuntimeEventProcessor {
         if (outcome === "applied") {
             this.options.onTaskRuntimeApplied?.({
                 taskId: event.taskId,
-                roleName: event.roleName
+                roleName: event.roleName,
+                agentId: event.agentId,
+                adapterId: event.adapterId,
+                launchId: event.launchId,
+                nativeSessionId: event.nativeSessionId,
+                runId: event.runId
             });
         }
         return outcome === "deferred" ? "deferred" : outcome;
@@ -439,7 +673,12 @@ export class AsyncRuntimeEventProcessor {
             }
             this.options.onTaskRuntimeApplied?.({
                 taskId: event.taskId,
-                roleName: event.roleName
+                roleName: event.roleName,
+                agentId: event.agentId,
+                adapterId: event.adapterId,
+                ...(event.launchId === undefined ? {} : { launchId: event.launchId }),
+                nativeSessionId: event.nativeSessionId,
+                ...(event.runId === undefined ? {} : { runId: event.runId })
             });
             return "applied";
         }
@@ -495,7 +734,7 @@ export class AsyncRuntimeEventProcessor {
         await this.observer.observeClaudeStopFailureEvent(input, now);
     }
     async recordObsolete(event, reason, now) {
-        if (event.scope !== "task" || event.taskId === undefined)
+        if (event.scope !== "task" || event.taskId === undefined || event.type === "durable-job-terminal")
             return;
         await this.observer.observeObsoleteRuntimeEvent?.({
             eventId: event.id,