feat: 0.1.3 invocation-local reuse and small-batch scoring equivalence

[rextio]

Summary

Safe, bounded invocation-local reuse for the rextio-tensorflow 0.1.3 Unreleased candidate, plus self-contained small-batch eager scoring equivalence coverage.

Architecture

Core plugin API 1.6 has no per-generated-function invocation/prologue hook (claim / lower / covers / describe / type_vocabulary / optional artifact_capability only). This PR therefore does not invent process-global, thread-local, or cross-context tensor/context caching.

Instead, reuse is carried by existing generated values:

Mechanism	Carrier	What is reused
Pinned Python eager context	BorrowedContext	Existing synchronous capsule (unchanged contract)
Prepared axes / transpose perm	BorrowedContext RAII table	Context-bound constants (from prior 0.1.3 work)
Dtype / rank / device facts	TrustedResidentFacts on OwnedTensorHandle	After full validation of boundary extract or op result

Avoided after facts are trusted for a handle: redundant TFE_TensorHandleDataType / NumDims / Dim / BackingDeviceName queries for that same resident intermediate inside one generated call graph.

Still required: boundary validation exactly once on extract; full validation of every operation result before facts are stamped; same-context checks; fail-closed unsupported dtype/rank/device; existing error message strings; PendingHandle / OwnedTensorHandle / PreparedHandle / BorrowedContext drop ordering with Python anchors alive.

TF_Status: remains per operation. TF 2.21.0 framework image exports TF_NewStatus / TF_DeleteStatus / TF_SetStatus / TF_GetCode / TF_Message but no exact public TF_ResetStatus (or equivalent fail-closed reset). Status reuse via TF_SetStatus(OK, …) was not accepted.

CUDA: source derivation updated to preserve the facts short-circuit while keeping exact GPU:0 backing-device validation and the frozen E3 surface. No CUDA contract promotion.

Core blocker (remaining)

A true explicit InvocationContext spanning one generated function needs a Core per-generated-function prologue/invocation hook. Optional follow-on: bind a public fail-closed status-reset symbol if TensorFlow ever exports one, for reusable TF_Status hosted on that object.

Non-claims

• No speedup / performance claim; no latency threshold
• No graph / tf.function / FunctionDef fusion
• No cross-generated-function residency or process-global prepared caches
• No CUDA support/certification promotion
• Optional tf.function diagnostic in scoring test is non-headline Python-only

Tests / validation

Local (CPython 3.11.9 + TF 2.21.0 + rextio 0.1.6):

pytest tests -m "not needs_cargo" -q
# 444 passed, 1 skipped, 10 deselected

ruff check src tests   # All checks passed
mypy src               # Success: no issues found in 30 source files

pytest tests/e2e/test_alpha_real_cargo.py -q
# 10 passed (includes intermediate chain + small-batch scoring)

pytest tests/e2e/test_alpha_real_cargo.py::test_small_batch_scoring_equivalence_real_cargo -q
# 1 passed (incl. per-function four-round Rust for/if source lock)

Small-batch scoring (batches 1/16/128, F=32, C=8): full logits, probabilities, and classes compared across Python / fallback / forced native — not argmax-only. Generated bodies for all three scoring functions are asserted to contain for round_idx in 0..4 and if __rextio_checked_rem(round_idx, 2)? == 0, scoped per pyfunction so unrelated loops cannot satisfy the check.

Hosted CI on this PR: all checks passed (16/16 green on the feature branch; re-run after the control-flow source-lock commit as applicable).

Commits

• f2c1743 — feat: add invocation-local trusted resident fact reuse
• e1a4f3e — docs: document 0.1.3 invocation-local reuse and small-batch scoring
• 4c15aed — test: lock small-batch generated four-round Rust control flow

Base: 0.1.3 @ 346ca58148ed2563d4c7547dd8443d60cd4f905b

Test plan

• Unit suite (not needs_cargo)
• ruff + mypy
• Real-Cargo full test_alpha_real_cargo.py
• Hosted CI native-e2e / package jobs on this PR (passed)
• Do not merge/tag/release from this PR without integration review