integration.communication-os-persistence

@lssm-tech/integration.communication-os-persistence

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)
• ./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.

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 });

Usar 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.