Skip to content

feat(ffi): infer the instances generic items export at - #152

Merged
kixelated merged 10 commits into
mainfrom
quest/m1/ffi-export/instance-keys
Oct 28, 2026
Merged

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

Conversation

@kixelated

@kixelated kixelated commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

The exporter exported a generic type or function only at the instances ffi.toml's instances key named. moq-ffi still wrapped four instances by hand that the key could not spell. A new maintainer decision (2026-10-27), newer than the quest's plan to extend the key, says translators take stock crates as they are, with no config beyond true platform boundaries. So the exporter now infers its instances, and the instances key is gone instead of extended.

Approach

A generic type exports at the instances it infers:

  • its defaults, when each type parameter has one (hang's Catalog<()>, which exports DEFAULT_NAME);
  • the instance each concrete inherent impl is of (impl Pair<u32>);
  • each choice among a parameter's default and the types the exports implement its bounding exported trait for (catalog::Producer<E: CatalogExt> at (), hang::Extra, and ts::Ext);
  • each instance an exported signature or field names, once that is all its export refuses. This repeats until nothing new is inferred, before orphaned objects are refused.

An instance that holds an instance of a type inside it (Cell<Cell<u8>>) is refused, which bounds the closure. A generic function's parameter that no fixed rule picks exports once per implementor of its exported trait bound. It takes &X where that also meets the bound, so C keeps its handle (moq-net's with_publisher at &origin::Producer). Each instance is named by the shortest unique form of its arguments (see Decisions). exclude takes a generic item's path or an instance's, a function instance's included. rename takes the generic item's path and renames every instance.

moq's 16 instance keys are gone. The one line added is a rename of hang's Catalog, which its old key carried. 11 excludes for items that now export were pruned.

Impact

  • Breaking for the exporter's config: instances (top-level and [crates.*]) is removed. Unknown keys fail to parse. See ffi/MIGRATE.md.
  • Breaking for C and C++ names: instances change from config names to rule names (moq_catalog_producer becomes moq_catalog_producer_extra, moq_client_with_publisher becomes moq_client_with_publisher_producer). Adding an instance upstream can lengthen another instance's name. See ffi/MIGRATE.md. ir::Instance carries named arguments instead of a name.
  • A () field of an instance has no getter, since it holds nothing to read.
  • Census before and after (exported / refused), types | methods and fields:
    • hang: 59/12 to 68/8 | 186/26 to 256/23
    • moq-mux: 110/35 to 173/25 | 395/61 to 1047/98
    • moq-net: 119/33 unchanged | 517/34 to 521/33; functions 3/3 to 4/2
    • moq-tokio: methods 219/86 to 221/86; moq-clock and moq-pattern unchanged
  • moq's header: 701,698 to 864,184 B raw (+23%), 171,098 to 183,077 B gzipped (+7%), measured before the naming change and the merge of main. The growth is mostly moq-mux's container::Producer at every container and config it can take. Exporting takes 2.5 s vs 2.0 s on main. After both, moq.h is 875,525 B raw and 187,323 B gzipped, and moq.hpp is 1,593,016 B and 247,361 B. I didn't re-measure main at the same revision.

Alternatives

  • Extending instances to spell &T, IntoIterator, and serde_json::Value, as the quest planned. Superseded by the decision above.
  • Inferring only from signatures and defaults: this can't reach catalog::Producer<Extra>, which no moq signature names concretely. Only moq-ffi's own code does, and the stand-in is empty.
  • Treating pub type aliases of instances as seeds and names: moq has none, so this is left out.

Decisions

  1. How inferred instances are named, settled by the maintainer:

    • (a) Full argument names (moq_catalog_producer_catalog_hang_extra).
    • ✅ (b′) The shortest unique form. Each argument takes the last segment of its C name, and an argument takes one more segment at a time only where two instances of one item would otherwise share a name. Counter::seeded is api_counter_seeded_point at Point and api_counter_seeded_polar_point at polar::Point.
    • (c) No suffix for a function's only instance.

    Each name depends on the item's whole set of instances, never on crate iteration order, so an instance added upstream can lengthen another's name (documented in the README and MIGRATE.md). A short name that still matches an unrelated item's C name fails as a clash at both spans, as any other name does. abi.rs unit tests cover lengthening over several rounds, an argument with no more segments, and order independence. The api fixture's polar::Point covers a clash end to end from C, C++, and native.

