@earendil-works/pi-agent-core 0.84.3 → 0.85.0

package/dist/harness/session/jsonl/storage.d.ts

@@ -1,43 +1,41 @@
-import { type BranchBounds, type Entry, type EntryQuery, type ForkOptions, type LanePointer, type LaneRecord, type LogItem, type LogOptions, type NewRecord, type OperationStartedRecord, type ProvisionedEntry, type RecordQuery, type SessionStats, type SessionStorage } from "../types.ts";
-import type { JsonlSessionMetadata, JsonlSessionRepoFileSystem, JsonlV4Header } from "./types.ts";
-export declare class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata> {
-    private readonly fs;
-    private readonly metadata;
-    private readonly state;
-    private tail;
-    constructor(fs: JsonlSessionRepoFileSystem, metadata: JsonlSessionMetadata);
-    static create(fs: JsonlSessionRepoFileSystem, path: string, header: JsonlV4Header): Promise<JsonlSessionStorage>;
-    static load(fs: JsonlSessionRepoFileSystem, path: string): Promise<JsonlSessionStorage>;
-    fork(path: string, header: JsonlV4Header, options: ForkOptions): Promise<JsonlSessionStorage>;
-    drain(): Promise<void>;
-    getMetadata(): Promise<JsonlSessionMetadata>;
-    getLanes(): Promise<LanePointer[]>;
-    createLane(lane: string, at: string | null): Promise<void>;
-    moveLane(lane: string, to: string | null): Promise<void>;
-    appendEntry<TEntry extends Entry>(newEntry: ProvisionedEntry<TEntry>, lane: string): Promise<TEntry>;
-    appendRecord<TRecord extends LaneRecord>(newRecord: NewRecord<TRecord>): Promise<TRecord>;
-    getEntry(id: string): Promise<Entry | undefined>;
-    findEntries(query?: EntryQuery): Promise<Entry[]>;
-    findEntriesOnBranch(query: EntryQuery & BranchBounds & {
-        start: string;
-    }): Promise<Entry[]>;
-    findRecords<K extends LaneRecord["type"]>(query: RecordQuery & {
-        type: K;
-    }): Promise<Extract<LaneRecord, {
-        type: K;
-    }>[]>;
-    findRecords(query?: RecordQuery): Promise<LaneRecord[]>;
-    findOpenOperations(lane: string, options?: {
-        limit?: number;
-    }): Promise<OperationStartedRecord[]>;
-    getLog(options?: LogOptions): Promise<LogItem[]>;
-    getName(): Promise<string | undefined>;
-    setName(name: string | undefined): Promise<void>;
-    getLabel(id: string): Promise<string | undefined>;
-    setLabel(id: string, label: string | undefined): Promise<void>;
-    getStats(): Promise<SessionStats>;
-    private enqueue;
-    private appendMutation;
-    private applyMutation;
+import type { Context } from "../../context.ts";
+import { type ForkDestinationSnapshot, type ForkSourceSnapshot } from "../fork.ts";
+import type { CommitResult, Entry, EntryScan, EntryStructure, SessionStats, Storage, StorageBranchScan, UsageRow, UsageScan, Write } from "../types.ts";
+import type { ListElement, ListReadOptions, StoredValue, Value, ValueList } from "../values.ts";
+import { type JsonlStorageHeader, type JsonlStorageOptions } from "./types.ts";
+/** JSONL storage backed by an injected filesystem capability. */
+export declare class JsonlStorage implements Storage {
+    private readonly fileSystem;
+    private readonly path;
+    private readonly now;
+    readonly header: JsonlStorageHeader;
+    private backing;
+    private readonly storageState;
+    private commitQueue;
+    private state;
+    private closePromise;
+    private constructor();
+    static create(options: JsonlStorageOptions, header: JsonlStorageHeader, initialWrites: Write[], context: Context): Promise<JsonlStorage>;
+    /** Atomically create storage from a complete prepared snapshot. */
+    static createFromForkSnapshot(options: JsonlStorageOptions, header: JsonlStorageHeader, snapshot: ForkDestinationSnapshot, context: Context): Promise<JsonlStorage>;
+    static open(options: JsonlStorageOptions, context: Context): Promise<JsonlStorage>;
+    private static openLegacyV3;
+    private replayCommitted;
+    commit(writes: Write[], context: Context): Promise<CommitResult>;
+    private applyCommit;
+    private upgradeLegacyV3ToV4;
+    getEntries(ids: string[], _context: Context): Promise<Map<string, Entry>>;
+    getValue<T>(address: Value<T>, _context: Context): Promise<StoredValue<T> | undefined>;
+    scanValues<T>(prefix: Value<T>, _context: Context): Promise<StoredValue<T>[]>;
+    readList<T>(address: ValueList<T>, options: ListReadOptions | undefined, _context: Context): Promise<ListElement<T>[]>;
+    scanBranch(query: StorageBranchScan, _context: Context): Promise<Entry[]>;
+    scanBranchStructure(query: StorageBranchScan, _context: Context): Promise<EntryStructure[]>;
+    scanEntries(query: EntryScan, _context: Context): Promise<Entry[]>;
+    scanUsage(query: UsageScan, _context: Context): Promise<UsageRow[]>;
+    getStats(_context: Context): Promise<SessionStats>;
+    private withImportedUsage;
+    /** Capture the state needed to fork at one serialized boundary between commits. */
+    captureForkSource(_context: Context): Promise<ForkSourceSnapshot>;
+    close(_context: Context): Promise<void>;
 }
 //# sourceMappingURL=storage.d.ts.map

package/dist/harness/session/jsonl/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../src/harness/session/jsonl/storage.ts"],"names":[],"mappings":"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","sourcesContent":["import { type SessionMutation, SessionState } from \"../state.ts\";\nimport {\n\ttype BranchBounds,\n\ttype Entry,\n\ttype EntryQuery,\n\ttype ForkOptions,\n\ttype LanePointer,\n\ttype LaneRecord,\n\ttype LogItem,\n\ttype LogOptions,\n\ttype NewRecord,\n\ttype OperationStartedRecord,\n\ttype ProvisionedEntry,\n\ttype RecordQuery,\n\tSessionError,\n\ttype SessionStats,\n\ttype SessionStorage,\n} from \"../types.ts\";\nimport { encodeHeader, encodeMutation, metadataFromHeader, parseHeader, parseMutation } from \"./codec.ts\";\nimport { fileResult, invalidFile, JsonlDecodeError } from \"./errors.ts\";\nimport type { JsonlSessionMetadata, JsonlSessionRepoFileSystem, JsonlV4Header } from \"./types.ts\";\n\n/**\n * Build a complete sibling temporary file, then atomically rename it over the destination.\n * The populate callback must create or overwrite `tempPath` with the complete file. The\n * destination is untouched until the rename commits, so a process crash while populating\n * can leave only the ignored `.tmp` file behind.\n *\n * Rejects when population or rename fails. On rejection, temporary-file removal is\n * best-effort and the original error is preserved. Callers must serialize publications to\n * the same destination because they share its deterministic `.tmp` path.\n */\nasync function publishFileAtomically(\n\tfs: JsonlSessionRepoFileSystem,\n\tdestinationPath: string,\n\tpopulate: (tempPath: string) => Promise<void>,\n): Promise<void> {\n\tconst tempPath = `${destinationPath}.tmp`;\n\ttry {\n\t\tawait populate(tempPath);\n\t\tfileResult(await fs.renameFile(tempPath, destinationPath), `Failed to publish staged file ${destinationPath}`);\n\t} catch (error) {\n\t\tawait fs.remove(tempPath, { force: true });\n\t\tthrow error;\n\t}\n}\n\nexport class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata> {\n\tprivate readonly fs: JsonlSessionRepoFileSystem;\n\tprivate readonly metadata: JsonlSessionMetadata;\n\tprivate readonly state = new SessionState();\n\tprivate tail: Promise<void> = Promise.resolve();\n\n\tconstructor(fs: JsonlSessionRepoFileSystem, metadata: JsonlSessionMetadata) {\n\t\tthis.fs = fs;\n\t\tthis.metadata = structuredClone(metadata);\n\t}\n\n\tstatic async create(\n\t\tfs: JsonlSessionRepoFileSystem,\n\t\tpath: string,\n\t\theader: JsonlV4Header,\n\t): Promise<JsonlSessionStorage> {\n\t\tfileResult(await fs.writeFile(path, encodeHeader(header)), `Failed to initialize session ${path}`);\n\t\tconst fileInfo = fileResult(await fs.fileInfo(path), `Failed to read session metadata ${path}`);\n\t\treturn new JsonlSessionStorage(fs, metadataFromHeader(header, path, fileInfo.mtimeMs));\n\t}\n\n\tstatic async load(fs: JsonlSessionRepoFileSystem, path: string): Promise<JsonlSessionStorage> {\n\t\tconst content = fileResult(await fs.readTextFile(path), `Failed to read session ${path}`);\n\t\tconst physicalLines = content.split(\"\\n\");\n\t\tif (physicalLines.at(-1) === \"\") physicalLines.pop();\n\t\tif (physicalLines.length === 0 || !physicalLines[0]) {\n\t\t\tthrow invalidFile(path, 1, new JsonlDecodeError(\"schema\", \"is missing a header\"));\n\t\t}\n\t\tconst headerResult = parseHeader(physicalLines[0]);\n\t\tif (!headerResult.ok) throw invalidFile(path, 1, headerResult.error);\n\t\tconst fileInfo = fileResult(await fs.fileInfo(path), `Failed to read session metadata ${path}`);\n\t\tconst storage = new JsonlSessionStorage(fs, metadataFromHeader(headerResult.value, path, fileInfo.mtimeMs));\n\t\tfor (let index = 1; index < physicalLines.length; index++) {\n\t\t\tconst line = physicalLines[index]!;\n\t\t\tconst mutationResult = parseMutation(line);\n\t\t\tif (!mutationResult.ok) {\n\t\t\t\tconst isTornTail = index === physicalLines.length - 1 && mutationResult.error.kind === \"syntax\";\n\t\t\t\tif (isTornTail) {\n\t\t\t\t\t// Drop the unacknowledged partial append by atomically publishing the valid prefix.\n\t\t\t\t\tconst validPrefix = `${physicalLines.slice(0, index).join(\"\\n\")}\\n`;\n\t\t\t\t\tawait publishFileAtomically(fs, path, async (tempPath) => {\n\t\t\t\t\t\tfileResult(await fs.writeFile(tempPath, validPrefix), `Failed to stage torn-tail repair ${path}`);\n\t\t\t\t\t});\n\t\t\t\t\treturn storage;\n\t\t\t\t}\n\t\t\t\tthrow invalidFile(path, index + 1, mutationResult.error);\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tstorage.applyMutation(mutationResult.value);\n\t\t\t} catch (error) {\n\t\t\t\tif (error instanceof SessionError && error.code === \"invalid_entry\") {\n\t\t\t\t\tthrow invalidFile(path, index + 1, error);\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t\tif (!content.endsWith(\"\\n\")) {\n\t\t\tfileResult(await fs.appendFile(path, \"\\n\"), `Failed to repair unterminated session tail ${path}`);\n\t\t}\n\t\treturn storage;\n\t}\n\n\tasync fork(path: string, header: JsonlV4Header, options: ForkOptions): Promise<JsonlSessionStorage> {\n\t\tconst mutations = this.state.createForkMutations(options);\n\t\tawait publishFileAtomically(this.fs, path, async (tempPath) => {\n\t\t\tconst targetStorage = await JsonlSessionStorage.create(this.fs, tempPath, header);\n\t\t\tfor (const mutation of mutations) {\n\t\t\t\tawait targetStorage.appendMutation(mutation);\n\t\t\t\ttargetStorage.applyMutation(mutation);\n\t\t\t}\n\t\t});\n\t\treturn JsonlSessionStorage.load(this.fs, path);\n\t}\n\n\tasync drain(): Promise<void> {\n\t\tawait this.tail;\n\t}\n\n\tasync getMetadata(): Promise<JsonlSessionMetadata> {\n\t\treturn structuredClone(this.metadata);\n\t}\n\n\tasync getLanes(): Promise<LanePointer[]> {\n\t\treturn this.state.getLanes();\n\t}\n\n\tcreateLane(lane: string, at: string | null): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.state.validateNewLane(lane);\n\t\t\tthis.state.validateTarget(at);\n\t\t\tconst mutation: SessionMutation = { kind: \"lane\", seq: this.state.nextSequence, lane, leafId: at };\n\t\t\tawait this.appendMutation(mutation);\n\t\t\tthis.applyMutation(mutation);\n\t\t});\n\t}\n\n\tmoveLane(lane: string, to: string | null): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.state.requireLane(lane);\n\t\t\tthis.state.validateTarget(to);\n\t\t\tconst mutation: SessionMutation = { kind: \"lane\", seq: this.state.nextSequence, lane, leafId: to };\n\t\t\tawait this.appendMutation(mutation);\n\t\t\tthis.applyMutation(mutation);\n\t\t});\n\t}\n\n\tappendEntry<TEntry extends Entry>(newEntry: ProvisionedEntry<TEntry>, lane: string): Promise<TEntry> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst parentId = this.state.requireLane(lane);\n\t\t\tthis.state.validateUnusedId(newEntry.id);\n\t\t\tconst entry = {\n\t\t\t\t...structuredClone(newEntry),\n\t\t\t\tparentId,\n\t\t\t\tseq: this.state.nextSequence,\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t} as unknown as TEntry;\n\t\t\tconst mutation: SessionMutation = { kind: \"entry\", lane, entry };\n\t\t\tawait this.appendMutation(mutation);\n\t\t\tthis.applyMutation(mutation);\n\t\t\treturn structuredClone(entry);\n\t\t});\n\t}\n\n\tappendRecord<TRecord extends LaneRecord>(newRecord: NewRecord<TRecord>): Promise<TRecord> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.state.requireLane(newRecord.lane);\n\t\t\tthis.state.validateUnusedId(newRecord.id);\n\t\t\tconst currentOpenOperationId = this.state.findOpenOperations(newRecord.lane, { limit: 1 })[0]?.id;\n\t\t\tif (newRecord.type === \"operation_started\" && currentOpenOperationId !== undefined) {\n\t\t\t\tthrow new SessionError(\n\t\t\t\t\t\"storage\",\n\t\t\t\t\t`Lane ${newRecord.lane} already has an open operation ${currentOpenOperationId}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst record = {\n\t\t\t\t...structuredClone(newRecord),\n\t\t\t\tseq: this.state.nextSequence,\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t} as unknown as TRecord;\n\t\t\tconst mutation: SessionMutation = { kind: \"record\", record };\n\t\t\tawait this.appendMutation(mutation);\n\t\t\tthis.applyMutation(mutation);\n\t\t\treturn structuredClone(record);\n\t\t});\n\t}\n\n\tasync getEntry(id: string): Promise<Entry | undefined> {\n\t\tconst entry = this.state.getEntry(id);\n\t\treturn entry === undefined ? undefined : structuredClone(entry);\n\t}\n\n\tasync findEntries(query: EntryQuery = {}): Promise<Entry[]> {\n\t\treturn structuredClone(this.state.findEntries(query));\n\t}\n\n\tasync findEntriesOnBranch(query: EntryQuery & BranchBounds & { start: string }): Promise<Entry[]> {\n\t\treturn structuredClone(this.state.findEntriesOnBranch(query));\n\t}\n\n\tasync findRecords<K extends LaneRecord[\"type\"]>(\n\t\tquery: RecordQuery & { type: K },\n\t): Promise<Extract<LaneRecord, { type: K }>[]>;\n\tasync findRecords(query?: RecordQuery): Promise<LaneRecord[]>;\n\tasync findRecords(query: RecordQuery = {}): Promise<LaneRecord[]> {\n\t\treturn structuredClone(this.state.findRecords(query));\n\t}\n\n\tasync findOpenOperations(lane: string, options?: { limit?: number }): Promise<OperationStartedRecord[]> {\n\t\treturn structuredClone(this.state.findOpenOperations(lane, options));\n\t}\n\n\tasync getLog(options: LogOptions = {}): Promise<LogItem[]> {\n\t\treturn structuredClone(this.state.getLog(options));\n\t}\n\n\tasync getName(): Promise<string | undefined> {\n\t\treturn this.state.getName();\n\t}\n\n\tsetName(name: string | undefined): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst mutation: SessionMutation = { kind: \"fact\", seq: this.state.nextSequence, fact: \"name\", name };\n\t\t\tawait this.appendMutation(mutation);\n\t\t\tthis.applyMutation(mutation);\n\t\t});\n\t}\n\n\tasync getLabel(id: string): Promise<string | undefined> {\n\t\treturn this.state.getLabel(id);\n\t}\n\n\tsetLabel(id: string, label: string | undefined): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.state.validateTarget(id);\n\t\t\tconst mutation: SessionMutation = {\n\t\t\t\tkind: \"fact\",\n\t\t\t\tseq: this.state.nextSequence,\n\t\t\t\tfact: \"label\",\n\t\t\t\ttargetId: id,\n\t\t\t\tlabel,\n\t\t\t};\n\t\t\tawait this.appendMutation(mutation);\n\t\t\tthis.applyMutation(mutation);\n\t\t});\n\t}\n\n\tasync getStats(): Promise<SessionStats> {\n\t\treturn structuredClone(this.state.getStats());\n\t}\n\n\tprivate enqueue<T>(operation: () => Promise<T>): Promise<T> {\n\t\tconst result = this.tail.then(operation);\n\t\tthis.tail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t}\n\n\tprivate async appendMutation(mutation: SessionMutation): Promise<void> {\n\t\tfileResult(\n\t\t\tawait this.fs.appendFile(this.metadata.path, encodeMutation(mutation)),\n\t\t\t`Failed to append session ${this.metadata.path}`,\n\t\t);\n\t}\n\n\tprivate applyMutation(mutation: SessionMutation): void {\n\t\tthis.state.applyMutation(mutation);\n\t}\n}\n"]}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../src/harness/session/jsonl/storage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAE,KAAK,uBAAuB,EAAE,KAAK,kBAAkB,EAAsB,MAAM,YAAY,CAAC;AAWvG,OAAO,KAAK,EACX,YAAY,EACZ,KAAK,EACL,SAAS,EACT,cAAc,EACd,YAAY,EACZ,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,KAAK,EACL,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGhG,OAAO,EAAyB,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA4FtG,iEAAiE;AACjE,qBAAa,YAAa,YAAW,OAAO;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,YAAY,CAA4B;IAEhD,OAAO,eAMN;IAED,OAAa,MAAM,CAClB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,kBAAkB,EAC1B,aAAa,EAAE,KAAK,EAAE,EACtB,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,YAAY,CAAC,CAOvB;IAED,mEAAmE;IACnE,OAAa,sBAAsB,CAClC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,uBAAuB,EACjC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,YAAY,CAAC,CAavB;IAED,OAAa,IAAI,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCvF;mBAEoB,YAAY;IAoBjC,OAAO,CAAC,eAAe;IAKjB,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAQrE;YAEa,WAAW;YAgBX,mBAAmB;IAuCjC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAGxE;IAED,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAGrF;IAED,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAG5E;IAEK,QAAQ,CAAC,CAAC,EACf,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,eAAe,GAAG,SAAS,EACpC,QAAQ,EAAE,OAAO,GACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAG3B;IAEK,UAAU,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAG9E;IAEK,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGhG;IAED,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAGjE;IAED,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGlE;IAED,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAGjD;IAED,OAAO,CAAC,iBAAiB;IAIzB,mFAAmF;IACnF,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAQhE;IAED,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtC;CACD","sourcesContent":["import type { Usage } from \"@earendil-works/pi-ai\";\nimport { uuidv7 } from \"@earendil-works/pi-ai/utils/uuid\";\nimport type { Context } from \"../../context.ts\";\nimport type { FileError, FileSystem, Result } from \"../../types.ts\";\nimport { insertUsage } from \"../commit.ts\";\nimport { type ForkDestinationSnapshot, type ForkSourceSnapshot, forkSnapshotWrites } from \"../fork.ts\";\nimport {\n\ttype CommittedEntryWrite,\n\ttype CommittedListAppendWrite,\n\ttype CommittedListDeleteWrite,\n\ttype CommittedUsageWrite,\n\ttype CommittedValueDeleteWrite,\n\ttype CommittedValueSetWrite,\n\ttype CommittedWrite,\n\tInMemoryStorageState,\n} from \"../in-memory-storage-state.ts\";\nimport type {\n\tCommitResult,\n\tEntry,\n\tEntryScan,\n\tEntryStructure,\n\tSessionStats,\n\tStorage,\n\tStorageBranchScan,\n\tUsageRow,\n\tUsageScan,\n\tWrite,\n} from \"../types.ts\";\nimport type { ListElement, ListReadOptions, StoredValue, Value, ValueList } from \"../values.ts\";\nimport { type LegacyV3SessionHeader, parseJsonlSessionHeader } from \"./codec.ts\";\nimport { normalizeLegacyV3Header, normalizeLegacyV3Records } from \"./legacy-v3.ts\";\nimport { JSONL_STORAGE_VERSION, type JsonlStorageHeader, type JsonlStorageOptions } from \"./types.ts\";\n\nfunction fileValue<T>(result: Result<T, FileError>, action: string): T {\n\tif (!result.ok) throw new Error(`${action}: ${result.error.message}`, { cause: result.error });\n\treturn result.value;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction requireSafeInteger(value: unknown, field: string, minimum: number): void {\n\tif (!Number.isSafeInteger(value) || (value as number) < minimum) throw new Error(`Invalid JSONL ${field}`);\n}\n\nfunction parseCommittedWrite(value: unknown): CommittedWrite {\n\tif (!isRecord(value)) throw new Error(\"Invalid JSONL transaction write\");\n\trequireSafeInteger(value.seq, \"write seq\", 1);\n\tswitch (value.kind) {\n\t\tcase \"entry\":\n\t\t\trequireSafeInteger(value.timestamp, \"entry timestamp\", 0);\n\t\t\treturn value as unknown as CommittedEntryWrite;\n\t\tcase \"usage\":\n\t\t\treturn value as unknown as CommittedUsageWrite;\n\t\tcase \"value\":\n\t\t\tif (value.op === \"set\") return value as unknown as CommittedValueSetWrite;\n\t\t\tif (value.op === \"delete\") return value as unknown as CommittedValueDeleteWrite;\n\t\t\tthrow new Error(`Invalid JSONL value operation: ${String(value.op)}`);\n\t\tcase \"list\":\n\t\t\tif (value.op === \"append\") return value as unknown as CommittedListAppendWrite;\n\t\t\tif (value.op === \"delete\") return value as unknown as CommittedListDeleteWrite;\n\t\t\tthrow new Error(`Invalid JSONL list operation: ${String(value.op)}`);\n\t\tdefault:\n\t\t\tthrow new Error(`Invalid JSONL write kind: ${String(value.kind)}`);\n\t}\n}\n\nfunction parseTransaction(line: string): CommittedWrite[] {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(line);\n\t} catch (error) {\n\t\tthrow new Error(\"Invalid JSONL transaction: not valid JSON\", { cause: error });\n\t}\n\treturn (Array.isArray(value) ? value : [value]).map(parseCommittedWrite);\n}\n\nfunction serializeTransaction(writes: CommittedWrite[]): string {\n\treturn JSON.stringify(writes.length === 1 ? writes[0] : writes);\n}\n\nfunction serializeStorage(header: JsonlStorageHeader, transactions: CommittedWrite[][]): string {\n\treturn `${[JSON.stringify(header), ...transactions.map(serializeTransaction)].join(\"\\n\")}\\n`;\n}\n\nfunction splitCompleteLines(content: string): { lines: string[]; torn: boolean } {\n\tif (content.endsWith(\"\\n\")) return { lines: content.slice(0, -1).split(\"\\n\"), torn: false };\n\tconst lastNewline = content.lastIndexOf(\"\\n\");\n\tif (lastNewline === -1) return { lines: [], torn: true };\n\treturn { lines: content.slice(0, lastNewline).split(\"\\n\"), torn: true };\n}\n\nasync function publishFileAtomically(\n\tfileSystem: FileSystem,\n\tdestinationPath: string,\n\tcontent: string,\n\tcontext: Context,\n): Promise<void> {\n\tconst tempPath = `${destinationPath}.tmp`;\n\ttry {\n\t\tfileValue(\n\t\t\tawait fileSystem.writeFile(tempPath, content, context),\n\t\t\t`Failed to stage JSONL storage ${destinationPath}`,\n\t\t);\n\t\tfileValue(\n\t\t\tawait fileSystem.renameFile(tempPath, destinationPath, context),\n\t\t\t`Failed to publish JSONL storage ${destinationPath}`,\n\t\t);\n\t} catch (error) {\n\t\tawait fileSystem.remove(tempPath, { force: true }, context);\n\t\tthrow error;\n\t}\n}\n\ntype LegacyV3Backing = {\n\tkind: \"v3\";\n\timportedUsage: Usage;\n\tbaselineWrites: readonly CommittedWrite[];\n};\n\ntype JsonlBacking = { kind: \"v4\" } | LegacyV3Backing;\n\n/** JSONL storage backed by an injected filesystem capability. */\nexport class JsonlStorage implements Storage {\n\tprivate readonly fileSystem: FileSystem;\n\tprivate readonly path: string;\n\tprivate readonly now: () => number;\n\treadonly header: JsonlStorageHeader;\n\tprivate backing: JsonlBacking;\n\tprivate readonly storageState = new InMemoryStorageState();\n\tprivate commitQueue: Promise<void> = Promise.resolve();\n\tprivate state: \"open\" | \"closing\" | \"closed\" = \"open\";\n\tprivate closePromise: Promise<void> | undefined;\n\n\tprivate constructor(options: JsonlStorageOptions, header: JsonlStorageHeader, backing: JsonlBacking) {\n\t\tthis.fileSystem = options.fileSystem;\n\t\tthis.path = options.path;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.header = header;\n\t\tthis.backing = backing;\n\t}\n\n\tstatic async create(\n\t\toptions: JsonlStorageOptions,\n\t\theader: JsonlStorageHeader,\n\t\tinitialWrites: Write[],\n\t\tcontext: Context,\n\t): Promise<JsonlStorage> {\n\t\tconst storage = new JsonlStorage(options, header, { kind: \"v4\" });\n\t\tconst prepared = storage.storageState.prepareCommit(initialWrites, storage.now());\n\t\tconst transactions = prepared.writes.length === 0 ? [] : [prepared.writes];\n\t\tawait publishFileAtomically(options.fileSystem, options.path, serializeStorage(header, transactions), context);\n\t\tstorage.storageState.applyValidated(prepared.writes);\n\t\treturn storage;\n\t}\n\n\t/** Atomically create storage from a complete prepared snapshot. */\n\tstatic async createFromForkSnapshot(\n\t\toptions: JsonlStorageOptions,\n\t\theader: JsonlStorageHeader,\n\t\tsnapshot: ForkDestinationSnapshot,\n\t\tcontext: Context,\n\t): Promise<JsonlStorage> {\n\t\tconst writes = forkSnapshotWrites(snapshot);\n\t\tconst snapshotHeader = { ...header, nextSeq: snapshot.nextSeq };\n\t\tawait publishFileAtomically(\n\t\t\toptions.fileSystem,\n\t\t\toptions.path,\n\t\t\tserializeStorage(\n\t\t\t\tsnapshotHeader,\n\t\t\t\twrites.map((write) => [write]),\n\t\t\t),\n\t\t\tcontext,\n\t\t);\n\t\treturn JsonlStorage.open(options, context);\n\t}\n\n\tstatic async open(options: JsonlStorageOptions, context: Context): Promise<JsonlStorage> {\n\t\tconst content = fileValue(\n\t\t\tawait options.fileSystem.readTextFile(options.path, context),\n\t\t\t`Failed to read JSONL storage ${options.path}`,\n\t\t);\n\t\tconst { lines, torn } = splitCompleteLines(content);\n\t\tif (lines[0] === undefined || lines[0] === \"\") {\n\t\t\tthrow new Error(`Invalid JSONL storage ${options.path}: missing header`);\n\t\t}\n\t\tconst parsedHeader = parseJsonlSessionHeader(lines[0]);\n\t\tif (!parsedHeader.ok) {\n\t\t\tthrow new Error(`Invalid JSONL storage ${options.path}: invalid header`, { cause: parsedHeader.error });\n\t\t}\n\t\tif (parsedHeader.value.format === \"v3-legacy\") {\n\t\t\treturn JsonlStorage.openLegacyV3(options, parsedHeader.value.header, lines.slice(1), context);\n\t\t}\n\n\t\tconst header = parsedHeader.value.header;\n\t\tif (header.storageVersion !== JSONL_STORAGE_VERSION) {\n\t\t\tthrow new Error(`Session ${header.id} uses unsupported storage version ${header.storageVersion}`);\n\t\t}\n\t\tconst storage = new JsonlStorage(options, header, { kind: \"v4\" });\n\t\tfor (let index = 1; index < lines.length; index++) {\n\t\t\tconst line = lines[index]!;\n\t\t\ttry {\n\t\t\t\tstorage.replayCommitted(parseTransaction(line));\n\t\t\t} catch (error) {\n\t\t\t\tthrow new Error(`Invalid JSONL storage ${options.path}: line ${index + 1}`, { cause: error });\n\t\t\t}\n\t\t}\n\t\tif (header.nextSeq !== undefined) storage.storageState.advanceNextSeq(header.nextSeq);\n\t\tif (torn) await publishFileAtomically(options.fileSystem, options.path, `${lines.join(\"\\n\")}\\n`, context);\n\t\treturn storage;\n\t}\n\n\tprivate static async openLegacyV3(\n\t\toptions: JsonlStorageOptions,\n\t\theader: LegacyV3SessionHeader,\n\t\trecordLines: readonly string[],\n\t\tcontext: Context,\n\t): Promise<JsonlStorage> {\n\t\tconst { writes, importedUsage, nextSeq } = normalizeLegacyV3Records(recordLines);\n\t\tconst targetHeader = {\n\t\t\t...(await normalizeLegacyV3Header(options.fileSystem, header, context)),\n\t\t\tnextSeq,\n\t\t};\n\t\tconst storage = new JsonlStorage(options, targetHeader, {\n\t\t\tkind: \"v3\",\n\t\t\timportedUsage,\n\t\t\tbaselineWrites: writes,\n\t\t});\n\t\tstorage.replayCommitted(writes);\n\t\treturn storage;\n\t}\n\n\tprivate replayCommitted(writes: readonly CommittedWrite[]): void {\n\t\tthis.storageState.validateCommitted(writes);\n\t\tthis.storageState.applyValidated(writes);\n\t}\n\n\tasync commit(writes: Write[], context: Context): Promise<CommitResult> {\n\t\tif (this.state !== \"open\") throw new Error(\"JsonlStorage is closed\");\n\t\tconst result = this.commitQueue.then(() => this.applyCommit(writes, context));\n\t\tthis.commitQueue = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t}\n\n\tprivate async applyCommit(writes: Write[], context: Context): Promise<CommitResult> {\n\t\tif (this.backing.kind === \"v3\" && writes.length !== 0) {\n\t\t\treturn this.upgradeLegacyV3ToV4(this.backing, writes, context);\n\t\t}\n\t\tconst prepared = this.storageState.prepareCommit(writes, this.now());\n\t\tif (prepared.writes.length !== 0) {\n\t\t\tfileValue(\n\t\t\t\tawait this.fileSystem.appendFile(this.path, `${serializeTransaction(prepared.writes)}\\n`, context),\n\t\t\t\t`Failed to append JSONL storage ${this.path}`,\n\t\t\t);\n\t\t}\n\t\tconst stats = this.storageState.applyValidated(prepared.writes);\n\t\treturn { ...prepared.result, stats: this.withImportedUsage(stats) };\n\t}\n\n\t/** Atomically upgrade legacy v3 backing and preserve the first caller write as a v4 transaction. */\n\tprivate async upgradeLegacyV3ToV4(\n\t\tbacking: LegacyV3Backing,\n\t\tcallerWrites: Write[],\n\t\tcontext: Context,\n\t): Promise<CommitResult> {\n\t\tconst timestamp = this.now();\n\t\tconst prepared = this.storageState.prepareCommit(\n\t\t\t[\n\t\t\t\tinsertUsage({\n\t\t\t\t\tid: uuidv7(timestamp),\n\t\t\t\t\tusage: backing.importedUsage,\n\t\t\t\t\tadjustment: true,\n\t\t\t\t\tdetails: { source: \"v3-import\" },\n\t\t\t\t}),\n\t\t\t\t...callerWrites,\n\t\t\t],\n\t\t\ttimestamp,\n\t\t);\n\n\t\tconst nextSeq = prepared.result.firstSeq + prepared.writes.length;\n\t\tconst upgradedHeader = { ...this.header, nextSeq };\n\t\tawait publishFileAtomically(\n\t\t\tthis.fileSystem,\n\t\t\tthis.path,\n\t\t\tserializeStorage(upgradedHeader, [...backing.baselineWrites.map((write) => [write]), prepared.writes]),\n\t\t\tcontext,\n\t\t);\n\n\t\tconst stats = this.storageState.applyValidated(prepared.writes);\n\t\tthis.backing = { kind: \"v4\" };\n\t\t// The first sequence belongs to the internal usage adjustment; return only caller-write sequences.\n\t\treturn {\n\t\t\t...prepared.result,\n\t\t\tfirstSeq: prepared.result.firstSeq + 1,\n\t\t\tseqs: prepared.result.seqs.slice(1),\n\t\t\tstats,\n\t\t};\n\t}\n\n\tgetEntries(ids: string[], _context: Context): Promise<Map<string, Entry>> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\treturn Promise.resolve(this.storageState.getEntries(ids));\n\t}\n\n\tgetValue<T>(address: Value<T>, _context: Context): Promise<StoredValue<T> | undefined> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\treturn Promise.resolve(this.storageState.getValue(address));\n\t}\n\n\tscanValues<T>(prefix: Value<T>, _context: Context): Promise<StoredValue<T>[]> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\treturn Promise.resolve(this.storageState.scanValues(prefix));\n\t}\n\n\tasync readList<T>(\n\t\taddress: ValueList<T>,\n\t\toptions: ListReadOptions | undefined,\n\t\t_context: Context,\n\t): Promise<ListElement<T>[]> {\n\t\tif (this.state !== \"open\") throw new Error(\"JsonlStorage is closed\");\n\t\treturn this.storageState.readList(address, options);\n\t}\n\n\tasync scanBranch(query: StorageBranchScan, _context: Context): Promise<Entry[]> {\n\t\tif (this.state !== \"open\") throw new Error(\"JsonlStorage is closed\");\n\t\treturn this.storageState.scanBranch(query);\n\t}\n\n\tasync scanBranchStructure(query: StorageBranchScan, _context: Context): Promise<EntryStructure[]> {\n\t\tif (this.state !== \"open\") throw new Error(\"JsonlStorage is closed\");\n\t\treturn this.storageState.scanBranchStructure(query);\n\t}\n\n\tscanEntries(query: EntryScan, _context: Context): Promise<Entry[]> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\treturn Promise.resolve(this.storageState.scanEntries(query));\n\t}\n\n\tscanUsage(query: UsageScan, _context: Context): Promise<UsageRow[]> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\treturn Promise.resolve(this.storageState.scanUsage(query));\n\t}\n\n\tgetStats(_context: Context): Promise<SessionStats> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\treturn Promise.resolve(this.withImportedUsage(this.storageState.getStats()));\n\t}\n\n\tprivate withImportedUsage(stats: SessionStats): SessionStats {\n\t\treturn this.backing.kind === \"v4\" ? stats : { ...stats, usage: this.backing.importedUsage };\n\t}\n\n\t/** Capture the state needed to fork at one serialized boundary between commits. */\n\tcaptureForkSource(_context: Context): Promise<ForkSourceSnapshot> {\n\t\tif (this.state !== \"open\") return Promise.reject(new Error(\"JsonlStorage is closed\"));\n\t\tconst result = this.commitQueue.then(() => this.storageState.snapshotEntriesAndValues());\n\t\tthis.commitQueue = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t}\n\n\tclose(_context: Context): Promise<void> {\n\t\tif (this.closePromise !== undefined) return this.closePromise;\n\t\tthis.state = \"closing\";\n\t\tthis.closePromise = this.commitQueue.then(() => {\n\t\t\tthis.state = \"closed\";\n\t\t});\n\t\treturn this.closePromise;\n\t}\n}\n"]}

