opencode-graphiti 0.0.0-development

package/script/src/services/redis-events.d.ts

@@ -0,0 +1,46 @@
+import type { ClaimedDrainBatch, DrainQueueEntry, SessionEvent } from "../types/index.js";
+import type { RedisClient } from "./redis-client.js";
+export declare const sessionEventsKey: (sessionId: string) => string;
+export declare const sessionSnapshotKey: (sessionId: string) => string;
+export declare const memoryCacheKey: (groupId: string) => string;
+export declare const memoryCacheMetaKey: (groupId: string) => string;
+export declare const drainPendingKey: (groupId: string) => string;
+export declare const drainCursorKey: (groupId: string) => string;
+export declare const drainDeadKey: (groupId: string) => string;
+export declare const drainRetryKey: (groupId: string, batchKey: string) => string;
+export declare const drainClaimKey: (groupId: string, claimToken: string) => string;
+export declare const drainClaimCheckpointKey: (groupId: string, claimToken: string) => string;
+export declare const drainClaimActiveKey: (groupId: string) => string;
+export declare const drainClaimLockKey: (groupId: string) => string;
+export declare const buildDrainEpisodeBody: (entry: DrainQueueEntry) => string;
+export declare const getDrainEpisodeBodyBytes: (entry: DrainQueueEntry) => number;
+export interface RedisEventsServiceOptions {
+    sessionTtlSeconds: number;
+    claimLockTtlSeconds?: number;
+}
+export declare class RedisEventsService {
+    private readonly redis;
+    private readonly options;
+    private warnedInvalidClaimLockTtl;
+    constructor(redis: RedisClient, options: RedisEventsServiceOptions);
+    getClaimLockTtlSeconds(): number;
+    recordEvent(sessionId: string, groupId: string, event: SessionEvent): Promise<number>;
+    private isDurableDrainMutationUnavailable;
+    private isRedisUnavailable;
+    getRecentSessionEvents(sessionId: string, limit?: number, chronological?: boolean): Promise<SessionEvent[]>;
+    touchSessionEvents(sessionId: string): Promise<void>;
+    recallSessionEvents(sessionId: string, query: string, options?: {
+        scanLimit?: number;
+        resultLimit?: number;
+    }): Promise<SessionEvent[]>;
+    getPendingCount(groupId: string): Promise<number>;
+    getPendingBatch(groupId: string, maxItems: number, maxBytes: number): Promise<ClaimedDrainBatch | null>;
+    refreshClaimLease(groupId: string, claimToken: string, ttlSeconds?: number): Promise<boolean>;
+    private cleanupStaleClaimIfConnected;
+    markBatchSuccess(groupId: string, claimToken: string, entries: DrainQueueEntry[]): Promise<void>;
+    moveBatchToDeadLetter(groupId: string, entries: DrainQueueEntry[]): Promise<void>;
+    releaseClaim(groupId: string, claimToken: string): Promise<void>;
+    markClaimEntrySuccess(groupId: string, claimToken: string, entry: DrainQueueEntry): Promise<void>;
+    recoverAbandonedClaim(groupId: string): Promise<boolean>;
+}
+//# sourceMappingURL=redis-events.d.ts.map

package/script/src/services/redis-events.d.ts.map

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

package/script/src/services/redis-events.js

