0.4.6

May 25, 2026 · 5 packages · 26 unique changes · 6 release entries

appslibsmodulesBreaking changes

This release affects the contracts, sharedLibs, solutions familyies.

Run contractspec connect adoption resolve --family contracts to see how it impacts your project.

Release summaries

communication-os-loop-b-governance-runtime
Add Loop B governance contracts, runtime mutation helpers, policy evaluation ribbon, and live evaluator wiring across the CommunicationOS surface.
maintainer
Loop B adds 8 mutation helpers, a recordAuditEvent audit helper, governance state maps, new status types, 7 operation contracts (6 commands + 1 query), 7 domain handlers, and a PolicyEvaluationRibbon atom threaded via optional policyEvaluator prop — all additive and back-compat.
integrator
Integrators can now inject a policyEvaluator prop into CommunicationOsPreview, ComposePage, ComposeTemplate, MessagingWorkspace, or MessageComposerInput to display live policy verdicts in the compose UI without importing the runtime lib.
communication-os-loop-c
BREAKING: Rename all 23 CommunicationOS operation keys from communicationOs.* to communication.* namespace. Add thread-link lifecycle, live audit accumulation, defineQuery taxonomy parallels, and MCP exposure via generator tool + stdio server.
maintainer
Loop C adds 6 task clusters across 5 packages. C1a: HandoffList additive callbacks (onApprove, onReject) — additive only. C1b: policyEvaluator debounce (300ms) in CommunicationOsPreview example wrapper — example only. C3a (BREAKING): 23 operation keys renamed communicationOs.* → communication.*. Pre-step audit confirmed 0 external consumers. Blast radius bounded to this monorepo. C2a: 8 defineQuery siblings added for read ops; deprecated originals carry stability=deprecated, removal scheduled at example.communication-os@1.1.0 (Loop D). C2b: ThreadLinkStatus type, threadLinkStatuses map, activateThreadLink + unlinkThread runtime mutations, thread-link UI props (LinkedObjectChip/ThreadHeader/ThreadDetailPage), and 2 new contracts + handlers. C2c: CommunicationOsPreview gains live auditEvents state + addLiveAuditEvent accumulator wired to all governance actions. C3b: contracts-mcp-gen generator tool (generateMcpToolSchemas) + communicationos-mcp MCP server (24 tools, stdio) + example ./mcp static catalog (COMMUNICATION_OS_MCP_TOOLS). C1c security review conducted — finding deferred: identity.merge auth escalation to admin is Loop D.
integrator
BREAKING rename: update all operation key references from communicationOs.* to communication.*. Find-and-replace: sed -i 's/communicationOs\./communication./g' across contract key strings, handler registrations, audit event keys, and test fixtures in any consumer repo. New: thread-link lifecycle props (onUnlinkThread on ThreadDetailPage), live audit events in CommunicationOsPreview. New: import COMMUNICATION_OS_MCP_TOOLS from @lssm-tech/example.communication-os/mcp for a static MCP manifest. New: use generateMcpToolSchemas from @lssm-tech/tool.contracts-mcp-gen to derive MCP schemas from any OperationSpec iterable. Recommended: switch deprecated commands to defineQuery siblings before example.communication-os@1.1.0 removes them.
communication-os-runtime-core
Move CommunicationOS runtime and replay surfaces out of the module into runtime and example packages.
maintainer
Runtime helpers now live in a backend-neutral lib and example replay data lives in a standalone example package.
integrator
Existing module runtime imports keep working through deprecated shims, while examples/fixtures/proof imports must move to the example package.
contractspec-i18next-adapter
Add an optional ContractSpec-first i18next adapter for downstream interoperability.
maintainer
The translation runtime now exposes an optional `./i18next` subpath while keeping the root runtime and ContractSpec registry i18next-free.
integrator
Apps that already use i18next can initialize isolated instances or add resource bundles from ContractSpec translation catalogs without making i18next canonical.
customer
Multilingual applications gain a safer migration path from ContractSpec translations to i18next-powered surfaces while preserving locale metadata and diagnostics.
m2-communication-runtime-v2
Additive: M2 communication-runtime V2 ThreadLink mutations (kindId/instanceId); ThreadListItem V2 fields; cockpit ConversationGraphView wiring.
maintainer
communication-runtime: V2 ThreadLink mutation signatures use kindId + instanceId (was objectType + objectId). linkThread runtime API updated. RuntimeThread.links items, RuntimeEvent payload, threadLinkStatuses key format, and AuditableMutationRecord payload all updated to V2 shape. module.communication-os: ThreadListItem gains linkedKindId? + linkedInstanceId? as additive V2 fields. V1 fields (linkedObjectType, linkedObjectId) deprecated in JSDoc but still present. cockpit example: fixture migrated to V2; WorkGraphScreen uses ConversationGraphView template; ThreadDetailScreen shows V2 kindId::instanceId reference.
integrator
communication-runtime: update all direct callers of activateThreadLink, unlinkThread, and linkThread to use the V2 (kindId, instanceId) signature. Update any code that reads AuditableMutationRecord.payload.objectType/objectId to use payload.kindId/payload.instanceId. module.communication-os: prefer linkedKindId + linkedInstanceId on ThreadListItem; V1 linkedObjectType/linkedObjectId are deprecated and will be removed in a future release.
t1-i18n-preference-resolver
preference resolver helpers + OverrideScope mapping (additive)
maintainer
preference resolver helpers + OverrideScope mapping (additive)
integrator
preference resolver helpers + OverrideScope mapping (additive)

