RFC: Stabilize a Perry native value profile for fixed-width scalars, POD records, and native boundaries

[rink3y]

The problem

Perry already has two strong halves of a native-value story, but they are not
yet one stable user-facing contract.

On the application side, Perry intentionally accepts ordinary TypeScript:
number, objects, arrays, interfaces, classes, npm modules, and Node-compatible
APIs. That compatibility should remain the default.

On the compiler and native-library side, Perry already models explicit native
representations:

• the native-representation pipeline has I32, I64, U32, U64, USize,
  F32, F64, BufferLen, native handles, POD records, and verified
  materialization boundaries;
• the native-library manifest accepts typed ABI descriptors and C-layout POD
  records;
• generated declarations currently expose internal-looking types such as
  PerryI32, PerryU64, PerryF32, and PerryPod<T>;
• NativeArena, typed views, sizeof<T>(), alignof<T>(), and
  offsetof<T>() already exist; and
• Typed Native Specialization Pipeline: explicit native reps and verifiable native regions #1849 has landed most of the compiler foundation for explicit native
  representations and verifier-backed native regions.

The missing piece is a documented source-level contract that an application or
library author can intentionally use.

Today, a developer can see that Perry internally understands exact widths and
POD layouts, but there is no stable answer to questions such as:

1. How do I declare that a value is a u16, i32, u64, or f32, rather
   than an ordinary JavaScript number?
2. Which conversions are checked, lossy, wrapping, or rejected?
3. Can an exact-width value remain native across local variables, calls,
   arrays, records, WebAssembly, and native-library boundaries?
4. How do I define one C-layout record in TypeScript and have Perry verify the
   same layout against a native-library manifest?
5. What happens when i64 or u64 crosses a JavaScript-compatible boundary
   where a number cannot represent it exactly?
6. Which parts are stable language/API guarantees and which parts are compiler
   optimizations that may safely fall back to boxed JavaScript values?

Without that contract, native packages either duplicate representation
information in a manifest, pass data through generic number/object values, or
drop down to typed arrays and manual offsets. The compiler can optimize some of
those cases, but the author cannot state and rely on an exact native contract.

A concrete example I would like Perry to support is:

import {
  type u16,
  type pod,
  u32,
  u64,
  f32,
  sizeof,
  alignof,
  offsetof,
} from "perry/native";

type PacketHeader = pod<{
  version: u16;
  flags: u16;
  payloadLength: u32;
  sequence: u64;
  gain: f32;
}>;

const header: PacketHeader = {
  version: 1,
  flags: 0,
  payloadLength: u32(payload.length),
  sequence: u64(sequence),
  gain: f32(0.5),
};

console.log(sizeof<PacketHeader>());
console.log(alignof<PacketHeader>());
console.log(offsetof<PacketHeader>("payloadLength"));

The goal is not to make ordinary Perry code look like systems code. The goal is
to let TypeScript code become explicit at the small number of boundaries where
width, range, layout, ABI, or measured performance is part of correctness.

Proposed solution

Stabilize an opt-in Perry native-value profile exposed through a normal,
valid TypeScript module such as perry/native.

This should build on the native representation and ABI work Perry already has,
not introduce a separate parser, file extension, or second compiler pipeline.
Ordinary .ts/.tsx code and ordinary number semantics remain unchanged.

1. Public native scalar types

Expose stable public names for:

Type	Contract
i8, i16, i32, i64	exact-width signed integers
u8, u16, u32, u64	exact-width unsigned integers
isize, usize	target pointer-sized signed/unsigned integers
f32, f64	IEEE-754 32-bit/64-bit floating-point values
byte	alias for u8
number	unchanged JavaScript-compatible numeric type

The existing PerryI32, PerryU64, PerryF32, etc. could remain as
compatibility aliases or internal generated names, while perry/native
provides the supported author-facing surface.

Numeric literals may use contextual typing when they are compile-time
representable:

import { type u16, type i32, type f32 } from "perry/native";

const port: u16 = 8080;
const offset: i32 = -120;
const ratio: f32 = 0.5;

Conversions from a dynamic or wider value should be explicit and checked:

import { i32, u32, f32 } from "perry/native";

const count = u32(input);
const delta = i32(otherValue);
const ratio = f32(computation);

