@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/native/session/session.js

@@ -10,84 +10,23 @@ import { NaxError } from "#src/infra/index";
 import { createSpinBreaker } from "#src/infra/spin-breaker/index";
 import { NATIVE_AGENT } from "../models.js";
 import { nativeSessionId } from "../session-affinity.js";
-import { deleteTranscript, pruneRetainedTranscripts, retainTranscript } from "./transcript-store.js";
-/**
- * Session name -> transcript directory, so sendTurn and close can find it.
- *
- * Cleared by every close path — `closeNativeSession` (in-process) and the
- * adapter's `closePhysicalSession` (run teardown, which only has the name) —
- * through the shared `clearNativeSessionState`. A caller that opens a session
- * and never closes it (e.g. an early return, or a thrown error between open and
- * close) still leaks an entry for the lifetime of the process. Harmless in
- * practice (it is a small in-memory map keyed by session name, not a handle
- * to a real resource), but worth knowing when debugging a growing map.
- */
-export const nativeTranscriptDirs = new Map();
-/**
- * Session name -> the root whose `.nax/scratchpad/` holds this session's
- * spill files (US-003).
- *
- * Recorded from the session's `workdir` at open — the same root the coding
- * tools are confined to — so a spilled body is reachable through
- * `ScratchpadRead` with the relative path the truncation marker names. Same
- * lifecycle as the maps above: set on open, cleared on close.
- */
-export const nativeSessionScratchpadRoots = new Map();
-/**
- * Session name -> timeoutSeconds, so sendTurn can bound each `complete()`
- * call with a deadline (whole-branch review finding 4). Same lifecycle as
- * `nativeTranscriptDirs` — populated on open, cleared on close only.
- */
-export const nativeSessionTimeouts = new Map();
-/**
- * Session name -> the runtime hooks handed to openSession. SessionManager
- * passes both (manager.ts, openSession) and the native adapter previously
- * ignored them, which is why the idle watchdog never covered native. Same
- * lifecycle as `nativeTranscriptDirs`: set on open, cleared on close only.
- */
-export const nativeSessionStreamHooks = new Map();
-/**
- * Session names whose most recent turn failed.
- *
- * `AgentAdapter.closeSession(handle)` carries no failure signal, so the close
- * cannot tell a finished session from a broken one and passed `failed: false`
- * for both -- deleting the transcript of exactly the session whose history the
- * retry needs and a human would read (nax#1838). Rather than widen the adapter
- * interface for one transport, the turn records what it knows here and the
- * close reads it. Same lifecycle as the maps above: written per turn, cleared
- * on close.
- *
- * A later successful turn clears the mark. "Failed" describes the session's
- * current state, not whether it ever stumbled -- a session that recovered and
- * finished is still cleaned up.
- */
-export const nativeSessionFailed = new Set();
-/**
- * Session name -> the identity that owns this session's transcript (nax#1877).
- *
- * Read by `runNativeTurn` on both the load and the save, so a transcript left
- * behind by an abandoned invocation of the same deterministic session name is
- * recognised as foreign rather than silently resumed. Same lifecycle as the
- * maps above: set on open, cleared on close.
- */
-export const nativeSessionTranscriptOwners = new Map();
-/** Session name -> resolved compaction settings. Same lifecycle as the maps above. */
-export const nativeSessionCompaction = new Map();
-/**
- * Session name -> resolved transport-fault retry settings (nax#1870). Same
- * lifecycle as the maps above: set on open, cleared on close.
- */
-export const nativeSessionTransportRetry = new Map();
-/**
- * Session name -> live `SpinBreaker` instance (nax#2013, lifetime extended in
- * nax#2047). Constructed once at open so the cumulative counter survives
- * across `runNativeTurn` calls — a fix round that opens a new turn on the
- * same `handle.id` must inherit the prior turn's evidence rather than start
- * fresh. Same lifecycle as `nativeSessionTransportRetry`: set on open, cleared
- * on close.
- */
-export const nativeSessionSpinBreaker = new Map();
-export const nativeSessionLastUsage = new Map();
+import { createFileTranscriptStore } from "./transcript-store.js";
+export function createNativeSessionState() {
+    return {
+        transcriptDirs: new Map(),
+        transcripts: new Map(),
+        scratchpadRoots: new Map(),
+        timeouts: new Map(),
+        streamHooks: new Map(),
+        failed: new Set(),
+        transcriptOwners: new Map(),
+        compaction: new Map(),
+        transportRetry: new Map(),
+        spinBreakers: new Map(),
+        lastUsage: new Map(),
+        systemPrompts: new Map(),
+    };
+}
 /**
  * The persisted anchor a turn on `model` may use. Prefix stability is a
  * property of (model, prefix) (P3 spec 3.3): an anchor measured under a
@@ -95,50 +34,90 @@ export const nativeSessionLastUsage = new Map();
  * so it is dropped here rather than mis-sizing the next compaction decision.
  * An entry or a turn with no model makes no claim — the store's own rule.
  */
