loopforge 3.0.0 → 3.6.0

package/dist/loop-store.js

@@ -1,39 +1,128 @@
-/** Typed per-loop persistence. Markdown and prompts are derived views. */
+/** 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.
+ */
 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";
 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 const LOOP_STORE_SCHEMA_VERSION = 1;
+const SEVERITY_MAP = {
+    sequence_gap: "recoverable",
+    sequence_duplicate: "recoverable",
+    invalid_json: "corrupted",
+    invalid_format: "corrupted",
+    sequence_cross_loop: "corrupted",
+    sequence_invalid: "corrupted",
+};
+/** v2.12: Typed corruption error carrying a severity class. Callers may
+ *  recover from `recoverable` errors (record and continue) but must surface
+ *  `corrupted` errors — the runtime never silently repairs storage. */
 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;
+    kind;
+    severity;
+    constructor(kind, message) {
+        super(message);
         this.name = "StorageCorruptionError";
+        this.kind = kind;
+        this.severity = SEVERITY_MAP[kind];
+    }
+    get recoverable() {
+        return this.severity === "recoverable";
+    }
+}
+/** Zero-dependency synchronous sleep (Atomics.wait on a shared slot). */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Filter a loop's flat entry view with the legacy VaultBackend query
+ *  options. Derived read-only view over the single durable truth (typed
+ *  session/round documents) — never a separate write path. Feedback
+ *  entries are excluded by default, mirroring the historical
+ *  queryEntries({ feedbackOnly }) semantics. */
+export function queryLoopEntries(store, loopId, opts) {
+    return store.listEntries(loopId, { sinceRound: opts?.sinceRound }).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) {
+            if (!taskId.startsWith(opts.prefix))
+                return false;
+            // Guard against ambiguous prefix matches: "loop:x:r1" must not
+            // match "loop:x:r10" or "loop:x:r11". Only check when the prefix
+            // itself ends with a digit (indicating a specific round number).
+            // Prefixes ending in non-digits (e.g. "loop:x:r") match any round
+            // and should NOT be filtered.
+            const lastChar = opts.prefix[opts.prefix.length - 1];
+            if (lastChar !== undefined && /^\d$/.test(lastChar)) {
+                const after = taskId[opts.prefix.length];
+                if (after !== undefined && /^\d$/.test(after))
+                    return false;
+            }
+        }
+        return true;
+    });
+}
+/** v2.12: Ordered round sequence for a loop. Throws StorageCorruptionError
+ *  on gaps (recoverable) or mixed-format corruption; returns [] for loops
+ *  with no rounds. Consumed by audit (sequenceComplete) and resume. */
+export function eventSequence(store, loopId) {
+    checkRoundSequence(store, loopId);
+    return store.listRoundSequences(loopId).map((doc) => doc.round);
+}
+/** v2.12: Validate that a loop's round documents form a contiguous sequence
+ *  from 1 to max. Legacy loops (no sequence stamps at all) are exempt.
+ *  Mixed stamping is allowed only monotonically: rounds below the first
+ *  stamped round are treated as legacy; once stamping begins it must not
+ *  stop. Throws StorageCorruptionError on violation. */
+export function checkRoundSequence(store, loopId) {
+    const docs = store.listRoundSequences(loopId);
+    const stamped = docs.filter((doc) => doc.sequence !== undefined);
+    if (stamped.length === 0)
+        return { complete: true, legacy: true };
+    const firstStamped = Math.min(...stamped.map((doc) => doc.round));
+    // Any round at or after the first stamped round must itself be stamped.
+    for (const doc of docs) {
+        if (doc.round >= firstStamped && doc.sequence === undefined) {
+            throw new StorageCorruptionError("sequence_invalid", `Loop ${loopId}: round ${doc.round} is missing its sequence stamp ` +
+                `while round ${firstStamped} is stamped (mixed format)`);
+        }
     }
+    const stampedRounds = stamped.map((doc) => doc.round);
+    const max = Math.max(...stampedRounds);
+    const present = new Set(docs.filter((doc) => doc.round >= firstStamped).map((doc) => doc.round));
+    for (let round = firstStamped; round <= max; round++) {
+        if (!present.has(round)) {
+            throw new StorageCorruptionError("sequence_gap", `Loop ${loopId}: round sequence gap at ${round} (max ${max})`);
+        }
+    }
+    // v2.14: rounds below the first stamped round are exempt ONLY for loops
+    // without a runtime session document — migration imports may legitimately
+    // start at any round, but migration never writes session documents.
+    // A stamped loop WITH a session always began at round 1 (write-time
+    // continuity), so missing rounds 1..N-1 mean deletion, not import.
+    if (firstStamped > 1 && store.readSession(loopId)) {
+        throw new StorageCorruptionError("sequence_gap", `Loop ${loopId}: rounds 1..${firstStamped - 1} are missing ` +
+            `(first stamped round is ${firstStamped})`);
+    }
+    return { complete: true, legacy: false };
 }
 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];
