| name | rust-adapters-success |
| description | Build the four boundary-crossing constructs — boundary decode, owned parse rule, wire envelope, ordered TryFrom lift — the only shapes for data crossing into or out of the kyzo engine. Fires before touching bytes from disk, a network request, a foreign file format, or an FFI/WASM boundary; before writing a parser or grammar rule with no typed owner; or before writing unwrap/expect on external input, a hand-rolled byte-indexing parser, or an untyped String error at a boundary. |
Adapters
The boundary constructs: how bytes and foreign shapes are trusted crossing in, and how domain values are rendered crossing out. Distinct from rust-values-success, whose constructs represent truth already inside the engine, and from rust-order-success, which proves the byte order those crossings must respect.
Boundary Decode
Definition
A decode function or TryFrom/TryInto impl that is TOTAL over every byte sequence: it returns a typed Result for every input, never panics, and every refusal names its reason and, where a grammar is involved, its span.
Required Form
pub fn decode(bytes: &[u8]) -> Result<Value, DecodeError> {
let mut cursor = Cursor::new(bytes);
let tag_byte = cursor
.read_u8()
.map_err(|_| DecodeError::Truncated { at: cursor.position() })?;
let tag = Tag::try_from(tag_byte).map_err(|_| DecodeError::UnknownTag {
at: cursor.position().saturating_sub(1),
byte: tag_byte,
})?;
decode_payload(tag, &mut cursor, Depth::start())
}
fn decode_payload(tag: Tag, cursor: &mut Cursor<'_>, depth: Depth) -> Result<Value, DecodeError> {
depth.check()?;
match tag {
Tag::Int => Ok(Value::Int(cursor.read_i64_be()?)),
Tag::Str => {
let len = cursor.read_checked_len()?;
let bytes = cursor.read_exact(len)?;
Ok(Value::Str(Str::try_from(bytes)?))
}
Tag::Bytes => {
let len = cursor.read_checked_len()?;
Ok(Value::Bytes(cursor.read_exact(len)?.to_vec()))
}
}
}
Recursive descent (nested value decoding) carries a typed depth bound, checked before each recursive call, so no adversarial input can exhaust the stack; no input-declared size (a length prefix) reaches an allocator as an unbounded or infallible reservation before it's validated against the remaining input length.
Sorting Rules
If the incoming shape already matches a domain type exactly, decode constructs that type directly — no intermediate "wire struct" exists purely to be immediately unwrapped. Data expected to sometimes legitimately fail (a corrupt frame, an unparseable tail) constructs through an ordered lift (below), not through a decode that treats "fails sometimes" as an error case.
Replaced Forms
A hand-rolled byte-indexing loop (bytes[i], bytes[i+1], ad hoc) scattered across a function restates what a total decoder should own in one place; a slice-indexing panic on out-of-range input is exactly the adversarial-totality failure this doctrine forbids. .unwrap()/.expect() anywhere in a decode path assumes the input is trusted, which is precisely the thing crossing a boundary is not.
Construct-Specific Doctrine
Adversarial totality — every byte sequence decodes to either Ok or a named Err, never a panic, never an infinite loop, never a catastrophic-backtracking blowup — is proven by fuzzing, never asserted by review (zone-model). A decoder with no fuzz target is a decoder whose totality is a claim, not a fact.
Allowed Patterns
fn decode(&[u8]) -> Result<T, TypedError> total over all inputs, bounds-checked, every failure named with reason (and span, where structural)- a typed, checked recursion depth bound on any self-referential decode
- a length-prefixed field validated against remaining input length before any allocation sized by it
- a fuzz target exercising the decoder against arbitrary bytes
Forbidden
.unwrap()/.expect()/direct slice indexing (bytes[i]) with no bounds check, anywhere a decode reads untrusted input- recursive descent with no depth bound
- an allocation sized directly by an input-declared length with no validation against remaining input size first
- a decoder shipped with no fuzz target
Halt Rule
Halt when a byte sequence cannot be classified as Ok or a named typed refusal, or when a recursive rule has no depth bound. Report the shape and the byte sequence: the decoder is not yet total, and the table is not finished.
Owned Parse Rule
Definition
Every grammar rule (pest production, combinator, token class) has exactly one owner: either a domain success type constructed from a successful parse, or an explicitly owned typed refusal variant. The grammar advertises nothing unowned (zone-model).
Required Form
pub enum ParseRefusal {
BadInt { span: Span },
BadList { span: Span },
UnexpectedToken { span: Span, found: TokenKind },
}
pub fn lift_value(pair: Pair<'_, Rule>) -> Result<Value, ParseRefusal> {
match pair.as_rule() {
Rule::int => Ok(Value::Int(parse_int(pair)?)),
Rule::list => Ok(Value::List(parse_list(pair)?)),
Rule::error_token => Err(ParseRefusal::UnexpectedToken {
span: span_of(&pair),
found: TokenKind::from(pair),
}),
other => Err(ParseRefusal::UnexpectedToken {
span: span_of(&pair),
found: TokenKind::Unknown(other),
}),
}
}
Sorting Rules
Byte-level adversarial decode without a grammar is Boundary Decode. A grammar rule whose only job is structure for another rule still needs an owner (the parent lift) or an explicit refusal if it can fail independently.
Replaced Forms
A pest/Rule arm that parses successfully but has no AST/domain type and no refusal variant is advertising a case nothing handles. A wildcard _ that drops the rule identity is an unowned path.
Allowed Patterns
- every grammar rule paired with an owning success type or an explicit typed refusal variant (reason + span)
- parse lifts that match exhaustively on
Rule (or equivalent) with no silent discard
Forbidden
- a grammar rule that resolves to no typed success case and no typed refusal
- a parse lift that ignores a successfully matched rule
Halt Rule
Halt when a grammar rule owns nothing. Report the rule: give it a success type or an explicit typed refusal, and the table is not finished.
Wire Envelope
Definition
A serde-derived struct (or Arrow schema) that is a total, round-trip-proven VIEW of an existing domain value for one wire format (JSON, Arrow) — it adds no meaning the value plane lacks, and it is never a second place a value's meaning is decided.
Required Form
#[derive(Serialize, Deserialize)]
pub struct FillWire {
order_id: String,
account_id: String,
fill_price: String,
filled_quantity: String,
}
impl From<&Fill> for FillWire { }
impl TryFrom<FillWire> for Fill { }
Sorting Rules
This program's own request/reply shape at a host boundary (rust-wiring-success's Sealed Public Door) is this construct; a value already representable directly by a domain type needs no wire twin at all — serialize the domain type itself.
Replaced Forms
A second serialization path for any value, anywhere, for any reason, is forbidden outright by zone-model — a second serialization of any value is named as a standing violation, not a case-by-case judgment call. A wire struct that becomes a second source of truth (fields added to the wire shape that the domain type doesn't have, silently carried through) is meaning smuggled past the ontology.
Construct-Specific Doctrine
Round-trip is proven, not assumed: a property test constructs a domain value, serializes it to the wire shape, deserializes back, and asserts equality — for every wire format the value crosses.
Allowed Patterns
- one
serde/Arrow wire struct per domain type per format, existing only where the wire shape genuinely differs from the domain shape
From/TryFrom conversions between the domain type and its wire twin, re-validating through the domain type's own constructors- a round-trip property test per wire format
Forbidden
- a second encoding of any value that competes with
rust-order-success's canonical encoding as a byte authority
- a wire struct carrying a field the domain type doesn't have
- a wire shape assumed to round-trip with no test proving it
Halt Rule
Halt when a wire shape would need to carry meaning the domain type doesn't have, or when two encodings of the same value would coexist. Report the value and the format: either the domain type is missing a field or a second byte authority is being created, and the table is not finished.
Ordered TryFrom Lift
Definition
TryFrom/an ordered attempt sequence for foreign data expected sometimes to legitimately fail or say no — the stronger construction attempted first, a named failure case last, composing from the input itself.
Required Form
pub enum Frame {
Tick(Tick),
Unparseable(UnparseableFrame),
}
impl TryFrom<&[u8]> for Frame {
type Error = Infallible;
fn try_from(bytes: &[u8]) -> Result<Self, Infallible> {
match Tick::try_from(bytes) {
Ok(tick) => Ok(Frame::Tick(tick)),
Err(_) => Ok(Frame::Unparseable(UnparseableFrame::from_raw(bytes))),
}
}
}
Fed bytes that parse, Tick constructs; fed garbage, Tick refuses and Unparseable composes from the same input. As a field, frame: Frame admits garbage as a declared value — never as a propagated error.
Sorting Rules
One question routes every failure: did the domain say no (a value — this construct), or did a proof fail (a bug or an adversarial input — this propagates as an Err, never silently swallowed into a default)? Identity-carrying data (a discriminant tag is present) constructs through the sum type's own discriminant (rust-values-success), never by attempt order.
Replaced Forms
A match/inspection function that peeks at a foreign reply's shape to decide which variant to build restates the selection the ordered TryFrom chain already performs. A .unwrap_or_default()/x.unwrap_or(fallback) on a fallible foreign parse manufactures a value nothing proved.
Construct-Specific Doctrine
The one legal fallback: the failure variant composes from the raw input itself (bytes, string, whatever arrived), never from a synthesized default unrelated to what actually arrived. A caught foreign exception/error type is captured once, at the earliest possible boundary call, and immediately fed into the ordered construction — never inspected, branched on, or partially handled first.
Allowed Patterns
- an ordered attempt sequence (strongest construction first, named failure variant last) as an enum's
TryFrom impl
- the failure variant composing from the raw input that arrived
- a captured foreign
Result::Err fed directly into the ordered construction, one call, one binding
Forbidden
.unwrap_or_default()/.unwrap_or(fallback) on a fallible foreign parse- a reply-inspection function or
match that decides a foreign reply's case before ordered construction runs
- a failure variant synthesizing a default value instead of composing from the actual input
- catching a foreign error and branching on its contents before ordered construction
Halt Rule
Halt when a foreign source produces a signal or marker not named by its own interface, or when the failure variant cannot compose from the input itself. Report the source and the signal: the wire's shapes are not fully modeled, and the table is not finished.
