@m4ike1/ion-session-backend-sqlite-node

SQLite session storage backend for @m4ike1/ion-agent-core, built on node:sqlite (node >= 22.19).

import { BACKGROUND_CONTEXT } from "@m4ike1/ion-agent-core";
import {
  createNodeSqliteFactory,
  SqliteSessionRepo,
} from "@m4ike1/ion-session-backend-sqlite-node";

const repository = new SqliteSessionRepo({
  directory: "/var/lib/ion/sessions",
  databaseFactory: createNodeSqliteFactory(),
});

const session = await repository.create({}, BACKGROUND_CONTEXT);
const main = await session.createBranch("main", null, BACKGROUND_CONTEXT);
await main.appendMessage(
  { role: "user", content: "hello", timestamp: Date.now() },
  BACKGROUND_CONTEXT,
);
await session.close(BACKGROUND_CONTEXT);
await repository.close(BACKGROUND_CONTEXT);

Layout

• Default: one file per session under directory. Safe IDs ([A-Za-z0-9_-]+) map to {sessionId}.sqlite; all other IDs use a ~-prefixed base64url encoding of the UTF-16LE bytes. The durable session ID is unchanged; metadata.path carries the canonical physical path.
• databasePath option: store multiple sessions in one shared container. Its parent directory is created on demand.

Lifecycle and ownership

• open() and delete() reject metadata whose path is outside the configured repository, and never create a missing database.
• list() is read-only and best-effort: corrupt files, version mismatches, and unrelated *.sqlite files are skipped.
• One writable owner per session is the host's responsibility. The repo rejects overlapping local create/open/fork/delete for one ID but provides no cross-process lease, lock, fence, heartbeat, or takeover. Close a worker before deletion.
• fork() of a source open in the same repo queues its snapshot on that source's commit queue. Any other source uses an independent read-only connection with one deferred WAL transaction; later worker commits may land while the snapshot is open. Forks copy entries and scalar/list values, not usage ledger rows.
• repository.close() waits for every open session cleanup attempt before reporting errors (single error rethrown, multiple aggregated).
• No search service or FTS index is exported; search is a separate projection.

Further reading

• Setup and tasks — layout choice, open/list/delete/fork recipes, custom factories, shutdown order.
• Reference — public API: repo, sessions, factory, database capability, sql helper, constants.
• Concepts — file layout and ID encoding, ownership model, fork snapshots, version gate, schema.