Skip to content
ContractSpec
Start here

Package manual · integrations

·Communication and notifications

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.

integrationsintegrationv3.0.4experimentalservernode
@lssm-tech/integration.communication-os-persistence
bun add @lssm-tech/integration.communication-os-persistence
Package source ↗Manifest ↗

Manifest 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, enforceDeploymentMode
    • buildSchemaContributionDdl
    • CommunicationOsDeploymentModeError, 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 (applies communicationOsSchemaContribution)
    • 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 (SQL AuthOsProductMembershipStore for hCircle: idempotent provisioning with unique-violation conflicts, linked-user role lookup, verified bootstrap-owner reconciliation and meeting authority derivation) and COMMUNICATION_PRODUCT_MEMBERSHIP_MIGRATION_SQL (table, authority index, legacy backfill). Hosts bind a query function and run the migration after their Better Auth communication_auth."user"/account tables.
    • createManagedCommunicationOsPersistence (wraps the managed createDatabaseRuntime from @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
    • createPostgresCommunicationDeliveryArtifactStoreV1 persists revision-CAS preference sets and immutable prepared/fallback routing artifacts in that same scoped journal; restart replay revalidates every digest and binding
    • createPostgresCommunicationAgentHostExecutionStateV1 persists 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 RLS
    • createPostgresCommunicationOutboxStore persists indeterminate provider outcomes as exact, idempotent reconciliation_pending custody; 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 (env COMMUNICATION_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 twice
    • COMMUNICATION_OS_MIGRATIONS (digest-pinned baseline, private-note, and RLS migrations with immutable communication_os.schema_migrations receipts)
    • eraseCommunicationOsTenant (./database/tenant-erasure-store) runs communication.tenant.erase only through the SECURITY DEFINER communication_os.erase_tenant(text), owned by the NOLOGIN NOSUPERUSER NOBYPASSRLS communication_os_tenant_eraser and executable only by communication_os_tenant_erasure_caller; the app role cannot delete support notes or devices.
  • ./transport — server-only ContractSpec REST binding:
    • createCommunicationOsEcosystemCoreRestRegistry exposes the canonical v3 space, room, account, contact, message-search, and message-send operations, plus the canonical v2 governed-work lifecycle.
    • createCommunicationOsEcosystemCoreRestHandler derives actor, tenant, workspace, space, and principal context from the authenticated host. Room creation accepts only replay-safe client intent.
    • The narrower createCommunicationOsEcosystemMessageRestRegistry and 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)

ts
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

ts
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

THIS PACKAGEintegration.communication-os-persistence68 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

16 declarations

Declared capabilities

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.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • qualify:outbox-reclaim-killbun src/database/outbox-reclaim-kill-qualification.test-support.ts
  • typechecktsgo --noEmit