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.
2.4 KiB
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 — Phase 0 ADR 034 entry, inconsistencies section
- ADR-024 — Uses hub/spoke historically
- ADR-025 — Uses hub/spoke historically
- research/core.md — Head/worker terminology