Skip to content

feat(ffi): export tuples inside other types - #234

Merged
kixelated merged 10 commits into
mainfrom
quest/m1/ffi-export/tuples
Oct 30, 2026
Merged

kixelated merged 10 commits into
mainfrom
quest/m1/ffi-export/tuples

Conversation

@kixelated

@kixelated kixelated commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m1/ffi-export/tuples.md and deletes it.

Problem

ir::Type::Tuple crossed only as a function's whole return, through one out pointer per element. A tuple anywhere else was refused, which held back hang's catalog::Audio/Video::ranked (impl Iterator<Item = (&String, &Config)>), moq-net's stats::Snapshot::{control, traffic, sessions} (Vec of 2- and 3-tuples) and moq-mux's codec::annexb::find_start_code (Option<(usize, usize)>).

Approach

  • collect: a tuple maps wherever its elements do, each element as inside a value, as a Vec's item does. A tuple holding a reference is refused outside a return (tuple of references), as a Vec of references is. (Bound<T>, Bound<T>) keeps its own mapping everywhere but a whole success return, which ret still maps element by element.
  • C: a struct per distinct element list, <prefix>_tuple_<A>_<B>, named by the key rule options and Vecs use, with fields _0, _1, ...; borrowed elements hold clones. Two element lists sharing a name with different C layouts, which only nesting can cause, are a clash: a compile error. No _free, as an option struct has none: an array's free frees its tuples' elements.
  • C++: std::tuple, as a return already was. A parameter's tuple holds bytes as view, and is taken by value when it moves a handle in.
  • Kotlin: Pair, Triple, or a generated TupleN, as a return already was, and Tuple1 for a tuple of one anywhere but a whole return, so Option<(Option<T>,)> keeps Some((None,)) apart from None, and a borrowed or boxed one returned stays a tuple. A tuple of one returned whole is still its element. A JNI Wire codec per tuple struct; a handle moved in through a tuple is closed after the call.
  • A whole returned tuple keeps its C out pointers: the maintainer picked this option (keep out pointers, not breaking) over one struct everywhere.

The api fixture covers an Option of a 1-, 2- and 4-tuple, Option<(Option<u32>,)> round-tripped, a Vec of 3-tuples, a collected iterator of borrowed pairs holding a handle, a Vec parameter of tuples moving handles in, a record with tuple fields, nested tuples, a tuple parameter, (&str,) beside (String,), and a bound pair returned whole and as an error. C, C++ and Kotlin transcripts match native Rust's. The reject fixture covers the tuple-of-references refusal and the nested-name clash.

Census

just ffi census at the pin, before and after:

Package Row Before (exported / refused) After
hang Methods and fields 256 / 20 258 / 18
moq-net Methods and fields 560 / 17 563 / 14
moq-mux Functions 11 / 4 12 / 3

The six excludes leave ffi/moq/ffi.toml. No tuple refusal is left in any census.

Impact

  • C: new <prefix>_tuple_* structs, and new functions taking or returning them. No existing signature changes, so no MIGRATE.md entry.
  • C++: new functions only.
  • Kotlin: new functions, and a generated Tuple1 class when an export nests a tuple of one.
  • moq's export gains moq_catalog_audio_ranked, moq_catalog_video_ranked, moq_stats_snapshot_{control,traffic,sessions} and moq_codec_annexb_find_start_code.

Alternatives

  • A whole returned tuple as the struct, one rule everywhere: breaking for every tuple-returning C function, and moq's call sites read worse (made._0 against &origin, &driver). Not taken, per the maintainer.
  • Tuple names that encode arity, so nesting never collides: longer names for every tuple to avoid a clash only nesting causes, which now fails loud instead.

Review

Local quest review, codex gpt-6.1-sol medium, round 4 on head c25212cf1a716a15e1c64c77419b158f09c91af2: no findings.

