iios/docs/adr/0001-support-service-to-iios-naming-migration.md

ADR-0001: support-service → IIOS naming migration

• Status: Accepted
• Date: 2026-07-03
• Deciders: IIOS core
• Context tags: naming, packaging, migration, KG-16

Context

IIOS (Insignia Interaction OS) is the greenfield realization of a vision first prototyped in the standalone support-service app. That prototype already stated the core idea — "Everything is a message: a generic Message core (conversation / message / channel / user) is the foundation; Support (ticket / agent / callback) is a thin specialization on top" — but it did so with support-centric naming and as a single-purpose support desk.

IIOS generalizes that same idea to an interaction OS of much broader scope (messaging, inbox, routing, AI enrichment, calendar, plus support as one specialization among many). During P0–P9 it landed a clean, generic vocabulary: an Iios-prefixed persistence layer and @insignia/iios-* packages.

Two problems make an explicit decision necessary:

1. Naming drift. The prototype and IIOS use different words for the same concepts (Conversation vs IiosThread, Message vs IiosInteraction + IiosMessagePart, User vs IiosSourceHandle + IiosActorRef). Without a canonical mapping, contributors coming from the prototype reintroduce support-centric names, and host apps don't know which SDK is authoritative.
2. KG-16 — "support wedge evidence overgeneralized." The critics' analysis flags the risk of treating the support-service architecture as proof of all IIOS capabilities. Support is a specialization, not the core; the naming must make that structural (support names are namespaced under the generic core, never the core itself).

An unresolved sub-question also blocks packaging: the workspace scope was historically ambiguous between @insignia/* and @lynkeduppro/*.

Decision

1. Canonical vocabulary is interaction-centric and Iios-namespaced. The generic core is the noun set already shipped in @insignia/iios-service: IiosScope, IiosSourceHandle/IiosActorRef, IiosChannel, IiosThread, IiosInteraction/IiosMessagePart. Support is a specialization layered on top and is always namespaced as such (IiosSupport*, IiosTicket*, IiosCallbackRequest) — never promoted to a core concept. "Conversation" and support-centric "Message-as-ticket" framing are retired.

2. Package scope is @insignia/iios-*. This resolves the @insignia vs @lynkeduppro ambiguity in favour of @insignia. All IIOS packages already follow @insignia/iios-<name>; that is now the standard.

3. Migration is greenfield-and-deprecate (strangler), not rename-in-place. support-service is frozen legacy — we do not rename its models or ship a new version of it. New work happens in IIOS; host apps cut over to the @insignia/iios-* SDKs feature-by- feature. support-service is retired once every host app it serves has migrated.

Canonical naming map (legacy → IIOS)

support-service (legacy)	IIOS (canonical)	Note
Channel	IiosChannel	generic ingress/egress channel
User	IiosSourceHandle + IiosActorRef	identity split: external handle vs resolved actor
Conversation	IiosThread	"conversation" retired; thread is generic
Message	IiosInteraction + IiosMessagePart	envelope vs content parts
Attachment	IiosMessagePart (kind=MEDIA, contentRef)	attachments are just parts
Team / TeamMember	IiosSupportQueue / IiosSupportTeamMember	support specialization, namespaced
ConversationAssignment	support assignment (IiosSupport*)	specialization, not core
Ticket / TicketConversation	IiosTicket / IiosTicketThreadLink	ticket links to generic threads
CallbackRequest	IiosCallbackRequest
Meeting	IiosMeeting (+ P8 calendar models)	promoted to first-class in IIOS
Notification	notification_outbox (planned)	not yet built in IIOS
ProcessedCommand	IiosProcessedEvent + IiosIdempotencyCommand	consumer ledger vs command ledger
KnowledgeArticle	(deferred — AI/RAG)	out of current scope

Rules going forward

• Every persisted model is Iios-prefixed. No un-prefixed domain models.
• Support (and any future vertical) is namespaced under the generic core, never the other way round. If a name reads as "support-only," it must carry the IiosSupport*/IiosTicket* prefix and depend on the core — the core never depends on it (enforced by the import-boundary check).
• New packages are @insignia/iios-<name>.
• Legacy references in prose cite support-service explicitly as legacy, with a pointer to this ADR.

Consequences

Positive

• One authoritative vocabulary; contributors from the prototype have a lookup table.
• KG-16 is structurally addressed: support cannot masquerade as the core because its names are subordinate and the boundary check enforces the dependency direction.
• Packaging is unblocked (@insignia/iios-* is canonical).
• No risky in-place rename of a running legacy service; cutover is incremental per host app.

Negative / costs

• Two systems coexist during the strangler window; the legacy support-service must be kept running (but frozen) until host apps migrate.
• The legacy↔IIOS mapping must be consulted when porting features; this ADR is that map.
• Notification / KnowledgeArticle have no IIOS home yet — tracked as follow-ups, not blockers.

Alternatives considered

• Rename support-service in place to the IIOS vocabulary. Rejected: high-risk migration of a live service + DB for a system we intend to retire anyway; no benefit over greenfield.
• Keep both vocabularies and bridge with adapters. Rejected: perpetuates naming drift and the KG-16 confusion indefinitely.
• @lynkeduppro/* scope. Rejected: all IIOS packages already ship under @insignia; switching scopes now is churn with no upside. (A future rebrand can supersede this ADR.)