@theokit/sdk 5.9.1 → 5.10.0

package/dist/{inject-session-YNNOE3O6.js → inject-session-O24XGRR6.js}

@@ -1,7 +1,7 @@
-import { enqueueSessionWrite } from './chunk-5522X223.js';
+import { enqueueSessionWrite } from './chunk-EXI7EHDN.js';
 import { invalidateSessionCache } from './chunk-2XC6KDJM.js';
-import './chunk-2WXHA33T.js';
-import { SessionTranscript } from './chunk-JOFVLOFY.js';
+import './chunk-XERM7PDQ.js';
+import { SessionTranscript } from './chunk-FTZTZBCU.js';
 import './chunk-3JHIFQ4I.js';
 import './chunk-AGACYRJ2.js';
 import './chunk-CZJ6Q7CW.js';
@@ -23,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-YNNOE3O6.js.map
-//# sourceMappingURL=inject-session-YNNOE3O6.js.map
+//# sourceMappingURL=inject-session-O24XGRR6.js.map
+//# sourceMappingURL=inject-session-O24XGRR6.js.map

package/dist/{inject-session-YNNOE3O6.js.map → inject-session-O24XGRR6.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-YNNOE3O6.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-O24XGRR6.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/{inject-session-3FPXJDJP.cjs → inject-session-OMLFL2V3.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
-var chunkPSLCVSCS_cjs = require('./chunk-PSLCVSCS.cjs');
+var chunkFR6COQXZ_cjs = require('./chunk-FR6COQXZ.cjs');
 var chunkYJNYDJ2T_cjs = require('./chunk-YJNYDJ2T.cjs');
-require('./chunk-YIFFF23U.cjs');
-var chunkGZV6AVRL_cjs = require('./chunk-GZV6AVRL.cjs');
+require('./chunk-ZAM7BJXJ.cjs');
+var chunkZWACQM5U_cjs = require('./chunk-ZWACQM5U.cjs');
 require('./chunk-JLRLCBJ4.cjs');
 require('./chunk-NVXXWAU7.cjs');
 require('./chunk-6LHQPOMI.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunkPSLCVSCS_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkFR6COQXZ_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
-    const transcript = chunkGZV6AVRL_cjs.SessionTranscript.fromRecords(prior, {
+    const transcript = chunkZWACQM5U_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
       sessionId: opts.sessionId,
       model: opts.loc.model ?? "unknown"
@@ -25,5 +25,5 @@ async function injectSessionTurn(opts) {
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-3FPXJDJP.cjs.map
-//# sourceMappingURL=inject-session-3FPXJDJP.cjs.map
+//# sourceMappingURL=inject-session-OMLFL2V3.cjs.map
+//# sourceMappingURL=inject-session-OMLFL2V3.cjs.map

package/dist/{inject-session-3FPXJDJP.cjs.map → inject-session-OMLFL2V3.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-3FPXJDJP.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-OMLFL2V3.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

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

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkMEUBLCM4_cjs = require('../../../chunk-MEUBLCM4.cjs');
+var chunkYEHQ3SIC_cjs = require('../../../chunk-YEHQ3SIC.cjs');
 var chunkGHX4P3V2_cjs = require('../../../chunk-GHX4P3V2.cjs');
 require('../../../chunk-WPO3VCY4.cjs');
 require('../../../chunk-QOGNZMHD.cjs');
@@ -9,6 +9,7 @@ require('../../../chunk-GM54F4FE.cjs');
 require('../../../chunk-SA6K24NB.cjs');
 require('../../../chunk-IIYJMXYW.cjs');
 require('../../../chunk-NJSIAJEK.cjs');
+require('../../../chunk-EHD25JBZ.cjs');
 require('../../../chunk-UNFBHV46.cjs');
 require('../../../chunk-6LHQPOMI.cjs');
 
@@ -16,7 +17,7 @@ require('../../../chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "createOpenAiCompatibleRuntime", {
   enumerable: true,
-  get: function () { return chunkMEUBLCM4_cjs.createOpenAiCompatibleRuntime; }
+  get: function () { return chunkYEHQ3SIC_cjs.createOpenAiCompatibleRuntime; }
 });
 Object.defineProperty(exports, "LruEmbeddingCache", {
   enumerable: true,

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

@@ -1,4 +1,4 @@
-export { createOpenAiCompatibleRuntime } from '../../../chunk-HOHR75KF.js';
+export { createOpenAiCompatibleRuntime } from '../../../chunk-HI3W37FY.js';
 export { LruEmbeddingCache, globalEmbeddingCache } from '../../../chunk-H73MEMQB.js';
 import '../../../chunk-TE6XVTOA.js';
 import '../../../chunk-24MGQDK3.js';
@@ -7,6 +7,7 @@ import '../../../chunk-5DD4NJN3.js';
 import '../../../chunk-UKMBRMGT.js';
 import '../../../chunk-7JAKO3NM.js';
 import '../../../chunk-ZWFTECOE.js';
+import '../../../chunk-Q7GYMXVC.js';
 import '../../../chunk-B5MHRQJZ.js';
 import '../../../chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=index.js.map

package/dist/internal/memory/dreaming/phases.d.ts

@@ -6,6 +6,8 @@ export interface Cluster {
 }
 export interface ClusterResult {
     clusters: Cluster[];
+    /** How many input facts past the per-sweep cap were not clustered; 0 when none were. */
+    factsLeftOut: number;
 }
 /**
  * Light phase — drop facts whose embedding is too similar to one already kept.

package/dist/internal/memory/dreaming/run.d.ts

@@ -6,5 +6,10 @@ export interface DreamingResult {
     clustersCreated: number;
     notesWritten: number;
     diaryEntryHash: string | undefined;
+    /**
+     * Deduplicated facts past the per-sweep cap that were not clustered. Set on `"ok"`, 0 on
+     * `"skipped"`, and absent on `"error"`, where the sweep cannot say how many it left out.
+     */
+    factsLeftOut?: number;
 }
 export declare function runDreamingSweep(options: DreamingOptions): Promise<DreamingResult>;

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

@@ -44,6 +44,8 @@ export interface SdkMemoryModule {
         duplicatesRemoved: number;
         clustersCreated: number;
         notesWritten: number;
+        /** Optional: a peer older than the one that reports the count leaves it out. */
+        factsLeftOut?: number;
     }>;
     /** Mirrors @theokit/sdk-memory's IndexManager class (static open). */
     readonly IndexManager: {

package/dist/internal/memory/storage/fact-ceiling.d.cts

@@ -0,0 +1,19 @@
+import { ConfigurationError } from "../../../errors.js";
+/**
+ * The ceiling a caller declared, or `undefined` when none was declared.
+ *
+ * Validated before anything touches disk, because a ceiling that cannot be met (0, a negative or
+ * fractional number, a string, `null`) would otherwise surface later as a refusal of every write
+ * that names the wrong cause.
+ *
+ * @throws ConfigurationError with code `invalid_memory_ceiling` when the value is declared and is
+ *   not a positive safe integer.
+ */
+export declare function resolveMaxFacts(value: unknown): number | undefined;
+/**
+ * The refusal of a new fact at a store's declared ceiling: where the store is, how many facts it
+ * holds, the ceiling, and what to consolidate. `remedy` is the store-specific way to make room.
+ *
+ * Returned, not thrown, so each writer throws it at the point where it has written nothing.
+ */
+export declare function ceilingReachedError(where: string, count: number, maxFacts: number, remedy: string): ConfigurationError;

package/dist/internal/memory/storage/fact-ceiling.d.ts

@@ -0,0 +1,19 @@
+import { ConfigurationError } from "../../../errors.js";
+/**
+ * The ceiling a caller declared, or `undefined` when none was declared.
+ *
+ * Validated before anything touches disk, because a ceiling that cannot be met (0, a negative or
+ * fractional number, a string, `null`) would otherwise surface later as a refusal of every write
+ * that names the wrong cause.
+ *
+ * @throws ConfigurationError with code `invalid_memory_ceiling` when the value is declared and is
+ *   not a positive safe integer.
+ */
+export declare function resolveMaxFacts(value: unknown): number | undefined;
+/**
+ * The refusal of a new fact at a store's declared ceiling: where the store is, how many facts it
+ * holds, the ceiling, and what to consolidate. `remedy` is the store-specific way to make room.
+ *
+ * Returned, not thrown, so each writer throws it at the point where it has written nothing.
+ */
+export declare function ceilingReachedError(where: string, count: number, maxFacts: number, remedy: string): ConfigurationError;

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

@@ -1,15 +1,16 @@
 'use strict';
 
-var chunkT5KOSR5Y_cjs = require('../../../chunk-T5KOSR5Y.cjs');
+var chunkFYEHYQ7T_cjs = require('../../../chunk-FYEHYQ7T.cjs');
 var chunkTMKTSYDS_cjs = require('../../../chunk-TMKTSYDS.cjs');
-var chunk76PIKR4P_cjs = require('../../../chunk-76PIKR4P.cjs');
+var chunkZD66GFH5_cjs = require('../../../chunk-ZD66GFH5.cjs');
 require('../../../chunk-KRD3GQAA.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
 require('../../../chunk-SWALPLFQ.cjs');
 require('../../../chunk-GM54F4FE.cjs');
 require('../../../chunk-SA6K24NB.cjs');
-require('../../../chunk-GZV6AVRL.cjs');
+require('../../../chunk-ZWACQM5U.cjs');
 require('../../../chunk-P22BZE7G.cjs');
+require('../../../chunk-ASK2OQM5.cjs');
 require('../../../chunk-ZF2LDKQQ.cjs');
 require('../../../chunk-JLRLCBJ4.cjs');
 require('../../../chunk-UNFBHV46.cjs');
@@ -19,23 +20,23 @@ require('../../../chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "appendDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkT5KOSR5Y_cjs.appendDiaryEntry; }
+  get: function () { return chunkFYEHYQ7T_cjs.appendDiaryEntry; }
 });
 Object.defineProperty(exports, "diaryPath", {
   enumerable: true,
-  get: function () { return chunkT5KOSR5Y_cjs.diaryPath; }
+  get: function () { return chunkFYEHYQ7T_cjs.diaryPath; }
 });
 Object.defineProperty(exports, "entryHash", {
   enumerable: true,
-  get: function () { return chunkT5KOSR5Y_cjs.entryHash; }
+  get: function () { return chunkFYEHYQ7T_cjs.entryHash; }
 });
 Object.defineProperty(exports, "readAllSqliteFacts", {
   enumerable: true,
-  get: function () { return chunkT5KOSR5Y_cjs.readAllSqliteFacts; }
+  get: function () { return chunkFYEHYQ7T_cjs.readAllSqliteFacts; }
 });
 Object.defineProperty(exports, "renderDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkT5KOSR5Y_cjs.renderDiaryEntry; }
+  get: function () { return chunkFYEHYQ7T_cjs.renderDiaryEntry; }
 });
 Object.defineProperty(exports, "persistActiveMemoryTranscript", {
   enumerable: true,
@@ -43,99 +44,107 @@ Object.defineProperty(exports, "persistActiveMemoryTranscript", {
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.MEMORY_INDEX_MAX_BYTES; }
+  get: function () { return chunkZD66GFH5_cjs.MEMORY_INDEX_MAX_BYTES; }
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.MEMORY_INDEX_MAX_LINES; }
+  get: function () { return chunkZD66GFH5_cjs.MEMORY_INDEX_MAX_LINES; }
 });
 Object.defineProperty(exports, "appendFact", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.appendFact; }
+  get: function () { return chunkZD66GFH5_cjs.appendFact; }
 });
 Object.defineProperty(exports, "appendFactToMarkdown", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.appendFactToMarkdown; }
+  get: function () { return chunkZD66GFH5_cjs.appendFactToMarkdown; }
 });
 Object.defineProperty(exports, "asMemoryRoot", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.asMemoryRoot; }
+  get: function () { return chunkZD66GFH5_cjs.asMemoryRoot; }
+});
+Object.defineProperty(exports, "ceilingReachedError", {
+  enumerable: true,
+  get: function () { return chunkZD66GFH5_cjs.ceilingReachedError; }
 });
 Object.defineProperty(exports, "claudeProjectMemoryDir", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.claudeProjectMemoryDir; }
+  get: function () { return chunkZD66GFH5_cjs.claudeProjectMemoryDir; }
 });
 Object.defineProperty(exports, "collectMarkdownFiles", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.collectMarkdownFiles; }
