@theokit/sdk 4.53.1 → 4.55.0

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

@@ -10,4 +10,218 @@
  *
  * @internal
  */
-export {};
+/**
+ * The three `better-sqlite3` methods this module actually uses, declared structurally so nothing
+ * here imports the driver.
+ *
+ * A real `better-sqlite3` `Database` satisfies it. `pragma` is called both to read
+ * (`pragma("user_version", { simple: true })`, which must return the number itself rather than a
+ * row array) and to write (`pragma("user_version = N")`). `transaction` must return a function
+ * that, when called, runs the wrapped body inside a real SQLite transaction and rolls it back if
+ * the body throws — a stub that merely calls through gives `migrateSchema` no atomicity, and a
+ * half-applied migration is exactly what it exists to prevent.
+ *
+ * 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 interface SqliteLike {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+    exec: (sql: string) => void;
+    transaction: <Args extends unknown[], R>(fn: (...args: Args) => R) => (...args: Args) => R;
+}
+/**
+ * One forward migration step.
+ *
+ * `up` runs inside the shared transaction and must be self-contained: it may not commit, and any
+ * error it throws aborts the whole run and rolls back every step in it, including the ones that
+ * already succeeded. `user_version` is set to `toVersion` immediately after `up` returns, inside
+ * the same transaction, so version and schema move together or not at all.
+ *
+ * `toVersion` is the version the database reaches, not the one it starts from. Steps are ordered
+ * by it, gaps are allowed, and two steps sharing a `toVersion` both run — nothing deduplicates
+ * them.
+ *
+ * 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 interface Migration {
+    toVersion: number;
+    up: (db: SqliteLike) => void;
+}
+/**
+ * Arguments to `migrateSchema`.
+ *
+ * `currentVersion` is the version the code expects, and it is the ceiling: a migration whose
+ * `toVersion` exceeds it is left unapplied for a later release. `migrations` may be given in any
+ * order and may contain steps already applied — both are filtered and sorted here. `label` only
+ * ever appears in the downgrade error message.
+ *
+ * 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 interface MigrateSchemaOptions {
+    db: SqliteLike;
+    currentVersion: number;
+    migrations: ReadonlyArray<Migration>;
+    /** For log/error context (e.g., "memory-index", "registry"). */
+    label?: string;
+}
+/**
+ * What `migrateSchema` did.
+ *
+ * `from` is the `user_version` found on the database, `to` is the version it holds afterwards,
+ * and `ran` is how many steps executed. When nothing was pending, `to === from` and `ran === 0`.
+ *
+ * `to` is the `toVersion` of the last step applied, NOT `currentVersion`. A database at version 3
+ * against `currentVersion: 5` with no migration in that range comes back as
+ * `{ from: 3, to: 3, ran: 0 }` — the gap is reported, not closed. Comparing `to` with
+ * `currentVersion` is how a caller notices that the migration list is missing a step.
+ *
+ * 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 interface MigrateSchemaResult {
+    from: number;
+    to: number;
+    ran: number;
+}
+/**
+ * Bring a SQLite database's `user_version` up to `currentVersion` by running the steps that sit
+ * between the two.
+ *
+ * Steps are sorted ascending by `toVersion` and filtered to `> stored && <= currentVersion`, then
+ * run in that order inside ONE transaction: each `up` is followed immediately by the matching
+ * `user_version` write. Either every step in the run commits or none does — a step that throws
+ * aborts the transaction, propagates the error, and leaves the database at the version it started
+ * from. There is no partially-migrated state and no resume point.
+ *
+ * Forward-only. When the stored version is greater than `currentVersion` — an older build opening
+ * a database a newer one already migrated — this throws immediately, before touching anything,
+ * with a message naming both versions and `label`. Nothing downgrades, and no data is deleted on
+ * any path here; what a step does is the step's own business.
+ *
+ * A stored version equal to `currentVersion` returns without opening a transaction. A `user_version`
+ * that is absent or not a number is read as 0, so a fresh database runs every step.
+ *
+ * Concurrency: the SQLite transaction is the only serialization. This takes no file lock, so two
+ * processes migrating the same file at once are arbitrated by SQLite's own write lock — the loser
+ * gets a busy or locked error from the driver, not a queued turn. Wrap the call in `withFileLock`
+ * if that matters.
+ *
+ * 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 migrateSchema(opts: MigrateSchemaOptions): MigrateSchemaResult;
+/**
+ * The on-disk envelope: the payload under `data`, its schema version alongside it.
+ *
+ * `writeVersionedJson` always produces this shape. `readVersionedJson` reads it, but tolerates a
+ * file that is not in it — a legacy object with no `_schemaVersion` is treated as version 0 and
+ * handed to the migrate callback whole, so this type describes what is written, not everything
+ * that can be read.
+ *
+ * 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 interface VersionedJsonFile<T> {
+    _schemaVersion: number;
+    data: T;
+}
+/**
+ * Upgrade callback for `readVersionedJson`, invoked only when the stored version is BELOW the
+ * current one.
+ *
+ * `parsed` is the whole parsed JSON value, not `parsed.data`. That is deliberate: a legacy file
+ * predating the envelope has its fields at the top level, and a callback handed only `.data`
+ * would receive `undefined` for exactly the files that need migrating. It is typed `unknown`
+ * because nothing has validated it — narrow before reading.
+ *
+ * `fromVersion` is the `_schemaVersion` found on disk, or 0 when the field is missing or not a
+ * number.
+ *
+ * The return value is used as-is and is NOT written back; the file on disk still holds the old
+ * shape until someone calls `writeVersionedJson`. Throwing here propagates out of
+ * `readVersionedJson`, which otherwise never throws — return the default value instead if an
+ * unmigratable file should be survivable.
+ *
+ * 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 type VersionedJsonMigrate<T> = (parsed: unknown, fromVersion: number) => T;
+/**
+ * Arguments to `readVersionedJson`.
+ *
+ * `defaultValue` is a factory rather than a value because it is called on several paths and each
+ * caller must get its own object — returning a shared mutable default would let one caller's
+ * edits appear in another's. It is called for a missing file, an unreadable one, a corrupt one,
+ * a non-object payload, and a file written by a newer version.
+ *
+ * `migrate` is called only for a stored version strictly below `currentVersion`.
+ *
+ * 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 interface ReadVersionedJsonOptions<T> {
+    path: string;
+    currentVersion: number;
+    migrate: VersionedJsonMigrate<T>;
+    defaultValue: () => T;
+}
+/**
+ * Read a versioned JSON file, migrating or falling back rather than failing.
+ *
+ * What comes back, by case:
+ *
+ *   - version matches `currentVersion` — the file's `data` field, returned as `T` WITHOUT
+ *     validation. A file whose envelope is right but whose payload is not gets through.
+ *   - version below `currentVersion` — whatever `migrate(parsed, stored)` returns. The migrated
+ *     value is not persisted; the file is untouched.
+ *   - version above `currentVersion` — `defaultValue()`, plus a warning. Forward-only: a file
+ *     written by a newer build is left alone rather than downgraded.
+ *   - file missing, or unreadable for any other reason (permissions, a directory in its place) —
+ *     `defaultValue()`, silently. Absence and denial are not distinguished.
+ *   - file present but not valid JSON — `defaultValue()`, and the file is RENAMED to
+ *     `<path>.corrupt.<epoch-ms>` so the next run starts clean and the bad bytes stay available.
+ *     A rename that itself fails is warned about and the read still returns the default, which
+ *     means the same corrupt file will be met again next time.
+ *   - JSON that parses to a non-object (a number, a string, `null`) — `defaultValue()`, silently
+ *     and without moving the file aside.
+ *
+ * The only ways this throws are through the callbacks you supply: `migrate` or `defaultValue`
+ * raising. Nothing else here rejects.
+ *
+ * There is no locking. A concurrent `writeVersionedJson` on the same path is atomic at the rename,
+ * so a reader sees either the old file or the new one, never a half-written one — but a
+ * read-modify-write built from this pair is NOT atomic across the two calls, and needs
+ * `withFileLock` around both.
+ *
+ * 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 readVersionedJson<T>(opts: ReadVersionedJsonOptions<T>): Promise<T>;
+/**
+ * Write `data` wrapped in the version envelope, replacing the file atomically.
+ *
+ * The bytes go to a temp file in the same directory and are moved into place with `rename`, so a
+ * crash or a concurrent reader never observes a partial file: the path holds either the previous
+ * content or the complete new content. Parent directories are created as needed, and the file is
+ * created with mode 0600 (subject to the process umask), formatted with two-space indentation and
+ * a trailing newline.
+ *
+ * `currentVersion` is stamped verbatim as `_schemaVersion`; nothing checks it against what was
+ * already on disk, so this will happily overwrite a newer file with an older version. Read first
+ * if that matters.
+ *
+ * Rejects when `data` cannot be serialized — a circular reference, or a `toJSON` that throws.
+ * Serialization happens before any filesystem call, so on that path no directory is created, no
+ * temp file exists, and the file already on disk is untouched.
+ *
+ * Atomicity is the rename's, so it is as strong as the filesystem's: on NFS, SMB or FUSE the
+ * underlying writer emits a one-shot warning that the guarantee is weaker there.
+ *
+ * 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 writeVersionedJson<T>(path: string, data: T, currentVersion: number): Promise<void>;

package/dist/internal/persistence/session-writer.d.cts

@@ -57,13 +57,6 @@ export interface SessionWriterLease {
      */
     renew(): void;
 }
