@theokit/sdk 4.53.0 → 4.54.0

package/dist/internal/persistence/file-lock.d.cts

@@ -11,4 +11,44 @@
  *
  * @internal
  */
-export {};
+/**
+ * Retry and staleness tuning for `withFileLock`.
+ *
+ * Every field is optional and the defaults are applied per call, so `undefined` means the default
+ * rather than "no limit". They are handed to `proper-lockfile` and have NO effect on the fallback
+ * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which
+ * queues indefinitely and never goes stale.
+ *
+ * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a
+ * dead process and broken. Setting it below the longest a legitimate holder can run is what turns
+ * a slow operation into two concurrent ones.
+ *
+ * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`
+ * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to
+ * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall
+ * through to running `fn` unlocked.
+ *
+ * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for
+ * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ */
+export interface FileLockOptions {
+    /** Stale lock timeout in ms. Default 30_000 (30s). */
+    stale?: number;
+    /** Max retries on busy lock. Default 5. */
+    retries?: number;
+    /** Backoff factor between retries. Default 1.5. */
+    retryFactor?: number;
+}
+/**
+ * Run `fn` while holding an OS-level cross-process lock on `path`.
+ *
+ * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`
+ * file (`realpath: false`, so target file does NOT need to exist yet).
+ * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot
+ * stderr warning telling the user to install `proper-lockfile` for
+ * cross-process safety.
+ *
+ * The lock is released even when `fn` throws.
+ *
+ */
+export declare function withFileLock<T>(path: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/internal/persistence/file-lock.d.ts

@@ -11,4 +11,44 @@
  *
  * @internal
  */
-export {};
+/**
+ * Retry and staleness tuning for `withFileLock`.
+ *
+ * Every field is optional and the defaults are applied per call, so `undefined` means the default
+ * rather than "no limit". They are handed to `proper-lockfile` and have NO effect on the fallback
+ * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which
+ * queues indefinitely and never goes stale.
+ *
+ * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a
+ * dead process and broken. Setting it below the longest a legitimate holder can run is what turns
+ * a slow operation into two concurrent ones.
+ *
+ * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`
+ * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to
+ * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall
+ * through to running `fn` unlocked.
+ *
+ * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for
+ * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ */
+export interface FileLockOptions {
+    /** Stale lock timeout in ms. Default 30_000 (30s). */
+    stale?: number;
+    /** Max retries on busy lock. Default 5. */
+    retries?: number;
+    /** Backoff factor between retries. Default 1.5. */
+    retryFactor?: number;
+}
+/**
+ * Run `fn` while holding an OS-level cross-process lock on `path`.
+ *
+ * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`
+ * file (`realpath: false`, so target file does NOT need to exist yet).
+ * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot
+ * stderr warning telling the user to install `proper-lockfile` for
+ * cross-process safety.
+ *
+ * The lock is released even when `fn` throws.
+ *
+ */
+export declare function withFileLock<T>(path: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/internal/persistence/fs-session-store.d.cts

@@ -26,6 +26,9 @@ export interface FsSessionStoreOptions {
     /** The workspace cwd whose encoded form is the transcript project dir. */
     cwd: string;
 }
+/**
+ * The default `SessionStore` — reads/append-writes the native `.jsonl` transcript.
+ */
 export declare class FsSessionStore implements SessionStore {
     #private;
     constructor(options: FsSessionStoreOptions);

package/dist/internal/persistence/fs-session-store.d.ts

@@ -26,6 +26,9 @@ export interface FsSessionStoreOptions {
     /** The workspace cwd whose encoded form is the transcript project dir. */
     cwd: string;
 }
+/**
+ * The default `SessionStore` — reads/append-writes the native `.jsonl` transcript.
+ */
 export declare class FsSessionStore implements SessionStore {
     #private;
     constructor(options: FsSessionStoreOptions);

package/dist/internal/persistence/fts5-sanitize.d.cts

@@ -13,4 +13,32 @@
  *
  * @internal
  */
-export {};
+/**
+ * Six-step FTS5 query sanitizer. Returns a query string safe for passing
+ * to `WHERE <fts5_table> MATCH ?` as a parameter.
+ *
+ * Returns empty string when the input contains only specials (caller MUST
+ * short-circuit to avoid runtime SQL error — EC-3).
+ *
+ */
+export declare function sanitizeFts5Query(query: string): string;
+/**
+ * Report whether `text` holds at least one Chinese, Japanese or Korean character.
+ *
+ * Iterates by code point, so surrogate pairs are handled correctly, and returns on the first hit.
+ * An empty string is `false`.
+ *
+ * Coverage is deliberately coarse: CJK Symbols and Punctuation, Hiragana, Katakana, Hangul
+ * Syllables, and CJK Unified Ideographs including Extension A. Everything beyond that — the
+ * higher ideograph extensions, Halfwidth and Fullwidth Forms, Hangul Jamo — reads as `false`, so
+ * a `false` is not proof that the text is CJK-free.
+ *
+ * The reason to ask is FTS5: the default tokenizer splits on whitespace, which CJK text does not
+ * use, so a matching query against it returns nothing rather than failing. A caller seeing `true`
+ * should short-circuit to an empty result or a LIKE fallback instead of running the search and
+ * reporting no matches.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function containsCjk(text: string): boolean;

package/dist/internal/persistence/fts5-sanitize.d.ts

@@ -13,4 +13,32 @@
  *
  * @internal
  */
-export {};
+/**
+ * Six-step FTS5 query sanitizer. Returns a query string safe for passing
+ * to `WHERE <fts5_table> MATCH ?` as a parameter.
+ *
+ * Returns empty string when the input contains only specials (caller MUST
+ * short-circuit to avoid runtime SQL error — EC-3).
+ *
+ */
+export declare function sanitizeFts5Query(query: string): string;
+/**
+ * Report whether `text` holds at least one Chinese, Japanese or Korean character.
+ *
+ * Iterates by code point, so surrogate pairs are handled correctly, and returns on the first hit.
+ * An empty string is `false`.
+ *
+ * Coverage is deliberately coarse: CJK Symbols and Punctuation, Hiragana, Katakana, Hangul
+ * Syllables, and CJK Unified Ideographs including Extension A. Everything beyond that — the
+ * higher ideograph extensions, Halfwidth and Fullwidth Forms, Hangul Jamo — reads as `false`, so
+ * a `false` is not proof that the text is CJK-free.
+ *
+ * The reason to ask is FTS5: the default tokenizer splits on whitespace, which CJK text does not
+ * use, so a matching query against it returns nothing rather than failing. A caller seeing `true`
+ * should short-circuit to an empty result or a LIKE fallback instead of running the search and
+ * reporting no matches.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function containsCjk(text: string): boolean;

package/dist/internal/persistence/index.cjs

@@ -1,13 +1,14 @@
 'use strict';
 
-var chunkPNVDQL5Y_cjs = require('../../chunk-PNVDQL5Y.cjs');
-var chunkCZHPR2G7_cjs = require('../../chunk-CZHPR2G7.cjs');
-var chunkTR4V2LHV_cjs = require('../../chunk-TR4V2LHV.cjs');
-var chunkQLAWEGTZ_cjs = require('../../chunk-QLAWEGTZ.cjs');
-var chunkYLQQX5W2_cjs = require('../../chunk-YLQQX5W2.cjs');
-var chunk2CFEET3Y_cjs = require('../../chunk-2CFEET3Y.cjs');
-require('../../chunk-2YGIBOUH.cjs');
-require('../../chunk-SXSPMRSV.cjs');
+var chunkVTYY7XL5_cjs = require('../../chunk-VTYY7XL5.cjs');
+var chunkU2AC6JUP_cjs = require('../../chunk-U2AC6JUP.cjs');
+var chunkSKXBJ2NU_cjs = require('../../chunk-SKXBJ2NU.cjs');
+var chunk2ADR2GSO_cjs = require('../../chunk-2ADR2GSO.cjs');
+var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
+var chunkI6TGFUCO_cjs = require('../../chunk-I6TGFUCO.cjs');
+require('../../chunk-K3FW2XZD.cjs');
+require('../../chunk-JTB5Q42C.cjs');
+require('../../chunk-NUKRL3I6.cjs');
 var promises = require('fs/promises');
 
 async function createExclusive(path, data, options) {
@@ -37,87 +38,87 @@ function casUpdate(db, sql, params, expectedChanges = 1) {
 
 Object.defineProperty(exports, "PersistenceSchema", {
   enumerable: true,
-  get: function () { return chunkPNVDQL5Y_cjs.PersistenceSchema; }
+  get: function () { return chunkVTYY7XL5_cjs.PersistenceSchema; }
 });
 Object.defineProperty(exports, "displayTheokitHome", {
   enumerable: true,
-  get: function () { return chunkCZHPR2G7_cjs.displayTheokitHome; }
+  get: function () { return chunkU2AC6JUP_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkCZHPR2G7_cjs.getProfilesRoot; }
+  get: function () { return chunkU2AC6JUP_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkCZHPR2G7_cjs.getTheokitHome; }
+  get: function () { return chunkU2AC6JUP_cjs.getTheokitHome; }
 });
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunkCZHPR2G7_cjs.migrateSchema; }
+  get: function () { return chunkU2AC6JUP_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "readVersionedJson", {
   enumerable: true,
-  get: function () { return chunkCZHPR2G7_cjs.readVersionedJson; }
+  get: function () { return chunkU2AC6JUP_cjs.readVersionedJson; }
 });
 Object.defineProperty(exports, "writeVersionedJson", {
   enumerable: true,
-  get: function () { return chunkCZHPR2G7_cjs.writeVersionedJson; }
+  get: function () { return chunkU2AC6JUP_cjs.writeVersionedJson; }
 });
-Object.defineProperty(exports, "JsonlParseError", {
+Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunkTR4V2LHV_cjs.JsonlParseError; }
+  get: function () { return chunkSKXBJ2NU_cjs.applyWalWithFallback; }
 });
-Object.defineProperty(exports, "appendJsonl", {
+Object.defineProperty(exports, "containsCjk", {
   enumerable: true,
-  get: function () { return chunkTR4V2LHV_cjs.appendJsonl; }
+  get: function () { return chunkSKXBJ2NU_cjs.containsCjk; }
 });
-Object.defineProperty(exports, "loadJsonl", {
+Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunkTR4V2LHV_cjs.loadJsonl; }
+  get: function () { return chunkSKXBJ2NU_cjs.isCorruptionError; }
 });
-Object.defineProperty(exports, "readJsonlIds", {
+Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunkTR4V2LHV_cjs.readJsonlIds; }
+  get: function () { return chunkSKXBJ2NU_cjs.openSqliteResilient; }
 });
-Object.defineProperty(exports, "withFileLock", {
+Object.defineProperty(exports, "sanitizeFts5Query", {
   enumerable: true,
-  get: function () { return chunkTR4V2LHV_cjs.withFileLock; }
+  get: function () { return chunkSKXBJ2NU_cjs.sanitizeFts5Query; }
 });
-Object.defineProperty(exports, "applyWalWithFallback", {
+Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkQLAWEGTZ_cjs.applyWalWithFallback; }
+  get: function () { return chunk2ADR2GSO_cjs.JsonlParseError; }
 });
-Object.defineProperty(exports, "containsCjk", {
+Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkQLAWEGTZ_cjs.containsCjk; }
+  get: function () { return chunk2ADR2GSO_cjs.appendJsonl; }
 });
-Object.defineProperty(exports, "isCorruptionError", {
+Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkQLAWEGTZ_cjs.isCorruptionError; }
+  get: function () { return chunk2ADR2GSO_cjs.loadJsonl; }
 });
-Object.defineProperty(exports, "openSqliteResilient", {
+Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkQLAWEGTZ_cjs.openSqliteResilient; }
+  get: function () { return chunk2ADR2GSO_cjs.readJsonlIds; }
 });
-Object.defineProperty(exports, "sanitizeFts5Query", {
+Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkQLAWEGTZ_cjs.sanitizeFts5Query; }
+  get: function () { return chunk2ADR2GSO_cjs.withFileLock; }
 });
 Object.defineProperty(exports, "withCwdMutex", {
   enumerable: true,
-  get: function () { return chunkYLQQX5W2_cjs.withCwdMutex; }
+  get: function () { return chunkZF2LDKQQ_cjs.withCwdMutex; }
 });
 Object.defineProperty(exports, "atomicWriteJson", {
   enumerable: true,
-  get: function () { return chunk2CFEET3Y_cjs.atomicWriteJson; }
+  get: function () { return chunkI6TGFUCO_cjs.atomicWriteJson; }
 });
 Object.defineProperty(exports, "atomicWriteText", {
   enumerable: true,
-  get: function () { return chunk2CFEET3Y_cjs.atomicWriteText; }
+  get: function () { return chunkI6TGFUCO_cjs.atomicWriteText; }
 });
 Object.defineProperty(exports, "replaceFileAtomic", {
   enumerable: true,
-  get: function () { return chunk2CFEET3Y_cjs.replaceFileAtomic; }
+  get: function () { return chunkI6TGFUCO_cjs.replaceFileAtomic; }
 });
 exports.casUpdate = casUpdate;
 exports.createExclusive = createExclusive;

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;AAgCA,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,MAAMA,aAAA,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;;;ACjBO,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.cjs","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 * Atomically create `path` with `data`. Returns true iff this call\n * created the file (race-free under POSIX-compliant filesystems).\n *\n * @internal\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 * @internal\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Execute a CAS UPDATE. Returns true iff the actual changes count matches\n * `expectedChanges`. SQL errors (invalid syntax, closed db) propagate.\n *\n * @internal\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":["open"],"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,MAAMA,aAAA,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.cjs","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/index.d.cts

@@ -7,8 +7,13 @@
  * barrel `@theokit/sdk/persistence` instead. This alias re-exports the FULL current
  * surface UNCHANGED for one release (external back-compat, EC-1); it is scheduled
  * for removal in a future major. See `final_report.md § MEDIUM — internal/persistence`.
- * @internal
+ *
+ * Semver-exempt: everything reachable through this sub-path is an internal primitive and is NOT
+ * covered by the package's semver contract. It is nonetheless declared in `package.json` `exports`,
+ * so it MUST be emitted into the published declarations — a tag that erased it here would break
+ * every consumer the back-compat alias exists to serve.
  */
+export type { AtomicWriteJsonOptions } from "./atomic-write.js";
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from "./atomic-write.js";
 export { withCwdMutex } from "./cwd-mutex.js";
 export type { CreateExclusiveOptions } from "./exclusive-create.js";

package/dist/internal/persistence/index.d.ts

@@ -7,8 +7,13 @@
  * barrel `@theokit/sdk/persistence` instead. This alias re-exports the FULL current
  * surface UNCHANGED for one release (external back-compat, EC-1); it is scheduled
  * for removal in a future major. See `final_report.md § MEDIUM — internal/persistence`.
- * @internal
+ *
+ * Semver-exempt: everything reachable through this sub-path is an internal primitive and is NOT
+ * covered by the package's semver contract. It is nonetheless declared in `package.json` `exports`,
+ * so it MUST be emitted into the published declarations — a tag that erased it here would break
+ * every consumer the back-compat alias exists to serve.
  */
+export type { AtomicWriteJsonOptions } from "./atomic-write.js";
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from "./atomic-write.js";
 export { withCwdMutex } from "./cwd-mutex.js";
 export type { CreateExclusiveOptions } from "./exclusive-create.js";

package/dist/internal/persistence/index.js

@@ -1,11 +1,12 @@
-export { PersistenceSchema } from '../../chunk-CAH3G4IS.js';
-export { displayTheokitHome, getProfilesRoot, getTheokitHome, migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-L7EGRCKJ.js';
-export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-HTK54K2J.js';
-export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-W4FV7JBH.js';
-export { withCwdMutex } from '../../chunk-2XLKLVVR.js';
-export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-CHVSMEKM.js';
-import '../../chunk-HI4ZW62S.js';
-import '../../chunk-4X3SBHPK.js';
+export { PersistenceSchema } from '../../chunk-HY66GLM6.js';
+export { displayTheokitHome, getProfilesRoot, getTheokitHome, migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-UPRJR6IP.js';
+export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-CQ2TQ32Y.js';
+export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-CV7XMBHP.js';
+export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
+export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-VF7EWVDG.js';
+import '../../chunk-IDCKSLYH.js';
+import '../../chunk-T7XEKOVW.js';
+import '../../chunk-T7O6K6PX.js';
 import { open } from 'fs/promises';
 
 async function createExclusive(path, data, options) {

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":";;;;;;;;;;AAgCA,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;;;ACjBO,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 * Atomically create `path` with `data`. Returns true iff this call\n * created the file (race-free under POSIX-compliant filesystems).\n *\n * @internal\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 * @internal\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Execute a CAS UPDATE. Returns true iff the actual changes count matches\n * `expectedChanges`. SQL errors (invalid syntax, closed db) propagate.\n *\n * @internal\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/paths.d.cts

@@ -26,4 +26,57 @@
  *
  * @internal
  */
-export {};
+/**
+ * Resolve the directory cwd-anchored SDK state lives in.
+ *
+ * `THEOKIT_HOME` wins when it is set and not blank after trimming; the trimmed value is used, and
+ * it is used VERBATIM — it is not resolved against `cwd`, so a relative value stays relative and
+ * `.theokit` is not appended to it. Otherwise the answer is `<cwd>/.theokit`.
+ *
+ * The environment is read on every call, so a change to the variable takes effect immediately
+ * rather than being frozen at import.
+ *
+ * This creates nothing and checks nothing: the returned path may not exist, and the caller owns
+ * the `mkdir`. Call it instead of writing `join(cwd, ".theokit")` by hand, or the override stops
+ * working for that one call site and tests silently touch the real home.
+ *
+ * Not the whole story about where state lives — the transcript is home-anchored via
+ * `transcriptRoot()`, honoring the same variable but defaulting to `~/.theokit`. With
+ * `THEOKIT_HOME` unset, state is genuinely split between two roots.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function getTheokitHome(cwd: string): string;
+/**
+ * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
+ *
+ * Deliberately NOT affected by `THEOKIT_HOME`, which is the one thing to remember about it. If it
+ * followed the override, a session pointed at one profile would only be able to see that profile,
+ * and `theokit profile list` could never enumerate the rest. Profiles are the thing the override
+ * switches between, so their index cannot live behind it.
+ *
+ * Takes no `cwd` for the same reason. Creates nothing; the path may not exist.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function getProfilesRoot(): string;
+/**
+ * The same path `getTheokitHome(cwd)` returns, shortened for display: the home directory prefix
+ * collapses to `~`, so `/home/ada/.theokit` prints as `~/.theokit`.
+ *
+ * For humans only — log lines, CLI output, error messages. The result is NOT a usable path: `~`
+ * is a shell convention that `fs` does not expand, so passing this to a filesystem call resolves
+ * a literal directory named `~` relative to the process cwd. Use `getTheokitHome` for anything
+ * that touches disk.
+ *
+ * Collapsing is a prefix match on the home directory followed by a literal `/`, so a sibling like
+ * `/home/adalovelace` is left alone even though `/home/ada` is a string prefix of it. A path
+ * outside the home directory comes back unchanged — and so does a Windows path, where the
+ * separator is a backslash and the prefix test therefore never matches.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function displayTheokitHome(cwd: string): string;

package/dist/internal/persistence/paths.d.ts

@@ -26,4 +26,57 @@
  *
  * @internal
  */
-export {};
+/**
+ * Resolve the directory cwd-anchored SDK state lives in.
+ *
+ * `THEOKIT_HOME` wins when it is set and not blank after trimming; the trimmed value is used, and
+ * it is used VERBATIM — it is not resolved against `cwd`, so a relative value stays relative and
+ * `.theokit` is not appended to it. Otherwise the answer is `<cwd>/.theokit`.
+ *
+ * The environment is read on every call, so a change to the variable takes effect immediately
+ * rather than being frozen at import.
+ *
+ * This creates nothing and checks nothing: the returned path may not exist, and the caller owns
+ * the `mkdir`. Call it instead of writing `join(cwd, ".theokit")` by hand, or the override stops
+ * working for that one call site and tests silently touch the real home.
+ *
+ * Not the whole story about where state lives — the transcript is home-anchored via
+ * `transcriptRoot()`, honoring the same variable but defaulting to `~/.theokit`. With
+ * `THEOKIT_HOME` unset, state is genuinely split between two roots.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function getTheokitHome(cwd: string): string;
+/**
+ * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
+ *
+ * Deliberately NOT affected by `THEOKIT_HOME`, which is the one thing to remember about it. If it
+ * followed the override, a session pointed at one profile would only be able to see that profile,
+ * and `theokit profile list` could never enumerate the rest. Profiles are the thing the override
+ * switches between, so their index cannot live behind it.
+ *
+ * Takes no `cwd` for the same reason. Creates nothing; the path may not exist.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function getProfilesRoot(): string;
+/**
+ * The same path `getTheokitHome(cwd)` returns, shortened for display: the home directory prefix
+ * collapses to `~`, so `/home/ada/.theokit` prints as `~/.theokit`.
+ *
+ * For humans only — log lines, CLI output, error messages. The result is NOT a usable path: `~`
+ * is a shell convention that `fs` does not expand, so passing this to a filesystem call resolves
+ * a literal directory named `~` relative to the process cwd. Use `getTheokitHome` for anything
+ * that touches disk.
+ *
+ * Collapsing is a prefix match on the home directory followed by a literal `/`, so a sibling like
+ * `/home/adalovelace` is left alone even though `/home/ada` is a string prefix of it. A path
+ * outside the home directory comes back unchanged — and so does a Windows path, where the
+ * separator is a backslash and the prefix test therefore never matches.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function displayTheokitHome(cwd: string): string;

package/dist/internal/persistence/persistence-schema.d.cts

@@ -3,8 +3,16 @@
  * used by both `Workflow` snapshots and `Cache` semantic store persistence.
  * Extracted to remove the cross-module clone flagged by jscpd.
  *
- * @internal
+ * `PersistenceSchema` is re-exported from the semver-protected `@theokit/sdk/persistence` barrel
+ * and from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
  */
+import { z } from "zod";
 /**
  * `persistence?` opt-in JSON disk backend with `dir` required when chosen.
  *

package/dist/internal/persistence/persistence-schema.d.ts

@@ -3,8 +3,16 @@
  * used by both `Workflow` snapshots and `Cache` semantic store persistence.
  * Extracted to remove the cross-module clone flagged by jscpd.
  *
- * @internal
+ * `PersistenceSchema` is re-exported from the semver-protected `@theokit/sdk/persistence` barrel
+ * and from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
  */
+import { z } from "zod";
 /**
  * `persistence?` opt-in JSON disk backend with `dir` required when chosen.
  *