Choices made without asking

  • A parameter exports at &X rather than X when both meet its bound, which leaves C its handle.
  • A function instance is suffixed even when it exports at one type, so a new upstream impl does not rename it.
  • IntoIterator as a Vec and serde_json::Value are type mappings, not instances, so they stay in the rewritten quest. The &T argument and Catalog<()> land here.

Merging main

Review fixes

  • An instance with a const argument is refused, as the IR keeps only type arguments.
  • exclude of a function instance's path now applies.
  • An implementation for &X beside X's gives one instance, not a clash with itself.
  • A nested instance argument is named from its own path and arguments. Its arguments lengthen first, then its path, and it never reads its item's other instances, so A<B<u8>> beside B<A<u8>> no longer overflows the stack.
  • Inference walks the arguments of every candidate, so an instance made only by its own impl infers the instances inside it.
  • A parameter with a lifetime bound, such as 'static, never exports at a reference.
  • An instance that only a constant names is inferred.

Checks

  • After each round of review fixes: just check, just ffi test, and just ffi moq pass, and reverting each fix reproduces its failure. moq's C names are unchanged by the second round.
  • After merging main: just check passes, just ffi test passes (14 fixtures plus 3 unit tests, with the C++ matrix), and just ffi moq passes (C and C++).
  • Before the merge: just check passed.
  • Before the merge: just ffi test passed 14/14. The api fixture's C transcript matches native, and now drives inferred type and function instances, defaults, and &X. The reject fixture covers nested, excluded, and unmappable instances.
  • Before the merge: just ffi moq passed. The export built, and moq/moq.c ran on the new names.
  • Not run: just ffi bench (needs the bench shell; moq/bench/export.c uses no renamed names), and the ts, uniffi, and driver tests (untouched).

Follow-ups

  • Suggested quest: rename by an instance's path, so one instance can be named apart when its short name clashes with an unrelated item. Today the escape hatch is renaming the generic item, which renames every instance.

  • Iterator and JSON arguments the exporter can't map yet, this quest rewritten. Why json_snapshot's T: Serialize refuses String is worth a look there.

  • Suggested quest: measure the header and glue size that implementor products add, as moq-mux's container::Producer exports at 16 instances, and consider pruning instances that no consumer reaches.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

kixelated and others added 4 commits October 27, 2026 19:38
…instances key

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… remains

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Instances the config can't name yet feat(ffi): infer the instances generic items export at Oct 28, 2026
kixelated and others added 3 commits October 28, 2026 09:57
…que form

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… instances

main's `instances` keys for `Slot` are gone: `Slot<u8>` infers from its impl,
and `Slot<u32>` from a signature that names it. The reject fixture drops main's
cases of the removed key. api.cpp and moq.cpp follow the inferred names, and a
lent closure's type is kept per instance, as a foreign implementation's is.

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

chatgpt-codex-connector Bot commented Oct 28, 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-28T18:04:08.832507Z 04d4a57 New commits
🔒 Security Review ✅ Completed 2026-10-28T18:06:16.284236Z 04d4a57 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.

@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: 9094047af4

ℹ️ 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/collect.rs Resolved
Comment thread ffi/src/collect.rs Resolved
Comment thread ffi/src/collect.rs Resolved

@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: 9094047af4ccc30cbee5b0f4a270cd20513c1401.

