Skip to content

feat(ffi): Kotlin runtime helpers take underscore-prefixed names - #807

Merged
kixelated merged 4 commits into
mainfrom
quest/m1/ffi-export/kotlin-runtime-names
Nov 14, 2026
Merged

kixelated merged 4 commits into
mainfrom
quest/m1/ffi-export/kotlin-runtime-names

Conversation

@kixelated

@kixelated kixelated commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Kotlin's runtime helper classes, which _Native nests, now take a leading __ (__Reader, __Writer, __Handle, __Cleanup, __Returned, __Drop, __Lent, __Free, __Signal, __Pollable, __Ready, __Pending, __Eq, __Failed). This follows #777's naming for _Native. They're gone from TAKEN, so an exported type named like one keeps its name and no longer gets a trailing _.

  • ffi/runtime/rt.kt and the glue templates in ffi/src/kotlin.rs use the new names.
  • The unit test that required every runtime class to be in TAKEN now requires each one to start with __ (runtime_classes_prefixed).
  • The api fixture exports an object Handle, and tests/api.kt calls Handle.new(5u) and the async Handle.later(6u) under that name. The async case covers a factory return inside _Native.

Decisions

  • The prefix is __, not _. A single _ would clash with feat(ffi): Kotlin variant classes never shadow a name their enum uses #777's _<Name> import aliases for exported types, which Codex caught in review round 1.
  • StartSeekable stays in TAKEN without a prefix. It's a public interface that users implement, like Waker and Bytes, not an internal helper.
  • I added just one fixture type, Handle, an object. It's the helper whose name clashed most inside the glue.

Waiting

  • Maintainer: pick this to merge. It changes the generated Kotlin's helper names (_X to __X), so it lands only on your pick. Recommendation: merge; CI passes and Codex's review of 7549a88 found nothing.

Models

Size: S
Implementer: Claude, claude-opus-5-5, unknown effort
Implementer: Claude Code, claude-opus-5-5, low effort (iterate, S)

🤖 Generated with Claude Code