The important part is that the conversion behavior is specified. A checked
conversion should not silently wrap, truncate, or lose precision. Explicit
wrapping/truncating/saturating operations can be separate APIs if Perry wants
to support them.

2. A stable POD/native-record contract

Promote the existing PerryPod<T> concept to a documented public form such as
pod<T>.

For the first stable version, keep POD deliberately narrow and verifier-friendly:

• ordered fields;
• fixed-width scalar fields;
• nested POD records;
• fixed-size byte/numeric storage if and when Perry has a stable spelling for
  it;
• pointer-free handle IDs where explicitly supported; and
• no managed string, normal Array<T>, class instance, closure, promise,
  map, set, or arbitrary object fields.

sizeof<T>(), alignof<T>(), and offsetof<T>() should be compile-time
intrinsics for valid POD types. Field order, alignment, padding, and target
dependence must be documented.

POD layout should not silently imply endianness. Binary readers/writers should
continue to state byte order explicitly.

3. One representation contract across source, manifests, and codegen

A TypeScript POD declaration and a perry.nativeLibrary descriptor should be
cross-checked rather than allowed to drift independently.

For example, either:

• the manifest references an exported TypeScript POD type; or
• Perry generates a canonical layout descriptor from the TypeScript type and
  compares it with the manifest/native declaration during
  perry native validate.

A disagreement in width, signedness, field order, offset, size, alignment,
ownership, or return type should be a compile-time error with both sides shown.

This would also provide a common type vocabulary for:

• statically linked perry.nativeLibrary packages;
• the C-ABI work in runtime: C-ABI FFI layer (bun:ffi shape) — dlopen, typed calls, pinned buffers, toArrayBuffer, JSCallback #6562;
• WebAssembly imports/exports;
• generated bindings; and
• Perry-owned native APIs.

4. Explicit dynamic-boundary materialization

Native values should remain in their exact representation while Perry can prove
that representation, then materialize only at a real dynamic boundary.

The materialization rules should be part of the contract:

• i8 through u32, f32, and f64 can convert to a JavaScript number
  without changing their mathematical value (subject to the normal f32
  rounding already having occurred);
• i64 and u64 must not silently become an imprecise number;
• crossing an untyped/dynamic boundary with i64/u64 should either use
  bigint, require an explicit checked conversion, or produce a compile-time
  diagnostic; and
• a POD record should materialize to an ordinary object only through an
  explicit or compiler-recorded boundary, preserving Perry's existing
  verifier/artifact model.

This is where the public feature should reuse #1849 rather than bypass it:
native representations, guards, fallback paths, and materialization reasons
remain auditable.

5. Preserve Perry's TypeScript compatibility by default

This proposal is opt-in.

const value = 10; // still an ordinary TypeScript number

It does not reinterpret every integer-looking literal as an integer, does not
change operators for ordinary number, and does not require systems-level
annotations in normal application code.

The module spelling is also intentional: perry/native makes the non-portable
contract visible while keeping the source valid TypeScript and friendly to
existing editors, formatters, and TypeScript tooling.

Alternatives considered

Keep native representations entirely inferred

Perry should continue to infer and specialize ordinary TypeScript. That is a
major strength, and #1849 is the right foundation for it.

Inference alone is not enough when representation is externally observable:
C ABI calls, binary layouts, persistent formats, WebAssembly signatures,
hardware-facing buffers, and 64-bit integer precision need an author-declared
contract. An optimization may safely fall back; an ABI cannot silently do so.

Use typed arrays and DataView for everything

Typed arrays and DataView are good byte-storage APIs and should remain
supported. They become cumbersome for nested records and require authors to
repeat offsets, sizes, signedness, and alignment manually. They also do not
provide a function/manifest ABI contract by themselves.

Put all type information only in package.json

The native-library manifest already carries useful ABI information, but keeping
it only there duplicates types and prevents normal TypeScript code from
expressing the same contract. The source and manifest should be linked and
validated, not maintained as unrelated schemas.

Add new keywords such as struct, unsafe, or a new source extension now

That would make Perry-specific code clearer in some cases, but it would also
require parser, formatter, editor, language-server, and syntax-highlighting
work before the semantic contract is settled.

