alkdev/alknet
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
45506ed77b78ad9c13d7c3656754a7e8b1f256ad
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

197 lines
12 KiB
Markdown
Raw Blame History

---
status: draft
last_updated: 2026-07-07
---
# Open Questions
Each open question lives in its own file under [`questions/`](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](#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](questions/001-bistream-type-definition.md) | BiStream Type Definition | resolved | one | high |
| [OQ-02](questions/002-authcontext-resolution-timing.md) | AuthContext Resolution Timing | resolved | one | high |
### ALPN and Routing
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-03](questions/003-alpn-string-naming-convention.md) | ALPN String Naming Convention | resolved | one | med |
| [OQ-04](questions/004-dynamic-handler-registration-at-runtime-vs-static-at-startup.md) | Dynamic Handler Registration at Runtime vs Static at Startup | resolved | two | low |
### Transport and Endpoint
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-05](questions/005-multi-connectivity-endpoint.md) | Multi-Connectivity Endpoint | resolved | one | high |
| [OQ-06](questions/006-server-side-alpn-vs-client-side-alpn.md) | Server-Side ALPN vs Client-Side ALPN | resolved | one | low |
### Call Protocol
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-07](questions/007-call-protocol-scope-within-a-connection.md) | Call Protocol Scope Within a Connection | resolved | two | med |
### Security
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-08](questions/008-vault-integration-point.md) | Vault Integration Point | resolved | one | med |
### Deferred Questions
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-09](questions/009-wasm-target-boundaries.md) | WASM Target Boundaries | deferred | one | low |
| [OQ-10](questions/010-git-adapter-scope-smart-protocol-only-or-full-server.md) | Git Adapter Scope — Smart Protocol Only or Full Server? | deferred | two | low |
### alknet-core
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-11](questions/011-handler-level-auth-resolution-observability.md) | Handler-Level Auth Resolution Observability | resolved | two | med |
| [OQ-12](questions/012-tls-identity-provisioning-in-alknetendpoint.md) | TLS Identity Provisioning in AlknetEndpoint | resolved | one | high |
| [OQ-13](questions/013-operation-path-format-and-routing-scope.md) | Operation Path Format and Routing Scope | resolved | two | med |
| [OQ-14](questions/014-batch-operation-semantics.md) | Batch Operation Semantics | resolved | two | low |
### alknet-call
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-15](questions/015-call-protocol-client-and-adapter-contract.md) | Call Protocol Client and Adapter Contract | resolved | one | high |
| [OQ-16](questions/016-safe-vault-operations-for-call-protocol-exposure.md) | Safe Vault Operations for Call Protocol Exposure | resolved | one | high |
| [OQ-17](questions/017-abort-cascade-semantics-for-nested-calls.md) | Abort Cascade Semantics for Nested Calls | resolved | one/two | high |
| [OQ-18](questions/018-privilege-model-and-authority-context.md) | Privilege Model and Authority Context | resolved | one/two | high |
| [OQ-19](questions/019-session-scoped-operation-registries-and-agent-written-operations.md) | Session-Scoped Operation Registries and Agent-Written Operations | resolved | one/two | med |
### alknet-vault
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-20](questions/020-salt-kdf-and-encryption-key-derivation-method.md) | Salt/KDF and Encryption Key Derivation Method | resolved | one/two | high |
| [OQ-21](questions/021-remote-vault-administration.md) | Remote Vault Administration | resolved | one | med |
| [OQ-22](questions/022-key-rotation-mechanism.md) | Key Rotation Mechanism | resolved | one/two | med |
| [OQ-23](questions/023-handler-identity-registration-path-and-composition-authority.md) | Handler Identity Registration Path and Composition Authority | resolved | one/two | high |
| [OQ-24](questions/024-operation-error-schemas.md) | Operation Error Schemas | resolved | one/two | high |
### Call Client and Adapters
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-25](questions/025-remote-safe-marking-shape-for-callclient-peer-scoped-filtering-dissolved-by-adr-029.md) | ~~Remote-Safe Marking Shape for CallClient Peer-Scoped Filtering~~ (Dissolved by ADR-029) | dissolved | one/two | med |
| [OQ-26](questions/026-operationadapter-error-type-adaptererror-variants.md) | OperationAdapter Error Type (AdapterError Variants) | resolved | two | med |
| [OQ-27](questions/027-from-call-re-import-trigger.md) | from_call Re-Import Trigger | resolved | two | low |
| [OQ-28](questions/028-from-call-namespace-collision-behavior.md) | from_call Namespace Collision Behavior | resolved | two | low |
| [OQ-29](questions/029-callclient-tls-client-auth-and-remote-identity-verification.md) | CallClient TLS Client-Auth and Remote-Identity Verification | resolved | one/two | high |
| [OQ-30](questions/030-peerref-any-routing-policy.md) | PeerRef::Any Routing Policy | resolved | two | low |
| [OQ-31](questions/031-services-list-peers-re-export-semantics.md) | services/list-peers Re-Export Semantics | resolved | two | low |
| [OQ-32](questions/032-multi-hop-federation.md) | Multi-Hop Federation | deferred(scope) | one/two | low |
| [OQ-33](questions/033-peerid-cryptographic-identity-vs-stable-logical-identifier.md) | PeerId — Cryptographic Identity vs Stable Logical Identifier | resolved | one/two | high |
| [OQ-34](questions/034-persistent-peer-registry-cross-node-state-storage.md) | Persistent Peer Registry (Cross-Node State Storage) | resolved | one/two | med |
### Storage and Adapters
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-35](questions/035-api-key-identity-vs-peer-identity-dissolved.md) | ~~API Key Identity vs Peer Identity~~ (Dissolved) | dissolved | one | med |
| [OQ-36](questions/036-concrete-persistence-adapter-shapes.md) | Concrete Persistence Adapter Shapes | resolved | two | med |
### TLS Identity
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-37](questions/037-x-509-outgoing-only-case-three-peer-roles.md) | X.509 Outgoing-Only Case (Three Peer Roles) | resolved | one | med |
### alknet-http
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-38](questions/038-webtransport-standalone-relay-service-scope.md) | WebTransport Standalone Relay Service Scope | open | one/two | low |
| [OQ-39](questions/039-to-openapi-published-spec-versioning.md) | `to_openapi` Published-Spec Versioning | resolved | one/two | med |
| [OQ-40](questions/040-reqwest-client-config-and-connection-pooling.md) | reqwest Client Config and Connection Pooling | resolved | two | low |
| [OQ-41](questions/041-stream-operators-library.md) | Stream Operators Library | deferred(scope) | two | low |
### Runtime-Spawned Resources and Ownership
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-42](questions/042-dynamic-resource-ownership-for-runtime-spawned-resources.md) | Dynamic Resource Ownership for Runtime-Spawned Resources | resolved | one | high |
### alknet-tty
| OQ | Title | Status | Door | Pri |
|----|-------|--------|------|-----|
| [OQ-43](questions/043-ttycontrol-as-a-clone-trait-object.md) | `TtyControl` as a `Clone` trait object | resolved | one | med |
| [OQ-44](questions/044-terminal-modes-tty-modes.md) | Terminal Modes (TTY modes) | deferred(scope) | two | low |
| [OQ-45](questions/045-flow-control-for-high-throughput-stdout.md) | Flow Control for High-Throughput stdout | resolved | two | low |
| [OQ-46](questions/046-runner-api-surface.md) | Runner API Surface | deferred(scope) | two | low |
| [OQ-47](questions/047-stdin-closure-canonical-signal.md) | 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](questions/009-wasm-target-boundaries.md)
### 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](questions/010-git-adapter-scope-smart-protocol-only-or-full-server.md)
### 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](questions/032-multi-hop-federation.md)
### 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](questions/041-stream-operators-library.md)
### 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](questions/044-terminal-modes-tty-modes.md)
### 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](questions/046-runner-api-surface.md)
Reference in new issue View Git Blame Copy Permalink