(Written by Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: 7549a88

  • Base: origin/main at 639d8bf

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

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

  • Session: 01a1db2a-3afc-7603-87c2-1b314be90aed, round 1

  • Score: 9/10, The helper renames are consistent across the Kotlin runtime and generator, and the fixture covers the formerly reserved Handle name; no actionable defects were found by inspection, though builds and tests were not run as instructed.

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

  • Findings: none

Summary by CodeRabbit

  • New Features

    • Added a handle type that can be created with a count, report its count, and be created asynchronously.
  • Improvements

    • Kotlin runtime helper names now use a __ prefix, reducing conflicts with exported Kotlin names.
    • Updated Kotlin exception documentation to reference the correct exception factory.
  • Tests

    • Added coverage for synchronous and asynchronous handle creation.

Summary by CodeRabbit

  • New Features
    • Added a Handle API with a count getter and synchronous and asynchronous constructors.
  • Compatibility
    • Kotlin-generated runtime helper names now use a double-underscore prefix.
  • Tests
    • Added coverage confirming that both Handle constructors preserve the supplied count.

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Kotlin runtime helper types and generated references now use a __ prefix. The generator no longer reserves former helper names. The API fixture adds a public Handle type and tests its synchronous and asynchronous constructors.

Changes: Kotlin Runtime Naming

Layer / File(s) Summary
Prefix runtime helper declarations
ffi/runtime/rt.kt
Runtime helper types and internal references use __-prefixed names. The await signature and checks use the renamed signal and result types.
Update generated references and name reservations
ffi/src/kotlin.rs, ffi/runtime/jni.rs, quest/m1/ffi-export/kotlin-runtime-names.md
Generated Kotlin references use prefixed helper names. Former helper names are removed from TAKEN, and the runtime-class test checks that declarations have the prefix. The JNI documentation uses _Native.__Failed, and the runtime naming plan document is removed.
Add a public Handle fixture
ffi/fixtures/api/src/lib.rs, ffi/tests/api.kt
The API fixture adds Handle with a constructor, a count accessor, and an async constructor. The Kotlin test checks the counts returned by both constructors.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Refactor

Merge Risk: Minimal · up to 7549a

This change renames internal Kotlin runtime helpers with a __ prefix so exported types such as Handle keep their names. All references checked are consistent, and no actionable merge-blocking risk was found. Run the Kotlin build and tests as usual before merging.

Security architecture risk: Minimal · up to ba696

The inspected changes consistently separate internal helper names from exported API names. They do not introduce a material change to native-handle ownership, cleanup, cancellation, or privileges. Applications using formerly renamed exported types may need to update their Kotlin references when regenerating bindings.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The demonstrated new entrypoint exposure is a fixture object whose caller-controlled unsigned count is stored and returned, synchronously or asynchronously. Its implementation does not route that value to a privileged operation. The broader production effect established by the change is generated Kotlin name resolution, not additional native authority.

Trust Boundaries and Controls

  • observed — The generated native-call container remains internal, object raw-handle constructors remain internal, and callback dispatch retains its existing casts and close delegation. The rename does not replace those boundaries with public raw-handle construction.

Resilience and Maintainability Implications

  • observed — The source comparison preserves existing close/hold atomic transitions, repeated-close behavior, cleaner ownership tracking, and async finally cleanup. No new transition ordering or recovery behavior is introduced by the helper renames; this does not independently validate every pre-existing lifecycle guarantee.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: Kotlin runtime helpers now use underscore-prefixed (__) names. The changeset renames runtime helper classes in ffi/runtime/rt.kt and ffi/src/kotlin.rs, removes them …
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 names the main change: Kotlin runtime helpers now use underscore-prefixed (__) names. The changeset renames runtime helper classes in ffi/runtime/rt.kt and ffi/src/kotlin.rs, removes them from TAKEN, and updates the runtime-class test to check for the __ prefix. The title is specific and matches the primary change. The Handle fixture and the deleted planning document are secondary and need no mention in the title.

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: 1b05a1a7-fe83-4ac3-a89a-159ac5e71a9f
Commits

Reviewing files that changed from the base of the PR and between ba6964d and 7549a88.

Files selected for processing: 2

  • ffi/fixtures/api/src/lib.rs
  • ffi/src/kotlin.rs
Files skipped from review as they are similar to previous changes: 2

  • ffi/fixtures/api/src/lib.rs
  • ffi/src/kotlin.rs

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Kotlin runtime helpers take underscore-prefixed names feat(ffi): Kotlin runtime helpers take underscore-prefixed names Nov 14, 2026
…' `_<Name>` aliases

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 14, 2026 11:00

@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 — two stale doc comments inline.

Reviewed changes

I reviewed the rename of Kotlin's runtime helpers to __-prefixed names, their removal from TAKEN, and the new Handle fixture.

  • Runtime rename: every top-level class in ffi/runtime/rt.kt now starts with __, and so does _Native.__Failed. Every glue template in ffi/src/kotlin.rs uses the new names. A grep found no remaining unqualified or _Native.-qualified references to the old names, and jni.rs looks these classes up by method only, with no class-name strings.
  • TAKEN shrinks: the helper names are gone from TAKEN. StartSeekable and the Kotlin builtins stay.
  • Guard test: runtime_classes_prefixed now requires a __ prefix on top-level runtime classes, in place of the old TAKEN membership check.
  • Fixture: an exported Handle object, with a sync and an async factory, exercised from tests/api.kt under its own name.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread ffi/fixtures/api/src/lib.rs Resolved
Comment thread ffi/src/kotlin.rs Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@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

I reviewed what changed since the prior Pullfrog review at ba6964d.

  • Fixture comment: ffi/fixtures/api/src/lib.rs now says the runtime's helpers take a leading __, matching the actual prefix.
  • TAKEN doc: ffi/src/kotlin.rs now explains that the __ helpers need no place in TAKEN, because neither an exported type's name nor its _<Name> alias has that prefix. The wrap width is fixed too.

Both earlier threads are addressed and resolved.

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

@kixelated
kixelated added this pull request to the merge queue Nov 14, 2026
Merged via the queue into main with commit fc71dc3 Nov 14, 2026
10 checks passed
@kixelated
kixelated deleted the quest/m1/ffi-export/kotlin-runtime-names branch November 14, 2026 19:15
kixelated added a commit that referenced this pull request Nov 14, 2026
Main's #808 makes Score an opaque value, so the refusal fixtures hold a new
checked Copy handle, Mark. Its handed-back `&mut self` calls (#808) now pass a
status, which `Handed` places last; `Score::note(&Mark)` covers it. #807's
underscore names extend to `__Close` and `__Refused`, and Swift's moq program
drops the `try`s #808's values made unneeded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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