module.communication-os

@lssm-tech/module.communication-os

Production landing consumers pass dataMode="live" to LandingPage when counts and metrics come from a scoped live workspace. Preview remains the default for examples and visual fixtures; live mode replaces demo labeling, derives module counts from the supplied projection, and removes the synthetic-data disclosure.

Website: https://contractspec.io

CommunicationOS is the canonical messaging protocol, embeddable communication hub, and standalone AI-native messaging product for the ContractSpec ecosystem.

Build and artifact boundaries

The build uses explicit entries from the existing source export map and freezes both export maps. Unbundled module emission shares React contexts across public provider, hook, component and compatibility paths. Existing native page families keep their condition mappings; private file discovery cannot add public exports.

The Calm Signal shell imports the Design System's public Button/ButtonLink leaves so unrelated optional widgets do not become startup requirements. Its four UI/i18n leaves are qualified through direct Bun SSR, a Node-target consumer bundle, browser-target bundling, and strict declarations. The Next-based ButtonLink requires framework bundling for raw Node ESM resolution. Pure provider/hook leaves are also tested directly in Node. Native export/declaration checks do not establish a native-device or all-UI qualification.

Artifact evidence and remaining campaign gates are recorded in docs/refactoring/lssm-ecosystem/evidence/w2-communication-module-context/.

Package Boundary

CommunicationOS is delivered through three layers:

• @lssm-tech/lib.communication-spec and @lssm-tech/lib.communication-runtime define the canonical protocol, journal, projections, authority, and compatibility behavior.
• This module exposes reusable full routes, contextual slots, and provider-neutral UI.
• @lssm-tech/bundle.communication-os composes the reusable application kit consumed by standalone and host-app shells.

The module remains thin:

• Canonical contracts live in @lssm-tech/lib.communication-spec.
• Backend-neutral lifecycle, governance, state, ingestion, records, and replay helpers live in @lssm-tech/lib.communication-runtime.
• Examples, fixtures, and proof/replay data live in @lssm-tech/example.communication-os.
• Reusable low-level presentational communication blocks live behind @lssm-tech/lib.design-system/components/communication-os.
• Reusable CommunicationOS workflow UI and screen composition live in this module under @lssm-tech/module.communication-os/ui.
• The Calm Signal shell accepts an optional product-local sign-out action. Its EN/FR/ES label names hCircle explicitly so a product-session exit is never mistaken for a central Passport or ecosystem-wide logout.
• @lssm-tech/module.communication-os/hub re-exports canonical browser-safe v2 request, result, error, cursor, and projection DTOs. Hub journal and policy contexts are JSON-safe and no longer expose unknown payload records.
• Command-inbox helpers for message-originated commands are exposed through @lssm-tech/module.communication-os/core/command-inbox and delegate to the backend-neutral runtime.
• The Feature Hub registers the service-only communication.support.internal-note.create@1.0.0 and communication.support.internal-note.verify@1.0.0 operations. Private note bodies remain encrypted CommunicationOS data; downstream SupportOS surfaces receive only redacted note and evidence references.

CommunicationOS says: "Here is what changed, what matters, who owns it, what is blocked, what can be replied to, and what can safely happen next."

What It Is

• An end-user unified messaging product for web/PWA, Expo, and Tauri.
• An embeddable feature hub for full routes and contextual panels.
• A spec-first messaging protocol and append-only projection runtime.
• A normalized communication event model.
• A governed reply drafting and handoff contract surface.
• An agent-callable communication layer.
• A deterministic generic runtime for testable conversation-to-work flows.
• A reusable foundation for future vertical consumers and downstream applications.

What It Is Not

• Not a single-domain record inbox.
• Not a customer-support-only tool.
• Not a voicebot-only product.
• Not a free-form assistant widget.
• Not a provider-owned parallel source of truth.