package/dist/harness/session/jsonl/storage.js

@@ -1,217 +1,274 @@
-import { SessionState } from "../state.js";
-import { SessionError, } from "../types.js";
-import { encodeHeader, encodeMutation, metadataFromHeader, parseHeader, parseMutation } from "./codec.js";
-import { fileResult, invalidFile, JsonlDecodeError } from "./errors.js";
-/**
- * Build a complete sibling temporary file, then atomically rename it over the destination.
- * The populate callback must create or overwrite `tempPath` with the complete file. The
- * destination is untouched until the rename commits, so a process crash while populating
- * can leave only the ignored `.tmp` file behind.
- *
- * Rejects when population or rename fails. On rejection, temporary-file removal is
- * best-effort and the original error is preserved. Callers must serialize publications to
- * the same destination because they share its deterministic `.tmp` path.
- */
-async function publishFileAtomically(fs, destinationPath, populate) {
+import { uuidv7 } from "@earendil-works/pi-ai/utils/uuid";
+import { insertUsage } from "../commit.js";
+import { forkSnapshotWrites } from "../fork.js";
+import { InMemoryStorageState, } from "../in-memory-storage-state.js";
+import { parseJsonlSessionHeader } from "./codec.js";
+import { normalizeLegacyV3Header, normalizeLegacyV3Records } from "./legacy-v3.js";
+import { JSONL_STORAGE_VERSION } from "./types.js";
+function fileValue(result, action) {
+    if (!result.ok)
+        throw new Error(`${action}: ${result.error.message}`, { cause: result.error });
+    return result.value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireSafeInteger(value, field, minimum) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`Invalid JSONL ${field}`);
+}
+function parseCommittedWrite(value) {
+    if (!isRecord(value))
+        throw new Error("Invalid JSONL transaction write");
+    requireSafeInteger(value.seq, "write seq", 1);
+    switch (value.kind) {
+        case "entry":
+            requireSafeInteger(value.timestamp, "entry timestamp", 0);
+            return value;
+        case "usage":
+            return value;
+        case "value":
+            if (value.op === "set")
+                return value;
+            if (value.op === "delete")
+                return value;
+            throw new Error(`Invalid JSONL value operation: ${String(value.op)}`);
+        case "list":
+            if (value.op === "append")
+                return value;
+            if (value.op === "delete")
+                return value;
+            throw new Error(`Invalid JSONL list operation: ${String(value.op)}`);
+        default:
+            throw new Error(`Invalid JSONL write kind: ${String(value.kind)}`);
+    }
+}
+function parseTransaction(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (error) {
+        throw new Error("Invalid JSONL transaction: not valid JSON", { cause: error });
+    }
+    return (Array.isArray(value) ? value : [value]).map(parseCommittedWrite);
+}
+function serializeTransaction(writes) {
+    return JSON.stringify(writes.length === 1 ? writes[0] : writes);
+}
+function serializeStorage(header, transactions) {
+    return `${[JSON.stringify(header), ...transactions.map(serializeTransaction)].join("\n")}\n`;
+}
+function splitCompleteLines(content) {
+    if (content.endsWith("\n"))
+        return { lines: content.slice(0, -1).split("\n"), torn: false };
+    const lastNewline = content.lastIndexOf("\n");
+    if (lastNewline === -1)
+        return { lines: [], torn: true };
+    return { lines: content.slice(0, lastNewline).split("\n"), torn: true };
+}
+async function publishFileAtomically(fileSystem, destinationPath, content, context) {
     const tempPath = `${destinationPath}.tmp`;
     try {
-        await populate(tempPath);
-        fileResult(await fs.renameFile(tempPath, destinationPath), `Failed to publish staged file ${destinationPath}`);
+        fileValue(await fileSystem.writeFile(tempPath, content, context), `Failed to stage JSONL storage ${destinationPath}`);
+        fileValue(await fileSystem.renameFile(tempPath, destinationPath, context), `Failed to publish JSONL storage ${destinationPath}`);
     }
     catch (error) {
-        await fs.remove(tempPath, { force: true });
+        await fileSystem.remove(tempPath, { force: true }, context);
         throw error;
     }
 }
