integration.lssm-os-state-sqlite

@lssm-tech/integration.lssm-os-state-sqlite

Single-node transactional LSSM OS persistence for Bun SQLite and PGlite. It implements desired/observed state, immutable plans, optimistic executions, append-only receipt chains, idempotency, and lease fencing. Run the exported deterministic migration for the selected driver before constructing adapters.

Lease scopes use the reversible, collision-proof lssm-scope:v1 length-prefixed tuple encoding. Legacy slash-composed keys are rejected rather than guessed or silently re-keyed. Operators upgrading a database containing legacy lease rows must stop workers, explicitly map each row to a reviewed tenant/workspace/environment tuple, and migrate it before enabling this version.

Runtime Node V2

The adapter also persists issued Runtime Node work orders, fenced claim history, externally verified provider receipts, and exact completions. Bun SQLite and PGlite share the same backend-neutral SQL state machine from the runtime while retaining engine-specific transactions and migrations. Existing or partially created schemas are validated before mutation; malformed rows, torn terminal state, fence rewinds, receipt equivocation, and non-canonical timestamps fail closed.

The same migration installs the scoped Runtime Node registry. Registration, heartbeat, attestation, and qualification histories are append-only and tied to an exact registration digest. SQLite serializes writers across adapter instances; PGlite uses the same scope-lock protocol as Postgres. Registration rotation hides prior evidence until the new registration is requalified.

Hook Authority V1

SqlHookAuthorityAdapter is the durable implementation of HookAuthorityPort. createSingleNodeHookAuthorityPort is the production composition helper for a migrated driver plus trusted Connect verifier and live binding resolver; migrateHookAuthorityState is the Hook Authority-only migration entrypoint. The standard migration installs collision-safe scoped sessions, hash-only bearer capabilities, exact replay results, verified active leases and releases, and append-only decision, receipt, outbox, and audit rows. Verifier and live-binding resolver calls run outside database transactions; a short preflight and final authoritative BEGIN IMMEDIATE/PGlite transaction enforce the revision and fence compare-and-swap. Stop terminalization and exact lease releases commit atomically.

The root entry remains runtime-neutral. Bun callers compose createBunSqliteDriver, Node callers pass a node:sqlite DatabaseSync to createNodeSqliteDriver, and PGlite callers use createPgliteDriver. Construct the authority adapter only after migrateSingleNodeState has succeeded; a partial, weakened, or malformed prior Hook Authority schema fails migration closed, including constraint, index, trigger, and PGlite guard-function drift. Session starts require a caller-generated bearer whose SHA-256 commitment is in the signed decision. The raw bearer is delivered only to transition, is never returned by this adapter, and an exact retry after a lost response is safe.

Run bun run pack:verify before publication. It builds and installs the actual npm tarball with its complete local contracts/runtime/spec dependency closure in a clean consumer, verifies the dependency tree, imports every public subpath, and runs real node:sqlite and Bun SQLite migrations from the installed package. Production manifests are materialized only in an isolated staging directory; dependency builds and failed verification cannot rewrite source manifests.

Runtime Topology V1

SqlTopologyStateAdapter is the authoritative T0 topology-state implementation for Bun SQLite, node:sqlite, and PGlite. The standard migration installs the active topology and transition tables and rejects partial or weakened schemas. Qualified topology profiles are seeded explicitly with installActive; an initial transition must be explicitly recorded as observed. All later movement uses compareAndSetTransition, enforces the frozen transition graph, preserves the operation/claim/attempt/fence tuple and completed-step history, and admits exactly one writer under contention.

Every read and write binds the full tenant/workspace/environment/product/ application scope plus topology generation and exact component, capability, adapter, server, and client digests. Cache, broker, controller, or model output cannot create topology authority. This adapter is the embedded T0 reference; PostgreSQL T1 state, transition execution, and optional Redis/broker components are qualified separately.

Embedded Durable Queue V2

SqlEmbeddedQueueAdapter is the recoverable T0 implementation of the frozen Durable Queue V2 port. createSingleNodeEmbeddedQueue requires an exact qualified embedded capability profile and a trusted clock. Admission writes the immutable outbox record and inbox message in one database transaction; claims use monotonic queue fences and visibility leases, renewals are append-only, acknowledgement requires the exact current claim, and restart reconciliation returns the stored admission receipt.

The queue is at-least-once and intentionally remains coordination rather than effect authority. A consumer must reload the signed Runtime Node work order, Connect decision, operation revision, claim, attempt, and work-order fence before executing one effect, durably complete or checkpoint that operation, and only then acknowledge the queue claim. Queue fences never substitute for Runtime Node fences. The embedded buffer is only a wake-up optimization; startup scans the durable rows.