-export function sessionAnchorFor(sessionName, model) {
-    const entry = nativeSessionLastUsage.get(sessionName);
+export function sessionAnchorFor(state, sessionName, model) {
+    const entry = state.lastUsage.get(sessionName);
     if (entry?.model === undefined || model === undefined || entry.model === model)
         return entry;
-    nativeSessionLastUsage.delete(sessionName);
+    state.lastUsage.delete(sessionName);
     return undefined;
 }
 /** Records how the session's latest turn ended, for `closeNativeSession`. */
-export function markNativeTurnOutcome(sessionName, failed) {
+export function markNativeTurnOutcome(state, sessionName, failed) {
     if (failed)
-        nativeSessionFailed.add(sessionName);
+        state.failed.add(sessionName);
     else
-        nativeSessionFailed.delete(sessionName);
+        state.failed.delete(sessionName);
+}
+/**
+ * The session's transcript. A state seeded with only a transcript directory
+ * (tests that drive `runNativeTurn` without opening) resolves to the file store
+ * over it; `openNativeSession` always records an entry, so production does not
+ * take that path.
+ */
+export function sessionTranscriptFor(state, sessionName) {
+    const opened = state.transcripts.get(sessionName);
+    if (opened !== undefined)
+        return opened;
+    const dir = state.transcriptDirs.get(sessionName);
+    return dir === undefined ? undefined : { store: createFileTranscriptStore(dir), retainOnClose: false };
 }
-export async function openNativeSession(name, opts) {
+function openTranscriptStore(name, opts) {
+    if (opts.transcriptDir && opts.transcriptStore !== undefined) {
+        throw new NaxError(`native session "${name}" opened with both a transcriptDir and a transcriptStore`, "NATIVE_TRANSCRIPT_SOURCE_CONFLICT", { stage: "native-session" });
+    }
+    if (opts.transcriptStore !== undefined)
+        return opts.transcriptStore;
     // Never defaulted. An adapter that picks its own path writes a transcript
     // somewhere nobody looks, which is #1794's empty-packageDir bug one layer up.
     if (!opts.transcriptDir) {
-        throw new NaxError(`native session "${name}" opened without a transcriptDir`, "NATIVE_TRANSCRIPT_DIR_MISSING", {
-            stage: "native-session",
-        });
+        throw new NaxError(`native session "${name}" opened without a transcriptDir or transcriptStore`, "NATIVE_TRANSCRIPT_DIR_MISSING", { stage: "native-session" });
     }
-    nativeTranscriptDirs.set(name, opts.transcriptDir);
-    nativeSessionTimeouts.set(name, opts.timeoutSeconds);
-    nativeSessionScratchpadRoots.set(name, opts.workdir);
+    return createFileTranscriptStore(opts.transcriptDir);
+}
+/**
+ * Records, or clears, the session's system prompt at open. A helper so that
+ * openNativeSession gains no branch.
+ */
+function recordSystemPrompt(state, name, systemPrompt) {
+    if (systemPrompt === undefined)
+        state.systemPrompts.delete(name);
+    else
+        state.systemPrompts.set(name, systemPrompt);
+}
+/** The request field for the session's system prompt: `{ system }`, or `{}` when it has none. */
+export function systemFieldFor(state, sessionName) {
+    const system = state.systemPrompts.get(sessionName);
+    return system === undefined ? {} : { system };
+}
+export async function openNativeSession(state, name, opts) {
+    const store = openTranscriptStore(name, opts);
+    if (opts.transcriptDir)
+        state.transcriptDirs.set(name, opts.transcriptDir);
+    else
+        state.transcriptDirs.delete(name);
+    state.transcripts.set(name, { store, retainOnClose: opts.retainOnClose === true });
+    state.timeouts.set(name, opts.timeoutSeconds);
+    state.scratchpadRoots.set(name, opts.workdir);
     if (opts.transcriptOwner !== undefined)
-        nativeSessionTranscriptOwners.set(name, opts.transcriptOwner);
+        state.transcriptOwners.set(name, opts.transcriptOwner);
     else
-        nativeSessionTranscriptOwners.delete(name);
+        state.transcriptOwners.delete(name);
+    recordSystemPrompt(state, name, opts.systemPrompt);
     // `resume` is SessionManager's "this name already has a descriptor in this
     // process" signal, and it had no consumer on this transport (nax#1877) — a
     // native session resumed whatever transcript happened to be on disk. Honouring
-    // it here is the flag's documented contract; the owner check in loadTranscript
+    // it here is the flag's documented contract; the owner check in historyFromTranscript
     // is what covers the cases `resume` cannot see (a same-process re-entry into a
     // stage, and a process that died without closing anything).
     if (opts.resume !== true)
-        await deleteTranscript(opts.transcriptDir, name);
+        await store.delete(name);
     if (opts.compaction !== undefined)
-        nativeSessionCompaction.set(name, opts.compaction);
+        state.compaction.set(name, opts.compaction);
     if (opts.transportRetry !== undefined)
-        nativeSessionTransportRetry.set(name, opts.transportRetry);
+        state.transportRetry.set(name, opts.transportRetry);
     if (opts.spinBreaker !== undefined)
-        nativeSessionSpinBreaker.set(name, createSpinBreaker(opts.spinBreaker));
-    nativeSessionStreamHooks.set(name, {
+        state.spinBreakers.set(name, createSpinBreaker(opts.spinBreaker));
+    state.streamHooks.set(name, {
         ...(opts.onStreamActivity !== undefined ? { onStreamActivity: opts.onStreamActivity } : {}),
         ...(opts.onActiveCall !== undefined ? { onActiveCall: opts.onActiveCall } : {}),
     });
@@ -156,7 +135,7 @@ export async function openNativeSession(name, opts) {
     };
 }
 /**
- * Clear every module-level entry for one session name.
+ * Clear every state entry for one session name.
  *
  * Extracted so both close paths share one source of truth. `closeNativeSession`
  * has a `SessionHandle`; the adapter's `closePhysicalSession` gets only the
@@ -165,44 +144,45 @@ export async function openNativeSession(name, opts) {
  * is that name — but the signatures are not interchangeable, so this helper is
  * string-keyed rather than reconstructed into a synthetic handle.
  */
-export function clearNativeSessionState(sessionName) {
-    nativeTranscriptDirs.delete(sessionName);
-    nativeSessionTimeouts.delete(sessionName);
-    nativeSessionScratchpadRoots.delete(sessionName);
-    nativeSessionTranscriptOwners.delete(sessionName);
-    nativeSessionStreamHooks.delete(sessionName);
-    nativeSessionFailed.delete(sessionName);
-    nativeSessionCompaction.delete(sessionName);
-    nativeSessionTransportRetry.delete(sessionName);
-    nativeSessionSpinBreaker.delete(sessionName);
-    nativeSessionLastUsage.delete(sessionName);
+export function clearNativeSessionState(state, sessionName) {
+    state.transcriptDirs.delete(sessionName);
+    state.transcripts.delete(sessionName);
+    state.timeouts.delete(sessionName);
+    state.scratchpadRoots.delete(sessionName);
+    state.transcriptOwners.delete(sessionName);
+    state.streamHooks.delete(sessionName);
+    state.failed.delete(sessionName);
+    state.compaction.delete(sessionName);
+    state.transportRetry.delete(sessionName);
+    state.spinBreakers.delete(sessionName);
+    state.lastUsage.delete(sessionName);
+    state.systemPrompts.delete(sessionName);
 }
 /**
  * Kept on failure, deleted on success. Every Phase B op is lifetime "fresh", so
- * the transcript survives exactly when it is worth reading. The kept-on-failure
- * set is otherwise unbounded, so a failed close also prunes the feature's
- * `sessions/` directory down to `MAX_RETAINED_TRANSCRIPTS` (ADR-028 section 3).
+ * the transcript survives exactly when it is worth reading. Keeping is the
+ * store's `retainFailed`; the file store's also prunes the feature's
+ * `sessions/` directory down to `MAX_RETAINED_TRANSCRIPTS` (ADR-028 section 3),
+ * since the kept-on-failure set is otherwise unbounded. A session opened with
+ * `retainOnClose` skips both: its live document stays resumable.
  */
-export async function closeNativeSession(handle, failed) {
-    const dir = nativeTranscriptDirs.get(handle.id);
+export async function closeNativeSession(state, handle, failed) {
+    const transcript = sessionTranscriptFor(state, handle.id);
     // An explicit argument wins; otherwise the last turn's own verdict decides.
     // The adapter passes nothing, because its interface has no failure signal.
-    const treatAsFailed = failed ?? nativeSessionFailed.has(handle.id);
+    const treatAsFailed = failed ?? state.failed.has(handle.id);
     try {
-        if (dir !== undefined) {
-            if (treatAsFailed) {
-                // Retain for a human, out of reach of the next session of this name.
-                await retainTranscript(dir, handle.id);
-                await pruneRetainedTranscripts(dir);
-            }
-            else {
-                await deleteTranscript(dir, handle.id);
-            }
+        if (transcript !== undefined && !transcript.retainOnClose) {
+            // Retain for a human, out of reach of the next session of this name.
+            if (treatAsFailed)
+                await transcript.store.retainFailed(handle.id);
+            else
+                await transcript.store.delete(handle.id);
         }
     }
     finally {
         // The deletes must run even when the transcript I/O throws: a failed
         // cleanup step is no reason to strand the session's other state.
-        clearNativeSessionState(handle.id);
+        clearNativeSessionState(state, handle.id);
     }
 }

package/dist/native/session/transcript-identity.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Who may resume a transcript, applied by the loop to whatever document any
+ * `TranscriptStore` returns (S3 spec 5.5), so the identity rules hold for every
+ * store rather than only the file store.
+ */
+import type { ConversationMessage } from "@nathapp/nax-ai";
+import type { TranscriptDoc } from "./transcript-types.ts";
+/**
+ * Who may resume a transcript. `owner` is the op invocation (nax#1877); `model`
+ * is the native model that wrote it (nax#2150, P3 spec 8.3). A field the caller
+ * leaves undefined makes no claim, so non-op callers and tests read whatever is
+ * there.
+ */
+export interface TranscriptIdentity {
+    readonly owner?: string;
+    readonly model?: string;
+}
+/**
+ * The model half of `TranscriptIdentity`: the native `provider/model` id with
+ * the reasoning-effort suffix stripped. A thinking signature binds to the
+ * model, not to the effort — pi-ai's own `isSameModel` compares
+ * provider/api/model for the same reason. `parseModelSpec`, not
+ * `parseNativeModel`: this must never throw.
+ */
+export declare function transcriptModelIdentity(rawModel: string | undefined): string | undefined;
+/**
+ * The history a session may resume from a loaded document (nax#1877, nax#2150).
+ * An unknown `schemaVersion` fails the turn for the same reason
+ * `TRANSCRIPT_CORRUPT` does: silently starting over would drop history the
+ * conversation depends on. Both checks run before the owner/model check, so a
+ * document this build cannot read fails even when it would be foreign: the
+ * reader cannot trust the identity fields of a shape it does not know.
+ */
+export declare function historyFromTranscript(doc: TranscriptDoc | null, identity: TranscriptIdentity, sessionName: string): readonly ConversationMessage[];
+/**
+ * The document the loop saves. Key order is owner, model, savedAt, messages:
+ * the file store writes it as-is, and nax's transcript bytes depend on that order.
+ */
+export declare function transcriptDocFor(messages: readonly ConversationMessage[], identity: TranscriptIdentity): TranscriptDoc;

package/dist/native/session/transcript-identity.js

@@ -0,0 +1,81 @@
+/**
+ * Who may resume a transcript, applied by the loop to whatever document any
+ * `TranscriptStore` returns (S3 spec 5.5), so the identity rules hold for every
+ * store rather than only the file store.
+ */
+import { getLogger, NaxError } from "#src/infra/index";
+import { parseModelSpec } from "../models.js";
+/**
+ * The model half of `TranscriptIdentity`: the native `provider/model` id with
+ * the reasoning-effort suffix stripped. A thinking signature binds to the
+ * model, not to the effort — pi-ai's own `isSameModel` compares
+ * provider/api/model for the same reason. `parseModelSpec`, not
+ * `parseNativeModel`: this must never throw.
+ */
+export function transcriptModelIdentity(rawModel) {
+    return rawModel === undefined ? undefined : parseModelSpec(rawModel).model;
+}
+/**
+ * Another invocation's history (nax#1877) or another model's (nax#2150, P3
+ * spec 8.3(c)) reads as a new conversation. An ABSENT document model reads,
+ * unlike an absent owner: every native production turn records one (the
+ * adapter parses the model before the loop runs), so an absent field is a
+ * pre-upgrade file — which the owner check already keeps out of new processes.
+ * An owner-less document (including a pre-#1877 bare-array file) is foreign to
+ * a reader that has an owner: the cost is one re-exploration, where inheriting
+ * it silently bills a conversation this session never had.
+ */
+function isForeignTranscript(doc, identity, sessionName) {
+    const { owner, model } = identity;
+    if (owner !== undefined && doc.owner !== owner) {
+        getLogger().debug("native-session", "Ignoring a transcript owned by another invocation", {
+            sessionName,
+            storedOwner: doc.owner,
+            owner,
+        });
+        return true;
+    }
+    if (model !== undefined && doc.model !== undefined && doc.model !== model) {
+        getLogger().debug("native-session", "Ignoring a transcript written by another model", {
+            sessionName,
+            storedModel: doc.model,
+            model,
+        });
+        return true;
+    }
+    return false;
+}
+/**
+ * The history a session may resume from a loaded document (nax#1877, nax#2150).
+ * An unknown `schemaVersion` fails the turn for the same reason
+ * `TRANSCRIPT_CORRUPT` does: silently starting over would drop history the
+ * conversation depends on. Both checks run before the owner/model check, so a
+ * document this build cannot read fails even when it would be foreign: the
+ * reader cannot trust the identity fields of a shape it does not know.
+ */
+export function historyFromTranscript(doc, identity, sessionName) {
+    if (doc === null)
+        return [];
+    const version = doc.schemaVersion;
+    if (version !== undefined && version !== 1) {
+        throw new NaxError(`transcript for session "${sessionName}" has unsupported schemaVersion ${String(version)}`, "TRANSCRIPT_SCHEMA_UNSUPPORTED", { stage: "native-session" });
+    }
+    if (!Array.isArray(doc.messages)) {
+        throw new NaxError(`transcript for session "${sessionName}" is unreadable: messages is not an array`, "TRANSCRIPT_CORRUPT", { stage: "native-session" });
+    }
+    if (isForeignTranscript(doc, identity, sessionName))
+        return [];
+    return doc.messages;
+}
+/**
+ * The document the loop saves. Key order is owner, model, savedAt, messages:
+ * the file store writes it as-is, and nax's transcript bytes depend on that order.
+ */
+export function transcriptDocFor(messages, identity) {
+    return {
+        ...(identity.owner !== undefined ? { owner: identity.owner } : {}),
+        ...(identity.model !== undefined ? { model: identity.model } : {}),
+        savedAt: new Date().toISOString(),
+        messages: [...messages],
+    };
+}

package/dist/native/session/transcript-store.d.ts

@@ -7,35 +7,36 @@
  * none. See ADR-028 sections 2 and 3.
  */
 import type { ConversationMessage } from "@nathapp/nax-ai";
+import { type TranscriptIdentity } from "./transcript-identity.ts";
+import type { TranscriptDoc, TranscriptStore } from "./transcript-types.ts";
+export { type TranscriptIdentity, transcriptModelIdentity } from "./transcript-identity.ts";
 export declare function transcriptPath(dir: string, sessionName: string): string;
 /**
- * Who may resume a transcript. `owner` is the op invocation (nax#1877); `model`
- * is the native model that wrote it (nax#2150, P3 spec 8.3). A field the caller
- * leaves undefined makes no claim, so non-op callers and tests read whatever is
- * there.
+ * Missing file means no document. Anything else unreadable is a real failure.
+ *
+ * The file wraps the messages rather than storing a bare array, which is what
+ * makes nax#1877 unrepresentable: it records WHO it belongs to (`owner`, the op
+ * invocation's `scopeId ?? callId`) and which model wrote it (`model`, nax#2150),
+ * so the next session of the same deterministic name can tell its own history
+ * from an abandoned invocation's or another model's. A bare array is a pre-#1877
+ * transcript: it loads as an owner-less document, which `historyFromTranscript`
+ * then drops for any reader that has an owner.
  */
-export interface TranscriptIdentity {
-    readonly owner?: string;
-    readonly model?: string;
-}
+export declare function readTranscriptDoc(dir: string, sessionName: string): Promise<TranscriptDoc | null>;
 /**
- * The model half of `TranscriptIdentity`: the native `provider/model` id with
- * the reasoning-effort suffix stripped. A thinking signature binds to the
- * model, not to the effort — pi-ai's own `isSameModel` compares
- * provider/api/model for the same reason. `parseModelSpec`, not
- * `parseNativeModel`: this must never throw.
+ * The file store: `<dir>/<name>.transcript.json`, written as given (the loop's
+ * documents carry no schemaVersion or turn, so nax's bytes are unchanged).
+ * `retainFailed` is the kept-on-failure rename plus the prune to
+ * `MAX_RETAINED_TRANSCRIPTS` that `closeNativeSession` used to run inline.
  */
-export declare function transcriptModelIdentity(rawModel: string | undefined): string | undefined;
+export declare function createFileTranscriptStore(dir: string): TranscriptStore;
 /**
- * Missing file means a new conversation. Anything else is a real failure.
- *
- * Returns `[]` — a new conversation — when the transcript on disk belongs to a
- * different `owner` or a different recorded `model` than the caller (nax#1877,
- * nax#2150). A reader that declares no identity is not making a claim and
- * reads whatever is there, which keeps non-op callers and unit tests working
- * unchanged.
+ * File-level convenience over the file store: the history `sessionName` may
+ * resume from `dir`. `[]` — a new conversation — when there is no file or it
+ * belongs to a different `owner` or recorded `model` (nax#1877, nax#2150).
  */
 export declare function loadTranscript(dir: string, sessionName: string, identity?: TranscriptIdentity): Promise<ConversationMessage[]>;
+/** File-level convenience over the file store: save a loop document. */
 export declare function saveTranscript(dir: string, sessionName: string, messages: readonly ConversationMessage[], identity?: TranscriptIdentity): Promise<void>;
 /**
  * Move a failed session's transcript off the path the next session reads.

package/dist/native/session/transcript-store.js

@@ -9,41 +9,37 @@
 import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { getLogger, NaxError } from "#src/infra/index";
-import { parseModelSpec } from "../models.js";
+import { historyFromTranscript, transcriptDocFor } from "./transcript-identity.js";
+export { transcriptModelIdentity } from "./transcript-identity.js";
 export function transcriptPath(dir, sessionName) {
     return join(dir, `${sessionName}.transcript.json`);
 }
-/**
- * The model half of `TranscriptIdentity`: the native `provider/model` id with
- * the reasoning-effort suffix stripped. A thinking signature binds to the
- * model, not to the effort — pi-ai's own `isSameModel` compares
- * provider/api/model for the same reason. `parseModelSpec`, not
- * `parseNativeModel`: this must never throw.
- */
-export function transcriptModelIdentity(rawModel) {
-    return rawModel === undefined ? undefined : parseModelSpec(rawModel).model;
-}
-/** A bare array is a pre-#1877 transcript: real messages, no recorded owner. */
-function isLegacyTranscript(parsed) {
-    return Array.isArray(parsed);
+/** `savedAt` for a pre-#1877 bare-array transcript, which recorded none. */
+const LEGACY_SAVED_AT = new Date(0).toISOString();
+function corruptTranscript(sessionName, reason) {
+    return new NaxError(`transcript for session "${sessionName}" is unreadable: ${reason}`, "TRANSCRIPT_CORRUPT", {
+        stage: "native-session",
+    });
 }
 /**
- * Missing file means a new conversation. Anything else is a real failure.
+ * Missing file means no document. Anything else unreadable is a real failure.
  *
- * Returns `[]` — a new conversation — when the transcript on disk belongs to a
- * different `owner` or a different recorded `model` than the caller (nax#1877,
- * nax#2150). A reader that declares no identity is not making a claim and
- * reads whatever is there, which keeps non-op callers and unit tests working
- * unchanged.
+ * The file wraps the messages rather than storing a bare array, which is what
+ * makes nax#1877 unrepresentable: it records WHO it belongs to (`owner`, the op
+ * invocation's `scopeId ?? callId`) and which model wrote it (`model`, nax#2150),
+ * so the next session of the same deterministic name can tell its own history
+ * from an abandoned invocation's or another model's. A bare array is a pre-#1877
+ * transcript: it loads as an owner-less document, which `historyFromTranscript`
+ * then drops for any reader that has an owner.
  */
-export async function loadTranscript(dir, sessionName, identity = {}) {
+export async function readTranscriptDoc(dir, sessionName) {
     let raw;
     try {
         raw = await readFile(transcriptPath(dir, sessionName), "utf8");
     }
     catch (err) {
         if (err.code === "ENOENT")
-            return [];
+            return null;
         throw err;
     }
     let parsed;
@@ -51,59 +47,54 @@ export async function loadTranscript(dir, sessionName, identity = {}) {
         parsed = JSON.parse(raw);
     }
     catch (err) {
-        // Deliberately not [] — silently restarting a conversation would drop the
+        // Deliberately not null: silently restarting a conversation would drop the
         // history the model is mid-way through and look like a fresh session.
-        throw new NaxError(`transcript for session "${sessionName}" is unreadable: ${err instanceof Error ? err.message : String(err)}`, "TRANSCRIPT_CORRUPT", {
-            stage: "native-session",
-        });
+        throw corruptTranscript(sessionName, err instanceof Error ? err.message : String(err));
     }
-    if (isLegacyTranscript(parsed)) {
-        // Unowned history is foreign history to a reader that has an identity.
-        // Dropping it is the safe direction: the cost is one re-exploration, where
-        // inheriting it silently bills a conversation this session never had.
-        return identity.owner === undefined ? parsed : [];
-    }
-    const file = parsed;
-    if (isForeignTranscript(file, identity, sessionName))
-        return [];
-    return file.messages ?? [];
+    if (Array.isArray(parsed))
+        return { savedAt: LEGACY_SAVED_AT, messages: parsed };
+    if (typeof parsed !== "object" || parsed === null)
+        throw corruptTranscript(sessionName, "not a transcript document");
+    const doc = parsed;
+    return { ...doc, messages: doc.messages ?? [] };
+}
+async function writeTranscriptDoc(dir, sessionName, doc) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(transcriptPath(dir, sessionName), JSON.stringify(doc, null, 2), "utf8");
 }
 /**
- * Another invocation's history (nax#1877) or another model's (nax#2150, P3
- * spec 8.3(c)) reads as a new conversation. An ABSENT file model reads, unlike
- * an absent owner: every native production turn records one (the adapter parses
- * the model before the loop runs), so an absent field is a pre-upgrade file —
- * which the owner check already keeps out of new processes.
+ * The file store: `<dir>/<name>.transcript.json`, written as given (the loop's
+ * documents carry no schemaVersion or turn, so nax's bytes are unchanged).
+ * `retainFailed` is the kept-on-failure rename plus the prune to
+ * `MAX_RETAINED_TRANSCRIPTS` that `closeNativeSession` used to run inline.
  */
-function isForeignTranscript(file, identity, sessionName) {
-    const { owner, model } = identity;
-    if (owner !== undefined && file.owner !== owner) {
-        getLogger().debug("native-session", "Ignoring a transcript owned by another invocation", {
-            sessionName,
-            storedOwner: file.owner,
-            owner,
-        });
-        return true;
-    }
-    if (model !== undefined && file.model !== undefined && file.model !== model) {
-        getLogger().debug("native-session", "Ignoring a transcript written by another model", {
-            sessionName,
-            storedModel: file.model,
-            model,
-        });
-        return true;
-    }
-    return false;
+export function createFileTranscriptStore(dir) {
+    return {
+        load: (sessionId) => readTranscriptDoc(dir, sessionId),
+        save: (sessionId, doc) => writeTranscriptDoc(dir, sessionId, doc),
+        retainFailed: async (sessionId) => {
+            await retainTranscript(dir, sessionId);
+            await pruneRetainedTranscripts(dir);
+        },
+        delete: (sessionId) => deleteTranscript(dir, sessionId),
+        markTurn: async (sessionId, marker) => {
+            const existing = await readTranscriptDoc(dir, sessionId);
+            const base = existing ?? { savedAt: new Date().toISOString(), messages: [] };
+            await writeTranscriptDoc(dir, sessionId, { ...base, turn: marker });
+        },
+    };
 }
+/**
+ * File-level convenience over the file store: the history `sessionName` may
+ * resume from `dir`. `[]` — a new conversation — when there is no file or it
+ * belongs to a different `owner` or recorded `model` (nax#1877, nax#2150).
+ */
+export async function loadTranscript(dir, sessionName, identity = {}) {
+    return [...historyFromTranscript(await readTranscriptDoc(dir, sessionName), identity, sessionName)];
+}
+/** File-level convenience over the file store: save a loop document. */
 export async function saveTranscript(dir, sessionName, messages, identity = {}) {
-    await mkdir(dir, { recursive: true });
-    const file = {
-        ...(identity.owner !== undefined ? { owner: identity.owner } : {}),
-        ...(identity.model !== undefined ? { model: identity.model } : {}),
-        savedAt: new Date().toISOString(),
-        messages: [...messages],
-    };
-    await writeFile(transcriptPath(dir, sessionName), JSON.stringify(file, null, 2), "utf8");
+    await writeTranscriptDoc(dir, sessionName, transcriptDocFor(messages, identity));
 }
 /**
  * Move a failed session's transcript off the path the next session reads.