@lssm/lib.communication-spec

Identity resolution uses [email protected], [email protected], and [email protected]. Account outputs exclude credential references; identity merges remain human-reviewed and auditable.

Governed work uses canonical [email protected], [email protected], and [email protected]. These operations cover identity review, drafts, actions, handoffs, escalations, triage, summaries, agents, consent, retention, and policy while keeping scope and transition authority on the server. The v1 operations remain exported only for deliberate migration.

Canonical CommunicationOS contracts for threads, messages, spaces, rooms, scoped principals, memberships, connections, reply drafts, handoffs, realtime state, operations, queries, events, capabilities, and validation helpers.

The additive Discord community-intelligence surface models multiple guilds per workspace with explicit staff and managed-community trust zones, guild-local specialties and roles, protected typed provider events, evidence-backed insights, restricted coaching scorecards, and Kaizen digests. Existing v1 normalized message ingestion remains unchanged.

Canonical capability namespace

COMMUNICATION_OS_CAPABILITY_KEYS is the single capability vocabulary for route discovery, role projections, contextual slots, and UI action gates. All capability identifiers use the communication-os.* namespace. The legacy comms.* strings are no longer capability identifiers; similarly named comms.thread.summarize, comms.reply.draft, and comms.handoff.suggest values remain operation keys and are not authorization capabilities.

The direct public entry point ./capabilities/communication-os.capability-ids exposes the canonical keys and the exact subset used by the 23-route CommunicationOS hub.

Private Support notes use the additive [email protected] command and [email protected] query. Their public inputs never carry tenant, workspace, or actor authority; verification is redacted and never exposes note content.

The additive v2 ecosystem surface models strictly scoped personal and organization spaces, human/agent/system principals, hybrid connection placement, explicit encryption modes, cursor sync, messaging state, and revocable agent authority. Message v2.1 accepts optional public-safe attachment metadata backed by opaque, scope-authorized storage references; raw bytes and private storage locations are never part of the public message projection. Provider OAuth start accepts an optional provider key so Google and Microsoft mail can coexist under the email network without mutable process-global selection. Authenticated callback invalidations use the additive communication.connection.sync.invalidated event; they request sync and never become user or agent instructions. Provider subscription create and renewal use a separate durable lifecycle: requested is appended before Runtime Node dispatch, active requires an exact work-order receipt, definitive failed state obeys retryability, and indeterminate retains custody without automatic retry. [email protected] is the canonical JSON transport contract. It accepts only client intent plus replay keys; tenant, author, message identifier, revision, and timestamps are derived and returned by the authorized server. [email protected] likewise derives tenant authority from the session while retaining explicit workspace and space selection. [email protected], [email protected], [email protected], and [email protected] accept no client-selected scope. [email protected] accepts only the room name, kind, and replay key; tenant, workspace, space, principal, identifiers, revisions, and timestamps remain server-owned. CommunicationSpec remains canonical; Matrix and proprietary networks are adapters. All v1 contract keys remain exported unchanged.

Domain-command helpers classify agent-callable CommunicationOS actions such as reply drafting, reply sending, handoff creation, and escalation requests. These helpers are contract-only: they describe authority, autonomy, approval requirements, and semantic violations without provider adapters, persistence drivers, outbound sends, or runtime side effects.

Command-inbox contracts extend domain-command planning with non-executing inbox items, fail-closed status, AIP control refs, and CompanyOS bridge evidence. These contracts describe review/approval state only; they do not grant send or work-execution authority.

Agent omnichannel contracts

The additive V1 omnichannel surface keeps agent communication provider-neutral:

• agent-communication binds agent applications, runs, tasks, help requests, and background results through opaque refs.
• agent-lifecycle-projection publishes immutable, non-authoritative run, task, help, approval, and terminal status into the canonical conversation. A help projection must bind the exact durable help request and checkpoint.
• canonical-agent-conversation binds one scoped conversation to its exact session, participants, channel identities, origin, revision, and digest.
• ingress-admission separates the durable authenticated receipt from the deterministic connection, identity, pairing, membership, mention, and consent decision. Unresolved identity or membership quarantines rather than becoming model input.
• agent-surface-control binds help, approval, steer, queue, pause, cancel, and branch requests to one conversation, run, human identity proof, authority decision, expiry, idempotency key, and durable result.
• channel-routing provides an open channel key plus well-known email, calendar, SMS, Slack, Teams, Discord, Telegram, WhatsApp, Matrix, in-app, push, webhook, web-chat, and internal-chat keys.
• channel-preferences records typed user choices with authority: "preference_only"; each set has exactly one event, automation, feature, application, product, space, person, or stable platform-default resolution target plus explicit inherited parent-set refs. Resolution follows event/automation, feature/application, product, space/person, then platform default. A preference never authorizes delivery.
• delivery-intent, delivery-progress, and delivery-fallback carry content proof, opaque event/automation/feature/application/product classification, idempotency, receipts, reconciliation, policy, eligibility, and evidence refs with effectAuthority: "none". Route, preference, resolution, intent, progress, and fallback bindings retain revisions or digests; attempted fallback binds the exact prior progress ref and digest.

