@superblocksteam/gateway 2.0.155-next.0

package/dist/events/memory-event-store.js

@@ -0,0 +1,110 @@
+import { PRODUCERS_IN_ORDER, sortEvents } from "./merge.js";
+import { buildSnapshot } from "./snapshot.js";
+import { streamSuffix } from "./stream-key.js";
+import { EVENT_STREAM_TTL_MS, MAX_EVENTS_PER_STREAM, } from "./types.js";
+/**
+ * Local-only fallback for a laptop stack with no Redis, matching the same
+ * fallback the turn store makes. It is not a second source of truth: a
+ * multi-replica deployment would need an external store, because two
+ * processes with private maps cannot agree on what was already delivered.
+ *
+ * A shared test suite runs both implementations against the same behaviour, so
+ * "works locally, breaks on Redis" shows up here rather than in production.
+ */
+export class MemoryEventStore {
+    streams = new Map();
+    async append(event) {
+        const stream = this.streamFor(event, event.producer);
+        stream.expiresAtMs = Date.now() + EVENT_STREAM_TTL_MS;
+        // Presence is the de-duplication record, so it cannot outlive the event
+        // or be evicted separately from it.
+        if (stream.byEventId.has(event.eventId)) {
+            return "duplicate";
+        }
+        stream.byEventId.set(event.eventId, event);
+        this.trim(stream);
+        return "accepted";
+    }
+    async list(input) {
+        this.evictExpired();
+        const producers = input.producer ? [input.producer] : PRODUCERS_IN_ORDER;
+        const collected = [];
+        for (const producer of producers) {
+            const stream = this.streams.get(key(input, producer));
+            for (const event of stream?.byEventId.values() ?? []) {
+                if (input.afterSequence !== undefined &&
+                    event.sequence <= input.afterSequence) {
+                    continue;
+                }
+                collected.push(event);
+            }
+        }
+        const ordered = sortEvents(collected);
+        return input.limit === undefined ? ordered : ordered.slice(0, input.limit);
+    }
+    async snapshot(input) {
+        this.evictExpired();
+        return await buildSnapshot(input, {
+            firstRetainedSequence: async (producer) => this.ordered(input, producer)[0]?.sequence,
+            readAfter: async ({ afterSequence, limit, producer }) => {
+                const after = this.ordered(input, producer).filter((event) => event.sequence > afterSequence);
+                return limit === undefined ? after : after.slice(0, limit);
+            },
+            readTail: async ({ count, producer }) => this.ordered(input, producer).slice(-count),
+        });
+    }
+    /** One producer's retained stream in sequence order, as Redis reads it. */
+    ordered(scope, producer) {
+        const stream = this.streams.get(key(scope, producer));
+        return [...(stream?.byEventId.values() ?? [])].sort((left, right) => left.sequence - right.sequence ||
+            (left.eventId < right.eventId
+                ? -1
+                : left.eventId > right.eventId
+                    ? 1
+                    : 0));
+    }
+    streamFor(scope, producer) {
+        this.evictExpired();
+        const streamKey = key(scope, producer);
+        const existing = this.streams.get(streamKey);
+        if (existing) {
+            return existing;
+        }
+        const created = {
+            byEventId: new Map(),
+            expiresAtMs: Date.now() + EVENT_STREAM_TTL_MS,
+        };
+        this.streams.set(streamKey, created);
+        return created;
+    }
+    /**
+     * Drops the lowest-sequence events past the bound, which takes their
+     * de-duplication records with them: keeping every id forever would make the
+     * bound on events pointless.
+     */
+    trim(stream) {
+        if (stream.byEventId.size <= MAX_EVENTS_PER_STREAM) {
+            return;
+        }
+        const oldestFirst = [...stream.byEventId.values()].sort((left, right) => left.sequence - right.sequence);
+        for (const dropped of oldestFirst.slice(0, stream.byEventId.size - MAX_EVENTS_PER_STREAM)) {
+            stream.byEventId.delete(dropped.eventId);
+        }
+    }
+    evictExpired() {
+        const now = Date.now();
+        for (const [streamKey, stream] of this.streams) {
+            if (stream.expiresAtMs <= now) {
+                this.streams.delete(streamKey);
+            }
+        }
+    }
+}
+/**
+ * The same addressing the Redis store uses, from the same builder, so the two
+ * cannot disagree about which events share a stream.
+ */
+function key(scope, producer) {
+    return streamSuffix(scope, producer);
+}
+//# sourceMappingURL=memory-event-store.js.map

