Port alknet-typedef crate from alknet
Copy the binary struct engine (src/, tests/) verbatim from alknet/crates/alknet-typedef and create a standalone Cargo.toml (workspace-inherited fields inlined). Port the architecture docs (specs, ADRs 095-102, OQs 069-071) from alknet's nested multi-crate layout to a flat single-crate layout, fixing relative link paths. Build, 295 tests, and clippy all pass clean.
This commit is contained in:
104
docs/architecture/open-questions.md
Normal file
104
docs/architecture/open-questions.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-07-22
|
||||
---
|
||||
|
||||
# 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 is genuinely
|
||||
missing — a crate spec, POC result, or use case that doesn't exist yet.
|
||||
Has a concrete blocking condition. Not a failure — scope management.
|
||||
- `deferred(unclear)` — Cannot be resolved yet. The pieces exist (decided
|
||||
in other ADRs, existing types, existing patterns) but the composition
|
||||
— how they fit together — isn't clear yet. Resolution requires
|
||||
investigation (work through examples, maybe POC), not waiting. Has a
|
||||
concrete investigation target and an impacts field. Not a failure —
|
||||
honest uncertainty in a poorly-defined problem space.
|
||||
- `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.
|
||||
|
||||
**Impacts field**: Every unresolved OQ (`open`, `deferred(scope)`,
|
||||
`deferred(unclear)`, `partially resolved`) should have an `Impacts`
|
||||
field stating what it blocks downstream. Be specific: "blocks the first
|
||||
hub deployment because the hub dials workers" not "blocks the hub
|
||||
crate." This is the triage signal that makes the deferral's urgency
|
||||
visible.
|
||||
|
||||
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.
|
||||
|
||||
## By Theme
|
||||
|
||||
### Layout Engine
|
||||
|
||||
| OQ | Title | Status | Door | Pri |
|
||||
|----|-------|--------|------|-----|
|
||||
| [OQ-069](questions/069-arrays-of-variable-length-element-structs.md) | Arrays of Variable-Length-Element Structs | deferred(scope) | two | low |
|
||||
|
||||
### Platform Support
|
||||
|
||||
| OQ | Title | Status | Door | Pri |
|
||||
|----|-------|--------|------|-----|
|
||||
| [OQ-070](questions/070-no-std-alloc-support.md) | `no_std` + `alloc` Support | deferred(scope) | two | low |
|
||||
|
||||
### Schema Construction
|
||||
|
||||
| OQ | Title | Status | Door | Pri |
|
||||
|----|-------|--------|------|-----|
|
||||
| [OQ-071](questions/071-builder-api-for-schema-construction.md) | Builder API for Schema Construction | deferred(scope) | two | med |
|
||||
|
||||
## 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.
|
||||
This section exists so "what's currently blocking the architect" is
|
||||
answerable at a glance, not by filtering the tables above.
|
||||
|
||||
### OQ-069: Arrays of Variable-Length-Element Structs
|
||||
|
||||
- **Blocked on**: A concrete consumer that needs arrays of structs with
|
||||
variable-length fields, where the elements are interleaved
|
||||
(`[fixed_0][str_0][fixed_1][str_1]...`) and the engine must walk
|
||||
sequentially rather than use a fixed stride. The SFTP `Name` packet
|
||||
has `Vec<File>` where `File` contains strings, but SFTP serializes
|
||||
this as a sequence of length-prefixed strings (the serde `SeqAccess`
|
||||
pattern), not as an array of fixed-stride structs. Arrays of
|
||||
fixed-size structs are fully supported.
|
||||
- **Priority**: low
|
||||
- **Full file**: [OQ-069](questions/069-arrays-of-variable-length-element-structs.md)
|
||||
|
||||
### OQ-070: `no_std` + `alloc` Support
|
||||
|
||||
- **Blocked on**: An embedded use case that requires `no_std` + `alloc`
|
||||
(e.g., a microcontroller running Rust without `std`). The WASM target
|
||||
has `std` available via `wasm-bindgen`. The engine's core (offset
|
||||
computation, read/write) is already allocation-free; the `jsonschema`
|
||||
dependency is the only `alloc` consumer.
|
||||
- **Priority**: low
|
||||
- **Full file**: [OQ-070](questions/070-no-std-alloc-support.md)
|
||||
|
||||
### OQ-071: Builder API for Schema Construction
|
||||
|
||||
- **Blocked on**: A concrete need for programmatic schema construction
|
||||
in Rust. The current consumers (SFTP, metatensor, binary call frames,
|
||||
TTY negotiation) all have schemas that can be hand-written or
|
||||
generated from TypeBox. A builder API would be a fluent Rust API that
|
||||
produces the same JSON Schema structure — it would sit on top of the
|
||||
engine, not inside it.
|
||||
- **Priority**: medium
|
||||
- **Full file**: [OQ-071](questions/071-builder-api-for-schema-construction.md)
|
||||
Reference in New Issue
Block a user