Provider acceptance remains distinct from delivered/read evidence. An ambiguous prior effect must be reconciled before an alternate route can be selected. The contracts contain no provider credentials, runtime effects, or persistence implementation.

The domain-command outbox schema carries optional reconciliation custody bindings. An indeterminate provider outcome records the exact Runtime Node work order digest and evidence refs before its lease can leave effectful execution.

Public Entry Points

• . resolves through ./src/index.ts
• ./types resolves through ./src/types/index.ts
• ./types/domain-command resolves through ./src/types/domain-command.ts and includes command-inbox contracts
• ./commands resolves through ./src/commands/index.ts
• ./queries resolves through ./src/queries/index.ts
• ./events resolves through ./src/events/index.ts
• ./capabilities resolves through ./src/capabilities/index.ts
• ./validation resolves through ./src/validation/index.ts
• ./contracts/agent-communication resolves agent profiles and lifecycle links
• ./contracts/agent-lifecycle-projection resolves evidence-bound agent status and help projections for canonical conversations
• ./contracts/canonical-agent-conversation, ./contracts/ingress-admission, and ./contracts/agent-surface-control resolve canonical continuity, deterministic admission, and origin-neutral agent controls
• ./contracts/channel-routing and ./contracts/channel-preferences resolve open route keys and typed non-authoritative preferences
• ./contracts/preference-resolution resolves typed preference targets and the most-specific-to-platform-default hierarchy; it performs no runtime resolution
• ./contracts/delivery-intent, ./contracts/delivery-progress, and ./contracts/delivery-fallback resolve the fail-closed delivery artifact set
• ./contracts/delivery-eligibility resolves evidence-only route eligibility across consent, policy, grants, quiet hours, limits, provider health, cost, and channel-specific constraints; it grants no delivery authority
• ./fixtures/agent-omnichannel resolves the deterministic no-network fixture
• ./contracts/ecosystem-messaging.models resolves v2 spaces, rooms, principals, connections, messages, and authority grants
• ./contracts/ecosystem-workspace.operations and ./contracts/ecosystem-message.operations resolve additive v2 operations
• [email protected] and [email protected] expose server-selected navigation without accepting browser scope authority; their v2 predecessors remain exported for compatibility during migration
• ./contracts/ecosystem-messaging.events resolves additive v2 journal/realtime events
• The root and ./contracts exports include browser-safe v2 request, result, error, cursor, journal, realtime, and projection DTOs. Public extension payloads use CommunicationJsonObjectDto rather than unknown records.
• ./contracts/ecosystem-webhook.operations resolves authenticated, replay-safe provider webhook ingress
• [email protected] and [email protected] derive an allowlisted callback return origin from the authenticated host issuer, so embedded CompanyOS and standalone CommunicationOS return to their own shell. define scope-bound provider onboarding with PKCE, one-time opaque state, safe return paths, and credential-reference-only completion
• ./capabilities/ecosystem-messaging.capabilities resolves v2 messaging capability constants
• ./capabilities/communication-os.capability-ids resolves the canonical route and action capability identifiers

TenantBoundCommunicationIngestionSchema is an additive R001 contract exposed through ./contracts/ingestion. It binds the existing normalized ingestion record to the canonical F002 CompanyOS tenant-governance envelope and validates subject, consent, idempotency, and evidence/replay alignment without introducing provider or webhook behavior.

Persistence wave

CommunicationOS persistence stays contract-first. communicationOsSchemaContribution, communicationOsPersistencePlans, and createCommunicationOsMutationDescriptor expose portable schema and governed [email protected] envelopes for managed/BYOK providers. The domain command reference remains the write authority; provider packages execute SQL/Drizzle outside this spec package. Local/PgLite support is compatibility binding metadata, not an ownership mode.

Boundary

This package owns canonical communication contracts. Runtime behavior, examples, fixtures, proof/replay, and product composition live in separate packages. Deprecated module shims may re-export this surface for compatibility only.

Approval-bound sequences

CommunicationSequenceIntentSchema is the additive, provider-neutral contract for scheduled outbound intent. It binds the exact recipient, content proof, channel, side effect, schedule/expiry, policy and consent refs, kill switch, ActionPacket, approval request, and approval fingerprint. Runtime schedulers must revalidate those bindings and controls before every initial claim and retry. CommunicationSequenceApprovalTargetSchema is the canonical versioned human approval payload. Its deterministic fingerprint binds the sequence/version, tenant, recipient set, content proof, channel/effect, schedule and policy versions, and expiry. The approval request and ActionPacket evidence must carry that same fingerprint.

Matrix channel

ChannelTypeEnum includes matrix for deployments that ingest Matrix room events or send governed replies to Matrix rooms. Matrix bridge metadata is owned by integration contracts; this package only owns the canonical channel value.

Published browser conditions select the emitted browser artifacts alongside existing Node/Bun/type targets. Export keys and source behavior are preserved; this packaging metadata does not activate providers or grant execution authority.