Queue clock regression, partial schemas, malformed stored contracts, scope or profile substitution, replay conflicts, expired leases, stale claims, and direct history/identity mutation fail closed. T1 PostgreSQL will share its operation transaction with the outbox; external Redis Streams, SQS, RabbitMQ, MQTT, and GCP adapters remain later qualified transports.

The adapter also implements the additive fenced claimed-envelope read. It reloads the immutable envelope from SQL only while the exact claim digest, queue fence, and visibility lease remain current. Consumers must still reload Runtime Node order and effect authority before mutation.

V3 Operation State and Atomic Admission

SqlLssmOsOperationStatePortV1 durably implements the Runtime Node V3 operation-state contract for SQLite, node:sqlite, and PGlite. Accepted operations are scoped and idempotent, every transition is version-CAS guarded, only bindExecutionAuthority can introduce the attempt/claim/work-order fence tuple, and terminal receipts commit atomically with the terminal operation revision. Receipts remain dereferenceable only through the full operation scope.

admitOperationAndQueueAtomically creates a pristine accepted operation and its Durable Queue V2 outbox/inbox admission in one database transaction. Exact retries return the durable admission; a prior standalone operation cannot be backfilled and represented as co-atomic. Partial schemas, malformed payloads, tuple forgery, receipt substitution, stale versions, and direct mutation fail closed. This is the T0 admission boundary; a consumer still reloads the signed V3 order and current execution authority before any effect.

T0 Disaster-Recovery Simulation

The package carries a credential-free three-restore simulation for the embedded Bun SQLite topology. Each consecutive serialized snapshot is restored into a fresh database, the complete schema and stored rows are revalidated, and an exact terminal Runtime Node V3 receipt plus signed Hook Authority decision replay are recovered with zero row loss. The test records local restore and reconciliation duration against the v4 RTO and reconciliation ceilings.

This evidence is deliberately simulated. It does not qualify a production backup medium, filesystem crash consistency, remote storage, operator runbook, or live platform RTO. The production three-restore DR requirement therefore remains blocked until those exact-SHA live exercises are recorded.

T0 Concurrency Qualification

bun run qualify:concurrency executes 10,000 consecutive embedded-queue trials. For every durable message, 100 consumers race through the public claim port, exactly one claim is returned, and that exact fenced claim is durably acknowledged before the next trial. Ten fixed 1,000-trial process shards provide independent SQLite state and explicit progress while preserving the exact one-million-attempt total. The command is intentionally separate from the fast unit suite.

This closes the embedded SQLite half of the v4 concurrency matrix only. The production proof remains blocked until the same 10,000-trial qualification is green against real local PostgreSQL at the exact integrated release SHA.

SQLite V3 provider evidence

migrateSqliteV3ProviderReceipts installs additive immutable evidence storage after migrateSingleNodeState. SqliteV3ProviderReceiptPortV1 implements the canonical V3 provider receipt port over the existing SQLite operation authority. It stores the exact standard order and verified receipt, rejects mismatched active execution tuples inside a writer transaction, and preserves exact scoped reads after restart and terminal completion. This explicit adapter supports Bun and node:sqlite; PGlite callers retain their existing qualified compositions.

Compose it with Agent Host's createBuilderV3ReceiptWriter, an authoritative issued-order reader, and the V3 execution service. Receipt storage does not issue orders, verify Connect signatures, authorize dispatch, or establish process custody. No PostgreSQL service is required for this persistence increment. The file-backed SQLite proof uses synthetic order/receipt evidence; a complete local dispatch and issuance composition still requires qualification. See the adapter contract.

SQLite V3 issued authority and standard dispatch

Run migrateSqliteQualificationAuthority after migrateSingleNodeState to install the existing canonical qualification lifecycle in the same SQLite database. SqliteQualificationIssuance requires an explicit trusted clock and Connect verifier. It atomically records both standard and cleanup orders, both pristine reservations, pending cleanup authority and the frozen daily budget. Exact retries while the operation remains accepted replay all records without another charge.

SqliteQualificationDispatch reloads the exact issued standard order and queued operation, verifies Connect outside the transaction, rechecks time and revision, then atomically binds the existing V3 operation claim and consumes its normal reservation. SqliteQualificationOrderReader dereferences either signed order through its full scope and exact reference, including after reopening the file. Supply this reader and SqliteV3ProviderReceiptPortV1 to the existing Agent Host T0 infrastructure; the host's local SQLite Builder child composes both with existing physical process custody. No PostgreSQL server or placeholder order reader is needed for this standard Builder execution path.

