From 02ebcf9b92fbc3ff3c33fa09fbbd8846c55492e3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 16:46:10 -0800 Subject: [PATCH 1/2] docs(agents): a binding's native type stands in only where converting it to Rust can never fail Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 282d75755..1945c0f7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Each project lives in its own top-level directory; the [quest tree](quest/README One exception is an `unsafe` pointer from elsewhere whose origin translation can't see, such as a parameter's: a loud run-time check may stand in for the refusal, under m3's [unsafe policy](quest/m3/README.md), since refusing every such pointer would refuse pointer arithmetic on any parameter. The other is a binding, which checks at run time only the Rust rules its language cannot express: borrow exclusivity, use after a move or close, the thread of a value that is not `Send`, and a call of an item the library's target lacks. A failed check raises the language's own error, or aborts where it has none; a Rust panic aborts. - Generated output must match the source's semantics exactly: integer widths and overflow, drop order, laziness, and error paths. Prove it with differential tests against native Rust, not by inspection. -- A binding's types are lossless: every value of the Rust type crosses and returns exactly. A native type stands in only where it is exact; otherwise the runtime's own type crosses, with checked conversions to and from the idiomatic one. Speed ranks above ergonomics. +- A binding's types are lossless: every value of the Rust type crosses and returns exactly. A native type stands in only where converting it to the Rust type can never fail, such as `bool`, or a byte array for `Vec` in most languages. Otherwise the runtime's own type crosses, such as `rs.NonZeroU16`, or a string where the language's own can hold a lone surrogate, with checked conversions to and from the idiomatic one, so a value Rust cannot hold fails where it is built, never in a call. Speed ranks above ergonomics. - Everything is configless, with opinionated names and defaults. Translators take stock crates as they are: no annotations, and no config beyond true platform boundaries. Each config key or source change a consumer needs is a gap to close. - A vanity rename, if ever supported, is opt-in and lives inline in source next to the item, never in a config file. - moq is the first consumer of every project here; a binding target may be planned before any consumer asks for it. From 068b2802ff132361cc8e904de3cf1a1eaa2b5d4f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 16:47:10 -0800 Subject: [PATCH 2/2] docs(agents): check a runtime type's value once, at its conversion helper Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1945c0f7b..c51bb1a8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Each project lives in its own top-level directory; the [quest tree](quest/README One exception is an `unsafe` pointer from elsewhere whose origin translation can't see, such as a parameter's: a loud run-time check may stand in for the refusal, under m3's [unsafe policy](quest/m3/README.md), since refusing every such pointer would refuse pointer arithmetic on any parameter. The other is a binding, which checks at run time only the Rust rules its language cannot express: borrow exclusivity, use after a move or close, the thread of a value that is not `Send`, and a call of an item the library's target lacks. A failed check raises the language's own error, or aborts where it has none; a Rust panic aborts. - Generated output must match the source's semantics exactly: integer widths and overflow, drop order, laziness, and error paths. Prove it with differential tests against native Rust, not by inspection. -- A binding's types are lossless: every value of the Rust type crosses and returns exactly. A native type stands in only where converting it to the Rust type can never fail, such as `bool`, or a byte array for `Vec` in most languages. Otherwise the runtime's own type crosses, such as `rs.NonZeroU16`, or a string where the language's own can hold a lone surrogate, with checked conversions to and from the idiomatic one, so a value Rust cannot hold fails where it is built, never in a call. Speed ranks above ergonomics. +- A binding's types are lossless: every value of the Rust type crosses and returns exactly. A native type stands in only where converting it to the Rust type can never fail, such as `bool`, or a byte array for `Vec` in most languages. Otherwise the runtime's own type crosses, such as `rs.NonZeroU16`, or a string where the language's own can hold a lone surrogate, with helpers converting it to and from the idiomatic one. The caller checks a value once, at that conversion, rather than in every call it passes through, and a value Rust cannot hold fails there, never in a call. Speed ranks above ergonomics. - Everything is configless, with opinionated names and defaults. Translators take stock crates as they are: no annotations, and no config beyond true platform boundaries. Each config key or source change a consumer needs is a gap to close. - A vanity rename, if ever supported, is opt-in and lives inline in source next to the item, never in a config file. - moq is the first consumer of every project here; a binding target may be planned before any consumer asks for it.