-/**
- * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
- *
- * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the
- * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across
- * processes, not just across async tasks in one process.
- */
 /**
  * Staleness window **between machines** — and only between them.
  *
@@ -101,4 +94,11 @@ export declare const HEARTBEAT_WINDOW_MS = 30000;
  *
  */
 export declare function sessionHasWriter(sessionPath: string): boolean;
+/**
+ * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
+ *
+ * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the
+ * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across
+ * processes, not just across async tasks in one process.
+ */
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

package/dist/internal/persistence/session-writer.d.ts

@@ -57,13 +57,6 @@ export interface SessionWriterLease {
      */
     renew(): void;
 }
-/**
- * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
- *
- * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the
- * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across
- * processes, not just across async tasks in one process.
- */
 /**
  * Staleness window **between machines** — and only between them.
  *
@@ -101,4 +94,11 @@ export declare const HEARTBEAT_WINDOW_MS = 30000;
  *
  */
 export declare function sessionHasWriter(sessionPath: string): boolean;
+/**
+ * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
+ *
+ * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the
+ * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across
+ * processes, not just across async tasks in one process.
+ */
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

package/dist/internal/persistence/sqlite-cas.d.cts

@@ -20,6 +20,42 @@
  * loops). Helper does NOT cache prepared statements — `better-sqlite3`
  * caches internally; SDK use is one-shot per mutation, not hot loops.
  *
