@theokit/sdk 4.61.0 → 4.63.0

package/dist/internal/persistence/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":[],"mappings":";;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.js","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}
+{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.js","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}

package/dist/internal/persistence/session-dir.d.cts

@@ -1,16 +1 @@
-/** The subset of `LocalOptions` this resolver reads. */
-interface SessionDirOptions {
-    sessionDir?: string;
-    baseDir?: string;
-}
-/**
- * The session directory the caller ASKED for, or `undefined` when they asked for nothing.
- *
- * {@link resolveSessionDir} always answers with a path, falling back to the default home — which is
- * the right answer for "where do transcripts go" and the wrong one for "did this consumer opt into
- * sharing state with the Claude Code CLI". Memory writes need the second question, and the two
- * accepted names for the option live here, so asking it anywhere else would put a copy of that
- * knowledge somewhere it can drift.
- */
-export declare function explicitSessionDir(local: SessionDirOptions | undefined): string | undefined;
 export {};

package/dist/internal/persistence/session-dir.d.ts

@@ -1,16 +1 @@
-/** The subset of `LocalOptions` this resolver reads. */
-interface SessionDirOptions {
-    sessionDir?: string;
-    baseDir?: string;
-}
-/**
- * The session directory the caller ASKED for, or `undefined` when they asked for nothing.
- *
- * {@link resolveSessionDir} always answers with a path, falling back to the default home — which is
- * the right answer for "where do transcripts go" and the wrong one for "did this consumer opt into
- * sharing state with the Claude Code CLI". Memory writes need the second question, and the two
- * accepted names for the option live here, so asking it anywhere else would put a copy of that
- * knowledge somewhere it can drift.
- */
-export declare function explicitSessionDir(local: SessionDirOptions | undefined): string | undefined;
 export {};

package/dist/internal/runtime/memory/memory-store.d.ts

@@ -1,4 +1,4 @@
 import { type MemoryConfig, type MemoryFact, redactSecrets } from "../../memory/types.js";
 export { redactSecrets };
-export declare function readMemoryFacts(cwd: string, config: MemoryConfig, memoryHome?: string): Promise<MemoryFact[]>;
-export declare function appendMemoryFact(cwd: string, config: MemoryConfig, fact: MemoryFact, memoryHome?: string): Promise<void>;
+export declare function readMemoryFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
+export declare function appendMemoryFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;

package/dist/persistence.cjs

@@ -3,7 +3,8 @@
 var chunkVTYY7XL5_cjs = require('./chunk-VTYY7XL5.cjs');
 var chunk4I55V454_cjs = require('./chunk-4I55V454.cjs');
 var chunkBUIK7GUA_cjs = require('./chunk-BUIK7GUA.cjs');
-var chunkSKXBJ2NU_cjs = require('./chunk-SKXBJ2NU.cjs');
+var chunkA4RAL2ER_cjs = require('./chunk-A4RAL2ER.cjs');
+var chunkNXH4GPAQ_cjs = require('./chunk-NXH4GPAQ.cjs');
 var chunk2ADR2GSO_cjs = require('./chunk-2ADR2GSO.cjs');
 var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
 var chunkI6TGFUCO_cjs = require('./chunk-I6TGFUCO.cjs');
@@ -124,21 +125,21 @@ Object.defineProperty(exports, "transcriptRoot", {
   enumerable: true,
   get: function () { return chunkBUIK7GUA_cjs.transcriptRoot; }
 });
+Object.defineProperty(exports, "sanitizeFts5Query", {
+  enumerable: true,
+  get: function () { return chunkA4RAL2ER_cjs.sanitizeFts5Query; }
+});
 Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.applyWalWithFallback; }
+  get: function () { return chunkNXH4GPAQ_cjs.applyWalWithFallback; }
 });
 Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.isCorruptionError; }
+  get: function () { return chunkNXH4GPAQ_cjs.isCorruptionError; }
 });
 Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.openSqliteResilient; }
