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.
This commit is contained in:
1 parent
57d8ed25ba
commit
1a8a44ed0e
8 files changed
+1250
-39
No files matched your search
@@ -4,23 +4,21 @@
|
||||
[../overview.md](../overview.md);
|
||||
`@alkdev/alknet: docs/research/alknet-typedef/findings.md` (the builder
|
||||
API was noted as the one detail not covered by the POCs)
|
||||
- **Status**: deferred(scope)
|
||||
- **Status**: resolved
|
||||
- **Door type**: Two-way (additive — a builder API can be added without
|
||||
changing the existing JSON-consumption path)
|
||||
- **Priority**: medium
|
||||
- **Impacts**: Blocks programmatic schema construction in Rust without a
|
||||
JS toolchain. Any consumer that wants to build alktype schemas at
|
||||
runtime from Rust code (rather than loading pre-authored JSON) must
|
||||
construct the JSON manually or depend on TypeBox. Does NOT block any
|
||||
current consumer — all v1 consumers (SFTP, metatensor, binary call
|
||||
frames, TTY negotiation) use pre-authored schemas.
|
||||
- **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.
|
||||
- **Resolution**: Not yet decidable. The builder API is important but
|
||||
not needed for the initial consumers. The engine's JSON-consumption
|
||||
path is the primary interface for v1. 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.
|
||||
- **Cross-references**: ADR-001, [schema-layer.md](../schema-layer.md)
|
||||
- **Impacts**: (resolved) Was: blocks programmatic schema construction
|
||||
in Rust without a JS toolchain.
|
||||
- **Blocked on**: (resolved) Was: a concrete need for programmatic
|
||||
schema construction in Rust.
|
||||
- **Resolution**: Resolved by [ADR-009](../decisions/009-builder-api.md)
|
||||
in v0.1.0. alkcall — the merged `alknet-call` + `alknet-channels`
|
||||
extraction from `@alkdev/alknet` — is the concrete consumer that
|
||||
unblocked the deferral: it builds binary-layout schemas (channels'
|
||||
8-byte chunk header) and JSON payload schemas (`OperationSpec`
|
||||
input/output/error schemas) at runtime from Rust code. The builder
|
||||
produces `serde_json::Value`, covers both AlkType kinds and standard
|
||||
JSON Schema, and is implemented in `src/builder.rs`. See
|
||||
[../builder.md](../builder.md) for the spec.
|
||||
- **Cross-references**: ADR-001, ADR-009, [../builder.md](../builder.md)
|
||||
Reference in new issue
Block a user