- * @internal
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
  */
+import type Database from "better-sqlite3";
+type DatabaseInstance = InstanceType<typeof Database>;
+/**
+ * Run an UPDATE and report whether it changed exactly the number of rows you expected — the
+ * optimistic-concurrency equivalent of taking a lock.
+ *
+ * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the
+ * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This
+ * function generates nothing. It prepares the statement, runs it with `params`, and compares
+ * `changes` against `expectedChanges` (default 1).
+ *
+ * `false` means the guard did not match — someone else moved the row first, or the id does not
+ * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.
+ * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with
+ * whatever backoff it wants. There is no retry loop hidden in here, by design.
+ *
+ * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.
+ * Only the row-count mismatch is reported as `false`.
+ *
+ * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap
+ * the call yourself when the swap has to commit together with other writes.
+ *
+ * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser
+ * finds out immediately and decides what to do. Prefer it when the contended state is already a
+ * row with a version column. When the contended state is a FILE, there is no version column to
+ * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is
+ * to create something exactly once rather than update it, `createExclusive` is the primitive.
+ *
+ * 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 casUpdate(db: DatabaseInstance, sql: string, params: ReadonlyArray<unknown>, expectedChanges?: number): boolean;
 export {};

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

@@ -20,6 +20,42 @@
  * loops). Helper does NOT cache prepared statements — `better-sqlite3`
  * caches internally; SDK use is one-shot per mutation, not hot loops.
  *
- * @internal
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
  */