-});
-Object.defineProperty(exports, "sanitizeFts5Query", {
-  enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.sanitizeFts5Query; }
+  get: function () { return chunkNXH4GPAQ_cjs.openSqliteResilient; }
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,

package/dist/persistence.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":["atomicWriteTempTarget","TheokitAgentError","readFileSync","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":";;;;;;;;;;;;;;;AA6BO,SAAS,uBAAA,CACd,MACA,WAAA,EAC6B;AAE7B,EAAA,IAAI,KAAK,QAAA,CAAS,aAAa,CAAA,EAAG,OAAO,cAAc,gBAAA,GAAmB,MAAA;AAC1E,EAAA,IAAI,aAAa,OAAO,MAAA;AACxB,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,EAAG,OAAO,YAAA;AACpC,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,cAAc,CAAA,EAAG,OAAO,aAAA;AAC1C,EAAA,IAAIA,uCAAA,CAAsB,IAAI,CAAA,KAAM,MAAA,EAAW,OAAO,MAAA;AACtD,EAAA,OAAO,MAAA;AACT;ACNO,IAAM,gBAAA,GAAN,cAA+BC,mCAAA,CAAkB;AAAA,EAGtD,YAAqB,IAAA,EAAc;AACjC,IAAA,KAAA;AAAA,MACE,qDAAqD,IAAI,CAAA,+JAAA,CAAA;AAAA,MAGzD,EAAE,IAAA,EAAM,wBAAA,EAA0B,WAAA,EAAa,KAAA;AAAM,KACvD;AANmB,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAOrB;AAAA,EAPqB,IAAA;AAAA,EAFH,IAAA,GAAO,kBAAA;AAU3B;AAmCO,SAAS,cAAA,CACd,GAAA,EACA,GAAA,EACA,OAAA,GAAiC,EAAC,EAC5B;AACN,EAAA,KAAA,MAAW,IAAA,IAAQ,OAAA,CAAQ,gBAAA,IAAoB,EAAC,EAAG;AACjD,IAAA,IAAI,IAAA,KAAS,GAAA,EAAK,MAAM,IAAI,iBAAiB,GAAG,CAAA;AAAA,EAClD;AAEA,EAAA,MAAM,KAAA,GAAQC,eAAA,CAAa,GAAA,EAAK,MAAM,EACnC,KAAA,CAAM,IAAI,CAAA,CACV,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,EAAK,CAAE,SAAS,CAAC,CAAA;AACpC,EAAA,MAAM,IAAA,GACJ,QAAQ,iBAAA,KAAsB,MAAA,GAAY,QAAQ,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,OAAA,CAAQ,iBAAiB,CAAA;AAC5F,EAAA,MAAM,IAAA,GAAO,KAAK,MAAA,GAAS,CAAA,GAAI,GAAG,IAAA,CAAK,IAAA,CAAK,IAAI,CAAC;AAAA,CAAA,GAAO,EAAA;AAIxD,EAAA,MAAM,KAAKC,WAAA,CAAS,GAAA,EAAK,IAAA,EAAM,OAAA,CAAQ,QAAQ,GAAK,CAAA;AACpD,EAAA,IAAI;AACF,IAAAC,YAAA,CAAU,IAAI,IAAI,CAAA;AAAA,EACpB,CAAA,SAAE;AACA,IAAAC,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACF;AAiBA,IAAM,aAAa,EAAA,GAAK,IAAA;AASxB,SAAS,WAAA,CAAY,MAAc,IAAA,EAAsD;AAMvF,EAAA,MAAM,EAAA,GAAKF,WAAA,CAAS,IAAA,EAAM,GAAG,CAAA;AAC7B,EAAA,MAAM,IAAA,GAAOG,YAAA,CAAU,EAAE,CAAA,CAAE,IAAA;AAC3B,EAAA,IAAI,SAAA,GAAY,CAAA;AAChB,EAAA,IAAI,IAAA,GAAO,EAAA;AACX,EAAA,IAAI,GAAA,GAAM,IAAA;AACV,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,CAAA,EAAG;AACd,MAAA,MAAM,GAAA,GAAM,IAAA,CAAK,GAAA,CAAI,UAAA,EAAY,GAAG,CAAA;AACpC,MAAA,GAAA,IAAO,GAAA;AACP,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,KAAA,CAAM,GAAG,CAAA;AAC5B,MAAAC,WAAA,CAAS,EAAA,EAAI,GAAA,EAAK,CAAA,EAAG,GAAA,EAAK,GAAG,CAAA;AAC7B,MAAA,SAAA,IAAa,GAAA;AACb,MAAA,IAAA,GAAO,GAAA,CAAI,QAAA,CAAS,MAAM,CAAA,GAAI,IAAA;AAC9B,MAAA,IAAI,aAAA,CAAc,IAAI,CAAA,CAAE,MAAA,GAAS,IAAA,EAAM;AAAA,IACzC;AAAA,EACF,CAAA,SAAE;AACA,IAAAF,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACA,EAAA,MAAM,KAAA,GAAQ,cAAc,IAAI,CAAA;AAChC,EAAA,OAAO,EAAE,OAAO,GAAA,GAAM,CAAA,GAAI,MAAM,KAAA,CAAM,CAAC,CAAA,GAAI,KAAA,EAAO,SAAA,EAAU;AAC9D;AAGA,SAAS,cAAc,IAAA,EAAwB;AAC7C,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA,CAAE,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,EAAK,CAAE,MAAA,GAAS,CAAC,CAAA;AAC3D;AAYA,SAAS,cAAA,CAAe,MAAc,MAAA,EAAyB;AAC7D,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,EAC1B,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,OAAO,MAAA,CAAO,OAAA,KAAY,MAAA,IAAU,MAAA,CAAO,IAAA,KAAS,MAAA;AACtD;AASO,SAAS,aAAA,CACd,IAAA,EACA,OAAA,GAAgC,EAAC,EAC5B;AACL,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,UAAA,IAAc,MAAA,CAAO,iBAAA;AAC1C,EAAA,MAAM,EAAE,KAAA,EAAO,SAAA,EAAU,GAAI,WAAA,CAAY,MAAM,IAAI,CAAA;AAEnD,EAAA,IAAI,GAAA,GAAM,KAAA;AACV,EAAA,IAAI,OAAA,CAAQ,gBAAgB,MAAA,EAAW;AACrC,IAAA,MAAM,SAAS,OAAA,CAAQ,WAAA;AAOvB,IAAA,MAAM,GAAA,GAAM,IAAI,aAAA,CAAc,CAAC,MAAM,cAAA,CAAe,CAAA,EAAG,MAAM,CAAC,CAAA;AAC9D,IAAA,IAAI,OAAO,CAAA,EAAG,GAAA,GAAM,GAAA,CAAI,KAAA,CAAM,MAAM,CAAC,CAAA;AAAA,EACvC;AACA,EAAA,IAAI,MAAA,CAAO,SAAS,IAAI,CAAA,QAAS,GAAA,CAAI,KAAA,CAAM,CAAC,IAAI,CAAA;AAEhD,EAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,CAAC,MAAM,IAAA,CAAK,KAAA,CAAM,CAAC,CAAM,CAAA;AAC7C,EAAA,OAAO,OAAA,CAAQ,WAAW,IAAA,GAAQ,MAAA,CAAO,OAAO,GAAA,EAAK,EAAE,SAAA,EAAW,CAAA,GAAY,GAAA;AAChF","file":"persistence.cjs","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":["atomicWriteTempTarget","TheokitAgentError","readFileSync","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":"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","file":"persistence.cjs","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}

