@theokit/sdk 4.63.3 → 5.0.0-next.1

package/dist/internal/memory/lance-memory-adapter.d.ts

@@ -7,15 +7,22 @@
  * Semantic deltas vs SQLite (documented so callers know what to expect):
  *
  *  - `sync()` is a NO-OP. Lance is a pure vector store — there is no
- *    markdown corpus to crawl. Returns zero counts. Consumers writing
- *    facts use `LanceIndex.addFacts` directly (exposed via the index
- *    object returned to advanced callers).
- *  - `search()` performs vector-only retrieval. `MemorySearchHit.textScore`
- *    is undefined (no FTS5 layer); `vectorScore === score`.
+ *    markdown corpus to crawl. It returns zero counts with `supported: false`
+ *    so the result is not mistaken for a sync that found nothing. Consumers
+ *    writing facts hold a `LanceIndex` and call `addFacts` on it; the adapter
+ *    does not hand its adaptee out.
+ *  - `search()` is HYBRID, not vector-only. Lance supplies the vector distance
+ *    and `translateLanceHit` adds a client-side term-overlap ratio (T4.5), so
+ *    `textScore` is a real number in 0..1 and `score` is `0.7 * vectorScore +
+ *    0.3 * textScore` — never `=== vectorScore`. This block said the opposite
+ *    for as long as T4.5 has been shipped, while the docblock 90 lines below
+ *    described the change correctly, so the two halves of one file disagreed
+ *    and the header is the half a caller reads.
  *  - `status()` reports `backend: "hybrid"` only when an embedding runtime
  *    is wired (always the case for Lance — embedding is required at open).
- *    `chunksIndexed` reflects total Lance row count; `filesIndexed` is 0
- *    because Lance does not track file provenance per-row.
+ *    Both counts are 0 with `countsExact: false`: the port declares `status()`
+ *    synchronous and Lance's row count is async, so nothing can be measured
+ *    here. The zeros are placeholders and the flag says which.
  *
  * Ships with the lancedb-backend-ship-v1-1 plan (close D12, supersede via
  * D43). v1.4.0 of `@theokit/sdk`.
@@ -28,16 +35,11 @@ export declare class LanceMemoryAdapter implements MemoryIndex {
     private readonly inner;
     constructor(inner: LanceIndex);
     /**
-     * No-op for Lance — see file header. Returns zero counts so callers'
-     * existing logging (`filesScanned: X`) does not break.
+     * Not applicable to Lance — see file header. Returns zero counts with `supported: false` so a
+     * caller can distinguish this from a real sync that found nothing.
      */
     sync(): Promise<SyncResult>;
     search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
     status(): IndexStatus;
     close(): Promise<void>;
-    /**
-     * Escape hatch for advanced callers (migration tool, benchmark script)
-     * that need direct access to addFacts/countFacts/removeFacts.
-     */
-    unwrap(): LanceIndex;
 }

package/dist/internal/memory/memory-index.d.ts

@@ -21,6 +21,21 @@ export interface SyncResult {
     filesUpdated: number;
     chunksWritten: number;
     chunksEmbedded: number;
+    /**
+     * Whether this backend actually walked a corpus.
+     *
+     * REQUIRED, not optional, and that is the point. `MemoryIndex` has two implementers and consumers
+     * hold the interface: `IndexManager` walks files, and `LanceMemoryAdapter` has no corpus to walk —
+     * it is a vector store fed by explicit `addFacts`. The adapter used to answer with a frozen
+     * all-zeros result, which a caller cannot tell apart from a real sync that found nothing to do.
+     * The comment above it stated that as the intention ("so callers' existing logging does not
+     * break"), which is the substitution defect written down as a feature.
+     *
+     * A required boolean forces every implementer to say which case it is in, and forces the compiler
+     * to notice a new implementer that forgot. An optional flag would have let the next backend
+     * reproduce the silence.
+     */
+    supported: boolean;
 }
 /**
  * Common search-options parser used by both `IndexManager.search` and

package/dist/internal/memory/sdk-memory-peer-loader.d.ts

@@ -18,4 +18,57 @@
  *
  * @internal
  */