+import type Database from "better-sqlite3";
+type DatabaseInstance = InstanceType<typeof Database>;
+/**
+ * Run an UPDATE and report whether it changed exactly the number of rows you expected — the
+ * optimistic-concurrency equivalent of taking a lock.
+ *
+ * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the
+ * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This
+ * function generates nothing. It prepares the statement, runs it with `params`, and compares
+ * `changes` against `expectedChanges` (default 1).
+ *
+ * `false` means the guard did not match — someone else moved the row first, or the id does not
+ * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.
+ * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with
+ * whatever backoff it wants. There is no retry loop hidden in here, by design.
+ *
+ * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.
+ * Only the row-count mismatch is reported as `false`.
+ *
+ * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap
+ * the call yourself when the swap has to commit together with other writes.
+ *
+ * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser
+ * finds out immediately and decides what to do. Prefer it when the contended state is already a
+ * row with a version column. When the contended state is a FILE, there is no version column to
+ * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is
+ * to create something exactly once rather than update it, `createExclusive` is the primitive.
+ *
+ * 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 casUpdate(db: DatabaseInstance, sql: string, params: ReadonlyArray<unknown>, expectedChanges?: number): boolean;
 export {};

package/dist/internal/persistence/sqlite-open.d.cts

@@ -23,6 +23,20 @@ export interface ResilientSqliteDb {
     exec(sql: string): void;
     close(): void;
 }
+/**
+ * Input to {@link openSqliteResilient}.
+ *
+ * The trap is `recoverCorrupt`, whose default is ON. When the driver reports a corrupt or encrypted
+ * database, the file is renamed aside and a FRESH one is opened — so the call SUCCEEDS and hands
+ * back an EMPTY database. The old bytes survive on disk under the renamed path, but a caller that
+ * treats a resolved promise as "my data is here" is wrong exactly when it matters. Pass
+ * `recoverCorrupt: false` to get the corruption error thrown instead.
+ *
+ * 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.
+ *
+ * @typeParam T - the concrete DB handle the driver returns; defaults to {@link ResilientSqliteDb}
+ */
 export interface OpenSqliteResilientOptions<T extends ResilientSqliteDb> {
     /** Absolute path to the SQLite file. Parent directories are created. */
     filePath: string;

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

@@ -23,6 +23,20 @@ export interface ResilientSqliteDb {
     exec(sql: string): void;
     close(): void;
 }
+/**
+ * Input to {@link openSqliteResilient}.
+ *
+ * The trap is `recoverCorrupt`, whose default is ON. When the driver reports a corrupt or encrypted
+ * database, the file is renamed aside and a FRESH one is opened — so the call SUCCEEDS and hands
+ * back an EMPTY database. The old bytes survive on disk under the renamed path, but a caller that
+ * treats a resolved promise as "my data is here" is wrong exactly when it matters. Pass
+ * `recoverCorrupt: false` to get the corruption error thrown instead.
+ *
+ * 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.
+ *
+ * @typeParam T - the concrete DB handle the driver returns; defaults to {@link ResilientSqliteDb}
+ */
 export interface OpenSqliteResilientOptions<T extends ResilientSqliteDb> {
     /** Absolute path to the SQLite file. Parent directories are created. */
     filePath: string;

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

@@ -1,3 +1,47 @@
+/**
+ * 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.
+ *
+ * This block is the MODULE header and must stay at offset 0. Sitting below the import it became a
+ * leading comment of the first declaration instead, which is how its tag deleted `PragmaCapable`
+ * from the emitted `.d.ts` while `applyWalWithFallback` — which names it — survived.
+ */
+/**
+ * The narrow slice of a SQLite handle this module needs: anything with a `pragma()` method, which
+ * `better-sqlite3` satisfies without being named here.
+ *
+ * Not exported, but it appears in the signature of `applyWalWithFallback`, so it is emitted into
+ * the published declarations and a consumer can structurally satisfy it.
+ */
+interface PragmaCapable {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+}
+/**
+ * What journal mode a connection ended up in after `applyWalWithFallback`.
+ *
+ * `mode` is the mode actually in effect, never the one that was requested. `fellBack` is `true`
+ * only when WAL was attempted and refused — either the pragma threw or it reported a mode other
+ * than `wal` — and the connection was put into DELETE instead.
+ *
+ * `fellBack: true` is normal on NFS, SMB and FUSE, where WAL needs shared memory the filesystem
+ * does not provide. It is not an error and nothing further is required of the caller; the
+ * consequence is slower concurrent access, since DELETE mode does not allow readers alongside a
+ * writer. Treat it as a signal about the storage, not about the database.
+ *
+ * @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 WalApplyResult {
+    /** Final journal_mode actually in effect. */
+    mode: "wal" | "delete";
+    /** True if we wanted WAL but the filesystem refused. */
+    fellBack: boolean;
+}
 /**
  * Apply WAL mode with DELETE fallback. Idempotent — safe to call multiple
  * times on the same connection.
@@ -7,3 +51,4 @@
  *
  */
 export declare function applyWalWithFallback(db: PragmaCapable, label: string): WalApplyResult;
+export {};

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

@@ -1,3 +1,47 @@
+/**
+ * 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.
+ *
+ * This block is the MODULE header and must stay at offset 0. Sitting below the import it became a
+ * leading comment of the first declaration instead, which is how its tag deleted `PragmaCapable`
+ * from the emitted `.d.ts` while `applyWalWithFallback` — which names it — survived.
+ */
+/**
+ * The narrow slice of a SQLite handle this module needs: anything with a `pragma()` method, which
+ * `better-sqlite3` satisfies without being named here.
+ *
+ * Not exported, but it appears in the signature of `applyWalWithFallback`, so it is emitted into
+ * the published declarations and a consumer can structurally satisfy it.
+ */
+interface PragmaCapable {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+}
+/**
+ * What journal mode a connection ended up in after `applyWalWithFallback`.
+ *
+ * `mode` is the mode actually in effect, never the one that was requested. `fellBack` is `true`
+ * only when WAL was attempted and refused — either the pragma threw or it reported a mode other
+ * than `wal` — and the connection was put into DELETE instead.
+ *
+ * `fellBack: true` is normal on NFS, SMB and FUSE, where WAL needs shared memory the filesystem
+ * does not provide. It is not an error and nothing further is required of the caller; the
+ * consequence is slower concurrent access, since DELETE mode does not allow readers alongside a
+ * writer. Treat it as a signal about the storage, not about the database.
+ *
+ * @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 WalApplyResult {
+    /** Final journal_mode actually in effect. */
+    mode: "wal" | "delete";
+    /** True if we wanted WAL but the filesystem refused. */
+    fellBack: boolean;
+}
 /**
  * Apply WAL mode with DELETE fallback. Idempotent — safe to call multiple
  * times on the same connection.
@@ -7,3 +51,4 @@
  *
  */
 export declare function applyWalWithFallback(db: PragmaCapable, label: string): WalApplyResult;