@@ -0,0 +1,535 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisEventsService = exports.getDrainEpisodeBodyBytes = exports.buildDrainEpisodeBody = exports.drainClaimLockKey = exports.drainClaimActiveKey = exports.drainClaimCheckpointKey = exports.drainClaimKey = exports.drainRetryKey = exports.drainDeadKey = exports.drainCursorKey = exports.drainPendingKey = exports.memoryCacheMetaKey = exports.memoryCacheKey = exports.sessionSnapshotKey = exports.sessionEventsKey = void 0;
+const index_js_1 = require("../types/index.js");
+const logger_js_1 = require("./logger.js");
+const render_utils_js_1 = require("./render-utils.js");
+const SESSION_EVENT_LIMIT = 40;
+const SESSION_RECALL_SCAN_LIMIT = 120;
+const SESSION_RECALL_RESULT_LIMIT = 12;
+const DRAIN_TTL_SECONDS = 7 * 24 * 60 * 60;
+const DEAD_LETTER_TTL_SECONDS = 30 * 24 * 60 * 60;
+const CLAIM_LOCK_TTL_SECONDS = 60;
+const RECALL_ELIGIBLE_CATEGORIES = new Set([
+    "task.create",
+    "task.update",
+    "task.complete",
+    "decision",
+    "preference",
+    "rule.load",
+    "file.read",
+    "file.write",
+    "file.edit",
+    "file.search",
+    "error",
+    "git.activity",
+    "subagent.start",
+    "subagent.finish",
+    "intent",
+]);
+const RECALL_STOP_WORDS = new Set([
+    "about",
+    "after",
+    "again",
+    "always",
+    "been",
+    "before",
+    "between",
+    "could",
+    "from",
+    "have",
+    "into",
+    "keep",
+    "more",
+    "please",
+    "should",
+    "that",
+    "the",
+    "their",
+    "them",
+    "there",
+    "these",
+    "this",
+    "those",
+    "with",
+    "without",
+]);
+const sessionEventsKey = (sessionId) => `session:${sessionId}:events`;
+exports.sessionEventsKey = sessionEventsKey;
+const sessionSnapshotKey = (sessionId) => `session:${sessionId}:snapshot`;
+exports.sessionSnapshotKey = sessionSnapshotKey;
+const memoryCacheKey = (groupId) => `memory-cache:${groupId}`;
+exports.memoryCacheKey = memoryCacheKey;
+const memoryCacheMetaKey = (groupId) => `memory-cache:${groupId}:meta`;
+exports.memoryCacheMetaKey = memoryCacheMetaKey;
+const drainPendingKey = (groupId) => `drain:pending:${groupId}`;
+exports.drainPendingKey = drainPendingKey;
+const drainCursorKey = (groupId) => `drain:cursor:${groupId}`;
+exports.drainCursorKey = drainCursorKey;
+const drainDeadKey = (groupId) => `drain:dead:${groupId}`;
+exports.drainDeadKey = drainDeadKey;
+const drainRetryKey = (groupId, batchKey) => `drain:retry:${groupId}:${batchKey}`;
+exports.drainRetryKey = drainRetryKey;
+const drainClaimKey = (groupId, claimToken) => `drain:claim:${groupId}:${claimToken}`;
+exports.drainClaimKey = drainClaimKey;
+const drainClaimCheckpointKey = (groupId, claimToken) => `drain:claim-checkpoint:${groupId}:${claimToken}`;
+exports.drainClaimCheckpointKey = drainClaimCheckpointKey;
+const drainClaimActiveKey = (groupId) => `drain:claim-active:${groupId}`;
+exports.drainClaimActiveKey = drainClaimActiveKey;
+const drainClaimLockKey = (groupId) => `drain:claim-lock:${groupId}`;
+exports.drainClaimLockKey = drainClaimLockKey;
+const makeClaimToken = () => crypto.randomUUID();
+const textEncoder = new TextEncoder();
+const DURABLE_DRAIN_MUTATION_UNAVAILABLE = "Redis hot tier unavailable for durable drain-state mutation";
+const parseEntry = (raw) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+const parseSessionEvent = (raw) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+const buildDrainEpisodeBody = (entry) => {
+    const refs = entry.event.refs?.length
+        ? `\nRefs: ${entry.event.refs.join(", ")}`
+        : "";
+    const keywords = entry.event.keywords?.length
+        ? `\nKeywords: ${entry.event.keywords.join(", ")}`
+        : "";
+    return (0, render_utils_js_1.sanitizeMemoryInput)((0, render_utils_js_1.stripInjectedMemoryBlocks)([
+        `Category: ${entry.event.category}`,
+        `Role: ${entry.event.role}`,
+        `Summary: ${entry.event.summary}`,
+        entry.event.detail ? `Detail: ${entry.event.detail}` : "",
+        entry.event.continuityText
+            ? `Continuity: ${entry.event.continuityText}`
+            : (0, index_js_1.getSessionEventRecallText)(entry.event),
+        entry.event.body ? `Body: ${entry.event.body}` : "",
+        keywords,
+        refs,
+    ].filter(Boolean).join("\n")));
+};
+exports.buildDrainEpisodeBody = buildDrainEpisodeBody;
+const getDrainEpisodeBodyBytes = (entry) => textEncoder.encode((0, exports.buildDrainEpisodeBody)(entry)).length;
+exports.getDrainEpisodeBodyBytes = getDrainEpisodeBodyBytes;
+const sanitizeStoredValue = (value) => {
+    if (typeof value === "string") {
+        const sanitized = (0, render_utils_js_1.sanitizeMemoryInput)(value);
+        return sanitized || undefined;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeStoredValue(item)).filter((item) => item !== undefined);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => {
+            const sanitized = sanitizeStoredValue(entry);
+            return sanitized === undefined ? [] : [[key, sanitized]];
+        }));
+    }
+    return value;
+};
+const sanitizedStoredString = (value) => {
+    const sanitized = sanitizeStoredValue(value);
+    return typeof sanitized === "string" ? sanitized : undefined;
+};
+const sanitizedStoredStringArray = (value) => {
+    const sanitized = sanitizeStoredValue(value);
+    return Array.isArray(sanitized) ? sanitized : undefined;
+};
+const sanitizedStoredMetadata = (value) => {
+    const sanitized = sanitizeStoredValue(value);
+    return sanitized && typeof sanitized === "object" && !Array.isArray(sanitized)
+        ? sanitized
+        : undefined;
+};
+const sanitizeStoredEvent = (event) => ({
+    ...event,
+    summary: (0, render_utils_js_1.sanitizeMemoryInput)(event.summary),
+    body: sanitizedStoredString(event.body),
+    detail: sanitizedStoredString(event.detail),
+    continuityText: sanitizedStoredString(event.continuityText),
+    refs: sanitizedStoredStringArray(event.refs),
+    keywords: sanitizedStoredStringArray(event.keywords),
+    metadata: sanitizedStoredMetadata(event.metadata),
+});
+const tokenizeRecallQuery = (query) => {
+    const matches = query.toLowerCase().match(/[a-z0-9._/-]{3,}/g) ?? [];
+    return [...new Set(matches.filter((token) => !RECALL_STOP_WORDS.has(token)))];
+};
+const scoreSessionEventRecall = (event, query, tokens) => {
+    if (!RECALL_ELIGIBLE_CATEGORIES.has(event.category))
+        return 0;
+    const summary = event.summary.toLowerCase();
+    const continuity = (event.continuityText ?? "").toLowerCase();
+    const detail = (event.detail ?? "").toLowerCase();
+    const refs = (event.refs ?? []).join(" ").toLowerCase();
+    const keywords = (event.keywords ?? []).join(" ").toLowerCase();
+    const recallText = (0, index_js_1.getSessionEventRecallText)(event).toLowerCase();
+    let score = 0;
+    if (summary.includes(query))
+        score += 8;
+    else if (continuity.includes(query))
+        score += 7;
+    else if (detail.includes(query))
+        score += 5;
+    else if (recallText.includes(query))
+        score += 4;
+    for (const token of tokens) {
+        if (summary.includes(token))
+            score += 4;
+        if (continuity.includes(token))
+            score += 4;
+        if (detail.includes(token))
+            score += 3;
+        if (refs.includes(token))
+            score += 3;
+        if (keywords.includes(token))
+            score += 3;
+        if (recallText.includes(token))
+            score += 1;
+    }
+    return score;
+};
+class RedisEventsService {
+    constructor(redis, options) {
+        Object.defineProperty(this, "redis", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: redis
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+        Object.defineProperty(this, "warnedInvalidClaimLockTtl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+    }
+    getClaimLockTtlSeconds() {
+        const configured = this.options.claimLockTtlSeconds;
+        if (configured === undefined)
+            return CLAIM_LOCK_TTL_SECONDS;
+        if (!Number.isFinite(configured) || configured <= 0) {
+            if (!this.warnedInvalidClaimLockTtl) {
+                logger_js_1.logger.warn("Invalid drain claim TTL; falling back to default", {
+                    configuredClaimLockTtlSeconds: configured,
+                    effectiveClaimLockTtlSeconds: CLAIM_LOCK_TTL_SECONDS,
+                });
+                this.warnedInvalidClaimLockTtl = true;
+            }
+            return CLAIM_LOCK_TTL_SECONDS;
+        }
+        const normalized = Math.max(1, Math.ceil(configured));
+        if (normalized !== configured && !this.warnedInvalidClaimLockTtl) {
+            logger_js_1.logger.warn("Raised drain claim TTL to a sane minimum", {
+                configuredClaimLockTtlSeconds: configured,
+                effectiveClaimLockTtlSeconds: normalized,
+            });
+            this.warnedInvalidClaimLockTtl = true;
+        }
+        return normalized;
+    }
+    async recordEvent(sessionId, groupId, event) {
+        const sanitizedEvent = sanitizeStoredEvent(event);
+        const queueEntry = {
+            sessionId,
+            groupId,
+            event: sanitizedEvent,
+        };
+        await this.redis.prependToList((0, exports.sessionEventsKey)(sessionId), JSON.stringify(sanitizedEvent), this.options.sessionTtlSeconds);
+        try {
+            return await this.redis.prependToList((0, exports.drainPendingKey)(groupId), JSON.stringify(queueEntry), DRAIN_TTL_SECONDS);
+        }
+        catch (error) {
+            if (!this.isDurableDrainMutationUnavailable(error)) {
+                throw error;
+            }
+            logger_js_1.logger.warn("Durable drain queue unavailable; skipping enqueue", {
+                groupId,
+                sessionId,
+                eventId: sanitizedEvent.id,
+                category: sanitizedEvent.category,
+            });
+            return 0;
+        }
+    }
+    isDurableDrainMutationUnavailable(error) {
+        return error instanceof Error &&
+            error.message === DURABLE_DRAIN_MUTATION_UNAVAILABLE;
+    }
+    isRedisUnavailable(error) {
+        return error instanceof Error &&
+            (error.message === DURABLE_DRAIN_MUTATION_UNAVAILABLE ||
+                error.message.includes("redis unavailable"));
+    }
+    async getRecentSessionEvents(sessionId, limit = SESSION_EVENT_LIMIT, chronological = true) {
+        const raw = await this.redis.getRecentList((0, exports.sessionEventsKey)(sessionId), limit);
+        const events = raw.flatMap((item) => {
+            try {
+                return [JSON.parse(item)];
+            }
+            catch {
+                return [];
+            }
+        });
+        return chronological ? [...events].reverse() : events;
+    }
+    async touchSessionEvents(sessionId) {
+        await this.redis.touch((0, exports.sessionEventsKey)(sessionId), this.options.sessionTtlSeconds);
+    }
+    async recallSessionEvents(sessionId, query, options = {}) {
+        const normalizedQuery = query.trim().toLowerCase();
+        if (!normalizedQuery)
+            return [];
+        const tokens = tokenizeRecallQuery(normalizedQuery);
+        if (tokens.length === 0 && normalizedQuery.length < 3)
+            return [];
+        const raw = await this.redis.getListRange((0, exports.sessionEventsKey)(sessionId), 0, Math.max((options.scanLimit ?? SESSION_RECALL_SCAN_LIMIT) - 1, 0));
+        return raw
+            .flatMap((item) => {
+            const event = parseSessionEvent(item);
+            if (!event)
+                return [];
+            const score = scoreSessionEventRecall(event, normalizedQuery, tokens);
+            return score > 0 ? [{ event, score }] : [];
+        })
+            .sort((left, right) => {
+            if (right.score !== left.score)
+                return right.score - left.score;
+            if (right.event.ts !== left.event.ts) {
+                return right.event.ts - left.event.ts;
+            }
+            return left.event.id.localeCompare(right.event.id);
+        })
+            .slice(0, options.resultLimit ?? SESSION_RECALL_RESULT_LIMIT)
+            .map(({ event }) => event);
+    }
+    async getPendingCount(groupId) {
+        return await this.redis.getListLength((0, exports.drainPendingKey)(groupId));
+    }
+    async getPendingBatch(groupId, maxItems, maxBytes) {
+        if (maxItems <= 0)
+            return null;
+        await this.recoverAbandonedClaim(groupId);
+        const pendingKey = (0, exports.drainPendingKey)(groupId);
+        if (await this.redis.getListLength(pendingKey) === 0)
+            return null;
+        const claimToken = makeClaimToken();
+        const claimKey = (0, exports.drainClaimKey)(groupId, claimToken);
+        const checkpointKey = (0, exports.drainClaimCheckpointKey)(groupId, claimToken);
+        const lockAcquired = await this.redis.setStringIfAbsent((0, exports.drainClaimLockKey)(groupId), claimToken, this.getClaimLockTtlSeconds());
+        if (!lockAcquired)
+            return null;
+        const selected = [];
+        let totalBytes = 0;
+        try {
+            await this.redis.setString((0, exports.drainClaimActiveKey)(groupId), claimToken, DRAIN_TTL_SECONDS);
+            while (selected.length < maxItems) {
+                const raw = await this.redis.moveListItem(pendingKey, claimKey, "RIGHT", "RIGHT");
+                if (!raw)
+                    break;
+                await this.redis.touch(claimKey, DRAIN_TTL_SECONDS);
+                const entry = parseEntry(raw);
+                if (!entry) {
+                    await this.redis.moveListItem(claimKey, (0, exports.drainDeadKey)(groupId), "RIGHT", "RIGHT");
+                    await this.redis.touch((0, exports.drainDeadKey)(groupId), DEAD_LETTER_TTL_SECONDS);
+                    logger_js_1.logger.warn("Dead-lettered malformed claimed drain payload", {
+                        groupId,
+                        claimToken,
+                        raw,
+                    });
+                    continue;
+                }
+                const bytes = (0, exports.getDrainEpisodeBodyBytes)(entry);
+                if (bytes > maxBytes) {
+                    await this.redis.moveListItem(claimKey, (0, exports.drainDeadKey)(groupId), "RIGHT", "RIGHT");
+                    await this.redis.touch((0, exports.drainDeadKey)(groupId), DEAD_LETTER_TTL_SECONDS);
+                    logger_js_1.logger.warn("Dead-lettered oversized claimed drain payload", {
+                        groupId,
+                        claimToken,
+                        eventId: entry.event.id,
+                        eventBytes: bytes,
+                        batchMaxBytes: maxBytes,
+                    });
+                    continue;
+                }
+                if (selected.length > 0 && totalBytes + bytes > maxBytes) {
+                    await this.redis.moveListItem(claimKey, pendingKey, "RIGHT", "RIGHT");
+                    break;
+                }
+                selected.push(entry);
+                totalBytes += bytes;
+            }
+            if (selected.length === 0) {
+                await this.redis.deleteKey(claimKey);
+                await this.redis.deleteKey(checkpointKey);
+                await this.redis.deleteKeyIfValue((0, exports.drainClaimActiveKey)(groupId), claimToken);
+                await this.redis.deleteKeyIfValue((0, exports.drainClaimLockKey)(groupId), claimToken);
+                return null;
+            }
+            return {
+                claimToken,
+                claimKey,
+                lockTtlSeconds: this.getClaimLockTtlSeconds(),
+                entries: selected,
+            };
+        }
+        catch (err) {
+            await this.releaseClaim(groupId, claimToken);
+            throw err;
+        }
+    }
+    async refreshClaimLease(groupId, claimToken, ttlSeconds = this.getClaimLockTtlSeconds()) {
+        try {
+            const lockRefreshed = await this.redis.compareAndTouch((0, exports.drainClaimLockKey)(groupId), claimToken, ttlSeconds);
+            if (!lockRefreshed) {
+                return false;
+            }
+            const activeRefreshed = await this.redis.compareAndTouch((0, exports.drainClaimActiveKey)(groupId), claimToken, DRAIN_TTL_SECONDS);
+            if (!activeRefreshed) {
+                return false;
+            }
+            await this.redis.touch((0, exports.drainClaimKey)(groupId, claimToken), DRAIN_TTL_SECONDS);
+            return true;
+        }
+        catch (error) {
+            if (!this.isRedisUnavailable(error))
+                throw error;
+            return false;
+        }
+    }
+    async cleanupStaleClaimIfConnected(groupId, claimToken) {
+        if (!this.redis.isConnected())
+            return false;
+        const activeKey = (0, exports.drainClaimActiveKey)(groupId);
+        const lockKey = (0, exports.drainClaimLockKey)(groupId);
+        const claimKey = (0, exports.drainClaimKey)(groupId, claimToken);
+        const checkpointKey = (0, exports.drainClaimCheckpointKey)(groupId, claimToken);
+        let activeToken;
+        let lockToken;
+        let claimLength;
+        let checkpointLength;
+        try {
+            [activeToken, lockToken, claimLength, checkpointLength] = await Promise
+                .all([
+                this.redis.getString(activeKey),
+                this.redis.getString(lockKey),
+                this.redis.getListLength(claimKey),
+                this.redis.getListLength(checkpointKey),
+            ]);
+        }
+        catch (error) {
+            if (!this.isRedisUnavailable(error))
+                throw error;
+            return false;
+        }
+        if (claimLength === 0 && checkpointLength === 0)
+            return false;
+        const missingLockForSameActive = activeToken === claimToken &&
+            lockToken === null;
+        const missingActiveForSameLock = lockToken === claimToken &&
+            activeToken !== claimToken;
+        const orphanedPointers = activeToken === null && lockToken === null;
+        if (!missingLockForSameActive &&
+            !missingActiveForSameLock &&
+            !orphanedPointers) {
+            return false;
+        }
+        try {
+            await this.releaseClaim(groupId, claimToken);
+            return true;
+        }
+        catch (error) {
+            if (!this.isRedisUnavailable(error))
+                throw error;
+            return false;
+        }
+    }
+    async markBatchSuccess(groupId, claimToken, entries) {
+        if (entries.length === 0)
+            return;
+        await this.redis.deleteKey((0, exports.drainClaimKey)(groupId, claimToken));
+        await this.redis.deleteKey((0, exports.drainClaimCheckpointKey)(groupId, claimToken));
+        await this.redis.deleteKeyIfValue((0, exports.drainClaimActiveKey)(groupId), claimToken);
+        await this.redis.deleteKeyIfValue((0, exports.drainClaimLockKey)(groupId), claimToken);
+        await this.redis.setString((0, exports.drainCursorKey)(groupId), entries.at(-1)?.event.id ?? "", DRAIN_TTL_SECONDS);
+    }
+    async moveBatchToDeadLetter(groupId, entries) {
+        for (const entry of entries) {
+            await this.redis.appendToList((0, exports.drainDeadKey)(groupId), JSON.stringify(entry), DEAD_LETTER_TTL_SECONDS);
+        }
+    }
+    async releaseClaim(groupId, claimToken) {
+        const pendingKey = (0, exports.drainPendingKey)(groupId);
+        const claimKey = (0, exports.drainClaimKey)(groupId, claimToken);
+        const checkpointKey = (0, exports.drainClaimCheckpointKey)(groupId, claimToken);
+        while (true) {
+            const raw = await this.redis.moveListItem(claimKey, pendingKey, "RIGHT", "RIGHT");
+            if (!raw)
+                break;
+        }
+        await this.redis.deleteKey(claimKey);
+        await this.redis.deleteKey(checkpointKey);
+        await this.redis.deleteKeyIfValue((0, exports.drainClaimActiveKey)(groupId), claimToken);
+        await this.redis.deleteKeyIfValue((0, exports.drainClaimLockKey)(groupId), claimToken);
+    }
+    async markClaimEntrySuccess(groupId, claimToken, entry) {
+        const checkpointKey = (0, exports.drainClaimCheckpointKey)(groupId, claimToken);
+        const checkpointed = await this.redis.getListRange(checkpointKey, 0, -1);
+        if (checkpointed.some((raw) => parseEntry(raw)?.event.id === entry.event.id)) {
+            return;
+        }
+        const raw = await this.redis.moveListItem((0, exports.drainClaimKey)(groupId, claimToken), checkpointKey, "LEFT", "RIGHT");
+        if (!raw)
+            return;
+        const claimedEntry = parseEntry(raw);
+        if (claimedEntry?.event.id !== entry.event.id) {
+            throw new Error(`Drain claim checkpoint order mismatch for event ${entry.event.id}`);
+        }
+        await this.redis.touch(checkpointKey, DRAIN_TTL_SECONDS);
+        await this.redis.setString((0, exports.drainCursorKey)(groupId), entry.event.id, DRAIN_TTL_SECONDS);
+    }
+    async recoverAbandonedClaim(groupId) {
+        if (!this.redis.isConnected())
+            return false;
+        let activeToken;
+        let lockToken;
+        try {
+            [activeToken, lockToken] = await Promise.all([
+                this.redis.getString((0, exports.drainClaimActiveKey)(groupId)),
+                this.redis.getString((0, exports.drainClaimLockKey)(groupId)),
+            ]);
+        }
+        catch (error) {
+            if (!this.isRedisUnavailable(error))
+                throw error;
+            return false;
+        }
+        const claimTokens = [activeToken, lockToken].filter((token) => {
+            return typeof token === "string" && token.length > 0;
+        });
+        if (claimTokens.length === 0)
+            return false;
+        for (const claimToken of new Set(claimTokens)) {
+            if (await this.cleanupStaleClaimIfConnected(groupId, claimToken)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+exports.RedisEventsService = RedisEventsService;

package/script/src/services/redis-snapshot.d.ts

@@ -0,0 +1,16 @@
+import { type SessionEvent } from "../types/index.js";
+import type { RedisClient } from "./redis-client.js";
+export declare const buildSessionSnapshotXml: (sessionId: string, events: SessionEvent[]) => string;
+export interface RedisSnapshotServiceOptions {
+    ttlSeconds: number;
+}
+export declare class RedisSnapshotService {
+    private readonly redis;
+    private readonly options;
+    constructor(redis: RedisClient, options: RedisSnapshotServiceOptions);
+    getSnapshot(sessionId: string): Promise<string | null>;
+    saveSnapshot(sessionId: string, snapshot: string): Promise<void>;
+    touchSnapshot(sessionId: string): Promise<void>;
+    rebuildAndSave(sessionId: string, events: SessionEvent[]): Promise<string>;
+}
+//# sourceMappingURL=redis-snapshot.d.ts.map

package/script/src/services/redis-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-snapshot.d.ts","sourceRoot":"","sources":["../../../src/src/services/redis-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgCrD,eAAO,MAAM,uBAAuB,GAClC,WAAW,MAAM,EACjB,QAAQ,YAAY,EAAE,KACrB,MAiOF,CAAC;AAEF,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,2BAA2B;IAGjD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAItD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EAAE,GACrB,OAAO,CAAC,MAAM,CAAC;CAKnB"}