-export {};
+/**
+ * Minimal structural mirror of the sdk-memory surface this loader
+ * exposes to Memory class methods. Keeps the contract pinned even
+ * if sdk-memory ships additional exports.
+ */
+export interface SdkMemoryModule {
+    /** Mirrors @theokit/sdk-memory's catalog Record. */
+    readonly MEMORY_EMBEDDING_ADAPTERS: Readonly<Record<string, {
+        readonly id: string;
+        readonly defaultModel: string;
+        readonly transport: "local" | "remote";
+        create(options: any): Promise<any>;
+    }>>;
+    /** Mirrors @theokit/sdk-memory's runDreamingSweep entrypoint. */
+    runDreamingSweep(opts: {
+        cwd: string;
+        embedding: any;
+        dedupThreshold?: number;
+        clusterThreshold?: number;
+    }): Promise<{
+        status: "ok" | "skipped" | "error";
+        factsBefore: number;
+        factsAfter: number;
+        duplicatesRemoved: number;
+        clustersCreated: number;
+        notesWritten: number;
+    }>;
+    /** Mirrors @theokit/sdk-memory's IndexManager class (static open). */
+    readonly IndexManager: {
+        open(opts: {
+            cwd: string;
+            filePath?: string;
+            embedding?: any;
+            backend?: "sqlite-vec" | "lance";
+        }): Promise<any>;
+    };
+    /** Mirrors @theokit/sdk-memory's migrateSqliteToLance entrypoint (ADR D44). */
+    migrateSqliteToLance(opts: {
+        cwd: string;
+        dryRun?: boolean;
+        batchSize?: number;
+        logger?: (msg: string) => void;
+    }): Promise<{
+        countSqlite: number;
+        countLance: number;
+        validated: boolean;
+        sampleComparisons: ReadonlyArray<{
+            id: string;
+            match: boolean;
+        }>;
+        lancePath: string;
+        committed: boolean;
+    }>;
+}

package/dist/internal/memory/storage/index.cjs

@@ -1,138 +1,137 @@
 'use strict';
 
