@theokit/sdk 4.53.1 → 4.55.0

package/dist/internal/mcp/token-storage.d.ts

@@ -1,3 +1,37 @@
+/**
+ * The OAuth tokens held for one MCP server. See ADR D41.
+ *
+ * Persisted per server name by `setTokens` and returned unchanged by `getTokens`. Where it lands
+ * depends on what is installed: `keytar` puts the serialized bundle in the OS keychain, and
+ * without it the bundle is written to a JSON file at mode 0600 inside a 0700 directory — in
+ * PLAINTEXT, keyed by server name alongside every other server's tokens. Nothing here encrypts it.
+ *
+ * `refreshToken` is the field that matters most and the field that is optional. When present it
+ * outlives `accessToken` and can mint new ones, so a leaked store is a persistent compromise of
+ * the account rather than a temporary one. When absent, an expired access token means re-running
+ * the authorization flow.
+ *
+ * `expiresAt` and `obtainedAt` are both epoch milliseconds and both describe the ACCESS token —
+ * when it stops working, and when this bundle was issued. Nothing records when the refresh token
+ * expires, so a refresh rejected because the grant itself lapsed is only discovered at the token
+ * endpoint.
+ *
+ * The value is not validated on read: whatever JSON was stored is cast to this shape, so a
+ * hand-edited or truncated store yields an object whose fields may be missing rather than an
+ * error.
+ *
+ * `scope` records what the token was granted, as the server returned it. It is stored for
+ * inspection; nothing in this module enforces it.
+ *
+ * @public — re-exported from `@theokit/sdk/mcp-auth`, and therefore under semver.
+ */
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    scope?: string;
+    obtainedAt: number;
+}
 /**
  * Persist tokens for `serverName`. Tries keychain first, falls back to file
  * with chmod 600 (POSIX). Idempotent.

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

@@ -1,29 +1,30 @@
 'use strict';
 
-var chunkRAHSWE5C_cjs = require('../../../chunk-RAHSWE5C.cjs');
-require('../../../chunk-SVO5WPZX.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-WQ53UQL4.cjs');
-require('../../../chunk-C5DEO6OI.cjs');
-require('../../../chunk-ZT57WTUJ.cjs');
+require('../../../chunk-R3UPQFKK.cjs');
 require('../../../chunk-VKJ7V7EB.cjs');
-require('../../../chunk-LPVIRJVF.cjs');
-require('../../../chunk-BM6N4KHO.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 chunkRAHSWE5C_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-KSWHTR54.js';
-import '../../../chunk-FFM3SJTQ.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-3WVMJY7F.js';
-import '../../../chunk-R5YZACGK.js';
-import '../../../chunk-SK4QLUBK.js';
+import '../../../chunk-QARJGQSA.js';
 import '../../../chunk-RIAM53CP.js';
-import '../../../chunk-U4UJHOSH.js';
-import '../../../chunk-5F5NWKPN.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/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>;

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

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

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

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

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

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

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

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

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

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

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

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