The standalone product and embedded inbox are both consumers of the same canonical contracts and bundle. Matrix, email, SMS, Slack, Telegram, WhatsApp, and Discord remain adapters.

Route discovery and action affordances now share the canonical communication-os.* capability vocabulary from @lssm-tech/lib.communication-spec/capabilities. Embedded hosts must project those identifiers directly; legacy comms.* capability aliases are not accepted by the UI gates.

Alignment With Existing ContractSpec Surfaces

• @lssm-tech/module.ai-chat owns conversational UI and model/provider workflows. CommunicationOS owns operational threads, normalized events, reply governance, and thread-to-action contracts.
• @lssm-tech/lib.notification and the deprecated @lssm-tech/module.notifications preserve notification contracts, entities, and helper compatibility. CommunicationOS owns canonical delivery composition, destination eligibility, and fallback; notification helpers grant no delivery authority.
• @lssm-tech/module.audit-trail owns audit aggregation. CommunicationOS emits audit-ready event payloads, policy refs, and replay evidence rather than creating a second audit console.
• @lssm-tech/module.lifecycle-core owns reusable lifecycle primitives. CommunicationOS documents domain-specific transitions for messages, threads, suggestions, replies, and handoffs.
• @lssm-tech/module.context-storage owns durable context snapshots. CommunicationOS threads, summaries, and source message references can become agent-readable context sources.
• @lssm-tech/module.product-intent-core owns product intent routing. CommunicationOS message intents can become product intent signals for downstream applications.

Core Concepts

• CommunicationThread: conversation container across channels.
• CommunicationMessage: normalized message with channel and participant context.
• CommunicationParticipant: person or system participating in conversations.
• ChannelAccount: participant identity on a specific channel.
• ChannelPolicy and ConsentRecord: channel-specific governance and permission state.
• IdentityLink: proposed or reviewed relation between participant identities.
• ThreadLink: generic bridge from a thread to a future vertical object.
• MessageIntent: classified intent with confidence and evidence.
• ReplyDraft: draft response with policy metadata and review state.
• HandoffPacket: structured transfer with summary, actions, questions, and evidence.
• CommunicationAction: extracted work candidate with source messages.
• CommunicationSummary: summary with source references, facts, actions, decisions, and risks.
• AgentSuggestion: non-canonical AI suggestion.
• CommunicationAuditEvent: audit-ready record of a communication action or policy decision.
• CommunicationCommandInboxItem: non-executing evidence packet for message-originated commands, including AIP controls and optional CompanyOS bridge status.

Voice-originated proposals

Voice-originated work follows the same communication-to-governance split as message-originated work. CommunicationOS can normalize a voice transcript, preserve source evidence, classify intent, summarize redaction classes, and propose actions. It does not authorize the action. For the canonical Voice-to-Product-Gap proof, the internal product-gap proposal is handed to CompanyOS for policy and PM approval, while the customer-facing promise remains blocked by default.

Product Invariants

• AI suggestions are not canonical truth.
• Identity links are proposed before trusted merge.
• Sensitive replies require policy checks.
• Channel constraints must be respected.
• Every sent reply must be auditable.
• Personal and organization spaces must remain strictly isolated.
• Agent sends require active room membership and an explicit, current, workspace-scoped authority grant.
• Missing, expired, or revoked authority fails closed immediately before dispatch.
• Provider views are replayable projections of the canonical append-only journal.
• Every generated handoff must link back to evidence.
• Future vertical links must not leak domain assumptions into the core.
• Command-inbox items are evidence, not execution authority; canExecute remains false and blocked signals fail closed.

Agent Behavior

Agents may:

• read thread context;
• summarize with source references;
• classify message intent;
• propose thread links, identity links, and actions;
• draft replies;
• prepare handoff packets;
• request escalation;
• record human feedback.

Agents may not without explicit policy approval:

• send sensitive replies;
• merge identities;
• make commitments;
• mutate future vertical objects;
• bypass consent;
• ignore retention or channel policy;
• invent missing facts;
• treat a command-inbox item as permission to send, run shell commands, fetch credentials, or execute CompanyOS high-impact work.

Examples And Fixtures

• src/fixtures/ includes normalized event examples and evaluation fixtures for intent classification, identity rejection, policy blocking, reply review, handoff evidence, summary sources, and action extraction.
• src/examples/operational-inbox.example.ts shows a generic operational inbox consumer that groups threads and exposes review actions without becoming the core.
• src/examples/domain-pack.example.ts shows how a future domain pack links a thread to a neutral business object while keeping the core unchanged.
• src/examples/channel-capability-matrix.ts models email, SMS, voice transcript, and custom adapter capabilities without implementing full connectors.
• src/proof/communication-os.replay.ts replays the fixture surface into a compact proof object.

Future Consumer Model

Future vertical consumers extend CommunicationOS through ThreadLink, domain-specific intent labels, reply policies, escalation rules, handoff templates, action extraction rules, and evaluation fixtures. CommunicationOS core owns communication primitives. Domain packs own vertical meaning. Deployment-specific apps and downstream applications own UI and workflow composition.

Roadmap

• Phase 0: inventory and alignment — align with ai-chat, audit, notifications, lifecycle, context storage, product intent, docs, package exports, and examples conventions.
• Phase 1: contracts and normalized events — public contract map, normalized event examples, invariants, and fixtures.
• Phase 2: AI triage and governed assistance — classify, summarize, extract actions/decisions/risks, draft replies, create handoffs, propose links, escalate, block by policy, and record feedback.
• Phase 3: generic operational inbox consumer — minimal consumer example for grouping, review, handoff, escalation, and archive flows.
• Phase 4: domain packs — generic extension guide and neutral domain pack example.
• Phase 5: advanced connectors and voice strategy — capability matrix, voice transcript strategy, and deployment-specific workflow features as future layers.

Architecture

• src/communication-os.capability.ts defines the module capability surface.
• src/communication-os.feature.ts defines the feature entrypoint with operations and events.
• @lssm-tech/lib.communication-spec owns canonical enums, models, operations, queries, events, capabilities, and validation helpers.
• @lssm-tech/lib.communication-runtime owns backend-neutral governance, lifecycle, state, ingestion, records, replay/scenario helpers, and deterministic runtime behavior.
• src/core/ and src/core/contracts/ are compatibility shims for existing module import paths; new code should import from the split lib packages.
• src/docs/ contains module-specific public docblocks.
• src/ui/ contains reusable workflow UI that accepts caller-provided CommunicationOS data and does not import example fixtures.
• The Calm Signal shell accepts authorized space labels as data; it does not manufacture personal, team, or company spaces when a host has not supplied them.
• @lssm-tech/example.communication-os owns examples, fixtures, and replay/proof evidence as a standalone adopter package and composes the module UI with local fixture adapters.

Public Entry Points And Compatibility Classification

Compatibility shims are intentionally additive for the current release. Do not remove module ./core* exports until a release note classifies the break and downstream imports have a migration window.

Local Commands

• bun run build
• bun run typecheck
• bun run lint:check
• bun run test

Voice signal summary UI

@lssm-tech/module.communication-os/ui now exports VoiceSignalSummaryCard and optional voiceSignal data on CommunicationOsPreviewData / MessagingWorkspaceData. This keeps voice-originated evidence reusable at the module boundary without importing example fixtures or runtime providers.

Quick-start

# In your consuming app or bundle
bun add @lssm-tech/module.communication-os

Minimal wiring (Next.js App Router route page):

// app/comms/inbox/page.tsx  (server component)
import { InboxPage } from '@lssm-tech/module.communication-os/ui';
import { resolvePresentationData } from '@lssm-tech/lib.communication-runtime';
import { EMPTY_ROLEMORPH } from '@lssm-tech/module.communication-os/ui';

