Detached-reference handling: rescue re-run + mechanical belt¶

TorchLens installs persistent wrappers around torch callables on the first torch capture. A Python binding created before that installation—such as from torch import relu—can still point to the raw callable after the torch namespace itself is wrapped.

The historical sys.modules crawler (and its patch_policy rollout) is deleted. TorchLens no longer rewrites module attributes broadly, reads module sources, or mutates user model instances to repair stale bindings. Coverage is now:

1. Rescue re-run. A completed capture that carries an escape signal — the tensor-provenance warning, an escape_detector diagnostic, or an output-attribution failure — is re-run ONCE with a TorchFunctionMode net armed. The net redirects any stale pre-wrap reference to its exact wrapper, so recovered ops are logged with full wrapper fidelity. The primary capture is never mode-armed (an armed mode flips torch's fused fast paths, e.g. eval MultiheadAttention 3 ops -> 27 ops), so ordinary captures are byte-identical to earlier releases. The rescue also covers holder classes the crawler never reached: closure cells, staticmethods, module-level partials, plain object attributes, pre-bound tensor methods, torch-free-source modules, and C-held references. The most reliable pattern is still to wrap early: call torchlens.backends.torch.wrappers.wrap_torch() before creating aliases, closures, partials, or object-held torch callables. Then those bindings capture the wrappers directly and no rescue is needed. The MIRROR direction is a declared residual for BARE references: a plain attribute read taken WHILE wrappers are installed (held = F.relu) hands the user the wrapper object, and torchlens.backends.torch.wrappers.unwrap_torch() does not repair user-held wrapper references — TorchLens never crawls or mutates user objects during capture. The held reference stays callable (it delegates to the original) but is identity-poisoned after unwrap: held is F.relu is False and pickling it (or any object holding it) fails. For references held on a MODEL, tl.release_model(model) is the shipped repair: it normalizes held torch-function attributes (one level of exact builtin containers, namedtuples included, dict keys included) to the currently-live values, and registers the model so every later wrap-state flip re-normalizes it — released models stay serializable in every epoch. Bare references held outside a model still require re-reading the attribute after unwrap, or a fresh process.
2. Mechanical belt. A small, per-build DERIVED set of wrapped functions is invisible to every TorchFunctionMode (zero protocol callbacks, measured at wrap time): on current builds torch.from_numpy, torch.from_dlpack, torch.frombuffer, torch.Tensor.as_subclass, and torch.Tensor._make_subclass (the authoritative set is the live derivation in belt_report().members, pinned per build in tests/test_mechanical_belt.py). A stale reference to one of these produces no signal a rescue could trigger on, so module-level attribute references to them keep targeted patching, with a conditional reversal ledger restored at torchlens.backends.torch.wrappers.unwrap_torch().

Honesty semantics¶

• A rescued trace is disclosed: capture_verified=False, capture_verification_reason == "mode_rescue_rerun", and a session-time trace.rescue_rerun record naming the trigger and the recovered ops. Rescue captures are never byte-attestable (the forward ran twice and mode presence can de-fuse fast paths).
• An escape the net cannot recover — a worker-thread stale reference (modes are thread-local; op logging is owner-thread-scoped by design) or a stale reference inside a third-party handle_torch_function composite body (the protocol pops the mode before the body runs) — is DISCLOSED, never silent: capture_verified=False with reason "escape_rescue_unrecovered" unless a more specific verdict (dispatch witness, shadow detector, Dynamo boundary) is already present, which stays authoritative.
• An armed completeness witness that VERIFIES the capture outranks the heuristic provenance signal (for example an autograd.grad boundary is a known no-provenance source); no rescue runs.
• Ineligible captures skip only the RE-RUN, never the disclosure. Every channel the re-run would invoke a second time refuses (fail closed): streaming saves, streaming.on_save callbacks, disk grad storage, stop_after= predicates, intervene= predicates, pre-attached hooks=, and the activation_transform, grad_transform, and output_transform callables. A live escape signal on such a capture still settles capture_verified=False with reason "escape_rescue_unrecovered" (skipped_reason == "rescue_ineligible", forward_runs == 1) plus a UserWarning — never clean-capture fields.
• A rescue re-run executes the user's forward a SECOND time. When the primary forward ACTUALLY WROTE module buffer state (train-mode BatchNorm running stats and num_batches_tracked, in-forward buffer counters), the re-run is refused — RNG is restored between runs, module state is not — and the escape stands disclosed (skipped_reason == "buffer_writes_double_forward", forward_runs == 1). The refusal keys on a VALUE-CHANGING write, not on journal presence: fused norm mutators are journaled unconditionally, so eval-mode BN/IN/GN captures carry buffer_value_changed == False records and stay rescuable; an unknown change status refuses fail-closed. The refusal covers EVERY trigger, including an output-attribution failure — there the re-run is refused, the failure propagates with its exc.partial_trace, and the skip is disclosed on the partial's trace (rescue_rerun). On rescued (eval-mode) captures, a custom in-forward PYTHON-attribute counter (not a registered buffer) still mutates twice: a declared residual of the double forward, visible via trace.rescue_rerun["forward_runs"] == 2.
• The capture-attempt-failed advisory ("Partial diagnostics ride the exception") is emitted on a dedicated RuntimeWarning subclass and DEFERRED while a rescue re-run may still swallow the failure: a successful rescue drops it (the rescue is disclosed on the returned trace), and every re-raising path flushes it, so it never points at an exception the user does not receive.
• A rescue that would count as recovery must produce a strict SUPERSET of the primary's op multiset. Mode presence can de-fuse fused fast paths; any op LOSS keeps the mode-free primary authoritative, with both deltas disclosed (recovered_ops / lost_ops).

Removed surface¶

• tl.wrap_torch(patch_policy=..., patch_modules=...) — removed (formerly deprecated no-ops).
• patch_detached_references(...) / clear_patch_detached_references_cache() — removed (formerly no-op shims for the deleted crawler; PatchReport removed with them).
• Trace fields detached_patch_policy / detached_patch_epoch — removed.
• The "scoped_dispatch_witness_not_enabled" verification reason — removed with the policy machinery.

Shadow detector semantics¶

escape_detector="shadow" observes raw callable execution using exact object/code identity. It reports a tl.errors.CaptureGapWarning with the callable, registered export sites, source callsite, storage hint, short stack, and remediation. Reports also appear in trace.escape_diagnostics, and a diagnostic now also TRIGGERS the rescue re-run (the report from the primary run is preserved in trace.rescue_rerun["primary_escape_diagnostics"]).

Every wrapper-to-original edge uses a one-shot immediate-caller token. Tokens are identity-compatible with transient Tensor-bound builtins by requiring a Tensor receiver and an exact method name from the wrapped-method inventory. They never exempt the dynamic duration of a wrapper. Thus a raw descriptor called by a user callback inside a composite wrapper remains reportable. TorchLens-internal exceptions, if ever required, must match an exact parent/child/callsite row; the audited table has a hard budget of 16 entries. Its current rows are exhausted by the two branches of the eight torch._jit_internal.boolean_dispatch pooling functions; each row is restricted to the exact parent wrapper, child callable, _jit_internal.py callsite, and fn caller.

The one-shot token also cannot represent a Python inventory original that recursively calls itself through a pre-wrap reference. For example, a synthetic registered original shaped like def original(x): return original(x - 1) if x else x consumes its wrapper token on the first call, then the recursive call can self-convict. This class is documented rather than exempted because its callsite is arbitrary original/user code; a general recursion exemption would become an ancestry blanket and hide real escaped calls.

Shadow is default-off. When it is enabled, the resulting trace remains unverified even with no reports ("shadow_diagnostic_mode"); pair it with completeness_witness=True for a positive verdict.

Machine-readable qualification¶

Live torch traces expose these diagnostic fields:

Public tl.record(...) uses the same guarded forward hot path and mirrors these fields onto the returned Recording.

The verification VERDICT now survives a .tlspec round-trip in the negative direction only: a capture the producer refused to bless loads with capture_verified=False and its string capture_verification_reason intact, so an escape-disclosed artifact is never byte-indistinguishable from a clean one. A positive claim never persists — a loaded trace reports None/unknown rather than a falsely preserved (or forged) True, and load degrades any non-False persisted value the same way. rescue_rerun (and the heavyweight escape_diagnostics) remain live session-time diagnostic state and still do not survive the round-trip.

Honest boundaries¶

The thread tripwire compares threading.active_count() at forward entry and exit. It catches a live count delta cheaply, but a worker that starts and joins entirely inside the forward can evade that sample. This is why the guarantee remains explicitly owner-thread-qualified.