feat(arxjit): resolve a compilable signature from Python annotations

[Jaskirat-s7]

Follows #102. Closes the remaining open question in wiki Issue 2: "decide how Python annotations interact with explicit signatures."

The rules

New arxjit.reconcile decides which Signature a validated function will be compiled against:

given	result
explicit signature=	wins outright; annotations are not read at all
annotations only	signature derived from them
neither	reported at WARNING severity, function stays interpreted
some annotations, others missing or unsupported	every remaining gap is an ERROR

Because an explicit signature short-circuits, a function may annotate freely without having to agree with it — there is deliberately no mismatch error, per the decision in the thread. The last row is the judgement call worth flagging: once a function annotates anything, it is read as asking to be compiled, so a gap elsewhere is an error rather than a silent fallback.

Annotations are read from the ast, not __annotations__

A module using from __future__ import annotations turns every annotation into a string at runtime, which would otherwise have to be evaluated back with eval_str. Reading the ast makes that irrelevant, and lets each diagnostic point at the exact annotation that caused it rather than at the function.

Only a bare int, float or bool is accepted; a subscripted (list[int]), dotted (np.float64) or quoted ("int") annotation is reported against its own location. One consequence worth naming: this can never produce i32 or f32, since Python has no annotation that distinguishes widths, so the narrow types stay explicit-signature only. That partly answers the "should we trim i32/f32?" question from #91 — they remain reachable, just not from annotations.

Positional-only parameters are included in the derived signature. Validation permits them and they are ordinary positional arguments to a compiled function, so leaving them out would silently drop an argument.

Fail-closed on argument shapes

Signature is a fixed list of positional argument types, so a variadic or keyword-only parameter has nowhere to go. Validation rejects those shapes first, which makes this unreachable through @jit — but resolve_signature is exported, and without a check it would leave the parameters out and hand back a signature that is quietly wrong (i64() for a function taking *args). It now reports that it cannot derive one instead. Four regression tests cover *args, **kwargs, keyword-only, and the mixed positional-plus-variadic case.

Location helpers moved

_char_column and _diagnostic move out of validation.py into a new arxjit.locations, now that a second stage builds diagnostics from ast nodes. Single-sourcing them keeps the two stages from drifting on the column contract (one-based Unicode characters, converted from ast's zero-based UTF-8 byte offsets at the boundary). No behaviour change — a move, plus a severity parameter so reconciliation can emit WARNING.

Note on scope

resolve_signature is exported and fully tested but not yet consulted by @jit — core.py is untouched here. Wiring it into the decorator, along with the strict flag and the warn-and-fall-back behaviour, is the next PR. Splitting it this way keeps the resolution rules reviewable on their own, separately from the decorator behaviour change.

Verification

169 tests, arxjit coverage 100%. All gates green locally: pytest+cov, ruff format/check, mypy strict (cd packages/arxjit && mypy src), bandit -iii -lll, vulture 80, mccabe 10, douki sync idempotent. Verified on CPython 3.10.19, 3.11.11 and 3.14.6.

[xmnlab]

thanks for working on that @Jaskirat-s7

some comments from my side:

1. High — explicit-signature arity is still unchecked

resolve_signature() still returns an explicit signature immediately. It does not compare the number of explicit.arg_types with the function’s positional and positional-only parameters.

Therefore, this still succeeds incorrectly:

def add(a, b):
    return a + b

resolve_signature(extract_source(add), i64(i64))

Signature accepts any argument-type tuple and does not perform that structural check itself.

An explicit signature should override annotation types, but it should not be allowed to describe a different number of arguments from the function.

2. Medium — annotation types are still resolved by spelling

Bare names spelled int, float, or bool are accepted without checking what those names resolve to in the function’s namespace.

For example:

int = str

def identity(value: int) -> int:
    return value

The resolver derives i64(i64), even though Python resolves both annotations to str.

ExtractedSource already carries globalns and freevars, so the resolver has most of the context needed to reject shadowed builtin annotation names or deliberately document them as reserved ArxJIT syntax.

CI

The package tests, language tests, and linter pass. The main workflow currently fails only because the PR branch is no longer up to date with origin/main; it needs to be rebased or updated.

Once the two reconciliation issues are addressed and the branch is updated, this should be ready for another review.

[Jaskirat-s7]

Both good catches, thanks, fixed in the latest commit.
@xmnlab , @yuvimittal
On the arity one, you're right, and it turned out wider than your example. The short-circuit was written for the rule that an explicit signature overrides annotation types, but it returned before everything else, so it was also skipping the variadic guard from the last round ,@jit(signature=i64(i64)) on a def f(*args) sailed straight through too. So rather than just adding an arity check, I moved the structural checks ahead of the explicit branch, and both paths get them now. An unsupported shape stops there and doesn't also report a count, since "takes 0 arguments" for a *args function is a number nobody can act on.

for the second change I was matching on spelling and never asking what the name currently pointed at.
Annotation names now have to resolve to the builtin they're spelled after, using the namespace already on ExtractedSource from that work.

One thing I'd like your call on: I've only consulted globalns. A function's own locals can't matter, since annotations are evaluated in the enclosing scope when the def runs. But an enclosing function rebinding int is real and i don't think it's observable here — freevars only records names the body reads, and an annotation isn't part of the body. Is module-level enough, or would you rather I document the enclosing case as out of contract with a test pinning it, like we did for the method forms in #102?

While auditing before pushing I also pulled out three things that weren't earning their place, none of which line coverage could see: the mismatch message pluralized the count but no test ever produced the plural (both halves sit on one ternary); the builtin lookup had an unreachable default that would have reported every module merely defining the name as shadowing it, if it had ever fired; and _annotation_type existed only to prove a node was an ast.Name and then lose that narrowing, so its one caller had to cast it back. First got a test, second lost the default, third got merged in.
179 tests, 100% coverage including branches, checked on 3.10/3.11/3.14.