glm-5.1
19b3d3a078
Phase 0a — ADRs (9 new): - ADR-026: Transport/interface separation (three-layer model) - ADR-027: Crate decomposition (core, secret, storage, flowgraph, napi, CLI) - ADR-028: Auth as irpc service (AuthProtocol behind feature flag) - ADR-029: Identity as core type (Identity + IdentityProvider in alknet-core) - ADR-030: Static/dynamic config split (ArcSwap, ConfigReloadHandle) - ADR-031: Forwarding policy (rule-based allow/deny, TransportKind-aware) - ADR-032: Event boundary discipline (domain, irpc, call protocol boundaries) - ADR-033: OperationEnv universal composition (three dispatch paths) - ADR-034: Head/worker terminology (replace hub/spoke) Phase 0b — New spec documents (7): - identity.md, services.md, interface.md, configuration.md, storage.md, flowgraph.md, secret-service.md Updated existing docs: - auth.md: reference identity.md for canonical definitions, add AuthProtocol - open-questions.md: resolve OQ-12, OQ-16, OQ-18, OQ-22, OQ-23-25 - README.md: add all new docs, ADRs 026-034 Marked 19 architecture tasks as completed.
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# ADR-034: Head/Worker Terminology
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The project previously used hub/spoke terminology for describing node
|
|
relationships: a hub node that coordinates connections and spokes that connect to
|
|
it. This terminology implies a strict star topology where the hub is
|
|
fundamentally different from spokes.
|
|
|
|
In practice, a coordinating node can also execute operations (run services,
|
|
forward traffic). Any node can become a coordinator. The architecture supports
|
|
mesh topologies where nodes coordinate in a peer-to-peer fashion.
|
|
|
|
The research documents (`core.md`, `services.md`) and updated architecture
|
|
specs (`call-protocol.md`, `auth.md`, `napi-and-pubsub.md`, `open-questions.md`)
|
|
already use head/worker consistently. Existing ADRs (024, 025) retain their
|
|
original hub/spoke language because ADRs are historical records.
|
|
|
|
## Decision
|
|
|
|
**Use head/worker terminology throughout the project.**
|
|
|
|
- **Head node**: A node that coordinates — accepts connections, routes
|
|
operations, manages cluster state. A head is also a worker (it can execute
|
|
operations).
|
|
- **Worker node**: A node that connects to a head, registers its services, and
|
|
executes operations. Any worker can become a head.
|
|
- **Node**: Any participant in the network. Every node has an Ed25519 identity.
|
|
|
|
The terms hub and spoke are deprecated in all new specs, code, and
|
|
documentation. Existing ADRs retain their original language as historical
|
|
records — ADRs document what was decided at the time, not what the current
|
|
terminology is.
|
|
|
|
## Consequences
|
|
|
|
- **Positive**: Natural mesh formation. A head that is also a worker enables
|
|
multi-hop routing, redundancy, and distributed topologies without a
|
|
centralized authority.
|
|
- **Positive**: Consistency with integration plan and research documents.
|
|
- **Positive**: The terminology better reflects the architecture — there is no
|
|
single "hub" that's fundamentally different from "spokes."
|
|
- **Neutral**: Existing ADRs (024, 025) retain hub/spoke in their text. This is
|
|
intentional — ADRs are historical records.
|
|
|
|
## References
|
|
|
|
- [research/integration-plan.md](../../research/integration-plan.md) — Phase 0 ADR 034 entry, inconsistencies section
|
|
- [ADR-024](024-bidirectional-call-protocol.md) — Uses hub/spoke historically
|
|
- [ADR-025](025-handler-spec-separation.md) — Uses hub/spoke historically
|
|
- [research/core.md](../../research/core.md) — Head/worker terminology |