docs(architecture): record the messaging severance as it landed

The register described a design written before any measurement existed, and two of
its open questions were answered while landing archie-core-1ng1 -- both by
measuring rather than by preference. The client did not become two packages: the
workflow and persona watches stayed on internal/app/controlplane's Client, which
now embeds the new one, so the daemon's validated watch is still defined once and
the read path still has one implementation. And the vocabulary stayed in
internal/infrastructure/controlplanerpc rather than moving to a domain package,
because it has exactly one consumer and the store-backed side reads the same
definitions through type aliases rather than a copy.

It records what made that safe rather than asserting it: internal/app/controlplane
was the ONLY direct import of the Messaging Service that dragged a banned runtime
-- gatewayrpc, staterpc, applystatus, messaging, configuration, readiness and health
were all clean -- so severing that one dependency sufficed and no third package was
needed. The workflow/task exception the gate carries is recorded too, with the
verification that justifies it rather than the precedent alone.

Two questions stay open and named: whether the store-backed server also leaves
internal/app/ (archie-core-8f4n), and whether internal/domain/workflow's
contract/engine split happens (archie-core-inh6). Promoting the vocabulary to a
domain package is recorded for the day a second consumer appears.

Committed without pushing on purpose: a docs-only push to main republishes :latest
with a dev stamp for no benefit (archie-core-i5nb), so this rides with the next code
change.
This commit is contained in:
sam committed 2026-09-22 07:28:11 +10:00
1 parent a7d6cc8c9d
commit f39fdd73a0
1 file changed
+38 -23
+38 -23
View File
@@ -269,34 +269,49 @@ around is no longer a boundary.
infrastructure. infrastructure.
- The schema derivation, which describes the documents the server advertises. - The schema derivation, which describes the documents the server advertises.
**Placement, the decision the PRD does not cover.** Recommended: **Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,
`internal/domain/controlplane` for the vocabulary (kinds, documents, decode) and `internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the
`internal/infrastructure/controlplanerpc` for the client, mirroring `gatewayrpc` channel-settings document and its decode) and the client
and `staterpc`. A service client belongs in infrastructure by the convention (`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the
`organisation.md` already fixes, and a domain vocabulary carries no store or wire sentinels and `ClientError`). A second `internal/domain/controlplane` package
engine dependency by construction. Rejected: one for the vocabulary was planned and then measured out of the design: the vocabulary
`internal/infrastructure/controlplane` holding both halves, because the client has exactly one consumer, the client that projects it, and the store-backed side
would still import a package that links the store, which is the thing the gate reads the same definitions through type aliases rather than a copy -- so a separate
exists to measure. domain package would have been a package with one consumer and a second name for
one thing. What made that safe is a measurement, not a preference:
`internal/app/controlplane` was the ONLY direct import of the Messaging Service
that dragged a banned runtime (`gatewayrpc`, `staterpc`, `applystatus`, `messaging`,
`configuration`, `readiness` and `health` were all clean), so severing that one
dependency is sufficient, and the severance needed no third package. Promoting the
vocabulary to a domain package stays open for the day a second consumer appears.
**Open questions this decision deliberately does not settle**, listed so **Settled by the implementation.** Two of the four open questions this decision
`archie-core-8cda.6.5` does not inherit them: originally left are answered, in both cases by measuring rather than by preference:
- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and
`WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now
*embeds* the new one, so the daemon's validated watch is still defined once and
the read path still has one implementation -- which is what the second package
was for -- with one fewer package to keep in step.
- The schedules and workflow documents stayed put, and
`internal/domain/workflow/task` is linked deliberately: it carries the Task
status and view vocabulary, its own dependency set holds none of the banned
runtimes, and `cmd/archie-messaging/architecture_test.go` carries it as an
exception checked in both directions (the same entry, for the same reason, as
`cmd/archie-ui/architecture_test.go`).
**Still open.**
1. Does the server also leave `internal/app/`? `organisation.md` reserves 1. Does the server also leave `internal/app/`? `organisation.md` reserves
`internal/app/` for wiring and composition, and a store-backed gRPC server is `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 infrastructure -- but the gate does not require the move, and it would multiply
multiply the diff across archied's wiring and the State Store binary. the diff across archied's wiring and the State Store binary. Tracked as
2. Where does `WatchWorkflowExecutionSettings` live, given it cannot share a `archie-core-8f4n`.
package with the Messaging Service's client? Either a second, workflow-aware 2. Does `internal/domain/workflow`'s contract/engine split happen, and when? A
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 contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only
because `agent.go` sits beside it. Independent of this severance, and it is because `agent.go` sits beside it. Independent of this severance, tracked as
the other half of the PRD's workflow-engine ban. `archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.
4. Do archied's watches move with the client, or stay with the composition? 3. Does the vocabulary move to a domain package when a second consumer appears?
archied is the only other consumer of the client half.
**Both consumers keep compiling.** archied imports the new vocabulary for the **Both consumers keep compiling.** archied imports the new vocabulary for the
kinds it names and the new client package for `RuntimeConfig` and the persona kinds it names and the new client package for `RuntimeConfig` and the persona