lib-prism

Architecture

One crate, kinogaki-prism, with no dependencies. Owned code forbids unsafe.

Decisions

Typed storage. Components live in a Vec of their Rust type (Vec<f64>, Vec<u32>, …), not in a byte buffer. Callers borrow them as slices (as_f64s) or take them without a copy (into_f64s). Binary decoding is one bounds check and a bulk conversion per array; encoding writes through a 16 KiB stack block. Booleans and chars keep raw bytes so a non-canonical crate re-encodes identically.

Paths are strings. A Path is its validated canonical string, so lookups take &str (HashMap<Path, usize> with Borrow<str>) and ordering is bytewise, which is luce-prism's order and equals the C++ segment order for every path the C++ reader accepts.

Deterministic by construction. Properties, metadata and tombstones are BTreeMap/ BTreeSet; connections are a target→source map; wildcard links a sorted set. Every encoding is a function of content, so equal documents encode to equal bytes and the binary writer matches the reference without a sort pass.

Bounded, fail-closed decoding. Every count is checked against the remaining bytes (at the smallest possible record size) and against Limits before anything is allocated; declared array shapes are checked the same way in text. Malformed input is an Error with a kind, never a panic (truncation and mutation tests feed every prefix and thousands of random corruptions). Text errors carry line and column.

Streaming where it pays. write_to/save stream binary and text through a buffered writer without building the file in memory; loading reads the file once and decodes from the slice. Large numeric arrays dominate cost, and those paths run at memory bandwidth (see BENCHMARKS.md). Compression is optional and slow by comparison because its match search matches the reference byte for byte.

Composition is explicit. Decoding never follows reference arcs or touches the file system; compose takes a resolver, which is the security boundary.

Differences from the reference implementations

• From the C++ reference: names may contain - (luce-prism); the text reader rejects a property set twice in a block, out-of-range integers, multi-byte chars and invalid UTF-8; it reads general bool arrays, quoted animated property names and float3[], which the C++ reader cannot; the writer keeps signed zero and full-precision keyframe times; binary decoding rejects duplicate records, non-slot connection endpoints, unknown flags and unsorted keyframes instead of repairing them. overlay applies wildcard links stated in a layer and clears tombstones on elements it adds; diff deletes removed top-level elements (the C++ diff omits them, so its overlay cannot reproduce the target).
• From luce-prism: numbers are written in shortest round-trip form rather than %.9g/%.17g (both read back to identical values). The asset store is a separate Assets map used with packages, not part of Document.

Testing

• tests/fixtures.rs: the C++-generated crate, compressed crate and package fixtures are reproduced byte for byte; luce-prism's eight pinned model digests (SHA-256 of the reference crate) through all five encodings.
• tests/serialization.rs, tests/values.rs, tests/hardening.rs, tests/packages.rs and tests/layers.rs: serialization and compression, values and animation, hostile input, packages, and overlay, diff and reference cases.
• tests/robustness.rs: 400 generated documents (layers included) through text, binary, compressed, package-binary and package-text with byte-stable re-encoding; every truncated prefix; random mutations; hostile counts; limits.
• tests/oracle.rs (hand_run_, with PRISM_ORACLE; failing without it): both directions against the C++ reference on the fixtures, any PRISM_CORPUS directories and 300 generated documents; overlay/diff on layers.