[0.33][ABI] Support bounded nested dynamic values with canonical codecs #48

Alpha closure disposition — 2026-10-28

The implementation is included in v0.33.0-alpha.1. The maintainer explicitly authorized publication after integration tests, without CI or additional peripheral review. This issue is closed for that alpha implementation scope; public APIs may still change.

The original stable-admission checklist below is retained. Its unexecuted full-gate and stable-freeze conditions are deferred for this alpha, not recorded as passed. See the alpha validation record and the Chinese closure comment for completed evidence and remaining boundaries.

Outcome and version

Planned for 0.33, following the maintainer's October 5 request. Support explicitly bounded nested dynamic values, beginning with lists of variable-length bytes and records containing variable-length payloads, with one canonical codec contract across source, builders and on-chain verification.

Priority within this program: 2 — nested dynamic data, following the highest-priority Cell selection/correspondence work; independent codec implementation can proceed in parallel. Record implementation ownership and review disposition before executable admission.

Motivation and duplicate check

Use cases: batches of differently sized messages or proof payloads, variable-metadata records, and batch state migration payloads. Admitting their encoding does not authenticate a bridge message or establish a proof system's security.

Reviewed all 41 existing open/closed issues on October 5. #13 owns authenticated commitment openings, including its accepted bounded profile; this issue owns general nested value representation and does not silently broaden an existing commitment codec. #23 owns value-generics rules; #24 owns typed bounded source reads. #43/#44 own financial and ZK application semantics, not general nested codecs. No direct duplicate was found, and their existing acceptance requirements stay in place.

The baseline matrix already permits selected single-level dynamic fields. Vec<Vec<u8>> has no general runtime verifier. This issue must preserve those distinctions.

flowchart LR
    Source["Declared witness or Cell-data source"] --> Bounds["Check total bytes, counts and nesting depth"]
    Bounds --> Codec["Validate canonical Molecule offsets and lengths"]
    Codec --> View["Typed bounded nested views"]
    View --> Rules["Application predicates"]
    Rules --> Output["Verify the declared successor encoding"]
    Builder["Generated builder and shared vectors"] --> Codec
    View -. "Optional owned materialization" .-> Heap["Bounded collection memory contract"]

Required decisions and scope

1. Freeze two initial shapes: a bounded list of byte strings and a bounded list of records with fixed identity fields plus a variable byte payload. Specify outer/inner counts, per-element bytes, total bytes and maximum depth. Arbitrary recursive schemas are not admitted.
2. Reuse Molecule schemas and existing source/ABI infrastructure. Specify canonical empty values, optional values, offset tables, field boundaries and exact consumption of bytes. Check all integer arithmetic before pointer/range calculations; reject malformed offsets, truncation, aliasing/overlap where forbidden, out-of-range lengths and noncanonical trailing bytes.
3. Keep source ownership and identity explicit. Design bounded read-only views first; nested decoding must not require a new heap allocator. If owned mutation/materialization is added, it depends on the separate bounded collection-memory contract and must retain lifetime/alias rules.
4. Make the admitted shapes executable for witness validation and single-Cell input/successor data checks. Verify the actual output encoding, total size and occupied-capacity requirements on chain. Batched multi-Cell selection/lifecycle remains owned by the separate Cell-set issue.
5. Bind recursive schema identity, bounds, source, codec and compatibility classification into public interfaces, metadata, typed semantics, builders and checker records. Any extension of [Language design] Add explicit typed openings for digest-committed substate #13's authenticated openings needs an explicit versioned profile, not an implicit codec change.

Authoring direction — 2026-10-19

The maintainer adopted this authoring direction on 2026-10-19. Existing experimental lowerings and tests remain reusable evidence; they do not freeze the final public API. Exact declaration grammar remains to be selected against complete programs. This adds acceptance work within #47–#49 and preserves every existing runtime, checker, builder, resource, gate and review requirement; it is not a release claim or review waiver.

Keep explicit borrow root as view { ... } for a useful lexical read-only region, without requiring a borrow block for every ordinary permitted field read. Distinguish semantic prohibitions from current proof/implementation limitations. Checked, bounded, non-escaping read-only helper composition must preserve each view's root, source, bounds, lifetime and authority. Current call/escape restrictions stay enforced until those proofs exist; this does not authorize general mutable borrowing, escaping borrowed values or foreign lifecycle authority.

Treat NestedValues<T, N, P, B> as the current experimental spelling, not a frozen final authoring API. Associate reusable data shapes with named item-count, per-payload and total-encoded-byte limits, declared once and resolved into the existing codec/metadata/builder contracts. Exact alias, attribute or declaration syntax is still a design decision. Preserve the distinction between codec limits and the complete entry-witness budget; authoring cleanup must not silently alter canonical wire bytes.

At use sites, support ordinary indexing, fields and iteration without requiring authors to repeat internal derived-view types. Demonstrate checked non-escaping read-only helper calls over admitted byte-list and record-list views while retaining the validated root, schema, bounds and backing lifetime. Evaluate these in the complete variable-payload batch migration with #49, while retaining this issue's independent witness and single-Cell successor acceptance.

Acceptance

• Review complete byte-list and record-list programs, including the [0.33][Runtime] Extend bounded Cell selection and correspondence for heterogeneous and dynamic data #49 variable-payload batch and reusable helper extraction, before freezing the public authoring form; retain current/proposed source comparisons and the decision.
• Named count/payload/encoded-byte bounds resolve identically in source, interfaces, metadata, checker and generated builders; wrong or conflicting bounds produce clear declaration diagnostics and no silent wire/entry-budget change.
• Checked non-escaping helper composition preserves source/schema/buffer lifetime; source substitution and stale/escaping views reject. The final syntax has formatter, completion/rename and browser-summary parity without forcing all predicates into one action.
• Exact supported shapes, operations, contexts and numeric budgets are frozen before acceptance measurements; unsupported combinations remain fail-closed.
• Shared canonical vectors cover empty/single/mixed-size/maximal inputs and round trips through independent Rust and generated-builder consumers.
• CKB-VM positives exercise nested witness reads and actual single-Cell successor encoding; malformed offset/length tables, overflow, excessive depth/count/bytes, wrong source, stale views and substituted output bytes reject at the intended boundary.
• Checker mutations rebind outer identities and demonstrate rejection of omitted or changed nested bounds, codec/source identities and output checks.
• Parser/types/lowering, formatter/LSP, metadata/WASM and generated builders agree wherever affected; old wire formats retain their semantics or have an explicit versioned migration.
• Publish measured valid and late-invalid cycles, stack/memory, ELF, witness/transaction bytes and occupied capacity at frozen maxima. Adversarial encodings must not trigger unbounded repeated decoding.
• Appropriate dev, backend and ci gates pass on identified source, and the scope-specific review disposition is recorded before stable admission.

General recursive heap graphs, hidden Cell resources inside values, automatic bridge/proof authentication and arbitrary dynamic collection mutation are outside this codec contract. Successful parsing alone does not close this issue.

Related 0.33 work

#47 owns allocation-backed value collections. Read-only nested decoding is independent; owned nested materialization may depend on #47 only after both ownership and codec contracts admit that combination.

#49 consumes this codec in its variable-payload Cell batch phase; its fixed-layout selection phase can proceed independently.