loopforge 3.0.0 → 3.2.1

package/dist/loop-store.d.ts

@@ -1,47 +1,129 @@
+/** 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 type { PromptArtifact } from "./protocol.js";
 import type { RoundTransactionSnapshot } from "./round-transaction.js";
-import type { VaultEntry } from "./vault-types.js";
-import { LOOP_STORE_FORMAT } from "./vault-format.js";
-export { LOOP_STORE_FORMAT } from "./vault-format.js";
+/** Loose per-loop entry shape shared by session documents, round documents,
+ *  and the flat list views (listEntries/queryLoopEntries). The single
+ *  durable truth is the typed per-loop documents; entries are what the
+ *  runtime writes into them. */
+export interface VaultEntry {
+    id?: string;
+    task_id?: string;
+    version_tag?: string;
+    is_active?: boolean;
+    timestamp?: string;
+    user_intent?: string;
+    task_type?: string;
+    /** @deprecated Use `success` field instead. Kept for reading old vault data. */
+    quality_score?: number;
+    success?: boolean;
+    skill_used?: string;
+    loop_id?: string;
+    loop_lineage?: Record<string, unknown>;
+    loop_objective?: Record<string, unknown> | null;
+    execution_feedback?: string;
+    task?: string;
+    output_summary?: string;
+    constraint_violations?: string[];
+    tags?: string[];
+    full_prompt?: string;
+    [key: string]: unknown;
+}
+export declare const LOOP_STORE_SCHEMA_VERSION: 1;
+/** v2.12: Storage corruption taxonomy. Only sequence gaps/duplicates are
+ *  recoverable (manual file deletion etc.); structural corruption is not. */
+export type StorageCorruptionKind = "invalid_json" | "invalid_format" | "sequence_gap" | "sequence_duplicate" | "sequence_cross_loop" | "sequence_invalid";
+export type StorageCorruptionSeverity = "recoverable" | "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 declare class StorageCorruptionError extends Error {
+    readonly code: "storage_corruption";
+    readonly kind: StorageCorruptionKind;
+    readonly severity: StorageCorruptionSeverity;
+    constructor(kind: StorageCorruptionKind, message: string);
+    get recoverable(): boolean;
+}
 export interface LoopSessionDocument {
-    format: typeof LOOP_STORE_FORMAT;
+    schemaVersion: typeof LOOP_STORE_SCHEMA_VERSION;
     loopId: string;
     updatedAt: string;
     entry: VaultEntry;
 }
 export interface LoopRoundDocument {
-    format: typeof LOOP_STORE_FORMAT;
+    schemaVersion: typeof LOOP_STORE_SCHEMA_VERSION;
     loopId: string;
     round: number;
+    /** v2.12: Monotonic round stamp distinguishing new-format loops (strict
+     *  continuity checked) from legacy loops (no stamp → exempt). */
+    sequence?: number;
     updatedAt: string;
     lineage?: VaultEntry;
-    roundEvent?: VaultEntry;
+    feedback?: VaultEntry;
     transaction?: RoundTransactionSnapshot;
     promptArtifact?: PromptArtifact;
     events: VaultEntry[];
 }
+export interface LoopStoreMigrationResult {
+    source: string;
+    imported: number;
+    skipped: number;
+    alreadyMigrated: boolean;
+}
 export interface LoopStore {
     withLock<T>(fn: () => T): T;
     listLoopIds(): string[];
-    listEntries(loopId?: string): VaultEntry[];
-    queryLoopEvents(loopId: string): VaultEntry[];
+    /** Flat entry view over the durable documents. v3.0.1: `sinceRound` skips
+     *  round documents older than the given round (the session document is
+     *  always included) — used by incremental compile hydration. */
+    listEntries(loopId?: string, opts?: {
+        sinceRound?: number;
+    }): VaultEntry[];
     appendEntry(entry: VaultEntry): void;
     appendEntries(entries: VaultEntry[]): number;
-    replaceEntries(entries: VaultEntry[]): void;
     readSession(loopId: string): LoopSessionDocument | null;
     writeSession(loopId: string, document: LoopSessionDocument): void;
     readRound(loopId: string, round: number): LoopRoundDocument | null;
+    /** v2.12: Per-round sequence stamps for continuity checking. Backends
+     *  without round documents return [] (legacy → exempt from checks). */
+    listRoundSequences(loopId: string): Array<{
+        round: number;
+        sequence?: number;
+    }>;
+    migrateLegacyVault(path?: string): LoopStoreMigrationResult;
 }
-export type StorageCorruptionKind = "invalid_json" | "invalid_format" | "sequence_gap" | "sequence_duplicate" | "sequence_cross_loop" | "sequence_invalid";
-export declare class StorageCorruptionError extends Error {
-    readonly kind: StorageCorruptionKind;
-    readonly path: string;
-    readonly loopId?: string | undefined;
-    readonly sequence?: number | undefined;
-    readonly code: "storage_corruption";
-    readonly recoverable: false;
-    constructor(kind: StorageCorruptionKind, path: string, loopId?: string | undefined, sequence?: number | undefined, message?: string);
-}
+/** 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 declare function queryLoopEntries(store: LoopStore, loopId: string, opts?: {
+    prefix?: string;
+    feedbackOnly?: boolean;
+    /** v3.0.1: only entries from round documents >= this round. Passed
+     *  through to listEntries so incremental hydration skips old docs. */
+    sinceRound?: number;
+}): VaultEntry[];
+/** 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 declare function eventSequence(store: LoopStore, loopId: string): number[];
+/** 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 declare function checkRoundSequence(store: LoopStore, loopId: string): {
+    complete: boolean;
+    legacy: boolean;
+};
 export declare class FileLoopStore implements LoopStore {
     readonly root: string;
     private lockDepth;
@@ -51,16 +133,22 @@ export declare class FileLoopStore implements LoopStore {
     readSession(loopId: string): LoopSessionDocument | null;
     writeSession(loopId: string, document: LoopSessionDocument): void;
     readRound(loopId: string, round: number): LoopRoundDocument | null;
-    listEntries(loopId?: string): VaultEntry[];
-    queryLoopEvents(loopId: string): VaultEntry[];
+    listRoundSequences(loopId: string): Array<{
+        round: number;
+        sequence?: number;
+    }>;
+    listEntries(loopId?: string, opts?: {
+        sinceRound?: number;
+    }): VaultEntry[];
     appendEntry(entry: VaultEntry): void;
     appendEntries(entries: VaultEntry[]): number;
-    replaceEntries(entries: VaultEntry[]): void;
+    migrateLegacyVault(path?: string): LoopStoreMigrationResult;
     private writeEntry;
-    private withEventSequence;
     private loopDir;
+    /** Read a JSON document, distinguishing missing from corrupt.
+     *  ENOENT → null (missing); parse failure → StorageCorruptionError
+     *  (corrupted) — the runtime never silently repairs storage. */
     private readJson;
-    private assertSequence;
     private atomicWrite;
 }
 //# sourceMappingURL=loop-store.d.ts.map

package/dist/loop-store.d.ts.map

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