The existing branded types, POD analysis, native ABI descriptors, and arena
intrinsics show that Perry can establish the contract using valid TypeScript
first. New syntax can be reconsidered later if the library/type form proves
insufficient.

Treat TypeScript annotations as unconditional runtime truth

This would conflict with the safety model described in #1849. Normal TypeScript
annotations should remain erasable hints. Native types become runtime-relevant
only because the author explicitly opts into the perry/native contract, and
the compiler must still verify conversions, layouts, lifetimes, and boundary
transitions.

Scope

• Small — CLI flag, new stdlib function, doc page
• Medium — new widget, new code-gen pass, new perry.toml field
• Large — new platform target, new backend, cross-cutting compiler change

This is large as a complete feature, but it can land in independently useful
slices:

1. stabilize names, documentation, conversions, and diagnostics for the native
   scalar types Perry already models;
2. stabilize and document pod<T>, layout intrinsics, and NativeArena;
3. validate TypeScript POD/scalar declarations against native-library
   manifests;
4. extend exact-width coverage (i8/i16/u8/u16/isize) and cross-target
   behavior; and
5. broaden typed function/collection paths only where verifier-backed
   correctness and measurable benefit justify them.

I would be happy for maintainers to split this RFC into a tracker plus
implementer-sized issues.

Additional context

This proposal is intended as a public-contract layer over work Perry already
contains:

• Perry's native-representation documentation
• Typed Native Specialization Pipeline tracker (#1849)
• Current native-library manifest ABI
• Current generated PerryI32 / PerryPod<T> / NativeArena declarations
• C-ABI FFI tracker (#6562)

I do not intend this to duplicate either tracker. #1849 is primarily the
compiler's specialization, proof, fallback, and materialization foundation.
#6562 is runtime dynamic C-ABI loading and callbacks. This RFC asks for the
stable TypeScript-facing type, conversion, layout, and boundary contract that
can sit above both.

Relevant prior art:

• Bun exposes exact-width scalar and pointer descriptors at its FFI boundary:
  https://bun.sh/docs/api/ffi
• WebAssembly has explicit i32, i64, f32, and f64 value types:
  https://webassembly.github.io/spec/core/syntax/types.html
• Rust makes C-compatible layout an explicit representation contract rather
  than an inference:
  https://doc.rust-lang.org/reference/type-layout.html#the-c-representation

The requested Perry-specific outcome is:

Keep ordinary TypeScript ordinary, but provide one stable way to state exact native width, layout, and boundary behavior when those properties are part of correctness.

[rink3y]

One clarification after posting the RFC: I do not think the native profile should stop at scalar aliases and record layouts. The common thread is a coherent native execution model: values with exact representation, resources with real ownership, and temporary access that the compiler can prove safe.

Arithmetic should look like arithmetic

An i32 or u32 should use the operators TypeScript developers already know:

function area(width: u32, height: u32): u32 {
  return width * height;
}

function advance(position: i32, velocity: i32): i32 {
  return position + velocity;
}

let pending: usize = queue.length;
pending -= 1;

There should not be a second arithmetic interface made from one method per operator and overflow mode. If the type is exact-width, the compiler already knows which operation it is lowering.

For the initial contract, I suggest:

• same-type arithmetic stays in that type;
• integer overflow is checked in every build mode;
• integer division truncates toward zero;
• division by zero and invalid shifts are errors;
• f32 rounds as f32 after each operation;
• f64 has normal IEEE-754 double semantics; and
• ordinary number expressions remain unchanged.

That makes this predictable:

const next: u32 = current + 1;

but rejects an implicit width change:

const small: u16 = 10;
const large: u32 = 20;

const total = small + large;
// error: arithmetic mixes u16 and u32

const valid: u32 = u32(small) + large;

I would leave wrapping and saturating arithmetic out of the first version rather than commit Perry to one method per operator. If real crypto, codec, or DSP workloads later need another overflow policy, it should be designed for an expression or lexical region while preserving a + b as the arithmetic spelling.

Conversions are where explicit syntax belongs:

const index: u32 = u32(input);
const temperature: f32 = f32(reading);
const sequence: u64 = u64(bigintValue);

Those conversions should reject fractional integer inputs, negative values for unsigned types, out-of-range values, NaN, infinity, and silent precision loss. Constant failures should be compiler diagnostics.

The i64/u64 case also needs a hard rule. A value may stay in a native 64-bit lane, but it must not quietly become an imprecise JavaScript number when it crosses into an untyped object, dynamic call, JSON, or a web host. Perry should materialize it as bigint, require an explicit checked conversion, or reject that crossing.

Since the native model needs more than numbers

The useful split is:

1. managed values;
2. native copy values;
3. owned resources; and
4. borrows.

Managed values remain the default

Normal objects, arrays, strings, classes, and closures keep the TypeScript
model:

const user = { name: "Ada" };
const jobs: Job[] = [];

Assignment preserves reference identity, closures can capture the values, and Perry's GC owns their lifetime. A borrow checker should not be imposed on ordinary application objects.

Native scalars and POD records are values

Exact scalars copy by value. A standalone pod<T> should do the same:

type Point = pod<{
  x: f32;
  y: f32;
}>;

const original: Point = { x: 10, y: 20 };
const copy = original;
copy.x = 30;

console.log(original.x); // 10

That behavior must be explicit because it differs from an ordinary object. It is also what makes a native record useful as more than a layout annotation.

An arena-backed PodView<T> is different: it is a view into owned storage, so writing through it updates that storage. Perry should distinguish a standalone POD value from a borrowed POD view rather than letting optimization decide the observable semantics.

Native resources have ownership

Files, sockets, database connections, GPU allocations, external buffers, OS handles, and FFI objects with finalizers are not copy values. They have one owner and can be transferred:

function submit(buffer: owned<NativeBuffer>): void;

const buffer = NativeBuffer.alloc(4096);
submit(buffer);

console.log(buffer.byteLength);
// error because 'buffer' was moved by submit(buffer)

The call should remain ordinary. Perry can infer the move from the callee's interface; requiring move(buffer) at every transfer would only expose compiler bookkeeping.

Owned resources should integrate with TypeScript's existing cleanup syntax:

using file = File.open(path);
const data = file.readAll();

await using transaction = await database.begin();
await transaction.commit();

Cleanup must run on return, throw, and cancellation. If cleanup itself can fail, the resource should expose an explicit close() or commit() result instead of hiding the failure in finalization.

Borrowing should be explicit at interfaces, inferred locally

Use ref<T> for shared read-only access and mut<T> for exclusive mutable
access:

function hash(data: ref<Uint8Array>): u64;
function receive(
  socket: mut<Socket>,
  into: mut<Uint8Array>,
): usize;

const digest = hash(bytes);
receive(socket, bytes);

The useful rules are small:

• any number of shared borrows, or one mutable borrow;
• an owner cannot be moved or disposed while borrowed;
• a borrow cannot outlive its owner;
• overlapping mutable aliases are rejected;
• a borrow cannot escape into longer-lived storage unless that lifetime is proven; and
• a temporary borrow cannot cross await or a thread transfer.

Perry should infer short local borrows from use. ref<T> and mut<T> earn their keep in exported functions, native declarations, stored callbacks, async work, and other escape points. Requiring them on every local variable would turn useful safety into ceremony.

For a synchronous FFI call, passing a typed array can create a borrow for the duration of the call. Perry then keeps the backing memory stable by pinning it or using non-moving storage. An asynchronous native operation cannot retain that temporary borrow: it must take ownership, receive a pinned owned buffer, or copy the input. The function's interface should make that choice visible.

The same ownership information should control thread transfer. An owned native resource crosses threads only if its type is declared transferable; a shared borrow crosses only when concurrent reads are safe; mut<T> remains exclusive. Perry already carries ownership and thread-affinity metadata for native handles, so this should deepen that existing model rather than introduce a parallel one.

Raw pointers can come later

The scalar, POD, arena, ownership, and borrow model is useful without exposing general pointer dereference.

When Perry eventually adds ptr<T>, operations that can violate layout, aliasing, or lifetime rules should require a small, visible unsafe scope. Library authors can use that scope to build safe wrappers; callers should not inherit the unsafe contract. I would keep raw pointers and the exact unsafe syntax as a later RFC so they do not block the safe native layer.

So ordinary Perry code remains ordinary TypeScript. These rules become relevant only when a developer opts into a native contract because width, layout, lifetime, or ABI behavior is part of correctness.