package/dist/events/memory-event-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-event-store.js","sourceRoot":"","sources":["../../src/events/memory-event-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GAOtB,MAAM,YAAY,CAAC;AAgBpB;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACV,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErD,KAAK,CAAC,MAAM,CAAC,KAAoB;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrD,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,mBAAmB,CAAC;QACtD,wEAAwE;QACxE,oCAAoC;QACpC,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,KAIC;QAED,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACzE,MAAM,SAAS,GAAoB,EAAE,CAAC;QACtC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;YACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;gBACrD,IACE,KAAK,CAAC,aAAa,KAAK,SAAS;oBACjC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,aAAa,EACrC,CAAC;oBACD,SAAS;gBACX,CAAC;gBACD,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;QACtC,OAAO,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,KAA4D;QAE5D,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,MAAM,aAAa,CAAC,KAAK,EAAE;YAChC,qBAAqB,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CACxC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ;YAC5C,SAAS,EAAE,KAAK,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE;gBACtD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,MAAM,CAChD,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,aAAa,CAC1C,CAAC;gBACF,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC7D,CAAC;YACD,QAAQ,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,CACtC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IACnE,OAAO,CAAC,KAAiB,EAAE,QAAuB;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CACjD,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACd,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ;YAC9B,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;gBAC3B,CAAC,CAAC,CAAC,CAAC;gBACJ,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;oBAC5B,CAAC,CAAC,CAAC;oBACH,CAAC,CAAC,CAAC,CAAC,CACX,CAAC;IACJ,CAAC;IAEO,SAAS,CAAC,KAAiB,EAAE,QAAuB;QAC1D,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,OAAO,GAAW;YACtB,SAAS,EAAE,IAAI,GAAG,EAAE;YACpB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,mBAAmB;SAC9C,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACK,IAAI,CAAC,MAAc;QACzB,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,qBAAqB,EAAE,CAAC;YACnD,OAAO;QACT,CAAC;QACD,MAAM,WAAW,GAAG,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CACrD,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAChD,CAAC;QACF,KAAK,MAAM,OAAO,IAAI,WAAW,CAAC,KAAK,CACrC,CAAC,EACD,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG,qBAAqB,CAC9C,EAAE,CAAC;YACF,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAEO,YAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/C,IAAI,MAAM,CAAC,WAAW,IAAI,GAAG,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,GAAG,CAAC,KAAiB,EAAE,QAAuB;IACrD,OAAO,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACvC,CAAC"}

package/dist/events/merge.d.ts

@@ -0,0 +1,23 @@
+import type { EventProducer, LiveEditEvent } from "./types.js";
+export declare const PRODUCERS_IN_ORDER: readonly EventProducer[];
+/**
+ * Merges each producer's stream into one order.
+ *
+ * This cannot be a comparator. "Sequence within a producer, timestamp across
+ * producers" has no total order behind it: if one producer's clock steps
+ * backwards between two of its own events (NTP correction, container skew),
+ * its first event can be later than another producer's event that is itself
+ * later than its second. Sorting on such a rule is a cycle, and `Array#sort`
+ * answers a cycle differently depending on the order it read the input — so
+ * two Gateway replicas holding the same events could disagree about what the
+ * turn looked like.
+ *
+ * A merge has no such freedom. Each producer is walked strictly in sequence
+ * order, so its own events can never be reordered against each other whatever
+ * its clock did. Only the choice of which producer to take from next depends
+ * on time, and that is decided by a monotone clock — a producer's event is
+ * never treated as earlier than one already emitted from the same producer —
+ * with producer name and then sequence settling a dead heat. The result
+ * depends on the set of events alone, never on the order they were read.
+ */
+export declare function sortEvents(events: LiveEditEvent[]): LiveEditEvent[];

package/dist/events/merge.js