-var chunkOFRFZRQ4_cjs = require('../../../chunk-OFRFZRQ4.cjs');
-var chunkGKEFRLU7_cjs = require('../../../chunk-GKEFRLU7.cjs');
-var chunkIAHZCGBE_cjs = require('../../../chunk-IAHZCGBE.cjs');
+var chunkV6ZY4AX6_cjs = require('../../../chunk-V6ZY4AX6.cjs');
+var chunkTMKTSYDS_cjs = require('../../../chunk-TMKTSYDS.cjs');
+var chunkLHSWHYF3_cjs = require('../../../chunk-LHSWHYF3.cjs');
 require('../../../chunk-KRD3GQAA.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
 require('../../../chunk-LKFET5A3.cjs');
-require('../../../chunk-V2BOS4WF.cjs');
-require('../../../chunk-VKJ7V7EB.cjs');
-require('../../../chunk-5HEG4CQH.cjs');
-require('../../../chunk-5VB22SYX.cjs');
+require('../../../chunk-7A6535RA.cjs');
+require('../../../chunk-SA6K24NB.cjs');
+require('../../../chunk-GZV6AVRL.cjs');
+require('../../../chunk-DQZU7JK6.cjs');
 require('../../../chunk-ZF2LDKQQ.cjs');
-require('../../../chunk-UALX2J2Q.cjs');
-require('../../../chunk-4ZHTIJNE.cjs');
-require('../../../chunk-XL7Q7HB2.cjs');
-require('../../../chunk-EG4QM7ZJ.cjs');
+require('../../../chunk-JLRLCBJ4.cjs');
+require('../../../chunk-J7J7J2GN.cjs');
+require('../../../chunk-6LHQPOMI.cjs');
 
 
 
 Object.defineProperty(exports, "appendDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkOFRFZRQ4_cjs.appendDiaryEntry; }
+  get: function () { return chunkV6ZY4AX6_cjs.appendDiaryEntry; }
 });
 Object.defineProperty(exports, "diaryPath", {
   enumerable: true,
-  get: function () { return chunkOFRFZRQ4_cjs.diaryPath; }
+  get: function () { return chunkV6ZY4AX6_cjs.diaryPath; }
 });
 Object.defineProperty(exports, "entryHash", {
   enumerable: true,
-  get: function () { return chunkOFRFZRQ4_cjs.entryHash; }
+  get: function () { return chunkV6ZY4AX6_cjs.entryHash; }
 });
 Object.defineProperty(exports, "readAllSqliteFacts", {
   enumerable: true,
-  get: function () { return chunkOFRFZRQ4_cjs.readAllSqliteFacts; }
+  get: function () { return chunkV6ZY4AX6_cjs.readAllSqliteFacts; }
 });
 Object.defineProperty(exports, "renderDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkOFRFZRQ4_cjs.renderDiaryEntry; }
+  get: function () { return chunkV6ZY4AX6_cjs.renderDiaryEntry; }
 });
 Object.defineProperty(exports, "persistActiveMemoryTranscript", {
   enumerable: true,
-  get: function () { return chunkGKEFRLU7_cjs.persistActiveMemoryTranscript; }
+  get: function () { return chunkTMKTSYDS_cjs.persistActiveMemoryTranscript; }
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.MEMORY_INDEX_MAX_BYTES; }
+  get: function () { return chunkLHSWHYF3_cjs.MEMORY_INDEX_MAX_BYTES; }
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.MEMORY_INDEX_MAX_LINES; }
+  get: function () { return chunkLHSWHYF3_cjs.MEMORY_INDEX_MAX_LINES; }
 });
 Object.defineProperty(exports, "appendFact", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.appendFact; }
+  get: function () { return chunkLHSWHYF3_cjs.appendFact; }
 });
 Object.defineProperty(exports, "appendFactToMarkdown", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.appendFactToMarkdown; }
+  get: function () { return chunkLHSWHYF3_cjs.appendFactToMarkdown; }
 });
 Object.defineProperty(exports, "asMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.asMemoryRoot; }
+  get: function () { return chunkLHSWHYF3_cjs.asMemoryRoot; }
 });
 Object.defineProperty(exports, "claudeProjectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.claudeProjectMemoryDir; }
+  get: function () { return chunkLHSWHYF3_cjs.claudeProjectMemoryDir; }
 });
 Object.defineProperty(exports, "collectMarkdownFiles", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.collectMarkdownFiles; }
+  get: function () { return chunkLHSWHYF3_cjs.collectMarkdownFiles; }
 });
 Object.defineProperty(exports, "defaultIndexPath", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.defaultIndexPath; }
+  get: function () { return chunkLHSWHYF3_cjs.defaultIndexPath; }
 });
 Object.defineProperty(exports, "discoverSessionFiles", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.discoverSessionFiles; }
+  get: function () { return chunkLHSWHYF3_cjs.discoverSessionFiles; }
 });
 Object.defineProperty(exports, "discoverWikiFiles", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.discoverWikiFiles; }
+  get: function () { return chunkLHSWHYF3_cjs.discoverWikiFiles; }
 });
 Object.defineProperty(exports, "indexBudgetWarning", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.indexBudgetWarning; }
+  get: function () { return chunkLHSWHYF3_cjs.indexBudgetWarning; }
 });
 Object.defineProperty(exports, "lanceStoragePath", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.lanceStoragePath; }
+  get: function () { return chunkLHSWHYF3_cjs.lanceStoragePath; }
 });
 Object.defineProperty(exports, "memoryMdPath", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.memoryMdPath; }
+  get: function () { return chunkLHSWHYF3_cjs.memoryMdPath; }
 });
 Object.defineProperty(exports, "memoryReadRoots", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.memoryReadRoots; }