+  get: function () { return chunkZD66GFH5_cjs.collectMarkdownFiles; }
 });
 Object.defineProperty(exports, "defaultIndexPath", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.defaultIndexPath; }
+  get: function () { return chunkZD66GFH5_cjs.defaultIndexPath; }
 });
 Object.defineProperty(exports, "discoverSessionFiles", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.discoverSessionFiles; }
+  get: function () { return chunkZD66GFH5_cjs.discoverSessionFiles; }
 });
 Object.defineProperty(exports, "discoverWikiFiles", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.discoverWikiFiles; }
+  get: function () { return chunkZD66GFH5_cjs.discoverWikiFiles; }
 });
 Object.defineProperty(exports, "indexBudgetWarning", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.indexBudgetWarning; }
+  get: function () { return chunkZD66GFH5_cjs.indexBudgetWarning; }
 });
 Object.defineProperty(exports, "lanceStoragePath", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.lanceStoragePath; }
+  get: function () { return chunkZD66GFH5_cjs.lanceStoragePath; }
 });
 Object.defineProperty(exports, "memoryIndexRoot", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.memoryIndexRoot; }
+  get: function () { return chunkZD66GFH5_cjs.memoryIndexRoot; }
 });
 Object.defineProperty(exports, "memoryMdPath", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.memoryMdPath; }
+  get: function () { return chunkZD66GFH5_cjs.memoryMdPath; }
 });
 Object.defineProperty(exports, "memoryReadRoots", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.memoryReadRoots; }
+  get: function () { return chunkZD66GFH5_cjs.memoryReadRoots; }
 });
 Object.defineProperty(exports, "notesDir", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.notesDir; }
+  get: function () { return chunkZD66GFH5_cjs.notesDir; }
 });
 Object.defineProperty(exports, "projectMemoryDir", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.projectMemoryDir; }
+  get: function () { return chunkZD66GFH5_cjs.projectMemoryDir; }
 });
 Object.defineProperty(exports, "readFacts", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.readFacts; }
+  get: function () { return chunkZD66GFH5_cjs.readFacts; }
 });
 Object.defineProperty(exports, "readFactsFromMarkdown", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.readFactsFromMarkdown; }
+  get: function () { return chunkZD66GFH5_cjs.readFactsFromMarkdown; }
+});
+Object.defineProperty(exports, "resolveMaxFacts", {
+  enumerable: true,
+  get: function () { return chunkZD66GFH5_cjs.resolveMaxFacts; }
 });
 Object.defineProperty(exports, "resolveMemoryRoot", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.resolveMemoryRoot; }
+  get: function () { return chunkZD66GFH5_cjs.resolveMemoryRoot; }
 });
 Object.defineProperty(exports, "sessionSummaryPath", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.sessionSummaryPath; }
