lib.communication-runtime
Backend-neutral CommunicationOS runtime, governance, lifecycle, state, ingestion, records, and replay helpers.
@lssm-tech/lib.communication-runtimebun add @lssm-tech/lib.communication-runtimeManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
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./governanceresolves through./src/governance/index.ts./ingestionresolves through./src/ingestion/index.ts./lifecycleresolves through./src/lifecycle/index.ts./recordsresolves through./src/records/index.ts./replayresolves through./src/replay/index.ts./stateresolves through./src/state/index.ts./runtimeincludes domain-command planning and persistence helpers./command-inboxexposes the fail-closed command inbox projection helper./delivery-routingexposes deterministic preference, eligibility, intent, and fallback preparation;./delivery-routing.fixtureexposes its sealed test fixture- the root export includes
createInMemoryCommunicationJournal,projectCommunicationJournal,evaluateCommunicationContentPolicy, andevaluateMessagingSendAuthority ./ecosystem-oauthexposes the provider-neutral OAuth coordinator, state codec/replay ports, provider port, and deterministic test store./ecosystem-governed-workexposes persisted work projections and lifecycle commands without importing example or application packages./ecosystem-conversation-referencesrecords authenticated provider conversation addresses in the scoped journal and resolves only active, non-revoked references for later delivery admission./ecosystem-messaging-serviceresolves opaque, scope-bound attachment IDs before appending public-safe file metadata to the immutable message event./support-internal-notesvalidates private Support note commands, protects content before persistence, and returns body-free evidence projections./agent-lifecycle-projectionvalidates immutable, digest-bound progress and help projections before an injected canonical-conversation sink is called; the projection grants no effect authority./canonical-agent-conversationvalidates and resolves exact scoped conversation/session bindings./ingress-admissionpersists the authenticated receipt before context compilation, applies deterministic admission, and resumes an already durable decision through an idempotent normalized-ingress reference./channel-admissionlinks channel accounts to principals: Connect-backed admission, one-time pairing by the exact account, quarantine and terminal revocation. Sender claims (names, mentions, threads, forwards) are evidence only;createChannelAdmissionContextCompilerV1feeds ingress admission./agent-surface-controlclaims 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-coordinatorjournals 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-syncjournals adapter health changes, gates on thesynccapability, 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-dispatcheris the outbound delivery gate behind the outbox (createCommunicationDeliveryDispatcher,CommunicationDeliveryErrorand the context/adapter resolver ports). It requires a valid payload identity, a matching resolved context, host target verification (verifyTarget), adapter placement andsendsupport, a healthy connection, and an unchanged context after the health check; provider ambiguity becomes a reconciliation-required error. It implements thedeliveryport thatintegration.communication-os-runtimeCommunicationOsOutboxAgentHostProviderV1consumes; adapters are structural./discord-community-installationsowns 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 onlib.communication-specdiscord-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.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
7 declarations
@lssm-tech/lib.agent-protocol-specworkspace:^
Read the package manual ↗@lssm-tech/lib.communication-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.forms-runtimeworkspace:^
Read the package manual ↗@lssm-tech/lib.schemaworkspace:^
Read the package manual ↗@lssm-tech/lib.lifecycleworkspace:^
Read the package manual ↗
Declared capabilities
Backend-neutral CommunicationOS runtime, governance, lifecycle, state, ingestion, records, and replay helpers.
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit --tsBuildInfoFile .cache/typecheck.tsbuildinfo