+  get: function () { return chunkLHSWHYF3_cjs.memoryReadRoots; }
 });
 Object.defineProperty(exports, "notesDir", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.notesDir; }
+  get: function () { return chunkLHSWHYF3_cjs.notesDir; }
 });
 Object.defineProperty(exports, "projectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.projectMemoryDir; }
+  get: function () { return chunkLHSWHYF3_cjs.projectMemoryDir; }
 });
 Object.defineProperty(exports, "readFacts", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.readFacts; }
+  get: function () { return chunkLHSWHYF3_cjs.readFacts; }
 });
 Object.defineProperty(exports, "readFactsFromMarkdown", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.readFactsFromMarkdown; }
+  get: function () { return chunkLHSWHYF3_cjs.readFactsFromMarkdown; }
 });
 Object.defineProperty(exports, "resolveMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.resolveMemoryRoot; }
+  get: function () { return chunkLHSWHYF3_cjs.resolveMemoryRoot; }
 });
 Object.defineProperty(exports, "sessionSummaryPath", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.sessionSummaryPath; }
+  get: function () { return chunkLHSWHYF3_cjs.sessionSummaryPath; }
 });
 Object.defineProperty(exports, "sessionsDir", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.sessionsDir; }
+  get: function () { return chunkLHSWHYF3_cjs.sessionsDir; }
 });
 Object.defineProperty(exports, "wikiDir", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.wikiDir; }
