@theokit/sdk 4.37.2 → 4.39.0

package/dist/internal/memory/adapters/azure-openai-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const azureOpenAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1 @@
+export {};

package/dist/internal/memory/adapters/cohere-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const cohereMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/deepinfra-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const deepinfraMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/gemini-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const geminiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,28 @@
+'use strict';
+
+var chunk7U2HAAWB_cjs = require('../../../chunk-7U2HAAWB.cjs');
+require('../../../chunk-6YNYA7GD.cjs');
+var chunk2RW7K6FN_cjs = require('../../../chunk-2RW7K6FN.cjs');
+require('../../../chunk-MUUQ2WFJ.cjs');
+require('../../../chunk-7OLG7VI4.cjs');
+require('../../../chunk-TIMPJL5V.cjs');
+require('../../../chunk-7YBJZS5P.cjs');
+require('../../../chunk-IHFNRNTJ.cjs');
+require('../../../chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "createOpenAiCompatibleRuntime", {
+  enumerable: true,
+  get: function () { return chunk7U2HAAWB_cjs.createOpenAiCompatibleRuntime; }
+});
+Object.defineProperty(exports, "LruEmbeddingCache", {
+  enumerable: true,
+  get: function () { return chunk2RW7K6FN_cjs.LruEmbeddingCache; }
+});
+Object.defineProperty(exports, "globalEmbeddingCache", {
+  enumerable: true,
+  get: function () { return chunk2RW7K6FN_cjs.globalEmbeddingCache; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

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

@@ -0,0 +1,16 @@
+/**
+ * theokit#160 — the ONE embedding runtime, shared with `@theokit/sdk-memory`.
+ *
+ * The satellite used to carry a full copy of `createOpenAiCompatibleRuntime`, and the peer's catalog
+ * REPLACES core's at runtime when installed — so the copy that ran was not the copy most people
+ * read. That duplication produced theokit#128 (four adapters present in one copy, missing from the
+ * other, for two months), and every fix since had to be applied twice by hand: the `{model}` path
+ * substitution, then all three provider dialects.
+ *
+ * This is the shared leaf both packages now import. Semver-exempt, exactly like the
+ * `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.
+ */
+export { createOpenAiCompatibleRuntime, type EmbeddingDialect, type OpenAiCompatibleConfig, } from "./openai-compatible.js";

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

@@ -0,0 +1,16 @@
+/**
+ * theokit#160 — the ONE embedding runtime, shared with `@theokit/sdk-memory`.
+ *
+ * The satellite used to carry a full copy of `createOpenAiCompatibleRuntime`, and the peer's catalog
+ * REPLACES core's at runtime when installed — so the copy that ran was not the copy most people
+ * read. That duplication produced theokit#128 (four adapters present in one copy, missing from the
+ * other, for two months), and every fix since had to be applied twice by hand: the `{model}` path
+ * substitution, then all three provider dialects.
+ *
+ * This is the shared leaf both packages now import. Semver-exempt, exactly like the
+ * `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.
+ */
+export { createOpenAiCompatibleRuntime, type EmbeddingDialect, type OpenAiCompatibleConfig, } from "./openai-compatible.js";

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

@@ -0,0 +1,11 @@
+export { createOpenAiCompatibleRuntime } from '../../../chunk-QKE556YD.js';
+import '../../../chunk-SCFW5MJZ.js';
+export { LruEmbeddingCache, globalEmbeddingCache } from '../../../chunk-OXNYIMZZ.js';
+import '../../../chunk-FD2UT76F.js';
+import '../../../chunk-LGILIGV3.js';
+import '../../../chunk-PI4RO4GR.js';
+import '../../../chunk-J3UK2GMN.js';
+import '../../../chunk-SG5ZWT6C.js';
+import '../../../chunk-IVSD7L22.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/internal/memory/adapters/jina-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const jinaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/mistral-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const mistralMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/ollama-embedding.d.cts

@@ -0,0 +1,34 @@
+/**
+ * Ollama embedding adapter (T3.1, ADR D183).
+ *
+ * Targets Ollama's OpenAI-compatible `/v1/embeddings` endpoint and reuses
+ * the shared `createOpenAiCompatibleRuntime` factory. The differentiating
+ * bits:
+ *
+ *  - `authType: "none"` — Ollama local ignores `Authorization`. Sentinel
+ *    `"ollama-local"` is passed as apiKey to satisfy the factory contract
+ *    (mirrors peer-project `OLLAMA_DEFAULT_API_KEY = "ollama-local"`).
+ *  - `OLLAMA_HOST` overrides the default `http://localhost:11434`.
+ *  - `OLLAMA_API_KEY` (optional) overrides the sentinel for Ollama Cloud
+ *    or reverse-proxy auth setups.
+ *  - Default model: `nomic-embed-text` (768 dim, ~274MB). User can opt
+ *    into `all-minilm` (384 dim, ~45MB) or any other locally-installed
+ *    embedding model.
+ *
+ * EC-B MUST FIX (edge-case review 2026-05-21): empty text is rejected
+ * upstream in the shared factory (`classifyEntry` short-circuits to a
+ * zero vector). That behavior is acceptable here because the zero
+ * vector is identical for any empty input — downstream similarity
+ * calcs ignore zero-norm vectors via the existing `cosineSimilarity`
+ * guard. No additional fail-fast needed.
+ *
+ * EC-A MUST FIX (edge-case review 2026-05-21): dimension is locked
+ * by the `DIMENSION_BY_MODEL` table; an unknown model id throws
+ * `ConfigurationError(code: "embedding_unknown_model")` per the
+ * factory's EC-4 contract. Future model versions with different
+ * dimensions are added to the table here without breaking changes.
+ *
+ * @internal
+ */
+export declare const DEFAULT_OLLAMA_EMBEDDING_MODEL = "nomic-embed-text";
+export declare const ollamaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,51 @@
+import type { CreateAdapterOptions, EmbeddingRuntime } from "../embedding-adapter.js";
+export interface OpenAiCompatibleConfig {
+    id: string;
+    defaultBaseUrl: string;
+    apiKeyEnv: string;
+    baseUrlEnv?: string;
+    defaultModel: string;
+    /**
+     * Dimension hint by model id. The chosen model MUST be in this table —
+     * unknown models throw `ConfigurationError(code: "embedding_unknown_model")`
+     * (EC-4 fix). This prevents vec0 virtual-table dimension mismatches that
+     * surface as cryptic errors downstream.
+     */
+    dimensionByModel: Record<string, number>;
+    /**
+     * Path component appended to `baseUrl` for the embeddings endpoint.
+     * Default `"/v1/embeddings"` (OpenAI canonical). REPLACES the default —
+     * does NOT concatenate. Used by DeepInfra (`"/v1/openai/embeddings"`),
+     * etc. (EC-2 fix).
+     */
+    embeddingsPath?: string;
+    /**
+     * theokit#159 — per-provider deviations from the OpenAI wire.
+     *
+     * The runtime was rigidly OpenAI-shaped: one auth header, one body, one response shape. Three of
+     * the ten catalog providers do not speak it, so every call they made was rejected — Azure
+     * authenticates with an `api-key` header and puts the deployment in the path, Cohere's `/v2/embed`
+     * takes `texts` and answers `{embeddings:{float}}`. Advertising a provider that cannot work is
+     * worse than not advertising it.
+     *
+     * Every hook is optional and its default is exactly the previous behaviour, so the seven
+     * providers that DO speak OpenAI are untouched.
+     */
+    dialect?: EmbeddingDialect;
+}
+/**
+ * theokit#159 — the three points where a provider may deviate from the OpenAI embedding wire.
+ *
+ * Deliberately three narrow hooks rather than a general "transform the request" seam: these are the
+ * only axes on which the supported providers actually differ, and a wider seam would invite
+ * per-provider logic that belongs in the adapter.
+ */
+export interface EmbeddingDialect {
+    /** Replaces `authorization: Bearer <key>`. */
+    authHeaders?: (apiKey: string) => Record<string, string>;
+    /** Replaces the `{ model, input }` request body. */
+    body?: (model: string, inputs: ReadonlyArray<string>) => Record<string, unknown>;
+    /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */
+    vectors?: (json: unknown) => number[][] | undefined;
+}
+export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

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

@@ -19,5 +19,33 @@ export interface OpenAiCompatibleConfig {
      * etc. (EC-2 fix).
      */
     embeddingsPath?: string;
+    /**
+     * theokit#159 — per-provider deviations from the OpenAI wire.
+     *
+     * The runtime was rigidly OpenAI-shaped: one auth header, one body, one response shape. Three of
+     * the ten catalog providers do not speak it, so every call they made was rejected — Azure
+     * authenticates with an `api-key` header and puts the deployment in the path, Cohere's `/v2/embed`
+     * takes `texts` and answers `{embeddings:{float}}`. Advertising a provider that cannot work is
+     * worse than not advertising it.
+     *
+     * Every hook is optional and its default is exactly the previous behaviour, so the seven
+     * providers that DO speak OpenAI are untouched.
+     */
+    dialect?: EmbeddingDialect;
+}
+/**
+ * theokit#159 — the three points where a provider may deviate from the OpenAI embedding wire.
+ *
+ * Deliberately three narrow hooks rather than a general "transform the request" seam: these are the
+ * only axes on which the supported providers actually differ, and a wider seam would invite
+ * per-provider logic that belongs in the adapter.
+ */
+export interface EmbeddingDialect {
+    /** Replaces `authorization: Bearer <key>`. */
+    authHeaders?: (apiKey: string) => Record<string, string>;
+    /** Replaces the `{ model, input }` request body. */
+    body?: (model: string, inputs: ReadonlyArray<string>) => Record<string, unknown>;
+    /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */
+    vectors?: (json: unknown) => number[][] | undefined;
 }
 export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const openAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/openrouter-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const openRouterMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/voyage-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const voyageMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,4 @@
+export declare function diaryPath(cwd: string): string;
+export declare function renderDiaryEntry(entry: DiaryEntry): string;
+export declare function appendDiaryEntry(cwd: string, entry: DiaryEntry): Promise<void>;
+export declare function entryHash(entry: DiaryEntry): string;

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

@@ -0,0 +1,15 @@
+import type { EmbeddingRuntime } from "../embedding-adapter.js";
+import type { MemoryFact } from "../types.js";
+export interface Cluster {
+    representativeText: string;
+    members: ReadonlyArray<MemoryFact>;
+}
+export interface ClusterResult {
+    clusters: Cluster[];
+}
+/** Light phase — drop facts whose embedding is too similar to one already kept. */
+export declare function lightPhase(facts: ReadonlyArray<MemoryFact>, embedding: EmbeddingRuntime, threshold?: number): Promise<DedupResult>;
+/** REM phase — single-link agglomerative clustering by cosine similarity. */
+export declare function remPhase(facts: ReadonlyArray<MemoryFact>, embedding: EmbeddingRuntime, threshold?: number, maxFactsPerSweep?: number): Promise<ClusterResult>;
+/** Deep phase — render consolidated markdown for the dreamed note. */
+export declare function deepPhase(clusters: ReadonlyArray<Cluster>, timestampMs: number): string;

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

@@ -0,0 +1,10 @@
+export interface DreamingResult {
+    status: "ok" | "skipped" | "error";
+    factsBefore: number;
+    factsAfter: number;
+    duplicatesRemoved: number;
+    clustersCreated: number;
+    notesWritten: number;
+    diaryEntryHash: string | undefined;
+}
+export declare function runDreamingSweep(options: DreamingOptions): Promise<DreamingResult>;

package/dist/internal/memory/migrate-sqlite-to-lance.d.ts

@@ -0,0 +1,15 @@
+export interface MigrateResult {
+    countSqlite: number;
+    countLance: number;
+    /** Set when validation succeeded (or dryRun); false on validation failure. */
+    validated: boolean;
+    /** Per-fact compare results (size = sample count, up to 10). */
+    sampleComparisons: ReadonlyArray<{
+        id: string;
+        match: boolean;
+    }>;
+    /** Lance storage location (final, after migration). */
+    lancePath: string;
+    /** Was the migration committed (false for dry-run). */
+    committed: boolean;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * SDK 2.0 Phase 4 (Stage 4) — Optional peer loader for
+ * `@theokit/sdk-memory`.
+ *
+ * The Memory class public API in `src/memory.ts` keeps its surface
+ * stable but routes through sdk-memory when installed. When sdk-memory
+ * is NOT installed, methods fall back to sdk-core's legacy
+ * `internal/memory/*` implementations — preserving v1.x back-compat.
+ *
+ * Pattern mirrors sdk-handoff's optional-peer dynamic import: try
+ * `await import("@theokit/sdk-memory")` once, cache the result (the
+ * module OR `null` for "definitively missing"), and let the caller
+ * route.
+ *
+ * Iter 76 (Stage 4 #1): foundation helper for the Memory class
+ * delegation refactor. No behavior changes yet — this iter only
+ * adds the loader; iter 77+ wires Memory class methods to use it.
+ *
+ * @internal
+ */
+export {};

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

@@ -11,8 +11,8 @@
  * readable 0o644 under typical umask 022. Callers writing non-sensitive
  * files can pass `mode: 0o644` explicitly.
  *
- * NFS sem honor de O_EXCL é documentado (D61 — mesma postura do
- * `withFileLock`); SDK target é ext4/APFS/NTFS.
+ * NFS not honoring O_EXCL is documented (D61 — same stance as
+ * `withFileLock`); the SDK target is ext4/APFS/NTFS.
  *
  * @internal
  */

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

@@ -11,8 +11,8 @@
  * readable 0o644 under typical umask 022. Callers writing non-sensitive
  * files can pass `mode: 0o644` explicitly.
  *
- * NFS sem honor de O_EXCL é documentado (D61 — mesma postura do
- * `withFileLock`); SDK target é ext4/APFS/NTFS.
+ * NFS not honoring O_EXCL is documented (D61 — same stance as
+ * `withFileLock`); the SDK target is ext4/APFS/NTFS.
  *
  * @internal
  */

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

@@ -32,34 +32,34 @@ export declare class FsSessionStore implements SessionStore {
     readRecords(agentId: string): Promise<SessionRecord[]>;
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
     /**
-     * Toma o lease de escritor da sessão. Lança `SessionBusyError` quando outro processo a detém.
+     * Takes the session's writer lease. Throws `SessionBusyError` when another process holds it.
      *
-     * **Explícito, e NÃO no `appendRecords`** — a revisão adversarial do M95 mediu por que isso
-     * importa: o contrato de `SessionStore` diz que "an `appendRecords` rejection is logged to
-     * stderr, NOT thrown to the caller (best-effort write)". Adquirir ali fazia o `SessionBusyError`
-     * ser **engolido**, e o resultado era pior que o problema original: em vez de dois escritores
-     * intercalarem linhas, o perdedor **perdia o turno em silêncio** — nada em disco, um aviso em
-     * stderr invisível sob a TUI, e o chamador sem como reagir.
+     * **Explicit, and NOT inside `appendRecords`** — M95's adversarial review measured why that
+     * matters: the `SessionStore` contract states that "an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write)". Acquiring there made the
+     * `SessionBusyError` get **swallowed**, and the result was worse than the original problem:
+     * instead of two writers interleaving lines, the loser **lost the turn silently** — nothing on
+     * disk, a stderr warning invisible under the TUI, and no way for the caller to react.
      *
-     * No init o erro chega a quem pode agir: o `exec` forka para um id novo, que é o que a própria
-     * mensagem do erro prescreve. É a diferença entre falhar onde dá para decidir e falhar onde só
-     * dá para perder.
+     * At init the error reaches someone who can act: `exec` forks to a new id, which is exactly what
+     * the error message itself prescribes. It is the difference between failing where a decision is
+     * possible and failing where only loss is.
      */
     acquire(agentId: string): Promise<void>;
     /**
-     * Solta o lease de UM agente.
+     * Releases ONE agent's lease.
      *
-     * Existe porque `dispose()` solta **todos** os leases do store, e um store injetado pelo
-     * consumidor pode servir vários agentes: um init que falha para o agente B não pode liberar o
-     * lease do agente A, que segue vivo e escrevendo.
+     * It exists because `dispose()` releases **every** lease the store holds, and a store injected by
+     * the consumer may serve several agents: an init that fails for agent B must not free agent A's
+     * lease, which is still live and writing.
      */
     release(agentId: string): Promise<void>;
     /**
-     * Solta todo lease que este store detém.
+     * Releases every lease this store holds.
      *
-     * Sem isto o `.writer.lock` sobrevive ao processo e a próxima abertura teria de esperar a janela
-     * de heartbeat — recuperável, mas 30 s de espera para um encerramento LIMPO seria um defeito
-     * evitável. Idempotente: chamar duas vezes não é erro.
+     * Without it the `.writer.lock` outlives the process and the next open would have to wait out the
+     * heartbeat window — recoverable, but 30 s of waiting after a CLEAN shutdown would be an avoidable
+     * defect. Idempotent: calling it twice is not an error.
      */
     dispose(): Promise<void>;
 }

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

@@ -32,34 +32,34 @@ export declare class FsSessionStore implements SessionStore {
     readRecords(agentId: string): Promise<SessionRecord[]>;
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
     /**
-     * Toma o lease de escritor da sessão. Lança `SessionBusyError` quando outro processo a detém.
+     * Takes the session's writer lease. Throws `SessionBusyError` when another process holds it.
      *
-     * **Explícito, e NÃO no `appendRecords`** — a revisão adversarial do M95 mediu por que isso
-     * importa: o contrato de `SessionStore` diz que "an `appendRecords` rejection is logged to
-     * stderr, NOT thrown to the caller (best-effort write)". Adquirir ali fazia o `SessionBusyError`
-     * ser **engolido**, e o resultado era pior que o problema original: em vez de dois escritores
-     * intercalarem linhas, o perdedor **perdia o turno em silêncio** — nada em disco, um aviso em
-     * stderr invisível sob a TUI, e o chamador sem como reagir.
+     * **Explicit, and NOT inside `appendRecords`** — M95's adversarial review measured why that
+     * matters: the `SessionStore` contract states that "an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write)". Acquiring there made the
+     * `SessionBusyError` get **swallowed**, and the result was worse than the original problem:
+     * instead of two writers interleaving lines, the loser **lost the turn silently** — nothing on
+     * disk, a stderr warning invisible under the TUI, and no way for the caller to react.
      *
-     * No init o erro chega a quem pode agir: o `exec` forka para um id novo, que é o que a própria
-     * mensagem do erro prescreve. É a diferença entre falhar onde dá para decidir e falhar onde só
-     * dá para perder.
+     * At init the error reaches someone who can act: `exec` forks to a new id, which is exactly what
+     * the error message itself prescribes. It is the difference between failing where a decision is
+     * possible and failing where only loss is.
      */
     acquire(agentId: string): Promise<void>;
     /**
-     * Solta o lease de UM agente.
+     * Releases ONE agent's lease.
      *
-     * Existe porque `dispose()` solta **todos** os leases do store, e um store injetado pelo
-     * consumidor pode servir vários agentes: um init que falha para o agente B não pode liberar o
-     * lease do agente A, que segue vivo e escrevendo.
+     * It exists because `dispose()` releases **every** lease the store holds, and a store injected by
+     * the consumer may serve several agents: an init that fails for agent B must not free agent A's
+     * lease, which is still live and writing.
      */
     release(agentId: string): Promise<void>;
     /**
-     * Solta todo lease que este store detém.
+     * Releases every lease this store holds.
      *
-     * Sem isto o `.writer.lock` sobrevive ao processo e a próxima abertura teria de esperar a janela
-     * de heartbeat — recuperável, mas 30 s de espera para um encerramento LIMPO seria um defeito
-     * evitável. Idempotente: chamar duas vezes não é erro.
+     * Without it the `.writer.lock` outlives the process and the next open would have to wait out the
+     * heartbeat window — recoverable, but 30 s of waiting after a CLEAN shutdown would be an avoidable
+     * defect. Idempotent: calling it twice is not an error.
      */
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/index.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
 var chunkPNVDQL5Y_cjs = require('../../chunk-PNVDQL5Y.cjs');
-var chunkD4ZUJTFB_cjs = require('../../chunk-D4ZUJTFB.cjs');
-var chunkTQI3KRXZ_cjs = require('../../chunk-TQI3KRXZ.cjs');
-var chunkFK4EJD2I_cjs = require('../../chunk-FK4EJD2I.cjs');
+var chunkLALG2K33_cjs = require('../../chunk-LALG2K33.cjs');
+var chunkDMTZ3FII_cjs = require('../../chunk-DMTZ3FII.cjs');
+var chunk75DSEWTJ_cjs = require('../../chunk-75DSEWTJ.cjs');
 var chunkYLQQX5W2_cjs = require('../../chunk-YLQQX5W2.cjs');
-var chunkICYBIC6N_cjs = require('../../chunk-ICYBIC6N.cjs');
-require('../../chunk-MHCKWQR3.cjs');
-require('../../chunk-LTCOPATU.cjs');
+var chunkDGLLVCNB_cjs = require('../../chunk-DGLLVCNB.cjs');
+require('../../chunk-IHFNRNTJ.cjs');
+require('../../chunk-BCQ3E2ZG.cjs');
 var promises = require('fs/promises');
 
 async function createExclusive(path, data, options) {
@@ -41,67 +41,67 @@ Object.defineProperty(exports, "PersistenceSchema", {
 });
 Object.defineProperty(exports, "displayTheokitHome", {
   enumerable: true,
-  get: function () { return chunkD4ZUJTFB_cjs.displayTheokitHome; }
+  get: function () { return chunkLALG2K33_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkD4ZUJTFB_cjs.getProfilesRoot; }
+  get: function () { return chunkLALG2K33_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkD4ZUJTFB_cjs.getTheokitHome; }
+  get: function () { return chunkLALG2K33_cjs.getTheokitHome; }
 });
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunkD4ZUJTFB_cjs.migrateSchema; }
+  get: function () { return chunkLALG2K33_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "readVersionedJson", {
   enumerable: true,
-  get: function () { return chunkD4ZUJTFB_cjs.readVersionedJson; }
+  get: function () { return chunkLALG2K33_cjs.readVersionedJson; }
 });
 Object.defineProperty(exports, "writeVersionedJson", {
   enumerable: true,
-  get: function () { return chunkD4ZUJTFB_cjs.writeVersionedJson; }
+  get: function () { return chunkLALG2K33_cjs.writeVersionedJson; }
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkTQI3KRXZ_cjs.JsonlParseError; }
+  get: function () { return chunkDMTZ3FII_cjs.JsonlParseError; }
 });
 Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkTQI3KRXZ_cjs.appendJsonl; }
+  get: function () { return chunkDMTZ3FII_cjs.appendJsonl; }
 });
 Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkTQI3KRXZ_cjs.loadJsonl; }
+  get: function () { return chunkDMTZ3FII_cjs.loadJsonl; }
 });
 Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkTQI3KRXZ_cjs.readJsonlIds; }
+  get: function () { return chunkDMTZ3FII_cjs.readJsonlIds; }
 });
 Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkTQI3KRXZ_cjs.withFileLock; }
+  get: function () { return chunkDMTZ3FII_cjs.withFileLock; }
 });
 Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunkFK4EJD2I_cjs.applyWalWithFallback; }
+  get: function () { return chunk75DSEWTJ_cjs.applyWalWithFallback; }
 });
 Object.defineProperty(exports, "containsCjk", {
   enumerable: true,
-  get: function () { return chunkFK4EJD2I_cjs.containsCjk; }
+  get: function () { return chunk75DSEWTJ_cjs.containsCjk; }
 });
 Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunkFK4EJD2I_cjs.isCorruptionError; }
+  get: function () { return chunk75DSEWTJ_cjs.isCorruptionError; }
 });
 Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunkFK4EJD2I_cjs.openSqliteResilient; }
+  get: function () { return chunk75DSEWTJ_cjs.openSqliteResilient; }
 });
 Object.defineProperty(exports, "sanitizeFts5Query", {
   enumerable: true,
-  get: function () { return chunkFK4EJD2I_cjs.sanitizeFts5Query; }
+  get: function () { return chunk75DSEWTJ_cjs.sanitizeFts5Query; }
 });
 Object.defineProperty(exports, "withCwdMutex", {
   enumerable: true,
@@ -109,15 +109,15 @@ Object.defineProperty(exports, "withCwdMutex", {
 });
 Object.defineProperty(exports, "atomicWriteJson", {
   enumerable: true,
-  get: function () { return chunkICYBIC6N_cjs.atomicWriteJson; }
+  get: function () { return chunkDGLLVCNB_cjs.atomicWriteJson; }
 });
 Object.defineProperty(exports, "atomicWriteText", {
   enumerable: true,
-  get: function () { return chunkICYBIC6N_cjs.atomicWriteText; }
+  get: function () { return chunkDGLLVCNB_cjs.atomicWriteText; }
 });
 Object.defineProperty(exports, "replaceFileAtomic", {
   enumerable: true,
-  get: function () { return chunkICYBIC6N_cjs.replaceFileAtomic; }
+  get: function () { return chunkDGLLVCNB_cjs.replaceFileAtomic; }
 });
 exports.casUpdate = casUpdate;
 exports.createExclusive = createExclusive;

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;AAgCA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAMA,aAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACjBO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.cjs","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS sem honor de O_EXCL é documentado (D61 — mesma postura do\n * `withFileLock`); SDK target é ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Atomically create `path` with `data`. Returns true iff this call\n * created the file (race-free under POSIX-compliant filesystems).\n *\n * @internal\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * @internal\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Execute a CAS UPDATE. Returns true iff the actual changes count matches\n * `expectedChanges`. SQL errors (invalid syntax, closed db) propagate.\n *\n * @internal\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}
+{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;AAgCA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAMA,aAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACjBO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.cjs","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Atomically create `path` with `data`. Returns true iff this call\n * created the file (race-free under POSIX-compliant filesystems).\n *\n * @internal\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * @internal\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Execute a CAS UPDATE. Returns true iff the actual changes count matches\n * `expectedChanges`. SQL errors (invalid syntax, closed db) propagate.\n *\n * @internal\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}