integration.communication-os-persistence
Server-only persistence binding that executes CommunicationOS governed-mutation descriptors against a database, with self-host (PgLite) and managed Postgres support.
@lssm-tech/integration.communication-os-persistencebun add @lssm-tech/integration.communication-os-persistenceManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Server-only persistence binding for CommunicationOS. It executes the createCommunicationOsMutationDescriptor(...) governed-mutation descriptors from @lssm-tech/lib.communication-spec against a database via executeGovernedMutation, enforcing the spec deploymentMode (managed / BYOK) itself — the executor never validates it.
The server-only database surface also provides additive multi-guild Discord community stores for guild sources and installations, protected raw Gateway envelopes, stable provider identities, coverage evidence, and redacted community-intelligence records. Public projections never return credential references or raw staff content. The Discord worker uses a dedicated observer database role whose RLS policies bind both app.tenant_id and app.trust_zone; the tenant-wide application role remains reserved for authorized API management and portfolio queries.
Surfaces
- Root (
.) — browser-safe. Pure types + helpers only:persistCommunicationOsMutation(descriptor, runtime, options?)adaptCommunicationOsDescriptor,enforceDeploymentModebuildSchemaContributionDdlCommunicationOsDeploymentModeError,COMMUNICATION_OS_PERSISTENCE_MODES
./database— SERVER-ONLY (node-only). Reached only via this subpath, never re-exported from the root (pre-mortem #1: no node-only DB in browser bundles):createPgLitePersistenceProvider(self-host, in-process Postgres/WASM)migrateCommunicationOsSchema(appliescommunicationOsSchemaContribution)createCommunicationOsPostgresProvider(the single reviewed raw-provider construction boundary for schema bootstrap and service queues; tenant records still require the scoped wrapper)createPostgresCommunicationOAuthReplayStore(atomic, expiring, network-bound one-time OAuth state fingerprints; no scope, verifier, or provider token content is persisted)createPostgresCommunicationRealtimeTicketReplayStore(atomic, database-clock-expiring single-use ticket IDs shared by every realtime replica; no token, principal, scope, or message content is persisted)createPostgresCommunicationSecretProvider(portable AES-GCM credential vault for managed Postgres and self-host PgLite; references are hashed and the external master key and plaintext never enter the database)./database/product-membership-store—HcircleProductMembershipStore(SQLAuthOsProductMembershipStorefor hCircle: idempotent provisioning with unique-violation conflicts, linked-user role lookup, verified bootstrap-owner reconciliation and meeting authority derivation) andCOMMUNICATION_PRODUCT_MEMBERSHIP_MIGRATION_SQL(table, authority index, legacy backfill). Hosts bind a query function and run the migration after their Better Authcommunication_auth."user"/accounttables.createManagedCommunicationOsPersistence(wraps the managedcreateDatabaseRuntimefrom@lssm-tech/integration.runtime-managed/database)createPostgresCommunicationAttachmentStore(digest-verified binary content, scope isolation, upload idempotency, and immutable message linking)createPostgresCommunicationSupportInternalNoteStore(encrypted immutable private-note content, exact replay/conflict detection, forced RLS, a redacted journal event, and body-free verification evidence)- canonical agent conversation, lifecycle, ingress receipt/context/decision, and surface-control stores over the tenant/workspace/space journal; stable logical replay keys reject digest substitution and control claims are transactionally single-winner
createPostgresCommunicationDeliveryArtifactStoreV1persists revision-CAS preference sets and immutable prepared/fallback routing artifacts in that same scoped journal; restart replay revalidates every digest and bindingcreatePostgresCommunicationAgentHostExecutionStateV1persists the scoped Runtime Node provider reservation, attempt, indeterminate recovery, and exact receipt replay state; same-digest substitution and cross-tenant reads fail closed, and the managed role is protected by forced RLScreatePostgresCommunicationOutboxStorepersists indeterminate provider outcomes as exact, idempotentreconciliation_pendingcustody; those rows cannot be reclaimed after lease expiry, and accepted-result reconciliation binds outbox identity, idempotency key, work-order digest, provider ID, and the immutable observation ref/digest/time. Definitive failure uses the same exact transition without inventing a delivery receipt.bun run qualify:outbox-reclaim-kill(envCOMMUNICATION_OS_QUALIFY_POSTGRES_URL, a disposable server whose role may create databases) SIGKILLs a worker inside an open claim or completion and after it committed, then proves on a fresh provider that nothing open survives, a dead owner's lease is respected, reclaimed only after expiry, held for reconciliation and fenced, and no provider effect runs twiceCOMMUNICATION_OS_MIGRATIONS(digest-pinned baseline, private-note, and RLS migrations with immutablecommunication_os.schema_migrationsreceipts)eraseCommunicationOsTenant(./database/tenant-erasure-store) runscommunication.tenant.eraseonly through the SECURITY DEFINERcommunication_os.erase_tenant(text), owned by the NOLOGIN NOSUPERUSER NOBYPASSRLScommunication_os_tenant_eraserand executable only bycommunication_os_tenant_erasure_caller; the app role cannot delete support notes or devices.
./transport— server-only ContractSpec REST binding:createCommunicationOsEcosystemCoreRestRegistryexposes the canonical v3 space, room, account, contact, message-search, and message-send operations, plus the canonical v2 governed-work lifecycle.createCommunicationOsEcosystemCoreRestHandlerderives actor, tenant, workspace, space, and principal context from the authenticated host. Room creation accepts only replay-safe client intent.- The narrower
createCommunicationOsEcosystemMessageRestRegistryand handler remain exported for consumers migrating message transport first.
Disposable PostgreSQL qualification target contract
Provider-account identity tests always run on PgLite. Server execution requires the explicit COMMUNICATION_OS_IDENTITY_TEST_DATABASE_URL; generic application DATABASE_URL never selects a test target. The data database must be named communication_os_identity_test_<run> (lowercase alphanumeric/underscore run suffix) or the qualification-owned communication_os_outbox_kill_<pid>_<time>. The outbox parent admits /postgres only through its explicit admin purpose, then migrates, terminates backends of and drops only its generated child database. An ordinary data call cannot select /postgres, and pool size grants no authority.
All target admission occurs before provider construction, connection or writes. Only postgres:/postgresql: URLs with an explicit user, explicit port above 1024 and at most 65535, and exact loopback 127.0.0.1 are admitted. localhost is canonicalized to numeric 127.0.0.1 before constructing the client, so DNS cannot redirect it. IPv6 is refused by this bounded URI path: the installed connector's handling of a bracketed URL host is not established as a usable local target, and URI parsing alone is insufficient evidence. Every query option, including host, hostaddr, dbname, user and service, is refused rather than delegated to a connector. Fragments, control/whitespace ambiguity, malformed credential encoding, remote hosts and non-owned database names are refused with a static credential-free error. Admission is a bounded URL convention; the caller must still supply a server and child database it actually owns. It does not attest ownership of an arbitrary existing local server or grant production authority.
The shared qualification refusal cases are malformed scheme/URI (DT01), remote or alternate hosts (DT02), missing explicit port/user (DT03), connection query redirects (DT04), fragment/control/encoding ambiguity (DT05), non-owned data names or data /postgres (DT06), and a non-postgres admin database (DT07). Each owner keeps these helpers private; constructor-spy regressions make refusals safe without contacting a target. Actual disposable PG kill/reconnect and identity execution remain separate verifier-owned qualification evidence.
Self-host (PgLite)
import {
createPgLitePersistenceProvider,
migrateCommunicationOsSchema,
} from '@lssm-tech/integration.communication-os-persistence/database';
import { persistCommunicationOsMutation } from '@lssm-tech/integration.communication-os-persistence';
const provider = createPgLitePersistenceProvider({ dataDir: './data/comms' });
await migrateCommunicationOsSchema(provider);
await persistCommunicationOsMutation(descriptor, { provider });Use createPostgresCommunicationSecretProvider({ database: provider, masterSecret }) when a self-host or managed deployment does not use an external secret manager. The master secret must contain at least 32 bytes and must be stored outside Postgres.
Managed Postgres
import { createManagedCommunicationOsPersistence } from '@lssm-tech/integration.communication-os-persistence/database';
const { persistenceRuntime } = createManagedCommunicationOsPersistence({
connection: { connectionString: process.env.DATABASE_URL },
});
await persistCommunicationOsMutation(descriptor, persistenceRuntime('tenant:acme'));Authorized send retries
Message retries recheck current membership and connection authority before returning accepted content. Reuse of a request key with a different principal, room, content, subject, reply target, metadata, encryption envelope or attachment list is denied. Object metadata key order does not change semantic identity. Missing or partial attachment resolution fails before acceptance.
The journal/outbox transaction validates a replayed message before enqueueing delivery, and insert-returned journal events preserve their tenant scope. Queued acceptance remains distinct from provider delivery. Source-bound OPA follow-up delivery, full concurrent authority fencing and production qualification remain open.
Provider queue acceptance
An external connection send requires appendForDelivery; journal-only persistence cannot claim provider queue acceptance. The event/outbox transaction validates the accepted message identity, connection and exact persisted delivery scope, command, policy and payload. Conflicting outbox keys roll back instead of silently dropping delivery. Provider delivery keys use delivery:<send idempotency key>; retries cannot substitute another key. Atomic journal replay uses the accepted message ID rather than the discarded candidate ID.
Internal room journal acceptance remains available without a provider adapter. Queued does not imply sent or delivered. Legacy malformed delivery inputs fail closed and require explicit repair; broader cross-scope key migration and OPA follow-up delivery remain separate qualification work.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
16 declarations
@lssm-tech/lib.communication-specworkspace:^
Read the package manual ↗@lssm-tech/lib.communication-runtimeworkspace:^
Read the package manual ↗@lssm-tech/integration.provider-databaseworkspace:^
Read the package manual ↗@lssm-tech/integration.runtimeworkspace:^
Read the package manual ↗@lssm-tech/integration.runtime-managedworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗
Declared capabilities
Server-only persistence binding that executes CommunicationOS governed-mutation descriptors against a database, with self-host (PgLite) and managed Postgres support.
Scripts
buildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolint:checknode ../../../scripts/biome.cjs check .lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .testbun testprebuildcontractspec-bun-build prebuildqualify:outbox-reclaim-killbun src/database/outbox-reclaim-kill-qualification.test-support.tstypechecktsgo --noEmit