Skip to content

Retain explicit callable argument contracts for runtime boundaries - #58

Open
wolfy-j wants to merge 2 commits into
feature/tick-preemptionfrom
feat/runtime-argument-contracts
Open

wolfy-j wants to merge 2 commits into
feature/tick-preemptionfrom
feat/runtime-argument-contracts

Conversation

@wolfy-j

@wolfy-j wolfy-j commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

Let embedders validate arguments at an external function boundary using explicit Lua parameter declarations. Ordinary VM calls are unchanged. Wippy's Lua function integration in wippyai/runtime#887 calls the new helper; there is no global VM validation switch.

Implementation

  • The canonical checker exports declaration-only signatures separately from inferred module exports. Untyped parameter slots remain any; contextual/inferred signatures do not become runtime contracts.
  • Compilation attaches a resolved contract to the actual callable prototype, including its lexical type aliases. Aliases and reexports therefore retain the implementation's contract.
  • FunctionProto.CheckArguments(state, args) lazily decodes immutable metadata and uses the existing Type:is validator. It checks missing values as nil and typed varargs, returning non-retryable INVALID errors with argument/parameter/field details.
  • Manifest v15 and bytecode v3 preserve the metadata. Older manifest v13/v14 and bytecode v2 remain readable, but previously erased declarations cannot be reconstructed: old bytecode must be rebuilt to gain validation.
  • The module's compile-time source-to-contract index is stripped from runtime TypeInfo; only each callable's own descriptor is retained. No additional global cache.

Semantics and limits

No return validation, coercion, inferred-arity enforcement, or global VM-call changes. Extra ordinary arguments remain allowed. Validation has precisely the existing runtime type semantics: records allow extra fields, arrays/string-keyed maps validate their respective table portions, function types check callable kind and platform types check userdata kind. Generic function parameters are not dynamically instantiated from argument values.

Verification

  • Targeted source/bytecode and metadata-format tests pass under race: optional/missing/untyped/mixed/variadic arguments, same-line functions, aliases, recursive/generic aliases, implicit self, invalid metadata, concurrent initialization, constraints, and v2 compatibility.
  • go vet ./... passes.
  • Differential CI-linter check passes (0 new issues). The installed newer linter flags three pre-existing QF1012 diagnostics in untouched files on a full check.
  • Every subpackage passed the full local regression run, and the root VM suite passes when the fixture corpus is run separately. The combined root run exceeded the default 10-minute timeout while progressing through that corpus; CI uses a 25-minute timeout. The complete Ubuntu CI suite now passes, along with CI lint, fuzz, benchmarks and all six fixture race shards. Windows and the remaining race shard are still running; this is not a claim that all checks are green.

Review stack

This PR is stacked on go-lua #60 and owns both dependency commits previously tested by runtime's temporary integration branch. The composition commit adds no source changes. Runtime #887 pins this reproducible commit and is stacked on runtime #893.

Land #60 before this PR. Updated-head CI is rerunning; prior verification is not a claim that the new CI run is complete. Nothing has been merged or released.

CI corrections

  • Removes a dead matcher ownership assignment immediately before a successful return. Match ownership and runtime limits are unchanged.
  • Runs the manifest-diagnostic equivalence corpus through the existing fixture race shards, rather than duplicating the entire corpus in the other shard. All fixtures, assertions and limits remain covered and unchanged.
  • Exact CI linter (v2.8.0) reports zero issues. Twenty repetitions of the affected FindOne success/ownership/cancellation race regressions pass. A real fixture passes both corpus test roots with the new shard selector.
  • The ten-repeat full matcher stress command exceeded its default ten-minute harness limit. A single full matcher race run with an explicit twenty-minute budget is still running; updated-head CI is rerunning. This PR is not claimed fully green yet.

Current landing review — 2026-10-31

The exact 5908d78c86c80319a4ad42f1db0577a271a94532 head has twelve successful hosted checks, and focused argument-contract tests pass locally under the race detector. This remains a stack on feature/tick-preemption (#60), not a standalone change against main. Rodrigo's recorded approval names fd9105fd69f6f574fb57aa9aa2b9859e1b5f36c5, before the current composed dependency state.

Hold landing until #60 has a qualified current-main integration, then verify this contract-only delta, manifest/bytecode compatibility and consumer integration at the resulting exact head. Runtime #887 remains untouched in this review. No release or Runtime adoption is inferred from the passing stacked-head checks.

The approved fd9105f patch was also isolated directly on current main in an owned worktree: it applies cleanly as a twelve-file contract-only change and its focused race tests pass. That proves mechanical independence of the library code, not approval to reorder the consumer stack. Runtime #887 explicitly integrates on #893, pins the composed library revision, and exercises initializer preemption alongside validation. The original #58 branch/base remain unchanged; the local extraction was not pushed and no Runtime dependency was altered. Preserve the documented landing order until that combined integration is qualified.

@wolfy-j
wolfy-j changed the base branch from main to feature/tick-preemption October 5, 2026 14:39
@wolfy-j
wolfy-j force-pushed the feature/tick-preemption branch from 397cc2b to fa08172 Compare November 10, 2026 03:00
@wolfy-j
wolfy-j force-pushed the feat/runtime-argument-contracts branch from 5908d78 to ffe81d2 Compare November 10, 2026 03:00
@wolfy-j
wolfy-j force-pushed the feat/runtime-argument-contracts branch from ffe81d2 to 7572c35 Compare November 10, 2026 04:07
@wolfy-j

wolfy-j commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto #60 at its new tip (tag archive/runtime-argument-contracts-2026-11-10 holds the previous branch). The merge commit that composed #60 and this change is dropped, as stacking on #60 replaces it; the CI shard commit keeps only race-shard.sh, as its pm.go line is already removed in #60. The full suite passes at the tip, including all 10 argument-contract tests.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants