ADR-0017 — Working result tensors and evidence snapshots¶

Status: proposed
Date: 2026-08-31
Owners: ZeroProofML maintainers
Supersedes / superseded by: none

Context¶

A frozen dataclass does not make contained NumPy arrays or Torch storage immutable. Torch working values must also preserve autograd, while serialized, monitored, or audited evidence must not share mutable storage or an active graph.

Decision¶

ResultTensor is the backend-native working layer. Construction breaks source aliasing; NumPy arrays are owned and read-only, Torch payloads are cloned while preserving gradient flow, and a full digest protects payload plus every status, cause, exact-zero, schema, semantic, origin, and execution-evidence field. Working Torch tensors can still be mutated by computation, so every evidence boundary calls validate_integrity() and validate_invariants().

ResultTensor.freeze_evidence() creates a ResultTensorSnapshot. A snapshot is detached, CPU-canonical, NumPy-backed, read-only, storage-independent, fully validated, size-bounded, and bound by one canonical SHA-256. Only snapshots have canonical tensor serialization. Monitoring accepts snapshots and freezes a working result automatically.

Ordinary read-only protection prevents accidental NumPy writes. The digest detects deliberate write-flag bypass at the next boundary. This matches the in-process threat model in ADR-0016 without claiming memory isolation.

Consequences¶

Callers retain differentiable Torch behavior inside a calculation. A working result is not durable evidence until frozen. Snapshot deserialization validates field sets, dtype, rank, shape, element and byte bounds, canonical base64 length, semantic/profile hashes, cross-axis rules, and the serialized digest before it is exposed.

Alternatives considered¶

Freezing every Torch tensor would break normal autograd and still would not provide process isolation. Keeping only the historical exact-zero digest would leave payload and other axes unprotected. Always serializing backend-native Torch objects would retain mutable storage and pickle concerns.

Verification and rollout¶

Tests cover source aliasing, gradient flow, storage independence, read-only behavior, every protected axis, NaN mutation, schema/dtype/shape substitution, resource bounds, and canonical round trips. Maintainer approval is required before changing this ADR from proposed to accepted.