+  get: function () { return chunkLHSWHYF3_cjs.wikiDir; }
 });
 Object.defineProperty(exports, "writeSessionSummary", {
   enumerable: true,
-  get: function () { return chunkIAHZCGBE_cjs.writeSessionSummary; }
+  get: function () { return chunkLHSWHYF3_cjs.writeSessionSummary; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/memory/storage/index.js

@@ -1,17 +1,16 @@
-export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-ACDLHN3W.js';
-export { persistActiveMemoryTranscript } from '../../../chunk-XO4SOZN6.js';
-export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-L4BDVXIM.js';
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-WJXOICRC.js';
+export { persistActiveMemoryTranscript } from '../../../chunk-OR6XIWLB.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-UNK4HNJH.js';
 import '../../../chunk-KVNWIAO4.js';
 import '../../../chunk-FD2UT76F.js';
 import '../../../chunk-WFC26L6Y.js';
-import '../../../chunk-HS7AVXTF.js';
-import '../../../chunk-RIAM53CP.js';
-import '../../../chunk-UMP6OJIM.js';
-import '../../../chunk-LWGSI6M3.js';
+import '../../../chunk-EH6XD3FY.js';
+import '../../../chunk-UKMBRMGT.js';
+import '../../../chunk-JOFVLOFY.js';
+import '../../../chunk-6PWOWXMC.js';
 import '../../../chunk-Q5EWJPRY.js';
-import '../../../chunk-2GUYQR5P.js';
-import '../../../chunk-ZZMZWBR6.js';
-import '../../../chunk-D4CUGAKZ.js';
-import '../../../chunk-XEQ3TM66.js';
+import '../../../chunk-3JHIFQ4I.js';
+import '../../../chunk-ALUN2B4W.js';
+import '../../../chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/internal/memory/storage/memory-root.d.cts

@@ -15,9 +15,8 @@ import type { MemoryConfig } from "../types.js";
  * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
  * the package boundary, which is where this type has to work.
  */
-export type MemoryRoot = string & {
-    readonly __memoryRoot: "resolved";
-};
+import type { MemoryRoot } from "../../../types/memory-provider.js";
+export type { MemoryRoot };
 /**
  * Treat a directory as a memory root without resolving one.
  *

package/dist/internal/memory/storage/memory-root.d.ts

@@ -15,9 +15,8 @@ import type { MemoryConfig } from "../types.js";
  * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
  * the package boundary, which is where this type has to work.
  */
-export type MemoryRoot = string & {
-    readonly __memoryRoot: "resolved";
-};
+import type { MemoryRoot } from "../../../types/memory-provider.js";
+export type { MemoryRoot };
 /**
  * Treat a directory as a memory root without resolving one.
  *

package/dist/internal/persistence/atomic-write.d.cts

@@ -1,6 +1,6 @@
 /**
  * M107 — temp-file creation control, shared by `replaceFileAtomic`,
- * `atomicWriteJson` e `atomicWriteText`.
+ * `atomicWriteJson` and `atomicWriteText`.
  *
  * Both fields are OPTIONAL and the default is byte-identical to the behavior
  * before M107. See `replaceFileAtomic` for why the mode reassertion
@@ -99,9 +99,9 @@ export interface AtomicWriteJsonOptions extends AtomicWriteFileOptions {
 export declare function atomicWriteJson<T>(filePath: string, data: T, options?: AtomicWriteJsonOptions): Promise<void>;
 /**
  * Atomic text write. Same crash-safety guarantees as `replaceFileAtomic` +
- * auto-mkdir of the parent directory. Used by `theokit-migrate-config`
- * (T4.1, EC-2 MUST FIX) so a crash mid-migration leaves previous MD files
- * intact rather than corrupting them.
+ * auto-mkdir of the parent directory. Written for `theokit-migrate-config` (T4.1, EC-2 MUST FIX) so
+ * a crash mid-migration left previous MD files intact rather than corrupting them; that CLI is no
+ * longer published, and the guarantee is the reason every other caller uses this too.
  *
  */
 export declare function atomicWriteText(filePath: string, content: string): Promise<void>;

package/dist/internal/persistence/atomic-write.d.ts

@@ -1,6 +1,6 @@
 /**
  * M107 — temp-file creation control, shared by `replaceFileAtomic`,
- * `atomicWriteJson` e `atomicWriteText`.
+ * `atomicWriteJson` and `atomicWriteText`.
  *
  * Both fields are OPTIONAL and the default is byte-identical to the behavior
  * before M107. See `replaceFileAtomic` for why the mode reassertion
@@ -99,9 +99,9 @@ export interface AtomicWriteJsonOptions extends AtomicWriteFileOptions {
 export declare function atomicWriteJson<T>(filePath: string, data: T, options?: AtomicWriteJsonOptions): Promise<void>;
 /**
  * Atomic text write. Same crash-safety guarantees as `replaceFileAtomic` +
- * auto-mkdir of the parent directory. Used by `theokit-migrate-config`
- * (T4.1, EC-2 MUST FIX) so a crash mid-migration leaves previous MD files
- * intact rather than corrupting them.
+ * auto-mkdir of the parent directory. Written for `theokit-migrate-config` (T4.1, EC-2 MUST FIX) so
+ * a crash mid-migration left previous MD files intact rather than corrupting them; that CLI is no
+ * longer published, and the guarantee is the reason every other caller uses this too.
  *
  */
 export declare function atomicWriteText(filePath: string, content: string): Promise<void>;

package/dist/internal/persistence/index.cjs

@@ -1,16 +1,15 @@
 'use strict';
 
 var chunkVTYY7XL5_cjs = require('../../chunk-VTYY7XL5.cjs');
-var chunk2HVF2WJY_cjs = require('../../chunk-2HVF2WJY.cjs');
+var chunkRQMCOFAI_cjs = require('../../chunk-RQMCOFAI.cjs');
 var chunkA4RAL2ER_cjs = require('../../chunk-A4RAL2ER.cjs');
-var chunk5VB22SYX_cjs = require('../../chunk-5VB22SYX.cjs');
-var chunkUU36SHFY_cjs = require('../../chunk-UU36SHFY.cjs');
+var chunkDQZU7JK6_cjs = require('../../chunk-DQZU7JK6.cjs');
+var chunkBJUJT5ED_cjs = require('../../chunk-BJUJT5ED.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
-var chunkUALX2J2Q_cjs = require('../../chunk-UALX2J2Q.cjs');
-var chunkAQO3NSRG_cjs = require('../../chunk-AQO3NSRG.cjs');
-require('../../chunk-4ZHTIJNE.cjs');
-require('../../chunk-XL7Q7HB2.cjs');
-require('../../chunk-EG4QM7ZJ.cjs');
+var chunkJLRLCBJ4_cjs = require('../../chunk-JLRLCBJ4.cjs');
+var chunkCEILSTWB_cjs = require('../../chunk-CEILSTWB.cjs');
+require('../../chunk-J7J7J2GN.cjs');
+require('../../chunk-6LHQPOMI.cjs');
 var promises = require('fs/promises');
 
 async function createExclusive(path, data, options) {
@@ -44,15 +43,15 @@ Object.defineProperty(exports, "PersistenceSchema", {
 });
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunk2HVF2WJY_cjs.migrateSchema; }
+  get: function () { return chunkRQMCOFAI_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "readVersionedJson", {
   enumerable: true,
-  get: function () { return chunk2HVF2WJY_cjs.readVersionedJson; }
+  get: function () { return chunkRQMCOFAI_cjs.readVersionedJson; }
 });
 Object.defineProperty(exports, "writeVersionedJson", {
   enumerable: true,
-  get: function () { return chunk2HVF2WJY_cjs.writeVersionedJson; }
+  get: function () { return chunkRQMCOFAI_cjs.writeVersionedJson; }
 });
 Object.defineProperty(exports, "containsCjk", {
   enumerable: true,
@@ -64,35 +63,35 @@ Object.defineProperty(exports, "sanitizeFts5Query", {
 });
 Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunk5VB22SYX_cjs.applyWalWithFallback; }
+  get: function () { return chunkDQZU7JK6_cjs.applyWalWithFallback; }
 });
 Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunk5VB22SYX_cjs.isCorruptionError; }
+  get: function () { return chunkDQZU7JK6_cjs.isCorruptionError; }
 });
 Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunk5VB22SYX_cjs.openSqliteResilient; }
