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:
2026-08-02 05:59:12 +00:00
parent eac7ad88b3
commit 2c4a4994dc
36 changed files with 13805 additions and 0 deletions

View 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)