@@ -41,19 +130,22 @@ function loopIdFromEntry(entry) {
     return round?.[1] ?? null;
 }
 function roundFromEntry(entry) {
-    const round = entry.loop_lineage?.round;
-    if (typeof round === "number" && Number.isInteger(round))
-        return round;
+    const data = entry.loop_lineage;
+    if (data && typeof data.round === "number" && Number.isInteger(data.round)) {
+        return data.round;
+    }
     const match = String(entry.task_id ?? "").match(/:r(\d+)(?::|$)/);
     return match ? Number(match[1]) : null;
 }
-function isEvent(value) {
-    return isRecord(value) && value.format === LOOP_EVENT_FORMAT;
+function promptFromSnapshot(snapshot) {
+    return snapshot?.promptArtifact;
 }
 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++;
@@ -65,64 +157,57 @@ export class FileLoopStore {
             }
         }
         mkdirSync(this.root, { recursive: true });
-        const lock = join(this.root, ".store.lock");
-        const owner = join(lock, "owner.json");
+        const lockPath = join(this.root, ".store.lock");
+        const ownerPath = join(lockPath, "owner.json");
         const token = randomUUID();
         const deadline = Date.now() + 1000;
-        let spinCount = 0;
         for (;;) {
             try {
-                mkdirSync(lock);
-                writeFileSync(owner, JSON.stringify({ token, pid: process.pid }));
+                mkdirSync(lockPath);
+                writeFileSync(ownerPath, JSON.stringify({ token, pid: process.pid, createdAt: Date.now() }));
                 break;
             }
             catch {
                 let stale = false;
+                let age = 0;
                 try {
-                    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);
-                            }
-                    }
+                    age = Date.now() - statSync(lockPath).mtimeMs;
                 }
                 catch {
-                    // 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;
+                    age = 0;
+                }
+                let owner = null;
+                try {
+                    owner = JSON.parse(readFileSync(ownerPath, "utf8"));
+                }
+                catch {
+                    // v2.14: a crash between mkdir(lock) and write(owner.json) leaves
+                    // a lock directory without an owner. That window is microseconds,
+                    // so after a short grace the lock is provably stale — previously
+                    // this state caused a permanent lock until manual deletion.
+                    stale = age > 500;
+                }
+                if (!stale && owner && age > 5000 && typeof owner.pid === "number") {
                     try {
-                        age = Date.now() - statSync(lock).mtimeMs;
+                        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
                     }
-                    catch { /* lock vanished; next spin retries */ }
-                    if (age > 5000)
-                        stale = true;
                 }
                 if (stale) {
                     try {
-                        rmSync(lock, { recursive: true });
+                        rmSync(lockPath, { 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;
@@ -132,205 +217,263 @@ export class FileLoopStore {
         finally {
             this.lockDepth = 0;
             try {
-                const current = JSON.parse(readFileSync(owner, "utf8"));
-                if (current.token === token)
-                    rmSync(lock, { recursive: true });
+                const owner = JSON.parse(readFileSync(ownerPath, "utf8"));
+                if (owner.token === token)
+                    rmSync(lockPath, { recursive: true });
             }
-            catch { /* never remove another owner's lock */ }
+            catch { /* never delete an unowned lock */ }
         }
     }
     listLoopIds() {
-        const root = join(this.root, "loops");
-        if (!existsSync(root))
+        const loops = join(this.root, "loops");
+        if (!existsSync(loops))
             return [];
-        const ids = [];
-        for (const name of readdirSync(root)) {
-            const metadataPath = join(root, name, "metadata.json");
-            const metadata = this.readJson(metadataPath);
-            if (metadata === null)
+        const result = [];
+        for (const name of readdirSync(loops)) {
+            const dir = join(loops, name);
+            const metadata = this.readJson(join(dir, "metadata.json"));
+            if (isRecord(metadata) && typeof metadata.loopId === "string") {
+                result.push(metadata.loopId);
                 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);
+            // v2.14: orphaned loop dirs (sessions written before metadata
+            // stamping) recover their loopId from the session document itself.
+            const session = this.readJson(join(dir, "session.json"));
+            if (isRecord(session) && typeof session.loopId === "string") {
+                result.push(session.loopId);
+            }
         }
-        return ids.sort();
+        return result.sort();
     }
     readSession(loopId) {
         validateLoopId(loopId);
-        const path = join(this.loopDir(loopId), "session.json");
-        const value = this.readJson(path);
+        const value = this.readJson(join(this.loopDir(loopId), "session.json"));
+        // readJson returns null only for a missing file; an existing document
+        // with an unexpected shape is structural corruption, never silently
+        // treated as "missing" (which would let a later write overwrite it).
         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);
+        if (!isRecord(value) || value.schemaVersion !== LOOP_STORE_SCHEMA_VERSION ||
+            value.loopId !== loopId || !isRecord(value.entry)) {
+            throw new StorageCorruptionError("invalid_format", `Loop ${loopId}: session.json has an unexpected document shape`);
         }
         return value;
     }
     writeSession(loopId, document) {
         validateLoopId(loopId);
-        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 });
+        const dir = this.loopDir(loopId);
+        // v2.14: stamp metadata alongside the session document — a session with
+        // no committed rounds yet (created, then crashed before round 1) must
+        // still be discoverable via listLoopIds / auto-resume.
+        this.atomicWrite(join(dir, "metadata.json"), {
+            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
+            loopId,
+        });
+        this.atomicWrite(join(dir, "session.json"), document);
     }
     readRound(loopId, round) {
         validateLoopId(loopId);
         if (!Number.isInteger(round) || round < 1)
             return null;
-        const path = join(this.loopDir(loopId), "rounds", `${round}.json`);
-        const value = this.readJson(path);
+        const value = this.readJson(join(this.loopDir(loopId), "rounds", `${round}.json`));
+        // readJson returns null only for a missing file; an existing document
+        // with an unexpected shape is structural corruption — surfacing it
+        // (rather than returning null) prevents silent overwrite by writeEntry.
         if (value === null)
             return null;
-        if (!isRecord(value) || value.format !== LOOP_STORE_FORMAT || value.loopId !== loopId || value.round !== round) {
-            throw new StorageCorruptionError("invalid_format", path, loopId);
+        if (!isRecord(value) || value.schemaVersion !== LOOP_STORE_SCHEMA_VERSION ||
+            value.loopId !== loopId || value.round !== round) {
+            throw new StorageCorruptionError("invalid_format", `Loop ${loopId}: round ${round} document has an unexpected shape`);
         }
-        const tx = parseRoundTransactionSnapshot(value.transaction);
-        if (value.transaction !== undefined && !tx) {
-            throw new StorageCorruptionError("invalid_format", path, loopId);
+        // v2.12: a stamped document whose stamp disagrees with its filename is
+        // structural corruption, never silently repaired.
+        if (typeof value.sequence === "number" && value.sequence !== round) {
+            throw new StorageCorruptionError("sequence_invalid", `Loop ${loopId}: round ${round} document carries sequence ${value.sequence}`);
         }
-        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);
-            }
+        const events = Array.isArray(value.events)
+            ? value.events.filter(isRecord)
+            : [];
+        const transaction = parseRoundTransactionSnapshot(value.transaction);
+        return {
+            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
+            loopId,
+            round,
+            sequence: typeof value.sequence === "number" ? value.sequence : undefined,
+            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,
+        };
+    }
+    listRoundSequences(loopId) {
+        validateLoopId(loopId);
+        const roundsDir = join(this.loopDir(loopId), "rounds");
+        if (!existsSync(roundsDir))
+            return [];
+        const result = [];
+        for (const file of readdirSync(roundsDir).filter((name) => /^\d+\.json$/.test(name))) {
+            const round = Number(file.slice(0, -5));
+            const value = this.readJson(join(roundsDir, file));
+            if (!isRecord(value) || value.loopId !== loopId || value.round !== round)
+                continue;
+            result.push({
+                round,
+                sequence: typeof value.sequence === "number" ? value.sequence : undefined,
+            });
         }
-        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 : [] };
+        return result.sort((a, b) => a.round - b.round);
     }
-    listEntries(loopId) {
+    listEntries(loopId, opts) {
+        const ids = loopId ? [loopId] : this.listLoopIds();
         const result = [];
-        for (const id of loopId ? [loopId] : this.listLoopIds()) {
+        for (const id of ids) {
             const session = this.readSession(id);
             if (session)
                 result.push(session.entry);
-            const dir = join(this.loopDir(id), "rounds");
-            if (!existsSync(dir))
+            const roundsDir = join(this.loopDir(id), "rounds");
+            if (!existsSync(roundsDir))
                 continue;
-            for (const file of readdirSync(dir).filter((name) => /^\d+\.json$/.test(name))) {
-                const round = this.readRound(id, Number(file.slice(0, -5)));
-                if (!round)
+            // Numeric sort — readdirSync order is filesystem-dependent and must
+            // not leak into the flat entry view (rounds 1, 10, 2 … would be).
+            for (const file of readdirSync(roundsDir)
+                .filter((name) => /^\d+\.json$/.test(name))
+                .sort((a, b) => Number(a.slice(0, -5)) - Number(b.slice(0, -5)))) {
+                const round = Number(file.slice(0, -5));
+                // v3.0.1: incremental reads skip older round documents entirely —
+                // this is what bounds per-compile I/O in long loops.
+                if (opts?.sinceRound !== undefined && round < opts.sinceRound)
                     continue;
-                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);
+                const doc = this.readRound(id, round);
+                if (!doc)
+                    continue;
+                if (doc.lineage) {
+                    result.push({
+                        ...doc.lineage,
+                        full_prompt: doc.promptArtifact?.renderedPrompt ?? doc.lineage.full_prompt,
+                    });
+                }
+                if (doc.feedback)
+                    result.push(doc.feedback);
+                result.push(...doc.events);
             }
         }
         return result;
     }
-    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);
-            }
-            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);
+    appendEntry(entry) {
+        this.withLock(() => this.writeEntry(entry));
+    }
+    appendEntries(entries) {
+        return this.withLock(() => {
+            for (const entry of entries)
+                this.writeEntry(entry);
+            return entries.length;
+        });
+    }
+    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, { allowGap: true });
+                imported++;
             }