@@ -0,0 +1,97 @@
+export const PRODUCERS_IN_ORDER = [
+    "dev_server",
+    "sabs",
+];
+/**
+ * Merges each producer's stream into one order.
+ *
+ * This cannot be a comparator. "Sequence within a producer, timestamp across
+ * producers" has no total order behind it: if one producer's clock steps
+ * backwards between two of its own events (NTP correction, container skew),
+ * its first event can be later than another producer's event that is itself
+ * later than its second. Sorting on such a rule is a cycle, and `Array#sort`
+ * answers a cycle differently depending on the order it read the input — so
+ * two Gateway replicas holding the same events could disagree about what the
+ * turn looked like.
+ *
+ * A merge has no such freedom. Each producer is walked strictly in sequence
+ * order, so its own events can never be reordered against each other whatever
+ * its clock did. Only the choice of which producer to take from next depends
+ * on time, and that is decided by a monotone clock — a producer's event is
+ * never treated as earlier than one already emitted from the same producer —
+ * with producer name and then sequence settling a dead heat. The result
+ * depends on the set of events alone, never on the order they were read.
+ */
+export function sortEvents(events) {
+    const byProducer = new Map();
+    for (const event of events) {
+        const stream = byProducer.get(event.producer);
+        if (stream) {
+            stream.push(event);
+        }
+        else {
+            byProducer.set(event.producer, [event]);
+        }
+    }
+    const cursors = [...byProducer.entries()]
+        .sort(([left], [right]) => compareProducers(left, right))
+        .map(([producer, stream]) => ({
+        emittedThroughMs: Number.NEGATIVE_INFINITY,
+        // Sequence is the only authority within a producer. The event id settles
+        // the case of one sequence claimed twice, so even that stays stable.
+        events: [...stream].sort((left, right) => left.sequence - right.sequence ||
+            compareStrings(left.eventId, right.eventId)),
+        position: 0,
+        producer,
+    }));
+    const merged = [];
+    for (;;) {
+        const next = takeNext(cursors);
+        if (!next) {
+            return merged;
+        }
+        merged.push(next);
+    }
+}
+/**
+ * Removes and returns the event that comes next across all producers, or
+ * undefined once every stream is exhausted.
+ */
+function takeNext(cursors) {
+    let chosen;
+    let chosenAtMs = Number.POSITIVE_INFINITY;
+    for (const cursor of cursors) {
+        const head = cursor.events[cursor.position];
+        if (!head) {
+            continue;
+        }
+        const atMs = Math.max(head.occurredAtMs, cursor.emittedThroughMs);
+        // Cursors are already in producer order, so `<` alone keeps the earlier
+        // producer on a tie.
+        if (atMs < chosenAtMs) {
+            chosen = cursor;
+            chosenAtMs = atMs;
+        }
+    }
+    if (!chosen) {
+        return undefined;
+    }
+    chosen.emittedThroughMs = chosenAtMs;
+    const head = chosen.events[chosen.position];
+    chosen.position += 1;
+    return head;
+}
+function compareProducers(left, right) {
+    const leftRank = PRODUCERS_IN_ORDER.indexOf(left);
+    const rightRank = PRODUCERS_IN_ORDER.indexOf(right);
+    return leftRank !== rightRank
+        ? leftRank - rightRank
+        : compareStrings(left, right);
+}
+function compareStrings(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
+//# sourceMappingURL=merge.js.map

package/dist/events/merge.js.map

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

package/dist/events/normalized-collector.d.ts

@@ -0,0 +1,62 @@
+import type { ClarkPeerEvent } from "../sabs/editor-client-methods.js";
+import type { TurnCollector } from "../sabs/turn-collector.js";
+import type { LiveEditEvent, SESSION_STATUSES } from "./types.js";
+/**
+ * How many recent events are remembered for cross-transport de-duplication.
+ * A long build pushes far more than this; forgetting the oldest is safe
+ * because the overlap between the socket and the push path is measured in
+ * seconds, not in thousands of events.
+ */
+export declare const MAX_TRACKED_FINGERPRINTS = 256;
+export type NormalizedTurnCollectorDeps = {
+    collector: TurnCollector;
+    /**
+     * Clark needs an interactive authorization before it can continue. Reported
+     * rather than collected: it is not something Clark did, and a caller that
+     * only reads the turn's reply would never learn the build is stuck.
+     */
+    onAuthRequired?: (reason: string) => void;
+    /** The live-edit session changed state underneath the turn. */
+    onSessionStatus?: (status: (typeof SESSION_STATUSES)[number]) => void;
+    /** The turn id Gateway minted with the prompt this collector is driving. */
+    turnId: string | undefined;
+};
+/**
+ * One door into a turn's collector for both transports.
+ *
+ * Clark's activity reaches Gateway two ways during the transition: directly on
+ * the held editor socket, and relayed through SABS over the push channel. They
+ * overlap, so this applies each underlying fact once, and it drops anything
+ * carrying a turn id other than the one it is collecting for.
+ *
+ * Session lifecycle and auth-required are not turn activity. They are recorded
+ * here for the caller to read rather than pushed into the collector, which
+ * only understands what Clark did.
+ */
+export declare class NormalizedTurnCollector {
+    private readonly deps;
+    private readonly seen;
+    private authReason;
+    private session;
+    constructor(deps: NormalizedTurnCollectorDeps);
+    /** An event observed on the held editor socket. */
+    fromSocket(event: ClarkPeerEvent): void;
+    /** An event relayed through SABS over the push channel. */
+    fromPush(event: LiveEditEvent): void;
+    /** Reason Clark cannot proceed without an interactive authorization. */
+    authRequired(): string | undefined;
+    sessionStatus(): (typeof SESSION_STATUSES)[number] | undefined;
+    /** Exposed so the bound on remembered events can be asserted. */
+    trackedFingerprintCount(): number;
+    /**
+     * A session-scoped event carries no turn id and belongs to every turn on the
+     * live edit; a turn-scoped one belongs only to the turn that minted the id.
+     */
+    private belongsToThisTurn;
+    /**
+     * Records a fingerprint, returning false when it was already known.
+     * Insertion order is iteration order for a Set, so evicting the first entry
+     * drops the oldest.
+     */
+    private remember;
+}

package/dist/events/normalized-collector.js

@@ -0,0 +1,156 @@
+/**
+ * How many recent events are remembered for cross-transport de-duplication.
+ * A long build pushes far more than this; forgetting the oldest is safe
+ * because the overlap between the socket and the push path is measured in
+ * seconds, not in thousands of events.
+ */
+export const MAX_TRACKED_FINGERPRINTS = 256;
+/**
+ * One door into a turn's collector for both transports.
+ *
+ * Clark's activity reaches Gateway two ways during the transition: directly on
+ * the held editor socket, and relayed through SABS over the push channel. They
+ * overlap, so this applies each underlying fact once, and it drops anything
+ * carrying a turn id other than the one it is collecting for.
+ *
+ * Session lifecycle and auth-required are not turn activity. They are recorded
+ * here for the caller to read rather than pushed into the collector, which
+ * only understands what Clark did.
+ */
+export class NormalizedTurnCollector {
+    deps;
+    seen = new Set();
+    authReason;
+    session;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** An event observed on the held editor socket. */
+    fromSocket(event) {
+        const fingerprint = socketFingerprint(event);
+        if (fingerprint && !this.remember(fingerprint)) {
+            return;
+        }
+        this.deps.collector.handle(event);
+    }
+    /** An event relayed through SABS over the push channel. */
+    fromPush(event) {
+        if (!this.belongsToThisTurn(event)) {
+            return;
+        }
+        // The event id is authoritative for a redelivery of the same push; the
+        // content fingerprint is what catches the same fact arriving on the other
+        // transport, which has no event id to compare against.
+        if (!this.remember(`event:${event.eventId}`)) {
+            return;
+        }
+        const fingerprint = pushFingerprint(event);
+        if (fingerprint && !this.remember(fingerprint)) {
+            return;
+        }
+        switch (event.payload.kind) {
+            case "auth_required": {
+                this.authReason = event.payload.reason ?? "auth_required";
+                this.deps.onAuthRequired?.(this.authReason);
+                return;
+            }
+            case "session": {
+                this.session = event.payload.status;
+                this.deps.onSessionStatus?.(this.session);
+                return;
+            }
+            case "chat_message": {
+                this.deps.collector.handle({
+                    kind: "message",
+                    message: {
+                        content: event.payload.text,
+                        ...(event.payload.messageId ? { id: event.payload.messageId } : {}),
+                        role: event.payload.role,
+                        type: event.payload.messageType ?? "text",
+                    },
+                });
+                return;
+            }
+            case "generation_state": {
+                this.deps.collector.handle({
+                    ...(event.payload.hasError === undefined
+                        ? {}
+                        : { hasError: event.payload.hasError }),
+                    ...(event.payload.hasSuggestions === undefined
+                        ? {}
+                        : { hasSuggestions: event.payload.hasSuggestions }),
+                    kind: "generation_state",
+                    state: event.payload.state,
+                });
+                return;
+            }
+            case "progress": {
+                this.deps.collector.handle({
+                    kind: "task_status",
+                    label: event.payload.label,
+                });
+            }
+        }
+    }
+    /** Reason Clark cannot proceed without an interactive authorization. */
+    authRequired() {
+        return this.authReason;
+    }
+    sessionStatus() {
+        return this.session;
+    }
+    /** Exposed so the bound on remembered events can be asserted. */
+    trackedFingerprintCount() {
+        return this.seen.size;
+    }
+    /**
+     * A session-scoped event carries no turn id and belongs to every turn on the
+     * live edit; a turn-scoped one belongs only to the turn that minted the id.
+     */
+    belongsToThisTurn(event) {
+        if (!event.gatewayTurnId) {
+            return true;
+        }
+        return event.gatewayTurnId === this.deps.turnId;
+    }
+    /**
+     * Records a fingerprint, returning false when it was already known.
+     * Insertion order is iteration order for a Set, so evicting the first entry
+     * drops the oldest.
+     */
+    remember(fingerprint) {
+        if (this.seen.has(fingerprint)) {
+            return false;
+        }
+        if (this.seen.size >= MAX_TRACKED_FINGERPRINTS) {
+            const oldest = this.seen.values().next();
+            if (!oldest.done) {
+                this.seen.delete(oldest.value);
+            }
+        }
+        this.seen.add(fingerprint);
+        return true;
+    }
+}
+/**
+ * Identity of a fact as seen on the socket, in the same terms
+ * {@link pushFingerprint} uses, so the two transports collide on it.
+ *
+ * Only events with a stable identity are fingerprinted. A state or label with
+ * no id genuinely recurs during a build, and suppressing a real repeat is
+ * worse than letting a transitional duplicate through: the collector already
+ * drops consecutive identical progress lines.
+ */
+function socketFingerprint(event) {
+    if (event.kind === "message" && typeof event.message.id === "string") {
+        return `message:${event.message.id}`;
+    }
+    return undefined;
+}
+function pushFingerprint(event) {
+    if (event.payload.kind === "chat_message" && event.payload.messageId) {
+        return `message:${event.payload.messageId}`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=normalized-collector.js.map

package/dist/events/normalized-collector.js.map

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

package/dist/events/schema.d.ts

@@ -0,0 +1,9 @@
+import { type ParseResult } from "./types.js";
+/**
+ * Validates one inbound event against the contract.
+ *
+ * SABS validates the same shape before pushing it, which is not a reason to
+ * skip it here: a validated producer is not a trusted one, and this is the
+ * process boundary where the bytes become Gateway's problem.
+ */
+export declare function parseLiveEditEvent(input: unknown): ParseResult;

package/dist/events/schema.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { CHAT_ROLES, EVENT_CONTRACT_VERSION, EVENT_PRODUCERS, GENERATION_STATES, MAX_IDENTIFIER_LENGTH, MAX_LABEL_LENGTH, MAX_SEQUENCE, MAX_TEXT_LENGTH, SESSION_STATUSES, } from "./types.js";
+const identifier = z.string().min(1).max(MAX_IDENTIFIER_LENGTH);
+/**
+ * Payloads are strict objects: an unrecognized key fails the parse rather than
+ * being dropped. A field nobody declared is a field nobody bounded, and this
+ * body arrives from outside the process.
+ */
+const payloadByKind = {
+    auth_required: z
+        .object({ reason: z.string().max(MAX_LABEL_LENGTH).optional() })
+        .strict(),
+    chat_message: z
+        .object({
+        messageId: z.string().max(MAX_IDENTIFIER_LENGTH).optional(),
+        messageType: z.string().max(MAX_IDENTIFIER_LENGTH).optional(),
+        role: z.enum(CHAT_ROLES),
+        text: z.string().min(1).max(MAX_TEXT_LENGTH),
+    })
+        .strict(),
+    generation_state: z
+        .object({
+        hasError: z.boolean().optional(),
+        hasSuggestions: z.boolean().optional(),
+        state: z.enum(GENERATION_STATES),
+    })
+        .strict(),
+    progress: z
+        .object({ label: z.string().min(1).max(MAX_LABEL_LENGTH) })
+        .strict(),
+    session: z.object({ status: z.enum(SESSION_STATUSES) }).strict(),
+};
+const envelope = z
+    .object({
+    applicationId: identifier,
+    eventId: identifier,
+    gatewayTurnId: z.string().max(MAX_IDENTIFIER_LENGTH).optional(),
+    kind: z.enum(Object.keys(payloadByKind)),
+    liveEditId: identifier,
+    occurredAt: z.string().min(1),
+    organizationId: identifier,
+    payload: z.unknown(),
+    producer: z.enum(EVENT_PRODUCERS),
+    sequence: z.number().int().positive().max(MAX_SEQUENCE),
+    version: z.number().int(),
+})
+    .strict();
+/**
+ * Validates one inbound event against the contract.
+ *
+ * SABS validates the same shape before pushing it, which is not a reason to
+ * skip it here: a validated producer is not a trusted one, and this is the
+ * process boundary where the bytes become Gateway's problem.
+ */
+export function parseLiveEditEvent(input) {
+    const parsed = envelope.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: "malformed_event" };
+    }
+    // Version is checked before the payload so an event from a future contract
+    // is reported as such rather than as a malformed body.
+    if (parsed.data.version !== EVENT_CONTRACT_VERSION) {
+        return { ok: false, reason: "unsupported_version" };
+    }
+    const occurredAtMs = Date.parse(parsed.data.occurredAt);
+    if (Number.isNaN(occurredAtMs)) {
+        return { ok: false, reason: "malformed_event" };
+    }
+    const payload = payloadByKind[parsed.data.kind].safeParse(parsed.data.payload);
+    if (!payload.success) {
+        return { ok: false, reason: "malformed_event" };
+    }
+    const event = {
+        applicationId: parsed.data.applicationId,
+        eventId: parsed.data.eventId,
+        ...(parsed.data.gatewayTurnId
+            ? { gatewayTurnId: parsed.data.gatewayTurnId }
+            : {}),
+        kind: parsed.data.kind,
+        liveEditId: parsed.data.liveEditId,
+        occurredAtMs,
+        organizationId: parsed.data.organizationId,
+        payload: {
+            kind: parsed.data.kind,
+            ...payload.data,
+        },
+        producer: parsed.data.producer,
+        sequence: parsed.data.sequence,
+        version: EVENT_CONTRACT_VERSION,
+    };
+    return { ok: true, event };
+}
+//# sourceMappingURL=schema.js.map

package/dist/events/schema.js.map

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

package/dist/events/snapshot.d.ts

@@ -0,0 +1,32 @@
+import { type EventCursor } from "./cursor.js";
+import type { EventProducer, EventSnapshot, LiveEditEvent } from "./types.js";
+export type SnapshotReads = {
+    /**
+     * Lowest sequence this producer's stream still holds, or undefined when the
+     * stream is empty. This is the retention boundary a stale cursor fell off.
+     */
+    firstRetainedSequence(producer: EventProducer): Promise<number | undefined>;
+    /** Strictly-after-sequence read, done by the store rather than by filtering. */
+    readAfter(input: {
+        afterSequence: number;
+        limit?: number;
+        producer: EventProducer;
+    }): Promise<LiveEditEvent[]>;
+    /** Newest `count` events of one producer's stream, oldest first. */
+    readTail(input: {
+        count: number;
+        producer: EventProducer;
+    }): Promise<LiveEditEvent[]>;
+};
+/**
+ * Assembles a snapshot from a store's three reads.
+ *
+ * Shared rather than written twice so the memory and Redis stores cannot drift
+ * into disagreeing about what resuming means — the same reason both build
+ * their keys from one builder. Each store supplies only the reads; the cursor
+ * arithmetic and the staleness rule live here.
+ */
+export declare function buildSnapshot(input: {
+    cursor?: EventCursor;
+    limit?: number;
+}, reads: SnapshotReads): Promise<EventSnapshot>;