@theokit/sdk 5.13.0 → 5.15.0

package/dist/persistence.d.cts

@@ -1,41 +1,745 @@
+export { S as SqliteSessionStore, a as SqliteSessionStoreOptions, w as withCwdMutex } from './sqlite-session-store-TKXtT4ON.cjs';
+import { T as TheokitAgentError } from './errors-base-B5g01neU.cjs';
+import { z } from 'zod';
+export { T as TranscriptBlock, b as TranscriptMessage } from './session-store-Dh07jr9N.cjs';
+
 /**
- * Published as `@theokit/sdk/persistence`.
- *
- * Public persistence primitives (V2-3 — Theo Harness Capability Map, Theme G).
- *
- * Promotes the consumer-grade persistence helpers from `internal/persistence`
- * to a STABLE, semver-protected public sub-path so consumers (e.g. a code
- * assistant's eval harness or config store) adopt durable JSONL persist/resume,
- * audited atomic-write, and resilient-SQLite bootstrap WITHOUT coupling to the
- * semver-exempt `@theokit/sdk/internal/persistence` path.
- *
- * Several of these were extracted FROM a real consumer (theocode's SWE-bench
- * harness — see the `reference:` comments in `internal/persistence/jsonl.ts`);
- * this sub-path lets that consumer adopt its own contributed pattern back from a
- * stable home. DTS is generated via tsc (this barrel reaches `internal/`, like
- * `retry`/`compaction` — see `tsconfig.tools-dts.json`).
- */
-export type { AtomicWriteJsonOptions } from "./internal/persistence/atomic-write.js";
-export { atomicWriteJson, atomicWriteTempTarget, atomicWriteText, replaceFileAtomic, } from "./internal/persistence/atomic-write.js";
-export { withCwdMutex } from "./internal/persistence/cwd-mutex.js";
-export type { FileLockOptions } from "./internal/persistence/file-lock.js";
-export { withFileLock } from "./internal/persistence/file-lock.js";
-export { sanitizeFts5Query } from "./internal/persistence/fts5-sanitize.js";
-export { appendJsonl, JsonlParseError, loadJsonl, readJsonlIds, } from "./internal/persistence/jsonl.js";
-export { type ListSessionsOptions, listSessions, type SessionIdSource, type SessionListing, } from "./internal/persistence/list-sessions.js";
-export { PersistenceSchema } from "./internal/persistence/persistence-schema.js";
-export { classifySessionArtifact, type SessionArtifact, } from "./internal/persistence/session-artifacts.js";
-export { encodeProjectDir, legacyTranscriptPath, sessionUuidFor, transcriptPath, transcriptRoot, } from "./internal/persistence/session-transcript.js";
-export { acquireSessionWriter, SessionBusyError, type SessionWriterLease, sessionHasWriter, } from "./internal/persistence/session-writer.js";
-export type { OpenSqliteResilientOptions, ResilientSqliteDb, } from "./internal/persistence/sqlite-open.js";
-export { isCorruptionError, openSqliteResilient } from "./internal/persistence/sqlite-open.js";
-export type { WalApplyResult } from "./internal/persistence/sqlite-wal.js";
-export { applyWalWithFallback } from "./internal/persistence/sqlite-wal.js";
-/**
- * @deprecated Renamed to {@link LiveTranscriptError}. The root barrel exports a DIFFERENT class
- * under this name (`session-guard.ts`, about refusing to destroy a session), and a consumer holding
- * both got two classes `instanceof` could not tell apart while `err.name` matched both. This alias
- * keeps existing imports working; it will be removed in the next major.
- */
-export { type ForkTranscriptOptions, forkTranscript, LiveTranscriptError, LiveTranscriptError as LiveSessionError, type ReadJsonlTailOptions, readJsonlTail, } from "./internal/persistence/transcript-ops.js";
-export type { TranscriptBlock, TranscriptMessage } from "./types/session-record.js";
+ * M107 — temp-file creation control, shared by `replaceFileAtomic`,
+ * `atomicWriteJson` and `atomicWriteText`.
+ *
+ * Both fields are OPTIONAL and the default is byte-identical to the behavior
+ * before M107. See `replaceFileAtomic` for why the mode reassertion
+ * is conditional.
+ *
+ */
+interface AtomicWriteFileOptions {
+    /**
+     * Permission bits of the created file. Default: `0o600`, the previous fixed
+     * literal — filtered by the `umask`, as it always was. When provided, the mode is
+     * reasserted on the descriptor, so the `umask` cannot silently
+     * clearing bits the caller asked for.
+     */
+    mode?: number;
+    /**
+     * Create the temp file with `wx` (exclusive creation) instead of `w`. Default:
+     * `false` — the previous flag. With `true`, a pre-existing temp file becomes
+     * `EEXIST` instead of being truncated.
+     */
+    exclusive?: boolean;
+}
+/**
+ * U-9 — the file a leftover temp was replacing, or `undefined` if this is not one of ours.
+ *
+ * A crash between the open and the rename leaves `<file>.<pid>.<hex>.tmp` behind, and nothing here
+ * collects it: this module creates temps and has no opinion about sweeping them. A consumer that
+ * wants to has to know the format — which lived only in the implementation, so one copied it out of
+ * a compiled chunk as a regex. That copy would have gone on reporting "nothing to collect" the day
+ * the format changed, which is the quietest possible way for a cleanup to stop working.
+ *
+ * Deliberately strict: the pid must be digits and the suffix exactly 16 hex characters. Matching any
+ * `.tmp` would claim editors' swap files and other tools' scratch, on a path whose purpose is
+ * deleting them.
+ */
+declare function atomicWriteTempTarget(name: string): string | undefined;
+/**
+ * Atomic file replacement: write content to a per-call unique tmp path,
+ * fsync, then rename over the target. Crash mid-write leaves either the old
+ * file intact or the new file complete — never a half-written file.
+ *
+ * The tmp suffix is `<pid>.<rand>.tmp` so parallel processes (and concurrent
+ * burst writes within one process) never collide on the same tmp path — a
+ * race that would manifest as `ENOENT` on `rename` after the rival process
+ * already moved its tmp into place.
+ *
+ * Mirrors peer-project's `replaceFileAtomic` from
+ * `reference/peer-project/packages/memory-host-sdk/src/host/fs-utils.ts` with
+ * the multi-writer robustness fix.
+ *
+ * ## M107 — `options` is optional, and the default is byte-identical
+ *
+ * The third parameter is additive: every earlier caller still compiles and
+ * writing exactly the same bytes, with the same mode, to the same path.
+ *
+ * The mode reassertion (`handle.chmod`) is **conditional on `mode !== undefined`**,
+ * and that is not cosmetic. `open`'s mode argument is filtered by the `umask`,
+ * which only CLEARS bits — measured in this codebase before the change:
+ *
+ * ```
+ * umask 0o002  ->  0o600      umask 0o022  ->  0o600      umask 0o200  ->  0o400
+ * ```
+ *
+ * An unconditional `chmod` would take the third case from `0o400` to `0o600` — a
+ * an on-disk change for every caller that asked for nothing, including external
+ * consumers. When the caller DOES ask for a mode, however, letting the `umask` decide
+ * silently is the defect this parameter exists to close; hence the reassertion.
+ *
+ * It goes on the DESCRIPTOR, before the `rename`, never after: chmod-ing the final
+ * final one would leave a window where it carries the `umask`'s mode — a known anti-pattern.
+ * The chosen shape passes the mode as an `open` argument.
+ *
+ */
+declare function replaceFileAtomic(filePath: string, content: string, options?: AtomicWriteFileOptions): Promise<void>;
+/**
+ * Options for `atomicWriteJson`.
+ *
+ */
+interface AtomicWriteJsonOptions extends AtomicWriteFileOptions {
+    /** Indent passed to `JSON.stringify`. Default: 2. */
+    indent?: number;
+    /** Whether to append a trailing newline (POSIX convention). Default: true. */
+    trailingNewline?: boolean;
+}
+/**
+ * Typed JSON atomic write helper.
+ *
+ * Serializes `data` to JSON, then delegates to `replaceFileAtomic`. The
+ * parent directory is auto-created (recursive `mkdir`) to make this helper
+ * safe for callers who haven't ensured the directory exists (EC-4 in the
+ * persistence-state-hardening plan).
+ *
+ * Throws `TypeError` on circular refs or `undefined` data (propagates from
+ * `JSON.stringify`).
+ *
+ */
+declare function atomicWriteJson<T>(filePath: string, data: T, options?: AtomicWriteJsonOptions): Promise<void>;
+/**
+ * Atomic text write. Same crash-safety guarantees as `replaceFileAtomic` +
+ * auto-mkdir of the parent directory. Written for `theokit-migrate-config` (T4.1, EC-2 MUST FIX) so
+ * a crash mid-migration left previous MD files intact rather than corrupting them; that CLI is no
+ * longer published, and the guarantee is the reason every other caller uses this too.
+ *
+ */
+declare function atomicWriteText(filePath: string, content: string): Promise<void>;
+
+/**
+ * Cross-process file lock helper (ADR D61).
+ *
+ * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When
+ * the peer dep is absent, falls back to `withCwdMutex` (in-process only)
+ * with a one-shot stderr warning.
+ *
+ * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so
+ * `withFileLock` works even when the target `path` does not exist yet.
+ * Without this, fresh installs that lock-then-create would crash with ENOENT.
+ *
+ * @internal
+ */
+/**
+ * Retry and staleness tuning for `withFileLock`.
+ *
+ * Every field is optional and the defaults are applied per call, so `undefined` means the default
+ * rather than "no limit". They are handed to `proper-lockfile` and have NO effect on the fallback
+ * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which
+ * queues indefinitely and never goes stale.
+ *
+ * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a
+ * dead process and broken. Setting it below the longest a legitimate holder can run is what turns
+ * a slow operation into two concurrent ones.
+ *
+ * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`
+ * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to
+ * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall
+ * through to running `fn` unlocked.
+ *
+ * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for
+ * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ */
+interface FileLockOptions {
+    /** Stale lock timeout in ms. Default 30_000 (30s). */
+    stale?: number;
+    /** Max retries on busy lock. Default 5. */
+    retries?: number;
+    /** Backoff factor between retries. Default 1.5. */
+    retryFactor?: number;
+}
+/**
+ * Run `fn` while holding an OS-level cross-process lock on `path`.
+ *
+ * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`
+ * file (`realpath: false`, so target file does NOT need to exist yet).
+ * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot
+ * stderr warning telling the user to install `proper-lockfile` for
+ * cross-process safety.
+ *
+ * The lock is released even when `fn` throws.
+ *
+ */
+declare function withFileLock<T>(path: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+
+/**
+ * FTS5 query sanitization + CJK detection (ADR D64).
+ *
+ * Port of Hermes' 6-step sanitizer (`hermes_state.py:1797-1847`). Prevents
+ * crashes on user inputs with hyphens, dots, underscores, and unmatched
+ * specials. Auto-quotes identifier-shaped tokens so `error-code` finds
+ * literal `error-code` instead of `error AND code`.
+ *
+ * CJK detection returns true for inputs containing characters in the main
+ * CJK Unicode ranges (Chinese, Japanese, Korean). CJK trigram routing is
+ * deferred to v1.4 — callers receiving `containsCjk === true` should
+ * short-circuit to an empty result or LIKE fallback for v1.3.
+ *
+ * @internal
+ */
+/**
+ * Six-step FTS5 query sanitizer. Returns a query string safe for passing
+ * to `WHERE <fts5_table> MATCH ?` as a parameter.
+ *
+ * Returns empty string when the input contains only specials (caller MUST
+ * short-circuit to avoid runtime SQL error — EC-3).
+ *
+ */
+declare function sanitizeFts5Query(query: string): string;
+
+/** Raised when a JSONL line is not valid JSON or is not a JSON object. Carries the 1-based line number. */
+declare class JsonlParseError extends TheokitAgentError {
+    readonly line: number;
+    readonly name = "JsonlParseError";
+    constructor(message: string, line: number);
+}
+/**
+ * Parse a JSONL file into rows. Blank lines are skipped. A malformed or
+ * non-object line throws {@link JsonlParseError} naming the 1-based line. When
+ * `map` is provided, each raw object is mapped to the typed row (the SWE-bench
+ * schema lives in the caller's `map`, per M6 ADR D3).
+ */
+declare function loadJsonl<T = Record<string, unknown>>(path: string, opts?: {
+    map?: (raw: Record<string, unknown>, lineNumber: number) => T;
+    /**
+     * M81 — tolerate a truncated LAST line (a crash artifact: the process died mid-write).
+     *
+     * Opt-in on purpose. As a default it would also swallow corruption in the MIDDLE of the file,
+     * turning loud data loss into silent data loss — the wrong trade for a session store.
+     */
+    tolerateTrailingPartialLine?: boolean;
+}): T[];
+/**
+ * Append one record as a whole `\n`-terminated JSON line. Creates the parent dir
+ * if missing. `appendFileSync` is synchronous, so within a single Node process
+ * the event loop serializes writes and each call writes its line atomically —
+ * interleave-safe for the bounded-concurrency batch runner.
+ *
+ * reference: swebench-batch.ts:192 (mkdir-before-append), :205 (per-line flush).
+ */
+declare function appendJsonl(path: string, record: unknown): void;
+/**
+ * Read the set of keys from an existing JSONL file for which `keyFn(parsed)`
+ * returns a non-empty string. Used to resume a crashed batch by skipping rows
+ * already persisted with a successful result. A trailing partial line from an
+ * interrupted append is tolerated (skipped, not thrown), and a missing file
+ * yields an empty set.
+ *
+ * reference: swebench-batch.ts:113 (readDoneIds), :129 (success-only),
+ * :131 (tolerate partial line).
+ */
+declare function readJsonlIds(path: string, keyFn: (parsed: Record<string, unknown>) => string | undefined): Set<string>;
+
+/**
+ * #598 — enumerate the sessions on disk, saying where each id came from.
+ *
+ * ## Why this exists
+ *
+ * Every transcript helper this package published mapped FORWARD — `sessionUuidFor`,
+ * `transcriptPath`, `legacyTranscriptPath`, `encodeProjectDir`, `transcriptRoot`. **None enumerated.**
+ * So a consumer that needed the list rebuilt it, and two independent ones did, in opposite
+ * directions, and both got it wrong on the first attempt:
+ *
+ * | consumer | direction | what broke |
+ * |---|---|---|
+ * | `@theokit/agents` | file → id | derived the id from the file STEM |
+ * | a downstream agent runtime | id → file | compared session ids against filenames |
+ *
+ * The second measured, against 5.0.1: the protected set never matched, **so neither the registered
+ * sessions nor the live one were protected and everything classified as an orphan** — a garbage
+ * collector that would delete the session in use.
+ *
+ * ## Why documentation was not the fix
+ *
+ * `b85dab4` documented the rename thoroughly. One of those two consumers had READ it and broke
+ * anyway; the other had not and broke identically. Two samples, one informed and one not, same
+ * defect. If reading were sufficient the informed sample would have survived — so the cause is the
+ * shape of the surface, not the reader.
+ *
+ * And it cannot be closed by publishing an inverse: the filename is a UUIDv8 over SHA-256, which has
+ * none. Whoever holds the file must read the id from INSIDE it, and that the id lives in the first
+ * record is this package's knowledge. Both consumers had to discover it by reading bytes.
+ *
+ * ## Why the id is not just a string
+ *
+ * An `id: string` that is sometimes read from the transcript and sometimes inferred from the
+ * filename is the same defect one layer up: a value that reads as authoritative and occasionally is
+ * not. That is precisely what produced the garbage-collector failure above.
+ *
+ * So every entry carries {@link SessionListing.idSource}, and an entry whose id could not be
+ * determined is `undefined` rather than guessed. A caller deciding what to DELETE needs to tell
+ * "this session is not registered" from "I could not read this file" — those look identical in a
+ * plain list and mean opposite things.
+ *
+ * @public
+ */
+/** How the `id` on a {@link SessionListing} was obtained. */
+type SessionIdSource = 
+/** Read from the `sessionId` of the transcript's first well-formed record. Authoritative. */
+"transcript"
+/**
+ * Not determined: the file was unreadable, empty, or its first records carried no `sessionId`.
+ * `id` is `undefined` — deliberately not the filename, which is a hash and not an id.
+ */
+ | "unavailable";
+/** One session found on disk. */
+interface SessionListing {
+    /**
+     * The session id, or `undefined` when {@link idSource} is `"unavailable"`.
+     *
+     * Never derived from the filename. The filename is a UUIDv8 over SHA-256 of the id, so treating
+     * it as the id is the exact defect this function exists to prevent.
+     */
+    readonly id: string | undefined;
+    /** Where {@link id} came from. Check this before acting on `id`. */
+    readonly idSource: SessionIdSource;
+    /** Absolute path to the `.jsonl` transcript. */
+    readonly transcript: string;
+    /** Last modification time of the transcript. */
+    readonly modifiedAt: Date;
+}
+/** Options for {@link listSessions}. */
+interface ListSessionsOptions {
+    /**
+     * Root under which `projects/<encoded-cwd>/` lives. Defaults to {@link transcriptRoot}, which
+     * honours `THEOKIT_HOME`.
+     */
+    readonly baseDir?: string;
+    /**
+     * How many bytes of each transcript to read looking for the id. Default 65536.
+     *
+     * A cap rather than a full read because a transcript grows without bound and the id is in the
+     * first record. A session whose id is not in the first 64KB reports `"unavailable"` rather than
+     * being read to the end — bounded work with a declared outcome beats an unbounded read.
+     */
+    readonly idScanBytes?: number;
+}
+/**
+ * Every session transcript under `<baseDir>/projects/<encoded-cwd>/`, with the id read from inside
+ * each file.
+ *
+ * An absent directory yields `[]` — a cwd with no sessions is the common case, not an error.
+ *
+ * ```ts
+ * for (const s of await listSessions(process.cwd())) {
+ *   if (s.idSource === "unavailable") continue;   // do not guess, and do not delete
+ *   …
+ * }
+ * ```
+ */
+declare function listSessions(cwd: string, options?: ListSessionsOptions): Promise<readonly SessionListing[]>;
+
+/**
+ * Shared Zod schema for the `{ backend: "memory" | "json", dir? }` options
+ * used by both `Workflow` snapshots and `Cache` semantic store persistence.
+ * Extracted to remove the cross-module clone flagged by jscpd.
+ *
+ * `PersistenceSchema` is re-exported from the semver-protected `@theokit/sdk/persistence` barrel
+ * and from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
+ */
+
+/**
+ * `persistence?` opt-in JSON disk backend with `dir` required when chosen.
+ *
+ * `.refine()` restored after Zod v4-only migration (plan zod-v4-migration
+ * T1.1, ADR D4). With single v4 instance across workspace, ZodEffects
+ * inside `z.object()` works correctly.
+ */
+declare const PersistenceSchema: z.ZodOptional<z.ZodObject<{
+    backend: z.ZodEnum<{
+        memory: "memory";
+        json: "json";
+    }>;
+    dir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+
+/**
+ * The kinds of file this SDK leaves in a project's transcript directory.
+ *
+ * - `transcript` — the session itself (`transcriptPath`).
+ * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).
+ * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.
+ * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.
+ */
+type SessionArtifact = "transcript" | "writer-lock" | "lock-directory" | "temp";
+/**
+ * U-1 — what is this entry, if it is one of ours?
+ *
+ * The SDK writes four kinds of file into a project directory and reasons about none of them
+ * afterwards: there is no retention, no collector, and there was no way even to ask what an entry
+ * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and
+ * one did, which means a suffix changing here would have left its classifier silently mislabelling
+ * files on a path that deletes them.
+ *
+ * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to
+ * keep, which session is live, whether to delete at all — and policy belongs to the application,
+ * which is the only one that can know. What belongs here is the half only the SDK can answer.
+ *
+ * `undefined` means "not written by this SDK", and it is the answer that matters most: a caller
+ * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case
+ * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.
+ */
+declare function classifySessionArtifact(name: string, isDirectory: boolean): SessionArtifact | undefined;
+
+/** Claude Code path convention: cwd with every non-alphanumeric replaced by `-`. */
+declare function encodeProjectDir(cwd: string): string;
+/**
+ * Root of the transcript state.
+ *
+ * `THEOKIT_HOME` wins; the fallback is `~/.theokit`. Home-anchored on purpose, and NOT
+ * `paths.ts`'s `getTheokitHome(cwd)`: that one falls back to `<cwd>/.theokit`, and switching
+ * by it would move the transcript of everyone who does **not** set the variable. The sibling with the
+ * right shape is `catalog-source-models-dev.ts` (M94 ADR-2).
+ *
+ * Before M94 this function ignored the env var, so whoever set it had their state split in
+ * two silently — sessions stayed in `~/.theokit` while the rest of the SDK migrated.
+ */
+declare function transcriptRoot(): string;
+/**
+ * The transcript filename for an agent id — always a UUID.
+ *
+ * #400: the Claude Code CLI resumes a transcript ONLY when its basename is a UUID. Measured against
+ * CLI 2.1.236: `<uuid>.jsonl` resumes; `agent-<uuid>.jsonl` and `billing-bot.jsonl` are both ignored,
+ * with no error — the session simply is not offered. So a session written under a human-readable
+ * agent id was invisible to `claude --continue`, which is the interoperability this project claims
+ * as its difference from a proprietary session store.
+ *
+ * An id that is ALREADY a UUID passes through verbatim, so a transcript Claude Code wrote keeps its
+ * own name and the two directions stay symmetric. Anything else is derived with a UUIDv8, which is
+ * deterministic: the same agent id always yields the same filename, so nothing has to be persisted
+ * to map one back to the other.
+ *
+ * A DERIVED name is version 8 — RFC 9562's slot for a UUID whose bits come from an
+ * implementation-defined scheme, which is exactly what this is. The obvious alternative was v5, but
+ * RFC 4122 fixes v5's hash to SHA-1, and reaching for SHA-1 in 2026 means either shipping a weak
+ * primitive or arguing with every scanner that flags it, forever. v8 lets the hash be SHA-256 and
+ * lets the version nibble say honestly that this is our scheme rather than a standard one.
+ *
+ * There is no security claim here either way — no secret, no signature, and nothing an attacker
+ * gains by colliding two agent ids inside one consumer's own directory. The hash is a naming
+ * function. The point of preferring SHA-256 is not that SHA-1 was exploitable here; it is that a
+ * weak primitive in the tree costs a permanent argument with every scanner that sees it.
+ *
+ * The version nibble was measured, not assumed: CLI 2.1.236 resumes a v8-named transcript exactly as
+ * it does a v4 one.
+ */
+declare function sessionUuidFor(id: string): string;
+/** The `.jsonl` path for a session: `<baseDir>/projects/<encoded-cwd>/<session-uuid>.jsonl`. */
+declare function transcriptPath(baseDir: string, cwd: string, sessionId: string): string;
+/**
+ * The path this session used BEFORE #400 made transcript filenames UUIDs.
+ *
+ * Kept so an existing transcript is never orphaned: {@link FsSessionStore} prefers this file when it
+ * exists, so history written under the old scheme keeps accumulating in the same file instead of
+ * being silently abandoned for a fresh one under the new name.
+ */
+declare function legacyTranscriptPath(baseDir: string, cwd: string, sessionId: string): string;
+
+/**
+ * M81 — single-writer lease for a session transcript.
+ *
+ * ## The problem
+ *
+ * Nothing stops two processes appending to the same JSONL transcript. The concrete case: `exec
+ * resume --last` can write into the TUI's live session. Two interleaved appends to an append-only
+ * file produce lines that are each individually valid and whose SEQUENCE is fiction — and nothing
+ * reports it, because every line parses.
+ *
+ * ## Why an exclusive lockfile rather than `withFileLock`
+ *
+ * The plan's ADR D2 said to compose `withFileLock`, and that was the right instinct — do not build a
+ * second lock mechanism. It turned out not to fit the SHAPE: `withFileLock(path, fn)` is
+ * scope-based — it holds the lock for the duration of a callback. A session lease is **held across
+ * turns**, for as long as the process owns the session, with an explicit `release()`. Wrapping the
+ * whole session lifetime in a callback would invert control of the entire agent loop.
+ *
+ * So this uses the same underlying primitive `withFileLock` uses (an exclusive-create lockfile,
+ * `wx`) with lease semantics on top. That keeps the mechanism single — the file-existence lock —
+ * while giving it the lifetime the caller needs. The deviation from D2 is recorded here because the
+ * plan's rationale (no second mechanism) still holds; only its shape assumption did not.
+ *
+ * ## Fail fast, never wait
+ *
+ * A second writer that WAITED would block `exec` behind a TUI session that can last hours. The typed
+ * error lets the caller choose: fork to a new id, or give up with a real diagnosis.
+ *
+ * @internal
+ */
+
+/**
+ * M81 — another process already holds the writer lease for this session.
+ *
+ * Carries `sessionPath` because knowing WHICH session is busy is what lets the caller decide between
+ * forking and waiting for the user to close the TUI (`rules/error-handling.md § 2` — context enough
+ * to act on).
+ */
+declare class SessionBusyError extends TheokitAgentError {
+    readonly sessionPath: string;
+    readonly name = "SessionBusyError";
+    constructor(sessionPath: string);
+}
+/** A held writer lease. `release()` is idempotent. */
+interface SessionWriterLease {
+    readonly sessionPath: string;
+    release(): Promise<void>;
+    /**
+     * Re-stamp the ownership record, so a **live** owner never crosses the staleness window.
+     *
+     * Idempotent and cheap: one `write` of a ~80-byte JSON. Call it on the path that already writes to
+     * the session — appending a turn — and the cross-host window stops being a lie about liveness.
+     *
+     * A no-op after `release()`: renewing a lease you no longer hold would re-create the lock file and
+     * hand this process ownership it gave up. That is the one direction of this API that could
+     * *create* the double-writer it exists to prevent.
+     */
+    renew(): void;
+}
+/**
+ * Does the session have a writer **right now**? A query that does NOT take the lease.
+ *
+ * M95 — it exists because asking by taking creates the very contention it meant to detect: two
+ * processes querying a **free** session at the same time made one of them lose, and the consumer
+ * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.
+ *
+ * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take
+ * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to
+ * **decide an id before opening anything** use this, and handle the race where it shows up.
+ *
+ */
+declare function sessionHasWriter(sessionPath: string): boolean;
+/**
+ * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
+ *
+ * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the
+ * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across
+ * processes, not just across async tasks in one process.
+ */
+declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;
+
+/**
+ * Resilient SQLite open (plan m0-foundation-expose-primitives, M0-5).
+ *
+ * Generalizes the driver-load + WAL-apply + corruption-recovery logic that was
+ * duplicated (byte-identical) across `sdk/internal/memory/index-db.ts` and
+ * `sdk-memory/internal/index/index-db.ts`. Schema-agnostic: the caller applies
+ * its own PRAGMA/SCHEMA via the `onOpen` callback.
+ *
+ * Corruption recovery (EC-7): when opening fails with a "malformed" / "not a
+ * database" / "encrypted" error and `recoverCorrupt` is not false, the file is
+ * renamed aside to `<path>.corrupt-<ts>` (plus its WAL/SHM siblings) and a fresh
+ * DB is opened. The corrupt file is renamed, NOT backed up — the timestamped
+ * `.corrupt-*` file is kept for manual recovery.
+ *
+ * @internal — public via `@theokit/sdk/internal/persistence` (semver-exempt)
+ */
+/** Minimal SQLite handle surface every driver (`better-sqlite3`) exposes. */
+interface ResilientSqliteDb {
+    /** SQLite `pragma()` access (used by `applyWalWithFallback`). */
+    pragma(statement: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    exec(sql: string): void;
+    close(): void;
+}
+/**
+ * Input to {@link openSqliteResilient}.
+ *
+ * The trap is `recoverCorrupt`, whose default is ON. When the driver reports a corrupt or encrypted
+ * database, the file is renamed aside and a FRESH one is opened — so the call SUCCEEDS and hands
+ * back an EMPTY database. The old bytes survive on disk under the renamed path, but a caller that
+ * treats a resolved promise as "my data is here" is wrong exactly when it matters. Pass
+ * `recoverCorrupt: false` to get the corruption error thrown instead.
+ *
+ * Semver-exempt: reachable via the '@theokit/sdk/internal/persistence' sub-path, which the package
+ * declares in 'exports' but does NOT cover with its semver contract.
+ *
+ * @typeParam T - the concrete DB handle the driver returns; defaults to {@link ResilientSqliteDb}
+ */
+interface OpenSqliteResilientOptions<T extends ResilientSqliteDb> {
+    /** Absolute path to the SQLite file. Parent directories are created. */
+    filePath: string;
+    /**
+     * Called after the driver is open and WAL is applied, before the handle is
+     * returned. Apply PRAGMA/SCHEMA statements here. Errors propagate.
+     */
+    onOpen?: (db: T) => void | Promise<void>;
+    /** Label used in the WAL-fallback warning and corruption-recovery log. Default "sqlite". */
+    label?: string;
+    /** When true (default) a corruption error renames the file aside and rebuilds. */
+    recoverCorrupt?: boolean;
+}
+/**
+ * Open a SQLite file with WAL (+ DELETE fallback) and corruption recovery.
+ *
+ * @typeParam T - the concrete DB handle type the driver returns (defaults to the
+ *   minimal {@link ResilientSqliteDb} surface)
+ */
+declare function openSqliteResilient<T extends ResilientSqliteDb = ResilientSqliteDb>(options: OpenSqliteResilientOptions<T>): Promise<T>;
+/** True when an open error indicates an unreadable / corrupt database file. */
+declare function isCorruptionError(cause: unknown): boolean;
+
+/**
+ * SQLite WAL mode helper with NFS/SMB/FUSE fallback to DELETE (ADR D63).
+ *
+ * WAL is faster (concurrent readers + one writer) but unsupported on some
+ * network/FUSE filesystems. Try WAL; if the pragma returns something else
+ * or throws, fall back to DELETE journal mode. Warn one time per label.
+ *
+ * This block is the MODULE header and must stay at offset 0. Sitting below the import it became a
+ * leading comment of the first declaration instead, which is how its tag deleted `PragmaCapable`
+ * from the emitted `.d.ts` while `applyWalWithFallback` — which names it — survived.
+ */
+/**
+ * The narrow slice of a SQLite handle this module needs: anything with a `pragma()` method, which
+ * `better-sqlite3` satisfies without being named here.
+ *
+ * Not exported, but it appears in the signature of `applyWalWithFallback`, so it is emitted into
+ * the published declarations and a consumer can structurally satisfy it.
+ */
+interface PragmaCapable {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+}
+/**
+ * What journal mode a connection ended up in after `applyWalWithFallback`.
+ *
+ * `mode` is the mode actually in effect, never the one that was requested. `fellBack` is `true`
+ * only when WAL was attempted and refused — either the pragma threw or it reported a mode other
+ * than `wal` — and the connection was put into DELETE instead.
+ *
+ * `fellBack: true` is normal on NFS, SMB and FUSE, where WAL needs shared memory the filesystem
+ * does not provide. It is not an error and nothing further is required of the caller; the
+ * consequence is slower concurrent access, since DELETE mode does not allow readers alongside a
+ * writer. Treat it as a signal about the storage, not about the database.
+ *
+ * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for
+ * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ */
+interface WalApplyResult {
+    /** Final journal_mode actually in effect. */
+    mode: "wal" | "delete";
+    /** True if we wanted WAL but the filesystem refused. */
+    fellBack: boolean;
+}
+/**
+ * Apply WAL mode with DELETE fallback. Idempotent — safe to call multiple
+ * times on the same connection.
+ *
+ * @param db   any `pragma()`-capable SQLite handle (e.g., `better-sqlite3`)
+ * @param label short identifier used in the warning (e.g., "memory-index")
+ *
+ */
+declare function applyWalWithFallback(db: PragmaCapable, label: string): WalApplyResult;
+
+/**
+ * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.
+ *
+ * ## What this replaces
+ *
+ * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a
+ * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and
+ * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.
+ *
+ * ## The rule that travels WITH the operation
+ *
+ * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live
+ * pointer, the most recent transcript, and any active registry entry. That rule lived in the
+ * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy
+ * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:
+ * critical knowledge outside the module that needs it, applied by convention.
+ *
+ * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of
+ * them. The caller supplies the list because only the caller knows which session is live; the
+ * enforcement lives here because that is where the write happens.
+ *
+ * @internal
+ */
+
+/**
+ * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).
+ *
+ * Typed rather than a bare `Error` because the caller must distinguish "this session is protected"
+ * from "the disk is full": the first is a correct refusal, the second is an incident.
+ *
+ * RENAMED from `LiveSessionError` (2026-09-01). `session-guard.ts` exports a DIFFERENT class of that
+ * name from the root barrel, with an incompatible shape — `(sessionId, reason)` and a `reason`
+ * field, against this one's `(path)` and `code: "live_session_protected"` — and `.` and
+ * `./persistence` are both declared subpaths, so one consumer can hold both. `instanceof` never
+ * crossed the pair, so a `catch` checking the root import silently missed this one and ran its
+ * fallback for a condition it believed it handled; `err.name` matched BOTH, so a name check looked
+ * right and then read `err.reason`, which only the other one has. The names now say what each
+ * refusal is about: destroying a SESSION, versus overwriting a TRANSCRIPT file.
+ */
+declare class LiveTranscriptError extends TheokitAgentError {
+    readonly path: string;
+    readonly name = "LiveTranscriptError";
+    constructor(path: string);
+}
+/** Options for {@link forkTranscript}. */
+interface ForkTranscriptOptions {
+    /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */
+    readonly beforeRecordIndex?: number;
+    /**
+     * Paths that must never be written over — the live pointer, the most recent transcript, any active
+     * registry entry. The caller supplies them because only the caller knows which session is live.
+     */
+    readonly liveSessionPaths?: readonly string[];
+    /**
+     * M107 — permission bits for the created destination. Default: `0o600`.
+     *
+     * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was
+     * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on
+     * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a
+     * knob would reach zero consumers by omission, which is the failure mode that matters.
+     *
+     * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is
+     * `0o400`. That is accepted: the invariant bought here is "neither group nor others", and `0o400`
+     * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because
+     * that would hand back a bit the operator asked to remove.
+     */
+    readonly mode?: number;
+}
+/**
+ * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.
+ *
+ * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot
+ * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also
+ * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an
+ * error is the worst failure mode for an operation that touches user sessions.
+ */
+declare function forkTranscript(src: string, dst: string, options?: ForkTranscriptOptions): void;
+/** Options for {@link readJsonlTail}. */
+interface ReadJsonlTailOptions {
+    /** Maximum records to return, counted from the END. */
+    readonly maxRecords?: number;
+    /**
+     * Start the window AFTER the last record whose `subtype` (or `type`) equals this.
+     *
+     * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message
+     * mentioning the marker in its text truncated the read — silently, with a successful return.
+     */
+    readonly sinceMarker?: string;
+    /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */
+    readonly _stats?: boolean;
+}
+/**
+ * Read the LAST records of a JSONL file without loading the whole thing.
+ *
+ * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session
+ * transcript grows without bound; loading megabytes to show the last three turns is the cost this
+ * exists to avoid — and a `slice` over a full read would be that same cost with a better name.
+ */
+declare function readJsonlTail<T = Record<string, unknown>>(path: string, options?: ReadJsonlTailOptions): T[];
+
+export { type AtomicWriteJsonOptions, type FileLockOptions, type ForkTranscriptOptions, JsonlParseError, type ListSessionsOptions, LiveTranscriptError as LiveSessionError, LiveTranscriptError, type OpenSqliteResilientOptions, PersistenceSchema, type ReadJsonlTailOptions, type ResilientSqliteDb, type SessionArtifact, SessionBusyError, type SessionIdSource, type SessionListing, type SessionWriterLease, type WalApplyResult, acquireSessionWriter, appendJsonl, applyWalWithFallback, atomicWriteJson, atomicWriteTempTarget, atomicWriteText, classifySessionArtifact, encodeProjectDir, forkTranscript, isCorruptionError, legacyTranscriptPath, listSessions, loadJsonl, openSqliteResilient, readJsonlIds, readJsonlTail, replaceFileAtomic, sanitizeFts5Query, sessionHasWriter, sessionUuidFor, transcriptPath, transcriptRoot, withFileLock };