+export {};

package/dist/internal/persistence/transcript-ops.d.cts

@@ -70,7 +70,6 @@ export declare function forkTranscript(src: string, dst: string, options?: ForkT
 export interface ReadJsonlTailOptions {
     /** Maximum records to return, counted from the END. */
     readonly maxRecords?: number;
-    /** Stop once a line contains this marker (exclusive). */
     /**
      * Start the window AFTER the last record whose `subtype` (or `type`) equals this.
      *
@@ -81,4 +80,11 @@ export interface ReadJsonlTailOptions {
     /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */
     readonly _stats?: boolean;
 }
+/**
+ * Read the LAST records of a JSONL file without loading the whole thing.
+ *
+ * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session
+ * transcript grows without bound; loading megabytes to show the last three turns is the cost this
+ * exists to avoid — and a `slice` over a full read would be that same cost with a better name.
+ */
 export declare function readJsonlTail<T = Record<string, unknown>>(path: string, options?: ReadJsonlTailOptions): T[];

package/dist/internal/persistence/transcript-ops.d.ts

@@ -70,7 +70,6 @@ export declare function forkTranscript(src: string, dst: string, options?: ForkT
 export interface ReadJsonlTailOptions {
     /** Maximum records to return, counted from the END. */
     readonly maxRecords?: number;
-    /** Stop once a line contains this marker (exclusive). */
     /**
      * Start the window AFTER the last record whose `subtype` (or `type`) equals this.
      *
@@ -81,4 +80,11 @@ export interface ReadJsonlTailOptions {
     /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */
     readonly _stats?: boolean;
 }
+/**
+ * Read the LAST records of a JSONL file without loading the whole thing.
+ *
+ * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session
+ * transcript grows without bound; loading megabytes to show the last three turns is the cost this
+ * exists to avoid — and a `slice` over a full read would be that same cost with a better name.
+ */
 export declare function readJsonlTail<T = Record<string, unknown>>(path: string, options?: ReadJsonlTailOptions): T[];

package/dist/internal/plugins/types.d.cts

@@ -11,7 +11,7 @@
  * @public
  */
 import type { Plugin as PluginType } from "../../types/plugin.js";
-export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
+export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
 export type Plugin = PluginType;
 /**
  * Identity helper for plugin authors. TS-only convenience — preserves

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

@@ -11,7 +11,7 @@
  * @public
  */
 import type { Plugin as PluginType } from "../../types/plugin.js";
-export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
+export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
 export type Plugin = PluginType;
 /**
  * Identity helper for plugin authors. TS-only convenience — preserves

package/dist/internal/providers/builtin/openai-chatgpt.d.ts

@@ -1,2 +1,14 @@
+/**
+ * M43 — the ChatGPT "Codex" backend as a first-class builtin `ProviderProfile`. Migrated from the
+ * agent-builder M40 workaround; the SDK now owns the provider, so a consumer only selects
+ * `openai-chatgpt/<model>` and logs in — ZERO provider logic in the consumer.
+ *
+ * The provider-auth model (see the codex-provider-in-sdk blueprint):
+ * - static profile + a `transform.fetch` that resolves the LIVE credential per HTTP request (fresh Bearer +
+ *   dynamic `ChatGPT-Account-Id`), so a mid-turn expiry refreshes transparently with NO agent rebuild;
+ * - the protocol values (endpoint, models, oauth config, `originator` header) are SDK-owned constants.
+ *
+ * @internal
+ */
 import type { ProviderProfile } from "../types.js";
 export declare const OPENAI_CHATGPT: ProviderProfile;

package/dist/internal/providers/catalog-loader.d.ts

@@ -38,6 +38,14 @@ export interface CatalogEntry {
      */
     models?: Record<string, CatalogModel>;
 }
+/**
+ * Look up per-model catalog data by `provider/model` key.
+ *
+ * Semver-exempt: not declared in `package.json` `exports`, but re-exported by
+ * `catalog-source-models-dev.ts`, whose declaration is reachable from published entries — so it
+ * must be EMITTED.
+ */
+export declare function getCatalogModelInfo(key: string): CatalogModel | undefined;
 interface LoadOptions {
     _testInjectMalformed?: boolean;
 }