Skip to content

feat(ffi)!: a value whose None fills its niche crosses as its bytes - #899

Merged
kixelated merged 11 commits into
mainfrom
quest/m1/ffi-export/niche-values
Nov 20, 2026
Merged

kixelated merged 11 commits into
mainfrom
quest/m1/ffi-export/niche-values

Conversation

@kixelated

@kixelated kixelated commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Before this change, full in ffi/src/collect.rs counted a variant without data as initializing 0 bytes. So any Copy type holding an Option<NonZero<u64>> fell back to a handle, moq's Timestamp ({ value: u64, scale: Option<Timescale> } at moq 1aa86d5e6) among them. But when rustc encodes such a variant in another variant's niche, it writes the niche's whole scalar. full now counts that.

  • Least.niche changes from a bool to the smallest niche scalar the type may hold, both on this target and at each model width (4- and 8-byte pointers). A thin pointer's niche is its word, a wide pointer's is its first word, bool is 1 byte, char is 4, a pattern type or NonNull-like range comes from rustc's largest_niche, and an enum gets its variants' smallest niche when it is full, otherwise 1 byte.
  • In an enum with a niche, a variant whose fields hold no bytes counts that smallest niche. If a rustc gave the enum a tag instead, the enum is at least a byte bigger than a variant whose fields fill it, so neither it nor anything holding it is ever full. A miscount therefore never makes something a value.
  • moq's Timestamp crosses as its 16 bytes again. So do transport::ReceiveWindow (Option<NonZeroU64> + u64), transport::Limits (Option<NonZeroU64>), and hang::catalog::Clock (a Timestamp).
  • ffi/moq/moq.* and ffi/moq/bench/export.* no longer free, close, or dispose timestamps. Their comments say "copied" again, as they did before kixel-ai/rust2#881.
  • New api fixture type Rated { count: u64, scale: Option<NonZero<u64>> }. The new Miri test niche_value reads each word of one holding None and one holding Some with assume_init, as C reads them.
  • opaque_values gains these values: Scaled (the Timestamp shape), Lent (Option<&u32>), Nested (Option<Option<bool>>), and Chars (Option<char>). It gains these handles: Unset (Option<u32>), Narrow (Option<(u32, NonZero<u32>)>), and Sliced (Option<&[u8]>). It exports for both wasm32 and the host.
  • The quest is deleted and its link removed from ship.md. ffi/README.md and bench/ffi/README.md describe the rule and carry the measurements.

Public API

Breaking for moq's bindings in every language: Timestamp, transport::ReceiveWindow, transport::Limits, and hang::catalog::Clock change from handles to opaque values. Migration: drop each _free, close(), Close(), use {}, or [Symbol.dispose]() on them, and pass them by value. In C, moq_Timestamp_* functions take const moq_Timestamp * and lose their moq_status *, and constructors write a moq_Timestamp value. In Go, a value's methods return no status error. The api fixture gains Rated. No wire impact.

Decisions

