[mattcce]

Introduction

Native methods in Java provide FFI functionality to call foreign functions. Native methods are especially useful in the CSE machine to implement primitive functions, and in some cases, are the only real way to do so.

Motivation

The motivation for implementing native methods initially stemmed from Object.hashCode, which itself is a native method.

Native methods have clear uses for some other cases as well, like with displaying or printing to standard output. Other specific uses for native methods are presently unclear, but having the ability to break out of the CSEC machine is certainly not a detriment.

Implementation

Notation note: we refer generally to a Java syntactic native method by the term native method, and the foreign function that is eventually called when the native method is invoked by the term foreign function.

CSEC Handling

Two control items (labelled C1, C2) have been modified to allow for native methods to be properly handled.

(C1) Method Declarations (AST Node MethodDeclaration) will now dynamically link a foreign function to a native method declaration. Closures (the Closure type) now distinguishes between three types of declarations (previously two), with the newest being NativeDeclaration.

Constructors cannot be native in Java. NativeDeclarations mirror the MethodDeclaration type, except it does not have a method body but instead hold a pointer to the resolved foreign function.

Implementation note: even though MethodDeclaration and ConstructorDeclaration, both of which are contained within the Closure type, are defined in the AST (in ast/types/classes.ts), we instead choose to define NativeDeclaration in ec-evaluator/types.ts instead, to localise these changes.

(C2) Invocations (Instruction invoke) will now distinguish the new Closure type, and handle it specially. In particular, retains most of the usual functionality, and will appropriately initialise a new environment frame for the function to be executed (see native method architecture below), and push a return instruction before directly calling the foreign function with the full CSEC machine state.

Native Method Architecture

We offer full and complete power to native methods, passing in the entire control, stash, and environment to foreign functions they call. This matches the power that foreign functions are expected to have.

The CSEC machine still handles argument resolution and returning. This is because FFI calls should function like normal functions to the CSEC machine, except that it ignores whatever happens while the foreign function is running. To this end, common foreign functions are expected to:

• collect/find its arguments from the environment supplied to it, if any,
• push a result of the valid type onto the top of the stash.

Note that the foreign function, using common utility methods that the rest of the CSEC machine uses, will have to appropriately deserialise and serialise the values. In particular, it must be able to destructure AST nodes that it expects and reconstruct valid AST nodes that the CSEC machine expects.

Because the full control, stash, and environment is passed to the foreign function, this allows foreign functions to effectively do anything to the CSEC machine state. However, foreign functions are generally not permitted to expect anything except its arguments being defined in the current environment.

The dictionary used uses fully-qualified method descriptors to identify the correct foreign function. These are of the form:

class::identifier ( p1Type p1Identifier, … ): returnType

Note that foreign functions always have the same type:

({ control, stash, environment }: { control: Control; stash: Stash; environment: Environment }) => void

In particular, foreign functions always return nothing. Their results are to be injected directly into the stash that is provided, for use by the CSEC machine (and the program it is currently running).

The identifier is included in such a symbolic reference for the express purpose of making foreign functions easier to implement. Because foreign functions must retrieve their arguments from the environment, their implementations must be aware of the correct parameter identifiers.

---

Notes:

• This PR supercedes Native methods for CSEC machine #74

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	70.96% (+0.34% 🔼)	8264/11646
🔴	Branches	59.27% (+0.29% 🔼)	2756/4650
🟡	Functions	69.22% (+0.27% 🔼)	1466/2118
🟡	Lines	71.86% (+0.34% 🔼)	7775/10819

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / natives.ts	100%	100%	100%	100%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🔴	... / errors.ts	42.03% (-1.05% 🔻)	27.27%	14.71% (-0.92% 🔻)	43.94% (-1.22% 🔻)
🟢	... / interpreter.ts	98.76% (-0.28% 🔻)	91.03% (-0.87% 🔻)	98.15%	98.67% (-0.3% 🔻)

Test suite run success

1202 tests passing in 71 suites.

Report generated by 🧪jest coverage report action from 3b3abbb

[hj235]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-14T15:02:04.647199Z	3b3abbb	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 86a2b1d164

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[hj235]

Rebased onto main (65e71e4): mattcce's four commits are kept as-is; the two Merge branch 'main' commits are dropped; one import-list conflict in src/types/checker/index.ts is resolved by keeping both imports; and yarn.lock takes main's version (this PR doesn't touch package.json, so its lockfile churn was incidental).

On top of that, one commit addressing the Codex review: removes the stray console.log from the type checker, and gives enum methods the same native/bodyless handling as class methods. Previously a native method in an enum crashed typeCheck. Tests added for both. Diff against main is now 10 files, +215/−4.

Build is clean and the full suite passes (1199 passed, 6 skipped), including natives.test.ts. Verified by running: value-returning and static natives work, an unregistered native fails at call time with UndefinedNativeMethod, and natives are type checked by their header.

What this adds

• src/ec-evaluator/natives.ts: the NativeFunction type and an (empty) registry keyed by descriptor, e.g. 'get(): int'. A native gets the control, stash and environment, and pushes its result onto the stash.
• interpreter.ts: on invoke, after the arguments are bound, a native method dispatches to the registry, then a return instruction is pushed in place of a body. cmdEvaluators is also newly exported.
• utils.ts: isNative() and getFullyQualifiedDescriptor(). errors.ts: UndefinedNativeMethod.
• Type checker: a ; method body now parses (previously "unsupported Java specification"); native methods skip body checking; any other bodiless method gets the new MissingMethodBodyError.

Not addressed here, deliberately:

• The registry key omits the declaring class, so same-named natives on different classes collide (Codex P1). CSEC: Precompiled classes #79 already qualifies the key ('Object::hashCode(): int'), and CSEC: Precompiled classes #79's commits rewrite these same files, so fixing it here would only create conflicts when CSEC: Precompiled classes #79 is rebased onto this. The collision can't occur yet: the registry is empty.
• A native method with a body is accepted without checking the body. CSEC: Precompiled classes #79 adds NativeMethodHasBodyError.
• abstract methods are reported as "missing method body" (Codex P2). Abstract methods were already rejected before this PR, and neither the type checker nor the ECE supports abstract classes yet, so exempting them here would let programs pass type checking and then fail at runtime. That belongs with abstract-class support.

[hj235]

@codex review
Please re-check the issues raised in the previous Codex review and verify that the suggested fixes are complete. Also review the new diff for regressions.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1734ed5818

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[hj235]

@codex review
Please re-check the issues raised in the previous Codex review and verify that the suggested fixes are complete. Also review the new diff for regressions.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 3b3abbbd38

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[martin-henz]

LGTM