package/dist/persistence.js

@@ -1,7 +1,8 @@
 export { PersistenceSchema } from './chunk-HY66GLM6.js';
 export { SessionBusyError, acquireSessionWriter, sessionHasWriter } from './chunk-44JAAH4X.js';
 export { encodeProjectDir, transcriptPath, transcriptRoot } from './chunk-FKMUFNQE.js';
-export { applyWalWithFallback, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from './chunk-CQ2TQ32Y.js';
+export { sanitizeFts5Query } from './chunk-WE22OXQA.js';
+export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from './chunk-AMFXSENK.js';
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from './chunk-CV7XMBHP.js';
 export { withCwdMutex } from './chunk-Q5EWJPRY.js';
 import { atomicWriteTempTarget } from './chunk-VF7EWVDG.js';

package/dist/persistence.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":[],"mappings":"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","file":"persistence.js","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":[],"mappings":"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","file":"persistence.js","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}

package/dist/subagents-loader.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-D3Xr_-6Z.cjs';
+import { a as AgentDefinition } from './agent-X0DKA943.cjs';
 import './sdk-agent-DEoKhA8a.cjs';
 import './run-BYSHf58D.cjs';
 import 'zod';

package/dist/subagents-loader.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-DIu6FooJ.js';
+import { a as AgentDefinition } from './agent-BFno7Sfn.js';
 import './sdk-agent-D8qJVkuV.js';
 import './run-BYSHf58D.js';
 import 'zod';

package/dist/types/agent.d.ts