These are mine to make without the maintainer, recorded for review:

  1. The smallest niche any field offers, not rustc's largest_niche (the Plan proposed the latter). Only "full" makes a value, and another rustc at the same size may pick a different niche, so the smallest is the bound that holds whatever it picks. largest_niche is still used for a niche no field shows (pattern types, NonNull), scaled to the model's widths.
  2. Any variant whose fields hold no bytes counts the niche, not only one without fields. A variant of ZST fields, such as B(()), is never the untagged variant, so it writes the niche the same way.
  3. An enum that isn't full offers a 1-byte niche to an enum around it, since a tag or a partly written niche may be only a byte.
  4. Rated is new rather than a reshaped Moment. Moment's non-optional NonZero rate is what each language's "returned zero" check relies on. Rated sits only in the fixture, the surfaces, and the Miri test, not in the transcript, so the per-language scripts (kixel-ai/rust2#885, now on main) are untouched.

Validation

  • just ci passes.

  • just ffi moq: moq's scripts pass in C, C++, Kotlin, Python, Swift, Go, and Dart against the regenerated export.

  • Miri (api_miri, sanitize shell): miri::niche_value passes along with the rest.

  • Independent check of the rule: a scratch program wrote each None into MaybeUninit bytes and read every byte under cargo miri run, on x86_64 and i686. Stamp {u64, Option<NonZero<u64>>}, Option<&u32>, Option<Option<bool>>, and Option<char> read clean. Option<u32>, Option<(u32, NonZero<u32>)>, and Option<&[u8]> hit "Undefined Behavior: ... uninitialized memory". That is exactly the split full now makes.

  • opaque_values' header shows the four values as typedef struct { uint64_t opaque[n]; } and the three handles with _free.

  • Bench: just ffi bench on this branch and on main at 2f63f110, on fedora (Ryzen 9 9950X), load 17 to 24, median of 3 rounds each. Stamped write minus write, CPU ns:

    C C++ Swift Go Dart Kotlin Python TS (Node)
    handle (main) 40 30 56 149 111 210 218 283
    value (this PR) 20 10 7 58 36 220 138 138

    Rust's own from_micros takes 8 to 9 ns of that on both builds. Kotlin's CPU time, which counts its JIT and collector, moved within noise. The two builds were not run interleaved: the disk was at 91% and the build cache evicted this worktree's target/ twice mid-run.

Follow-ups

None.

Models

Size: M
Implementer: Claude Code, claude-opus-5-5, unknown effort (arm B)

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: 635032e

  • Base: origin/main at a9fef6e

  • Risk: high, Reclassifying exported types changes the C ABI and generated public APIs, requiring downstream consumers to regenerate and rebuild their bindings; reverting restores the prior interfaces.

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1f75b-1d53-7640-8731-9737729cc4ed, round 3

  • Score: 9/10, No actionable defects were found in the incremental changes or merge integration, though builds and tests remain unverified.

  • Raised the risk to high: Reclassifying exported types changes the C ABI and generated public APIs, requiring downstream consumers to regenerate and rebuild their bindings; reverting restores the prior interfaces.

  • Rounds: 3; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

After round 3, efe55a94 fixed Pullfrog's one low-severity note, a stale comment in ffi/moq/moq.cpp:164. Comment only, so no new round. Pullfrog approved that head.

Summary by CodeRabbit

  • New Features

    • Added a Rated value type, with construction, equality, debugging, and scale access across supported language bindings.
    • Timestamps and related transport and clock types are now value-style types across bindings, with updated APIs for passing optional timestamps.
    • Added value-based transport configuration types and accessors.
  • Documentation

    • Updated FFI guidance to explain how niche layouts affect value representation, with examples and benchmark results.

Summary by CodeRabbit

  • New Features

    • Added a Rated value type across supported language bindings, with construction, equality, debugging, and scale access.
    • Timestamps, transport settings, and catalog clocks now use value-style representations across bindings. APIs that accept optional timestamps and update configuration values have been revised accordingly.
  • Documentation

    • Updated FFI guidance and examples on how niche layouts affect value representation, and revised benchmark comparisons.

@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The FFI layout collector now tracks niche widths when classifying opaque values. MoQ timestamps, clocks, and transport configuration use value-oriented representations across language bindings. The PR adds a Rated fixture and updates related tests, benchmarks, and documentation.

Changes: Niche-aware opaque values

Layer / File(s) Summary
Niche-width accounting and fixtures
ffi/src/collect.rs, ffi/tests/fixtures.rs, ffi/README.md
Niche analysis now tracks scalar widths and uses them in enum layout calculations. Fixtures and documentation cover niche-encoded values and cases that remain handles.

Rated API and MoQ value types

Layer / File(s) Summary
Rated value API across surfaces
ffi/fixtures/api/src/lib.rs, ffi/surface/api/*, ffi/tests/miri/api.rs
The fixture adds Rated with a count and optional nonzero scale. Public declarations and a Miri test cover construction, access, and value representation.
MoQ C value contract
ffi/surface/moq/c.h
The C declarations use value types for timestamps, clocks, and transport configuration. Timestamp parameters and results use values or explicit optional-value wrappers.
MoQ binding declarations
ffi/surface/moq/cpp.hpp, ffi/surface/moq/{dart.dart,go.txt,kotlin.kt,python.pyi,swift.swift}, ffi/surface/moq-web/web.d.ts
The language declarations update MoQ value types and timestamp-bearing APIs to use value-oriented forms.
MoQ integrations and benchmark updates
ffi/moq/*, ffi/moq/bench/*, bench/ffi/README.md, quest/m1/ffi-export/*
The C integration test and cross-language benchmarks use timestamp values. Test descriptions and benchmark documentation reflect the value representation.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Possibly related PRs

  • kixel-ai/rust2#808: Moves eligible Copy types from handles to opaque values and uses the same classification rules for niche and padding behavior.
  • kixel-ai/rust2#742: Introduced the by-value crossing rule for eligible Copy types. This PR updates the niche-based classification used by that rule.
Merge Risk: Minimal · up to efe55

The change updates a test comment to describe timestamps as copied values, which matches the new C declarations. No merge-blocking risk was found. The broader breaking change to value-style MoQ bindings is intentional and documented in the PR description.

Architecture risk: Low · up to efe55

The change affects 3 systems.

Changed systems: ffi, quest, bench

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — ffi (service) was modified; 33 changed files map to changed impact.
  • observed — quest (service) was modified; 2 changed files map to changed impact.
  • observed — bench (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in bench/ffi/README.md: The timestamp-cost discussion now describes Timestamp as a Copy value whose None scale is encoded in its niche, replacing the prior account that it crossed as 16 bytes while retaining the measured handle costs and comparison with value costs.
  • observed — Modified behavior in bench/ffi/README.md: The description now says Timestamp’s None scale is written as the niche’s whole u64, while retaining the listed per-language representations.
  • observed — Modified behavior in bench/ffi/README.md: Adds a comparison of stamped-write-minus-write costs for Timestamp as a handle at 2f63f110 versus as a value across C, C++, Swift, Go, Dart, Kotlin, Python, and Node. The text attributes 8–9 ns per call to Rust’s from_micros and says Kotlin’s CPU-time change is within its noise.
  • observed — Modified behavior in ffi/README.md: The opaque-value layout description now treats a data-free enum variant occupying another variant’s niche as that niche’s whole scalar, and gives Option<NonZero<u64>> as an 8-byte None layout example. It adds Option<&[u8]> to the cases represented as objects because None may leave bytes uninitialized; previously the example listed only Option<u32> and described its bytes as value-dependent.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "feat(ffi)!: a value whose None fills its niche crosses as its bytes" matches the main change. The PR changes FFI classification so a Copy type whose None representation fills a niche is exp…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title "feat(ffi)!: a value whose None fills its niche crosses as its bytes" matches the main change. The PR changes FFI classification so a Copy type whose None representation fills a niche is exported by value rather than as a handle. The diff reflects this across the moq Timestamp, transport ReceiveWindow, transport Limits, and hang catalog Clock types, the niche analysis in ffi/src/collect.rs, the Rated fixture, and the opaque_values tests. The title is specific, uses the conventional commit form, and marks the breaking change with the ! marker, which the objectives describe as affecting every moq binding.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 828c6745-d114-4d50-ac5a-a075e38d4dc4
Commits

Reviewing files that changed from the base of the PR and between 635032e and efe55a9.

Files selected for processing: 1

  • ffi/moq/moq.cpp

Limit details: You’ve used all 10 included reviews currently available.

@kixelated kixelated changed the title Cross a value whose niche fills its bytes as an opaque value feat(ffi)!: a value whose None fills its niche crosses as its bytes Nov 20, 2026
@kixelated
kixelated marked this pull request as ready for review November 20, 2026 05:36

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No critical issues. One stale comment the port missed.

Approach: sound. Counting a dataless variant as the niche's whole scalar (the smallest across every field) gives a lower bound that holds for whichever niche a rustc picks. If a rustc tags instead, the enum ends up larger than any variant's fields, so the miscount can never make an unsound value.

Reviewed changes

This run covered the full diff at ca23749: the full() rule, its fixtures and Miri test, the hand-written moq scripts and bench programs, and the regenerated surfaces.

  • full() niche accounting (ffi/src/collect.rs): Least.niche changes from a bool to the smallest niche scalar, on this target and at both model widths. A zero-byte variant now counts that scalar, and an enum that isn't full offers a 1-byte niche to an enum around it. I traced Option<NonZero<u64>>, Option<&[u8]>, Option<Option<NonZero<u64>>>, Option<(u32, NonZero<u32>)>, NonNull<[u8]> via ranged, and a ZST single-variant enum. Each one either is truly full or stays a handle.
  • Fixtures: opaque_values adds the four values and the three handles, and the Miri niche_value test reads every word of Rated with assume_init for both None and Some.
  • moq bindings: Timestamp, transport::ReceiveWindow, transport::Limits, and hang::catalog::Clock change from handles to values. The scripts and bench programs drop their frees, closes, and disposes. The surfaces match: rt.Opaque, setters that return the value, and no clone/k_*.
  • Docs: ffi/README.md and bench/ffi/README.md explain the rule and add the handle-vs-value table. The quest is deleted and removed from ship.md.

ℹ️ ffi/moq/moq.cpp still calls a timestamp a handle

The PR rewrote the timestamp comment in moq.c, moq.dart, moq.go, moq.kt, moq.py, and moq.swift to say "copied", but not in moq.cpp. Line 164 still says // A timestamp is a handle, which a call borrows and leaves usable. The code there works either way, so only the comment is wrong. This file isn't in the diff, so the note can't go inline.

Technical details
# Stale handle comment in the C++ moq script

## Affected sites
- ffi/moq/moq.cpp:164 — `// A timestamp is a handle, which a call borrows and leaves usable. The track is untimed,`

## Required outcome
- The comment says a timestamp is a `Copy` value copied across, matching the other moq scripts.

## Suggested approach (optional)
- Use the wording from `moq.kt`/`moq.py`/`moq.swift`: "A timestamp is a `Copy` value copied across, which allocates nothing. The track is untimed, so a timed frame is refused."

Pullfrog  | Fix it ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No new issues. The one earlier note still stands.

Reviewed changes

This run covered ca23749..635032e. That range only merges main (#896, Python records and exceptions) and regenerates the outputs that depend on it.

  • Merged main: ffi/src/collect.rs merges cleanly. The only change there is main's new variants field, and the niche accounting is untouched. ffi/tests/fixtures.rs picks up main's idioms Python case.
  • Regenerated the surfaces: the API_CONTRACT hashes in ffi/surface/api/c.h changed. In the Python stubs, records now derive from _Record. Rated and HangCatalogClock still derive from _n.Value.
  • Kept the quest removal: niche-values.md is still deleted. After the merge, ship.md drops both the Niche values and the Python idioms lines.

ℹ️ ffi/moq/moq.cpp still calls a timestamp a handle

This was raised in the previous review and is unchanged. ffi/moq/moq.cpp:164 still says // A timestamp is a handle, which a call borrows and leaves usable., but every other moq script now says a timestamp is copied. The code works either way. Only the comment is stale, and the file isn't in the diff, so the note can't go inline.

Technical details
# Stale handle comment in the C++ moq script

## Affected sites
- ffi/moq/moq.cpp:164 — `// A timestamp is a handle, which a call borrows and leaves usable. The track is untimed,`

## Required outcome
- The comment says a timestamp is a `Copy` value copied across, matching `moq.kt`/`moq.py`/`moq.swift`.

Pullfrog  | Fix it ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated

Copy link
Copy Markdown
Collaborator Author

Fixed in the latest push: ffi/moq/moq.cpp:164 now says a timestamp is a Copy value copied across, as the other moq scripts do.

(Written by Claude Opus 5.5)

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

This run covered 635032e..efe55a9, a single commit.

  • Fixed the stale comment in ffi/moq/moq.cpp: the timestamp comment now says it is a Copy value copied across, matching the other moq scripts. This closes the one note from the earlier reviews.

Pullfrog  | View workflow run | Using claude-sonnet-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit aa1fe7a Nov 20, 2026
9 checks passed
@kixelated
kixelated deleted the quest/m1/ffi-export/niche-values branch November 20, 2026 06:31
@codspeed

codspeed Bot commented Nov 20, 2026

Copy link
Copy Markdown

Merging this PR will regress 2 benchmarks

1 warning

⚠️ 26 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚡ 4 improved benchmarks
❌ 2 regressed benchmarks
✅ 79 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ write 787.8 ms 1,404.1 ms -43.89%
❌ ready 3.5 s 4 s -12.41%
⚡ stamped 2.3 s 1.6 s +43.28%
⚡ stamped 214 ms 178.3 ms +20.05%
⚡ stamped 203.1 ms 177.9 ms +14.17%
⚡ stamped 62.3 ms 54.8 ms +13.69%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing quest/m1/ffi-export/niche-values (efe55a9) with main (1fd44bd)1

Open in CodSpeed

Footnotes

  1. No successful run was found on main (a9fef6e) during the generation of this report, so 1fd44bd was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant