Flat: a resolved model with direct access, not a stream of elements

[milyin]

Stage L0.5 of #229. #227 produced a Vec<Element>; this makes it a model that
can be asked questions, and closes the flat API so its references mean something.

Targets language-integration, not main.

Why

Three things about L0's output were wrong for what consumes it next.

It was a stream, so nobody could ask it anything. Every later stage needs to
look an item up by name. L1's checklist carried "elements are indexed by name" as
an afterthought; it is a property of the model.

References were unresolved. A parameter naming Storage yielded
TypeKind::Named { id } and nothing more. Whether that name denoted anything
surfaced much later as ResolveError::Unresolved from the fixed-point resolver —
the "one source-language fact, several authorities" #211 exists to end. Names live
in one flat namespace, so resolution is decidable at parse time.

Element mixed two levels. Function | Struct | Variant | Enum | Const put
type declarations beside functions and constants.

And the module was called language while the thing it models is the flat API.

What

pub enum Element { Function(Function), Type(Type), Constant(Constant), Unsupported(Unsupported) }
pub enum Type    { Struct(Struct), Variant(Variant), Enum(Enum), Opaque(Opaque) }

let flat = Flat::builder().source(PREBINDGEN_OUT_DIR).build()?;
flat.function("storage_get");        // answers by name
flat.resolve(&id);                   // a reference leads to its declaration

The type reference becomes TypeRef, freeing Type for the declaration.
Struct::fields drops its Option — None was the opaque case, which is now its
own entity.

Opacity is declared

#[prebindgen] pub type X = path; yields Type::Opaque. This reverses #227,
where a marked alias became Unsupported. It is how a foreign or crate-private
type gets a name in the flat API without any claim about its contents — and it
is the prerequisite for requiring references to resolve. A marked tuple struct
declares the same thing, unchanged from #227.

References resolve at parse time

A third pass walks every TypeRef — through Option, Vec, &, Result,
arrays, callback arguments and generic arguments alike. An item naming a type the
flat API does not declare becomes Element::Unsupported with
ItemError::UnresolvedType: deferred, not fatal, like every other refusal, so an
item no binding declares stays harmless. A path-qualified name gets its own
diagnosis, since #[prebindgen] pub type foreign::Option = .. is not a spelling
that exists.

Note the two resolutions stay distinct: this says a name denotes something,
while an adapter's resolver still decides whether it supplied a converter for it.

An out-parameter is a mode of borrowing

MaybeUninit is only meaningful behind a &mut, so uninitialized-ness is a
property of the borrow, not of a type. Ref carries the mode and absorbs it:

Ref { mode: RefMode, inner: Box<TypeRef> }
enum RefMode { Shared, Exclusive, Out }   // &T, &mut T, &mut MaybeUninit<T>

One axis, three values, and inner is always the borrowed value's type — so the
combinations that mean nothing at a boundary cannot be written down. Owned,
returned or in a field, uninitialized storage promises nothing; &MaybeUninit<T>
promises a readable T that may not be one. Both are refused, each naming why.

Out rather than Uninit because it names the boundary role every destination
language has (C's T *out) — the fact an adapter acts on. cbindgen was already
classifying MaybeUninit itself, so this moves that decision into the frontend per
#211; it is also the one foreign generic no alias can name, a generic alias being a
generic binder.

Closing the example flat APIs

Every referenced type had to become a declaration. Two idioms, chosen by what the
type is rather than by its Rust shape:

• A handle gets a marked alias. Storage, the three callback handlers,
  Token, TokenGc, Summary, Archive, Report, EscapeProbe,
  StorageError, Calculator move into a private handles module with
  #[prebindgen] pub type X = handles::X;. The alias is transparent, so every
  signature still reads the same. Error in both crates was already an alias and
  needed only the attribute — the shape zenoh-flat's 26 re-exports will take.
• A public newtype stays a marked struct. Millis, Celsius, Percent,
  Label are not handles: they cross by convert!, and covertest-helpers both
  constructs them and reads .0. An alias names the type but not the
  tuple-struct constructor, which lives in the value namespace — hiding them broke
  that downstream, which was the useful signal.

That second distinction also protects the goldens: a marked struct enters
registry.structs, and write.rs emits on_struct for any declared type there —
so marking the handles as structs would have changed generated output. A marked
alias is invisible to the registry (Item::Type no longer reaches passthrough
either, since an opaque declaration is not code to copy into a binding and its
target is routinely crate-private).

The closure is asserted, not assumed. covertest-kotlin's build script runs
Flat over both its sources and fails if anything is unsupported — the only place
the helper crate's references to perftest-flat's types resolve, since it cannot
mark them itself. Verified by deliberately unmarking Storage: the build fails,
naming all twelve referencing functions and the fix.

Verification

502 unit tests and 17 doctests pass on --all --all-features and on default
features; clippy clean; the boundary ledger unmoved. examples/regen-check.sh
reports byte-identical — the source crates were restructured and the model
rebuilt, and generation did not move. covertest-kotlin's JVM run passes all 47
sections.

Out of scope, and will break

zenoh-flat, zenoh-flat-c and zenoh-flat-jni are separate repos. Their 28
unmarked types (26 zenoh aliases plus Duration and Cow<'_, [u8]>) need the same
treatment before they parse. Cow<'_, [u8]> has no alias spelling, so
zbytes_to_bytes needs either the MaybeUninit treatment or a signature change.

Noticed while surveying: zenoh-flat-c/build.rs:539 declares zbytes_as_bytes,
which no longer exists in zenoh-flat (renamed zbytes_to_bytes) — that repo is
already stale against zenoh-flat HEAD.

Refs #211. Umbrella: #229.

🤖 Generated with Claude Code