Deprecations

- @lssm-tech/module.communication-os/core/runtime* are compatibility shims for @lssm-tech/lib.communication-runtime.
- ThreadListItem.linkedObjectId — deprecated; use linkedInstanceId.
- ThreadListItem.linkedObjectType — deprecated; use linkedKindId.

Migration guide

Update activateThreadLink / unlinkThread / linkThread call sites
Required
V2 signatures replace objectType/objectId parameters with kindId/instanceId. The composite key format also changed from `threadId::objectType::objectId` to `threadId::kindId::instanceId`.
1. Replace activateThreadLink(state, threadId, objectType, objectId) → activateThreadLink(state, threadId, kindId, instanceId).
2. Replace unlinkThread(state, threadId, objectType, objectId) → unlinkThread(state, threadId, kindId, instanceId).
3. Replace runtime.linkThread(threadId, objectType, objectId) → runtime.linkThread(threadId, kindId, instanceId).
4. Update payload reads: record.payload.objectType → record.payload.kindId, record.payload.objectId → record.payload.instanceId.
5. Run: bun test packages/libs/communication-runtime
Migrate ThreadListItem consumers to V2 linked fields
Use linkedKindId and linkedInstanceId instead of the deprecated V1 fields.
1. Replace threadItem.linkedObjectType with threadItem.linkedKindId.
2. Replace threadItem.linkedObjectId with threadItem.linkedInstanceId.
3. For CommunicationOS links, kindId should be 'communication.thread-linked-object'.
Rename communicationOs.* keys to communication.*
Required
String-replace `communicationOs.` with `communication.` in every consumer file that references CommunicationOS operation key literals. Applies to contract key strings, handler registrations, audit event keys, test fixtures, and any analytics or logging that references these keys by name.
1. Run: sed -i 's/communicationOs\./communication./g' $(grep -rl 'communicationOs\.' src/)
2. Run: bun x tsc --noEmit
3. Run: bun test
4. Verify no residual `communicationOs.` references remain in source.
Move CommunicationOS runtime imports to the runtime package
Required
Replace module runtime imports with `@lssm-tech/lib.communication-runtime`.
1. Move runtime imports to @lssm-tech/lib.communication-runtime.
Move CommunicationOS replay imports to the example package
Required
Replace module replay and fixture imports with `@lssm-tech/example.communication-os`.
1. Move replay/fixture imports to @lssm-tech/example.communication-os.
Import i18next helpers from the adapter subpath
Use `@lssm-tech/lib.translation-runtime/i18next` for downstream i18next projection instead of importing adapter internals.
1. Import `exportContractSpecToI18next`, `createI18nextInitOptions`, or `addContractSpecResourceBundles` from `@lssm-tech/lib.translation-runtime/i18next`.
2. Keep canonical translation contracts in `TranslationSpec` catalogs and use i18next resources as generated runtime interop data.
3. Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU plural/select/selectordinal messages through i18next.
Keep stable bundle identity separate from locale variants
Namespace translation bundles with stable ContractSpec keys and use `TranslationSpec.locale` for BCP 47 language tags.
1. Prefer bundle keys such as `commerce.checkout` rather than `commerce.checkout.en`.
2. Let the adapter map locales like `en-US`, `ar-EG`, and `zh-Hans` to i18next language resource keys.
3. Review adapter diagnostics for namespace, resource, ICU, and fallback projection issues.

