Authoring Builtins

Runtime builtins should be easy to discover, easy to call from the VM/JIT, and explicit about their semantic contract. A builtin implementation is not complete just because a Rust function exists; it also needs registration metadata, tests, and clear behavior for errors, output counts, GPU values, and unsupported argument forms.

Registration Flow

Loading diagram...

Most runtime builtins live under crates/runmat-runtime/src/builtins/<category>. The category module should re-export its child modules through the existing builtins/mod.rs tree so inventory registration is linked into native and WASM builds.

Macro Contract

Use #[runtime_builtin] for runtime-visible functions. The macro records the MATLAB name, documentation string, optional descriptor, type information, and acceleration tags.

When adding a builtin, provide:

Descriptors

BuiltinDescriptor is the structured API contract for a builtin. It describes signatures, completion policy, output mode, and known errors. This metadata feeds validation and editor features without executing user code.

Good descriptors should include:

• Accepted argument shapes and arity through BuiltinSignatureDescriptor.
• Output behavior through BuiltinOutputMode.
• Stable error identifiers through BuiltinErrorDescriptor.
• Completion policy when the function should or should not appear in suggestions.

Avoid treating descriptors as comments. If an error identifier is listed in metadata, the implementation should raise that identifier on the corresponding failure path.

Integer Capability Audit

Public builtins selected by the integer-capability census must eventually carry exactly one settled disposition. Use integer_capabilities(path) for APIs with integer data, control, class-preserving output, or backend behavior, and describe every distinct call form through BuiltinIntegerCapabilityDescriptor. Use integer_audit(path) only after review proves that the API has no integer surface or is an exact alias of a capability-bearing canonical builtin; an audit disposition must not coexist with positive capability records.

BuiltinIntegerAuditKind::NotApplicable is reserved for APIs whose broad descriptor types represent callbacks, handles, objects, or other nonnumeric values and whose runtime rejects numeric values in those positions. Do not use it merely because an integer form is unsupported: a numeric API that rejects integer input still needs a capability record with a rejected input mask. AliasOf requires an exact semantic alias, not just a recommended replacement or a shared implementation helper.

Run scripts/development/integer-capability-census.sh after changing these records. Its signature screen is a conservative triage population because Any intentionally covers many unrelated value families; the untriaged count is not a defect count or proof that every selected builtin accepts integers.

For cohort work, use scripts/development/integer-capability-audit.sh queue to obtain a deterministic catalog-order worklist, filter it with --name-regex or --input-type, and select 8–25 semantically related names. Run scripts/development/integer-capability-audit.sh packet NAME... before research or implementation; it rejects duplicate, unknown, settled, or out-of-size selections and emits the exact descriptor labels, screened input types, one-based queue/catalog positions, and available reference paths needed for a bounded evidence packet. The legacy census command delegates to the same query definitions, so dashboard and worklist counts cannot drift.

After exporting live descriptors for a completed cohort, use scripts/development/integer-capability-catalog-sync.sh --live LIVE.json --in-place NAME... to replace exactly those 8–25 checked records. The command rejects missing or duplicate names, proves the canonical target records equal the live export, proves every non-target checked record is unchanged, and prints the before/after hashes required by the cohort closure record; use --output instead of --in-place when reviewing the candidate file before replacement.

Runtime Semantics

Builtins receive and return runmat_builtins::Value. Keep MATLAB compatibility at the boundary:

• Preserve scalar versus array behavior.
• Respect requested output count for multi-output functions.
• Return output lists only when the caller expects multiple values.
• Use runtime error builders with stable identifiers for user-facing failures.
• Gather GPU-resident values only when the builtin has no device implementation or must inspect host-only metadata.
• Keep filesystem, networking, and interactive builtins compatible with async suspend/resume where applicable.

For the runtime value families, GC ownership rules, GPU residency, and host metadata helpers, see Runtime Values & Type Model.

GPU and Fusion Metadata

Acceleration metadata should describe real runtime behavior, not a future intent. If a builtin can run on device, document which provider hook or fusion pattern owns that path. If a builtin is host-only but accepts GPU inputs, it should gather explicitly and preserve the expected value semantics.

Use the same fusion categories as the library matrix:

Tests

Every builtin should have focused tests for:

• MATLAB-compatible success cases.
• Scalar, vector, matrix, empty, logical, string, cell, or struct cases relevant to that builtin.
• Error identifiers and invalid arity/type behavior.
• Multi-output behavior when applicable.
• GPU residency and gather/offload behavior when the builtin advertises acceleration.
• WASM-safe behavior for builtins available in browser builds.
• GPU parity with host behavior when the builtin advertises acceleration.

Prefer deterministic tests. For filesystem, networking, and random-number builtins, use temporary resources and explicit seeds.

Documentation Updates

When adding or changing a builtin:

1. Update crates/runmat-runtime/LIBRARY.md.
2. Update the table in Builtins if the docs are not generated from that file.
3. Add or update descriptor metadata if user-facing signatures changed.
4. Link implementation-specific behavior to the relevant runtime section instead of duplicating internals here.