feat(native): add checked scalar conversions

[proggeramlug]

Summary

Add the checked scalar-conversion slice proposed by the stable perry/native value profile. The new value-side i32, i64, u32, u64, usize, f32, and f64 functions reject values that cannot be represented without changing their meaning.

Changes

• expose same-name value conversions alongside the existing native scalar type aliases
• lower named, aliased, and namespace imports through native dispatch
• validate finite/integral/range/precision constraints with catchable TypeError and RangeError failures
• document the conversion contract and regenerate the public API reference
• add runtime, HIR, manifest, declaration-generation, and executable regression coverage

Related issue

Refs #6827

Test plan

• ./scripts/test_affected_crates.sh --base origin/main
• ./scripts/pre-tag-check.sh --quick
• cargo test -p perry-runtime native_value_profile --lib -- --nocapture
• cargo test -p perry-hir --test native_arena native_scalar -- --nocapture
• cargo test -p perry-codegen --test manifest_consistency
• PERRY=target/perry-dev/perry bash tests/test_native_value_profile.sh
• Added runtime, compiler, declaration, and end-to-end tests
• Updated docs/src/ and generated API documentation

Screenshots / output

The executable regression prints PASS after checking POD layout, bounds, precision, float rounding, and catchable conversion errors.

Checklist

• I have NOT bumped the workspace version or edited CLAUDE.md / CHANGELOG.md (maintainer handles these at merge)
• My commits follow the loose feat: / fix: / docs: / chore: prefix convention used in the log
• I've read CONTRIBUTING.md and agree to the Code of Conduct

Summary by CodeRabbit

• New Features

  • Added native numeric conversion functions for signed, unsigned, and floating-point types.
  • Conversions validate finiteness, integer requirements, ranges, safe-integer limits, and precision; invalid values now produce clear errors.
  • Added explicit f32 rounding to its representable value.

• Documentation

  • Updated API references, type declarations, and native value guidance with conversion behavior and examples.

• Tests

  • Added coverage for boundary values, rounding, invalid inputs, namespace usage, and runtime output.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9374e374-2ff0-48f7-b377-7ea0c4e929bc

📥 Commits

Reviewing files that changed from the base of the PR and between 55dc541 and a6b6731.

📒 Files selected for processing (20)

• changelog.d/8285-native-scalar-conversions.md
• crates/perry-api-manifest/src/entries.rs
• crates/perry-api-manifest/src/entries/part_1.rs
• crates/perry-api-manifest/src/lib.rs
• crates/perry-codegen/src/lower_call/native_table/mod.rs
• crates/perry-codegen/src/lower_call/native_table/native_profile.rs
• crates/perry-codegen/src/runtime_decls/stdlib_ffi/third_party.rs
• crates/perry-hir/src/lower/expr_call/intrinsics.rs
• crates/perry-hir/src/lower/expr_call/intrinsics/native_scalars.rs
• crates/perry-hir/src/lower/expr_call/mod.rs
• crates/perry-hir/tests/native_arena.rs
• crates/perry-runtime/src/lib.rs
• crates/perry-runtime/src/native_value_profile.rs
• crates/perry/src/commands/types.rs
• docs/api/perry.d.ts
• docs/src/api/reference.md
• docs/src/language/native-values.md
• tests/fixtures/native_value_profile.ts
• tests/test_native_value_profile.sh
• types/perry/native/index.d.ts

---

📝 Walkthrough

Walkthrough

Added seven checked perry/native scalar conversion functions. The change updates public manifests and declarations, validates call shapes during lowering, dispatches through native code generation, checks values at runtime, and expands documentation and regression coverage.

Changes

Native scalar conversions

Layer / File(s)	Summary
Public conversion contracts crates/perry-api-manifest/src/entries.rs, crates/perry-api-manifest/src/entries/part_1.rs, crates/perry-api-manifest/src/lib.rs, types/perry/native/index.d.ts, docs/api/perry.d.ts	Defines seven numeric conversion methods and their validation-oriented TypeScript declarations. Manifest tests verify ownership, method shape, and return types.
Call lowering and native dispatch crates/perry-hir/src/lower/expr_call/..., crates/perry-codegen/src/lower_call/native_table/..., crates/perry-codegen/src/runtime_decls/stdlib_ffi/third_party.rs, crates/perry-hir/tests/native_arena.rs	Resolves direct and namespace imports, rejects invalid call shapes, and dispatches valid calls to the runtime conversion functions.
Runtime conversion checks crates/perry-runtime/src/lib.rs, crates/perry-runtime/src/native_value_profile.rs	Adds checked integer and floating-point conversions with type, finiteness, range, safe-integer, precision, signed-zero, and f32 rounding checks.
Examples and regression coverage docs/src/language/native-values.md, tests/fixtures/native_value_profile.ts, tests/test_native_value_profile.sh, crates/perry/src/commands/types.rs, docs/src/api/reference.md, changelog.d/8285-native-scalar-conversions.md	Updates examples, generated output expectations, API coverage checks, reference documentation, and the changelog.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: jdalton, thehypnoo

Sequence Diagram(s)

sequenceDiagram
  participant Source as Source call
  participant HIR as HIR call lowering
  participant Dispatch as Native dispatch table
  participant Runtime as native_value_profile
  Source->>HIR: Call i32, u64, f32, or another native conversion
  HIR->>HIR: Validate callee, arity, spreads, and type arguments
  HIR->>Dispatch: Lower validated native method call
  Dispatch->>Runtime: Invoke exported scalar conversion
  Runtime-->>Source: Return converted number or throw conversion error

Loading

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[proggeramlug]

Merging. Runtime 2571 passed / 0 failed / 4 ignored, codegen 28 suites, 1524 passed, 9 failed — all nine baseline, perry-hir --test native_arena 20/0, cargo fmt clean, bash -n on the new test script clean.

Rejecting values that cannot be represented without changing their meaning is the right contract for a checked-conversion slice — the failure mode a silent as cast produces (a wrapped u32, a f64 that lost precision on the way to f32) is exactly the kind of bug that surfaces far from its cause. Catchable TypeError / RangeError rather than a panic keeps it usable from JS.

One thing I fixed during the merge, and it was not yours. api-docs-drift failed here, but the drift was perf_hooks.default — #8279's manifest entry, merged earlier today without regenerating docs/api/perry.d.ts. Main was drifted, not this branch. I regenerated on main separately, then re-merged here; the docs conflicted (both sides had regenerated) and I resolved by re-running scripts/regen_api_docs.sh, which is deterministic from the manifest and therefore the authoritative resolution. Your own doc updates were correct and complete — the only delta was the entry main owed.

That is the third gate I broke today by merging on a partial check (gc_runtime_root_holders after #8270, -D warnings after #8294, and this). Recording it here because the pattern is mine, not this PR's.