Files

glm-5.2 1a8a44ed0e Draft builder API (ADR-009) and generalized validation validate_bytes (ADR-010) for v0.1.0

- ADR-009: fluent Rust builder producing serde_json::Value, covers
  AlkType kinds + standard JSON Schema; resolves OQ-003 (alkcall is the
  unblocking consumer)
- ADR-010: AlkTypeEngine::validate_bytes(&[u8]) as the single-call
  binary-buffer validation entry point; materialize Value from bytes,
  then validate; two methods on one struct, not a trait
- builder.md: full builder API spec (Schema, Definitions, Discriminator)
  with four usage examples (channels chunk header, call input schema,
  SFTP Packet union, OperationSpec error schemas)
- validation.md: new validate_bytes subsection + entry-point comparison
  table; AlkTypeEngine impl block updated; design decisions table updated
- overview.md: builder.md added to component pointers; 'Not a schema
  builder' scope boundary retired; ADR-009/010 added to decisions table;
  OQ-003 marked resolved; Consumers table adds alkcall as first consumer
- open-questions.md + questions/003: OQ-003 moved from deferred(scope)
  to resolved (ADR-009)
- README.md: builder doc + ADR-009/010 added; OQ-003 marked resolved;
  two new Key Design Principles (9, 10) for v0.1.0 additions

Doc-only change; 346 tests pass, clippy clean.

2026-08-11 05:41:49 +00:00

5.5 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-08-11

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 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 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-001	Arrays of Variable-Length-Element Structs	deferred(scope)	two	low

Platform Support

OQ	Title	Status	Door	Pri
OQ-002	`no_std` + `alloc` Support	deferred(scope)	two	low

Schema Construction

OQ	Title	Status	Door	Pri
OQ-003	Builder API for Schema Construction	resolved (ADR-009)	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.

Note

: OQ-003 (Builder API) was resolved by ADR-009 in v0.1.0 and is retained below for traceability — it's marked RESOLVED, not deferred. The currently-parked OQs are OQ-001 and OQ-002.

OQ-001: 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-001

OQ-002: `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-002

OQ-003: Builder API for Schema Construction — RESOLVED

Status: resolved by ADR-009 in v0.1.0.
Unblocking condition: alkcall — the merged alknet-call + alknet-channels extraction from @alkdev/alknet — is the concrete consumer that needs programmatic schema construction in Rust. It builds both binary-layout schemas (channels' 8-byte chunk header) and JSON payload schemas (OperationSpec input/output/error schemas) at runtime.
Resolution: A fluent Rust builder producing serde_json::Value, covering AlkType kinds and standard JSON Schema. Implemented in src/builder.rs; spec in builder.md. See ADR-009.
Full file: OQ-003

5.5 KiB Raw Blame History