lib.communication-runtime

@lssm-tech/lib.communication-runtime

CommunicationOS capability migration

The v3 capability namespace migration keeps the append-only journal immutable. reconcileLegacyCommunicationCapabilities appends canonical membership and authority-grant events for the latest aggregates with an idempotent migration key. Read projections canonicalize legacy evidence immediately, so a valid persisted comms.room.write grant does not lose send authority while the reconciliation sweep completes.

Backend-neutral CommunicationOS runtime for lifecycle validation, governance decisions, in-memory state, ingestion normalization, records, and replay-oriented helpers.

Typed provider ingestion can retain validated non-message events as immutable communication.provider.<eventKind> journal entries without fabricating message events. Discord identity helpers correlate the same stable provider ID across guilds while preserving guild-local roles; different-account merges require explicit reviewed evidence.

The v2 ecosystem runtime adds a scope-isolated append-only journal, deterministic projections, personal/organization encryption policy evaluation, and immediate send-authority checks for human, agent, and system principals. The default remains legacy_draft_only; hosts explicitly choose membership_grants only after they can provide current room membership and auditable, revocable grants.

createCommunicationMessagingRuntime exposes typed listSpaces and listRooms projections rebuilt from the selected space journal. Historical room events that predate roomKind remain readable as group rooms; the projection never scans a sibling space or creates a parallel mutable catalog.

createCommunicationGovernedWorkRuntime adapts the existing CommunicationOS identity, draft, action, handoff, escalation, agent, consent, retention, and policy operations to the same append-only journal. Creates and decisions are idempotent, projected only inside the selected scope, and permit exactly one terminal transition from pending.

createCommunicationOAuthCoordinator provides the adapter-free provider onboarding control plane. It binds encrypted opaque state and PKCE to the exact principal, scope, network, optional provider key, placement, and safe return path; consumes replay state before exchange; and accepts only credential references from provider ports. Multiple providers may share one network; provider-less email onboarding deterministically retains the first registered provider while an explicit key is pinned through callback completion.

Authenticated provider invalidations use the same journal idempotency domain as cursor sync. They append communication.connection.sync.invalidated without fabricating a message, and duplicate callbacks reuse the durable evidence.

The runtime also exposes persistAgentCommunicationCommand, a provider-free domain-command persistence helper. It turns named CommunicationOS commands (for example communication.reply.send) into immutable in-memory runtime events with read_persisted, draft_persisted, or approval_packet_persisted status. The helper records the command plan and approval violations only; it does not send messages, call providers, open database connections, or mutate external systems.

createCommunicationCommandInboxItem projects message-originated commands into a command inbox item with canExecute: false, AIP control refs, persisted event evidence, and optional CompanyOS bridge review state. Production-send and high-impact CompanyOS bypass signals fail closed as blocked; approval-gated commands remain evidence packets until an external human/policy path acts.

Unified delivery preparation

prepareCommunicationDeliveryV1 resolves the sealed preference hierarchy, creates an exact no-authority delivery intent, evaluates every candidate route, and selects the first eligible route. Missing eligibility evidence fails closed. External routes always require consent. WhatsApp service windows/templates, Telegram first contact, workspace membership, suppression/opt-out, push-device, and calendar-permission constraints are explicit inputs. The fallback path stops after an ambiguous attempt until exact reconciliation proves failure.

reconciliation_pending is a non-claimable outbox state. Moving a leased record into it requires the exact lease plus the Runtime Node work-order digest and evidence refs; replay with substituted custody data fails closed. resolveCommunicationOutboxReconciliation can later resolve that custody only from a digest-bound provider observation for the same work order. Accepted evidence records the provider delivery ID; definitive-failure evidence records the error without creating a delivery receipt. Neither path redispatches.

./delivery-routing.fixture is a deterministic, provider-free integration fixture. The runtime contains no provider SDK, database adapter, secret, or send authority.

Public Entry Points