-            return sa - sb;
+            this.atomicWrite(marker, {
+                schemaVersion: LOOP_STORE_SCHEMA_VERSION,
+                source,
+                imported,
+                skipped,
+                migratedAt: new Date().toISOString(),
+            });
         });
-        this.assertSequence(entries, loopId);
-        return entries;
+        return { source, imported, skipped, alreadyMigrated: false };
     }
-    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);
+    writeEntry(entry, opts) {
+        const loopId = loopIdFromEntry(entry);
         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);
-        // 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 });
+        this.atomicWrite(join(dir, "metadata.json"), {
+            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
+            loopId,
+        });
         if (entry.task_type === "session_state" || entry.task_id === `loop:${loopId}:session`) {
-            this.atomicWrite(join(dir, "session.json"), { format: LOOP_STORE_FORMAT, loopId, updatedAt: now, entry });
+            this.atomicWrite(join(dir, "session.json"), {
+                schemaVersion: LOOP_STORE_SCHEMA_VERSION,
+                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) ?? { format: LOOP_STORE_FORMAT, loopId, round, updatedAt: now, events: [] };
+        // v2.12: monotonic write-time check — a stamped loop may not skip its
+        // predecessor. Legacy imports (allowGap) bypass this; the load-time
+        // scan in checkRoundSequence remains the backstop.
+        if (!opts?.allowGap && round > 1) {
+            const previous = this.readRound(loopId, round - 1);
+            if (!previous && this.listRoundSequences(loopId).some((doc) => doc.sequence !== undefined)) {
+                throw new StorageCorruptionError("sequence_gap", `Loop ${loopId}: cannot write round ${round}; round ${round - 1} is missing`);
+            }
+        }
+        const current = this.readRound(loopId, round) ?? {
+            schemaVersion: LOOP_STORE_SCHEMA_VERSION,
+            loopId,
+            round,
+            sequence: round,
+            updatedAt: now,
+            events: [],
+        };
+        if (current.sequence === undefined)
+            current.sequence = round;
         const taskId = String(entry.task_id ?? "");
-        if (taskId.endsWith(":event"))
-            current.roundEvent = entry;
-        else if (entry.task_type === "loop_lineage" || taskId === `loop:${loopId}:r${round}`)
+        if (taskId.endsWith(":feedback"))
+            current.feedback = 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 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;
+        }
+        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);
         }
         current.updatedAt = now;
         this.atomicWrite(join(dir, "rounds", `${round}.json`), current);
     }
