integration.agent-durable-store

@lssm-tech/integration.agent-durable-store

Durable implementations of @lssm-tech/lib.ai-agent's AgentSessionStore and AgentCheckpointPort. Choose embedded SQLite for a single durable worker or a provider-neutral Postgres adapter for horizontally scaled runtimes.

SQLite

import {
  createSqliteAgentCheckpointStore,
  createSqliteAgentSessionStore,
} from "@lssm-tech/integration.agent-durable-store";

const sessions = createSqliteAgentSessionStore({ file: "./agent.db" });
const checkpoints = createSqliteAgentCheckpointStore({ file: "./agent.db" });

Both factories accept the same file and can share one database file. Pass createSqliteAgentSessionStore({ file }) wherever new InMemorySessionStore() is currently constructed.

Each SQLite store also exposes close() (typed SqliteDurableStoreLifecycle), which releases its database handle. Close every store opened on a file before deleting it: Windows refuses to remove a database that still has an open handle (EBUSY/EPERM). close() is idempotent; using a closed store throws.

Durability

The database opens in WAL journal mode with synchronous = NORMAL, so a committed write is recoverable after a hard process kill. A fresh process pointed at the same file recovers the last committed session and checkpoint — see src/sqlite/process-death.test.ts (agent runtime conformance case 5).

Effect-replay safety

AgentCheckpointEnvelope.effectResults (keyed by ${nonce}:${stepInstanceId}) is persisted verbatim, so approval-gated side-effecting steps replay their recorded result on resume instead of re-firing. The dedup/replay logic lives in @lssm-tech/integration.workflow-devkit; this package only persists the field.

Postgres

The Postgres adapter accepts the repository's DatabaseProvider port, so the same store works with Supabase Postgres, self-hosted Postgres, Railway Postgres, or another compatible provider.

import { SupabasePostgresProvider } from "@lssm-tech/integration.provider-supabase";
import {
  createPostgresAgentCheckpointStore,
  createPostgresAgentSessionStore,
  migratePostgresAgentDurableStore,
} from "@lssm-tech/integration.agent-durable-store/postgres";

const database = new SupabasePostgresProvider({
  connectionString: process.env.SUPABASE_DATABASE_URL,
});

await migratePostgresAgentDurableStore(database);

const sessions = createPostgresAgentSessionStore({
  database,
  tenantId: "tenant-123",
});
const checkpoints = createPostgresAgentCheckpointStore({
  database,
  tenantId: "tenant-123",
});

Each store instance is bound to one non-empty tenant identifier. Every query includes that scope, persisted payloads are checked against it, session writes use optimistic revisions, and message/step histories are bounded. The adapter does not make deployment-specific security promises: the host remains responsible for credentials, TLS, database roles and RLS, backups, retention, regional placement, and tested RPO/RTO.

The same Postgres entrypoint also exposes durable stores for multiplayer collaboration sessions/events, governed improvement work orders, and tamper-evident audit events. Audit records form a per-tenant hash chain and support head verification; every adapter remains tenant-bound and uses optimistic concurrency where the domain contract requires it.

import {
  createPostgresAgentAuditStore,
  createPostgresCollaborationStore,
  createPostgresImprovementWorkOrderStore,
  createPostgresImprovementWorkOrderStoreV2,
} from "@lssm-tech/integration.agent-durable-store/postgres";

const collaboration = createPostgresCollaborationStore({
  database,
  tenantId: "tenant-123",
});
const improvement = createPostgresImprovementWorkOrderStore({
  database,
  tenantId: "tenant-123",
});
const adaptiveImprovement = createPostgresImprovementWorkOrderStoreV2({
  database,
  tenantId: "tenant-123",
});
const audit = createPostgresAgentAuditStore({
  database,
  tenantId: "tenant-123",
});

Call the migration through a serialized deployment step before serving traffic. Use a shared external Postgres service for multiple workers; do not place the SQLite file on an ephemeral or multi-writer filesystem.

The V2 improvement store uses the same table with an explicit contract-version discriminator. V1 and V2 queries are isolated, CAS remains revision-bound, and due observing work survives process restarts without duplicate scheduling.

Governed self-improvement lifecycle

