Skip to content

docs(agents): a binding's native type stands in only where converting it to Rust can never fail - #935

Merged
kixelated merged 2 commits into
mainfrom
docs/exact-binding-types
Nov 21, 2026
Merged

kixelated merged 2 commits into
mainfrom
docs/exact-binding-types

Conversation

@kixelated

@kixelated kixelated commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Sharpens the lossless-types rule in AGENTS.md. A binding's native type now stands in only where converting it to the Rust type can never fail, such as bool, or a byte array for Vec<u8> in most languages. Anything else crosses as the runtime's own type, such as rs.NonZeroU16, with helpers converting it to and from the native type. A value is checked once, at that conversion, instead of in every call that takes it, and a value Rust cannot hold fails there rather than mid-call.

The rule already said a native type stands in "only where it is exact". The Kotlin binding read "exact" loosely: NonZeroU16 is a UShort, char is an Int, and usize is a ULong. Each of those holds values Rust cannot, so the binding checks them in the call. In a closure's return value, that failure lands mid-Rust, which is what kixel-ai/rust2#922 unwinds through. The new wording names the test (can the conversion fail?), so the case is no longer a judgment call.

Decisions

Decided with the maintainer on 2026-11-20:

  • ✅ Runtime types for anything a language cannot express identically, with checked casts to and from them (the maintainer's direction).
  • ✅ Strings follow the rule too: where the language's own string can hold a lone surrogate (Kotlin/Java, JS/TS, Dart), a runtime string type crosses (rejected: the native String as a named exception; deciding per language).
  • ✅ Each runtime type gets helpers converting it to and from the native type, so a caller checks a value once, at the conversion, instead of in each of the N calls it passes through.
  • bool needs no runtime type, though it may be an alias; Vec<u8> needs none where the language's byte array converts infallibly.

Bringing the bindings in line is a follow-up, planned separately by this run's /quest-plan.

Public API

None. It is an instruction for agents. The generated bindings change only when that follow-up lands.

Validation

No behavior to exercise. just ci passes.

Models

Size: XS
Implementer: Claude Code, claude-opus-5-5, unknown effort

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: 068b280

  • Base: origin/main at 74f5652

  • 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: 01a1fb91-dd8f-7c60-bbee-0b0ced0e67fc, round 2

  • Score: 10/10, The incremental change clarifies that binding conversions validate values once, introduces no identifiable defect, and is ready to land.

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

  • Findings: none

  • Reviewer: Codex, gpt-6.1-sol, low effort, shadow

  • Session: 01a1fb91-dd8f-7821-84bd-e7c78b624645

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

Summary by CodeRabbit

  • Documentation
    • Clarified how bindings handle type conversions and when conversion failures occur.

… it to Rust can never fail

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

coderabbitai Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The binding documentation now limits native boundary types to conversions that cannot fail. Otherwise, the runtime type crosses the boundary with conversion helpers. Values that Rust cannot represent fail during conversion.

Changes: Binding type conversion policy

Layer / File(s) Summary
Boundary type and conversion rules
AGENTS.md
Native types cross the boundary only when conversion to the Rust type cannot fail. Otherwise, the runtime type crosses with conversion helpers. Callers check values during conversion, where unrepresentable values fail.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Suggested reviewers: pullfrog

Merge Risk: Minimal · up to 068b2

This PR clarifies binding guidance on when native types may cross the Rust boundary. It changes no runtime behavior or public API, so merging it carries minimal risk.

Architecture risk: Low · up to 068b2

The change affects 1 system.

Changed systems: AGENTS.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — AGENTS.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in AGENTS.md: The binding type policy now permits native types only when conversion to the Rust type cannot fail; otherwise, the runtime’s type crosses with conversion helpers. It also specifies that callers check values once at conversion and that values Rust cannot represent fail there, replacing the prior general checked-conversion rule.
Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title states that a binding's native type stands in only where converting it to Rust can never fail. The raw summary and PR objectives describe this same rule: a native type may stand in for a Rus…
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.
Full details: Title check

Explanation

The title states that a binding's native type stands in only where converting it to Rust can never fail. The raw summary and PR objectives describe this same rule: a native type may stand in for a Rust type only when conversion to Rust cannot fail, and the change is a documentation update to AGENTS.md. The title names the main change and is specific. It uses the docs(agents) prefix and is long, at 95 characters, but this does not make it unrelated or vague.

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: f6b059d4-a4a1-4808-bb22-c8b706f7b7b8
Commits

Reviewing files that changed from the base of the PR and between 74f5652 and 068b280.

Files selected for processing: 1

  • AGENTS.md

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

…lper

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

@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.

Approach: sound — the rule now names a testable criterion (can the conversion to Rust fail?) instead of the loose "exact".

Reviewed changes

Reviewed the single-line AGENTS.md edit in full.

  • Lossless-types rule: a native type stands in only where converting it to Rust can never fail. Otherwise a runtime type crosses, with conversion helpers, and the check happens once at the conversion rather than in each call.

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

@kixelated
kixelated added this pull request to the merge queue Nov 21, 2026
Merged via the queue into main with commit cd40ee4 Nov 21, 2026
10 checks passed
@kixelated
kixelated deleted the docs/exact-binding-types branch November 21, 2026 01:05
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