@namzu/sdk 42.0.2 → 44.0.0

package/dist/store/checkpoint/memory.d.ts

@@ -0,0 +1,27 @@
+import type { CheckpointId } from '../../types/ids/index.js';
+import type { Checkpoint } from '../../types/session/checkpoint.js';
+import { type CheckpointLogView, type CheckpointScope, type CheckpointWriteReceipt, type SessionCheckpointStore } from './contract.js';
+export interface InMemorySessionCheckpointStoreOptions {
+    /** The session log the checkpoints are verified and protected against. */
+    readonly log: CheckpointLogView;
+}
+/**
+ * Process-local {@link SessionCheckpointStore}, keyed by the full
+ * tenant/project/session/turn scope.
+ *
+ * It keeps the serialised bytes rather than the object, so `restore` hashes
+ * exactly what `write` hashed and refuses exactly what the disk store
+ * refuses. It is the parity partner of the disk store and the store an
+ * in-memory session keeps its checkpoints in.
+ */
+export declare class InMemorySessionCheckpointStore implements SessionCheckpointStore {
+    #private;
+    constructor(options: InMemorySessionCheckpointStoreOptions);
+    write(scope: CheckpointScope, checkpoint: Checkpoint): Promise<CheckpointWriteReceipt>;
+    read(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null>;
+    restore(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null>;
+    list(scope: CheckpointScope): Promise<Checkpoint[]>;
+    delete(scope: CheckpointScope, checkpointId: CheckpointId): Promise<void>;
+    prune(scope: CheckpointScope, keepLast: number): Promise<CheckpointId[]>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/store/checkpoint/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/store/checkpoint/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAO3B,MAAM,eAAe,CAAA;AAGtB,MAAM,WAAW,qCAAqC;IACrD,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAA;CAC/B;AAED;;;;;;;;GAQG;AACH,qBAAa,8BAA+B,YAAW,sBAAsB;;gBAKhE,OAAO,EAAE,qCAAqC;IASpD,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmBtF,IAAI,CAAC,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIpF,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkBvF,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IASnD,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAW9E"}

package/dist/store/checkpoint/memory.js

@@ -0,0 +1,80 @@
+import { asCheckpointId } from '../../utils/id.js';
+import { checkWriteOwner, parseStoredCheckpoint, serializeCheckpoint, validateCheckpointScope, verifyCheckpoint, writeReceipt, } from './contract.js';
+import { compareCheckpoints, selectStoredCheckpointsToPrune } from './prune.js';
+/**
+ * Process-local {@link SessionCheckpointStore}, keyed by the full
+ * tenant/project/session/turn scope.
+ *
+ * It keeps the serialised bytes rather than the object, so `restore` hashes
+ * exactly what `write` hashed and refuses exactly what the disk store
+ * refuses. It is the parity partner of the disk store and the store an
+ * in-memory session keeps its checkpoints in.
+ */
+export class InMemorySessionCheckpointStore {
+    #log;
+    /** `tenant/project/session` → checkpoint id → stored text. */
+    #sessions = new Map();
+    constructor(options) {
+        this.#log = options.log;
+    }
+    #documents(scope) {
+        const checked = validateCheckpointScope(scope);
+        return this.#sessions.get([checked.tenantId, checked.projectId, checked.sessionId].join('/'));
+    }
+    async write(scope, checkpoint) {
+        const checked = validateCheckpointScope(scope);
+        const document = checkWriteOwner(checked, checkpoint);
+        const key = [checked.tenantId, checked.projectId, checked.sessionId].join('/');
+        let documents = this.#sessions.get(key);
+        if (!documents) {
+            documents = new Map();
+            this.#sessions.set(key, documents);
+        }
+        if (documents.has(document.checkpointId)) {
+            throw new Error(`Checkpoint ${document.checkpointId} already exists; a checkpoint is never replaced.`);
+        }
+        const text = serializeCheckpoint(document);
+        documents.set(document.checkpointId, text);
+        return writeReceipt(document, text);
+    }
+    async read(scope, checkpointId) {
+        return (await this.#readText(scope, checkpointId))?.checkpoint ?? null;
+    }
+    async restore(scope, checkpointId) {
+        const found = await this.#readText(scope, checkpointId);
+        if (!found)
+            return null;
+        return verifyCheckpoint(this.#log, scope, found.checkpoint, found.text);
+    }
+    async #readText(scope, checkpointId) {
+        const id = asCheckpointId(checkpointId);
+        const text = this.#documents(scope)?.get(id);
+        if (text === undefined)
+            return null;
+        const checkpoint = parseStoredCheckpoint(text, scope, id);
+        // Another turn's checkpoint is not this turn's: absent, as the disk store answers.
+        return checkpoint.turnId === scope.turnId ? { checkpoint, text } : null;
+    }
+    async list(scope) {
+        const documents = this.#documents(scope);
+        if (!documents)
+            return [];
+        return [...documents]
+            .map(([id, text]) => parseStoredCheckpoint(text, scope, id))
+            .filter((checkpoint) => checkpoint.turnId === scope.turnId)
+            .sort(compareCheckpoints);
+    }
+    async delete(scope, checkpointId) {
+        const id = asCheckpointId(checkpointId);
+        if (await this.read(scope, id))
+            this.#documents(scope)?.delete(id);
+    }
+    async prune(scope, keepLast) {
+        const checked = validateCheckpointScope(scope);
+        const doomed = await selectStoredCheckpointsToPrune(this.#log, checked, await this.list(checked), keepLast);
+        for (const id of doomed)
+            await this.delete(checked, id);
+        return doomed;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/store/checkpoint/memory.js.map

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

package/dist/store/checkpoint/prune.d.ts

@@ -0,0 +1,45 @@
+import type { CheckpointId } from '../../types/ids/index.js';
+import type { Checkpoint } from '../../types/session/checkpoint.js';
+import type { CheckpointLogView, CheckpointScope } from './contract.js';
+/** What choosing checkpoints to prune needs to know about each one. */
+export type PrunableSessionCheckpoint = Pick<Checkpoint, 'checkpointId' | 'createdAt'>;
+/**
+ * The checkpoints to delete so that `keepLast` newer ones remain.
+ *
+ * Salvaged from the run-era `selectCheckpointsToPrune`: the candidates are the
+ * oldest `all.length - keepLast`, which keeps the newest `keepLast` (the
+ * turn's resume point) out of reach, and a protected checkpoint among them is
+ * skipped rather than counted.
+ *
+ * A checkpoint is protected when an open decision references it. The run-era
+ * document carried its own `pending` park; a session checkpoint carries none,
+ * because the question lives in the log as a `decision_requested` record with
+ * no `decision_resolved` or `decision_expired` after it. Deleting the
+ * checkpoint such a record names would leave a question somebody may be in
+ * the middle of answering with nothing to resume from. An expired decision is
+ * closed by its own record, so it protects nothing.
+ *
+ * Order is `createdAt`, then `checkpointId`: ids are UUIDv7, so the tiebreak
+ * is also chronological within one millisecond, and the order is total.
+ *
+ * @throws RangeError when `keepLast` is not a nonnegative safe integer.
+ */
+export declare function selectSessionCheckpointsToPrune(checkpoints: readonly PrunableSessionCheckpoint[], keepLast: number, protectedIds?: ReadonlySet<CheckpointId>): CheckpointId[];
+/** Oldest first: `createdAt`, then `checkpointId`. Shared by every store's `list`. */
+export declare function compareCheckpoints(left: PrunableSessionCheckpoint, right: PrunableSessionCheckpoint): number;
+/**
+ * The checkpoints `prune(scope, keepLast)` deletes, from the turn's stored
+ * documents: shared by every store so they choose alike.
+ *
+ * Only a committed checkpoint, one a `checkpoint_written` record names, is
+ * ranked. A document with no such record is inert by design (writes are
+ * unfenced: a stale writer, or a crash between the write and the append,
+ * leaves one behind) and a restore refuses it as `not-recorded`. Counting it
+ * toward `keepLast` would let it stand in for the turn's real resume point
+ * and prune that instead. It is not deleted either: the writer that holds
+ * the lease may be between its write and its append, and the id would go
+ * into a `checkpoint_pruned` record that names a checkpoint no record ever
+ * committed.
+ */
+export declare function selectStoredCheckpointsToPrune(log: CheckpointLogView, scope: CheckpointScope, stored: readonly Checkpoint[], keepLast: number): Promise<CheckpointId[]>;
+//# sourceMappingURL=prune.d.ts.map

package/dist/store/checkpoint/prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../../src/store/checkpoint/prune.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEvE,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,GAAG,WAAW,CAAC,CAAA;AAEtF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,+BAA+B,CAC9C,WAAW,EAAE,SAAS,yBAAyB,EAAE,EACjD,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,WAAW,CAAC,YAAY,CAAa,GACjD,YAAY,EAAE,CAUhB;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,yBAAyB,EAC/B,KAAK,EAAE,yBAAyB,GAC9B,MAAM,CAQR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CACnD,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,EAAE,CAAC,CAezB"}

package/dist/store/checkpoint/prune.js

@@ -0,0 +1,71 @@
+/**
+ * The checkpoints to delete so that `keepLast` newer ones remain.
+ *
+ * Salvaged from the run-era `selectCheckpointsToPrune`: the candidates are the
+ * oldest `all.length - keepLast`, which keeps the newest `keepLast` (the
+ * turn's resume point) out of reach, and a protected checkpoint among them is
+ * skipped rather than counted.
+ *
+ * A checkpoint is protected when an open decision references it. The run-era
+ * document carried its own `pending` park; a session checkpoint carries none,
+ * because the question lives in the log as a `decision_requested` record with
+ * no `decision_resolved` or `decision_expired` after it. Deleting the
+ * checkpoint such a record names would leave a question somebody may be in
+ * the middle of answering with nothing to resume from. An expired decision is
+ * closed by its own record, so it protects nothing.
+ *
+ * Order is `createdAt`, then `checkpointId`: ids are UUIDv7, so the tiebreak
+ * is also chronological within one millisecond, and the order is total.
+ *
+ * @throws RangeError when `keepLast` is not a nonnegative safe integer.
+ */
+export function selectSessionCheckpointsToPrune(checkpoints, keepLast, protectedIds = new Set()) {
+    if (!Number.isSafeInteger(keepLast) || keepLast < 0) {
+        throw new RangeError(`keepLast must be a nonnegative integer, got ${String(keepLast)}`);
+    }
+    if (checkpoints.length <= keepLast)
+        return [];
+    return [...checkpoints]
+        .sort(compareCheckpoints)
+        .slice(0, checkpoints.length - keepLast)
+        .filter((checkpoint) => !protectedIds.has(checkpoint.checkpointId))
+        .map((checkpoint) => checkpoint.checkpointId);
+}
+/** Oldest first: `createdAt`, then `checkpointId`. Shared by every store's `list`. */
+export function compareCheckpoints(left, right) {
+    const byTime = Date.parse(left.createdAt) - Date.parse(right.createdAt);
+    if (byTime !== 0)
+        return byTime;
+    return left.checkpointId < right.checkpointId
+        ? -1
+        : left.checkpointId > right.checkpointId
+            ? 1
+            : 0;
+}
+/**
+ * The checkpoints `prune(scope, keepLast)` deletes, from the turn's stored
+ * documents: shared by every store so they choose alike.
+ *
+ * Only a committed checkpoint, one a `checkpoint_written` record names, is
+ * ranked. A document with no such record is inert by design (writes are
+ * unfenced: a stale writer, or a crash between the write and the append,
+ * leaves one behind) and a restore refuses it as `not-recorded`. Counting it
+ * toward `keepLast` would let it stand in for the turn's real resume point
+ * and prune that instead. It is not deleted either: the writer that holds
+ * the lease may be between its write and its append, and the id would go
+ * into a `checkpoint_pruned` record that names a checkpoint no record ever
+ * committed.
+ */
+export async function selectStoredCheckpointsToPrune(log, scope, stored, keepLast) {
+    if (!Number.isSafeInteger(keepLast) || keepLast < 0) {
+        throw new RangeError(`keepLast must be a nonnegative integer, got ${String(keepLast)}`);
+    }
+    const committed = [];
+    for (const checkpoint of stored) {
+        if ((await log.writtenDocSha256(scope, checkpoint.checkpointId)) !== null) {
+            committed.push(checkpoint);
+        }
+    }
+    return selectSessionCheckpointsToPrune(committed, keepLast, new Set(await log.openDecisionCheckpoints(scope)));
+}
+//# sourceMappingURL=prune.js.map

package/dist/store/checkpoint/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../../src/store/checkpoint/prune.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,+BAA+B,CAC9C,WAAiD,EACjD,QAAgB,EAChB,eAA0C,IAAI,GAAG,EAAE;IAEnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAAC,+CAA+C,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACxF,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,EAAE,CAAA;IAC7C,OAAO,CAAC,GAAG,WAAW,CAAC;SACrB,IAAI,CAAC,kBAAkB,CAAC;SACxB,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,GAAG,QAAQ,CAAC;SACvC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;SAClE,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAA;AAC/C,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CACjC,IAA+B,EAC/B,KAAgC;IAEhC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IACvE,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAA;IAC/B,OAAO,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY;QAC5C,CAAC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY;YACvC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CAAA;AACN,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CACnD,GAAsB,EACtB,KAAsB,EACtB,MAA6B,EAC7B,QAAgB;IAEhB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAAC,+CAA+C,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACxF,CAAC;IACD,MAAM,SAAS,GAAiB,EAAE,CAAA;IAClC,KAAK,MAAM,UAAU,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC3E,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC3B,CAAC;IACF,CAAC;IACD,OAAO,+BAA+B,CACrC,SAAS,EACT,QAAQ,EACR,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CACjD,CAAA;AACF,CAAC"}

package/dist/store/config/index.d.ts

@@ -30,7 +30,7 @@ export declare class InMemoryConfigOverrideStore implements ConfigOverrideStore
  * Whole-file rather than append-and-replay: this holds tens of small
  * objects, not a log, and a rewrite is the shape a human can open and read.
  * A corrupt file loads as empty rather than throwing — a config override is
- * a preference, and refusing to start a run because one is unreadable would
+ * a preference, and refusing to start a turn because one is unreadable would
  * make a convenience into an outage.
  */
 export declare class DiskConfigOverrideStore implements ConfigOverrideStore {

package/dist/store/config/index.js

@@ -16,7 +16,7 @@ export class InMemoryConfigOverrideStore {
  * Whole-file rather than append-and-replay: this holds tens of small
  * objects, not a log, and a rewrite is the shape a human can open and read.
  * A corrupt file loads as empty rather than throwing — a config override is
- * a preference, and refusing to start a run because one is unreadable would
+ * a preference, and refusing to start a turn because one is unreadable would
  * make a convenience into an outage.
  */
 export class DiskConfigOverrideStore {

package/dist/store/evidence/disk.d.ts

@@ -1,11 +1,28 @@
-import type { DiskRunEvidenceOptions, RunEvidenceSource, RunTextEvidenceSource } from './types.js';
+import type { SessionEvidenceSource, SessionEvidenceSourceOptions, SessionTextEvidenceSource } from './types.js';
 /**
- * @experimental Bounded, authenticated disk index over one explicitly authorized run.
- * Closed by default; snapshot mode permits nonterminal metadata without assuming a dead writer.
- * The host owns authorization and the private directories. Stat changes invalidate addresses;
- * individual record/chunk digests detect changed bytes. This is not a hostile filesystem sandbox.
+ * A fixed end of the log a source reads up to: a record the capturing writer
+ * vouches for. Appends after it do not change what the source sees.
  */
-export declare function createDiskRunTextEvidenceSource(options: DiskRunEvidenceOptions): RunTextEvidenceSource;
-/** @experimental Tool-only view of the shared invocation text index. */
-export declare function createDiskRunEvidenceSource(options: DiskRunEvidenceOptions): RunEvidenceSource;
+export interface EvidenceAnchor {
+    readonly seq: number;
+    readonly offset: number;
+    readonly length: number;
+    readonly sha256: string;
+}
+/**
+ * @experimental Bounded, authenticated evidence over one explicitly authorized
+ * session log, or one turn of it. Closed by default (no active turn in scope);
+ * snapshot mode also reads a session whose turn is running, without assuming
+ * its writer is dead. The host owns authorization and the log's directory.
+ * Changes to the log invalidate addresses; record and chunk digests detect
+ * changed bytes. This is not a hostile filesystem sandbox.
+ */
+export declare function createSessionTextEvidenceSource(options: SessionEvidenceSourceOptions): SessionTextEvidenceSource;
+/**
+ * @internal A text source anchored at a record the writer holds: appends
+ * after it neither invalidate its addresses nor become visible to it.
+ */
+export declare function createAnchoredSessionTextEvidenceSource(options: SessionEvidenceSourceOptions, anchor: EvidenceAnchor): SessionTextEvidenceSource;
+/** @experimental Tool-only view of the shared session text index. */
+export declare function createSessionEvidenceSource(options: SessionEvidenceSourceOptions): SessionEvidenceSource;
 //# sourceMappingURL=disk.d.ts.map

package/dist/store/evidence/disk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../../src/store/evidence/disk.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EACX,sBAAsB,EAGtB,iBAAiB,EAIjB,qBAAqB,EACrB,MAAM,YAAY,CAAA;AAwDnB;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC9C,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAEvB;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,sBAAsB,GAAG,iBAAiB,CAqB9F"}
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../../src/store/evidence/disk.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAGX,qBAAqB,EACrB,4BAA4B,EAI5B,yBAAyB,EACzB,MAAM,YAAY,CAAA;AAyDnB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC9C,OAAO,EAAE,4BAA4B,GACnC,yBAAyB,CAE3B;AAED;;;GAGG;AACH,wBAAgB,uCAAuC,CACtD,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,cAAc,GACpB,yBAAyB,CAE3B;AAED,qEAAqE;AACrE,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,4BAA4B,GACnC,qBAAqB,CAqBvB"}

package/dist/store/evidence/disk.js

@@ -1,9 +1,9 @@
 import { lstat } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { z } from 'zod';
 import { EVIDENCE_CHUNK_BYTES, digest, mayContain, mayContainToken } from './format.js';
 import { entrySchema, evidenceSeal, indexPage, positionSchema, } from './index-page.js';
-import { EvidencePageLimit, PAGE_BYTES, RECORD_BYTES, decode, openEvidence, readBytes, readSmall, stamp, } from './io.js';
+import { EvidencePageLimit, PAGE_BYTES, RECORD_BYTES, decode, openEvidence, readBytes, stamp, } from './io.js';
 import { passageMatcher, passagesInWindow } from './passages.js';
 import { evidenceSearchInput, evidenceTermRefinement, evidenceTermsSchema } from './search-input.js';
 import { evidenceExclusionsKey, evidenceExclusionsSchema, excludesSuccessfulTool, } from './selection.js';
@@ -14,7 +14,7 @@ const scopeSchema = z
     tenantId: z.string().uuid(),
     projectId: z.string().uuid(),
     sessionId: z.string().uuid(),
-    runId: z.string().uuid(),
+    turnId: z.string().uuid().optional(),
 })
     .strict();
 const cursorSchema = z.object({
@@ -46,7 +46,7 @@ const pointerSchema = entrySchema.pick({
     part: true,
 });
 const addressSchema = z.object({ kind: z.literal('text'), entry: pointerSchema });
-/** Ignore an uncommitted tail in a nonterminal snapshot without repairing the writer's file. */
+/** Ignore an uncommitted tail in a snapshot without repairing the writer's file. */
 async function completePrefix(handle, size, budget) {
     if ((await readBytes(handle, size - 1, 1, budget))[0] === 10)
         return size;
@@ -61,20 +61,29 @@ async function completePrefix(handle, size, budget) {
         end = start;
     }
     if (floor === 0)
-        throw new Error('Transcript has no complete recorded evidence.');
-    throw new Error('Incomplete transcript tail exceeds the bounded record size.');
+        throw new Error('The session log has no complete recorded evidence.');
+    throw new Error('Incomplete session log tail exceeds the bounded record size.');
 }
 /**
- * @experimental Bounded, authenticated disk index over one explicitly authorized run.
- * Closed by default; snapshot mode permits nonterminal metadata without assuming a dead writer.
- * The host owns authorization and the private directories. Stat changes invalidate addresses;
- * individual record/chunk digests detect changed bytes. This is not a hostile filesystem sandbox.
+ * @experimental Bounded, authenticated evidence over one explicitly authorized
+ * session log, or one turn of it. Closed by default (no active turn in scope);
+ * snapshot mode also reads a session whose turn is running, without assuming
+ * its writer is dead. The host owns authorization and the log's directory.
+ * Changes to the log invalidate addresses; record and chunk digests detect
+ * changed bytes. This is not a hostile filesystem sandbox.
  */
-export function createDiskRunTextEvidenceSource(options) {
+export function createSessionTextEvidenceSource(options) {
     return createSource(options, 'text');
 }
-/** @experimental Tool-only view of the shared invocation text index. */
-export function createDiskRunEvidenceSource(options) {
+/**
+ * @internal A text source anchored at a record the writer holds: appends
+ * after it neither invalidate its addresses nor become visible to it.
+ */
+export function createAnchoredSessionTextEvidenceSource(options, anchor) {
+    return createSource(options, 'text', anchor);
+}
+/** @experimental Tool-only view of the shared session text index. */
+export function createSessionEvidenceSource(options) {
     const source = createSource(options, 'tools');
     const tool = (value) => {
         if (value.toolName === undefined || value.isError === undefined)
@@ -93,7 +102,58 @@ export function createDiskRunEvidenceSource(options) {
         },
     });
 }
-function createSource(options, mode) {
+/**
+ * The first record of a session log (its `session_started`) and whether the
+ * scope is closed: no turn of the session active, or — for a scope narrowed
+ * to one turn — that turn settled.
+ */
+async function sessionState(handle, size, scope) {
+    const unmetered = { bytes: 0, limit: Number.MAX_SAFE_INTEGER };
+    let first;
+    let active;
+    let turnClosed = false;
+    let buffered = Buffer.alloc(0);
+    let offset = 0;
+    while (offset < size || buffered.length > 0) {
+        let newline = buffered.indexOf(10);
+        if (newline < 0) {
+            if (offset >= size)
+                break;
+            if (buffered.length >= RECORD_BYTES)
+                throw new Error('Session log record exceeds 4 MiB.');
+            const count = Math.min(1 << 20, size - offset);
+            buffered = Buffer.concat([buffered, await readBytes(handle, offset, count, unmetered)]);
+            offset += count;
+            continue;
+        }
+        const raw = buffered.subarray(0, newline + 1);
+        buffered = buffered.subarray(newline + 1);
+        newline = -1;
+        const record = JSON.parse(decode(raw));
+        if (!first) {
+            if (record.type !== 'session_started' ||
+                record.sessionId !== scope.sessionId ||
+                record.projectId !== scope.projectId ||
+                (record.tenantId !== undefined && record.tenantId !== scope.tenantId)) {
+                throw new Error('The session log does not belong to the authorized scope.');
+            }
+            first = Buffer.from(raw);
+            continue;
+        }
+        if (record.type === 'turn_started')
+            active = record.turnId;
+        if (record.type === 'turn_completed' || record.type === 'turn_failed') {
+            if (active === record.turnId)
+                active = undefined;
+            if (record.turnId === scope.turnId)
+                turnClosed = true;
+        }
+    }
+    if (!first)
+        throw new Error('The session log is empty; evidence is incomplete.');
+    return { first, closed: scope.turnId !== undefined ? turnClosed : active === undefined };
+}
+function createSource(options, mode, anchor) {
     const consistency = z.enum(['closed', 'snapshot']).parse(options.consistency ?? 'closed');
     const maxReadBytes = z
         .number()
@@ -102,8 +162,10 @@ function createSource(options, mode) {
         .max(PAGE_BYTES)
         .parse(options.maxReadBytes ?? PAGE_BYTES);
     const scope = Object.freeze(scopeSchema.parse(options.scope));
-    const runDir = resolve(options.runDir);
-    const indexDir = resolve(options.indexDir);
+    const logPath = resolve(options.logPath);
+    if (!logPath.endsWith('.jsonl'))
+        throw new Error('A session log path ends in .jsonl.');
+    const sessionDir = logPath.slice(0, -'.jsonl'.length);
     const scopeKey = digest(JSON.stringify(scope));
     async function access(signal, requestedBytes, action) {
         const budget = {
@@ -112,38 +174,40 @@ function createSource(options, mode) {
             signal,
         };
         signal?.throwIfAborted();
-        const metaPath = join(runDir, 'run.json');
-        const metaStamp = stamp(await lstat(metaPath));
-        const metaBytes = await readSmall(metaPath, budget, 512 * 1024);
-        if (metaStamp !== stamp(await lstat(metaPath)))
-            throw new Error('Run metadata changed during retrieval.');
-        const meta = JSON.parse(decode(metaBytes));
-        const terminal = ['completed', 'failed', 'cancelled'].includes(meta.status);
-        const readable = terminal ||
-            (consistency === 'snapshot' && ['idle', 'pending', 'running'].includes(meta.status));
-        if (meta.id !== scope.runId ||
-            !readable ||
-            JSON.stringify(scopeSchema.parse(meta.metadata?.scope)) !== JSON.stringify(scope))
-            throw new Error(consistency === 'closed'
-                ? 'Evidence run is not closed or does not belong to the authorized scope.'
-                : 'Evidence run does not satisfy snapshot consistency or its authorized scope.');
-        const path = join(runDir, 'transcript.jsonl');
-        const handle = await openEvidence(path);
+        const handle = await openEvidence(logPath);
         try {
             const before = await handle.stat();
             if (before.size === 0)
-                throw new Error('Transcript is empty; evidence is incomplete.');
-            const size = consistency === 'snapshot' && !terminal
-                ? await completePrefix(handle, before.size, budget)
-                : before.size;
-            const sourceKey = digest(`${consistency === 'snapshot' ? 'snapshot-v1:' : ''}${mode === 'text' ? 'text-v2:' : ''}${scopeKey}:${stamp(before)}:${digest(metaBytes)}`);
-            const seal = await evidenceSeal(indexDir, scopeKey, sourceKey, budget);
-            const value = await action(handle, size, seal, sourceKey, budget, !terminal);
+                throw new Error('The session log is empty; evidence is incomplete.');
+            let size;
+            if (anchor) {
+                size = anchor.offset + anchor.length;
+                if (size > before.size)
+                    throw new Error('The session log is shorter than its anchor.');
+            }
+            else {
+                size =
+                    consistency === 'snapshot'
+                        ? await completePrefix(handle, before.size, budget)
+                        : before.size;
+            }
+            const state = await sessionState(handle, size, scope);
+            if (!state.closed && consistency === 'closed') {
+                throw new Error('Evidence scope has an active turn; it is not closed.');
+            }
+            const anchorKey = anchor ? await verifyAnchor(handle, anchor) : undefined;
+            const sourceKey = digest(`session-v1:${consistency}:${mode}:${scopeKey}:${anchorKey ?? stamp(before)}`);
+            const seal = evidenceSeal(state.first, sourceKey);
+            const value = await action(handle, size, seal, sourceKey, budget, !state.closed);
             signal?.throwIfAborted();
-            if (stamp(before) !== stamp(await handle.stat()) ||
-                stamp(before) !== stamp(await lstat(path)) ||
-                metaStamp !== stamp(await lstat(metaPath)))
+            if (anchor) {
+                if ((await verifyAnchor(handle, anchor)) !== anchorKey)
+                    throw new Error('Evidence source changed during retrieval.');
+            }
+            else if (stamp(before) !== stamp(await handle.stat()) ||
+                stamp(before) !== stamp(await lstat(logPath))) {
                 throw new Error('Evidence source changed during retrieval.');
+            }
             return value;
         }
         finally {
@@ -190,8 +254,8 @@ function createSource(options, mode) {
                 : terms
                     ? 'search-terms'
                     : 'search';
-            return access(signal, input.maxReadBytes, async (handle, size, seal, sourceKey, budget, nonterminal) => {
-                const readSource = createTextSourceReader(handle, runDir, scope.runId, budget);
+            return access(signal, input.maxReadBytes, async (handle, size, seal, _sourceKey, budget, nonterminal) => {
+                const readSource = createTextSourceReader(handle, sessionDir, scope.sessionId, budget);
                 const cursor = input.cursor
                     ? cursorSchema.parse(seal.unpack(input.cursor))
                     : {
@@ -223,7 +287,28 @@ function createSource(options, mode) {
                 // with the narrower key at exactly the same archive position.
                 if (refined)
                     cursor.termsKey = refined.termsKey;
-                const { page, cacheHit } = await indexPage(handle, size, scope.runId, cursor.position, seal, sourceKey, budget);
+                let indexed;
+                try {
+                    indexed = await indexPage(handle, size, scope.sessionId, cursor.position, budget);
+                }
+                catch (error) {
+                    if (!(error instanceof EvidencePageLimit))
+                        throw error;
+                    // This operation's allowance cannot index the next page (one
+                    // record can be larger than it). Nothing is claimed about the
+                    // records there; the same position is offered again.
+                    return {
+                        scope,
+                        matches: [],
+                        nextCursor: seal.pack({ ...cursor }),
+                        scannedBytes: budget.bytes,
+                        indexedRecords: 0,
+                        cacheHit: false,
+                        incomplete: true,
+                        unavailable: [],
+                    };
+                }
+                const { page, cacheHit } = indexed;
                 const matches = [];
                 const unavailable = [];
                 let partial = false;
@@ -238,6 +323,7 @@ function createSource(options, mode) {
                     if (!entry)
                         throw new Error('Invalid index entry.');
                     if ((mode === 'tools' && entry.source !== 'tool_completed') ||
+                        (scope.turnId !== undefined && entry.turnId !== scope.turnId) ||
                         (input.seq !== undefined && entry.seq !== input.seq) ||
                         (input.part !== undefined && entry.part !== input.part)) {
                         entryIndex++;
@@ -355,13 +441,28 @@ function createSource(options, mode) {
                 .parse(options);
             return access(signal, input.maxReadBytes, async (handle, _size, seal, _sourceKey, budget) => {
                 const pointer = addressSchema.parse(seal.unpack(input.address)).entry;
-                const source = await createTextSourceReader(handle, runDir, scope.runId, budget)(pointer);
+                const source = await createTextSourceReader(handle, sessionDir, scope.sessionId, budget)(pointer);
                 const entry = source.entry;
                 if (mode === 'tools' && entry.source !== 'tool_completed')
                     throw new Error('Not tool evidence.');
+                if (scope.turnId !== undefined && entry.turnId !== scope.turnId)
+                    throw new Error('Evidence is outside the authorized turn.');
                 return readTextPage(source, scope, input.byteOffset ?? 0, budget);
             });
         },
     });
 }
+/** The anchor record must still hold the bytes the writer vouched for. */
+async function verifyAnchor(handle, anchor) {
+    const bytes = await readBytes(handle, anchor.offset, anchor.length, {
+        bytes: 0,
+        limit: Number.MAX_SAFE_INTEGER,
+    });
+    if (digest(bytes) !== anchor.sha256)
+        throw new Error('The session log changed below its anchor.');
+    const record = JSON.parse(decode(bytes));
+    if (record.seq !== anchor.seq)
+        throw new Error('The session log changed below its anchor.');
+    return `${anchor.seq}:${anchor.sha256}`;
+}
 //# sourceMappingURL=disk.js.map