revisionlab 0.1.0__tar.gz

revisionlab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    env:
+      OMP_NUM_THREADS: "1"
+      MKL_NUM_THREADS: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install CPU runtime and development tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install -e ".[dev]"
+      - name: Lint and formatting
+        run: |
+          python -m ruff check .
+          python -m ruff format --check .
+      - name: Types
+        run: python -m mypy src/revisionlab
+      - name: Contracts, diagnostics, compile, and serialization
+        run: python -m pytest
+      - name: Build and validate distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+      - name: Install wheel outside source checkout
+        shell: bash
+        run: |
+          python -m pip uninstall -y revisionlab
+          python -m pip install --no-deps dist/*.whl
+          smoke_dir=$(mktemp -d)
+          cd "$smoke_dir"
+          python -c "from pathlib import Path; import revisionlab; path=Path(revisionlab.__file__).resolve(); assert 'site-packages' in path.parts and 'src' not in path.parts, path; print(path)"
+          revisionlab-check
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions-py${{ matrix.python }}
+          path: dist/*

revisionlab-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+*.pt
+*.pth
+*.npz
+*.npy
+.DS_Store

revisionlab-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+We welcome contributors of all backgrounds and experience levels. Treat people with respect, give constructive feedback, and focus disagreements on evidence and ideas.
+
+Harassment, threats, discriminatory language, sexual attention, personal attacks, and disclosure of private information without permission are unacceptable. Listen to criticism, acknowledge mistakes, respect boundaries, and consider the effects of your words.
+
+This code applies in project spaces and when representing the project publicly. Maintainers may remove harmful content, warn contributors, or restrict participation, considering context, impact, and repetition. Maintainers follow the same standards.
+
+For an incident, contact a repository maintainer through an available private GitHub channel. If no private channel is available, open an issue requesting private contact without sensitive details. Use GitHub private vulnerability reporting for security issues when enabled. Do not post private incident details publicly. Maintainers should protect reporter privacy and explain enforcement decisions where appropriate.
+
+Adapted from [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

revisionlab-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+Keep delayed-feedback behavior explicit. A corrector should be easy to replace without changing ticket issuance, maturity checks, or how forecasts are evaluated.
+
+## Setup
+
+Use Python 3.10 or newer:
+
+```powershell
+python -m pip install -e ".[dev]"
+revisionlab-check
+```
+
+## Add a corrector in five minutes
+
+1. Implement `read(key)`, `write(evidence)`, and `snapshot()` using the memory protocol.
+2. Return a finite scalar correction from `read`; check key shape and finite values before updating.
+3. Make `write` atomic: validate a candidate before committing it, and preserve state/counters if it fails.
+4. Return copied state from `snapshot`.
+5. Supply your corrector to generic `DelayedReplay` and test an issued ticket, exact maturity, duplicate release, and foreign owner.
+
+Start with [examples/delayed_forecast.py](examples/delayed_forecast.py). Import `DelayedReplay` from `revisionlab.replay`; its constructor accepts your memory plus a horizon. `issue(issue_hour, base_prediction, read_key)` returns a ticket, and `release(ticket.ticket_id, target, now_hour)` evaluates the issued forecast before settling its update. Low-level correctors may apply repeated `write` calls; the runner owns exactly-once enforcement. Checkpoint helpers live in `revisionlab.serialization`.
+
+This runnable custom bias corrector ignores the key and learns only a global residual offset:
+
+```python
+import math
+import numpy as np
+from revisionlab.replay import DelayedReplay
+
+
+class BiasCorrector:
+    def __init__(self):
+        self.value = 0.0
+
+    def read(self, key):
+        return self.value
+
+    def write(self, evidence):
+        residual = evidence.target - evidence.ticket.base_prediction
+        candidate = self.value + 0.1 * (residual - self.value)
+        if not math.isfinite(candidate):
+            raise ValueError("Nonfinite candidate")
+        self.value = candidate
+
+    def snapshot(self):
+        return {"value": self.value}
+
+
+runner = DelayedReplay(BiasCorrector(), horizon=2)
+ticket = runner.issue(0, 1.0, np.array([1.0]))
+assert runner.release(ticket.ticket_id, target=2.0, now_hour=2) == 1.0
+assert runner.memory.snapshot() == {"value": 0.1}
+```
+
+Built-in checkpoint helpers support only `ResidualMemory`, `RLS_Corrector`, `NoWrite`, and `ShuffledWrite`. They reject custom correctors; `snapshot()` alone is not a resumable checkpoint contract. Supporting your custom corrector's persistence is separate work, not a five-minute registration promise.
+
+Use a negative control name that describes what it does. No-write and shuffled-write controls must not be described as trained alternatives or evidence of improved memory. Keep prediction-time keys and issued forecasts fixed when feedback arrives; do not recompute past forecasts using current state.
+
+The runner retains settled IDs for lifetime duplicate detection. Include that growing ledger and pending tickets in memory accounting instead of reporting only the fixed corrector state.
+
+For a new rule, document its equation, forgetting/rate settings, clipping, initialization, state budget, and supported inputs. Distinguish a local residual update from full-model gradients. Compare identical inputs, baseline predictions, and released labels while scoring each policy's own actual issued forecast.
+
+## Checks
+
+```powershell
+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/*
+```
+
+Tests should expose causal leakage, failed-write mutation, duplicate settlement, and restore differences. Passing the original happy-path suite is insufficient: [the source audit](docs/source-audit.md) records failures found after 23 original tests passed. A separate reviewer evaluates author changes; authors do not self-approve.
+
+Do not add raw weather data, large checkpoints, credentials, or generated environments to the package. Keep historical receipts separate from newly executed results. Follow [the Code of Conduct](CODE_OF_CONDUCT.md).

revisionlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cjw0076 and RevisionLab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

revisionlab-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: revisionlab
+Version: 0.1.0
+Summary: PyTorch-native delayed-feedback memory contracts, controls, and diagnostics
+Project-URL: Repository, https://github.com/cjw0076/revisionlab
+Project-URL: Issues, https://github.com/cjw0076/revisionlab/issues
+Author: cjw0076
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.2
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hatch>=1.13; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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](https://github.com/cjw0076/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:
+
+```powershell
+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
+
+```python
+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](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
+
+| Boundary | Purpose |
+| --- | --- |
+| Prediction ticket | Keeps prediction-time key, baseline, actual forecast, maturity, and owner identity. |
+| Released evidence | Rejects targets that have not matured and invalid timestamp/target fields. |
+| Memory `read`/`write`/`snapshot` | Reads a correction, applies valid delayed evidence, and copies state. |
+| `DelayedReplay` | Owns tickets, evaluates the issued forecast, and settles feedback exactly once. |
+| Checkpoint | Preserves memory, replay owner, pending tickets, and settled identities for resume. |
+| Local alignment | Compares a correction update with a local residual-loss reference direction. |
+
+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](docs/methods.md) 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:
+
+| Historical policy | Mean joint MSE |
+| --- | ---: |
+| Frozen baseline | 2.122014 |
+| Native live residual | 2.092176 |
+| Live RLS | 2.070044 |
+
+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](docs/provenance.md) and [historical evidence](docs/evidence/README.md).
+
+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
+
+```powershell
+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](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](STATE.md).
+
+See [release steps](docs/releasing.md) for TestPyPI/PyPI handoff and [the source audit](docs/source-audit.md) for adversarial regression requirements. No PyPI upload automation is configured. Licensed under [MIT](LICENSE); participation follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+Local v0.1.0 validation: **95 tests passed, 1 CUDA hardware skip**; lint/format, strict package types, and separate reviews passed. See [verification evidence](docs/verification.md) and [release notes](docs/release-notes-v0.1.0.md). Hosted and publication receipts are recorded separately.

revisionlab-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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](https://github.com/cjw0076/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:
+
+```powershell
+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
+
+```python
+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](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
+
+| Boundary | Purpose |
+| --- | --- |
+| Prediction ticket | Keeps prediction-time key, baseline, actual forecast, maturity, and owner identity. |
+| Released evidence | Rejects targets that have not matured and invalid timestamp/target fields. |
+| Memory `read`/`write`/`snapshot` | Reads a correction, applies valid delayed evidence, and copies state. |
+| `DelayedReplay` | Owns tickets, evaluates the issued forecast, and settles feedback exactly once. |
+| Checkpoint | Preserves memory, replay owner, pending tickets, and settled identities for resume. |
+| Local alignment | Compares a correction update with a local residual-loss reference direction. |
+
+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](docs/methods.md) 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:
+
+| Historical policy | Mean joint MSE |
+| --- | ---: |
+| Frozen baseline | 2.122014 |
+| Native live residual | 2.092176 |
+| Live RLS | 2.070044 |
+
+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](docs/provenance.md) and [historical evidence](docs/evidence/README.md).
+
+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
+
+```powershell
+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](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](STATE.md).
+
+See [release steps](docs/releasing.md) for TestPyPI/PyPI handoff and [the source audit](docs/source-audit.md) for adversarial regression requirements. No PyPI upload automation is configured. Licensed under [MIT](LICENSE); participation follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+Local v0.1.0 validation: **95 tests passed, 1 CUDA hardware skip**; lint/format, strict package types, and separate reviews passed. See [verification evidence](docs/verification.md) and [release notes](docs/release-notes-v0.1.0.md). Hosted and publication receipts are recorded separately.

revisionlab-0.1.0/STATE.md

@@ -0,0 +1,28 @@
+# RevisionLab state
+
+Updated: 2026-10-01 (Asia/Seoul).
+
+## Completed local v0.1.0
+
+- Release priority: delayed-feedback memory/state contracts, controls, diagnostics, and small reproducible examples. archcredit remains separate; CREDO and Cosmos v14/v10 refinement are deferred.
+- Implemented native ResidualMemory/RLS, NumPy reference, differentiable delta primitive, immutable tickets, owner-bound exactly-once replay, negative controls, and built-in checkpoint resume.
+- Native checkpoints preserve pending/settled ticket identities, owner, clock, model state, and issued-forecast evaluation. Custom correctors work through generic replay but are not supported by built-in checkpoint helpers.
+- CLI, typed packaging, Python 3.10/3.11/3.12 CI, contributor recipe, MIT license, release guide, and provenance/evidence documentation are complete.
+- Recovered v13 historical artifacts are byte-preserved; source/result hashes and audit findings are recorded in [provenance](docs/provenance.md). This release did not rerun the full weather experiment.
+
+## Verification
+
+- Final local suite: **95 passed, 1 CUDA hardware skip, 196.79 seconds**.
+- Ruff lint/format passed for 21 formatted files; strict mypy passed for 8 source files.
+- Separate independent code review: APPROVE with zero remaining issues. Scientific documentation review: ACCEPT.
+- Regression tests cover maturity, immutable keys, foreign/duplicate settlement, atomic failed writes, checkpoint/resume, rate/config consistency, unsupported checkpoint dtypes, norm overflow, and seeded permutation consistency.
+- CPU `aot_eager`/gradcheck, examples, literal installed CLI, build/Twine metadata 2.4, and outside-checkout installed-wheel checks passed. See [verification](docs/verification.md).
+
+## Distribution receipts and next work
+
+- GitHub repository created: https://github.com/cjw0076/revisionlab. Hosted workflow receipts belong in [Actions](https://github.com/cjw0076/revisionlab/actions/workflows/ci.yml); publication assets belong at [v0.1.0](https://github.com/cjw0076/revisionlab/releases/tag/v0.1.0) once published. Local validation does not claim those hosted/publication steps have already succeeded.
+- The first hosted matrix failed on NumPy typing compatibility. Mypy now follows each runner's actual Python version with strict checks retained; an explicit float64 NumPy state annotation passes local mypy/format checks. Rebuilt artifacts and hosted rerun evidence are required before recording hosted all-green status.
+- No PyPI upload or model training/pretrained release is recorded. Next distribution step is approved TestPyPI/PyPI handoff with trusted-publisher configuration.
+- Next research step is controlled replay/generalization evidence across sites/regimes and matched correction budgets; v14 splitting requires separate preregistration and pending-ticket semantics.
+
+Local residual alignment is not global BPTT alignment. The replay audit ledger grows with settled ticket IDs; fixed corrector capacity does not mean constant whole-runner memory. CPU smoke does not establish CUDA/Inductor compatibility or performance.