docs(adr): support-service → IIOS naming migration (ADR-0001)
Establishes a docs/adr convention and records the naming-migration decision: interaction-centric Iios-prefixed vocabulary as canonical, support as a namespaced specialization (KG-16), @insignia/iios-* package scope, and a greenfield-and-deprecate (strangler) migration off the legacy support-service. Includes the legacy→IIOS naming map. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,107 @@
|
||||
# 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.)
|
||||
Reference in New Issue
Block a user