Files
alknet/docs/architecture/open-questions.md
T
glm-5.2 db4da1e6f0 docs(arch): resolve OQ-45 — no application-level windowing; QUIC per-stream flow control suffices
The backpressure chain is complete by construction: QUIC flow control
→ bounded drainer channel → bounded stdout channel → OS pipe/PTY buffer
→ process write() blocks. Every link awaits its producer; no unbounded
buffer breaks the chain. The reversal path (an additive ControlMessage
variant, not a wire-format header change) is noted in ADR-052's
consequences as a two-way door, not the expected path.

Tightened ADR-052 assumption 1 from a hedge ('expected to work; a POC
would confirm') to a decided constraint. Updated all OQ-45 references
across the tty spec docs from 'open (low risk)' to 'resolved'.
2026-07-07 09:36:18 +00:00

12 KiB

status, last_updated
status last_updated
draft 2026-07-07

Open Questions

Each open question lives in its own file under questions/, named NNN-slug.md (mirroring the ADR convention). This file is the index: theme-grouped tables for scannability, plus a cross-theme Deferred / Blocked section that surfaces the safe-exit deferrals with their blocking conditions inline — so "what's currently parked and why" is answerable at a glance.

Status values:

  • open — Needs to be resolved now. Has a clear path to resolution.
  • resolved — Decided. The resolution is stated cleanly, without caveats about how it could be changed later.
  • deferred(scope) — Cannot be resolved yet. The information doesn't exist. Has a concrete blocking condition (e.g., "blocked on: alknet-agent crate spec"). Not a failure — scope management.
  • partially resolved — Some aspects decided, others deferred or open.
  • dissolved — The question was reframed out of existence (e.g., superseded by an ADR that retires the premise). Kept for reference.

Door type classifications follow ADR-009 — they describe reversal cost (how expensive it is to undo), not urgency:

  • One-way door: Reversal requires rewriting significant code or permanently closes a capability. Getting it wrong is expensive — requires ADR before implementation.
  • Two-way door: Reversal is cheap or additive. Getting it wrong is recoverable — decide, implement, revert if needed.

Door type is separate from whether a decision is made. A two-way door is a decision you make now and can revert later, not a decision to defer. See ADR-009 §"What this framework is NOT."

By Theme

Core Types

OQ Title Status Door Pri
OQ-01 BiStream Type Definition resolved one high
OQ-02 AuthContext Resolution Timing resolved one high

ALPN and Routing

OQ Title Status Door Pri
OQ-03 ALPN String Naming Convention resolved one med
OQ-04 Dynamic Handler Registration at Runtime vs Static at Startup resolved two low

Transport and Endpoint

OQ Title Status Door Pri
OQ-05 Multi-Connectivity Endpoint resolved one high
OQ-06 Server-Side ALPN vs Client-Side ALPN resolved one low

Call Protocol

OQ Title Status Door Pri
OQ-07 Call Protocol Scope Within a Connection resolved two med

Security

OQ Title Status Door Pri
OQ-08 Vault Integration Point resolved one med

Deferred Questions

OQ Title Status Door Pri
OQ-09 WASM Target Boundaries deferred one low
OQ-10 Git Adapter Scope — Smart Protocol Only or Full Server? deferred two low

alknet-core

OQ Title Status Door Pri
OQ-11 Handler-Level Auth Resolution Observability resolved two med
OQ-12 TLS Identity Provisioning in AlknetEndpoint resolved one high
OQ-13 Operation Path Format and Routing Scope resolved two med
OQ-14 Batch Operation Semantics resolved two low

alknet-call

OQ Title Status Door Pri
OQ-15 Call Protocol Client and Adapter Contract resolved one high
OQ-16 Safe Vault Operations for Call Protocol Exposure resolved one high
OQ-17 Abort Cascade Semantics for Nested Calls resolved one/two high
OQ-18 Privilege Model and Authority Context resolved one/two high
OQ-19 Session-Scoped Operation Registries and Agent-Written Operations resolved one/two med

alknet-vault

OQ Title Status Door Pri
OQ-20 Salt/KDF and Encryption Key Derivation Method resolved one/two high
OQ-21 Remote Vault Administration resolved one med
OQ-22 Key Rotation Mechanism resolved one/two med
OQ-23 Handler Identity Registration Path and Composition Authority resolved one/two high
OQ-24 Operation Error Schemas resolved one/two high

Call Client and Adapters

OQ Title Status Door Pri
OQ-25 Remote-Safe Marking Shape for CallClient Peer-Scoped Filtering (Dissolved by ADR-029) dissolved one/two med
OQ-26 OperationAdapter Error Type (AdapterError Variants) resolved two med
OQ-27 from_call Re-Import Trigger resolved two low
OQ-28 from_call Namespace Collision Behavior resolved two low
OQ-29 CallClient TLS Client-Auth and Remote-Identity Verification resolved one/two high
OQ-30 PeerRef::Any Routing Policy resolved two low
OQ-31 services/list-peers Re-Export Semantics resolved two low
OQ-32 Multi-Hop Federation deferred(scope) one/two low
OQ-33 PeerId — Cryptographic Identity vs Stable Logical Identifier resolved one/two high
OQ-34 Persistent Peer Registry (Cross-Node State Storage) resolved one/two med

Storage and Adapters

OQ Title Status Door Pri
OQ-35 API Key Identity vs Peer Identity (Dissolved) dissolved one med
OQ-36 Concrete Persistence Adapter Shapes resolved two med

TLS Identity

OQ Title Status Door Pri
OQ-37 X.509 Outgoing-Only Case (Three Peer Roles) resolved one med

alknet-http

OQ Title Status Door Pri
OQ-38 WebTransport Standalone Relay Service Scope open one/two low
OQ-39 to_openapi Published-Spec Versioning resolved one/two med
OQ-40 reqwest Client Config and Connection Pooling resolved two low
OQ-41 Stream Operators Library deferred(scope) two low

Runtime-Spawned Resources and Ownership

OQ Title Status Door Pri
OQ-42 Dynamic Resource Ownership for Runtime-Spawned Resources resolved one high

alknet-tty

OQ Title Status Door Pri
OQ-43 TtyControl as a Clone trait object resolved one med
OQ-44 Terminal Modes (TTY modes) deferred(scope) two low
OQ-45 Flow Control for High-Throughput stdout resolved two low
OQ-46 Runner API Surface deferred(scope) two low
OQ-47 Stdin Closure Canonical Signal resolved two low

Deferred / Blocked

The safe-exit visibility surface. These questions are parked because the information needed to resolve them does not exist yet — each has a concrete blocking condition. They are not failures; they are scope management. See ADR-009 §"Safe Exit: Deferred Decisions." This section exists so "what's currently blocking the architect" is answerable at a glance, not by filtering the tables above.

OQ-09: WASM Target Boundaries

  • Blocked on: A concrete server-side WASM use case, or a deliberate confirmation that WASM stays a client-side design constraint. Tracked as architecture/oq-09-wasm-server-use-case in tasks/architecture/.
  • Priority: low
  • Full file: OQ-09

OQ-10: Git Adapter Scope — Smart Protocol Only or Full Server?

  • Blocked on: Speccing the alknet-git crate — resolve this when that crate is specified, not deferred past it. Tracked as architecture/oq-10-git-adapter-spec in tasks/architecture/.
  • Priority: low
  • Full file: OQ-10

OQ-32: Multi-Hop Federation

  • Blocked on: A concrete use case for multi-hop federation. The one-hop model covers all current use cases (head→worker, runner→hub).
  • Priority: low
  • Full file: OQ-32

OQ-41: Stream Operators Library

  • Blocked on: A handler that needs stream operators and finds the existing combinators (Box::pin(stream::iter(...)), async_stream::stream!, futures::stream) insufficient. The operators library is a convenience, not a prerequisite for any handler.
  • Priority: low
  • Full file: OQ-41

OQ-44: Terminal Modes (TTY modes)

  • Blocked on: a concrete mode-control use case (a deployment that needs to set echo/raw/canonical/etc. modes on a PTY, beyond the backend's defaults).
  • Priority: low
  • Full file: OQ-44

OQ-46: Runner API Surface

  • Blocked on: a concrete runner-policy use case that forces the API surface (job management, log persistence, task graph integration).
  • Priority: low
  • Full file: OQ-46