Skip to content

Validate declared Lua function arguments automatically at the handler boundary - #887

Open
wolfy-j wants to merge 6 commits into
feature/lua-tick-preemptionfrom
feat/lua-function-arguments
Open

wolfy-j wants to merge 6 commits into
feature/lua-tick-preemptionfrom
feat/lua-function-arguments

Conversation

@wolfy-j

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

Copy link
Copy Markdown
Contributor

Purpose

Automatically validate explicitly annotated parameters when the functions subsystem invokes a Lua handler. No entry field or application configuration is required, and static diagnostics can remain disabled.

local function run(id: string, limit: integer?)
    -- Invalid external arguments are rejected before this body runs.
end
return {run = run}

Calling this handler with an integer id produces a non-retryable INVALID error. Missing required arguments fail, optional parameters accept nil, and untyped parameters stay unchecked. Typed varargs validate each extra value; ordinary extra arguments retain Lua semantics.

Implementation

  • All four Lua function pool types enable the same engine-boundary policy. The actual selected callable owns its declaration contract; the generic function registry stays Lua-agnostic.
  • The engine transcodes annotated-call arguments without swallowing conversion failures, validates the selected handler before its body, and propagates errors through the existing API error/result path. Untyped calls retain their previous conversion behavior.
  • The code manager resolves explicit type syntax using its existing canonical checker even when static diagnostics are disabled. It reuses compile/typecheck caches; a warm compiled-cache hit needs no parse or analysis.
  • Contracts survive new packed bytecode and cached artifacts. Hot reload keeps old code paired with its old signature while a replacement pool uses the new one.
  • Pins the companion go-lua commit without a local replace, from runtime's current v1.6.2 dependency onto the current main lineage plus the declaration-contract changes.

Scope and limits

Lua function handlers only. Ordinary Lua calls, process startup, workflows, WASM handlers, and return values are unchanged. Module initialization may run before validation; the rejected handler body does not.

Validation follows existing Type:is semantics, not JSON schema: no coercion; records allow extra fields; arrays/string-keyed maps check their respective table portions. Callable/opaque platform types check runtime kinds rather than callback signatures/userdata identity. Generic function parameters are not dynamically instantiated from argument values. Old bytecode without declaration metadata must be rebuilt.

Typed source requires declaration analysis on a cold compile even when diagnostics are off. There is no new per-call analysis, second resolver, or unbounded contract cache.

Verification

  • Full race suites pass for Lua code/cache/lint, engine, function manager, and all scheduler pools.
  • Targeted regression checks pass for all pool types, hot reload, source/bytecode, cache restart, imported types, method-body non-execution, reusable pools after rejection, optional conversion failures, and unchanged untyped-call conversion.
  • Vet passes for all changed runtime packages.
  • Full repository lint passes (0 issues) with the local integration workspace. Targeted boundary and full code-manager/function-pool race suites also pass independently with GOWORK=off against the pushed/pinned dependency. All CI checks now pass on the pinned dependency.

Depends on wippyai/go-lua#58. Neither PR authorizes a release or merge.

Review stack and dependency

This PR is stacked on runtime #893 (CPU-bound actor preemption). Land #893 first; this PR adds handler argument validation and the compatibility corrections on top.

  • Compatibility corrections are part of this PR, not a separate integration branch.
  • The selected handler is validated before its body, after scheduled initialization. Fresh calls retain conversion failures until the callable is known; cached handlers retain direct validation. Process/untyped calls preserve legacy conversion.
  • Regression coverage includes source/dumped bytecode, fresh/cached calls, required/optional/variadic arguments, method selection, initializer preemption, pool reuse, and conversion error kind/retryability/index/cause.
  • Pins go-lua add _env for standard db configuration #58, stacked on EE2-1740 fix ws_demo app, security issues #60, at v1.6.4-0.20261005132556-8e0ac4f7baf7; no local replacement or workspace dependency.
  • Combined actor, Lua engine/code/cache and function-pool race suites passed against the real pin; full repository lint passed on the integrated code. CI is rerunning for the updated PR head.

Landing order: go-lua #60 then #58; runtime #893 then #887. Nothing has been merged or released by this update.

Integration patch for runtime #887 and #893. Preserve conversion failures until the actual callable is known, reject before its body, retain untyped conversion semantics, and exercise source/bytecode, cached calls and initializer preemption. Pin the reproducible go-lua #58/#60 integration revision, with no local replacement. Neither main nor existing argument-contract dependency PR is merged.
…duler

Bring current main and the reviewed #893 shutdown/upgrade fixes into the isolated #887/#893 integration branch. Existing PR heads and main remain separate.
Exercise missing/optional/variadic arguments on fresh and cached calls, method switches, preempted initialization, and unchanged process/untyped conversion. Keep native API error causes and clean messages through the existing Lua-to-API boundary. Strengthen the late-admission routing assertion to use the canonical PID key.
@wolfy-j
wolfy-j changed the base branch from main to feature/lua-tick-preemption October 5, 2026 14:39
@wolfy-j
wolfy-j requested a review from skhaz October 23, 2026 02:26
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