• . resolves through ./src/index.ts
• ./governance resolves through ./src/governance/index.ts
• ./ingestion resolves through ./src/ingestion/index.ts
• ./lifecycle resolves through ./src/lifecycle/index.ts
• ./records resolves through ./src/records/index.ts
• ./replay resolves through ./src/replay/index.ts
• ./state resolves through ./src/state/index.ts
• ./runtime includes domain-command planning and persistence helpers
• ./command-inbox exposes the fail-closed command inbox projection helper
• ./delivery-routing exposes deterministic preference, eligibility, intent, and fallback preparation; ./delivery-routing.fixture exposes its sealed test fixture
• the root export includes createInMemoryCommunicationJournal, projectCommunicationJournal, evaluateCommunicationContentPolicy, and evaluateMessagingSendAuthority
• ./ecosystem-oauth exposes the provider-neutral OAuth coordinator, state codec/replay ports, provider port, and deterministic test store
• ./ecosystem-governed-work exposes persisted work projections and lifecycle commands without importing example or application packages
• ./ecosystem-conversation-references records authenticated provider conversation addresses in the scoped journal and resolves only active, non-revoked references for later delivery admission
• ./ecosystem-messaging-service resolves opaque, scope-bound attachment IDs before appending public-safe file metadata to the immutable message event
• ./support-internal-notes validates private Support note commands, protects content before persistence, and returns body-free evidence projections
• ./agent-lifecycle-projection validates immutable, digest-bound progress and help projections before an injected canonical-conversation sink is called; the projection grants no effect authority
• ./canonical-agent-conversation validates and resolves exact scoped conversation/session bindings
• ./ingress-admission persists the authenticated receipt before context compilation, applies deterministic admission, and resumes an already durable decision through an idempotent normalized-ingress reference
• ./agent-surface-control claims a conversation/run-bound control once and delegates execution to an injected authority; duplicate or indeterminate claims reconcile rather than calling authority again
• ./ecosystem-subscription-coordinator journals a provider subscription request before one injected effect authority call, reuses active state until the renewal lead, honours the retry window, and settles completed, rejected or indeterminate outcomes; it never performs the provider effect itself
• ./ecosystem-connection-sync journals adapter health changes, gates on the sync capability, reads one provider page from the stored cursor, ingests it through bound rooms, and advances the cursor last. The adapter, resolver and failure mapping are injected ports, so hosts keep credential-backed adapters and their transport error type
• ./ecosystem-delivery-dispatcher is the outbound delivery gate behind the outbox (createCommunicationDeliveryDispatcher, CommunicationDeliveryError and the context/adapter resolver ports). It requires a valid payload identity, a matching resolved context, host target verification (verifyTarget), adapter placement and send support, a healthy connection, and an unchanged context after the health check; provider ambiguity becomes a reconciliation-required error. It implements the delivery port that integration.communication-os-runtime CommunicationOsOutboxAgentHostProviderV1 consumes; adapters are structural
• ./discord-community-installations owns the Discord guild installation lifecycle for community intelligence (createCommunicationCommunityIntelligenceRuntime): verifier-evidence-bound authorization, policy update and revocation with tenant/workspace-scoped identifiers and an order-independent request digest (WebCrypto SHA-256, base64url), plus public projections that never expose credential references. Persistence and the Discord verifier are injected ports typed on lib.communication-spec discord-community models

Boundary

Source checks and artifact declarations

typecheck uses tsconfig.json and checks all source tests without emitting declarations. Its TypeScript incremental state stays in .cache/ so a package artifact rebuild does not discard source-check progress. Unit tests remain a separate required acceptance check.

Artifact builds use tsconfig.build.json to emit production declarations. Test, spec, story and test-support files are excluded as compiler roots; files referenced by production signatures remain reachable and are still checked and emitted. The public delivery-routing.fixture entry is retained. This scope separates artifact generation from test verification: a successful package build does not replace the full source typecheck and unit tests.

This package depends on @lssm-tech/lib.communication-spec and lower-level libs only. It must not import @lssm-tech/example.communication-os, examples/*, or module packages.

Matrix runtime channel

The runtime recognizes matrix as a backend-neutral channel type with default send capability and human-review expectations for sensitive replies. Matrix SDK behavior belongs in integration provider packages, not in this runtime package.

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.