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.
- 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.
**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,
`internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the
channel-settings document and its decode) and the client
(`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the
wire sentinels and `ClientError`). A second `internal/domain/controlplane` package
for the vocabulary was planned and then measured out of the design: the vocabulary
has exactly one consumer, the client that projects it, and the store-backed side
reads the same definitions through type aliases rather than a copy -- so a separate
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
`archie-core-8cda.6.5` does not inherit them:
**Settled by the implementation.** Two of the four open questions this decision
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
`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
infrastructure -- but the gate does not require the move, and it would multiply
the diff across archied's wiring and the State Store binary. Tracked as
`archie-core-8f4n`.
2. 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.
because `agent.go` sits beside it. Independent of this severance, tracked as
`archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.
3. Does the vocabulary move to a domain package when a second consumer appears?
**Both consumers keep compiling.** archied imports the new vocabulary for the
kinds it names and the new client package for `RuntimeConfig` and the persona