@theokit/sdk 4.53.0 → 4.54.0

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

@@ -1,29 +1,30 @@
 'use strict';
 
-var chunkADVZIC43_cjs = require('../../../chunk-ADVZIC43.cjs');
-require('../../../chunk-E3OCRJU6.cjs');
-var chunk2RW7K6FN_cjs = require('../../../chunk-2RW7K6FN.cjs');
+var chunkEI2Q7SJ5_cjs = require('../../../chunk-EI2Q7SJ5.cjs');
+var chunkGHX4P3V2_cjs = require('../../../chunk-GHX4P3V2.cjs');
+require('../../../chunk-DQKERTND.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
-require('../../../chunk-KNZU4YO5.cjs');
-require('../../../chunk-NFATC6ZF.cjs');
-require('../../../chunk-YTO5BRBD.cjs');
+require('../../../chunk-R3UPQFKK.cjs');
 require('../../../chunk-VKJ7V7EB.cjs');
-require('../../../chunk-2YGIBOUH.cjs');
-require('../../../chunk-SXSPMRSV.cjs');
+require('../../../chunk-ILCGLTSA.cjs');
+require('../../../chunk-CQGYNZ3K.cjs');
+require('../../../chunk-K3FW2XZD.cjs');
+require('../../../chunk-JTB5Q42C.cjs');
+require('../../../chunk-NUKRL3I6.cjs');
 
 
 
 Object.defineProperty(exports, "createOpenAiCompatibleRuntime", {
   enumerable: true,
-  get: function () { return chunkADVZIC43_cjs.createOpenAiCompatibleRuntime; }
+  get: function () { return chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime; }
 });
 Object.defineProperty(exports, "LruEmbeddingCache", {
   enumerable: true,
-  get: function () { return chunk2RW7K6FN_cjs.LruEmbeddingCache; }
+  get: function () { return chunkGHX4P3V2_cjs.LruEmbeddingCache; }
 });
 Object.defineProperty(exports, "globalEmbeddingCache", {
   enumerable: true,
-  get: function () { return chunk2RW7K6FN_cjs.globalEmbeddingCache; }
+  get: function () { return chunkGHX4P3V2_cjs.globalEmbeddingCache; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

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

@@ -11,6 +11,8 @@
  * `internal/persistence` and `internal/security` sub-paths that exist for the same reason: extracted
  * packages need primitives that are not part of the stable public contract.
  *
- * @internal — semver-exempt. Not part of the stable `@theokit/sdk` API.
+ * Semver-exempt: NOT part of the stable `@theokit/sdk` API. The sub-path IS declared in
+ * `package.json` `exports`, so the names below must survive into the published declarations.
  */
+export { globalEmbeddingCache, LruEmbeddingCache } from "../embedding-cache.js";
 export { createOpenAiCompatibleRuntime, type EmbeddingDialect, type OpenAiCompatibleConfig, } from "./openai-compatible.js";

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

@@ -11,6 +11,8 @@
  * `internal/persistence` and `internal/security` sub-paths that exist for the same reason: extracted
  * packages need primitives that are not part of the stable public contract.
  *
- * @internal — semver-exempt. Not part of the stable `@theokit/sdk` API.
+ * Semver-exempt: NOT part of the stable `@theokit/sdk` API. The sub-path IS declared in
+ * `package.json` `exports`, so the names below must survive into the published declarations.
  */
+export { globalEmbeddingCache, LruEmbeddingCache } from "../embedding-cache.js";
 export { createOpenAiCompatibleRuntime, type EmbeddingDialect, type OpenAiCompatibleConfig, } from "./openai-compatible.js";

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

@@ -1,12 +1,13 @@
-export { createOpenAiCompatibleRuntime } from '../../../chunk-EFXJ5C7X.js';
-import '../../../chunk-OZXPA3ME.js';
-export { LruEmbeddingCache, globalEmbeddingCache } from '../../../chunk-OXNYIMZZ.js';
+export { createOpenAiCompatibleRuntime } from '../../../chunk-XN7NOENA.js';
+export { LruEmbeddingCache, globalEmbeddingCache } from '../../../chunk-H73MEMQB.js';
+import '../../../chunk-5JLFFPCH.js';
 import '../../../chunk-FD2UT76F.js';
-import '../../../chunk-ITQ4NO4P.js';
-import '../../../chunk-ZSJPRPN7.js';
-import '../../../chunk-XWCTBGYK.js';
+import '../../../chunk-QARJGQSA.js';
 import '../../../chunk-RIAM53CP.js';
-import '../../../chunk-HI4ZW62S.js';
-import '../../../chunk-4X3SBHPK.js';
+import '../../../chunk-UC3HT2S4.js';
+import '../../../chunk-OC4NTGMN.js';
+import '../../../chunk-IDCKSLYH.js';
+import '../../../chunk-T7XEKOVW.js';
+import '../../../chunk-T7O6K6PX.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/internal/memory/adapters/openai-compatible.d.cts

@@ -1,4 +1,18 @@
 import type { CreateAdapterOptions, EmbeddingRuntime } from "../embedding-adapter.js";
+/**
+ * What one provider adapter tells {@link createOpenAiCompatibleRuntime} about
+ * its wire: where to POST, which environment variables carry the key and the
+ * base URL, which model to use by default, and how wide each model's vectors
+ * are.
+ *
+ * `id` is the provider id that ends up on errors and on
+ * `EmbeddingRuntime.id`, and is also the identity the SQLite vector index stores
+ * — changing it invalidates the vectors already on disk.
+ *
+ * `apiKeyEnv` is required, `baseUrlEnv` is not: a provider that declares no
+ * base-URL variable can only be redirected by passing `baseUrl` explicitly.
+ * Leave `dialect` unset for anything that speaks the OpenAI embedding wire.
+ */
 export interface OpenAiCompatibleConfig {
     id: string;
     defaultBaseUrl: string;
@@ -48,4 +62,35 @@ export interface EmbeddingDialect {
     /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */
     vectors?: (json: unknown) => number[][] | undefined;
 }
+/**
+ * Build an {@link EmbeddingRuntime} for a provider that speaks the OpenAI
+ * embedding wire — or, through `cfg.dialect`, one that deviates from it in a
+ * known way. Every adapter in the memory catalog is a thin call to this.
+ *
+ * Resolution order for each setting is explicit option, then environment
+ * variable, then the config default. Two things are checked before any request
+ * is sent, so a misconfiguration fails at creation rather than at first search:
+ * a missing or empty key rejects with an `AuthenticationError` carrying
+ * `embedding_missing_api_key`, and a model absent from `dimensionByModel`
+ * rejects with a `ConfigurationError` carrying `embedding_unknown_model`. The
+ * second check exists because the vector index is created at a fixed width — an
+ * unknown dimension would surface much later as a vec0 mismatch.
+ *
+ * `{model}` in `embeddingsPath` is replaced with the URL-encoded model, which is
+ * how Azure addresses a deployment in the path. `embeddingsPath` replaces the
+ * default `/v1/embeddings` rather than being appended to it.
+ *
+ * The returned `embed` batches at 100 texts per request and runs at most 3
+ * requests concurrently, preserving input order. Whitespace-only inputs never
+ * reach the network and come back as an all-zero vector. Results are cached by
+ * model and text; the cache defaults to a process-wide LRU of 5000 entries, so
+ * pass `options.cache` when runtimes must not share entries.
+ *
+ * Failed requests retry up to twice on 429 and 5xx with a 50ms-per-attempt
+ * linear backoff. Anything else, and a retry budget that runs out, throws the
+ * typed error the OpenAI-compatible mapper builds from the status and body. A
+ * response that parses but carries no vectors throws a `NetworkError` with
+ * `embedding_invalid_response`. There is no request timeout here — cancellation
+ * is the caller's to impose.
+ */
 export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

package/dist/internal/memory/adapters/openai-compatible.d.ts

@@ -1,4 +1,18 @@
 import type { CreateAdapterOptions, EmbeddingRuntime } from "../embedding-adapter.js";
+/**
+ * What one provider adapter tells {@link createOpenAiCompatibleRuntime} about
+ * its wire: where to POST, which environment variables carry the key and the
+ * base URL, which model to use by default, and how wide each model's vectors
+ * are.
+ *
+ * `id` is the provider id that ends up on errors and on
+ * `EmbeddingRuntime.id`, and is also the identity the SQLite vector index stores
+ * — changing it invalidates the vectors already on disk.
+ *
+ * `apiKeyEnv` is required, `baseUrlEnv` is not: a provider that declares no
+ * base-URL variable can only be redirected by passing `baseUrl` explicitly.
+ * Leave `dialect` unset for anything that speaks the OpenAI embedding wire.
+ */
 export interface OpenAiCompatibleConfig {
     id: string;
     defaultBaseUrl: string;
@@ -48,4 +62,35 @@ export interface EmbeddingDialect {
     /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */
     vectors?: (json: unknown) => number[][] | undefined;
 }
+/**
+ * Build an {@link EmbeddingRuntime} for a provider that speaks the OpenAI
+ * embedding wire — or, through `cfg.dialect`, one that deviates from it in a
+ * known way. Every adapter in the memory catalog is a thin call to this.
+ *
+ * Resolution order for each setting is explicit option, then environment
+ * variable, then the config default. Two things are checked before any request
+ * is sent, so a misconfiguration fails at creation rather than at first search:
+ * a missing or empty key rejects with an `AuthenticationError` carrying
+ * `embedding_missing_api_key`, and a model absent from `dimensionByModel`
+ * rejects with a `ConfigurationError` carrying `embedding_unknown_model`. The
+ * second check exists because the vector index is created at a fixed width — an
+ * unknown dimension would surface much later as a vec0 mismatch.
+ *
+ * `{model}` in `embeddingsPath` is replaced with the URL-encoded model, which is
+ * how Azure addresses a deployment in the path. `embeddingsPath` replaces the
+ * default `/v1/embeddings` rather than being appended to it.
+ *
+ * The returned `embed` batches at 100 texts per request and runs at most 3
+ * requests concurrently, preserving input order. Whitespace-only inputs never
+ * reach the network and come back as an all-zero vector. Results are cached by
+ * model and text; the cache defaults to a process-wide LRU of 5000 entries, so
+ * pass `options.cache` when runtimes must not share entries.
+ *
+ * Failed requests retry up to twice on 429 and 5xx with a 50ms-per-attempt
+ * linear backoff. Anything else, and a retry budget that runs out, throws the
+ * typed error the OpenAI-compatible mapper builds from the status and body. A
+ * response that parses but carries no vectors throws a `NetworkError` with
+ * `embedding_invalid_response`. There is no request timeout here — cancellation
+ * is the caller's to impose.
+ */
 export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

package/dist/internal/memory/embedding-cache.d.ts

@@ -1 +1,42 @@
-export {};
+import type { EmbeddingCache } from "./embedding-adapter.js";
+/**
+ * Bounded in-memory LRU cache for embeddings, keyed by `sha256(text)` (or any
+ * stable key the caller chooses).
+ *
+ * Recency is tracked by Map insertion order: `get` re-inserts the hit so it becomes the newest,
+ * and `set` evicts the oldest key once `capacity` (default 5000) is reached. Nothing here bounds
+ * the size of a single VALUE, so capacity is a count of vectors, not a memory budget.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/memory-adapters` sub-path, which the
+ * package declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare class LruEmbeddingCache implements EmbeddingCache {
+    private readonly capacity;
+    private readonly map;
+    constructor(capacity?: number);
+    get(key: string): number[] | undefined;
+    set(key: string, value: number[]): void;
+    size(): number;
+}
+/**
+ * T4.4 — Process-wide singleton embedding cache (DR4 finding #4).
+ *
+ * Pre-T4.4 each adapter / index-manager constructed its own
+ * `LruEmbeddingCache` — a consumer with 3 Memory.openIndex calls
+ * got 3 independent caches with no cross-index deduplication. The
+ * same text embedded identically across indexes re-computed the
+ * embedding each time.
+ *
+ * The singleton shares the cache process-wide so hit rate goes up
+ * dramatically. The LRU eviction (default 5000 entries) bounds
+ * memory usage even with the shared surface.
+ *
+ * Consumers who need isolation (e.g., multi-tenant with different
+ * embedding models) should construct their own `LruEmbeddingCache`
+ * and pass it explicitly — the singleton is the DEFAULT, not the
+ * only option.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/memory-adapters` sub-path, which the
+ * package declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare const globalEmbeddingCache: EmbeddingCache;

package/dist/internal/memory/escape-like-pattern.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Escapes a user query for a SQL `LIKE ... ESCAPE '\'` clause.
+ *
+ * The order of the three replacements is the whole correctness argument, so it is its own
+ * function rather than a chain inline at the call site.
+ *
+ * The previous version escaped `%` and `_` but not the escape character itself, which is the
+ * defect CodeQL reports as `js/incomplete-sanitization` (alerts #14, #15). Two things went wrong,
+ * and the second is the one that matters:
+ *
+ *   "back\slash"  ->  "%back\slash%"    the `\s` is an escape of `s`, which LIKE does not define
+ *   "x\%y"        ->  "%x\\%y%"         the inserted `\` is consumed escaping the user's `\`,
+ *                                       leaving `%` UNESCAPED — a wildcard the caller did not
+ *                                       write, matching anything between `x\` and `y`
+ *
+ * The second is wildcard injection: a search for a literal string silently becomes a scan. In a
+ * memory index that is both a wrong answer and a way to pull back rows the query never asked for.
+ *
+ * Escaping the backslash FIRST is what fixes it — afterwards every `\` in the string is one this
+ * function put there, so the later replacements cannot collide with a user-supplied one.
+ */
+export declare function escapeLikePattern(query: string): string;

package/dist/internal/memory/sqlite-vec-loader.d.ts

@@ -1,3 +1 @@
-import type { MemoryDb } from "./index-db.js";
-/** Check whether sqlite-vec is loaded by running a tiny version query. */
-export declare function isSqliteVecLoaded(db: MemoryDb): boolean;
+export {};

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

@@ -6,11 +6,6 @@ export declare function notesDir(cwd: string): string;
 export declare function readFactsFromMarkdown(cwd: string): Promise<MemoryFact[]>;
 /** Append a fact to `MEMORY.md ## Facts`. Creates the section if missing. Atomic + serialized. */
 export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact): Promise<void>;
-export interface NoteFile {
-    slug: string;
-    path: string;
-}
-export declare function listNotes(cwd: string): Promise<NoteFile[]>;
 /** Configuration-aware accessors honoring the existing MemoryConfig contract. */
 export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
 export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;

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

@@ -1,3 +1,27 @@
+/**
+ * M107 — temp-file creation control, shared by `replaceFileAtomic`,
+ * `atomicWriteJson` e `atomicWriteText`.
+ *
+ * Both fields are OPTIONAL and the default is byte-identical to the behavior
+ * before M107. See `replaceFileAtomic` for why the mode reassertion
+ * is conditional.
+ *
+ */
+export interface AtomicWriteFileOptions {
+    /**
+     * Permission bits of the created file. Default: `0o600`, the previous fixed
+     * literal — filtered by the `umask`, as it always was. When provided, the mode is
+     * reasserted on the descriptor, so the `umask` cannot silently
+     * clearing bits the caller asked for.
+     */
+    mode?: number;
+    /**
+     * Create the temp file with `wx` (exclusive creation) instead of `w`. Default:
+     * `false` — the previous flag. With `true`, a pre-existing temp file becomes
+     * `EEXIST` instead of being truncated.
+     */
+    exclusive?: boolean;
+}
 /**
  * U-9 — the file a leftover temp was replacing, or `undefined` if this is not one of ours.
  *
@@ -12,3 +36,72 @@
  * deleting them.
  */
 export declare function atomicWriteTempTarget(name: string): string | undefined;
+/**
+ * Atomic file replacement: write content to a per-call unique tmp path,
+ * fsync, then rename over the target. Crash mid-write leaves either the old
+ * file intact or the new file complete — never a half-written file.
+ *
+ * The tmp suffix is `<pid>.<rand>.tmp` so parallel processes (and concurrent
+ * burst writes within one process) never collide on the same tmp path — a
+ * race that would manifest as `ENOENT` on `rename` after the rival process
+ * already moved its tmp into place.
+ *
+ * Mirrors peer-project's `replaceFileAtomic` from
+ * `reference/peer-project/packages/memory-host-sdk/src/host/fs-utils.ts` with
+ * the multi-writer robustness fix.
+ *
+ * ## M107 — `options` is optional, and the default is byte-identical
+ *
+ * The third parameter is additive: every earlier caller still compiles and
+ * writing exactly the same bytes, with the same mode, to the same path.
+ *
+ * The mode reassertion (`handle.chmod`) is **conditional on `mode !== undefined`**,
+ * and that is not cosmetic. `open`'s mode argument is filtered by the `umask`,
+ * which only CLEARS bits — measured in this codebase before the change:
+ *
+ * ```
+ * umask 0o002  ->  0o600      umask 0o022  ->  0o600      umask 0o200  ->  0o400
+ * ```
+ *
+ * An unconditional `chmod` would take the third case from `0o400` to `0o600` — a
+ * an on-disk change for every caller that asked for nothing, including external
+ * consumers. When the caller DOES ask for a mode, however, letting the `umask` decide
+ * silently is the defect this parameter exists to close; hence the reassertion.
+ *
+ * It goes on the DESCRIPTOR, before the `rename`, never after: chmod-ing the final
+ * final one would leave a window where it carries the `umask`'s mode — a known anti-pattern.
+ * The chosen shape passes the mode as an `open` argument.
+ *
+ */
+export declare function replaceFileAtomic(filePath: string, content: string, options?: AtomicWriteFileOptions): Promise<void>;
+/**
+ * Options for `atomicWriteJson`.
+ *
+ */
+export interface AtomicWriteJsonOptions extends AtomicWriteFileOptions {
+    /** Indent passed to `JSON.stringify`. Default: 2. */
+    indent?: number;
+    /** Whether to append a trailing newline (POSIX convention). Default: true. */
+    trailingNewline?: boolean;
+}
+/**
+ * Typed JSON atomic write helper.
+ *
+ * Serializes `data` to JSON, then delegates to `replaceFileAtomic`. The
+ * parent directory is auto-created (recursive `mkdir`) to make this helper
+ * safe for callers who haven't ensured the directory exists (EC-4 in the
+ * persistence-state-hardening plan).
+ *
+ * Throws `TypeError` on circular refs or `undefined` data (propagates from
+ * `JSON.stringify`).
+ *
+ */
+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.
+ *
+ */
+export declare function atomicWriteText(filePath: string, content: string): Promise<void>;

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

@@ -1,3 +1,27 @@
+/**
+ * M107 — temp-file creation control, shared by `replaceFileAtomic`,
+ * `atomicWriteJson` e `atomicWriteText`.
+ *
+ * Both fields are OPTIONAL and the default is byte-identical to the behavior
+ * before M107. See `replaceFileAtomic` for why the mode reassertion
+ * is conditional.
+ *
+ */
+export interface AtomicWriteFileOptions {
+    /**
+     * Permission bits of the created file. Default: `0o600`, the previous fixed
+     * literal — filtered by the `umask`, as it always was. When provided, the mode is
+     * reasserted on the descriptor, so the `umask` cannot silently
+     * clearing bits the caller asked for.
+     */
+    mode?: number;
+    /**
+     * Create the temp file with `wx` (exclusive creation) instead of `w`. Default:
+     * `false` — the previous flag. With `true`, a pre-existing temp file becomes
+     * `EEXIST` instead of being truncated.
+     */
+    exclusive?: boolean;
+}
 /**
  * U-9 — the file a leftover temp was replacing, or `undefined` if this is not one of ours.
  *
@@ -12,3 +36,72 @@
  * deleting them.
  */
 export declare function atomicWriteTempTarget(name: string): string | undefined;
+/**
+ * Atomic file replacement: write content to a per-call unique tmp path,
+ * fsync, then rename over the target. Crash mid-write leaves either the old
+ * file intact or the new file complete — never a half-written file.
+ *
+ * The tmp suffix is `<pid>.<rand>.tmp` so parallel processes (and concurrent
+ * burst writes within one process) never collide on the same tmp path — a
+ * race that would manifest as `ENOENT` on `rename` after the rival process
+ * already moved its tmp into place.
+ *
+ * Mirrors peer-project's `replaceFileAtomic` from
+ * `reference/peer-project/packages/memory-host-sdk/src/host/fs-utils.ts` with
+ * the multi-writer robustness fix.
+ *
+ * ## M107 — `options` is optional, and the default is byte-identical
+ *
+ * The third parameter is additive: every earlier caller still compiles and
+ * writing exactly the same bytes, with the same mode, to the same path.
+ *
+ * The mode reassertion (`handle.chmod`) is **conditional on `mode !== undefined`**,
+ * and that is not cosmetic. `open`'s mode argument is filtered by the `umask`,
+ * which only CLEARS bits — measured in this codebase before the change:
+ *
+ * ```
+ * umask 0o002  ->  0o600      umask 0o022  ->  0o600      umask 0o200  ->  0o400
+ * ```
+ *
+ * An unconditional `chmod` would take the third case from `0o400` to `0o600` — a
+ * an on-disk change for every caller that asked for nothing, including external
+ * consumers. When the caller DOES ask for a mode, however, letting the `umask` decide
+ * silently is the defect this parameter exists to close; hence the reassertion.
+ *
+ * It goes on the DESCRIPTOR, before the `rename`, never after: chmod-ing the final
+ * final one would leave a window where it carries the `umask`'s mode — a known anti-pattern.
+ * The chosen shape passes the mode as an `open` argument.
+ *
+ */
+export declare function replaceFileAtomic(filePath: string, content: string, options?: AtomicWriteFileOptions): Promise<void>;
+/**
+ * Options for `atomicWriteJson`.
+ *
+ */
+export interface AtomicWriteJsonOptions extends AtomicWriteFileOptions {
+    /** Indent passed to `JSON.stringify`. Default: 2. */
+    indent?: number;
+    /** Whether to append a trailing newline (POSIX convention). Default: true. */
+    trailingNewline?: boolean;
+}
+/**
+ * Typed JSON atomic write helper.
+ *
+ * Serializes `data` to JSON, then delegates to `replaceFileAtomic`. The
+ * parent directory is auto-created (recursive `mkdir`) to make this helper
+ * safe for callers who haven't ensured the directory exists (EC-4 in the
+ * persistence-state-hardening plan).
+ *
+ * Throws `TypeError` on circular refs or `undefined` data (propagates from
+ * `JSON.stringify`).
+ *
+ */
+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.
+ *
+ */
+export declare function atomicWriteText(filePath: string, content: string): Promise<void>;

package/dist/internal/persistence/cwd-mutex.d.cts

@@ -1 +1,35 @@
+/**
+ * Run `fn` after every earlier `withCwdMutex` call for the same `key` has settled, and return
+ * what `fn` returns.
+ *
+ * Calls with the same key run strictly in the order they were made — FIFO, never concurrent.
+ * Calls with different keys never wait on each other. The key is an opaque string: two callers
+ * serialize against each other exactly when they pass equal keys, so a shared key IS the
+ * contract, and a mismatched one silently buys no protection at all.
+ *
+ * A rejection does not poison the queue. The next waiter runs whether the previous `fn` fulfilled
+ * or rejected, and the rejection is delivered only to the caller whose `fn` threw. This function
+ * neither retries nor swallows: the returned promise rejects with whatever `fn` rejected with.
+ *
+ * There is no timeout and no cancellation. An `fn` that never settles blocks that key for the
+ * lifetime of the process.
+ *
+ * **Scope — this is an in-process lock only.** State is a module-scoped Map, so it serializes
+ * callers that share one module instance and nothing else. Two processes, two worker threads, or
+ * two copies of the SDK resolved into the same tree do not see each other's queue. When the
+ * resource is a file that other processes can also write, use `withFileLock` from
+ * `./file-lock.ts` instead — it takes an OS-level lock and layers this mutex underneath, so it
+ * gives both guarantees. Reach for `withCwdMutex` directly when the shared state is in memory, or
+ * when the file is one only this process touches.
+ *
+ * Extracted packages (`@theokit/sdk-budget`, `@theokit/sdk-memory`) import this from
+ * `@theokit/sdk` rather than reimplementing it, precisely so the Map is the same one: a per-package
+ * copy would give each package its own queue and let their writes race.
+ *
+ * The Map is module-scoped, so nothing survives a process restart or a fresh module instance, and
+ * its entries are never removed — pass keys from a bounded set rather than from arbitrary input.
+ * Signature and semantics will not change before sdk-core v3.0.
+ *
+ * @public
+ */
 export declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;

package/dist/internal/persistence/cwd-mutex.d.ts

@@ -1 +1,35 @@
+/**
+ * Run `fn` after every earlier `withCwdMutex` call for the same `key` has settled, and return
+ * what `fn` returns.
+ *
+ * Calls with the same key run strictly in the order they were made — FIFO, never concurrent.
+ * Calls with different keys never wait on each other. The key is an opaque string: two callers
+ * serialize against each other exactly when they pass equal keys, so a shared key IS the
+ * contract, and a mismatched one silently buys no protection at all.
+ *
+ * A rejection does not poison the queue. The next waiter runs whether the previous `fn` fulfilled
+ * or rejected, and the rejection is delivered only to the caller whose `fn` threw. This function
+ * neither retries nor swallows: the returned promise rejects with whatever `fn` rejected with.
+ *
+ * There is no timeout and no cancellation. An `fn` that never settles blocks that key for the
+ * lifetime of the process.
+ *
+ * **Scope — this is an in-process lock only.** State is a module-scoped Map, so it serializes
+ * callers that share one module instance and nothing else. Two processes, two worker threads, or
+ * two copies of the SDK resolved into the same tree do not see each other's queue. When the
+ * resource is a file that other processes can also write, use `withFileLock` from
+ * `./file-lock.ts` instead — it takes an OS-level lock and layers this mutex underneath, so it
+ * gives both guarantees. Reach for `withCwdMutex` directly when the shared state is in memory, or
+ * when the file is one only this process touches.
+ *
+ * Extracted packages (`@theokit/sdk-budget`, `@theokit/sdk-memory`) import this from
+ * `@theokit/sdk` rather than reimplementing it, precisely so the Map is the same one: a per-package
+ * copy would give each package its own queue and let their writes race.
+ *
+ * The Map is module-scoped, so nothing survives a process restart or a fresh module instance, and
+ * its entries are never removed — pass keys from a bounded set rather than from arbitrary input.
+ * Signature and semantics will not change before sdk-core v3.0.
+ *
+ * @public
+ */
 export declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;

package/dist/internal/persistence/exclusive-create.d.cts

@@ -20,3 +20,34 @@ export interface CreateExclusiveOptions {
     /** Unix mode for the new file (default 0o600 — owner-only). */
     mode?: number;
 }
+/**
+ * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call
+ * created it, `false` when it was already there.
+ *
+ * The check and the create are one `open(path, "wx")` syscall, so of N processes racing to create
+ * the same path exactly one gets `true` — no window between testing and writing. The content is
+ * written after the create, so the `false` branch tells you the file exists, not that another
+ * writer has finished filling it.
+ *
+ * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is
+ * `ENOENT`, an unwritable one `EACCES`. This never creates directories.
+ *
+ * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is
+ * subject to the process umask. That default is deliberate — the callers are token files,
+ * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.
+ *
+ * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right
+ * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential
+ * exactly once. It cannot guard repeated updates, because a file that already exists always loses.
+ * For read-modify-write on a path several writers touch, take a lock instead —
+ * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For
+ * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent
+ * primitive.
+ *
+ * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets
+ * ext4, APFS and NTFS.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function createExclusive(path: string, data: string | Uint8Array, options?: CreateExclusiveOptions): Promise<boolean>;

package/dist/internal/persistence/exclusive-create.d.ts

@@ -20,3 +20,34 @@ export interface CreateExclusiveOptions {
     /** Unix mode for the new file (default 0o600 — owner-only). */
     mode?: number;
 }
+/**
+ * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call
+ * created it, `false` when it was already there.
+ *
+ * The check and the create are one `open(path, "wx")` syscall, so of N processes racing to create
+ * the same path exactly one gets `true` — no window between testing and writing. The content is
+ * written after the create, so the `false` branch tells you the file exists, not that another
+ * writer has finished filling it.
+ *
+ * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is
+ * `ENOENT`, an unwritable one `EACCES`. This never creates directories.
+ *
+ * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is
+ * subject to the process umask. That default is deliberate — the callers are token files,
+ * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.
+ *
+ * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right
+ * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential
+ * exactly once. It cannot guard repeated updates, because a file that already exists always loses.
+ * For read-modify-write on a path several writers touch, take a lock instead —
+ * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For
+ * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent
+ * primitive.
+ *
+ * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets
+ * ext4, APFS and NTFS.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function createExclusive(path: string, data: string | Uint8Array, options?: CreateExclusiveOptions): Promise<boolean>;