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.
2.3 KiB
2.3 KiB
OQ-56: Full Channel-Level Flow-Control Windowing
- Origin:
docs/research/alknet-channels/phase-0-findings.md§DP-5, §OQ-CH-03;docs/architecture/decisions/076-backpressure-channel-limits-id-reuse.md - Status: deferred(scope)
- Door type: two-way (additive — per-channel window tracking does not change the wire format)
- Priority: low
- Impacts: None — bounded-buffer backpressure (ADR-076) is the v1 mechanism and handles the intended use cases (TTY, SSH, tunnels). Would impact high-throughput channel use cases (e.g., file transfer over a tunnel) if HOL blocking is observed in practice.
- Blocked on: a real deployment observes head-of-line blocking on a saturated channel where the bounded-buffer's stop-reading mitigation is insufficient. The trigger is specific: a channel whose consumer is persistently slower than its producer, causing the demux to stall that channel's reads frequently enough that other channels' throughput is measurably affected. The intended use cases (TTY, SSH, tunnels) are not high-throughput in the HOL-blocking sense; the trigger requires a high-throughput use case (e.g., file transfer over a tunnel) that saturates a channel.
- Resolution: Not yet decidable. The bounded-buffer backpressure
(ADR-076, default 1 MiB per
(channel_id, stream_type)) is the decided v1 mechanism — validated by the POC's 1 MiBtunnel_large_payloadtest with no deadlock and no cross-channel blocking. Full channel-level windowing (SSH-style sliding-window per channel) is an additive extension that does not change the wire format; it adds per-channel window tracking to the demux/mux. The decision to add it depends on whether the bounded-buffer mitigation is sufficient in practice, which can only be determined by a deployment that hits the limitation. - What does NOT block on this: the bounded-buffer mechanism is decided and is the v1 implementation. Full windowing is an extension, not a prerequisite. The channels crate ships with bounded-buffer backpressure; full windowing is added if and only if the trigger condition is observed.
- Cross-references: ADR-076 (bounded-buffer decision), ADR-071 (wire
format — unchanged by windowing extension),
docs/research/alknet-channels/poc-summary.md§POC Target 1 (backpressure validation)