The exported classes deliberately implement only issuance and standard dispatch, not the entire qualification authority port. The complete lifecycle composition below adds cleanup dispatch, absence completion and responsibility transfer after an explicit schema upgrade. The evidence extension below adds settlement and unused reservation release; cleanup budget cannot be silently discarded. This slice must not be presented as complete infrastructure-canary lifecycle support. SQLite is trusted single-host owner storage, with explicit schema and row-integrity checks; it does not provide PostgreSQL's independent database-role isolation.

Qualification uses real file-backed SQLite, concurrent connections, storage-failure rollback and a canonical-state comparison against the existing PostgreSQL adapter on PGlite. Those adapter tests use fixture Connect responses and signed artifacts. The integration-owned src/connect-runtime-v3.test.ts additionally consumes real local Ed25519 signatures and durable Connect authority through SQLite issuance and standard dispatch. Run it from this package with bun test ./src/connect-runtime-v3.test.ts; the subprocess creates and removes its own temporary database and receives an empty environment. This composition test belongs here so the provider-neutral Connect package does not import a concrete integration. Production issuer signatures, provider behavior and production backup recovery remain separate evidence. See the authority contract.

SQLite evidence settlement and unused-reservation release

migrateSqliteQualificationEvidence upgrades only the exact recognized issuance schema and preserves existing orders, reservations and active claims. It adds immutable canonical V2 evidence, verifier identity/time and guarded reservation transitions in one transaction. The base migration recognizes and validates the upgraded schema on restart; partial or weakened schemas still fail closed.

SqliteQualificationEvidence implements settleReservationWithEvidence and releaseReservationWithEvidence with an explicit trusted clock, bounded evidence verifier and verifier reference. Settlement moves a dispatched charge into settled EUR micros and retains the unverified remainder as provisional spend. Exact settlement replay requires the same durable evidence and amount. Release requires distinct signed not_applied and terminal_fence records for the exact held reservation/order, including an unused cleanup reserve. Duplicate release returns false, matching the PostgreSQL contract. Frozen daily budget accounting retains the original reserved amounts; neither operation introduces an automatic refund.

Verification happens outside the writer transaction, then scope, order, claim, fence, provider, kind, lifetime and current reservation state are rechecked before evidence and balances commit together. Conflicting evidence IDs, overbilling, stale state/time, unavailable verification and storage failures cannot partially settle or release funds. Reopening validates exact evidence-to-reservation bindings and full budget conservation. The complete lifecycle extension below provides cleanup dispatch, signed absence completion and custody transfer through their dedicated mandatory verifier ports.

The file-backed tests cover concurrent settlement replay, one release winner, restart, previous-schema upgrade, malformed SQL updates and rollback. A separate PostgreSQL/PGlite oracle produces identical canonical reservations, evidence and replay results. Signatures are fixtures; live billing/evidence trust is separate. See the evidence contract.

Complete SQLite V2 qualification lifecycle

migrateSqliteQualificationCleanup upgrades the exact recognized authority/evidence schema without discarding prior orders, charges or released reservations. It adds immutable nonce-bound cleanup permits, original verified observations and custody receipts. Unknown schema drift remains rejected, including case changes inside SQL JSON paths. Existing owner migrations recognize the upgraded schema on reopen.

createSqliteQualificationAuthorityV2 composes all seven canonical V2 methods. It requires connectVerifier, observationVerifier, evidenceVerifier, custodyVerifier, a trusted clock and verifierRef; no verifier has a permissive default. Cleanup dispatch requires independently identified observer and mutator, fresh exact resource/claim/fence evidence and pending issued authority. A writer transaction persists one permit/observation, marks cleanup executing and dispatches the held cleanup reserve. Exact permit replay cannot substitute another nonce, observer attestation or executor. Signed absence marks executing cleanup teardown_verified; billing settlement remains independent and conservative.

Custody transfer requires two distinct verified principals and explicit incident and responsibility-receipt references. It atomically records those approvals and marks cleanup responsibility_transferred. Completed or transferred authority cannot dispatch or transfer again; duplicate completion and transfer return false, matching PostgreSQL. The adapter issues durable permits; it does not itself call providers or treat fixture signatures as live authority.

The canonical V3 order reader also exposes getStandardOrderForOperation for server recovery when only the operation scope/id survived an interrupted response. Exactly one matching standard order must exist; absence or ambiguity returns undefined. Callers never need to mint an order digest or create another binding store.

Real file-backed tests cover permit/custody recovery, concurrent exact replay, observer independence, stale state/time, storage rollback, prior settled-schema upgrade and operation-scoped discovery. The PostgreSQL/PGlite oracle returns the same canonical permits, authority state, evidence, custody receipts and replay outcomes. Production signatures, provider effects and infrastructure isolation still require separate live qualification. See the cleanup contract.