export default async function InboxRoute() {
  const data = await resolvePresentationData(); // your data layer
  return <InboxPage data={data} personalization={{}} rolemorph={EMPTY_ROLEMORPH} />;
}

With persona-aware personalization and capability gating:

// app/comms/inbox/page.tsx  (server component)
import { InboxPage, EMPTY_ROLEMORPH } from '@lssm-tech/module.communication-os/ui';
import { resolveRoleMorph } from '@lssm-tech/lib.surface-runtime/rolemorph';
import {
  personalizationForActorKind,
  toRoleMorphProjection,
} from '../../../lib/companyos-rolemorph-projection';

export default async function InboxRoute() {
  const [data, roleMorphResult] = await Promise.all([
    resolvePresentationData(),
    resolveRoleMorph(),
  ]);
  return (
    <InboxPage
      data={data}
      personalization={personalizationForActorKind(roleMorphResult.actor.kind)}
      rolemorph={toRoleMorphProjection(roleMorphResult)}
    />
  );
}

Both personalization and rolemorph are optional — defaults are {} and EMPTY_ROLEMORPH (fail-closed).

Template integration pattern

Bundle templates (InboxTemplate, ThreadsTemplate, HandoffsTemplate, ThreadDetailTemplate from @lssm-tech/bundle.managed-companyos) accept the same optional props and set providers once at the template boundary:

// In a bundle template (already 'use client')
import {
  CommsCapabilityProvider,
  CommsPersonalizationProvider,
  EMPTY_ROLEMORPH,
  type ResolvedPreferenceProfile,
  type RoleMorphProjection,
} from '@lssm-tech/module.communication-os/ui';

export function InboxTemplate({
  viewModel,
  personalization = {},
  rolemorph = EMPTY_ROLEMORPH,
}: InboxTemplateProps) {
  return (
    <CommsCapabilityProvider capabilities={rolemorph.capabilities}>
      <CommsPersonalizationProvider profile={personalization}>
        {/* organisms read density/tone/capability from context — no prop drilling */}
      </CommsPersonalizationProvider>
    </CommsCapabilityProvider>
  );
}

Rules:

• Set providers once at the route or template boundary — never inside organisms or molecules.
• CommsCapabilityProvider without a parent fails closed: useCommsCapability(key) returns false for all keys.
• personalization defaults to {} — all hooks return their comfortable/default/normal fallback.
• Hosts that persist explicit preferences import the canonical value sets, balanced defaults and strict parser from @lssm-tech/module.communication-os/ui/personalization/preference-values (COMMS_PREFERENCE_VALUES, DEFAULT_COMMS_PREFERENCES, readCommsPreferenceProfile). Storage location and keys stay host-owned.

Atomic layer guide

@lssm-tech/module.communication-os/ui follows atomic design with a strict 5-layer chain:

domain data → *presenter() → viewmodel → *Template → *Page
                                             ↑
                  organisms compose ─────────┘
                  molecules compose organisms
                  atoms compose molecules

Variant token system (cva)

All atoms and top-level molecules use class-variance-authority with these canonical tokens:

pace (motion: fast / normal / slow / instant) is resolved by useCommsPace() internally — not a cva variant.

Capability gating

import { CapabilityGate } from '@lssm-tech/module.communication-os/ui';
import { COMMS_HANDOFF_KEYS } from '@lssm-tech/lib.communication-spec/capabilities';

// Omit affordance when capability absent (fail-closed)
<CapabilityGate capability={COMMS_HANDOFF_KEYS.APPROVE}>
  <HandoffApproveButton onClick={handleApprove} />
</CapabilityGate>

// Auditor fallback — surface stays meaningful
<CapabilityGate
  capability={COMMS_AI_CAPABILITY_KEYS.FULL}
  fallback={<EvidencePanel thread={thread} />}
>
  <Composer thread={thread} />
</CapabilityGate>

