@theokit/sdk 4.53.0 → 4.54.0

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

@@ -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/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-dir.d.cts

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

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

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

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.
  *
@@ -88,4 +81,24 @@ export interface SessionWriterLease {
  * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.
  */
 export declare const HEARTBEAT_WINDOW_MS = 30000;
+/**
+ * Does the session have a writer **right now**? A query that does NOT take the lease.
+ *
+ * M95 — it exists because asking by taking creates the very contention it meant to detect: two
+ * processes querying a **free** session at the same time made one of them lose, and the consumer
+ * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.
+ *
+ * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take
+ * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to
+ * **decide an id before opening anything** use this, and handle the race where it shows up.
+ *
+ */
+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.
  *
@@ -88,4 +81,24 @@ export interface SessionWriterLease {
  * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.
  */
 export declare const HEARTBEAT_WINDOW_MS = 30000;
+/**
+ * Does the session have a writer **right now**? A query that does NOT take the lease.
+ *
+ * M95 — it exists because asking by taking creates the very contention it meant to detect: two
+ * processes querying a **free** session at the same time made one of them lose, and the consumer
+ * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.
+ *
+ * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take
+ * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to
+ * **decide an id before opening anything** use this, and handle the race where it shows up.
+ *
+ */
+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;