Upgrade steps

Use V2 ThreadLink mutation APIs
assisted
Adopt kindId + instanceId parameter names aligned with rich-reference V2 vocabulary.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/module.communication-os, @lssm-tech/example.companyos-communicationos-operating-cockpit
1. Import activateThreadLink, unlinkThread from @lssm-tech/lib.communication-runtime.
2. Pass kindId (e.g., 'communication.thread-linked-object') and instanceId (object's id) instead of objectType/objectId.
3. Composite key in threadLinkStatuses map is now threadId::kindId::instanceId.
Wire ConversationGraphView in cockpit/inbox graph screens
assisted
The cockpit WorkGraphScreen now demonstrates how to build GraphNode/GraphEdge arrays from ThreadListItem data and render them via ConversationGraphView.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/module.communication-os, @lssm-tech/example.companyos-communicationos-operating-cockpit
1. Build nodes from thread data: { id: thread.id, kind: 'channel' } + { id: thread.linkedInstanceId, kind: 'escalated' }.
2. Build edges: { id, from: thread.id, to: linkedNodeId, kind: 'handoff' }.
3. Pass to ConversationGraphView with viewerRole='manager' for overview or 'engineer' for flow detail.
Review T1 I18n Preference Resolver adoption
manual
preference resolver helpers + OverrideScope mapping (additive)
Packages: @lssm-tech/lib.translation-runtime, @lssm-tech/lib.contracts-spec
1. Review the paired changeset summary and update consumers only if they use the affected package surface.
Inject a policyEvaluator for live compose UI verdicts
assisted
Pass an optional (body => PolicyEvaluationSummary) function to CommunicationOsPreview or MessagingWorkspace to enable the PolicyEvaluationRibbon above the compose area.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/example.communication-os, @lssm-tech/module.communication-os, @lssm-tech/example.messaging-app, @lssm-tech/example.companyos-communicationos-operating-cockpit
1. Implement a function matching (body: string) => PolicyEvaluationSummary from @lssm-tech/module.communication-os/ui.
2. Pass it as policyEvaluator={fn} to CommunicationOsPreview or MessagingWorkspace.
3. Optionally use evaluateDraftAgainstPolicies from @lssm-tech/lib.communication-runtime in app/example layers only — never inside module UI.
Use Loop B mutation helpers for action/identity/handoff governance
assisted
Import approveAction, rejectAction, mergeIdentity, rejectIdentityCandidate, approveHandoff, rejectHandoff, and evaluateDraftAgainstPolicies from @lssm-tech/lib.communication-runtime.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/example.communication-os, @lssm-tech/module.communication-os, @lssm-tech/example.messaging-app, @lssm-tech/example.companyos-communicationos-operating-cockpit
1. Each mutation helper accepts (state, payload) and returns { state, record: AuditableMutationRecord }.
2. Always check the current status before calling; invalid transitions return invalidTransitionRecord without throwing.
3. Handlers must call recordAuditEvent exactly once per invocation.
BREAKING: Rename all communicationOs.* keys to communication.*
manual
All 23 operation contract keys have been renamed. Consumers that reference these keys by string must update every reference.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/example.communication-os, @lssm-tech/module.communication-os, @lssm-tech/tool.contracts-mcp-gen, @lssm-tech/app.communicationos-mcp
1. Replace all `communicationOs.` prefixes with `communication.` in contract key strings, handler registrations, audit event keys, and test fixtures.
2. Full key list: inbox.list, thread.getDetail, thread.linkToObject, compose.draft, compose.approve, compose.block, compose.evaluateDraft, governance.check, governance.listPolicies, actions.approve, actions.reject, actions.extract, actions.list, handoff.approve, handoff.reject, handoff.create, handoff.list, identity.merge, identity.reject, identity.proposeLink, identity.listCandidates, audit.getTrail, audit.listEvents.
3. Update audit event keys emitted to addLiveAuditEvent in CommunicationOsPreview: they now use communication.* prefixes.
4. Pre-step audit confirmed 0 external consumers — blast radius is bounded to this monorepo.
Switch read operations to defineQuery siblings
assisted
Eight formerly defineCommand read operations now have defineQuery siblings. Deprecated originals will be removed in example.communication-os@1.1.0 (Loop D).
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/example.communication-os, @lssm-tech/module.communication-os, @lssm-tech/tool.contracts-mcp-gen, @lssm-tech/app.communicationos-mcp
1. Replace ListInbox → ListInboxQuery, GetThreadDetail → GetThreadDetailQuery, ListHandoffs → ListHandoffsQuery, ListIdentityCandidates → ListIdentityCandidatesQuery, ListActions → ListActionsQuery, GetAuditTrail → GetAuditTrailQuery, ListEvents → ListEventsQuery.
2. EvaluateDraftAgainstPolicies was already a defineQuery — no change required.
3. Deprecated originals will be removed at example.communication-os@1.1.0. Update before that release.
Wire thread-link lifecycle callbacks
assisted
ThreadDetailPage now accepts onUnlinkThread for unlink UI affordances.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/example.communication-os, @lssm-tech/module.communication-os, @lssm-tech/tool.contracts-mcp-gen, @lssm-tech/app.communicationos-mcp
1. Pass onUnlinkThread={(threadId, objectType, objectId) => { ... }} to ThreadDetailPage to enable the Unlink button in LinkedObjectChip.
2. Use activateThreadLink and unlinkThread from @lssm-tech/lib.communication-runtime in handler layers only — never import in module UI.
Consume the MCP tool catalog or use the generator
assisted
Use the static catalog or the generator to expose CommunicationOS contracts in any MCP server.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/example.communication-os, @lssm-tech/module.communication-os, @lssm-tech/tool.contracts-mcp-gen, @lssm-tech/app.communicationos-mcp
1. Import COMMUNICATION_OS_MCP_TOOLS from @lssm-tech/example.communication-os/mcp for a static, pre-built manifest of 24 non-deprecated tools.
2. Use generateMcpToolSchemas from @lssm-tech/tool.contracts-mcp-gen to derive MCP schemas from any Iterable<OperationSpec> — set includeQueries: true to include query specs.
3. Run communicationos-mcp via `bun src/index.ts` for a full stdio MCP server hosting all 24 tools.
Use the runtime lib for conversation-to-work flows
manual
Import `createCommunicationOsRuntime` and grouped lifecycle/governance/state helpers from `@lssm-tech/lib.communication-runtime`.
Packages: @lssm-tech/lib.communication-runtime, @lssm-tech/module.communication-os, @lssm-tech/example.communication-os
1. Keep adapters, durable stores, and external channel dispatch in integration/app layers.
2. Use thread links for generic business object binding.
3. Evaluate reply policy before approving or sending drafts.
Initialize i18next from ContractSpec exports
manual
Use generated resources and init options with caller-owned i18next instances for SSR and request isolation.
Packages: @lssm-tech/lib.translation-runtime
1. Export resources from canonical specs or runtime snapshots.
2. Pass `createI18nextInitOptions(...).options` to a caller-created i18next instance.
3. Serialize the same runtime snapshot/exported resources for hydration when using SSR.

Unique release changes

- preference resolver helpers + OverrideScope mapping (additive)
2 packages · 4 occurrences
- All 23 operation contract keys have been renamed. Consumers that reference these keys by string must update every reference.
3 packages · 3 occurrences
- BREAKING: Rename all 23 CommunicationOS operation keys from communicationOs.* to communication.* namespace. Add thread-link lifecycle, live audit accumulation, defineQuery taxonomy parallels, and MCP exposure via generator tool + stdio server.
3 packages · 3 occurrences
- Eight formerly defineCommand read operations now have defineQuery siblings. Deprecated originals will be removed in example.communication-os@1.1.0 (Loop D).
3 packages · 3 occurrences
- String-replace `communicationOs.` with `communication.` in every consumer file that references CommunicationOS operation key literals. Applies to contract key strings, handler registrations, audit event keys, test fixtures, and any analytics or logging that references these keys by name.
3 packages · 3 occurrences
- ThreadDetailPage now accepts onUnlinkThread for unlink UI affordances.
3 packages · 3 occurrences
- Use the static catalog or the generator to expose CommunicationOS contracts in any MCP server.
3 packages · 3 occurrences
- @lssm-tech/module.communication-os/core/runtime* are compatibility shims for @lssm-tech/lib.communication-runtime.
2 packages · 2 occurrences
- Add Loop B governance contracts, runtime mutation helpers, policy evaluation ribbon, and live evaluator wiring across the CommunicationOS surface.
2 packages · 2 occurrences
- Additive: M2 communication-runtime V2 ThreadLink mutations (kindId/instanceId); ThreadListItem V2 fields; cockpit ConversationGraphView wiring.
2 packages · 2 occurrences
- Adopt kindId + instanceId parameter names aligned with rich-reference V2 vocabulary.
2 packages · 2 occurrences
- Import `createCommunicationOsRuntime` and grouped lifecycle/governance/state helpers from `@lssm-tech/lib.communication-runtime`.
2 packages · 2 occurrences
- Import approveAction, rejectAction, mergeIdentity, rejectIdentityCandidate, approveHandoff, rejectHandoff, and evaluateDraftAgainstPolicies from @lssm-tech/lib.communication-runtime.
2 packages · 2 occurrences
- Move CommunicationOS runtime and replay surfaces out of the module into runtime and example packages.
2 packages · 2 occurrences
- Pass an optional (body => PolicyEvaluationSummary) function to CommunicationOsPreview or MessagingWorkspace to enable the PolicyEvaluationRibbon above the compose area.
2 packages · 2 occurrences
- Replace module replay and fixture imports with `@lssm-tech/example.communication-os`.
2 packages · 2 occurrences
- Replace module runtime imports with `@lssm-tech/lib.communication-runtime`.
2 packages · 2 occurrences
- The cockpit WorkGraphScreen now demonstrates how to build GraphNode/GraphEdge arrays from ThreadListItem data and render them via ConversationGraphView.
2 packages · 2 occurrences
- ThreadListItem.linkedObjectId — deprecated; use linkedInstanceId.
2 packages · 2 occurrences
- ThreadListItem.linkedObjectType — deprecated; use linkedKindId.
2 packages · 2 occurrences
- Use linkedKindId and linkedInstanceId instead of the deprecated V1 fields.
2 packages · 2 occurrences
- V2 signatures replace objectType/objectId parameters with kindId/instanceId. The composite key format also changed from `threadId::objectType::objectId` to `threadId::kindId::instanceId`.
2 packages · 2 occurrences
- Add an optional ContractSpec-first i18next adapter for downstream interoperability.
1 packages · 1 occurrences
- Namespace translation bundles with stable ContractSpec keys and use `TranslationSpec.locale` for BCP 47 language tags.
1 packages · 1 occurrences
- Use `@lssm-tech/lib.translation-runtime/i18next` for downstream i18next projection instead of importing adapter internals.
1 packages · 1 occurrences
- Use generated resources and init options with caller-owned i18next instances for SSR and request isolation.
1 packages · 1 occurrences

Impacted packages

@lssm-tech/app.communicationos-mcp
Layer: apps · 6 changes
@lssm-tech/lib.communication-runtime
Layer: libs · 5 changes
@lssm-tech/lib.contracts-spec
Layer: libs · 2 changes
@lssm-tech/lib.translation-runtime
Layer: libs · 4 changes
@lssm-tech/module.communication-os
Layer: modules · 5 changes