+  get: function () { return chunkZD66GFH5_cjs.sessionSummaryPath; }
 });
 Object.defineProperty(exports, "sessionsDir", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.sessionsDir; }
+  get: function () { return chunkZD66GFH5_cjs.sessionsDir; }
 });
 Object.defineProperty(exports, "wikiDir", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.wikiDir; }
+  get: function () { return chunkZD66GFH5_cjs.wikiDir; }
 });
 Object.defineProperty(exports, "writeSessionSummary", {
   enumerable: true,
-  get: function () { return chunk76PIKR4P_cjs.writeSessionSummary; }
+  get: function () { return chunkZD66GFH5_cjs.writeSessionSummary; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/memory/storage/index.d.cts

@@ -20,6 +20,7 @@ export { defaultIndexPath } from "../index-db.js";
 export { collectMarkdownFiles, type DiscoveredFile } from "../index-manager-helpers.js";
 export { lanceStoragePath } from "../lance-index.js";
 export { readAllSqliteFacts, type SqliteFactRow } from "../migrate-sqlite-to-lance.js";
+export { ceilingReachedError, resolveMaxFacts } from "./fact-ceiling.js";
 export { appendFact, appendFactToMarkdown, memoryMdPath, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
 export { asMemoryRoot, claudeProjectMemoryDir, indexBudgetWarning, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, type MemoryLocationConfig, type MemoryRoot, memoryIndexRoot, memoryReadRoots, projectMemoryDir, resolveMemoryRoot, } from "./memory-root.js";
 export { discoverSessionFiles, type SessionFile } from "./session-loader.js";

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

@@ -20,6 +20,7 @@ export { defaultIndexPath } from "../index-db.js";
 export { collectMarkdownFiles, type DiscoveredFile } from "../index-manager-helpers.js";
 export { lanceStoragePath } from "../lance-index.js";
 export { readAllSqliteFacts, type SqliteFactRow } from "../migrate-sqlite-to-lance.js";
+export { ceilingReachedError, resolveMaxFacts } from "./fact-ceiling.js";
 export { appendFact, appendFactToMarkdown, memoryMdPath, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
 export { asMemoryRoot, claudeProjectMemoryDir, indexBudgetWarning, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, type MemoryLocationConfig, type MemoryRoot, memoryIndexRoot, memoryReadRoots, projectMemoryDir, resolveMemoryRoot, } from "./memory-root.js";
 export { discoverSessionFiles, type SessionFile } from "./session-loader.js";

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

@@ -1,13 +1,14 @@
-export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-QDQQYRJI.js';
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-W2ZVTEOD.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, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-TC4RWP3Y.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, ceilingReachedError, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMaxFacts, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-X3LOJJMO.js';
 import '../../../chunk-KVNWIAO4.js';
 import '../../../chunk-FD2UT76F.js';
 import '../../../chunk-4QCJAJAG.js';
 import '../../../chunk-5DD4NJN3.js';
 import '../../../chunk-UKMBRMGT.js';
-import '../../../chunk-JOFVLOFY.js';
+import '../../../chunk-FTZTZBCU.js';
 import '../../../chunk-XZHJYSPB.js';
+import '../../../chunk-RGQICWFU.js';
 import '../../../chunk-Q5EWJPRY.js';
 import '../../../chunk-3JHIFQ4I.js';
 import '../../../chunk-B5MHRQJZ.js';

package/dist/internal/memory/storage/markdown-store.d.cts

@@ -29,7 +29,9 @@ export declare function readFactsFromMarkdown(cwd: string, config?: MemoryLocati
  * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
  * timestamp that can lie about when something was learned, and weighing recency is the point.
  */
-export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string, options?: {
+    maxFacts?: number;
+}): Promise<void>;
 /**
  * Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig}: when memory is
  * disabled the call resolves to `[]` without touching disk. Configuration-aware entry point;

package/dist/internal/memory/storage/markdown-store.d.ts

@@ -29,7 +29,9 @@ export declare function readFactsFromMarkdown(cwd: string, config?: MemoryLocati
  * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
  * timestamp that can lie about when something was learned, and weighing recency is the point.
  */
-export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string, options?: {
+    maxFacts?: number;
+}): Promise<void>;
 /**
  * Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig}: when memory is
  * disabled the call resolves to `[]` without touching disk. Configuration-aware entry point;

package/dist/internal/memory/types.d.ts

@@ -9,6 +9,12 @@ export interface MemoryConfig {
      * See `storage/memory-root.ts` for why a relative value is refused rather than resolved.
      */
     directory?: string;
+    /**
+     * The most facts the write directory may hold. A new fact at the ceiling is refused with
+     * `memory_ceiling_reached`; a second observation of a stored fact is still admitted. Absent means
+     * no ceiling. The public contract is `MemorySettings.maxFacts` in `types/agent.ts`.
+     */
+    maxFacts?: number;
 }
 /**
  * What a fact IS, which is what decides whether it ages (#389).

package/dist/internal/persistence/index.cjs

@@ -4,7 +4,8 @@ var chunkVTYY7XL5_cjs = require('../../chunk-VTYY7XL5.cjs');
 var chunkRQMCOFAI_cjs = require('../../chunk-RQMCOFAI.cjs');
 var chunkA4RAL2ER_cjs = require('../../chunk-A4RAL2ER.cjs');
 var chunkP22BZE7G_cjs = require('../../chunk-P22BZE7G.cjs');
-var chunkOF2CLCTH_cjs = require('../../chunk-OF2CLCTH.cjs');
+var chunkR5YPDAKD_cjs = require('../../chunk-R5YPDAKD.cjs');
+var chunkASK2OQM5_cjs = require('../../chunk-ASK2OQM5.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkJLRLCBJ4_cjs = require('../../chunk-JLRLCBJ4.cjs');
 var chunkTY56BKSK_cjs = require('../../chunk-TY56BKSK.cjs');
@@ -75,23 +76,23 @@ Object.defineProperty(exports, "openSqliteResilient", {
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.JsonlParseError; }
+  get: function () { return chunkR5YPDAKD_cjs.JsonlParseError; }
 });
 Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.appendJsonl; }
+  get: function () { return chunkR5YPDAKD_cjs.appendJsonl; }
 });
 Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.loadJsonl; }
+  get: function () { return chunkR5YPDAKD_cjs.loadJsonl; }
 });
 Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.readJsonlIds; }
+  get: function () { return chunkR5YPDAKD_cjs.readJsonlIds; }
 });
 Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.withFileLock; }
+  get: function () { return chunkASK2OQM5_cjs.withFileLock; }
 });
 Object.defineProperty(exports, "withCwdMutex", {
   enumerable: true,

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

@@ -2,7 +2,8 @@ export { PersistenceSchema } from '../../chunk-HY66GLM6.js';
 export { migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-SVQIW5RJ.js';
 export { containsCjk, sanitizeFts5Query } from '../../chunk-WE22OXQA.js';
 export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from '../../chunk-XZHJYSPB.js';
-export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-BKMDRBJ7.js';
+export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds } from '../../chunk-7KIN3L2S.js';
+export { withFileLock } from '../../chunk-RGQICWFU.js';
 export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-3JHIFQ4I.js';
 export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-X7EUUHXU.js';

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

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

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

@@ -22,8 +22,8 @@ import { z } from "zod";
  */
 export declare const PersistenceSchema: z.ZodOptional<z.ZodObject<{
     backend: z.ZodEnum<{
-        memory: "memory";
         json: "json";
+        memory: "memory";
     }>;
     dir: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;

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

@@ -22,8 +22,8 @@ import { z } from "zod";
  */
 export declare const PersistenceSchema: z.ZodOptional<z.ZodObject<{
     backend: z.ZodEnum<{
-        memory: "memory";
         json: "json";
+        memory: "memory";
     }>;
     dir: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;