P2 — Honor instance-specific renames before deriving the suffix (ffi/src/abi.rs:170–180, also function_name). Only the generic IR path reaches self.name(path), so an entry such as [rename] "Pair<u32>" = "pair" is never consulted and fails with “rename … names nothing exported.” The same applies to a specialized function path. This loses the promised per-instance rename escape hatch after removing instances: callers cannot preserve one specialization's ABI name or repair its clash without renaming every specialization. Carry the concrete instance path into naming, check its exact override first, then fall back to generic-name-plus-suffix; add an end-to-end rename fixture.

I independently found the specialized-function exclusion issue already reported here; please check exclude after constructing shown, rather than adding another inline thread. The existing const-argument loss and borrowed-implementor duplication findings also remain applicable on this head.

Direction: fixed-rule inference fits the stated no-instance-config goal; the bounded closure and deterministic naming are reasonable. Completing concrete-instance selectors is simpler than restoring an enumeration config.

Verification: static inspection of the collector, naming/config/driver changes and C/C++ fixtures only; I did not run builds or tests.

… and dedupe implementors

An instance with a const argument is refused, as the IR keeps only type
arguments. An `exclude` of a function instance's path, such as
`Stack::depth_past<api_fixture::polar::Point>`, now leaves it out. An
implementation for `&X` is taken as it is, never borrowed again, and one beside
`X`'s chooses `&X` once instead of twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

On the per-instance rename point in the automated review from the maintainer's account: I agree it's a gap, but I'm leaving it out of this PR. I removed the PR body's claim that rename takes an instance's path. For now, renaming the generic item renames every instance, and a short name that clashes with another item fails loudly at both spans. I listed per-instance rename as a suggested follow-up quest.

(Written by Claude Opus 5.5)

@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: b582b69c40069226b036fdb89c690d7603a75e30, against my previous review of 9094047af4ccc30cbee5b0f4a270cd20513c1401 (same base).

No new actionable bugs found in this update. The three previously referenced collector findings are addressed: const-generic instances are rejected before lowering; specialized function exclusions are checked after constructing their path; borrowed implementors are normalized and deduplicated. The added reject/API/C/C++ fixtures target those cases.

The previous instance-specific rename finding is deferred, not implemented: the PR description now removes its support claim and explicitly documents the limitation/follow-up. Generic-item renaming remains the workaround; I am not presenting this unchanged limitation as a new finding.

Direction: these narrow fixes are appropriate and avoid adding unnecessary machinery. Verification was static inspection of the one-commit delta and relevant surrounding collector/naming behavior; I did not run tests or builds.

@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: b582b69c40

ℹ️ 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/abi.rs Resolved
Comment thread ffi/src/collect.rs Resolved
…nfer them

An instance's argument that is itself an instance takes its names from its own
path and arguments, never from its item's other instances, so `A<B<u8>>` beside
`B<A<u8>>` no longer recurses without end. Inference walks the arguments of
every candidate, not only those a signature names, so `Outer<Inner<u8>>` made
by its own impl infers `Inner<u8>`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@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: 3db0ba011250edb857a7125a2b5192191556cf99, compared with my last reviewed head b582b69c40069226b036fdb89c690d7603a75e30 (unchanged base).

No new actionable bugs found in this delta. The independently reported recursive naming-group overflow and missing nested seed arguments are addressed: argument forms now depend on the finite argument tree instead of recursively naming entire instance groups, and inference walks all seed candidates. The new cross and Outer<Inner<u8>> fixtures exercise both paths through native/C/C++ consumers.

Direction: computing local argument forms is a simpler fix than adding naming-group cycle state. The earlier three collector fixes remain intact; instance-specific renaming remains explicitly deferred, not a new finding.

Verification: static inspection of this one-commit change and surrounding naming/inference behavior only. I did not run builds or tests.

@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: 3db0ba0112

ℹ️ 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/collect.rs Resolved
Comment thread ffi/src/collect.rs Resolved
…tances constants name

A type parameter with a lifetime bound, such as `'static`, never exports at a
reference, which a value C passes for the call cannot meet. A constant's type
is mapped through `naming`, so an instance only a constant names is inferred.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@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: 04d4a5714f46db87f2f0fc5ecad7a01e643971bb, against my last reviewed head 3db0ba011250edb857a7125a2b5192191556cf99 (same base).