+  get: function () { return chunkDQZU7JK6_cjs.openSqliteResilient; }
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.JsonlParseError; }
+  get: function () { return chunkBJUJT5ED_cjs.JsonlParseError; }
 });
 Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.appendJsonl; }
+  get: function () { return chunkBJUJT5ED_cjs.appendJsonl; }
 });
 Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.loadJsonl; }
+  get: function () { return chunkBJUJT5ED_cjs.loadJsonl; }
 });
 Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.readJsonlIds; }
+  get: function () { return chunkBJUJT5ED_cjs.readJsonlIds; }
 });
 Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.withFileLock; }
+  get: function () { return chunkBJUJT5ED_cjs.withFileLock; }
 });
 Object.defineProperty(exports, "withCwdMutex", {
   enumerable: true,
@@ -100,27 +99,27 @@ Object.defineProperty(exports, "withCwdMutex", {
 });
 Object.defineProperty(exports, "atomicWriteJson", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.atomicWriteJson; }
+  get: function () { return chunkJLRLCBJ4_cjs.atomicWriteJson; }
 });
 Object.defineProperty(exports, "atomicWriteText", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.atomicWriteText; }
+  get: function () { return chunkJLRLCBJ4_cjs.atomicWriteText; }
 });
 Object.defineProperty(exports, "replaceFileAtomic", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.replaceFileAtomic; }
+  get: function () { return chunkJLRLCBJ4_cjs.replaceFileAtomic; }
 });
 Object.defineProperty(exports, "displayTheokitHome", {
   enumerable: true,
-  get: function () { return chunkAQO3NSRG_cjs.displayTheokitHome; }
+  get: function () { return chunkCEILSTWB_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkAQO3NSRG_cjs.getProfilesRoot; }
+  get: function () { return chunkCEILSTWB_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkAQO3NSRG_cjs.getTheokitHome; }
+  get: function () { return chunkCEILSTWB_cjs.getTheokitHome; }
 });
 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":";;;;;;;;;;;;;;;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"]}
+{"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.js

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