-    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) {
+        const hash = createHash("sha256").update(loopId).digest("hex");
+        return join(this.root, "loops", hash);
     }
-    loopDir(loopId) { return join(this.root, "loops", createHash("sha256").update(loopId).digest("hex")); }
+    /** Read a JSON document, distinguishing missing from corrupt.
+     *  ENOENT → null (missing); parse failure → StorageCorruptionError
+     *  (corrupted) — the runtime never silently repairs storage. */
     readJson(path) {
         try {
             return JSON.parse(readFileSync(path, "utf8"));
@@ -338,26 +481,30 @@ export class FileLoopStore {
         catch (error) {
             if (error.code === "ENOENT")
                 return null;
-            throw new StorageCorruptionError("invalid_json", path, undefined, undefined, `Invalid JSON in ${path}`);
+            throw new StorageCorruptionError("invalid_json", `Corrupt JSON at ${path}: ${error.message}`);
         }
     }
-    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);
+    atomicWrite(path, value) {
+        mkdirSync(dirname(path), { recursive: true });
+        const writeOnce = () => {
+            const temporary = `${path}.tmp.${randomUUID().slice(0, 8)}`;
+            writeFileSync(temporary, JSON.stringify(value, null, 2), "utf8");
+            renameSync(temporary, path);
+        };
+        // v2.12: transient I/O failures (Windows rename EPERM/EACCES) are
+        // retried once after a short backoff; a second failure bubbles.
+        try {
+            writeOnce();
+        }
+        catch (first) {
+            sleepSync(500);
+            try {
+                writeOnce();
             }
-            seen.add(sequence);
-            if (sequence !== index + 1) {
-                throw new StorageCorruptionError("sequence_gap", this.loopDir(loopId), loopId, sequence);
+            catch (second) {
+                throw second;
             }
         }
     }
-    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