natives: design record for IR bodies of `native fn` and `native { }` (step 1 of #53)

orion commented

2026-10-23 03:20:26 +00:00

Collaborator

Context

Step 1 of #53 (natives: native fn bodies as IR and native { } blocks; ROADMAP "The kernel of natives", CONCEPT "Foreign Functions"). CONCEPT plans that the body of a native fn is IR and native { ... } a block of IR inside an ordinary function, but no design record fixes the concrete surface: what the IR looks like as source, what the checker accepts, how it is lowered. That has to be decided in writing before the parser, checker or lowering is touched. This step is documentation only.

Goal

A design record docs/design/NATIVE-BODIES.md that specifies the syntax, the checker rules and the lowering of IR bodies, and cuts the implementation into slices.

Acceptance criteria

docs/design/NATIVE-BODIES.md exists with pdisc frontmatter, a status line ("designed, not built") and an entry in docs/design/index.md.
The source form is specified with a grammar and at least one worked example each for native fn add(other: Int64): Int64 { ... } (a kernel operation such as Int64.add) and a native { ... } block inside an ordinary function: how an intrinsic and its numeric kind are written (aligned with the IR text of BACKEND 1.7 and the Intrinsic/IntrinsicOperation names), how parameters, self and the result are named inside the body, how ownership and the checked-versus-unchecked variants are spelled.
The checker rules are numbered: where native bodies and blocks are allowed (std/ only, as CONCEPT says until the IR format is versioned), what is verified at the site (IR verifier: form, slot types, ownership; not meaning), the error text for each refusal, and how a bodiless native fn (the platform edge: files, clock, processes) stays unchanged.
The lowering is specified for both back ends (C and VM): the body is lowered through the same Intrinsic path as today's manifest wrapper; a back end that lacks an intrinsic reports a clean compile error (BACKEND gap 22); the manifest (natives.trb) entries that the bodies replace are named, with the migration order owed to the audit table of #52 (docs/design/NATIVES.md, #407, if already landed; otherwise the manifest itself).
The record states the seed impact of each later slice under the two-commit rule (new syntax: teach both forms, refresh the seed, then migrate std/), and lists the slices: (1) syntax and parser with a gate test, (2) checker rules, (3) lowering in the VM and C back end, (4) std migrates its arithmetic (Int64.add and the other kernel rows). Each slice fits one PR of one or two Conventional Commits.
Open design questions of the record are decided by the record (technical choices, per the loop contract); a question is left open only if it is one of the owner categories (public commitment, cost, product direction, breaking change of a published contract).
CONCEPT "Foreign Functions" and ROADMAP "The kernel of natives" link the record; docs/ regenerates skills/ as CLAUDE.md requires; gates green in both tiers.

Design record point

CONCEPT "Foreign Functions (Draft)" (planned: the body of a native fn is IR); ROADMAP "The kernel of natives"; BACKEND 1.7 (IR text), 3.7 (the manifest) and gap 22 (missing intrinsic is a compile error).

Seed impact

None for this step (documentation only). The later slices change syntax and add a name the compiler parses, so they fall under the two-commit rule; the seed refresh itself stays Torben's.

Size

One PR, one Conventional Commit (docs(natives): design record for IR bodies of native fn).

Dependencies

None hard. It should read the kernel list from docs/design/NATIVES.md once #407 (PR #409) has landed. Blocks the implementation slices of #53; part of #52.

## Context Step 1 of #53 (natives: `native fn` bodies as IR and `native { }` blocks; ROADMAP "The kernel of natives", CONCEPT "Foreign Functions"). CONCEPT plans that the body of a `native fn` is IR and `native { ... }` a block of IR inside an ordinary function, but no design record fixes the concrete surface: what the IR looks like as source, what the checker accepts, how it is lowered. That has to be decided in writing before the parser, checker or lowering is touched. This step is documentation only. ## Goal A design record `docs/design/NATIVE-BODIES.md` that specifies the syntax, the checker rules and the lowering of IR bodies, and cuts the implementation into slices. ## Acceptance criteria - [ ] `docs/design/NATIVE-BODIES.md` exists with pdisc frontmatter, a status line ("designed, not built") and an entry in `docs/design/index.md`. - [ ] The source form is specified with a grammar and at least one worked example each for `native fn add(other: Int64): Int64 { ... }` (a kernel operation such as `Int64.add`) and a `native { ... }` block inside an ordinary function: how an intrinsic and its numeric kind are written (aligned with the IR text of BACKEND 1.7 and the `Intrinsic`/`IntrinsicOperation` names), how parameters, `self` and the result are named inside the body, how ownership and the checked-versus-unchecked variants are spelled. - [ ] The checker rules are numbered: where `native` bodies and blocks are allowed (`std/` only, as CONCEPT says until the IR format is versioned), what is verified at the site (IR verifier: form, slot types, ownership; not meaning), the error text for each refusal, and how a bodiless `native fn` (the platform edge: files, clock, processes) stays unchanged. - [ ] The lowering is specified for both back ends (C and VM): the body is lowered through the same `Intrinsic` path as today's manifest wrapper; a back end that lacks an intrinsic reports a clean compile error (BACKEND gap 22); the manifest (`natives.trb`) entries that the bodies replace are named, with the migration order owed to the audit table of #52 (`docs/design/NATIVES.md`, #407, if already landed; otherwise the manifest itself). - [ ] The record states the seed impact of each later slice under the two-commit rule (new syntax: teach both forms, refresh the seed, then migrate `std/`), and lists the slices: (1) syntax and parser with a gate test, (2) checker rules, (3) lowering in the VM and C back end, (4) `std` migrates its arithmetic (`Int64.add` and the other kernel rows). Each slice fits one PR of one or two Conventional Commits. - [ ] Open design questions of the record are decided by the record (technical choices, per the loop contract); a question is left open only if it is one of the owner categories (public commitment, cost, product direction, breaking change of a published contract). - [ ] CONCEPT "Foreign Functions" and ROADMAP "The kernel of natives" link the record; `docs/` regenerates `skills/` as `CLAUDE.md` requires; gates green in both tiers. ## Design record point CONCEPT "Foreign Functions (Draft)" (planned: the body of a `native fn` is IR); ROADMAP "The kernel of natives"; BACKEND 1.7 (IR text), 3.7 (the manifest) and gap 22 (missing intrinsic is a compile error). ## Seed impact None for this step (documentation only). The later slices change syntax and add a name the compiler parses, so they fall under the two-commit rule; the seed refresh itself stays Torben's. ## Size One PR, one Conventional Commit (`docs(natives): design record for IR bodies of native fn`). ## Dependencies None hard. It should read the kernel list from `docs/design/NATIVES.md` once #407 (PR #409) has landed. Blocks the implementation slices of #53; part of #52.

orion added the

loop

ready

labels

2026-10-23 03:20:26 +00:00

orion referenced this issue

2026-10-23 03:20:26 +00:00

natives: native fn bodies as IR and native { } blocks #53

orion referenced this issue

2026-10-23 03:20:26 +00:00

natives: native fn bodies as IR and native { } blocks #53

orion commented

2026-10-23 03:39:20 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261023 until 2026-10-23T09:39:20Z

orion referenced this issue from a pull request that will close it,

2026-10-23 03:43:13 +00:00

docs(natives): design record for IR bodies of native fn #412

orion commented

2026-10-23 04:14:31 +00:00

Author

Collaborator

[loop:torbscript] implement: design record docs/design/NATIVE-BODIES.md written (grammar and examples for native fn and native { }, intrinsic typing table, checker rules N1-N10 with error texts, lowering through the existing Intrinsic path in C and the VM, manifest rows replaced, four slices with seed impact, technical questions decided in section 9, none left for the owner); linked from CONCEPT, ROADMAP and docs/design/index.md. PR #412 (Closes #410), commit-message check clean locally. Forge CI has not started: all four checks of the PR sit pending for 30+ min because the runners are backlogged (runs 1355-1360 and others are waiting), no result yet. Deviation: design records here are plain Markdown named in the documents list of the index, so the record has no front matter; the pdisc check of the PR will say if that is wrong. Not run locally: torb format --check (no .trb touched, no torb binary in the sandbox). Tokens: roughly 130k.
next: waiting (forge CI queued on 3 runners backlog, then review by argus)

[loop:torbscript] implement: design record `docs/design/NATIVE-BODIES.md` written (grammar and examples for `native fn` and `native { }`, intrinsic typing table, checker rules N1-N10 with error texts, lowering through the existing `Intrinsic` path in C and the VM, manifest rows replaced, four slices with seed impact, technical questions decided in section 9, none left for the owner); linked from CONCEPT, ROADMAP and `docs/design/index.md`. PR https://git.torb.dev/torbscript/language/pulls/412 (`Closes #410`), commit-message check clean locally. Forge CI has not started: all four checks of the PR sit `pending` for 30+ min because the runners are backlogged (runs 1355-1360 and others are `waiting`), no result yet. Deviation: design records here are plain Markdown named in the `documents` list of the index, so the record has no front matter; the `pdisc` check of the PR will say if that is wrong. Not run locally: `torb format --check` (no `.trb` touched, no torb binary in the sandbox). Tokens: roughly 130k. next: waiting (forge CI queued on 3 runners backlog, then review by argus)

orion referenced this issue

2026-10-23 04:17:49 +00:00

collections: design record for ArrayList, the hash tables and the tries on Buffer (step 1 of #55) #413

orion commented

2026-10-23 04:27:43 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261023 until 2026-10-23T10:27:00Z

orion commented

2026-10-23 04:42:23 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #412 (#412) pdisc fixed on head 8a40ca84: CONCEPT.md was stale after the link to docs/design/NATIVE-BODIES.md, restamped with pdisc.py stamp; locally pdisc.py check and the index are ok; the PR is mergeable without a rebase, no merge commit. next: waiting (forge CI runners are queued; pdisc, commit messages and gates on the new head are still pending, no failure) - then the merge gate (argus) reviews.

[loop:torbscript] implement: PR #412 (https://git.torb.dev/torbscript/language/pulls/412) pdisc fixed on head 8a40ca84: CONCEPT.md was stale after the link to docs/design/NATIVE-BODIES.md, restamped with pdisc.py stamp; locally `pdisc.py check` and the index are ok; the PR is mergeable without a rebase, no merge commit. next: waiting (forge CI runners are queued; pdisc, commit messages and gates on the new head are still pending, no failure) - then the merge gate (argus) reviews.