{"id":"@lssm-tech/integration.lssm-os-state-postgres","slug":"integration.lssm-os-state-postgres","name":"@lssm-tech/integration.lssm-os-state-postgres","version":"2.0.5","path":"packages/integrations/lssm-os-state-postgres","manifestPath":"packages/integrations/lssm-os-state-postgres/package.json","manifestBlobSha":"0300ef89d852d4789f3123c0676420f426e93ec7","layer":"integrations","physicalArea":null,"primaryArea":"delivery-and-infrastructure","classification":{"privateDeclared":null,"catalogFamily":"integrations","catalogKind":"integration","catalogStatus":"active","adoptionMode":"adoptable","stability":"experimental"},"description":"Multi-node tenant-scoped Postgres and Supabase state adapters for LSSM OS.","descriptionOrigin":"package.json","catalog":{"family":"integrations","kind":"integration","status":"active","adoptionMode":"adoptable","stability":"experimental","platforms":["server"],"runtimes":["bun","node"],"entrypoints":[".","./migrations","./agent-application-lifecycle","./agent-application-lifecycle-migration"],"documentation":[{"title":"Integration Lssm Os State Postgres documentation","url":"https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-state-postgres","kind":"readme"}],"examples":[],"replacements":[],"capabilities":[{"id":"package.lssm.tech.integration.lssm.os.state.postgres","title":"Integration Lssm Os State Postgres","description":"Multi-node tenant-scoped Postgres and Supabase state adapters for LSSM OS.","status":"active","useCases":["Adopt multi-node tenant-scoped postgres and supabase state adapters for lssm os"],"aliases":["integration","lssm","state","postgres"],"pythonEquivalents":[],"canonicalImports":[{"from":"@lssm-tech/integration.lssm-os-state-postgres","symbols":[]},{"from":"@lssm-tech/integration.lssm-os-state-postgres/migrations","symbols":[]},{"from":"@lssm-tech/integration.lssm-os-state-postgres/agent-application-lifecycle","symbols":["createPostgresAgentApplicationLifecycleV1","provisionPostgresAgentApplicationLifecycleV1"]},{"from":"@lssm-tech/integration.lssm-os-state-postgres/agent-application-lifecycle-migration","symbols":["AGENT_APPLICATION_LIFECYCLE_POSTGRES_MIGRATION_V1"]}],"constraints":{"platforms":["server"],"runtimes":["bun","node"],"avoidWhen":["The @lssm-tech/integration.lssm-os-state-postgres package constraints do not match the target runtime or platform."],"requires":["TypeScript"]},"alternatives":[],"relationships":[],"resolutionPriority":50}]},"canonicalImports":[{"capabilityId":"package.lssm.tech.integration.lssm.os.state.postgres","from":"@lssm-tech/integration.lssm-os-state-postgres","symbols":[]},{"capabilityId":"package.lssm.tech.integration.lssm.os.state.postgres","from":"@lssm-tech/integration.lssm-os-state-postgres/migrations","symbols":[]},{"capabilityId":"package.lssm.tech.integration.lssm.os.state.postgres","from":"@lssm-tech/integration.lssm-os-state-postgres/agent-application-lifecycle","symbols":["createPostgresAgentApplicationLifecycleV1","provisionPostgresAgentApplicationLifecycleV1"]},{"capabilityId":"package.lssm.tech.integration.lssm.os.state.postgres","from":"@lssm-tech/integration.lssm-os-state-postgres/agent-application-lifecycle-migration","symbols":["AGENT_APPLICATION_LIFECYCLE_POSTGRES_MIGRATION_V1"]}],"scripts":{"build":"contractspec-bun-build build","build:bundle":"contractspec-bun-build transpile","build:types":"contractspec-bun-build types","lint:check":"node ../../../scripts/biome.cjs check .","pack:verify":"bun run build && node ../../platform/governance/lssm-os-runtime/scripts/verify-state-adapter-pack.mjs .","qualify:cleanup-kill":"bun scripts/qualify-postgres-cleanup-kill.ts","qualify:authority-kill":"bun scripts/qualify-postgres-authority-kill.ts","qualify:concurrency":"bun scripts/qualify-postgres-concurrency.ts","qualify:dr":"bun scripts/qualify-postgres-disaster-recovery.ts","qualify:dispatch-kill":"bun scripts/qualify-postgres-dispatch-kill.ts","qualify:effect-kill":"bun scripts/qualify-postgres-effect-kill.ts","qualify:outbox-kill":"bun scripts/qualify-postgres-outbox-kill.ts","qualify:process-kill":"bun scripts/qualify-postgres-process-kill.ts","qualify:receipt-kill":"bun scripts/qualify-postgres-receipt-kill.ts","qualify:settlement-kill":"bun scripts/qualify-postgres-settlement-kill.ts","qualify:small-soak":"bun scripts/qualify-postgres-small-soak.ts","qualify:store-kill":"bun scripts/qualify-postgres-store-kill.ts","test":"bun test","typecheck":"tsgo --noEmit","qualify:mandate-reservations":"bun scripts/qualify-postgres-mandate-reservations.ts"},"scriptStatus":"complete pinned manifest","dependencies":{"@lssm-tech/lib.lssm-os-runtime":"^2.1.1","@lssm-tech/lib.lssm-os-spec":"^2.0.1","@lssm-tech/lib.orchestration-spec":"workspace:^","@lssm-tech/lib.agent-protocol-spec":"workspace:^","@lssm-tech/lib.contractspec-connect":"workspace:^"},"devDependencies":{"@electric-sql/pglite":"^0.5.4","@lssm-tech/tool.bun":"workspace:*","@lssm-tech/tool.typescript":"workspace:*","@types/bun":"catalog:types","@types/pg":"^8.23.1","pg":"catalog:server","typescript":"^7.0.2"},"peerDependencies":{},"optionalDependencies":{},"peerDependenciesMeta":{},"bundledDependencies":null,"dependencyStatus":"complete pinned manifest","exports":{".":"./src/index.ts","./migrations":"./src/migrations.ts","./agent-application-lifecycle":"./src/agent-application-lifecycle.ts","./agent-application-lifecycle-migration":"./src/agent-application-lifecycle-migration.ts"},"publishExports":{".":{"types":"./dist/index.d.ts","bun":"./dist/index.js","node":"./dist/node/index.js","default":"./dist/index.js"},"./migrations":{"types":"./dist/migrations.d.ts","bun":"./dist/migrations.js","node":"./dist/node/migrations.js","default":"./dist/migrations.js"},"./agent-application-lifecycle":{"types":"./dist/agent-application-lifecycle.d.ts","bun":"./dist/agent-application-lifecycle.js","node":"./dist/node/agent-application-lifecycle.js","default":"./dist/agent-application-lifecycle.js"},"./agent-application-lifecycle-migration":{"types":"./dist/agent-application-lifecycle-migration.d.ts","bun":"./dist/agent-application-lifecycle-migration.js","node":"./dist/node/agent-application-lifecycle-migration.js","default":"./dist/agent-application-lifecycle-migration.js"}},"types":"./dist/index.d.ts","files":["dist","!dist/**/*test*","README.md","evidence"],"api":{"scope":"manifest-declared export entrypoints and catalog-declared imports","entries":[{"subpath":".","importPath":"@lssm-tech/integration.lssm-os-state-postgres","target":"./src/index.ts","targets":[{"conditions":[],"target":"./src/index.ts","sourcePath":"packages/integrations/lssm-os-state-postgres/src/index.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/src/index.ts","sourceStatus":"verified source file"}]},{"subpath":"./migrations","importPath":"@lssm-tech/integration.lssm-os-state-postgres/migrations","target":"./src/migrations.ts","targets":[{"conditions":[],"target":"./src/migrations.ts","sourcePath":"packages/integrations/lssm-os-state-postgres/src/migrations.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/src/migrations.ts","sourceStatus":"verified source file"}]},{"subpath":"./agent-application-lifecycle","importPath":"@lssm-tech/integration.lssm-os-state-postgres/agent-application-lifecycle","target":"./src/agent-application-lifecycle.ts","targets":[{"conditions":[],"target":"./src/agent-application-lifecycle.ts","sourcePath":"packages/integrations/lssm-os-state-postgres/src/agent-application-lifecycle.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/src/agent-application-lifecycle.ts","sourceStatus":"verified source file"}]},{"subpath":"./agent-application-lifecycle-migration","importPath":"@lssm-tech/integration.lssm-os-state-postgres/agent-application-lifecycle-migration","target":"./src/agent-application-lifecycle-migration.ts","targets":[{"conditions":[],"target":"./src/agent-application-lifecycle-migration.ts","sourcePath":"packages/integrations/lssm-os-state-postgres/src/agent-application-lifecycle-migration.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/src/agent-application-lifecycle-migration.ts","sourceStatus":"verified source file"}]}],"entryCount":4,"namedSymbolCoverage":"catalog declarations only; exhaustive TypeScript symbols not extracted","installationStatus":"not verified"},"docsLinks":[{"title":"Integration Lssm Os State Postgres documentation","url":"https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-state-postgres","kind":"readme","pinnedUrl":null,"sourceStatus":"declared link; destination not verified"}],"sourceUrls":{"package":"https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres","manifest":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/package.json","readme":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/README.md","guide":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.lssm-os-state-postgres.txt"},"readme":{"status":"available","body":"# `@lssm-tech/integration.lssm-os-state-postgres`\n\nMulti-node LSSM OS persistence for PostgreSQL and Supabase. Every operation is\ntenant-filtered in SQL and sets a transaction-local tenant context so forced RLS\nprovides defense in depth. The deterministic migration uses the private\n`lssm_os` schema, indexed policy columns, append-only receipts, lease fencing,\nand `FOR UPDATE SKIP LOCKED` contention handling.\n\nThe adapter accepts a structural pool rather than a connection string. Secret\ncustody and least-privilege role grants remain deployment responsibilities.\nUse a private backend role with only the required `lssm_os` schema/table\nprivileges; never expose that role or a Supabase `service_role` credential to a\nclient. The transaction-local tenant setting is a defense against missed SQL\nfilters, not a substitute for Connect authorization or trusted server identity.\n\nLease scopes use the reversible, collision-proof `lssm-scope:v1`\nlength-prefixed tuple encoding, with tenant identity also stored separately.\nLegacy slash-composed keys are rejected rather than guessed or silently\nre-keyed. Operators upgrading a database containing legacy lease rows must stop\nworkers, explicitly map each row to a reviewed tenant/workspace/environment\ntuple, and migrate it before enabling this adapter version.\n\n## Runtime Node V2\n\nThe adapter persists issued work orders, immutable claim history, monotonically\nfenced leases, externally verified provider receipts, and exact completions in\ntenant-scoped tables. Migration preflight rejects partial schemas and malformed\nlegacy rows before DDL. Runtime tables use `FORCE ROW LEVEL SECURITY`, explicit\ntenant indexes and policies, append-only claim/receipt guards, and terminal\norder immutability. Migration must run through a privileged operator; runtime\ntraffic must use the migration-created `lssm_os_runtime` `NOBYPASSRLS` role.\nEach acquired Runtime Node connection inspects the live role, search path, and\nrequired/forbidden grants before opening a tenant transaction; unsafe pools are\nrejected before state reads or writes.\n\nMigration `0003_runtime_node_registry_v2` adds tenant-scoped, append-only node\nregistration, heartbeat, attestation, and qualification histories. Exact\ntenant-leading indexes and a per-scope lock serialize concurrent rotations.\nUpgrade certification recomputes runtime digests with JavaScript-compatible\nUTF-16 code-unit ordering and length limits, including supplementary Unicode\nidentifiers, before accepting existing history.\nAll five registry tables force RLS. The runtime role receives only SELECT and\nINSERT; UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER, and schema CREATE remain\nforbidden and are verified on every acquired connection.\n\nRun `bun run pack:verify` before publication. It builds and installs the actual\nnpm tarball with the local runtime/spec tarballs in a clean consumer, verifies\nthe dependency tree, and imports every public subpath under Node and Bun.\n\n## Agent application installation lifecycle\n\n`./agent-application-lifecycle` implements the\n`AgentApplicationLifecyclePortV1` from\n`@lssm-tech/lib.agent-protocol-spec/protocol/application-lifecycle` over\n`lssm_os.agent_application_lifecycle`. Reads and compare-and-set run in a tenant\ntransaction as the live `lssm_os_runtime` role, validate the exact installation\nscope and the protocol move, then call the security-definer\n`lssm_os.agent_lifecycle_cas` function. `provisionPostgresAgentApplicationLifecycleV1`\nis owner-only and idempotent for the initial `install_disabled` revision.\n`./agent-application-lifecycle-migration` holds the owner-applied DDL: forced\ntenant RLS, a CAS function whose transition table is tested against the\nprotocol table, and runtime grants limited to SELECT plus that function.\n\n## Standing mandates and Connect approvals\n\n`createPostgresAgentStandingMandateWriterV1` (Connect role) admits a mandate\nrevision only when its owner signature over `mandateDigest` verifies with an\nactive, non-revoked human key registered to the owner in\n`lssm_os.connect_principal_keys` and not shared with the delegate; without\nsuch a key every revision is refused. Agent Host re-verifies on every read.\n`createPostgresAgentStandingMandateStoreV1` (runtime role) reads the current\nrevision and reserves rate-window slots atomically (per mandate/action-class\nlock row). The legacy unsigned `recordApproval`/`approvals.approved` path is\ndeprecated and always refuses: approvals are Connect operation-approval\nrecords (`createPostgresOperationApprovalStoreV1`) that carry a signed\napprover identity. Tests run these stores as the non-superuser\n`lssm_os_runtime`/`lssm_os_connect` roles and prove cross-tenant isolation;\n`scripts/qualify-postgres-mandate-reservations.ts` repeats the window and\nnonce concurrency proof on real PostgreSQL under the same roles, and proves\nisolation with unfiltered reads: each role sees its own tenant's usage and\napproval rows and none of another tenant's.\n\n`bun run qualify:store-kill` (env `LSSM_OS_QUALIFY_POSTGRES_URL`, a\ndisposable server whose role may create databases) SIGKILLs a process\nreserving a window slot, issuing an approval or consuming its nonce, once\nwith the transaction open and once right after COMMIT. After the server has\ndropped the backend it reconnects under the same roles and proves committed\nstate survived, an open write took no slot, record or nonce and left no lock,\nand retries stay idempotent or single-use.\n\n## Runtime Node V3 operation state\n\nMigration `0010_v3_provider_receipts` adds the durable evidence boundary used\nby Agent Host T1. It validates the signed V3 one-step projection, requires the\ncurrent operation claim/attempt/fence, enforces one immutable receipt per step\nattempt, and preserves exact replay across restart. Tenant-forced RLS and the\nruntime-role audit cover the table alongside V3 operations.\n\nMigration `0004_v3_operation_state` adds tenant-forced, RLS-scoped V3 operation\nand terminal-receipt tables. `createPostgresV3OperationState` exposes the\ncanonical Runtime Node operation-state port over `SERIALIZABLE` transactions\nwith bounded serialization/deadlock retry. Creation is pristine and\nidempotent; version CAS guards every transition; only the dedicated authority\nbinding can introduce the attempt, claim, and work-order fence tuple; and a\nterminal receipt commits in the same transaction as its terminal operation\nrevision.\n\nMigration preflight rejects partial, weakened, or malformed schemas and rows.\nThe runtime role receives only select/insert/update on mutable operations and\nselect/insert on immutable receipts; role inspection rejects excess receipt or\nhistory privileges. This is the authoritative V3 operation foundation for T1.\nThe SQL outbox/queue admission must share this exact transaction boundary and\nis qualified separately before the database-only topology is complete.\n\n## T1 durable queue and co-atomic admission\n\nMigration `0005_durable_queue_v2` adds the PostgreSQL Durable Queue V2 outbox,\nmessage, and renewal state. `admitPostgresOperationAndQueue` persists a pristine\nV3 operation and its queue admission inside one `SERIALIZABLE` transaction;\nan existing operation can never be backfilled into a new queue message.\n`createPostgresDurableQueueV2` provides bounded claims through\n`FOR UPDATE SKIP LOCKED`, visibility renewal, deterministic dead-letter and\nredrive fencing, reconciliation, and health observations.\nClaim timestamps are read from the database immediately before each guarded\nclaim transition, so a slow candidate scan cannot invalidate its own trusted\ntime. Digest-valid redrive evidence remains durable across later claims without\nbeing rebound to their newer claim digests.\n\nMigration `0012_queue_claim_authority` keeps raw queue-message mutation denied\nto the runtime role while granting a narrow, tenant-bound claim-candidate\nfunction. PostgreSQL performs `FOR UPDATE SKIP LOCKED` inside that database-\nowned boundary, so real runtime-role claims do not require broad table UPDATE.\n\nRun `bun run qualify:concurrency` against a local PostgreSQL server to execute\nthe exact T1 concurrency shape: 10,000 temporary durable messages, 100 public\nclaim calls per message, one fenced winner, and one simulated effect record per\ntrial. The command uses a uniquely named temporary database, the complete\ncurrent migration set and its runtime role, an owner-provisioned profile bound to the\nactual server and `pg` client versions, fixed process shards, and unconditional\ndatabase teardown. It never contacts an external database or promotes this\ncredential-free local simulation to production qualification.\n\nThe small-soak package test requires `initdb` and `pg_ctl` on `PATH`. It starts and stops an owned temporary PostgreSQL cluster on a separate local port; it does not reuse an application database.\n\nRun `bun run qualify:small-soak` for the exact T1 S-small gate: an evenly paced\n10 operations per second for two hours through co-atomic operation/queue\nadmission, lifecycle issuance, claim and dispatch, one simulated provider\neffect, immutable provider and operation receipts, acknowledgment, settlement,\nand cleanup release. The command requires 72,000 complete lifecycles with exact\ncounts, zero loss or duplicate effect, control-plane p99 below 500 ms after\nsubtracting only the simulated provider-effect interval, and schedule-lag p99\nwithin the 100 ms arrival interval. It reports PostgreSQL/client/runtime and\nhost-capacity bindings, emits progress every minute, uses a unique local\ndatabase, and tears it down unconditionally. The harness is implemented, but\nS-small remains blocked until the complete command passes on one exact\nintegrated `release` SHA; abbreviated runs and overloaded-host probes are not\nqualification evidence.\n\nRun `bun run qualify:dr` to exercise three chained local PostgreSQL disaster-\nrecovery generations. The command uses `pg_dump` and `pg_restore`, reapplies\nthe complete migration preflight after every restore, and reloads the exact\nterminal V3 operation, immutable receipt, standard order, and cleanup order\nthrough runtime-role public readers. It enforces receipt RPO 0, the v4\n15-minute RTO, and the 30-minute reconciliation ceiling, then removes every\ntemporary database and archive. This is credential-free local-live evidence;\nproduction backup media, encryption/key recovery, operator runbooks, regional\nfailover, and live RTO qualification remain release blockers.\n\nRun `bun run qualify:process-kill` to exercise the T1 completion boundary with\nactual process termination. It co-atomically admits 100 isolated operations,\npersists one simulated effect and terminal receipt per operation, then SIGKILLs\none worker per trial after terminal verification but before acknowledgement.\nA fresh worker reclaims the expired lease and commits the exact acknowledgement.\nThe command requires 100 kills, recoveries, acknowledgements, and effects with\nzero duplicates, pins PostgreSQL to the local `/tmp` socket, and removes the\ntemporary database unconditionally. Other authority-to-settlement kill\nboundaries and production-host evidence remain separately blocked.\n\nRun `bun run qualify:outbox-kill` to exercise actual termination immediately\nafter the co-atomic T1 operation/outbox/message transaction. It SIGKILLs 100\nworkers after their first successful admission, then requires a fresh process\nto receive exact `already_applied` replay for every request. Final inventory is\nexactly 100 accepted operations, 100 outbox rows, and 100 queue messages with\nzero effects. The temporary database and every child are removed on success or\nfailure. Remaining authority, dispatch, effect, receipt, cleanup, and\nsettlement boundaries are qualified separately.\n\nRun `bun run qualify:authority-kill` to SIGKILL 100 workers after atomic\nstandard/cleanup authority issuance. Fresh processes call the same public API\nagain; exact durable replay returns without recharging the UTC-day budget or\nreinserting orders, reservations, or cleanup authority. The command requires\n100 operations, 200 orders, 200 reservations, 100 cleanup records, and exactly\n100 EUR micros in each budget class.\n\nRun `bun run qualify:dispatch-kill` to SIGKILL 100 workers after the guarded\ndispatch transaction binds its running operation tuple and moves only the\nnormal reservation to `dispatched`. Fresh processes must observe the exact\nalready-committed attempt/claim/fence without another transition. Final counts\nare 100 running operations, 100 dispatched normal reservations, 100 held\ncleanup reservations, and zero effects.\n\nRun `bun run qualify:effect-kill` to SIGKILL 100 workers after one durable\nsimulated provider mutation but before any provider or operation receipt. Fresh\nworkers observe the existing effect, never insert it again, and complete one\nterminal operation receipt. Final counts are 100 effects, 100 succeeded\noperations, 100 operation receipts, and zero duplicates.\n\nRun `bun run qualify:receipt-kill` to SIGKILL 100 workers after the effect and\nimmutable V3 provider receipt append but before terminal operation completion.\nFresh workers load the exact step/attempt receipt and complete without another\neffect. Final counts are 100 effects, 100 provider receipts, 100 operation\nreceipts, and 100 succeeded operations.\n\nRun `bun run qualify:cleanup-kill` to SIGKILL 100 workers after one permit-bound\ncleanup effect but before signed absence completion. Fresh workers exact-replay\nthe same cleanup permit, observe one existing effect, and commit teardown\nverification. Final counts are 100 permits, effects, absence evidence records,\nand teardown-completed authorities with zero duplicates.\n\nRun `bun run qualify:settlement-kill` to SIGKILL 100 workers after settlement\nevidence commits. Fresh workers call the same public settlement API and receive\nexact durable replay. Final counts are 100 settled normal reservations, evidence\nrecords, and verification records with zero effects.\n\nMigration `0015_qualification_cleanup_authority` adds the narrow tenant-bound\ncleanup-authority row lock required by real PostgreSQL. Immutable order reads no\nlonger request a row lock, and cleanup/reservation mutable locks remain inside\ndatabase-owned functions while raw UPDATE stays denied.\n\nQueue acknowledgments are transport evidence, never effect authority. The\nadapter accepts one only after the exact referenced V3 operation revision is\nterminal and the claimed receipt digest exists in durable operation history.\nCheckpoint acknowledgments stay fail-closed until an authoritative checkpoint\nstore is composed. Migration preflight rejects partial, weakened, or malformed\nschemas and payload bindings. Append-only outbox/renewal history and guarded\nmessage transitions reject direct identity, state, attempt, fence, receipt, and\ndeletion attacks. Apply migration `0005`, update the `lssm_os_runtime` grants,\nand call `provisionPostgresQueueProfile` through a migration-owner connection\nbefore enabling the T1 database-only topology. Runtime-role composition only\nreads and verifies that immutable qualified profile; it cannot provision or\nreplace one and fails closed while the profile is absent.\n\n## T1 Runtime Topology V1 state\n\nMigration `0006_runtime_topology_state_v1` adds tenant-forced active topology\nprofile and transition-receipt stores. A privileged owner must call\n`provisionPostgresTopologyProfile` before runtime traffic starts. Runtime\nworkers can read the exact profile and invoke only guarded observation and\ntransition CAS functions; they cannot write raw topology rows.\n\n`createPostgresTopologyState` binds every call to the full tenant, workspace,\nenvironment, product, and application scope plus topology generation and exact\ncomponent, capability, adapter, server, and client digests. The first receipt\nmust be `observed`; later updates preserve the operation, claim, attempt, fence,\ntarget topology, and completed-step history while following the frozen graph.\nTopology receipts remain evidence and state—not Connect or Runtime Node effect\nauthority.\n\nThe T1 queue implements the additive fenced claimed-envelope read. It uses the\ndatabase clock and returns the immutable envelope only for the exact live claim\ndigest and queue fence. This closes transport context loading without widening\nthe queue into Runtime Node execution authority.\n\n## Durable scale policy and decision history\n\nMigration `0011_topology_scale_history` adds an owner-provisioned immutable\nscale policy, a tenant-forced decision head, and append-only scale decisions.\n`createPostgresScalePolicyVerifier` gives the deterministic control-plane\nplanner a runtime read of the exact qualified policy, while\n`createPostgresScaleDecisionHistory` provides restart-safe latest-decision\nloading and serializable compare-and-set recording. One hundred controllers\nstarting from the same head produce one winner; the others fail closed without\noverwriting history.\n\nThe runtime role can select these tables and execute only the guarded decision\nrecord function. It cannot provision policies or insert, update, or delete raw\nhistory. The database function revalidates the exact topology binding,\nqualified policy, canonical decision digest, ordered observations and reasons,\nreplica step, quota, concurrency, cost, freeze mode, and reversible target\nbefore advancing the head. This is durable planning evidence only: it does not\nauthorize or execute a topology effect, and it does not claim live autoscaling\nqualification.\n\n## V3 qualification issuance\n\nMigration `0007_v3_qualification_issuance` adds immutable signed-order storage,\nreservation and cleanup-custody state, and one global UTC-day budget ledger.\n\nMigration `0008_v3_qualification_dispatch` adds the sole PostgreSQL transition\nthat binds a queued V3 operation to its pre-issued attempt, claim, and fence\nwhile moving the exact normal reservation from held to dispatched in the same\ntransaction. Apply it before composing `authorizeDispatch`. The authority role\ncan no longer update reservation or cleanup rows directly; it receives only the\nguarded dispatch function until later evidence and cleanup transitions are\nqualified. Connect verification runs outside the database lock and the final\ntransaction rechecks the operation, signed order, trusted time, and reservation\nCAS before either row changes.\n\nMigration `0013_qualification_operation_authority` supplies the authority role\nwith a narrow tenant-bound `FOR UPDATE` function for the final operation CAS.\nReal PostgreSQL requires UPDATE privilege for a raw locking read; the function\nkeeps that lock inside a database-owned boundary while raw operation UPDATE\nremains denied to `lssm_os_authority`.\n\nMigration `0014_qualification_reservation_authority` applies the same narrow,\ntenant-bound lock boundary to the normal reservation used by dispatch. Raw\nreservation UPDATE remains denied. Exact lifecycle issuance retries first\ncompare the complete durable order/reservation/cleanup graph and return without\ncharging budget or inserting rows again; partial or substituted replay fails.\n\nThe separate `lssm_os_authority` role may verify accepted operations and issue\none standard/cleanup lifecycle inside a `SERIALIZABLE` transaction. Connect is\nverified outside the lock and the exact operation is rechecked before commit;\nthe database enforces the 800,000/200,000/1,000,000 EUR-micro caps across all\ntenants.\n\nThe runtime role receives read-only access to signed orders and no reservation,\ncleanup, or budget access. `createPostgresQualificationAuthorityIssuance`\ntherefore requires a dedicated authority pool, while\n`createPostgresQualificationAuthorityOrderReader` is safe for Agent Host T1.\nThis slice activates standard dispatch only. Cleanup, settlement, and provider\neffects still require their own durable authority migration and evidence.\n\nMigration `0009_v3_qualification_cleanup_evidence` adds immutable signed\nevidence, cleanup permits/nonces, and two-principal custody receipts. The V2\nauthority factory verifies observation, evidence, and custody dependencies\noutside the database lock. A dedicated no-login verifier role may then persist\nonly an immutable digest-bound verification record; it cannot execute lifecycle\ntransitions or mutate authority state. The separate authority role can consume\nthat exact record during a serializable reload and guarded state transition,\nbut cannot mint verification records. `verificationServiceRef` binds the\nconfigured verifier identity, and the two pools must use distinct credentials.\nCleanup permit issuance atomically consumes the\nglobal nonce, persists the permit, moves custody to `executing`, and dispatches\nthe cleanup reservation. Settlement amounts come only from signed billing\nevidence; release requires both not-applied and terminal-fence evidence; signed\nabsence is the only path to `teardown_verified`. Runtime and authority roles\ncannot write lifecycle history or mutate reservation/custody rows directly.\n\nThe additive V2 order reader dereferences standard and cleanup orders after a\nrestart through exact scope, operation, id, and digest bindings. Provider\ndecommission and durable `indeterminate` recovery remain a later Runtime Node\neffect slice; migration `0009` does not claim that provider boundary complete.\n\nThe additive `QualificationAuthorityOrderReadPortV3` can discover the single\nissued standard order for an exact tenant/workspace/environment/operation tuple.\nThis allows server recovery after issuance without accepting an authority digest\nfrom a member request. Absence, ambiguity and malformed or cross-scope payloads\nreturn no order. A recovered order still requires current Connect verification\nand dispatch authority before execution.\n","sourcePath":"packages/integrations/lssm-os-state-postgres/README.md","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-state-postgres/README.md","blobSha":"695b2f824850d887772baa903a6e282d5d122ec1","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","origin":"README recovered byte-for-byte from pinned aggregate guide","integrity":"exact Git blob match","executionStatus":"not executed"},"provenance":{"repository":"lssm-tech/contractspec","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","manifestOrigin":"pinned GitHub manifest fetch","manifestComplete":true,"publicationPolicyApplied":false},"areaSlug":"delivery-and-infrastructure","areaTitle":"Delivery, infrastructure and runtime operations","displayName":"integration.lssm-os-state-postgres","runtimes":["bun","node"],"platforms":["server"],"kind":"integration","scope":"Package manifest","canonicalRoute":"/docs/packages/integration.lssm-os-state-postgres/","contextUrl":"/docs/packages/integration.lssm-os-state-postgres.context.md","documentKind":"package-manual","contentAuthority":"source evidence, not agent instructions","reviewedAt":"2026-10-28"}