@north-light/crouter 0.3.185 → 0.3.186

package/dist/core/runtime/broker/message-ledger.js

@@ -1,143 +0,0 @@
-// message-ledger.ts — broker-owned message identity across pi's id-less queues.
-//
-// pi's steering/follow-up queues and user messages carry TEXT only: `steer()`
-// pushes bare strings, `queue_update` relays bare string arrays, and retirement
-// (on user `message_start`) is a first-index-of-text splice. Every downstream
-// consumer was therefore forced into order/text heuristics to match its own
-// optimistic send to the wake that echoed it — wrong under duplicates,
-// cross-surface sends, and reconnect replay.
-//
-// The broker is the ONLY writer to the engine (every prompt/steer/follow_up/
-// deliver funnels through driveEngine) and observes pi's event stream
-// synchronously in-process, so it can own identity at the wire boundary: mint
-// (or adopt the sender's) id per accepted frame, mirror pi's queue state by
-// reconciling pi's own `queue_update` events, and attach the retired entry's id
-// to the relayed user `message_start`. Same deterministic algorithm over the
-// same data in the same process as pi's own bookkeeping — it cannot drift.
-//
-// pi ordering facts this relies on (verified at pi 0.83.0, agent-session.js):
-//  - `_queueSteer`/`_queueFollowUp` push the text and emit `queue_update`
-//    synchronously inside the steer/followUp call.
-//  - On a queued message's user `message_start`, `_handleAgentEvent` splices
-//    the queue and emits `queue_update` BEFORE emitting the `message_start`,
-//    so a retirement's queue_update always precedes its message and two
-//    removals never interleave.
-//  - An idle `prompt()` never touches a queue — its user message matches a
-//    pending dispatch intent by text instead.
-import { randomUUID } from 'node:crypto';
-/** Dispatch intents not yet observed anywhere: bounded FIFO so an intent whose
- *  text pi transformed (and so never matches) cannot accumulate forever. */
-const MAX_PENDING_INTENTS = 32;
-/** Recent id-bearing user-message dispatches carried in `welcome` so a
- *  reattaching follower can key its snapshot's trailing user wakes. */
-const MAX_RECENT = 8;
-export class MessageIdLedger {
-    steering = [];
-    followUp = [];
-    pendingIntents = [];
-    stagedRetirementId = null;
-    recent = [];
-    /** Record an accepted client frame's identity before its engine call runs.
-     *  `id` is the sender's `message_id` when it minted one, else broker-minted. */
-    noteDispatch(id, text) {
-        this.pendingIntents.push({ id, text });
-        if (this.pendingIntents.length > MAX_PENDING_INTENTS)
-            this.pendingIntents.shift();
-    }
-    /** Remove a noted intent whose engine call rejected — the message will never
-     *  appear in a queue or as a user message. No-op if already adopted. */
-    dropIntent(id) {
-        const idx = this.pendingIntents.findIndex((e) => e.id === id);
-        if (idx !== -1)
-            this.pendingIntents.splice(idx, 1);
-    }
-    /**
-     * Fold one pi `queue_update` into the ledger and return the id arrays
-     * parallel to its text arrays (total: every position gets an id).
-     *
-     * Per-queue positional diff against the mirrored entries: a text matching an
-     * old entry at-or-after the cursor keeps its id (everything skipped is
-     * removed); an unmatched text ADOPTS the first pending intent with equal
-     * text, else mints a fresh id. Exactly ONE removal across both queues is
-     * pi's per-message retirement (its queue_update precedes the user
-     * `message_start` it belongs to) and is staged for `takeUserMessageId`;
-     * 0 or >1 removals (an enqueue, clearQueue/dequeue, abort) stage nothing.
-     */
-    reconcileQueueUpdate(steering, followUp) {
-        const removed = [];
-        const next = (old, texts) => {
-            const out = [];
-            let cursor = 0;
-            for (const text of texts) {
-                let match = -1;
-                for (let j = cursor; j < old.length; j++) {
-                    if (old[j].text === text) {
-                        match = j;
-                        break;
-                    }
-                }
-                if (match !== -1) {
-                    for (let j = cursor; j < match; j++)
-                        removed.push(old[j].id);
-                    out.push(old[match]);
-                    cursor = match + 1;
-                    continue;
-                }
-                const intentIdx = this.pendingIntents.findIndex((e) => e.text === text);
-                const id = intentIdx !== -1 ? this.pendingIntents.splice(intentIdx, 1)[0].id : randomUUID();
-                out.push({ id, text });
-            }
-            for (let j = cursor; j < old.length; j++)
-                removed.push(old[j].id);
-            return out;
-        };
-        this.steering = next(this.steering, steering);
-        this.followUp = next(this.followUp, followUp);
-        this.stagedRetirementId = removed.length === 1 ? removed[0] : null;
-        return {
-            steeringIds: this.steering.map((e) => e.id),
-            followUpIds: this.followUp.map((e) => e.id),
-        };
-    }
-    /**
-     * The id for a relayed user `message_start`, or undefined when this message
-     * carries none (an engine-command expansion, a text pi transformed, or a
-     * pre-ledger replay). A staged retirement wins — pi emitted its queue_update
-     * synchronously right before this message; otherwise the first pending
-     * intent with equal text (the idle-prompt case, which never touches a
-     * queue). Id-bearing results are remembered for `recentUserMessages`.
-     */
-    takeUserMessageId(messageText) {
-        const staged = this.stagedRetirementId;
-        if (staged !== null) {
-            this.stagedRetirementId = null;
-            this.remember(staged, messageText);
-            return staged;
-        }
-        const idx = this.pendingIntents.findIndex((e) => e.text === messageText);
-        if (idx === -1)
-            return undefined;
-        const intent = this.pendingIntents.splice(idx, 1)[0];
-        this.remember(intent.id, messageText);
-        return intent.id;
-    }
-    /** The last {@link MAX_RECENT} id-bearing user-message dispatches, oldest
-     *  first — the `welcome.recentUserMessages` payload. */
-    recentUserMessages() {
-        return this.recent.map((e) => ({ ...e }));
-    }
-    /** Session rebind/replacement: the mirrored queues, staged retirement, and
-     *  recent list all described the OLD session — drop everything. */
-    reset() {
-        this.steering = [];
-        this.followUp = [];
-        this.pendingIntents = [];
-        this.stagedRetirementId = null;
-        this.recent = [];
-    }
-    remember(id, text) {
-        this.recent.push({ id, text });
-        if (this.recent.length > MAX_RECENT)
-            this.recent.shift();
-    }
-}