glm-5.2
5941280bca
Address the root cause of rework-causing hedging: the architect was
put in a logical bind where it couldn't express justified uncertainty
('the pieces exist but the shape isn't clear yet'). The only options
were 'decide now' (premature) or 'deferred(scope)' (false — the
information isn't missing, it's un-synthesized). The agent picked
deferred(scope) with a circular blocking condition (OQ-64 blocked on
OQ-55, OQ-55 needs OQ-64) because there was no honest way to say 'I
can see the pieces but I can't see the shape.'
Changes to the architect role spec:
- Add deferred(unclear) state: the pieces exist but the composition
isn't clear; resolution requires investigation (work through
examples, POC), not waiting. Has an investigation target and an
impacts field.
- Add 'Impacts' field to the OQ format: what does this block
downstream? Be specific ('blocks the first hub deployment because
the hub dials workers' not 'blocks the hub crate'). The triage
signal that makes deferral urgency visible — the field that would
have made the AlknetClient circular hedge visible.
- Add circular-reasoning guard to self-review: 'check that your
blocking condition isn't a prerequisite of the thing you're
deferring.'
- Trim anti-patterns #9-#11 (hedging synonyms catalog, ~40 lines):
detection belongs in the reviewer, not the architect's self-review.
The architect is too close to its own reasoning to see its own
circular hedges.
- Trim door-types section (30→10 lines): keep the one-paragraph
summary, cut the elaboration.
Changes to the architecture-reviewer role spec:
- Add Decision Quality (F) category: false-deferral check
distinguishing three cases — (1) hedging on a resolved decision, (2)
false deferral / circular hedge (the blocking condition is a
prerequisite of the thing being deferred), (3) legitimate deferral.
- Add Impacts Field Coverage (G) category: check that unresolved OQs
have specific impacts fields.
- Note: the Decision Quality category is often the highest-value
check on poorly-defined projects — the architect cannot self-review
it (circular reasoning is invisible from inside the circle).
Retrofit existing OQs:
- Add Impacts field to all 16 unresolved OQs (10 deferred, 6 open).
- Update OQ-63 (TlsError shape) to reflect ADR-087's client-side
addition — the error type now covers both server and client
variants.
- Move OQ-65 (WebSocket carrying channels) to alknet-http theme
(done in prior commit; this commit adds its impacts field).
- Verified: no circular reasoning found in existing deferrals. The
AlknetClient hedge (OQ-64) was the circular one; it's already
resolved by ADR-087.
3.9 KiB
3.9 KiB
OQ-58: Worker Registration Flow
- Origin:
docs/architecture/crates/hub/README.md§"Worker registration" — the provisioning → enrollment → connection sequence that makes TCP+TLS a hard requirement for the hub. - Status: open
- Door type: one-way (the registration endpoint shape and the enrollment-token model are an API surface; changing them after workers are provisioned against them is a breaking change for every deployment)
- Priority: high
- Impacts: Blocks worker provisioning — a freshly-provisioned worker has no way to enroll its key with the hub until the registration endpoint exists. Blocks the first hub deployment that provisions workers (web + native use case).
- Blocked on: nothing structural — the identity machinery
(
resolve_from_token,PeerEntry.auth_token_hash, ADR-030/034) and the HTTP substrate (HttpAdapteronh2/http/1.1over TCP+TLS, ADR-010 Am. 1 / ADR-065) both exist. What remains is deciding the token model and the endpoint shape, not building new primitives. - Resolution: Not yet decided. The flow is decision-ready in
shape (see "Decision-ready shape" below). The open sub-questions are:
- Enrollment-token model. Is the registration token one-time single-use (burned on first POST), one-time-per-worker (a worker can retry the POST until it succeeds, then the token is invalidated), or refresh-capable (the token can enroll multiple workers, e.g. a pool token)? One-time-per-worker is the likely default (matches the provisioning flow: one token per instance); pool tokens are a feature extension.
- Session credential returned. After registration, does the
hub return a bearer token for the ongoing channels connection
(the worker authenticates over TCP+TLS via
auth_token), or does it record the worker's fingerprint and expect fingerprint auth on the channels connection (the worker authenticates over QUIC via its raw key)? Both are valid; the choice depends on whether the worker's transport is known at registration time. A hub that accepts both should probably support both return shapes (return a token and record the fingerprint). - Endpoint path.
POST /register?POST /v1/workers/register? A versioned path is safer for a one-way door. - Token source. Does the hub generate the enrollment token, or does the assembly layer (the provisioning system) generate it and the hub just validates it? The latter keeps the hub out of the token-generation business but requires a shared secret or signature scheme.
- Decision-ready shape: the registration endpoint is an HTTP POST
on the hub's
HttpAdapter(served onh2/http/1.1over TCP+TLS). The request carries the worker's public key and the enrollment token. The hub validates the token, creates aPeerEntryfor the worker (fingerprint from the key,auth_token_hashfrom a session token the hub issues), and returns the session credential. The worker then connects via channels (QUIC or TCP+TLS) and authenticates with the fingerprint or the bearer token. ThePeerEntrycreated at registration is whatresolve_from_token/resolve_from_fingerprintmatches at connection time. - What does NOT block on this: the hub's multi-transport accept
loop, the channels-over-TCP path, the identity-over-TCP path
(bearer token via
resolve_from_token), and the supervision loop. All of these are decided and use existing machinery. OQ-58 is about the registration endpoint specifically — the one new surface the hub introduces. - Cross-references: ADR-030 (PeerEntry, auth_token_hash), ADR-034 (bearer-token identity over non-fingerprint transports), ADR-010 Am. 1 (TCP+TLS dispatch via from_stream), ADR-065 (Connection::from_bidi), ADR-080 (ChannelClient::from_connection), OQ-52 (CallConnection::wait_for_close — the supervision loop the registration flow feeds into).