RevisionLab

PyTorch-native delayed-feedback memory contracts, controls, and diagnostics.

RevisionLab records a prediction when it is issued, waits for its outcome to mature, and applies a residual-state update to the memory that owned the prediction. It provides a small substrate for testing delayed correction: immutable tickets, explicit memory interfaces, replay, negative controls, and resumable state.

v0.1 focuses on fixed-capacity residual memory and RLS correction. It does not implement Cosmos v14 state splitting or the v10 learned-refinement toy. It makes no claim to support every neural architecture. archcredit remains a separate architecture/credit benchmark library; RevisionLab does not depend on it.

Install and check

From a checkout with Python 3.10 or newer:

python -m pip install -e ".[dev]"
revisionlab-check

The check runs a small synthetic delayed-feedback example. It does not download weather data or replay the historical experiment.

Minimal API

import numpy as np
from revisionlab import ResidualMemory
from revisionlab.replay import DelayedReplay

runner = DelayedReplay(ResidualMemory(2, rate=0.1), horizon=2)
ticket = runner.issue(0, 1.0, np.array([1.0, 0.0]))
error = runner.release(ticket.ticket_id, target=2.0, now_hour=2)
assert ticket.prediction == 1.0
assert error == 1.0
assert runner.memory.read(np.array([1.0, 0.0])) == 0.1

See examples/delayed_forecast.py for a complete replay example. revisionlab.serialization.save_checkpoint(path, runner) and load_checkpoint(path) preserve delayed-feedback runners using the four native built-in correctors. Custom correctors and the NumPy reference are not supported by these checkpoint helpers in v0.1.

Contracts

The NumPy reference and PyTorch-native implementations use fixed-capacity state. Negative controls are explicitly named; shuffled writes corrupt write addressing rather than demonstrating a new learning rule. A no-write control must preserve zero correction and perform no learning.

ResidualMemory(slots, rate) is the native normalized-delta corrector. revisionlab.baselines provides RLS_Corrector(slots, forget), NoWrite(slots), and ShuffledWrite(slots, rate, seed=...). See the method manifest for equations and clipping. Low-level memory write applies each valid call; exactly-once settlement is a DelayedReplay guarantee, not a guarantee of direct memory writes. Tickets retain prediction-time keys and forecasts, and the runner rejects duplicate/foreign settlement.

Memory values have fixed capacity. Replay retains settled ticket identities for lifetime deduplication, so its total audit ledger grows with settled forecasts; report that overhead alongside pending tickets. Do not call the entire runner constant-memory.

What the evidence means

Recovered v13 artifacts report the following historical mean joint MSE:

These are prior-run receipts for one site and the first half of 2026, across five weight seeds. The residual method improved on the frozen baseline in that recorded setting, while RLS had the lower mean MSE. This release has not rerun the full weather experiment, established superiority over RLS, or demonstrated generalization to other climates. See provenance and historical evidence.

The original shuffled-write policy used a fixed cyclic permutation. The release's seeded ShuffledWrite control is a distinct policy and does not reproduce that historical control automatically.

Local residual alignment rho is not full-model BPTT alignment. The delta primitive is differentiable, but that alone does not prove correct global credit assignment or causal memory capacity. Zero-norm directions have undefined alignment.

Development and contribution

python -m ruff check .
python -m ruff format --check .
python -m mypy src/revisionlab
python -m pytest
python -m build
python -m twine check dist/*

CONTRIBUTING.md explains the five-minute corrector recipe. CI covers Python 3.10/3.11/3.12, lint/format, types, tests, aot_eager compile/serialization/gradcheck, and wheel installation outside the checkout. A CI definition is not a claim that hosted jobs have already passed; current receipts belong in STATE.md.

See release steps for TestPyPI/PyPI handoff and the source audit for adversarial regression requirements. No PyPI upload automation is configured. Licensed under MIT; participation follows the Code of Conduct.

Local v0.1.0 validation: 95 tests passed, 1 CUDA hardware skip; lint/format, strict package types, and separate reviews passed. See verification evidence and release notes. Hosted and publication receipts are recorded separately.