Earlier rounds and online findings, all fixed:

  • Round 1: nested tuples sharing a C name overwrote one layout (now a clash); Kotlin erased a nested tuple of one, merging None and Some((None,)) (now Tuple1); a whole (Bound, Bound) return changed ABI (now kept).
  • Round 2: the clash compared IR types, refusing (&str,) beside (String,) (now compares C layout); a Result's bound-pair error became a tuple (now only a whole success return is).
  • Online, on 65e9db4d (ffi/src/kotlin.rs:1476, from the maintainer's local reviewer and Codex): Kotlin flattened a tuple of one after strip_refs, so a &(Vec<u8>,) or Box<(Vec<u8>,)> return, which C returns as the tuple struct, broke the JNI build. The flattening now reads function.ok itself; the api fixture's lent_back and boxed_tuple reproduce it and round-trip in C, C++ and Kotlin.

Merge of main at 802108e731c5030823cf7b5d3d54c80319e069b2: the only conflict was this PR deleting its finished quest file while #249 updated that file's links; resolved by deleting it. Nothing else changed since the reviewed head c25212cf, so this merge is a recorded skip, too trivial to review.

Checks

On head c25212cf, with origin/main merged (#231, #235, conflict-free): just check, just test (C, C++ and Kotlin transcripts), and just ffi moq (C, C++, Kotlin) pass. just ffi census ran on the first head; the later fixes change no moq mapping.

Follow-ups

None.

🤖 Generated with Claude Code

(written by Claude Opus 5.5)

kixelated and others added 3 commits October 29, 2026 13:07
A tuple now crosses wherever its elements map: as a Vec's or iterator's item,
inside an Option or Result, as a record's field, or as a parameter. C gets a
struct per element list, <prefix>_tuple_<A>_<B> with fields _0, _1, ...; C++
a std::tuple and Kotlin a Pair, Triple, or TupleN, as a returned tuple already
was. A whole returned tuple keeps its out pointers.

hang's catalog Audio/Video::ranked, moq-net's stats::Snapshot::{control,
traffic, sessions} and moq-mux's codec::annexb::find_start_code now export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Tuples inside other types feat(ffi): export tuples inside other types Oct 29, 2026
kixelated and others added 4 commits October 29, 2026 14:31
A whole returned tuple keeps its C out pointers, as the maintainer picked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n, and wrap a nested tuple of one in Kotlin

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d clash tuples only on C layout

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review October 29, 2026 21:49
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-30T01:51:50.722437Z c25212c New commits
🔒 Security Review ✅ Completed 2026-10-30T01:54:12.448561Z c25212c New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Automated review by review (OpenAI)

Reviewed commit 65e9db4.

One P2: Kotlin's singleton-return flattening also catches a borrowed tuple, although that return uses a tuple struct rather than an element out pointer. The inline finding gives a concrete generated-JNI compilation failure.

Direction: the recursive tuple representation and preservation of existing whole-return C out pointers are sound choices. The reported local fixes for name collisions, nested Tuple1 nullability, and bound-pair returns/errors are reflected in the code; restrict the remaining flattening to the actual whole-tuple ABI and add a borrowed singleton-bytes fixture.

Verification: GitHub-only static review of the diff and collector, ABI, C/C++, Rust glue, Kotlin/JNI and fixture surroundings. No builds, tests, census, or generated consumer runs executed; reported passing checks were not independently reproduced.

(Written by OpenAI)

Comment thread ffi/src/kotlin.rs Outdated
let ok = strip_refs(&function.ok);
// A tuple of one returned whole is its element, written through its one out pointer.
let ok = match strip_refs(&function.ok) {
Type::Tuple(mut elements) if elements.len() == 1 => elements.remove(0),

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

[P2] Flatten only a tuple returned through element out pointers

strip_refs removes the reference before this test, so newly admitted pub fn bytes(value: &(Vec<u8>,)) -> &(Vec<u8>,) { value } is also flattened to Vec<u8>. Its original IR return is Ref<Tuple<Vec>>, however, so Abi::export returns the tuple struct directly, not a buffer out pointer. In the direct-return JNI branch, put(&ok, "ret") then emits w.put(rt::Owned(ret)) for that tuple struct. The generated tuple implements Wire, but Owned<tuple_struct> does not (the runtime implementations cover buffers/lists), so the generated JNI crate fails to compile. Base the singleton exception on the original whole-tuple return/ABI rather than the reference-stripped type, and cover this borrowed singleton-bytes return in the differential fixture. This is a static trace, not an executed reproduction.

(Written by OpenAI)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in c25212c: the flattening now matches on function.ok itself, before strip_refs, so only a tuple of one returned whole (written through its one out pointer) is its element; one behind a reference or Box stays a Tuple1, matching the struct C returns. The api fixture's lent_back(&(Vec<u8>,)) -> &(Vec<u8>,) and boxed_tuple(Vec<u8>) -> Box<(Vec<u8>,)> reproduced the JNI build failure (Owned<api_tuple_bytes>: Wire unsatisfied) and now round-trip in C, C++ and Kotlin against native Rust.

(written by Claude Opus 5.5)

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 65e9db4da6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread ffi/src/kotlin.rs Outdated
Comment on lines +1475 to +1476
let ok = match strip_refs(&function.ok) {
Type::Tuple(mut elements) if elements.len() == 1 => elements.remove(0),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Flatten singleton tuples only when the ABI uses element outs

For a newly supported return such as fn bytes() -> &'static (Vec<u8>,) or Box<(Vec<u8>,)>, stripping references and boxes before checking the arity flattens the Kotlin result even though the C ABI returns a tuple struct by value, rather than through an element out pointer. Locally generating the borrowed case produces w.put(rt::Owned(ret)), where ret is the tuple struct, but Owned<tuple_struct> has no Wire implementation, so the generated JNI bindings fail to build. Restrict flattening to an actual top-level Type::Tuple in function.ok, and cover borrowed and boxed singleton byte tuples in the differential tests.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in c25212c: the flattening now matches on function.ok itself, before strip_refs, so only a tuple of one returned whole (written through its one out pointer) is its element; one behind a reference or Box stays a Tuple1, matching the struct C returns. The api fixture's lent_back(&(Vec<u8>,)) -> &(Vec<u8>,) and boxed_tuple(Vec<u8>) -> Box<(Vec<u8>,)> reproduced the JNI build failure (Owned<api_tuple_bytes>: Wire unsatisfied) and now round-trip in C, C++ and Kotlin against native Rust.

(written by Claude Opus 5.5)

kixelated and others added 2 commits October 29, 2026 18:21

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Automated review by review (OpenAI)

Reviewed commit c25212c, comparing against my prior review at 65e9db4 and separating inherited main changes.

Fixed: the borrowed singleton-tuple JNI P2 in the earlier finding. Matching the original return shape before stripping references keeps the tuple-struct wire representation; only a true whole singleton tuple is flattened. The new borrowed-byte tuple regression exercises this distinction across C, C++ and Kotlin, with boxed-tuple coverage alongside it.

No new actionable bugs found in this delta. Direction: this narrow fix preserves the existing C return ABI without adding another conversion path, and the differential fixtures are appropriate.

Verification: GitHub-only static inspection of the fix, JNI direct/out-parameter paths and fixture ownership/cleanup, including an independent review pass. No builds, tests or census were executed; the reported passing checks were not independently reproduced.

# Conflicts:
#	quest/m1/ffi-export/tuples.md
@coderabbitai

coderabbitai Bot commented Oct 30, 2026

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 24c8430a-e947-4f45-80d7-88e973446486
Commits

Reviewing files that changed from the base of the PR and between e51ecad and 802108e.

Files selected for processing: 18
  • ffi/README.md
  • ffi/fixtures/api/examples/transcript.rs
  • ffi/fixtures/api/src/lib.rs
  • ffi/fixtures/reject/expected.txt
  • ffi/fixtures/reject/src/lib.rs
  • ffi/moq/ffi.toml
  • ffi/src/abi.rs
  • ffi/src/c.rs
  • ffi/src/collect.rs
  • ffi/src/cpp.rs
  • ffi/src/glue.rs
  • ffi/src/ir.rs
  • ffi/src/kotlin.rs
  • ffi/tests/api.c
  • ffi/tests/api.cpp
  • ffi/tests/api.kt
  • quest/m1/ffi-export/README.md
  • quest/m1/ffi-export/tuples.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@kixelated
kixelated merged commit 5962344 into main Oct 30, 2026
2 checks passed
@kixelated
kixelated deleted the quest/m1/ffi-export/tuples branch October 30, 2026 05:28
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