@theokit/sdk 1.5.0

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

@@ -0,0 +1,68 @@
+import type { EmbeddingRuntime } from "./embedding-adapter.js";
+import { type MemoryIndex } from "./memory-index.js";
+export interface IndexStatus {
+    backend: "fts-only" | "hybrid";
+    filesIndexed: number;
+    chunksIndexed: number;
+    lastSyncMs?: number;
+}
+export interface SearchOptions {
+    maxResults?: number;
+    minScore?: number;
+    sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+    /** 0..1 — vector vs text weight in hybrid scoring (D4). Default 0.6. */
+    vectorWeight?: number;
+    /** 0..1 — text weight in hybrid scoring. Default 0.4. */
+    textWeight?: number;
+}
+/** Vector backend selector. SQLite default; Lance opt-in (ADR D43). */
+export type MemoryBackend = "sqlite-vec" | "lance";
+export interface OpenIndexOptions {
+    cwd: string;
+    filePath?: string;
+    /** When provided, vector index is enabled in hybrid mode. */
+    embedding?: EmbeddingRuntime;
+    /** Vector backend. Default and only value today: `"sqlite-vec"`. */
+    backend?: MemoryBackend;
+}
+export declare class IndexManager implements MemoryIndex {
+    private readonly cwd;
+    private readonly db;
+    private readonly embedding;
+    private lastSyncMs;
+    private vectorReady;
+    private constructor();
+    /**
+     * Open a memory index. Dispatches to SQLite (default) or Lance (opt-in
+     * via `backend: "lance"`). See `openLanceInternal` for Lance-specific
+     * preconditions + typed errors.
+     */
+    static open(opts: OpenIndexOptions & {
+        backend: "lance";
+    }): Promise<MemoryIndex>;
+    static open(opts: Omit<OpenIndexOptions, "backend"> | (OpenIndexOptions & {
+        backend?: "sqlite-vec";
+    })): Promise<IndexManager>;
+    /** Internal SQLite-path open. Renamed from previous public `open`. */
+    private static openSqliteInternal;
+    private initVectorBackend;
+    /** Walk the memory corpus + (re)index changed files. */
+    sync(): Promise<{
+        filesScanned: number;
+        filesUpdated: number;
+        chunksWritten: number;
+        chunksEmbedded: number;
+    }>;
+    search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
+    status(): IndexStatus;
+    private ftsSearch;
+    private vectorSearchById;
+    private combineHybridScores;
+    private mergeHits;
+    private fetchChunksByIds;
+    private loadFilesIndex;
+    private upsertFile;
+    private deleteChunksForFile;
+    private insertChunk;
+    close(): void;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * SQLite schema for the memory index.
+ *
+ * Tables:
+ *   - files      — one row per indexed markdown file (path, mtime, hash).
+ *   - chunks     — one row per chunk produced by `chunkMarkdown`.
+ *   - chunks_fts — FTS5 virtual table mirroring chunks.text for BM25 search.
+ *   - meta       — key/value store; persists the active embedding identity
+ *                  (provider id, model, dimension) so we detect when the
+ *                  index was built against a different embedding setup.
+ *   - embeddings — sqlite-vec virtual table holding the chunk vectors
+ *                  (created on demand by `vec-index.ts`).
+ *
+ * @internal
+ */
+/**
+ * Non-WAL pragmas. WAL is applied separately via
+ * `applyWalWithFallback` (T4.2, ADR D63) so NFS/SMB users get a graceful
+ * DELETE fallback instead of crashing.
+ */
+export declare const PRAGMA_STATEMENTS: ReadonlyArray<string>;

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

@@ -0,0 +1,32 @@
+import type { EmbeddingRuntime } from "./embedding-adapter.js";
+export interface LanceFactRecord {
+    id: string;
+    text: string;
+    source: "memory" | "sessions" | "wiki";
+    embedding: ReadonlyArray<number>;
+    namespace: string;
+    scope: string;
+    user_id: string;
+    timestamp: number;
+}
+export interface OpenLanceOptions {
+    cwd: string;
+    embedding: EmbeddingRuntime;
+    /** Override storage location. Default: `<cwd>/.theokit/memory/lance/`. */
+    storagePath?: string;
+}
+export interface LanceSearchOptions {
+    namespace: string;
+    scope?: string;
+    limit?: number;
+    sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+}
+export interface LanceSearchHit {
+    id: string;
+    text: string;
+    source: "memory" | "sessions" | "wiki";
+    namespace: string;
+    scope: string;
+    userId: string;
+    score: number;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * `LanceMemoryAdapter` — wraps `LanceIndex` to expose the common
+ * `MemoryIndex` interface (sync/search/status/close) so consumers of
+ * `IndexManager.open({ backend: "lance" })` get a drop-in replacement
+ * for the SQLite-backed `IndexManager`.
+ *
+ * Semantic deltas vs SQLite (documented so callers know what to expect):
+ *
+ *  - `sync()` is a NO-OP. Lance is a pure vector store — there is no
+ *    markdown corpus to crawl. Returns zero counts. Consumers writing
+ *    facts use `LanceIndex.addFacts` directly (exposed via the index
+ *    object returned to advanced callers).
+ *  - `search()` performs vector-only retrieval. `MemorySearchHit.textScore`
+ *    is undefined (no FTS5 layer); `vectorScore === score`.
+ *  - `status()` reports `backend: "hybrid"` only when an embedding runtime
+ *    is wired (always the case for Lance — embedding is required at open).
+ *    `chunksIndexed` reflects total Lance row count; `filesIndexed` is 0
+ *    because Lance does not track file provenance per-row.
+ *
+ * Ships with the lancedb-backend-ship-v1-1 plan (close D12, supersede via
+ * D43). v1.4.0 of `@theokit/sdk`.
+ *
+ * @internal
+ */
+import type { LanceIndex } from "./lance-index.js";
+import { type MemoryIndex, type SyncResult } from "./memory-index.js";
+export declare class LanceMemoryAdapter implements MemoryIndex {
+    private readonly inner;
+    constructor(inner: LanceIndex);
+    /**
+     * No-op for Lance — see file header. Returns zero counts so callers'
+     * existing logging (`filesScanned: X`) does not break.
+     */
+    sync(): Promise<SyncResult>;
+    search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
+    status(): IndexStatus;
+    close(): Promise<void>;
+    /**
+     * Escape hatch for advanced callers (migration tool, benchmark script)
+     * that need direct access to addFacts/countFacts/removeFacts.
+     */
+    unwrap(): LanceIndex;
+}

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

@@ -0,0 +1,16 @@
+import { type MemoryConfig, type MemoryFact } from "./types.js";
+export declare function memoryDir(cwd: string): string;
+export declare function memoryMdPath(cwd: string): string;
+export declare function notesDir(cwd: string): string;
+/** Read facts from `MEMORY.md`'s `## Facts` section. Returns `[]` when missing. */
+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/memory/memory-index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Common `MemoryIndex` interface shared between the SQLite-backed
+ * `IndexManager` (default) and the Lance-backed adapter (ADR D43, shipped
+ * v1.4.0 via lancedb-backend-ship-v1-1 plan).
+ *
+ * Consumers (`local-agent-memory.ts`, `active-memory.ts`, `tools.ts`,
+ * `runActiveMemory`) only ever call `sync()`, `search()`, `status()`,
+ * `close()` — the union of those four methods is the portable surface.
+ *
+ * Why a separate file (vs declaring inline in `index-manager.ts`)? D43
+ * promised "extrair interface abstrata `MemoryIndex` em
+ * `internal/memory/index-interface.ts`". Keeping the contract physically
+ * separated from one of its implementations preserves OCP — future
+ * backends (Qdrant, PGVector) can land without touching IndexManager.
+ *
+ * @internal
+ */
+export type { IndexStatus, MemorySearchHit, SearchOptions };
+export interface SyncResult {
+    filesScanned: number;
+    filesUpdated: number;
+    chunksWritten: number;
+    chunksEmbedded: number;
+}
+/**
+ * Common search-options parser used by both `IndexManager.search` and
+ * `LanceMemoryAdapter.search`. Returns the normalized cap + minimum-score
+ * floor — eliminates jscpd duplication while keeping per-backend search
+ * logic distinct.
+ */
+export declare function parseSearchOptions(options?: SearchOptions): {
+    maxResults: number;
+    minScore: number;
+};
+export interface MemoryIndex {
+    /**
+     * Walk the memory corpus + reindex changed files. Lance backend has no
+     * markdown corpus to walk — its adapter returns zero counts (no-op) and
+     * relies on explicit `addFact` calls instead.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Semantic + textual search over the indexed corpus. Both backends
+     * return the same `MemorySearchHit[]` shape; Lance leaves `textScore`
+     * undefined (vector-only — no FTS5 layer).
+     */
+    search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
+    /** Snapshot of the index health (backend type + counts). */
+    status(): IndexStatus;
+    /** Release native handles. Idempotent. */
+    close(): Promise<void> | void;
+}

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/migration.d.ts

@@ -0,0 +1,9 @@
+import { type MemoryConfig } from "./types.js";
+export interface MigrationResult {
+    migrated: boolean;
+    factCount: number;
+    reason?: "already-migrated" | "no-legacy-json" | "markdown-exists" | "readonly-fs";
+}
+export declare function migrateLegacyJson(cwd: string, config: MemoryConfig): Promise<MigrationResult>;
+/** Test-only — reset the in-process migration flag map. */
+export declare function resetMigrationStateForTests(): void;

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

@@ -0,0 +1,8 @@
+import type { MemoryReadResult } from "./types.js";
+export interface ReadFileOptions {
+    cwd: string;
+    relPath: string;
+    from?: number;
+    lines?: number;
+}
+export declare function readMemoryFileBounded(opts: ReadFileOptions): Promise<MemoryReadResult>;

package/dist/internal/memory/session-loader.d.ts

@@ -0,0 +1 @@
+export declare function discoverSessionFiles(cwd: string): Promise<SessionFile[]>;

package/dist/internal/memory/session-summary-writer.d.ts

@@ -0,0 +1,2 @@
+export declare function sessionsDir(cwd: string): string;
+export declare function sessionSummaryPath(cwd: string, runId: string): string;

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

@@ -0,0 +1,3 @@
+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;

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

@@ -0,0 +1,14 @@
+import type { MemoryIndex } from "./memory-index.js";
+export interface MemoryTool extends MemoryToolJson {
+    execute(input: Record<string, unknown>): Promise<string>;
+}
+export interface MemorySearchToolOptions {
+    index: MemoryIndex;
+    /** Cap on the JSON response size (EC-10 of edge-case review). Default 16384. */
+    maxTotalChars?: number;
+}
+export declare function createMemorySearchTool(opts: MemorySearchToolOptions): MemoryTool;
+export interface MemoryGetToolOptions {
+    cwd: string;
+}
+export declare function createMemoryGetTool(opts: MemoryGetToolOptions): MemoryTool;

package/dist/internal/memory/transcript-store.d.ts

@@ -0,0 +1 @@
+export declare function persistActiveMemoryTranscript(cwd: string, transcript: ActiveMemoryTranscript): Promise<void>;

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

@@ -0,0 +1,17 @@
+export interface MemoryConfig {
+    enabled: boolean;
+    namespace?: string;
+    userId?: string;
+    scope?: "agent" | "user" | "team";
+    storePath?: string;
+}
+export interface MemoryFact {
+    text: string;
+}
+export { redactSecrets } from "../security/index.js";
+/**
+ * Resolve the legacy JSON memory path used pre-ADR-D8 (kept for migration
+ * helpers + tests). Centralized here so `migration.ts` and the legacy-aware
+ * `runtime/memory-store.ts` don't duplicate the path logic (jscpd cleanup).
+ */
+export declare function legacyMemoryJsonPath(cwd: string, config: MemoryConfig): string;

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

@@ -0,0 +1,28 @@
+import type { EmbeddingRuntime } from "./embedding-adapter.js";
+import type { MemoryDb } from "./index-db.js";
+export declare const META_KEY_MODEL = "embedding.model";
+export declare const META_KEY_DIMENSION = "embedding.dimension";
+export interface EmbeddingIdentity {
+    providerId: string;
+    model: string;
+    dimension: number;
+}
+export declare function readEmbeddingIdentity(db: MemoryDb): EmbeddingIdentity | undefined;
+export declare function writeEmbeddingIdentity(db: MemoryDb, identity: EmbeddingIdentity): void;
+export declare function identityMatches(a: EmbeddingIdentity, b: EmbeddingIdentity): boolean;
+export declare function dropVectorIndex(db: MemoryDb): void;
+export declare function createVectorIndex(db: MemoryDb, dimension: number): void;
+/** Pack a Float32Array into a Buffer suitable for sqlite-vec BLOB binding. */
+export declare function packVector(vec: ReadonlyArray<number>): Buffer;
+export declare function upsertEmbedding(db: MemoryDb, chunkId: number, vec: ReadonlyArray<number>): void;
+export interface VectorHitRow {
+    chunk_id: number;
+    distance: number;
+}
+export declare function vectorSearch(db: MemoryDb, query: ReadonlyArray<number>, k: number): VectorHitRow[];
+export interface EmbedAllArgs {
+    db: MemoryDb;
+    runtime: EmbeddingRuntime;
+}
+/** Embed every chunk that doesn't yet have a vector. */
+export declare function embedMissingChunks(args: EmbedAllArgs): Promise<number>;

package/dist/internal/memory/wiki-loader.d.ts

@@ -0,0 +1,2 @@
+export declare function wikiDir(cwd: string): string;
+export declare function discoverWikiFiles(cwd: string): Promise<WikiFile[]>;

package/dist/internal/observability/tracer-loader.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared OTel tracer loader (extracted to eliminate cross-module clones —
+ * was previously inlined in cache/, workflow/, eval/, handoff/ telemetry
+ * modules). Lazy-loads `@opentelemetry/api` via `createRequire`; users
+ * without OTel installed pay zero cost.
+ *
+ * @internal
+ */
+export interface SpanLike {
+    setAttribute(key: string, value: string | number | boolean): SpanLike;
+    end(): void;
+}
+export declare const noopSpan: SpanLike;
+export interface TracerLike {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): SpanLike;
+}
+export declare function getTracer(name: string, version?: string): TracerLike | undefined;
+export declare function resetTracerCacheForTests(): void;

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

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

package/dist/internal/persistence/conversation-storage-fs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Filesystem-backed implementation of {@link ConversationStorageAdapter}
+ * (Production-Readiness #1, ADR D304).
+ *
+ * Default adapter when `AgentOptions.conversationStorage` is not provided.
+ * Writes append-only JSONL to `<root>/.theokit/agents/<safeId>/messages.jsonl`,
+ * preserving the pre-D303 byte-identical behavior (redaction D68 + JSONL
+ * line granularity).
+ *
+ * Path safety: every conversationId flows through `sanitizeIdentifier` +
+ * `safePathJoin` before touching disk. `deleteConversation` re-applies the
+ * guard (EC-1) — without this the new `rm -rf` would escape via traversal.
+ *
+ * Listing: `listConversationIds` catches ENOENT (EC-2) so first-run deploys
+ * without any `.theokit/agents/` directory return `[]` instead of crashing.
+ *
+ * @public
+ */
+import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+export interface FileSystemConversationStorageOptions {
+    /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
+    root?: string;
+}
+export declare class FileSystemConversationStorage implements ConversationStorageAdapter {
+    #private;
+    constructor(opts?: FileSystemConversationStorageOptions);
+    /** Exposed for tests + diagnostics. The path is sanitized at use sites. */
+    get root(): string;
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds(opts?: {
+        limit?: number;
+    }): Promise<readonly string[]>;
+    compact(conversationId: string, maxTurns: number): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/internal/persistence/conversation-storage-memory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * In-memory implementation of {@link ConversationStorageAdapter} (Production-Readiness #1, ADR D304).
+ *
+ * Intended for tests + ephemeral single-process dev/CLI usage. Holds messages
+ * in a `Map<conversationId, StoredMessage[]>`. JavaScript's single-threaded
+ * runtime makes per-conversation appends naturally atomic; no external mutex
+ * needed.
+ *
+ * The adapter returns defensive copies from `getMessages` so callers cannot
+ * mutate internal state by holding a reference to the returned array.
+ *
+ * @public
+ */
+import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+export declare class InMemoryConversationStorage implements ConversationStorageAdapter {
+    #private;
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds(opts?: {
+        limit?: number;
+    }): Promise<readonly string[]>;
+    dispose(): Promise<void>;
+}

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

@@ -0,0 +1 @@
+export declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,14 @@
+/**
+ * Cross-process file lock helper (ADR D61).
+ *
+ * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When
+ * the peer dep is absent, falls back to `withCwdMutex` (in-process only)
+ * with a one-shot stderr warning.
+ *
+ * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so
+ * `withFileLock` works even when the target `path` does not exist yet.
+ * Without this, fresh installs that lock-then-create would crash with ENOENT.
+ *
+ * @internal
+ */
+export {};

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

@@ -0,0 +1,16 @@
+/**
+ * FTS5 query sanitization + CJK detection (ADR D64).
+ *
+ * Port of Hermes' 6-step sanitizer (`hermes_state.py:1797-1847`). Prevents
+ * crashes on user inputs with hyphens, dots, underscores, and unmatched
+ * specials. Auto-quotes identifier-shaped tokens so `error-code` finds
+ * literal `error-code` instead of `error AND code`.
+ *
+ * CJK detection returns true for inputs containing characters in the main
+ * CJK Unicode ranges (Chinese, Japanese, Korean). CJK trigram routing is
+ * deferred to v1.4 — callers receiving `containsCjk === true` should
+ * short-circuit to an empty result or LIKE fallback for v1.3.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/persistence/markdown-config-loader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared loader for `.theokit/<dir>/<name>.md` (or `.theokit/<dir>/<name>/PLUGIN.md`)
+ * config files. Mirrors the SKILL.md pattern: YAML frontmatter delimited by
+ * `---` blocks + optional markdown body for prose / rationale.
+ *
+ * Consumed by hooks-loader (T1.2), context-manager (T2.2), and
+ * plugins-manager (T3.2) — DRY across all 3 user-edited config surfaces.
+ *
+ * ADRs: D74 (markdown format), D75 (1 file = 1 entity), D76 (Zod schema).
+ *
+ * @internal
+ */
+import type { z } from "zod";
+export interface MarkdownEntity<T> {
+    /** Slug from filename (without `.md`) for flat pattern, or subdir name for nested. */
+    slug: string;
+    /** Validated frontmatter. */
+    frontmatter: T;
+    /** Markdown body (everything after the closing `---`). May be empty. */
+    body: string;
+    /** Absolute source path for audit / error context. */
+    source: string;
+}
+export interface LoadOptions<T> {
+    /** Absolute path to the directory containing `*.md` files (flat) or
+     *  subdirs with `PLUGIN.md` (nested). */
+    dir: string;
+    /** Zod schema validating the frontmatter shape. */
+    schema: z.ZodType<T>;
+    /** `"flat"` = top-level `<slug>.md` files; `"nested"` = subdirs each with
+     *  `PLUGIN.md`. Default: `"flat"`. */
+    pattern?: "flat" | "nested";
+    /** Error code prefix (e.g., `"hook"` → `"hook_frontmatter_invalid"`). */
+    errorCodePrefix: string;
+}

package/dist/internal/persistence/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Path resolution for SDK state files (ADR D60).
+ *
+ * Theokit anchors state at `<cwd>/.theokit/` by default (per-cwd). An
+ * optional `THEOKIT_HOME` environment variable overrides this, enabling
+ * test isolation, profile switching, and multi-tenant deployments.
+ *
+ * Rules:
+ *   - `getTheokitHome(cwd)` is the ONLY canonical resolver. Never hardcode
+ *     `path.join(cwd, ".theokit")` in callers — use this function so tests
+ *     and overrides stay consistent.
+ *   - `getProfilesRoot()` is intentionally home-anchored (not affected by
+ *     `THEOKIT_HOME`) so `theokit profile list` discovers all profiles
+ *     regardless of which is active.
+ *   - `displayTheokitHome(cwd)` returns a human-readable path for logs.
+ *
+ * @internal
+ */
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * Shared Zod schema for the `{ backend: "memory" | "json", dir? }` options
+ * used by both `Workflow` snapshots and `Cache` semantic store persistence.
+ * Extracted to remove the cross-module clone flagged by jscpd.
+ *
+ * @internal
+ */
+/**
+ * `persistence?` opt-in JSON disk backend with `dir` required when chosen.
+ */
+export declare const PersistenceSchema: z.ZodOptional<z.ZodObject<{
+    backend: z.ZodEnum<{
+        memory: "memory";
+        json: "json";
+    }>;
+    dir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;

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

@@ -0,0 +1,13 @@
+/**
+ * Schema versioning helpers (ADR D62).
+ *
+ * Two parallel APIs:
+ *   - `migrateSchema` — SQLite via `PRAGMA user_version` + ordered forward-only migrations.
+ *   - `readVersionedJson` / `writeVersionedJson` — JSON files with `_schemaVersion` field.
+ *
+ * Forward-only: never deletes data, never downgrades. Migration callbacks
+ * own the transformation; this module owns the bookkeeping.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/persistence/sqlite-wal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SQLite WAL mode helper with NFS/SMB/FUSE fallback to DELETE (ADR D63).
+ *
+ * WAL is faster (concurrent readers + one writer) but unsupported on some
+ * network/FUSE filesystems. Try WAL; if the pragma returns something else
+ * or throws, fall back to DELETE journal mode. Warn one time per label.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/personality/context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Personality fork-context (ADR D168 + EC-A snapshot semantic).
+ *
+ * Uses Node's `AsyncLocalStorage` so a fork's execution chain can know
+ * that it is running inside a fork AND can see the slug that was active
+ * on the parent **at fork-construction time**.
+ *
+ * **EC-A:** The slug stored here is captured ONCE at the wrap site
+ * (`localAgentFork`) — passing `parentStore.active(parentAgentId)`
+ * returns a primitive `string | undefined`, which is then frozen
+ * inside the ALS context object. Subsequent `usePersonality` calls on
+ * the parent do NOT mutate the fork's view, because the fork reads from
+ * its own ALS frame, not from the parent's store.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/personality/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PersonalityRegistry — loads `.theokit/personalities/*.md` from project
+ * + user dirs (T1.1, ADRs D161 / D162).
+ *
+ * Project entries win on slug collision (matches `.theokit/` family
+ * convention). Reserved slugs (`none`, `default`, `neutral`) cannot be
+ * registered — they map to "clear active preset".
+ *
+ * **EC-C:** name regex enforced lowercase-only by the Zod schema in
+ * `types.ts`. Filenames are independent of the frontmatter `name`.
+ *
+ * **EC-M (documented):** body content is NOT sanitized against
+ * prompt-injection — users own their preset content.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/personality/store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * PersonalityStore — session-default + persistent JSON state of the
+ * currently-active personality slug per agentId (T2.1, ADR D163).
+ *
+ * Storage layout (`$THEOKIT_HOME/personality.json`):
+ *
+ * ```json
+ * { "version": 1, "agents": { "agent-xyz": "coder" } }
+ * ```
+ *
+ * **EC-B (MUST FIX):** `setActive(agentId, undefined, { save: true })`
+ * **DELETES** the key from the `agents` map. Never writes `null`.
+ * "Key absent === no active personality" is the single canonical
+ * representation. Hydration only reads present keys.
+ *
+ * **EC-N (DOCUMENT):** Brief memory/disk divergence on persist failure is
+ * tolerated — session state always wins; next successful call recovers.
+ * Disk write failures log a one-shot warn (via redactSecrets) and do NOT
+ * throw to the caller (mirrors credential-pool EC-A pattern).
+ *
+ * Cross-process safety: writes go through `withFileLock` (D61) and use
+ * `atomicWriteJson` (atomic rename). Reads always re-load from disk
+ * inside the lock so concurrent writers don't lose updates (EC-6).
+ *
+ * @internal
+ */
+export {};