migratePostgresSelfImprovementStore creates tenant/workspace-scoped program, candidate, signal, and append-only lifecycle tables. By default, the migration applies and forces database-enforced tenant and workspace policies for least-privilege runtime roles. Every repository transaction establishes both claims locally before querying. createPostgresSelfImprovementStores returns typed program, candidate, and signal ports. Candidate transitions are fenced by their previous status, state digest, and timestamp, so duplicate identifiers and stale, reordered, invalid, non-monotonic, or tampered receipts are rejected transactionally.

The candidate store also implements SelfImprovementLifecycleStorePortV1. Call state(id) to obtain the fenced status, digest, sequence, and immutable initial state, and receipts(id) to load the ordered append-only chain for exact replay. These reads remain tenant/workspace scoped and do not grant execution authority.

The returned program, candidate, and signal stores also implement the additive query ports. Lists are deterministic, tenant/workspace scoped, and bounded to 500 records per request. Candidate list results overlay the current fenced status on the immutable candidate document; they do not rewrite its canonical fingerprint or lifecycle receipts.

Protocol artifact persistence

migratePostgresAgentProtocolArtifactStore creates tenant-, space-, product-, application-, purpose-, session-, run-, kind-, and artifact-scoped head and append-only revision tables. createPostgresAgentProtocolArtifactStore stores context manifests, model capability profiles, routes, qualifications, evaluation decisions, canary states, selections, fallback decisions, execution plans, plan validations, run budgets, bounded epochs, checkpoints, progress, reflections, help requests, help responses, context projections, task graphs, delegations, task results, team syntheses, immutable Agent Host application bindings, terminal decisions, protocol run state, memory proposals, owner decisions, mutation receipts, projections, projection revocations, automation definitions, previews, materializations, lifecycle transitions, claims, run receipts, and follow-ups without gaining execution authority.

Every write binds the contract identity digest to the payload, computes an independent canonical payload digest, rejects raw credential fields and common credential values, and uses optimistic revisions. Context manifests, routes, selections, evaluation decisions, and fallback decisions are immutable and idempotent. Model qualification and canary records evolve only through append-only CAS revisions. Epoch and run-state records also evolve through append-only CAS. Automation lifecycle state is the only mutable automation artifact and also evolves through append-only CAS; its definitions, previews, materializations, transitions, claims, receipts, and follow-ups are immutable. Every other execution artifact is immutable. Reads revalidate both digests before returning data. Protocol state binds the exact historical epoch revision and digest, so a crash after an epoch write but before the state commit can retry idempotently without accepting substituted work.

The migration enables and forces RLS by default and scopes policies to transaction-local tenant and space settings. The runtime still includes exact scope predicates on every query. For Supabase, keep these tables server-side, do not grant browser roles access, and pass only opaque secretRef values—never database URLs, provider keys, access tokens, or refresh tokens.

Founder-operations stores

migratePostgresFounderOpsStore (migration founder-ops-v1) creates three tenant-scoped tables: agent_supervised_coding_sessions, agent_proactive_proposals and agent_workflow_improvement_briefs. Table names and the schema are configurable, and the usual role grants and tenant RLS options apply. Run it as a serialized deployment step after the existing agent migrations. The tables do not depend on earlier agent tables.

The stores are structurally typed. The owning module supplies a codec that validates every payload read back, so this integration never imports a product module:

import {
  createPostgresProactiveProposalLedger,
  createPostgresSupervisedCodingSessionStore,
  createPostgresWorkflowImprovementBriefStore,
  migratePostgresFounderOpsStore,
} from "@lssm-tech/integration.agent-durable-store/postgres";
import {
  proactiveLedgerRecordCodecV1,
  supervisedCodingSessionCodecV1,
  workflowImprovementBriefCodecV1,
} from "@lssm-tech/module.agent-fleet/core";

await migratePostgresFounderOpsStore(database);
const sessions = createPostgresSupervisedCodingSessionStore({
  database,
  tenantId,
  codec: supervisedCodingSessionCodecV1,
});

Session and ledger compareAndSet calls require next.revision to be exactly expectedRevision + 1 and update only when the stored revision matches. This means concurrent supervisors apply a coding-wait answer exactly once. Briefs keep the first write, so a frozen success criterion cannot be replaced.