@@ -270,6 +270,17 @@ export interface MemorySettings {
     userId?: string;
     scope?: "agent" | "user" | "team";
     storePath?: string;
+    /**
+     * Where this agent's memory lives. Default `<cwd>/.theokit/memory`.
+     *
+     * Must be an absolute path or start with `~/` — a relative value is refused rather than
+     * resolved, because the two plausible bases put the store in two different places.
+     *
+     * Point it at `~/.claude/projects/<encoded-cwd>/memory` to WRITE where the Claude Code CLI
+     * reads. That store is READ unconditionally either way, so setting this is only needed to
+     * share the writes.
+     */
+    directory?: string;
     /**
      * Whether the SDK auto-injects recalled facts as a `<memory>` block in the
      * LLM system prompt. Default `true`.

package/dist/types/memory-provider.d.ts

@@ -66,6 +66,14 @@ export interface RecordSessionSummaryArgs {
      * compute the markdown file path.
      */
     readonly cwd: string;
+    /**
+     * The memory root the kernel resolved for this agent, from `memory.directory` or the default.
+     *
+     * Supplied by the kernel, never constructed by an implementor — which is why it is required
+     * rather than optional. An implementation that recomputed it from `cwd` would write the summary
+     * into a different directory than the one the rest of the subsystem uses (#463).
+     */
+    readonly memoryRoot: import("../internal/memory/storage/memory-root.js").MemoryRoot;
     /** Run id used as the filename key. */
     readonly runId: string;
     /** Agent identity for scope (foldering). */

package/docs/error-codes.md

@@ -6,7 +6,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 
 **Transport codes vs the rest.** `ErrorCode` in `errors.ts` is the small canonical union a provider failure maps onto — the codes marked *transport* below. Everything else is raised by a specific subsystem at a specific place, and a `catch` that only handles the union will meet them anyway.
 
-205 distinct code(s).
+206 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -53,7 +53,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cron_no_target` | domain | ConfigurationError | `packages/sdk/src/cron.ts:220` +1 |
 | `cron_workflow_message` | domain | ConfigurationError | `packages/sdk/src/cron.ts:226` |
 | `duplicate_tool_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:201` |
-| `embedding_dimension_mismatch` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:142` +1 |
+| `embedding_dimension_mismatch` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:146` +1 |
 | `embedding_invalid_response` | domain | NetworkError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:370` |
 | `embedding_missing_api_key` | domain | AuthenticationError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:129` |
 | `embedding_unknown_model` | domain | ConfigurationError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:141` |
@@ -88,7 +88,8 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_input` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:98` +9 |
 | `invalid_max_iterations` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/real-local-run.ts:215` |
 | `invalid_memory_backend` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:24` +1 |
-| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:233` |
+| `invalid_memory_directory` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/memory-root.ts:105` |
+| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:206` |
 | `invalid_model_selection` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:21` |
 | `invalid_request` | transport | — | `packages/sdk/src/internal/error-mappers/vertex.ts:52` +1 |
 | `invalid_retry_config` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/retry/with-retry.ts:67` |
@@ -97,7 +98,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_timezone` | domain | ConfigurationError | `packages/sdk/src/internal/cron/validate.ts:134` |
 | `iteration_limit_reached` | domain | — | `packages/sdk/src/internal/agent-loop/loop.ts:149` |
 | `judge_credential` | domain | — | `packages/sdk/src/internal/judge/judge-call.ts:72` +1 |
-| `lance_backend_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:102` +3 |
+| `lance_backend_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:105` +3 |
 | `lance_requires_embedding` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:39` +1 |
 | `live_session_protected` | domain | — | `packages/sdk/src/internal/persistence/transcript-ops.ts:39` +1 |
 | `local_provider_http_error` | domain | ConfigurationError | `packages/sdk/src/internal/catalog/local-models.ts:61` |
@@ -112,11 +113,11 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `mcp_not_init` | domain | ConfigurationError | `packages/sdk/src/internal/mcp/client.ts:251` +2 |
 | `mcp_timeout` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:71` |
 | `memory_context_missing_user_id` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent-memory-direct.ts:128` |
-| `memory_path_escapes_root` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:109` +1 |
+| `memory_path_escapes_root` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:115` +1 |
 | `memory_path_traversal` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:280` |
-| `memory_threat_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:250` |
-| `memory_tool_bad_args` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:132` +1 |
-| `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:114` +1 |
+| `memory_threat_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:223` |
+| `memory_tool_bad_args` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:138` +1 |
+| `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:127` +1 |
 | `missing_api_key` | domain | AuthenticationError, ConfigurationError | `packages/sdk/src/agent-helpers.ts:217` +2 |
 | `missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:66` |
 | `missing_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:35` |
@@ -167,7 +168,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:77` +3 |
 | `server_error` | transport | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:92` +2 |
 | `session_busy` | domain | — | `packages/sdk/src/internal/persistence/session-writer.ts:56` +1 |
-| `sql_injection_blocked` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:252` +3 |
+| `sql_injection_blocked` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:256` +3 |
 | `sqlite_driver_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/persistence/sqlite-open.ts:192` |
 | `sqlite_vec_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/memory/sqlite-vec-loader.ts:23` +1 |
 | `squad_process_unsupported` | domain | ConfigurationError | `packages/sdk/src/squad.ts:117` |

package/docs/harness-capability-map.md

@@ -4,7 +4,7 @@ Every public symbol the TheoKit workspace publishes, and the exact specifier to
 
 A symbol listed under two specifiers is reachable from both, but that does NOT make the two interchangeable: a class emitted separately into a subpath entry is a distinct nominal type from the one in the root bundle, so passing one where the other is expected fails on a private field. When a symbol appears twice, import it and everything it is passed to from the SAME specifier.
 
-1137 export(s) across 46 entry point(s).
+1177 export(s) across 46 entry point(s).
 
 ## `@theokit/acp`
 
@@ -526,9 +526,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `ActiveMemoryResult` | interface | Result of one recall attempt.  |
 | `ActiveMemoryStatus` | type | Outcome of one recall attempt.  |
 | `ActiveMemoryTranscript` | interface | Optional on-disk persistence for Active Memory recall transcripts (ADR D6).  |
-| `appendDiaryEntry` | function | Append one entry to the dream diary, creating the file with a `# Dream Diary` header when it does not exist yet.  |
+| `appendDiaryEntry` | function | Append one sweep's entry to `<memory root>/dream-diary.md`, creating the file with its header when this is the first sweep.  |
 | `appendFact` | function | Record a fact, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves without touching disk.  |
 | `appendFactToMarkdown` | function | Write a fact as its own memory file and point the `MEMORY.md` index at it.  |
+| `asMemoryRoot` | function | Treat a directory as a memory root without resolving one.  |
 | `assertValidBackend` | function | EC-1: runtime guard for `opts.backend`.  |
 | `azureOpenAiMemoryEmbeddingProviderAdapter` | const | Azure OpenAI embeddings.  |
 | `buildErrorMetadata` | function | Build an `ErrorMetadata` object with all optional fields included conditionally (no `undefined` keys in the output). |
@@ -542,6 +543,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `Cluster` | interface | A group of facts the REM phase judged related.  |
 | `ClusterResult` | interface | What {@link remPhase } produced.  |
 | `cohereMemoryEmbeddingProviderAdapter` | const | Cohere embeddings.  |
+| `collectMarkdownFiles` | function | Every markdown file the memory corpus holds: the index, the per-memory files, `notes/`, `wiki/` and `sessions/`, each tagged with the bucket `memory_search`'s `corpus` filters on.  |
 | `CreateAdapterOptions` | interface | Per-call overrides handed to {@link MemoryEmbeddingProviderAdapter.create } .  |
 | `createCategorizedMemory` | function | Create a typed categorized memory store over the closed `categories` taxonomy.  |
 | `CreateCategorizedMemoryOptions` | interface | Options for {@link createCategorizedMemory } . |
@@ -564,11 +566,12 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `DEFAULT_OPENAI_EMBEDDING_MODEL` | const | OpenAI embedding adapter (ADR D3) — built on the shared OpenAI-compatible factory.  |
 | `DEFAULT_OPENROUTER_EMBEDDING_MODEL` | const | OpenRouter embedding adapter — routes through OpenRouter's `POST /api/v1/embeddings` endpoint (OpenAI-compatible request/response shape).  |
 | `DEFAULT_VOYAGE_EMBEDDING_MODEL` | const | Voyage AI embedding adapter — `POST /v1/embeddings` at `https://api.voyageai.com` with the OpenAI-compatible `{ model, input }` request shape.  |
-| `defaultIndexPath` | function | Where the SQLite index lives when the caller does not name a path: `<cwd>/.theokit/memory/.index/memory.sqlite`.  |
+| `defaultIndexPath` | function | `<index root>/.index/memory.sqlite`.  |
 | `DiaryEntry` | interface | Dream-diary append (ADR D7).  |
-| `diaryPath` | function | Path to the dream diary, `<memory root>/dream-diary.md`.  |
-| `discoverSessionFiles` | function | List the session summaries under `sessions/`, with each path expressed relative to the memory root so the index can store a stable `sessions/<id>.md`.  |
-| `discoverWikiFiles` | function | List the `.md` files directly under `wiki/`, with each path expressed relative to the memory root so the index can store a stable `wiki/<name>.md`.  |
+| `diaryPath` | function | `<memory root>/dream-diary.md`.  |
+| `DiscoveredFile` | interface | One markdown file the corpus walk found, with the source bucket the indexer tags it with.  |
+| `discoverSessionFiles` | function | Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.  |
+| `discoverWikiFiles` | function | Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.  |
 | `DreamingOptions` | interface | Dreaming sweep orchestrator (ADR D7 of memory-system-peer-project-parity).  |
 | `DreamingResult` | interface | What one sweep did.  |
 | `dropVectorIndex` | function | Drop the `embeddings` table, discarding every stored vector.  |
@@ -579,9 +582,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `EmbeddingRuntime` | interface | A live embedding provider, bound to one model.  |
 | `EmbeddingRuntimeStats` | interface | Counters accumulated by a runtime since it was created.  |
 | `embedMissingChunks` | function | Embed every chunk that doesn't yet have a vector. |
-| `entryHash` | function | A sha256 over the five counts of an entry, as a hex string.  |
+| `entryHash` | function | A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.  |
 | `geminiMemoryEmbeddingProviderAdapter` | const | Google Gemini embeddings through Google's OpenAI-compatible surface at `/v1beta/openai/embeddings`.  |
 | `identityMatches` | function | Compare two embedding identities field by field.  |
+| `indexBudgetWarning` | function | What to say about an index that the interop partner will truncate, or `undefined` when there is nothing true to say.  |
 | `IndexManager` | class | The default memory index: SQLite for storage, FTS5 for text matching, and sqlite-vec for vectors when an embedding runtime is supplied.  |
 | `IndexStatus` | interface | A snapshot of index health.  |
 | `isLanceAvailable` | function | Test helper for {@link LanceIndex } : indicates whether the Lance module is loadable in the current environment.  |
@@ -592,30 +596,33 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `LanceMemoryAdapter` | class | Presents a `LanceIndex` as a {@link MemoryIndex } , so a consumer written against the SQLite index runs unchanged on `backend: "lance"`.  |
 | `LanceSearchHit` | interface | One Lance search result.  |
 | `LanceSearchOptions` | interface | Filters for `LanceIndex.search`.  |
-| `lanceStoragePath` | function | Test helper: re-export the storage path computation. |
+| `lanceStoragePath` | function | `<memory root>/lance`.  |
 | `legacyMemoryJsonPath` | function | Resolve the legacy JSON memory path used pre-ADR-D8 (kept for migration helpers + tests).  |
 | `lightPhase` | function | Light phase — drop facts whose embedding is too similar to one already kept. |
 | `listNotes` | function | List the `.md` files directly under `notes/`.  |
 | `loadSqliteVecExtension` | function | Load the `sqlite-vec` extension into an opened SQLite connection.  |
 | `mapOpenAICompatibleError` | function | Turn a failed OpenAI-shaped HTTP response into the typed error the SDK throws.  |
 | `MEMORY_EMBEDDING_ADAPTERS` | const | Memory embedding adapter catalog, indexed by provider id.  |
+| `MEMORY_INDEX_MAX_BYTES` | const | The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches first.  |
+| `MEMORY_INDEX_MAX_LINES` | const | The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.  |
 | `MemoryBackend` | type | Vector backend selector.  |
 | `MemoryChunk` | interface | A semantically meaningful slice of a markdown memory file, produced by `chunkMarkdown`.  |
 | `MemoryConfig` | interface | Per-agent memory configuration.  |
 | `MemoryDb` | interface | Thin wrapper around the SQLite driver.  |
-| `memoryDir` | function | The memory root for a workspace: `<cwd>/.theokit/memory`.  |
 | `MemoryEmbeddingProviderAdapter` | interface | Memory embedding provider adapter contract (ADR D3 of memory-system-peer-project-parity).  |
 | `MemoryFact` | interface | One remembered statement.  |
 | `MemoryFileEntry` | interface | Lightweight reference to a markdown file in the memory corpus.  |
 | `MemoryGetToolOptions` | interface | Options for {@link createMemoryGetTool } .  |
 | `MemoryIndex` | interface | The four operations both backends implement, and the type every consumer should hold.  |
+| `MemoryLocationConfig` | type | Only `directory` is read; the full config is accepted so callers pass what they already hold. |
 | `memoryMdPath` | function | Path to `MEMORY.md`, the index that points at the per-memory files — and, in stores written before #389, the flat `## Facts` list itself.  |
 | `MemoryReadResult` | interface | Result of `reader.readFile`.  |
+| `memoryReadRoots` | function | Every directory a read must cover, deduplicated and in precedence order.  |
+| `MemoryRoot` | type | A path that {@link resolveMemoryRoot } produced — the only thing the subsystem's path helpers accept.  |
 | `MemorySearchHit` | interface | Memory index manager contract — leaf types shared by `index-manager.ts` (orchestrator), `index-manager-dispatch.ts` (backend dispatch), `lance-memory-adapter.ts` (Lance backend), and `memory-index.... |
 | `MemorySearchToolOptions` | interface | Options for {@link createMemorySearchTool } . |
 | `MemoryTool` | interface | A memory tool ready to hand to the agent loop: the JSON-serialisable description an LLM sees, plus the `execute` that runs it.  |
 | `MemoryToolJson` | interface | Memory tools (`memory_search` + `memory_get`) — ADR D5 of memory-system-peer-project-parity.  |
-| `memoryWriteDir` | function | Where a NEW fact should be written.  |
 | `META_KEY_DIMENSION` | const | `meta` table key holding the vector width the `embeddings` vec0 table was created with. |
 | `META_KEY_MODEL` | const | `meta` table key holding the embedding model id the vectors were produced with. |
 | `META_KEY_PROVIDER_ID` | const | `meta` table key holding the id of the embedding provider that produced the vectors currently on disk (for example `openai`, `ollama`). |
@@ -639,8 +646,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `packVector` | function | Pack a Float32Array into a Buffer suitable for sqlite-vec BLOB binding. |
 | `parseRetryAfter` | function | Parse `retry-after` header in numeric-seconds form.  |
 | `parseSearchOptions` | function | Common search-options parser used by both `IndexManager.search` and `LanceMemoryAdapter.search`.  |
-| `persistActiveMemoryTranscript` | function | Write one recall transcript to `<memory root>/transcripts/active-memory/<runId>.json`, creating the parent directories and replacing the file atomically.  |
+| `persistActiveMemoryTranscript` | function | Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.  |
 | `PRAGMA_STATEMENTS` | const | Non-WAL pragmas.  |
+| `projectMemoryDir` | function | The project store: `<cwd>/.theokit/memory`.  |
+| `readAllSqliteFacts` | function | Read all facts from the SQLite memory index.  |
 | `readEmbeddingIdentity` | function | Read the embedding identity recorded in the `meta` table.  |
 | `readFacts` | function | Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves to `[]` without touching disk.  |
 | `readFactsFromMarkdown` | function | Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in `MEMORY.md`.  |
@@ -648,17 +657,19 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `readMemoryFileBounded` | function | Read a bounded slice of a text file and report what was left behind.  |
 | `redactSecrets` | function | Canonical credential-redaction primitive (ADR D68).  |
 | `remPhase` | function | REM phase — single-link agglomerative clustering by cosine similarity. |
-| `renderDiaryEntry` | function | Render one entry as the markdown block {@link appendDiaryEntry } writes: an h2 heading carrying the ISO timestamp, then a bullet list of the counts, prefixed by the first eight hex characters of {@... |
+| `renderDiaryEntry` | function | One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash, and the counts the sweep produced.  |
 | `resetMigrationStateForTests` | function | Test-only — reset the in-process migration flag map. |
+| `resolveMemoryRoot` | function | The memory root for this agent: `memory.directory` when set, the project store otherwise.  |
 | `runActiveMemory` | function | Run one blocking recall before the system prompt is assembled, and report what happened.  |
 | `RunActiveMemoryArgs` | interface | Everything {@link runActiveMemory } needs for one attempt.  |
 | `runDreamingSweep` | function | Run one consolidation sweep over `MEMORY.md`: drop near-duplicate facts, cluster what is left, write a consolidated note under `notes/`, and append a diary entry.  |
 | `SCHEMA_STATEMENTS` | const | SQLite schema for the memory index.  |
 | `SearchOptions` | interface | Search tuning.  |
 | `SessionFile` | interface | Session summary discovery (ADR D20).  |
-| `sessionsDir` | function | Path to `<memory root>/sessions`, where one markdown summary per finished run is written.  |
+| `sessionsDir` | function | `<memory root>/sessions`.  |
 | `SessionSummaryInput` | interface | Per-run session summary writer (ADR D20).  |
-| `sessionSummaryPath` | function | Path of the summary file for a run.  |
+| `sessionSummaryPath` | function | The file one run's summary occupies: `<memory root>/sessions/<safe-id>.md`.  |
+| `SqliteFactRow` | interface | One row of the SQLite memory index, as the Lance migration reads it: the chunk plus the tenant columns the target table needs.  |
 | `SyncResult` | interface | What one `sync()` did.  |
 | `TenantContext` | interface | T4.9 — Tenant isolation context for cache key derivation.  |
 | `truncateRaw` | function | Truncate raw response body to ~2KB and redact known credential patterns so it can ride inside `ErrorMetadata.raw` without ballooning logs OR leaking tokens.  |
@@ -667,7 +678,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `VectorHitRow` | interface | One row of a vec0 KNN result: the chunk id and its raw distance from the query vector.  |
 | `vectorSearch` | function | Run a k-nearest-neighbour query against the `embeddings` table and return the matches ordered by ascending distance (closest first).  |
 | `voyageMemoryEmbeddingProviderAdapter` | const | Voyage AI embeddings, over the standard OpenAI wire.  |
-| `wikiDir` | function | Path to `<memory root>/wiki`, the read-only supplement directory.  |
+| `wikiDir` | function | `<memory root>/wiki`.  |
 | `WikiFile` | interface | Wiki supplement discovery (ADR Phase 10 of memory-system-peer-project-parity).  |
 | `writeEmbeddingIdentity` | function | Record the embedding identity in the `meta` table, upserting each of the three keys.  |
 | `writeSessionSummary` | function | Write a session summary file.  |
@@ -1009,15 +1020,44 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 
 | Symbol | Kind | Summary |
 |---|---|---|
+| `ActiveMemoryTranscript` | interface | Optional on-disk persistence for Active Memory recall transcripts (ADR D6).  |
+| `appendDiaryEntry` | function | Append one sweep's entry to `<memory root>/dream-diary.md`, creating the file with its header when this is the first sweep.  |
 | `appendFact` | function | Record a fact, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves without touching disk.  |
 | `appendFactToMarkdown` | function | Write a fact as its own memory file and point the `MEMORY.md` index at it.  |
+| `asMemoryRoot` | function | Treat a directory as a memory root without resolving one.  |
 | `claudeProjectMemoryDir` | function | Where the Claude Code CLI keeps THIS project's memories.  |
-| `memoryDir` | function | The memory root for a workspace: `<cwd>/.theokit/memory`.  |
+| `collectMarkdownFiles` | function | Every markdown file the memory corpus holds: the index, the per-memory files, `notes/`, `wiki/` and `sessions/`, each tagged with the bucket `memory_search`'s `corpus` filters on.  |
+| `defaultIndexPath` | function | `<index root>/.index/memory.sqlite`.  |
+| `DiaryEntry` | interface | Dream-diary append (ADR D7).  |
+| `diaryPath` | function | `<memory root>/dream-diary.md`.  |
+| `DiscoveredFile` | interface | One markdown file the corpus walk found, with the source bucket the indexer tags it with.  |
+| `discoverSessionFiles` | function | Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.  |
+| `discoverWikiFiles` | function | Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.  |
+| `entryHash` | function | A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.  |
+| `indexBudgetWarning` | function | What to say about an index that the interop partner will truncate, or `undefined` when there is nothing true to say.  |
+| `lanceStoragePath` | function | `<memory root>/lance`.  |
+| `MEMORY_INDEX_MAX_BYTES` | const | The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches first.  |
+| `MEMORY_INDEX_MAX_LINES` | const | The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.  |
+| `MemoryLocationConfig` | type | Only `directory` is read; the full config is accepted so callers pass what they already hold. |
 | `memoryMdPath` | function | Path to `MEMORY.md`, the index that points at the per-memory files — and, in stores written before #389, the flat `## Facts` list itself.  |
-| `memoryWriteDir` | function | Where a NEW fact should be written.  |
+| `memoryReadRoots` | function | Every directory a read must cover, deduplicated and in precedence order.  |
+| `MemoryRoot` | type | A path that {@link resolveMemoryRoot } produced — the only thing the subsystem's path helpers accept.  |
 | `notesDir` | function | Path to `<memory root>/notes`, where per-topic notes and the consolidated notes a dreaming sweep writes live.  |
+| `persistActiveMemoryTranscript` | function | Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.  |
+| `projectMemoryDir` | function | The project store: `<cwd>/.theokit/memory`.  |
+| `readAllSqliteFacts` | function | Read all facts from the SQLite memory index.  |
 | `readFacts` | function | Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves to `[]` without touching disk.  |
 | `readFactsFromMarkdown` | function | Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in `MEMORY.md`.  |
+| `renderDiaryEntry` | function | One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash, and the counts the sweep produced.  |
+| `resolveMemoryRoot` | function | The memory root for this agent: `memory.directory` when set, the project store otherwise.  |
+| `SessionFile` | interface | Session summary discovery (ADR D20).  |
+| `sessionsDir` | function | `<memory root>/sessions`.  |
+| `SessionSummaryInput` | interface | Per-run session summary writer (ADR D20).  |
+| `sessionSummaryPath` | function | The file one run's summary occupies: `<memory root>/sessions/<safe-id>.md`.  |
+| `SqliteFactRow` | interface | One row of the SQLite memory index, as the Lance migration reads it: the chunk plus the tenant columns the target table needs.  |
+| `wikiDir` | function | `<memory root>/wiki`.  |
+| `WikiFile` | interface | Wiki supplement discovery (ADR Phase 10 of memory-system-peer-project-parity).  |
+| `writeSessionSummary` | function | Write a session summary file.  |
 
 ## `@theokit/sdk/internal/persistence`