loopforge 2.7.0 → 3.0.0

package/dist/loop-store.js

@@ -1,27 +1,39 @@
-/** Typed per-loop persistence.
- *
- * Layout:
- *   .loopforge/loops/<sha256(loopId)>/session.json
- *   .loopforge/loops/<sha256(loopId)>/rounds/<round>.json
- *
- * Markdown state files are derived views. These JSON documents are the only
- * durable transaction truth.
- */
+/** Typed per-loop persistence. Markdown and prompts are derived views. */
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { parseRoundTransactionSnapshot } from "./round-transaction.js";
 import { validateLoopId } from "./policy.js";
-export const LOOP_STORE_SCHEMA_VERSION = 1;
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
+import { isRecord } from "./token-utils.js";
+import { LOOP_EVENT_FORMAT, LOOP_STORE_FORMAT } from "./vault-format.js";
+export { LOOP_STORE_FORMAT } from "./vault-format.js";
+/** Synchronous sleep for lock backoff. Atomics.wait on a SharedArrayBuffer
+ *  is a zero-dependency sleep that works on all supported platforms
+ *  (including Windows); an ordinary ArrayBuffer would throw a TypeError. */
+const BACKOFF_SLOT = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(BACKOFF_SLOT, 0, 0, ms);
+}
+export class StorageCorruptionError extends Error {
+    kind;
+    path;
+    loopId;
+    sequence;
+    code = "storage_corruption";
+    recoverable = false;
+    constructor(kind, path, loopId, sequence, message) {
+        super(message ?? `Corrupt LoopForge storage (${kind}) at ${path}`);
+        this.kind = kind;
+        this.path = path;
+        this.loopId = loopId;
+        this.sequence = sequence;
+        this.name = "StorageCorruptionError";
+    }
 }
 function loopIdFromEntry(entry) {
     if (typeof entry.loop_id === "string" && entry.loop_id)
         return entry.loop_id;
     const taskId = String(entry.task_id ?? "");
-    if (!taskId.startsWith("loop:"))
-        return null;
     const session = taskId.match(/^loop:(.+):session$/);
     if (session)
         return session[1];
@@ -29,22 +41,19 @@ function loopIdFromEntry(entry) {
     return round?.[1] ?? null;
 }
 function roundFromEntry(entry) {
-    const data = entry.loop_lineage;
-    if (data && typeof data.round === "number" && Number.isInteger(data.round)) {
-        return data.round;
-    }
+    const round = entry.loop_lineage?.round;
+    if (typeof round === "number" && Number.isInteger(round))
+        return round;
     const match = String(entry.task_id ?? "").match(/:r(\d+)(?::|$)/);
     return match ? Number(match[1]) : null;
 }
-function promptFromSnapshot(snapshot) {
-    return snapshot?.promptArtifact;
+function isEvent(value) {
+    return isRecord(value) && value.format === LOOP_EVENT_FORMAT;
 }
 export class FileLoopStore {
     root;
     lockDepth = 0;
-    constructor(root = ".loopforge") {
-        this.root = resolve(root);
-    }
+    constructor(root = ".loopforge") { this.root = resolve(root); }
     withLock(fn) {
         if (this.lockDepth > 0) {
             this.lockDepth++;
@@ -56,46 +65,64 @@ export class FileLoopStore {
             }
         }
         mkdirSync(this.root, { recursive: true });
-        const lockPath = join(this.root, ".store.lock");
-        const ownerPath = join(lockPath, "owner.json");
+        const lock = join(this.root, ".store.lock");
+        const owner = join(lock, "owner.json");
         const token = randomUUID();
         const deadline = Date.now() + 1000;
+        let spinCount = 0;
         for (;;) {
             try {
-                mkdirSync(lockPath);
-                writeFileSync(ownerPath, JSON.stringify({ token, pid: process.pid, createdAt: Date.now() }));
+                mkdirSync(lock);
+                writeFileSync(owner, JSON.stringify({ token, pid: process.pid }));
                 break;
             }
             catch {
                 let stale = false;
                 try {
-                    const owner = JSON.parse(readFileSync(ownerPath, "utf8"));
-                    const age = Date.now() - statSync(lockPath).mtimeMs;
-                    if (age > 5000 && typeof owner.pid === "number") {
-                        try {
-                            process.kill(owner.pid, 0);
-                        }
-                        catch (error) {
-                            // On Windows, EPERM may be returned for dead cross-user
-                            // processes. Treat as stale when the lock is old regardless.
-                            const code = error.code;
-                            stale = code === "ESRCH"
-                                || (code === "EPERM" && age > 10_000); // Windows safety: EPERM + old lock → stale
-                        }
+                    const info = JSON.parse(readFileSync(owner, "utf8"));
+                    const age = Date.now() - statSync(lock).mtimeMs;
+                    if (age > 5000) {
+                        // Unreadable owner (orphaned lock) or a self-owned lock (crashed
+                        // during release) is reclaimable; otherwise probe the pid. The
+                        // 5s age gate keeps the mkdir→owner.json race window out of the
+                        // reclaim path.
+                        if (typeof info.pid !== "number" || info.pid === process.pid)
+                            stale = true;
+                        else
+                            try {
+                                process.kill(info.pid, 0);
+                            }
+                            catch (error) {
+                                const code = error.code;
+                                stale = code === "ESRCH" || (code === "EPERM" && age > 10000);
+                            }
                     }
                 }
                 catch {
-                    stale = false;
+                    // owner.json unreadable: an orphan left by a crash between mkdir
+                    // and owner.json. The age gate keeps the mkdir→owner.json race
+                    // window out of the reclaim path (that write completes in ms).
+                    let age = -1;
+                    try {
+                        age = Date.now() - statSync(lock).mtimeMs;
+                    }
+                    catch { /* lock vanished; next spin retries */ }
+                    if (age > 5000)
+                        stale = true;
                 }
                 if (stale) {
                     try {
-                        rmSync(lockPath, { recursive: true });
+                        rmSync(lock, { recursive: true });
                     }
                     catch { /* race */ }
                     continue;
                 }
                 if (Date.now() >= deadline)
                     throw new Error("LoopStore lock timeout (1000ms)");
+                // Exponential backoff (2→4→8→16→32ms) instead of a hot spin; the
+                // deadline above still bounds the total wait.
+                sleepSync(Math.min(2 << Math.min(spinCount, 4), 32));
+                spinCount++;
             }
         }
         this.lockDepth = 1;
@@ -105,338 +132,232 @@ export class FileLoopStore {
         finally {
             this.lockDepth = 0;
             try {
-                const owner = JSON.parse(readFileSync(ownerPath, "utf8"));
-                if (owner.token === token)
-                    rmSync(lockPath, { recursive: true });
+                const current = JSON.parse(readFileSync(owner, "utf8"));
+                if (current.token === token)
+                    rmSync(lock, { recursive: true });
             }
-            catch { /* never delete an unowned lock */ }
+            catch { /* never remove another owner's lock */ }
         }
     }
     listLoopIds() {
-        const loops = join(this.root, "loops");
-        if (!existsSync(loops))
+        const root = join(this.root, "loops");
+        if (!existsSync(root))
             return [];
-        const result = [];
-        for (const name of readdirSync(loops)) {
-            const metadata = this.readJson(join(loops, name, "metadata.json"));
-            if (isRecord(metadata) && typeof metadata.loopId === "string") {
-                result.push(metadata.loopId);
+        const ids = [];
+        for (const name of readdirSync(root)) {
+            const metadataPath = join(root, name, "metadata.json");
+            const metadata = this.readJson(metadataPath);
+            if (metadata === null)
+                continue;
+            if (!isRecord(metadata) || metadata.format !== LOOP_STORE_FORMAT ||
+                typeof metadata.loopId !== "string" || !metadata.loopId) {
+                throw new StorageCorruptionError("invalid_format", metadataPath);
             }
+            ids.push(metadata.loopId);
         }
-        return result.sort();
+        return ids.sort();
     }
     readSession(loopId) {
         validateLoopId(loopId);
-        const value = this.readJson(join(this.loopDir(loopId), "session.json"));
-        if (!isRecord(value) || value.schemaVersion !== LOOP_STORE_SCHEMA_VERSION ||
-            value.loopId !== loopId || !isRecord(value.entry))
+        const path = join(this.loopDir(loopId), "session.json");
+        const value = this.readJson(path);
+        if (value === null)
             return null;
+        if (!isRecord(value) || value.format !== LOOP_STORE_FORMAT || value.loopId !== loopId || !isEvent(value.entry)) {
+            throw new StorageCorruptionError("invalid_format", path, loopId);
+        }
+        if (!Number.isInteger(value.entry.event_sequence) || value.entry.event_sequence < 1) {
+            throw new StorageCorruptionError("sequence_invalid", path, loopId, value.entry.event_sequence);
+        }
         return value;
     }
     writeSession(loopId, document) {
         validateLoopId(loopId);
-        this.atomicWrite(join(this.loopDir(loopId), "session.json"), document);
+        const entry = this.withEventSequence(loopId, { format: LOOP_EVENT_FORMAT, ...document.entry });
+        this.atomicWrite(join(this.loopDir(loopId), "session.json"), { ...document, format: LOOP_STORE_FORMAT, entry });
     }
     readRound(loopId, round) {
         validateLoopId(loopId);
         if (!Number.isInteger(round) || round < 1)
             return null;
-        const value = this.readJson(join(this.loopDir(loopId), "rounds", `${round}.json`));
-        if (!isRecord(value) || value.schemaVersion !== LOOP_STORE_SCHEMA_VERSION ||
-            value.loopId !== loopId || value.round !== round)
+        const path = join(this.loopDir(loopId), "rounds", `${round}.json`);
+        const value = this.readJson(path);
+        if (value === null)
             return null;
-        const events = Array.isArray(value.events)
-            ? value.events.filter(isRecord)
-            : [];
-        const transaction = parseRoundTransactionSnapshot(value.transaction);
-        return {
-            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-            loopId,
-            round,
-            updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : "",
-            lineage: isRecord(value.lineage) ? value.lineage : undefined,
-            feedback: isRecord(value.feedback) ? value.feedback : undefined,
-            transaction: transaction ?? undefined,
-            promptArtifact: transaction?.promptArtifact,
-            events,
-        };
+        if (!isRecord(value) || value.format !== LOOP_STORE_FORMAT || value.loopId !== loopId || value.round !== round) {
+            throw new StorageCorruptionError("invalid_format", path, loopId);
+        }
+        const tx = parseRoundTransactionSnapshot(value.transaction);
+        if (value.transaction !== undefined && !tx) {
+            throw new StorageCorruptionError("invalid_format", path, loopId);
+        }
+        const invalidEvent = [value.lineage, value.roundEvent]
+            .filter((entry) => entry !== undefined && !isEvent(entry)).length > 0;
+        if (invalidEvent || (value.events !== undefined &&
+            (!Array.isArray(value.events) || value.events.some((entry) => !isEvent(entry))))) {
+            throw new StorageCorruptionError("invalid_format", path, loopId);
+        }
+        for (const event of [value.lineage, value.roundEvent, ...(Array.isArray(value.events) ? value.events : [])]) {
+            if (event !== undefined && (!Number.isInteger(event.event_sequence) || event.event_sequence < 1)) {
+                throw new StorageCorruptionError("sequence_invalid", path, loopId, event.event_sequence);
+            }
+        }
+        return { format: LOOP_STORE_FORMAT, loopId, round, updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : "", lineage: isEvent(value.lineage) ? value.lineage : undefined, roundEvent: isEvent(value.roundEvent) ? value.roundEvent : undefined, transaction: tx ?? undefined, promptArtifact: tx?.promptArtifact, events: Array.isArray(value.events) ? value.events : [] };
     }
     listEntries(loopId) {
-        const ids = loopId ? [loopId] : this.listLoopIds();
         const result = [];
-        for (const id of ids) {
+        for (const id of loopId ? [loopId] : this.listLoopIds()) {
             const session = this.readSession(id);
             if (session)
                 result.push(session.entry);
-            const roundsDir = join(this.loopDir(id), "rounds");
-            if (!existsSync(roundsDir))
+            const dir = join(this.loopDir(id), "rounds");
+            if (!existsSync(dir))
                 continue;
-            for (const file of readdirSync(roundsDir).filter((name) => /^\d+\.json$/.test(name))) {
+            for (const file of readdirSync(dir).filter((name) => /^\d+\.json$/.test(name))) {
                 const round = this.readRound(id, Number(file.slice(0, -5)));
                 if (!round)
                     continue;
-                if (round.lineage) {
-                    result.push({
-                        ...round.lineage,
-                        full_prompt: round.promptArtifact?.renderedPrompt ?? round.lineage.full_prompt,
-                    });
-                }
-                if (round.feedback)
-                    result.push(round.feedback);
+                if (round.lineage)
+                    result.push({ ...round.lineage, full_prompt: round.promptArtifact?.renderedPrompt ?? round.lineage.full_prompt });
+                if (round.roundEvent)
+                    result.push(round.roundEvent);
                 result.push(...round.events);
             }
         }
         return result;
     }
-    appendEntry(entry) {
-        this.withLock(() => this.writeEntry(entry));
-    }
-    appendEntries(entries) {
-        return this.withLock(() => {
-            for (const entry of entries)
-                this.writeEntry(entry);
-            return entries.length;
-        });
-    }
-    replaceEntries(entries) {
-        this.withLock(() => {
-            for (const entry of entries)
-                this.writeEntry(entry);
-        });
-    }
-    migrateLegacyVault(path = ".promptcraft/prompt_vault.json") {
-        const source = resolve(path);
-        const marker = join(this.root, "migrations", "promptcraft-v1.json");
-        if (existsSync(marker)) {
-            return { source, imported: 0, skipped: 0, alreadyMigrated: true };
-        }
-        let imported = 0;
-        let skipped = 0;
-        const raw = this.readJson(source);
-        const entries = isRecord(raw) && Array.isArray(raw.entries)
-            ? raw.entries.filter(isRecord)
-            : [];
-        this.withLock(() => {
-            const existing = new Set(this.listEntries().map((entry) => String(entry.task_id ?? "")));
-            for (const entry of entries) {
-                if (!loopIdFromEntry(entry) || existing.has(String(entry.task_id ?? ""))) {
-                    skipped++;
-                    continue;
-                }
-                this.writeEntry(entry);
-                imported++;
+    queryLoopEvents(loopId) {
+        const seen = new Set();
+        const entries = this.listEntries(loopId).filter((entry) => {
+            const derived = loopIdFromEntry(entry);
+            if (entry.loop_id !== undefined && entry.loop_id !== loopId) {
+                throw new StorageCorruptionError("sequence_cross_loop", this.loopDir(loopId), loopId);
             }
-            this.atomicWrite(marker, {
-                schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-                source,
-                imported,
-                skipped,
-                migratedAt: new Date().toISOString(),
-            });
+            if (derived !== loopId) {
+                throw new StorageCorruptionError("sequence_cross_loop", this.loopDir(loopId), loopId);
+            }
+            return true;
+        }).filter((entry) => {
+            const key = `${entry.task_id ?? entry.id ?? ""}:${entry.event_sequence ?? ""}`;
+            if (seen.has(key)) {
+                throw new StorageCorruptionError("sequence_duplicate", this.loopDir(loopId), loopId, entry.event_sequence);
+            }
+            seen.add(key);
+            return true;
+        }).sort((a, b) => {
+            const sa = a.event_sequence;
+            const sb = b.event_sequence;
+            if (!Number.isInteger(sa) || !Number.isInteger(sb) || sa < 1 || sb < 1) {
+                throw new StorageCorruptionError("sequence_invalid", this.loopDir(loopId), loopId);
+            }
+            return sa - sb;
         });
-        return { source, imported, skipped, alreadyMigrated: false };
+        this.assertSequence(entries, loopId);
+        return entries;
     }
-    writeEntry(entry) {
-        const loopId = loopIdFromEntry(entry);
+    appendEntry(entry) { this.withLock(() => this.writeEntry(entry)); }
+    appendEntries(entries) { return this.withLock(() => { for (const entry of entries)
+        this.writeEntry(entry); return entries.length; }); }
+    replaceEntries(entries) { this.withLock(() => { for (const entry of entries)
+        this.writeEntry(entry); }); }
+    writeEntry(input) {
+        const loopId = loopIdFromEntry(input);
         if (!loopId)
             throw new Error("LoopStore only accepts loop-scoped entries");
         validateLoopId(loopId);
+        if (input.loop_id !== undefined && input.loop_id !== loopId) {
+            throw new StorageCorruptionError("sequence_cross_loop", this.loopDir(loopId), loopId);
+        }
+        if (input.format !== undefined && input.format !== LOOP_EVENT_FORMAT)
+            throw new Error("LoopStore rejected an event with an unknown format");
+        const entry = this.withEventSequence(loopId, { format: LOOP_EVENT_FORMAT, ...input });
         const now = new Date().toISOString();
         const dir = this.loopDir(loopId);
-        this.atomicWrite(join(dir, "metadata.json"), {
-            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-            loopId,
-        });
+        // metadata.json holds only {format, loopId} and changes never: rewrite it
+        // only when missing (crash-consistent self-healing — a deleted metadata
+        // file is rebuilt on the next write, and listLoopIds recovers in turn).
+        const metadataPath = join(dir, "metadata.json");
+        if (!existsSync(metadataPath))
+            this.atomicWrite(metadataPath, { format: LOOP_STORE_FORMAT, loopId });
         if (entry.task_type === "session_state" || entry.task_id === `loop:${loopId}:session`) {
-            this.atomicWrite(join(dir, "session.json"), {
-                schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-                loopId,
-                updatedAt: now,
-                entry,
-            });
+            this.atomicWrite(join(dir, "session.json"), { format: LOOP_STORE_FORMAT, loopId, updatedAt: now, entry });
             return;
         }
         const round = roundFromEntry(entry);
         if (!round)
             throw new Error(`Loop entry has no round: ${entry.task_id ?? "unknown"}`);
-        const current = this.readRound(loopId, round) ?? {
-            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-            loopId,
-            round,
-            updatedAt: now,
-            events: [],
-        };
+        const current = this.readRound(loopId, round) ?? { format: LOOP_STORE_FORMAT, loopId, round, updatedAt: now, events: [] };
         const taskId = String(entry.task_id ?? "");
-        if (taskId.endsWith(":feedback"))
-            current.feedback = entry;
-        else if (entry.task_type === "loop_lineage" || taskId === `loop:${loopId}:r${round}`) {
+        if (taskId.endsWith(":event"))
+            current.roundEvent = entry;
+        else if (entry.task_type === "loop_lineage" || taskId === `loop:${loopId}:r${round}`)
             current.lineage = entry;
-        }
-        else {
-            current.events = [
-                ...current.events.filter((event) => event.task_id !== entry.task_id),
-                entry,
-            ];
-        }
-        const transactionRaw = current.feedback?.loop_lineage?.round_transaction ??
-            entry.loop_lineage?.round_transaction;
-        const transaction = parseRoundTransactionSnapshot(isRecord(transactionRaw) ? transactionRaw.snapshot : undefined);
-        if (transaction) {
-            current.transaction = transaction;
-            current.promptArtifact = promptFromSnapshot(transaction);
+        else
+            current.events = [...current.events.filter((event) => event.task_id !== entry.task_id), entry];
+        const raw = current.roundEvent?.loop_lineage?.round_transaction ?? entry.loop_lineage?.round_transaction;
+        const tx = parseRoundTransactionSnapshot(isRecord(raw) ? raw.snapshot : undefined);
+        if (tx) {
+            current.transaction = tx;
+            current.promptArtifact = tx.promptArtifact;
         }
         current.updatedAt = now;
         this.atomicWrite(join(dir, "rounds", `${round}.json`), current);
     }
-    loopDir(loopId) {
-        const hash = createHash("sha256").update(loopId).digest("hex");
-        return join(this.root, "loops", hash);
+    withEventSequence(loopId, entry) {
+        const existing = this.listEntries(loopId);
+        this.assertSequence(existing, loopId);
+        const prior = existing.find((candidate) => candidate.task_id === entry.task_id);
+        if (prior && Number.isInteger(prior.event_sequence)) {
+            if (entry.event_sequence === undefined)
+                return { ...entry, event_sequence: prior.event_sequence };
+            if (entry.event_sequence === prior.event_sequence)
+                return entry;
+            throw new StorageCorruptionError("sequence_invalid", this.loopDir(loopId), loopId, entry.event_sequence, "An existing event cannot change its event_sequence");
+        }
+        const used = new Set(existing.map((candidate) => candidate.event_sequence).filter((value) => typeof value === "number" && Number.isInteger(value) && value > 0));
+        const next = used.size ? Math.max(...used) + 1 : 1;
+        if (entry.event_sequence !== undefined) {
+            if (!Number.isInteger(entry.event_sequence) || entry.event_sequence < 1) {
+                throw new StorageCorruptionError("sequence_invalid", this.loopDir(loopId), loopId, entry.event_sequence);
+            }
+            if (used.has(entry.event_sequence)) {
+                throw new StorageCorruptionError("sequence_duplicate", this.loopDir(loopId), loopId, entry.event_sequence);
+            }
+            if (entry.event_sequence !== next) {
+                throw new StorageCorruptionError("sequence_gap", this.loopDir(loopId), loopId, entry.event_sequence);
+            }
+            return entry;
+        }
+        return { ...entry, event_sequence: next };
     }
+    loopDir(loopId) { return join(this.root, "loops", createHash("sha256").update(loopId).digest("hex")); }
     readJson(path) {
         try {
             return JSON.parse(readFileSync(path, "utf8"));
         }
-        catch {
-            return null;
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw new StorageCorruptionError("invalid_json", path, undefined, undefined, `Invalid JSON in ${path}`);
         }
     }
-    atomicWrite(path, value) {
-        mkdirSync(dirname(path), { recursive: true });
-        const temporary = `${path}.tmp.${randomUUID().slice(0, 8)}`;
-        writeFileSync(temporary, JSON.stringify(value, null, 2), "utf8");
-        renameSync(temporary, path);
-    }
-}
-/** @deprecated Use LoopStore directly.
- *
- *  Compatibility adapter so modules that still accept VaultBackend can
- *  operate on a LoopStore. Persistent truth is the typed per-loop
- *  documents; no Markdown lineage is written. */
-export class LoopStoreBackend {
-    store;
-    constructor(store = new FileLoopStore()) {
-        this.store = store;
-    }
-    withLock(fn) { return this.store.withLock(fn); }
-    queryEntries(opts) {
-        return this.store.listEntries().filter((entry) => {
-            const taskId = String(entry.task_id ?? "");
-            if (opts?.feedbackOnly && !taskId.endsWith(":feedback"))
-                return false;
-            if (!opts?.feedbackOnly && taskId.endsWith(":feedback"))
-                return false;
-            if (opts?.prefix && !taskId.startsWith(opts.prefix))
-                return false;
-            if (opts?.taskIdPattern && !taskId.includes(opts.taskIdPattern))
-                return false;
-            return true;
-        });
-    }
-    appendEntry(entry) { this.store.appendEntry(entry); }
-    appendEntries(entries) { return this.store.appendEntries(entries); }
-}
-/** Adapter that wraps a VaultBackend as a LoopStore for backward compat.
- *
- *  SessionManager uses this when a VaultBackend is provided directly so
- *  VaultSessionStateStore can operate on typed session documents while
- *  the underlying storage remains VaultBackend entries. */
-export class VaultBackendLoopStore {
-    backend;
-    constructor(backend) {
-        this.backend = backend;
-    }
-    withLock(fn) {
-        return typeof this.backend.withLock === "function"
-            ? this.backend.withLock(fn)
-            : fn();
-    }
-    listLoopIds() {
-        return [...new Set(this.backend.queryEntries()
-                .filter((e) => typeof e.loop_id === "string")
-                .map((e) => e.loop_id))].sort();
-    }
-    listEntries(loopId) {
-        if (loopId)
-            return this.backend.queryEntries({ prefix: `loop:${loopId}` });
-        return this.backend.queryEntries();
-    }
-    appendEntry(entry) { this.backend.appendEntry(entry); }
-    appendEntries(entries) { return this.backend.appendEntries(entries); }
-    replaceEntries(_entries) {
-        // Best-effort: not all VaultBackend implementations support bulk replace.
-        // The typed session path bypasses this method.
-    }
-    readSession(loopId) {
-        const entry = this.backend.queryEntries({ prefix: `loop:${loopId}:session` })
-            .find((e) => e.task_type === "session_state" && e.loop_id === loopId);
-        if (!entry)
-            return null;
-        return {
-            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-            loopId,
-            updatedAt: typeof entry.timestamp === "string"
-                ? entry.timestamp
-                : new Date().toISOString(),
-            entry,
-        };
-    }
-    writeSession(loopId, document) {
-        const entry = document.entry;
-        // Ensure the entry carries identifying fields expected by queryEntries.
-        entry.task_type = "session_state";
-        entry.loop_id = loopId;
-        entry.task_id = `loop:${loopId}:session`;
-        // Session state lives in the vault entries list. The backend may
-        // provide readVault/writeVault as optional compat methods; if not,
-        // we fall back to appendEntry (which may create duplicates, but
-        // VaultSessionStateStore.load returns the first match).
-        const be = this.backend;
-        if (typeof be.readVault === "function" &&
-            typeof be.writeVault === "function") {
-            // Call via .call(be) so methods that reference `this` (e.g.
-            // MemoryBackend.readVault) keep their receiver.
-            const data = be.readVault.call(be);
-            const entries = Array.isArray(data.entries)
-                ? data.entries
-                : [];
-            const filtered = entries.filter((item) => !(item.task_type === "session_state" && item.loop_id === loopId));
-            be.writeVault.call(be, { entries: [...filtered, entry] });
-            return;
-        }
-        this.backend.appendEntry(entry);
-    }
-    readRound(loopId, round) {
-        const prefix = `loop:${loopId}:r${round}:`;
-        const entries = this.backend.queryEntries({ prefix });
-        if (entries.length === 0)
-            return null;
-        // Separate lineage, feedback, and raw events — same structure as
-        // FileLoopStore.readRound so callers get consistent round documents
-        // regardless of backend.
-        const lineage = entries.find((e) => e.task_type === "loop_lineage" || e.task_id === `loop:${loopId}:r${round}`);
-        const feedback = entries.find((e) => String(e.task_id ?? "").endsWith(":feedback"));
-        const events = entries.filter((e) => e !== lineage && e !== feedback);
-        let transaction;
-        const transactionRaw = feedback?.loop_lineage?.round_transaction ??
-            lineage?.loop_lineage?.round_transaction;
-        const transactionParsed = parseRoundTransactionSnapshot(isRecord(transactionRaw) ? transactionRaw.snapshot : undefined);
-        if (transactionParsed) {
-            transaction = transactionParsed;
+    assertSequence(entries, loopId) {
+        const seen = new Set();
+        const sorted = [...entries].sort((a, b) => (a.event_sequence ?? 0) - (b.event_sequence ?? 0));
+        for (let index = 0; index < sorted.length; index++) {
+            const sequence = sorted[index].event_sequence;
+            if (!Number.isInteger(sequence) || sequence < 1) {
+                throw new StorageCorruptionError("sequence_invalid", this.loopDir(loopId), loopId, sequence);
+            }
+            if (seen.has(sequence)) {
+                throw new StorageCorruptionError("sequence_duplicate", this.loopDir(loopId), loopId, sequence);
+            }
+            seen.add(sequence);
+            if (sequence !== index + 1) {
+                throw new StorageCorruptionError("sequence_gap", this.loopDir(loopId), loopId, sequence);
+            }
         }
-        return {
-            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
-            loopId,
-            round,
-            updatedAt: entries[0].timestamp ?? new Date().toISOString(),
-            lineage: lineage,
-            feedback: feedback,
-            transaction,
-            promptArtifact: transaction?.promptArtifact,
-            events,
-        };
-    }
-    migrateLegacyVault(_path) {
-        return { source: _path ?? "vault", imported: 0, skipped: 0, alreadyMigrated: true };
     }
+    atomicWrite(path, value) { mkdirSync(dirname(path), { recursive: true }); const temporary = `${path}.tmp.${randomUUID().slice(0, 8)}`; writeFileSync(temporary, JSON.stringify(value, null, 2), "utf8"); renameSync(temporary, path); }
 }
 //# sourceMappingURL=loop-store.js.map