Never use isReadOnly prop — it is deprecated. Use CapabilityGate + fallback instead.

Personalization hooks

// Inside CommsPersonalizationProvider tree
import {
  useCommsDensity,
  useCommsGuidance,
  useCommsPace,
} from '@lssm-tech/module.communication-os/ui';

function MyAtom() {
  const density  = useCommsDensity();   // 'compact' | 'comfortable' | 'spacious'
  const guidance = useCommsGuidance();  // 'subtle' | 'default' | 'verbose'
  const pace     = useCommsPace();      // 'fast' | 'normal' | 'slow' | 'instant'
  // pass density as cva variant, use guidance for help-text expansion
}

Live room controller

@lssm-tech/module.communication-os/ui/hooks/useCommunicationOsLiveRoom is the embedded live-room controller (initial load with a 5 s retry that reports unavailable only after three failures, realtime plus 15 s refresh, send with denial detection through the first active outbound binding, governed-work, agent, identity and provider actions). Hosts inject a CommunicationOsLiveRoomApi (transport, scope, redirects); the pure connection rules live in ./ui/hooks/live-room-state. appendMessage adds a confirmed message once (deduplicated by id).

Send outbox

@lssm-tech/module.communication-os/ui/hooks/useCommunicationOsSendOutbox accepts a message locally before delivery so a failed send is never lost. Each message keeps one idempotency key for its whole life; entries replay in FIFO order on online, when the tab becomes visible, on host request (for example when the live room reconnects) and after exponential backoff (2 s to 60 s, 8 automatic attempts). A host classifier maps failures to denied (terminal, never retried), rejected (manual retry), unauthorized or transient (backoff). Rows expose queued, sending, sent, failed and denied, plus retry, discard, a waiting count and a notice for live region announcements. Hosts inject a CommunicationOutboxStore scoped to one principal, workspace and room; delivery does not depend on realtime. The pure rules live in ./ui/hooks/send-outbox-state and ./ui/hooks/send-outbox-replay.

Meeting threads

MeetingList and MeetingThreadDetail (from ./ui/organisms) render the conversation around an OPA meeting: OPA owns the meeting (scheduling, preparation, private notes, transcripts, outcomes); CommunicationOS owns its room, shared agenda, participants, shared notes, and follow-ups as governed work (communication.meeting_thread.*@1.0.0). The organisms are presentational and token-styled: hosts pass view models, capability flags (canStart, canEdit), hrefs (conversation, OPA workspace), and save callbacks. Copy lives under commOs.organisms.meetings.* in en/fr/es. The CompanyOS monolith mounts them at /companyos/communication-os/meetings.

Storybook workflow

Visual state contracts live beside their components as <ComponentName>.visual-scenario.ts. Complex JSX, providers, icons, and callbacks remain in typed <ComponentName>.story-bindings.tsx modules. Executable CSF is generated deterministically under generated/storybook/.

# Regenerate or verify this package's committed CSF catalog
bun run --cwd packages/domains/communication/module storybook:generate
bun run --cwd packages/domains/communication/module storybook:check

# Run the monorepo Storybook host
bun run storybook

The published ./storybook entrypoint exposes an opt-in catalog manifest for downstream verticals. Generated files are review artifacts and must never be edited directly. Chromatic capture is permitted only for scenarios marked with synthetic or sanitized data and capture.external: true.

Feature Hub profile

./hub exposes the CommunicationOS define/install entrypoints, provider-neutral thread-store and delivery ports, and a small view model. The profile mounts at /communications and derives operation refs from CommunicationOsFeature. Delivery is optional, so inbox reading remains available in degraded mode. The catalog includes threads/messages, accounts/contacts, identity review, consent/retention, triage/summary/drafts/actions, handoffs/escalations, audit, and replay.

Standalone declaration exports keep their existing public subpath names. The shared builder preserves their original declaration suffix and copies checked source declarations into dist, without overwriting emitted implementation types.