@sema-agent/core-stores-sql

Core's storage seats (EngineStorageBackend: sessions, checkpoints, tool results, session policy, workflow journal, usage windows, background agents, mailbox, roster, file history, and the backend-level managed-retention executor) over one SQL database — PostgreSQL, or the MySQL protocol family (MySQL / InnoDB, MariaDB, TiDB) — to be built by neutral factories over a pool you hand in. Core itself ships only in-memory and file-backed stores, so a database-backed backend is built behind this face rather than inside core. Ships its own types; ES modules only.

Read this first: this release carries no SQL stores

The published versions so far fix the package's public face and how it is built, checked and released; they do not carry the stores yet. createSqlStorageBackend and createSqlDriver check the version pairing, read their options (refusing each wrong value by name) and then refuse — they do not return an object without its stores. Since no driver can be made yet, the backend's last read, the driver, refuses every call (options.driver was not made by createSqlDriver). baselineDdl(dialect) resolves to an empty list and publishedColumns() returns an empty list. A later release fills the face in; a removed or re-kinded name is called out as breaking in the @sema-agent/core release notes, the same as for core's own exports.

How a deployment wires it

One pool, one driver: make the driver once and hand it to the backend and to your own stores.

const driver = createSqlDriver({ dialect: "pg", pool, onFailOpen: (tag, detail) => log.warn(tag, detail) });
const backend = createSqlStorageBackend({
  driver,
  retention: "managed",
  transactionHooks: { retention: { holdLock, liveReferences, beforeDelete, audit }, session: { beforeCommit } },
});
await backend.ensureSchema(); // core's tables first
const conn = await driver.connect();
try {
  await assertCoreSchemaReady(conn, driver.dialect); // the first statement of your own ensure
  // …your own tables, which may reference core's
} finally {
  conn.release();
}

• The driver carries how its connections are initialized and what the engine reported (SqlDriver.facts, and SqlTxConn.facts on each connection), and the one fail-open sink every read of the package reports through; a tag is one word of SQL_FAIL_OPEN_TAGS. The backend takes only a driver createSqlDriver made.
• The hooks (SqlTransactionHooks) are the only way a deployment's tables take part in the backend's transactions; each runs inside the transaction and gets its statement face only (SqlStatementFace).
• The schema of core's tables is the package's: ensureSchema() creates, migrates and checks them under its own lock (SQL_ENSURE_LOCK), records the applied migrations in its own version table (SQL_SCHEMA_VERSION_TABLE) and answers a SqlSchemaReport. Your own ensure runs after it, starts with assertCoreSchemaReady, and uses a lock of its own.
• File-history bytes go to a table of the backend's, or to your object store through fileHistory.blobs (SqlBlobBytesPort: bytes only, under keys the backend mints — whether a blob is there is the backend's index).
• The sweeps (backend.sweep({ nowMs })) are one call your scheduler makes; the receipt counts each leg.

The planned consumer is a deployment that already owns SQL stores: @sema-agent/server re-homing them behind this face is the first use in view (planned, not shipped). It would build the backend from its own pool and hand the result to core's storage seats. Nothing in this package depends on that.

Install

npm install @sema-agent/core @sema-agent/core-stores-sql

Node >= 20.18.1. One entry, .; there are no deep paths. @sema-agent/core is a peer, pinned to the exact version of this package (see Version).

Version

@sema-agent/[email protected] is cut with @sema-agent/[email protected]: the same version number, built from the same commit, and it takes core as an exact peer. Every factory first compares its own version with the version the resolved core reports (CONTRACT_KIT_ENGINE_VERSION) and refuses unless they are equal, character for character. A package version moves with every core release whether or not this package changed.

Exports

Neutral factories and neutral types only. No store class, no dialect class, no SQL statement list, no ensure leg and no SQL predicate generator is exported: the face hands out seats, not classes, and a caller that reached for one of those would be going around the neutral seam. Each name below is a value or a type exported from the package root.

| Group | Names | | --- | --- | | Backend | createSqlStorageBackend SqlStorageBackend SqlStorageBackendOptions SqlSweepLeg SqlSweepReceipt | | Hooks | SqlTransactionHooks SqlStatementFace SqlRetentionOp | | Driver | createSqlDriver SqlDriver SqlTxConn SqlEngineFacts SqlWallSource PgPoolLike MysqlPoolLike | | Fail-open | SQL_FAIL_OPEN_TAGS SqlFailOpenTag SqlFailOpenSink | | Words | SqlDialect SqlEngine | | Schema | assertCoreSchemaReady SQL_ENSURE_LOCK SQL_SCHEMA_VERSION_TABLE SqlSchemaReport baselineDdl publishedColumns PublishedColumn | | File history | SqlBlobBytesPort SqlBlobKey |

SqlDialect is which SQL text is written (pg or mysql; the caller says it). SqlEngine is which engine answered (pg, innodb or tidb; probed, never configured). baselineDdl is the statements a new database is sent, recorded by running the ensure legs; publishedColumns is the readable-column list. PgPoolLike and MysqlPoolLike are structural: a pg.Pool and a mysql2 promise pool satisfy them as they are, and the package depends on neither pg nor mysql2 — the caller owns the pool, the package borrows from it and never ends it.

Building and checking it in this repo

The package imports @sema-agent/core by its public name, so the specifier has to resolve without a registry copy:

• In the repo, @sema-agent/core is the tree's own source: the root tsconfig.json maps it to ./src/index.ts (compilerOptions.paths) and includes packages/*/src, so the root typecheck compiles this package; the test runtime (vitest.config.ts) reads the same paths entry as its alias. Tests for this package live in the root test/ directory.
• Alone, at build time, this package's own tsconfig.json maps @sema-agent/core to the root's built declarations (../../dist/index.d.ts) — the view a consumer of the published package has. Build the root first. The build runs tsc twice, as the root's does: the second pass writes the declarations again with their comments, so the documentation on each exported name ships in the .d.ts.
• The root .npmrc carries one key, legacy-peer-deps=true: without it npm satisfies this package's peer by fetching the published @sema-agent/core into the lockfile (and fails outright once the version is bumped and not yet published). The file carries nothing else; a test refuses any other key.

npm run gate:packages reads the manifest, the export snapshot, the smoke table and the import graph; npm run gate:packages:pack builds the package, packs it, and installs it beside core's own tarball from the same tree in an empty directory.

Release

The package is published with the root, in the same release and from the same commit:

• from a plain clone of the tag, not a worktree, with gitHead written into its manifest for the publish and restored after — a workspace package directory has no .git, so npm cannot read it there;
• its version and its exact peerDependencies["@sema-agent/core"] move with the root's in the same commit (scripts/bump-version.mjs);
• the tarball holds package.json, this README, LICENSE and dist/ and nothing else; LICENSE is a byte copy of the root file, whose Licensed Work parameters name this package;
• each release owes a wire-changes/core-stores-sql@<version>.json manifest beside the root's, and the registry is checked for the package before the release counts as shipped.

License

Business Source License 1.1, the same terms as @sema-agent/core.