No new actionable bugs found in this delta. The independent lifetime-bound specialization finding is addressed by choosing owned implementors when the parameter has an outlives bound, rather than relying on a modulo-regions check to justify borrowing. The constant-only inference finding is addressed by routing constant getters through the existing naming bookkeeping. The kept and BOXED native/C/C++ fixture additions exercise those cases.

Direction: reusing the inference mechanism and conservatively avoiding a borrowed specialization are appropriately small fixes. Earlier fixes remain intact; instance-specific renaming remains explicitly deferred, not a new finding.

Verification: static review of the one-commit delta and relevant collector behavior only; I did not run builds or tests.

@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: 04d4a5714f

ℹ️ 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/collect.rs
Comment on lines +1429 to +1431
let declared = (tcx.generics_of(def_id).own_params.iter())
.filter(|p| matches!(p.kind, ty::GenericParamDefKind::Type { synthetic: false, .. }));
let args = declared.filter_map(|p| arg(args.type_at(p.index as usize))).collect();

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 Preserve inferred closure arguments in function specializations

For a signature such as fn apply<T: Copy, F: Fn(u32) -> u32>(p: Pair<T>, f: F) -> u32, with Pair<u32> inferred from a concrete inherent impl, specializing T makes this loop map every declared parameter, including F. However, instantiate() deliberately leaves F as a type parameter and records its closure mapping separately; arg(F) then rejects it because that mapping is available only in parameter position. Consequently, an otherwise supported function combining instance inference with a named closure parameter cannot export. The same issue affects named foreign-callback parameters. Preserve an inference placeholder for these arguments instead of requiring a concrete exported type.

AGENTS.md reference: AGENTS.md:L34-L34

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.

Agreed this is a gap, but I'm deferring it: the maintainer chose to merge after the fourth review round. The export refuses this case loudly, with no silent fallback, and moq doesn't hit it. I'm recording it as a follow-up quest on inference gaps, covering closure and callback arguments of inferred function instances.

(Written by Claude Opus 5.5)

Comment thread ffi/src/collect.rs
Comment on lines +1762 to +1763
if !found.contains(&ty) && self.ty(ty, Pos::Param).is_ok() {
found.push(ty);

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 Infer concrete generic implementors before checking their mapping

When an exported generic record such as Wrap<T> { pub value: T } implements an exported generic trait at Wrap<u32>, a function taking impl Seed<u64> cannot discover that specialization unless another signature, default, or inherent impl already seeds it. implementors() finds Wrap<u32>, but this ty() check rejects its not-yet-inferred instance and only appends it to pending. Since instantiate() then fails before function() enters naming(), the candidate never reaches named, so inference stops and refuses both the record and the function. With instances removed, consumers must change their Rust API to make this supported specialization discoverable. Feed concrete generic implementors into inference before requiring them to map.

AGENTS.md reference: AGENTS.md:L34-L34

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.

Agreed this is a gap, but I'm deferring it: the maintainer chose to merge after the fourth review round. The export refuses this case loudly, and moq doesn't hit it. I'm recording it in the same follow-up quest: feeding concrete generic implementors into inference before mapping them.

(Written by Claude Opus 5.5)

@kixelated

Copy link
Copy Markdown
Collaborator Author

Landing at 04d4a57 with a direct squash merge (quest merge --land is blocked until #137's land-queue setup is done).

  • Checks: Check passed on 04d4a57. just ffi test, just ffi moq, and just check passed locally.
  • Codex: rounds 1 to 3 fixed. Round 4's two findings on 04d4a57 (closure or callback params on inferred function instances, and concrete generic implementors not fed into inference) are deferred to a follow-up quest, as replied in their threads.

(Written by Claude Opus 5.5)

@kixelated
kixelated merged commit c57756a into main Oct 28, 2026
1 check passed
@kixelated
kixelated deleted the quest/m1/ffi-export/instance-keys branch October 28, 2026 18:18
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