@theokit/sdk 4.53.1 → 4.55.0

package/dist/internal/persistence/index.cjs

@@ -1,13 +1,14 @@
 'use strict';
 
-var chunkPNVDQL5Y_cjs = require('../../chunk-PNVDQL5Y.cjs');
-var chunkHAWE74GQ_cjs = require('../../chunk-HAWE74GQ.cjs');
-var chunkTTJ54H3E_cjs = require('../../chunk-TTJ54H3E.cjs');
-var chunkJIQRXKTA_cjs = require('../../chunk-JIQRXKTA.cjs');
-var chunkYLQQX5W2_cjs = require('../../chunk-YLQQX5W2.cjs');
-var chunkC4H6PB5J_cjs = require('../../chunk-C4H6PB5J.cjs');
-require('../../chunk-LPVIRJVF.cjs');
-require('../../chunk-BM6N4KHO.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 chunkHAWE74GQ_cjs.displayTheokitHome; }
+  get: function () { return chunkU2AC6JUP_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkHAWE74GQ_cjs.getProfilesRoot; }
+  get: function () { return chunkU2AC6JUP_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkHAWE74GQ_cjs.getTheokitHome; }
+  get: function () { return chunkU2AC6JUP_cjs.getTheokitHome; }
 });
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunkHAWE74GQ_cjs.migrateSchema; }
+  get: function () { return chunkU2AC6JUP_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "readVersionedJson", {
   enumerable: true,
-  get: function () { return chunkHAWE74GQ_cjs.readVersionedJson; }
+  get: function () { return chunkU2AC6JUP_cjs.readVersionedJson; }
 });
 Object.defineProperty(exports, "writeVersionedJson", {
   enumerable: true,
-  get: function () { return chunkHAWE74GQ_cjs.writeVersionedJson; }
+  get: function () { return chunkU2AC6JUP_cjs.writeVersionedJson; }
 });
-Object.defineProperty(exports, "JsonlParseError", {
+Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunkTTJ54H3E_cjs.JsonlParseError; }
+  get: function () { return chunkSKXBJ2NU_cjs.applyWalWithFallback; }
 });
-Object.defineProperty(exports, "appendJsonl", {
+Object.defineProperty(exports, "containsCjk", {
   enumerable: true,
-  get: function () { return chunkTTJ54H3E_cjs.appendJsonl; }
+  get: function () { return chunkSKXBJ2NU_cjs.containsCjk; }
 });
-Object.defineProperty(exports, "loadJsonl", {
+Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunkTTJ54H3E_cjs.loadJsonl; }
+  get: function () { return chunkSKXBJ2NU_cjs.isCorruptionError; }
 });
-Object.defineProperty(exports, "readJsonlIds", {
+Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunkTTJ54H3E_cjs.readJsonlIds; }
+  get: function () { return chunkSKXBJ2NU_cjs.openSqliteResilient; }
 });
-Object.defineProperty(exports, "withFileLock", {
+Object.defineProperty(exports, "sanitizeFts5Query", {
   enumerable: true,
-  get: function () { return chunkTTJ54H3E_cjs.withFileLock; }
+  get: function () { return chunkSKXBJ2NU_cjs.sanitizeFts5Query; }
 });
-Object.defineProperty(exports, "applyWalWithFallback", {
+Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkJIQRXKTA_cjs.applyWalWithFallback; }
+  get: function () { return chunk2ADR2GSO_cjs.JsonlParseError; }
 });
-Object.defineProperty(exports, "containsCjk", {
+Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkJIQRXKTA_cjs.containsCjk; }
+  get: function () { return chunk2ADR2GSO_cjs.appendJsonl; }
 });
-Object.defineProperty(exports, "isCorruptionError", {
+Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkJIQRXKTA_cjs.isCorruptionError; }
+  get: function () { return chunk2ADR2GSO_cjs.loadJsonl; }
 });
-Object.defineProperty(exports, "openSqliteResilient", {
+Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkJIQRXKTA_cjs.openSqliteResilient; }
+  get: function () { return chunk2ADR2GSO_cjs.readJsonlIds; }
 });
-Object.defineProperty(exports, "sanitizeFts5Query", {
+Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkJIQRXKTA_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 chunkC4H6PB5J_cjs.atomicWriteJson; }
+  get: function () { return chunkI6TGFUCO_cjs.atomicWriteJson; }
 });
 Object.defineProperty(exports, "atomicWriteText", {
   enumerable: true,
-  get: function () { return chunkC4H6PB5J_cjs.atomicWriteText; }
+  get: function () { return chunkI6TGFUCO_cjs.atomicWriteText; }
 });
 Object.defineProperty(exports, "replaceFileAtomic", {
   enumerable: true,
-  get: function () { return chunkC4H6PB5J_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-PBZ7HMBP.js';
-export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-NZL4BNFQ.js';
-export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-MSFLYJDY.js';
-export { withCwdMutex } from '../../chunk-2XLKLVVR.js';
-export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-6AZDM6LK.js';
-import '../../chunk-U4UJHOSH.js';
-import '../../chunk-5F5NWKPN.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.
  *

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

@@ -10,4 +10,218 @@
  *
  * @internal
  */
-export {};
+/**
+ * The three `better-sqlite3` methods this module actually uses, declared structurally so nothing
+ * here imports the driver.
+ *
+ * A real `better-sqlite3` `Database` satisfies it. `pragma` is called both to read
+ * (`pragma("user_version", { simple: true })`, which must return the number itself rather than a
+ * row array) and to write (`pragma("user_version = N")`). `transaction` must return a function
+ * that, when called, runs the wrapped body inside a real SQLite transaction and rolls it back if
+ * the body throws — a stub that merely calls through gives `migrateSchema` no atomicity, and a
+ * half-applied migration is exactly what it exists to prevent.
+ *
+ * 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 interface SqliteLike {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+    exec: (sql: string) => void;
+    transaction: <Args extends unknown[], R>(fn: (...args: Args) => R) => (...args: Args) => R;
+}
+/**
+ * One forward migration step.
+ *
+ * `up` runs inside the shared transaction and must be self-contained: it may not commit, and any
+ * error it throws aborts the whole run and rolls back every step in it, including the ones that
+ * already succeeded. `user_version` is set to `toVersion` immediately after `up` returns, inside
+ * the same transaction, so version and schema move together or not at all.
+ *
+ * `toVersion` is the version the database reaches, not the one it starts from. Steps are ordered
+ * by it, gaps are allowed, and two steps sharing a `toVersion` both run — nothing deduplicates
+ * them.
+ *
+ * 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 interface Migration {
+    toVersion: number;
+    up: (db: SqliteLike) => void;
+}
+/**
+ * Arguments to `migrateSchema`.
+ *
+ * `currentVersion` is the version the code expects, and it is the ceiling: a migration whose
+ * `toVersion` exceeds it is left unapplied for a later release. `migrations` may be given in any
+ * order and may contain steps already applied — both are filtered and sorted here. `label` only
+ * ever appears in the downgrade error message.
+ *
+ * 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 interface MigrateSchemaOptions {
+    db: SqliteLike;
+    currentVersion: number;
+    migrations: ReadonlyArray<Migration>;
+    /** For log/error context (e.g., "memory-index", "registry"). */
+    label?: string;
+}
+/**
+ * What `migrateSchema` did.
+ *
+ * `from` is the `user_version` found on the database, `to` is the version it holds afterwards,
+ * and `ran` is how many steps executed. When nothing was pending, `to === from` and `ran === 0`.
+ *
+ * `to` is the `toVersion` of the last step applied, NOT `currentVersion`. A database at version 3
+ * against `currentVersion: 5` with no migration in that range comes back as
+ * `{ from: 3, to: 3, ran: 0 }` — the gap is reported, not closed. Comparing `to` with
+ * `currentVersion` is how a caller notices that the migration list is missing a step.
+ *
+ * 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 interface MigrateSchemaResult {
+    from: number;
+    to: number;
+    ran: number;
+}
+/**
+ * Bring a SQLite database's `user_version` up to `currentVersion` by running the steps that sit
+ * between the two.
+ *
+ * Steps are sorted ascending by `toVersion` and filtered to `> stored && <= currentVersion`, then
+ * run in that order inside ONE transaction: each `up` is followed immediately by the matching
+ * `user_version` write. Either every step in the run commits or none does — a step that throws
+ * aborts the transaction, propagates the error, and leaves the database at the version it started
+ * from. There is no partially-migrated state and no resume point.
+ *
+ * Forward-only. When the stored version is greater than `currentVersion` — an older build opening
+ * a database a newer one already migrated — this throws immediately, before touching anything,
+ * with a message naming both versions and `label`. Nothing downgrades, and no data is deleted on
+ * any path here; what a step does is the step's own business.
+ *
+ * A stored version equal to `currentVersion` returns without opening a transaction. A `user_version`
+ * that is absent or not a number is read as 0, so a fresh database runs every step.
+ *
+ * Concurrency: the SQLite transaction is the only serialization. This takes no file lock, so two
+ * processes migrating the same file at once are arbitrated by SQLite's own write lock — the loser
+ * gets a busy or locked error from the driver, not a queued turn. Wrap the call in `withFileLock`
+ * if that matters.
+ *
+ * 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 migrateSchema(opts: MigrateSchemaOptions): MigrateSchemaResult;
+/**
+ * The on-disk envelope: the payload under `data`, its schema version alongside it.
+ *
+ * `writeVersionedJson` always produces this shape. `readVersionedJson` reads it, but tolerates a
+ * file that is not in it — a legacy object with no `_schemaVersion` is treated as version 0 and
+ * handed to the migrate callback whole, so this type describes what is written, not everything
+ * that can be read.
+ *
+ * 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 interface VersionedJsonFile<T> {
+    _schemaVersion: number;
+    data: T;
+}
+/**
+ * Upgrade callback for `readVersionedJson`, invoked only when the stored version is BELOW the
+ * current one.
+ *
+ * `parsed` is the whole parsed JSON value, not `parsed.data`. That is deliberate: a legacy file
+ * predating the envelope has its fields at the top level, and a callback handed only `.data`
+ * would receive `undefined` for exactly the files that need migrating. It is typed `unknown`
+ * because nothing has validated it — narrow before reading.
+ *
+ * `fromVersion` is the `_schemaVersion` found on disk, or 0 when the field is missing or not a
+ * number.
+ *
+ * The return value is used as-is and is NOT written back; the file on disk still holds the old
+ * shape until someone calls `writeVersionedJson`. Throwing here propagates out of
+ * `readVersionedJson`, which otherwise never throws — return the default value instead if an
+ * unmigratable file should be survivable.
+ *
+ * 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 type VersionedJsonMigrate<T> = (parsed: unknown, fromVersion: number) => T;
+/**
+ * Arguments to `readVersionedJson`.
+ *
+ * `defaultValue` is a factory rather than a value because it is called on several paths and each
+ * caller must get its own object — returning a shared mutable default would let one caller's
+ * edits appear in another's. It is called for a missing file, an unreadable one, a corrupt one,
+ * a non-object payload, and a file written by a newer version.
+ *
+ * `migrate` is called only for a stored version strictly below `currentVersion`.
+ *
+ * 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 interface ReadVersionedJsonOptions<T> {
+    path: string;
+    currentVersion: number;
+    migrate: VersionedJsonMigrate<T>;
+    defaultValue: () => T;
+}
+/**
+ * Read a versioned JSON file, migrating or falling back rather than failing.
+ *
+ * What comes back, by case:
+ *
+ *   - version matches `currentVersion` — the file's `data` field, returned as `T` WITHOUT
+ *     validation. A file whose envelope is right but whose payload is not gets through.
+ *   - version below `currentVersion` — whatever `migrate(parsed, stored)` returns. The migrated
+ *     value is not persisted; the file is untouched.
+ *   - version above `currentVersion` — `defaultValue()`, plus a warning. Forward-only: a file
+ *     written by a newer build is left alone rather than downgraded.
+ *   - file missing, or unreadable for any other reason (permissions, a directory in its place) —
+ *     `defaultValue()`, silently. Absence and denial are not distinguished.
+ *   - file present but not valid JSON — `defaultValue()`, and the file is RENAMED to
+ *     `<path>.corrupt.<epoch-ms>` so the next run starts clean and the bad bytes stay available.
+ *     A rename that itself fails is warned about and the read still returns the default, which
+ *     means the same corrupt file will be met again next time.
+ *   - JSON that parses to a non-object (a number, a string, `null`) — `defaultValue()`, silently
+ *     and without moving the file aside.
+ *
+ * The only ways this throws are through the callbacks you supply: `migrate` or `defaultValue`
+ * raising. Nothing else here rejects.
+ *
+ * There is no locking. A concurrent `writeVersionedJson` on the same path is atomic at the rename,
+ * so a reader sees either the old file or the new one, never a half-written one — but a
+ * read-modify-write built from this pair is NOT atomic across the two calls, and needs
+ * `withFileLock` around both.
+ *
+ * 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 readVersionedJson<T>(opts: ReadVersionedJsonOptions<T>): Promise<T>;
+/**
+ * Write `data` wrapped in the version envelope, replacing the file atomically.
+ *
+ * The bytes go to a temp file in the same directory and are moved into place with `rename`, so a
+ * crash or a concurrent reader never observes a partial file: the path holds either the previous
+ * content or the complete new content. Parent directories are created as needed, and the file is
+ * created with mode 0600 (subject to the process umask), formatted with two-space indentation and
+ * a trailing newline.
+ *
+ * `currentVersion` is stamped verbatim as `_schemaVersion`; nothing checks it against what was
+ * already on disk, so this will happily overwrite a newer file with an older version. Read first
+ * if that matters.
+ *
+ * Rejects when `data` cannot be serialized — a circular reference, or a `toJSON` that throws.
+ * Serialization happens before any filesystem call, so on that path no directory is created, no
+ * temp file exists, and the file already on disk is untouched.
+ *
+ * Atomicity is the rename's, so it is as strong as the filesystem's: on NFS, SMB or FUSE the
+ * underlying writer emits a one-shot warning that the guarantee is weaker there.
+ *
+ * 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 writeVersionedJson<T>(path: string, data: T, currentVersion: number): Promise<void>;