-export class JsonlSessionStorage {
-    fs;
-    metadata;
-    state = new SessionState();
-    tail = Promise.resolve();
-    constructor(fs, metadata) {
-        this.fs = fs;
-        this.metadata = structuredClone(metadata);
-    }
-    static async create(fs, path, header) {
-        fileResult(await fs.writeFile(path, encodeHeader(header)), `Failed to initialize session ${path}`);
-        const fileInfo = fileResult(await fs.fileInfo(path), `Failed to read session metadata ${path}`);
-        return new JsonlSessionStorage(fs, metadataFromHeader(header, path, fileInfo.mtimeMs));
-    }
-    static async load(fs, path) {
-        const content = fileResult(await fs.readTextFile(path), `Failed to read session ${path}`);
-        const physicalLines = content.split("\n");
-        if (physicalLines.at(-1) === "")
-            physicalLines.pop();
-        if (physicalLines.length === 0 || !physicalLines[0]) {
-            throw invalidFile(path, 1, new JsonlDecodeError("schema", "is missing a header"));
+/** JSONL storage backed by an injected filesystem capability. */
+export class JsonlStorage {
+    fileSystem;
+    path;
+    now;
+    header;
+    backing;
+    storageState = new InMemoryStorageState();
+    commitQueue = Promise.resolve();
+    state = "open";
+    closePromise;
+    constructor(options, header, backing) {
+        this.fileSystem = options.fileSystem;
+        this.path = options.path;
+        this.now = options.now ?? Date.now;
+        this.header = header;
+        this.backing = backing;
+    }
+    static async create(options, header, initialWrites, context) {
+        const storage = new JsonlStorage(options, header, { kind: "v4" });
+        const prepared = storage.storageState.prepareCommit(initialWrites, storage.now());
+        const transactions = prepared.writes.length === 0 ? [] : [prepared.writes];
+        await publishFileAtomically(options.fileSystem, options.path, serializeStorage(header, transactions), context);
+        storage.storageState.applyValidated(prepared.writes);
+        return storage;
+    }
+    /** Atomically create storage from a complete prepared snapshot. */
+    static async createFromForkSnapshot(options, header, snapshot, context) {
+        const writes = forkSnapshotWrites(snapshot);
+        const snapshotHeader = { ...header, nextSeq: snapshot.nextSeq };
+        await publishFileAtomically(options.fileSystem, options.path, serializeStorage(snapshotHeader, writes.map((write) => [write])), context);
+        return JsonlStorage.open(options, context);
+    }
+    static async open(options, context) {
+        const content = fileValue(await options.fileSystem.readTextFile(options.path, context), `Failed to read JSONL storage ${options.path}`);
+        const { lines, torn } = splitCompleteLines(content);
+        if (lines[0] === undefined || lines[0] === "") {
+            throw new Error(`Invalid JSONL storage ${options.path}: missing header`);
         }
-        const headerResult = parseHeader(physicalLines[0]);
-        if (!headerResult.ok)
-            throw invalidFile(path, 1, headerResult.error);
-        const fileInfo = fileResult(await fs.fileInfo(path), `Failed to read session metadata ${path}`);
-        const storage = new JsonlSessionStorage(fs, metadataFromHeader(headerResult.value, path, fileInfo.mtimeMs));
-        for (let index = 1; index < physicalLines.length; index++) {
-            const line = physicalLines[index];
-            const mutationResult = parseMutation(line);
-            if (!mutationResult.ok) {
-                const isTornTail = index === physicalLines.length - 1 && mutationResult.error.kind === "syntax";
-                if (isTornTail) {
-                    // Drop the unacknowledged partial append by atomically publishing the valid prefix.
-                    const validPrefix = `${physicalLines.slice(0, index).join("\n")}\n`;
-                    await publishFileAtomically(fs, path, async (tempPath) => {
-                        fileResult(await fs.writeFile(tempPath, validPrefix), `Failed to stage torn-tail repair ${path}`);
-                    });
-                    return storage;
-                }
-                throw invalidFile(path, index + 1, mutationResult.error);
-            }
+        const parsedHeader = parseJsonlSessionHeader(lines[0]);
+        if (!parsedHeader.ok) {
+            throw new Error(`Invalid JSONL storage ${options.path}: invalid header`, { cause: parsedHeader.error });
+        }
+        if (parsedHeader.value.format === "v3-legacy") {
+            return JsonlStorage.openLegacyV3(options, parsedHeader.value.header, lines.slice(1), context);
+        }
+        const header = parsedHeader.value.header;
+        if (header.storageVersion !== JSONL_STORAGE_VERSION) {
+            throw new Error(`Session ${header.id} uses unsupported storage version ${header.storageVersion}`);
+        }
+        const storage = new JsonlStorage(options, header, { kind: "v4" });
+        for (let index = 1; index < lines.length; index++) {
+            const line = lines[index];
             try {
-                storage.applyMutation(mutationResult.value);
+                storage.replayCommitted(parseTransaction(line));
             }
             catch (error) {
-                if (error instanceof SessionError && error.code === "invalid_entry") {
-                    throw invalidFile(path, index + 1, error);
-                }
-                throw error;
+                throw new Error(`Invalid JSONL storage ${options.path}: line ${index + 1}`, { cause: error });
             }
         }
-        if (!content.endsWith("\n")) {
-            fileResult(await fs.appendFile(path, "\n"), `Failed to repair unterminated session tail ${path}`);
-        }
+        if (header.nextSeq !== undefined)
+            storage.storageState.advanceNextSeq(header.nextSeq);
+        if (torn)
+            await publishFileAtomically(options.fileSystem, options.path, `${lines.join("\n")}\n`, context);
         return storage;
     }
-    async fork(path, header, options) {
-        const mutations = this.state.createForkMutations(options);
-        await publishFileAtomically(this.fs, path, async (tempPath) => {
-            const targetStorage = await JsonlSessionStorage.create(this.fs, tempPath, header);
-            for (const mutation of mutations) {
-                await targetStorage.appendMutation(mutation);
-                targetStorage.applyMutation(mutation);
-            }
+    static async openLegacyV3(options, header, recordLines, context) {
+        const { writes, importedUsage, nextSeq } = normalizeLegacyV3Records(recordLines);
+        const targetHeader = {
+            ...(await normalizeLegacyV3Header(options.fileSystem, header, context)),
+            nextSeq,
+        };
+        const storage = new JsonlStorage(options, targetHeader, {
+            kind: "v3",
+            importedUsage,
+            baselineWrites: writes,
         });
-        return JsonlSessionStorage.load(this.fs, path);
-    }
-    async drain() {
-        await this.tail;
-    }
-    async getMetadata() {
-        return structuredClone(this.metadata);
-    }
-    async getLanes() {
-        return this.state.getLanes();
+        storage.replayCommitted(writes);
+        return storage;
     }
-    createLane(lane, at) {
-        return this.enqueue(async () => {
-            this.state.validateNewLane(lane);
-            this.state.validateTarget(at);
-            const mutation = { kind: "lane", seq: this.state.nextSequence, lane, leafId: at };
-            await this.appendMutation(mutation);
-            this.applyMutation(mutation);
-        });
+    replayCommitted(writes) {
+        this.storageState.validateCommitted(writes);
+        this.storageState.applyValidated(writes);
     }
-    moveLane(lane, to) {
-        return this.enqueue(async () => {
-            this.state.requireLane(lane);
-            this.state.validateTarget(to);
-            const mutation = { kind: "lane", seq: this.state.nextSequence, lane, leafId: to };
-            await this.appendMutation(mutation);
-            this.applyMutation(mutation);
-        });
+    async commit(writes, context) {
+        if (this.state !== "open")
+            throw new Error("JsonlStorage is closed");
+        const result = this.commitQueue.then(() => this.applyCommit(writes, context));
+        this.commitQueue = result.then(() => undefined, () => undefined);
+        return result;
     }
-    appendEntry(newEntry, lane) {
-        return this.enqueue(async () => {
-            const parentId = this.state.requireLane(lane);
-            this.state.validateUnusedId(newEntry.id);
-            const entry = {
-                ...structuredClone(newEntry),
-                parentId,
-                seq: this.state.nextSequence,
-                timestamp: Date.now(),
-            };
-            const mutation = { kind: "entry", lane, entry };
-            await this.appendMutation(mutation);
-            this.applyMutation(mutation);
-            return structuredClone(entry);
-        });
+    async applyCommit(writes, context) {
+        if (this.backing.kind === "v3" && writes.length !== 0) {
+            return this.upgradeLegacyV3ToV4(this.backing, writes, context);
+        }
+        const prepared = this.storageState.prepareCommit(writes, this.now());
+        if (prepared.writes.length !== 0) {
+            fileValue(await this.fileSystem.appendFile(this.path, `${serializeTransaction(prepared.writes)}\n`, context), `Failed to append JSONL storage ${this.path}`);
+        }
+        const stats = this.storageState.applyValidated(prepared.writes);
+        return { ...prepared.result, stats: this.withImportedUsage(stats) };
     }
-    appendRecord(newRecord) {
-        return this.enqueue(async () => {
-            this.state.requireLane(newRecord.lane);
-            this.state.validateUnusedId(newRecord.id);
-            const currentOpenOperationId = this.state.findOpenOperations(newRecord.lane, { limit: 1 })[0]?.id;
-            if (newRecord.type === "operation_started" && currentOpenOperationId !== undefined) {
-                throw new SessionError("storage", `Lane ${newRecord.lane} already has an open operation ${currentOpenOperationId}`);
-            }
-            const record = {
-                ...structuredClone(newRecord),
-                seq: this.state.nextSequence,
-                timestamp: Date.now(),
-            };
-            const mutation = { kind: "record", record };
-            await this.appendMutation(mutation);
-            this.applyMutation(mutation);
-            return structuredClone(record);
-        });
+    /** Atomically upgrade legacy v3 backing and preserve the first caller write as a v4 transaction. */
+    async upgradeLegacyV3ToV4(backing, callerWrites, context) {
+        const timestamp = this.now();
+        const prepared = this.storageState.prepareCommit([
+            insertUsage({
+                id: uuidv7(timestamp),
+                usage: backing.importedUsage,
+                adjustment: true,
+                details: { source: "v3-import" },
+            }),
+            ...callerWrites,
+        ], timestamp);
+        const nextSeq = prepared.result.firstSeq + prepared.writes.length;
+        const upgradedHeader = { ...this.header, nextSeq };
+        await publishFileAtomically(this.fileSystem, this.path, serializeStorage(upgradedHeader, [...backing.baselineWrites.map((write) => [write]), prepared.writes]), context);
+        const stats = this.storageState.applyValidated(prepared.writes);
+        this.backing = { kind: "v4" };
+        // The first sequence belongs to the internal usage adjustment; return only caller-write sequences.
+        return {
+            ...prepared.result,
+            firstSeq: prepared.result.firstSeq + 1,
+            seqs: prepared.result.seqs.slice(1),
+            stats,
+        };
     }
-    async getEntry(id) {
-        const entry = this.state.getEntry(id);
-        return entry === undefined ? undefined : structuredClone(entry);
+    getEntries(ids, _context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        return Promise.resolve(this.storageState.getEntries(ids));
     }
-    async findEntries(query = {}) {
-        return structuredClone(this.state.findEntries(query));
+    getValue(address, _context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        return Promise.resolve(this.storageState.getValue(address));
     }
-    async findEntriesOnBranch(query) {
-        return structuredClone(this.state.findEntriesOnBranch(query));
+    scanValues(prefix, _context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        return Promise.resolve(this.storageState.scanValues(prefix));
     }
-    async findRecords(query = {}) {
-        return structuredClone(this.state.findRecords(query));
+    async readList(address, options, _context) {
+        if (this.state !== "open")
+            throw new Error("JsonlStorage is closed");
+        return this.storageState.readList(address, options);
     }
-    async findOpenOperations(lane, options) {
-        return structuredClone(this.state.findOpenOperations(lane, options));
+    async scanBranch(query, _context) {
+        if (this.state !== "open")
+            throw new Error("JsonlStorage is closed");
+        return this.storageState.scanBranch(query);
     }
-    async getLog(options = {}) {
-        return structuredClone(this.state.getLog(options));
+    async scanBranchStructure(query, _context) {
+        if (this.state !== "open")
+            throw new Error("JsonlStorage is closed");
+        return this.storageState.scanBranchStructure(query);
     }
-    async getName() {
-        return this.state.getName();
+    scanEntries(query, _context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        return Promise.resolve(this.storageState.scanEntries(query));
     }
-    setName(name) {
-        return this.enqueue(async () => {
-            const mutation = { kind: "fact", seq: this.state.nextSequence, fact: "name", name };
-            await this.appendMutation(mutation);
-            this.applyMutation(mutation);
-        });
+    scanUsage(query, _context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        return Promise.resolve(this.storageState.scanUsage(query));
     }
-    async getLabel(id) {
-        return this.state.getLabel(id);
-    }
-    setLabel(id, label) {
-        return this.enqueue(async () => {
-            this.state.validateTarget(id);
-            const mutation = {
-                kind: "fact",
-                seq: this.state.nextSequence,
-                fact: "label",
-                targetId: id,
-                label,
-            };
-            await this.appendMutation(mutation);
-            this.applyMutation(mutation);
-        });
+    getStats(_context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        return Promise.resolve(this.withImportedUsage(this.storageState.getStats()));
     }
-    async getStats() {
-        return structuredClone(this.state.getStats());
+    withImportedUsage(stats) {
+        return this.backing.kind === "v4" ? stats : { ...stats, usage: this.backing.importedUsage };
     }
-    enqueue(operation) {
-        const result = this.tail.then(operation);
-        this.tail = result.then(() => undefined, () => undefined);
+    /** Capture the state needed to fork at one serialized boundary between commits. */
+    captureForkSource(_context) {
+        if (this.state !== "open")
+            return Promise.reject(new Error("JsonlStorage is closed"));
+        const result = this.commitQueue.then(() => this.storageState.snapshotEntriesAndValues());
+        this.commitQueue = result.then(() => undefined, () => undefined);
         return result;
     }
-    async appendMutation(mutation) {
-        fileResult(await this.fs.appendFile(this.metadata.path, encodeMutation(mutation)), `Failed to append session ${this.metadata.path}`);
-    }
-    applyMutation(mutation) {
-        this.state.applyMutation(mutation);
+    close(_context) {
+        if (this.closePromise !== undefined)
+            return this.closePromise;
+        this.state = "closing";
+        this.closePromise = this.commitQueue.then(() => {
+            this.state = "closed";
+        });
+        return this.closePromise;
     }
 }
 //# sourceMappingURL=storage.js.map