docs(architecture): record the Phase 4 messaging severance plan

archie-core-8cda.6's fourth criterion cannot pass: the PRD's deletion gate for the
Messaging Service does not exist, and the check it names reports four banned
packages linked -- modernc.org/sqlite, internal/store, internal/domain/workflow and
internal/agentexec -- all through one import, archiemessaging/run.go ->
internal/app/controlplane, from which the service uses three symbols. The decision
is to sever rather than amend the gate, because a boundary you whitelist around is
no longer a boundary.

This records the plan before any implementation: what moves (every kind constant,
the channel-settings vocabulary and its decode, the generic client, the persona
watch, the workflow-settings document), what stays and why (the store-backed server
and Definition registry, WorkflowDefinitionsClient and stepRegistry,
WatchWorkflowExecutionSettings because decodeSettings returns and validates
workflow.ExecutionSettings, the schedules document because a domain vocabulary may
not import infrastructure, the schema derivation), and where the pieces go
(internal/domain/controlplane for the vocabulary,
internal/infrastructure/controlplanerpc for the client, mirroring gatewayrpc and
staterpc).

Four decisions are named rather than taken, so archie-core-8cda.6.5 does not
inherit them: whether the server also leaves internal/app/; where
WatchWorkflowExecutionSettings lives, given it cannot share a package with the
client the Messaging Service imports; whether internal/domain/workflow's
contract/engine split happens and when; and whether archied's watches move with the
client. Both existing consumers keep compiling, and the Messaging Service's
dependency set loses all four banned packages.

Verified: task check exit 0, docs-only change, docs:check and docs:prds green.
This commit is contained in:
sam committed 2026-09-22 07:17:06 +10:00
1 parent 2ae831abd7
commit 5adb19947c
1 file changed
+90
+90
View File
@@ -217,6 +217,96 @@ The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
polls from outside to confirm an update came back up; the rest of the PRD's
prohibition list is untouched.
**Phase 4 messaging severance: what must move, and the decision the PRD does
not cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot
pass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the
check that section specifies -- `go list -deps ./cmd/archie-messaging` links
zero banned runtime packages -- reports four:
| banned package | PRD category |
| --- | --- |
| `modernc.org/sqlite` | State Store |
| `internal/store` | State Store |
| `internal/domain/workflow` | Workflow engine |
| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |
All four arrive through one import: `internal/app/archiemessaging/run.go`
imports `internal/app/controlplane`, whose own dependency set is exactly those
four. The Messaging Service uses three symbols from that package
(`NewRPCClient`, `RuntimeChatConfig`, `ChannelSettingsKind`); the package also
carries the store-backed `ResourceStore` server, the `Definition` registry and
the workflow step vocabulary. Sever the package. Amending the gate to tolerate
`modernc.org/sqlite` and `internal/store` is rejected: a boundary you whitelist
around is no longer a boundary.
**What moves.**
- Every kind constant. They are strings with no dependency, and the client names
them.
- The channel-settings vocabulary and its decode: `channelSettings`,
`telegramSettings`, `webhookChannelSettings`, `emailSettings`,
`rateLimitSettings`, `channelDuration`, and `decodeRenamingLegacyKeys`.
- The generic client: `Client`, `NewRPCClient`, `RuntimeConfig` with
`runtimeConfigFrom`, `runtimeChatConfigFrom`, the other `runtime*From`
projections, and the `resourceReader` interface.
- The persona watch (`WatchPersonas`, `AppliedPersonas`), which needs only
`internal/domain/agent`.
- `executionSettingsDocument`, the document alone.
**What stays, and why.**
- The store-backed server: `Server`, `NewServer`, `ResourceStore`,
`ImportConfig`, `SeedSkip`, the `Definition` registry, and every other kind's
seed, validator and `Normalize` hook.
- `WorkflowDefinitionsClient` and `stepRegistry`, which decode through
`internal/domain/workflow`.
- `WatchWorkflowExecutionSettings` and `decodeSettings`: `decodeSettings`
returns and validates `workflow.ExecutionSettings`, so any package holding it
links the workflow domain and therefore `internal/agentexec`. This is why the
client cannot move as one package -- see open question 2.
- The schedules document, whose type is `cronstore.JobSpec` in
`internal/infrastructure`. A domain vocabulary package may not import
infrastructure.
- The schema derivation, which describes the documents the server advertises.
**Placement, the decision the PRD does not cover.** Recommended:
`internal/domain/controlplane` for the vocabulary (kinds, documents, decode) and
`internal/infrastructure/controlplanerpc` for the client, mirroring `gatewayrpc`
and `staterpc`. A service client belongs in infrastructure by the convention
`organisation.md` already fixes, and a domain vocabulary carries no store or
engine dependency by construction. Rejected: one
`internal/infrastructure/controlplane` holding both halves, because the client
would still import a package that links the store, which is the thing the gate
exists to measure.
**Open questions this decision deliberately does not settle**, listed so
`archie-core-8cda.6.5` does not inherit them:
1. Does the server also leave `internal/app/`? `organisation.md` reserves
`internal/app/` for wiring and composition, and a store-backed gRPC server is
infrastructure -- but the gate does not require the move, and it would
multiply the diff across archied's wiring and the State Store binary.
2. Where does `WatchWorkflowExecutionSettings` live, given it cannot share a
package with the Messaging Service's client? Either a second, workflow-aware
client package, or the watch returns the raw document and its caller decodes
it. Recommended: the second package, because the client-side validation it
performs is what the daemon's apply flow relies on.
3. Does `internal/domain/workflow`'s contract/engine split happen, and when? A
contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only
because `agent.go` sits beside it. Independent of this severance, and it is
the other half of the PRD's workflow-engine ban.
4. Do archied's watches move with the client, or stay with the composition?
archied is the only other consumer of the client half.
**Both consumers keep compiling.** archied imports the new vocabulary for the
kinds it names and the new client package for `RuntimeConfig` and the persona
watch, and keeps `internal/app/controlplane` for the server, the registry,
`ErrVersionConflict` and the workflow-aware pieces. The State Store binary
continues to call `NewServer` and `ResourceStore` unchanged. The Messaging
Service then imports only `internal/infrastructure/controlplanerpc`,
`gatewayrpc` and `staterpc`, so `go list -deps ./cmd/archie-messaging` loses all
four banned packages and the gate can land green.
### 3. Identity data migration
The migration must define: