cadence-net 0.1.0__tar.gz

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

@@ -0,0 +1,22 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check src tests examples
+      - run: mypy
+      - run: pytest -q
+      - run: python examples/half_center.py && python examples/ring_protocol.py

cadence_net-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+data/
+*_receipt.json

cadence_net-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bernhard Mueller
+
+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.

cadence_net-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: cadence-net
+Version: 0.1.0
+Summary: Machine learning by patch-net settlement: owner-local repair, held-out tests, receipts.
+Project-URL: Homepage, https://github.com/muellerberndt/cadence
+Project-URL: Issues, https://github.com/muellerberndt/cadence/issues
+Author: Bernhard Mueller
+License: MIT
+License-File: LICENSE
+Keywords: connectome,local learning,patch net,receipts,settlement
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Provides-Extra: accel
+Requires-Dist: torch>=2.2; extra == 'accel'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: torch>=2.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cadence
+
+**Machine learning by patch-net settlement: owner-local repair, held-out tests, receipts.**
+
+A patch net is a set of *owners*, each holding one patch of state, joined by declared
+*overlaps*. Nothing is computed globally. Every owner repairs its own patch from what
+arrives over its overlaps, and the state the net comes to rest in is the answer. Cadence
+is the library for building, settling, testing, and certifying such nets, from a
+six-owner ring to a 161,827-owner nervous system read from a connectome.
+
+```python
+import cadence as cd
+
+wiring = cd.Wiring.from_edges(4, pre=[0, 1, 2, 3], post=[1, 2, 3, 0], count=[120] * 4)
+engine = cd.Settlement(wiring, cd.GradedRule(gain=0.03))
+engine.settle(clamp={0: 1.0}, steps=60).activation.round(2)
+# array([1., 1., 1., 1.])
+```
+
+## What is in the box
+
+| layer | what it gives you |
+|---|---|
+| `Wiring` | owners and overlaps as sorted arrays, named sets, digests; built from edge lists |
+| `GradedRule`, `Adaptation` | the owner rule: a graded potential with a rectified sigmoid that emits nothing at rest, and an optional adaptation variable that turns fixed points into rhythm |
+| `Settlement` | the engine, on NumPy float64 (`"cpu"`) or torch (`"torch"`: CUDA, Apple silicon, or CPU) |
+| `conformance`, `settle_owner_by_owner`, `Ledger` | an owner-by-owner reference engine with a message ledger, to certify that a fast backend computes nothing the owners could not |
+| `Protocol`, `Row`, `shuffled`, `select_gain` | declared stimuli, readouts, and held-out facts with preconditions; the shuffled-wiring control; gain selection under a sparsity cap |
+| `Receipt`, `source_manifest` | canonical JSON bound to code and data by digest, verified by recomputing every pass flag |
+| `Source`, `fetch` | pinned public data, downloaded once, verified always |
+
+## Install
+
+```bash
+pip install cadence-net            # NumPy only; the import is `cadence`
+pip install "cadence-net[accel]"   # adds torch for CUDA and Apple silicon
+```
+
+Python 3.11 or newer. On an M-series Mac the torch backend runs on MPS in float32; on CUDA
+it runs in float64. The CPU backend is always float64 and is the one receipts are made on.
+
+## Sixty seconds
+
+**A wiring** is `n` owners plus directed overlaps with a contact count and a sign. Build it
+from edge lists; parallel overlaps merge, autapses drop, and you can name sets of owners.
+
+```python
+w = cd.Wiring.from_edges(
+    3, pre=[0, 0, 1], post=[1, 2, 2], count=[80, 20, 80], sign=[1, 1, -1],
+    sets={"input": [0], "output": [2]},
+)
+```
+
+**A rule** says what an owner does with its inbox. `GradedRule` is the one every
+connectome lane uses. Add `Adaptation` when you want rhythm.
+
+```python
+rule = cd.GradedRule(gain=0.02, adaptation=cd.Adaptation(tau_steps=40, strength=1.0))
+```
+
+**Settle** from rest under a clamp. A clamp is a list of owners at full amplitude, a
+`{owner: level}` map, or a dense drive vector. Ask for the trajectory when you want to watch.
+
+```python
+engine = cd.Settlement(w, rule, backend="torch")   # or "cpu"
+state = engine.settle(w.members("input"), steps=100, trajectory=True)
+state.activation, state.trajectory.shape
+```
+
+**Declare a protocol** and score it. Rows are held-out facts with predicates that carry
+their preconditions. The shuffled control keeps every count, sign, and set.
+
+```python
+protocol = cd.Protocol(
+    stimuli={"rest": (), "drive": ("input",)},
+    training=[("drive", "output", "active")],
+    rows=[cd.Row("R1", "rest", "output", "inactive", "nothing in, nothing out")],
+)
+protocol.score(engine)["passed"], protocol.score(cd.Settlement(cd.shuffled(w, 0), rule))["passed"]
+```
+
+**Certify** the backend and **write a receipt**.
+
+```python
+cd.conformance(engine, w.members("input"))["max_abs_deviation"]
+receipt = cd.Receipt.build("my-lane/v1", {"score": protocol.score(engine)}, sources=[("lane.py", Path("lane.py"))])
+receipt.write(Path("receipt.json"))
+cd.Receipt.verify(Path("receipt.json"), sources=[("lane.py", Path("lane.py"))])
+```
+
+The [quickstart](docs/quickstart.md) walks through a connectome; [concepts](docs/concepts.md)
+explains why the library is shaped this way; [backends](docs/backends.md) covers devices
+and precision; [receipts](docs/receipts.md) covers what a verified result means.
+
+## Discipline
+
+Three rules the library enforces rather than recommends:
+
+1. **Owner-local or nothing.** The reference engine reads one owner and its inbox at a
+   time and ledgers every delivery. `conformance` compares any backend against it.
+2. **Held out means held out.** A protocol names the few facts a model may be shown. Gains
+   are selected on those alone, and only while the net stays sparse, because runaway
+   activity lights every readout and proves nothing about the wiring.
+3. **A result is a receipt.** Canonical JSON, a digest, the digests of the code and data,
+   and every pass flag recomputable from the stored readings. A receipt that fails to
+   verify is not a result.
+
+## Where it comes from
+
+Cadence consolidates the lanes of the observer patch net programme: a *C. elegans*
+connectome scored against classical ablation phenotypes, the FlyWire *Drosophila* brain
+and the MANC nerve cord joined by their descending neurons and scored against held-out
+taste, grooming, escape, olfaction, and motor facts, and that nervous system driving a
+biomechanical fly in MuJoCo. Every one of those lanes is a wiring, a rule, a protocol, a
+control, and a receipt; the library is what they had in common.
+
+## Status
+
+Version 0.1.0 is the core: wiring, rule, engine, reference, protocol, receipts, custody.
+On the roadmap: the owner-local free/nudged learning rule, closure sub-nets for
+in-browser settlement, environment adapters for embodiment, and connectome loaders.
+
+MIT licensed.

cadence_net-0.1.0/README.md

@@ -0,0 +1,123 @@
+# Cadence
+
+**Machine learning by patch-net settlement: owner-local repair, held-out tests, receipts.**
+
+A patch net is a set of *owners*, each holding one patch of state, joined by declared
+*overlaps*. Nothing is computed globally. Every owner repairs its own patch from what
+arrives over its overlaps, and the state the net comes to rest in is the answer. Cadence
+is the library for building, settling, testing, and certifying such nets, from a
+six-owner ring to a 161,827-owner nervous system read from a connectome.
+
+```python
+import cadence as cd
+
+wiring = cd.Wiring.from_edges(4, pre=[0, 1, 2, 3], post=[1, 2, 3, 0], count=[120] * 4)
+engine = cd.Settlement(wiring, cd.GradedRule(gain=0.03))
+engine.settle(clamp={0: 1.0}, steps=60).activation.round(2)
+# array([1., 1., 1., 1.])
+```
+
+## What is in the box
+
+| layer | what it gives you |
+|---|---|
+| `Wiring` | owners and overlaps as sorted arrays, named sets, digests; built from edge lists |
+| `GradedRule`, `Adaptation` | the owner rule: a graded potential with a rectified sigmoid that emits nothing at rest, and an optional adaptation variable that turns fixed points into rhythm |
+| `Settlement` | the engine, on NumPy float64 (`"cpu"`) or torch (`"torch"`: CUDA, Apple silicon, or CPU) |
+| `conformance`, `settle_owner_by_owner`, `Ledger` | an owner-by-owner reference engine with a message ledger, to certify that a fast backend computes nothing the owners could not |
+| `Protocol`, `Row`, `shuffled`, `select_gain` | declared stimuli, readouts, and held-out facts with preconditions; the shuffled-wiring control; gain selection under a sparsity cap |
+| `Receipt`, `source_manifest` | canonical JSON bound to code and data by digest, verified by recomputing every pass flag |
+| `Source`, `fetch` | pinned public data, downloaded once, verified always |
+
+## Install
+
+```bash
+pip install cadence-net            # NumPy only; the import is `cadence`
+pip install "cadence-net[accel]"   # adds torch for CUDA and Apple silicon
+```
+
+Python 3.11 or newer. On an M-series Mac the torch backend runs on MPS in float32; on CUDA
+it runs in float64. The CPU backend is always float64 and is the one receipts are made on.
+
+## Sixty seconds
+
+**A wiring** is `n` owners plus directed overlaps with a contact count and a sign. Build it
+from edge lists; parallel overlaps merge, autapses drop, and you can name sets of owners.
+
+```python
+w = cd.Wiring.from_edges(
+    3, pre=[0, 0, 1], post=[1, 2, 2], count=[80, 20, 80], sign=[1, 1, -1],
+    sets={"input": [0], "output": [2]},
+)
+```
+
+**A rule** says what an owner does with its inbox. `GradedRule` is the one every
+connectome lane uses. Add `Adaptation` when you want rhythm.
+
+```python
+rule = cd.GradedRule(gain=0.02, adaptation=cd.Adaptation(tau_steps=40, strength=1.0))
+```
+
+**Settle** from rest under a clamp. A clamp is a list of owners at full amplitude, a
+`{owner: level}` map, or a dense drive vector. Ask for the trajectory when you want to watch.
+
+```python
+engine = cd.Settlement(w, rule, backend="torch")   # or "cpu"
+state = engine.settle(w.members("input"), steps=100, trajectory=True)
+state.activation, state.trajectory.shape
+```
+
+**Declare a protocol** and score it. Rows are held-out facts with predicates that carry
+their preconditions. The shuffled control keeps every count, sign, and set.
+
+```python
+protocol = cd.Protocol(
+    stimuli={"rest": (), "drive": ("input",)},
+    training=[("drive", "output", "active")],
+    rows=[cd.Row("R1", "rest", "output", "inactive", "nothing in, nothing out")],
+)
+protocol.score(engine)["passed"], protocol.score(cd.Settlement(cd.shuffled(w, 0), rule))["passed"]
+```
+
+**Certify** the backend and **write a receipt**.
+
+```python
+cd.conformance(engine, w.members("input"))["max_abs_deviation"]
+receipt = cd.Receipt.build("my-lane/v1", {"score": protocol.score(engine)}, sources=[("lane.py", Path("lane.py"))])
+receipt.write(Path("receipt.json"))
+cd.Receipt.verify(Path("receipt.json"), sources=[("lane.py", Path("lane.py"))])
+```
+
+The [quickstart](docs/quickstart.md) walks through a connectome; [concepts](docs/concepts.md)
+explains why the library is shaped this way; [backends](docs/backends.md) covers devices
+and precision; [receipts](docs/receipts.md) covers what a verified result means.
+
+## Discipline
+
+Three rules the library enforces rather than recommends:
+
+1. **Owner-local or nothing.** The reference engine reads one owner and its inbox at a
+   time and ledgers every delivery. `conformance` compares any backend against it.
+2. **Held out means held out.** A protocol names the few facts a model may be shown. Gains
+   are selected on those alone, and only while the net stays sparse, because runaway
+   activity lights every readout and proves nothing about the wiring.
+3. **A result is a receipt.** Canonical JSON, a digest, the digests of the code and data,
+   and every pass flag recomputable from the stored readings. A receipt that fails to
+   verify is not a result.
+
+## Where it comes from
+
+Cadence consolidates the lanes of the observer patch net programme: a *C. elegans*
+connectome scored against classical ablation phenotypes, the FlyWire *Drosophila* brain
+and the MANC nerve cord joined by their descending neurons and scored against held-out
+taste, grooming, escape, olfaction, and motor facts, and that nervous system driving a
+biomechanical fly in MuJoCo. Every one of those lanes is a wiring, a rule, a protocol, a
+control, and a receipt; the library is what they had in common.
+
+## Status
+
+Version 0.1.0 is the core: wiring, rule, engine, reference, protocol, receipts, custody.
+On the roadmap: the owner-local free/nudged learning rule, closure sub-nets for
+in-browser settlement, environment adapters for embodiment, and connectome loaders.
+
+MIT licensed.

cadence_net-0.1.0/docs/backends.md

@@ -0,0 +1,44 @@
+# Backends, devices, precision
+
+```python
+import cadence as cd
+cd.available_backends()
+# {'cpu': 'numpy float64', 'torch': 'mps float32'}   # on an M-series Mac with torch installed
+```
+
+| backend | where it runs | precision | use it for |
+|---|---|---|---|
+| `"cpu"` | NumPy | float64 | receipts, conformance, anything you will cite |
+| `"torch"` on CUDA | GPU | float64 | large wirings at receipt precision |
+| `"torch"` on MPS | Apple silicon GPU | float32 | interactive work; MPS has no float64 |
+| `"torch"` on CPU | torch CPU | float64 | when torch is installed and you want one code path |
+
+Both backends do the same arithmetic: one scatter of every overlap's message into its
+owner's inbox per step, then one owner-local update. NumPy uses `bincount`; torch uses
+`index_add_`. Neither builds a dense matrix, so a wiring of a few million overlaps settles
+in tens of milliseconds per step on a GPU and under a second on a CPU.
+
+## Choosing a device
+
+```python
+cd.Settlement(w, rule, backend="torch")               # cuda, else mps, else cpu
+cd.Settlement(w, rule, backend="torch", device="cpu")  # force
+```
+
+## Precision matters
+
+Owners can sit on knife edges, where a difference of 1e-7 in a drive flips a bistable
+readout. Float32 summation order alone did that to a motor neuron in the fly brain. Two
+habits keep this honest:
+
+1. Make receipts on `"cpu"` or on CUDA float64.
+2. When you use MPS float32 for a page or a demo, run `cd.conformance` on the same wiring
+   and clamp, and show the deviation. It is usually around 1e-5; when it is not, a readout
+   near threshold is telling you something.
+
+## Extending to another device
+
+The torch kernel is one small class, `settle._TorchKernel`, with three operations: gather
+`s[pre]`, scatter-add into `inbox`, and the elementwise update. Any array library that
+offers those three can host a backend; the reference engine and `conformance` are what you
+check it against.

cadence_net-0.1.0/docs/concepts.md

@@ -0,0 +1,70 @@
+# Concepts
+
+## Owners, overlaps, settlement
+
+A patch net is not a function that maps inputs to outputs. It is a set of owners, each
+holding a patch of state, joined by overlaps that carry messages. There is no global step:
+every owner repairs its own patch from its own state, its inbox, its clamp, and its bias.
+Iterating that repair from rest is *settlement*, and the state the net rests in is what a
+readout sees.
+
+The graded rule is
+
+    v <- v + dt * ( -v + inbox + clamp + bias - strength * a )
+    inbox = sum over inbound overlaps of  gain * count * sign * exp(log_gain[pre]) * s[pre]
+    s(v)  = rectified sigmoid, exactly zero at rest
+
+The drive is absolute per contact: a hub integrates every contact it receives, and the
+one global parameter is the drive of one contact. That follows the leaky integrate-and-fire
+convention used for the fly brain, and it is why gains are small numbers.
+
+## Why rest emits nothing
+
+A plain sigmoid emits a few percent at rest. Multiplied by thousands of contacts on a hub
+that leak ignites the net with no input at all. The activation is therefore re-based so
+that an owner at exactly rest publishes exactly zero, in the engine's own precision. Rest
+is then a fixed point of the whole net, and "nothing in, nothing out" is a testable fact.
+
+## Why adaptation
+
+A graded rule with one time constant converges to a fixed point under a constant clamp:
+a posture, never a gait. Adaptation adds one slow variable per owner that follows its own
+activation and subtracts from its own drive. With mutual inhibition, which every real
+wiring has in abundance, that is the half-center oscillator, and the net can carry rhythm.
+It is still owner-local: an owner reads only its own adaptation. It is off by default, and
+a lane that turns it on says how it chose the two numbers.
+
+## Why sparsity gates the gain
+
+Raise the gain enough and any wiring runs away: a large fraction of owners saturate and
+every readout lights. In that regime a protocol passes for reasons that have nothing to do
+with the wiring, and a shuffled control passes just as well. So a gain is admissible only
+while the net stays sparse under the training stimuli. The cap is declared, the table of
+gains tried is recorded, and the same rule is applied to the control.
+
+## Why float64
+
+Owners sit on knife edges. In the fly brain, one motor neuron under one taste settled to
+1.0 in one run and to 0.01 in another with the same wiring and clamp, because float32
+summation order differed. Receipts are made on the float64 CPU backend for that reason.
+Accelerated backends are for looking, and they come with a conformance number.
+
+## Why a shuffled control
+
+A protocol scored on a wiring alone measures the protocol as much as the wiring. The
+control keeps everything about the wiring that is not the wiring: every count, every sign,
+every owner's out-degree, every named set; only who talks to whom is destroyed. What the
+wiring passes and the control fails is what the wiring predicted.
+
+## Why receipts
+
+Numbers in a notebook rot. A receipt is canonical JSON with its own digest, the digests of
+the code and data that produced it, and enough stored readings that every pass flag can be
+recomputed by the verifier. Editing any source file the receipt names invalidates it, on
+purpose: a result belongs to the code that made it.
+
+## What Cadence does not claim
+
+Settling a measured wiring and passing held-out facts is evidence that the wiring carries
+those facts under this rule. It is not a claim about biology beyond the scored predicates,
+and nothing in the library ascribes experience to anything.

cadence_net-0.1.0/docs/quickstart.md

@@ -0,0 +1,139 @@
+# Quickstart: a measured wiring, a held-out test, a receipt
+
+This walks the whole loop on a wiring you build yourself, then shows the same calls on a
+connectome edge list. Everything runs on the NumPy backend; add `backend="torch"` for a GPU.
+
+## 1. Build a wiring
+
+```python
+import numpy as np
+import cadence as cd
+
+rng = np.random.default_rng(0)
+n, e = 200, 1500
+w = cd.Wiring.from_edges(
+    n,
+    pre=rng.integers(0, n, e),
+    post=rng.integers(0, n, e),
+    count=rng.integers(5, 40, e),                 # contacts per overlap
+    sign=np.where(rng.random(e) < 0.3, -1.0, 1.0), # 30% inhibitory
+    sets={"sensors": range(0, 10), "motors": range(190, 200)},
+    min_count=5,                                   # drop weak overlaps, as connectomes do
+)
+w.summary()
+```
+
+`Wiring` sorts overlaps by (post, pre), merges parallel ones, drops autapses, and digests
+itself. Sets are tuples of owner rows and travel with the wiring, so protocols speak in names.
+
+## 2. Settle it
+
+```python
+rule = cd.GradedRule(gain=0.02)                 # drive per contact per unit activation
+engine = cd.Settlement(w, rule)
+state = engine.settle(w.members("sensors"), steps=60, trajectory=True)
+state.mean(w.sets["motors"]), state.active(), state.trajectory.shape
+```
+
+Rest is an exact fixed point: with no clamp nothing fires. The activation is a sigmoid
+re-based to emit zero at rest, so a quiet net stays quiet.
+
+## 3. Declare what you will test
+
+```python
+protocol = cd.Protocol(
+    stimuli={"rest": (), "touch": ("sensors",)},
+    training=[("touch", "motors", "active")],           # the one fact the model may see
+    rows=[
+        cd.Row("R1", "rest", "motors", "inactive", "no input, no output"),
+        cd.Row("R2", "touch", "motors", "reduced", "cutting the sensors", ablate=("sensors",)),
+    ],
+)
+```
+
+Predicates carry preconditions: `reduced` requires the intact net to have been active, so a
+dead net cannot pass it.
+
+## 4. Select the gain on the training fact, under a sparsity cap
+
+```python
+gain, table = cd.select_gain(
+    lambda g: cd.Settlement(w, rule.replace(gain=g)), protocol, grid=(0.01, 0.02, 0.03, 0.05),
+)
+engine = cd.Settlement(w, rule.replace(gain=gain))
+```
+
+A gain is admissible only while at most 5% of owners are active under the training
+stimuli; pass `sparsity_cap=None` for toy nets that are meant to light entirely. Above the
+cap the net runs away and every readout lights, which says nothing about the wiring. The
+table records every gain tried.
+
+## 5. Score, and score the control
+
+```python
+report = protocol.score(engine)
+control = protocol.score(cd.Settlement(cd.shuffled(w, seed=0), rule.replace(gain=gain)))
+report["passed"], control["passed"]
+```
+
+`shuffled` permutes postsynaptic endpoints and keeps every count, sign, out-degree, and
+named set. If the wiring passes what the control does not, the prediction came from the
+wiring.
+
+## 6. Certify the engine
+
+```python
+cd.conformance(engine, w.members("sensors"), steps=60)
+# {'backend': 'cpu', 'max_abs_deviation': 1e-15, 'ledger': {'clean': True, ...}, ...}
+```
+
+The reference engine reads one owner and its inbox slice at a time and counts one delivery
+per declared overlap per step. Run this on the torch backend too, and record the number.
+
+## 7. Write the receipt
+
+```python
+from pathlib import Path
+
+receipt = cd.Receipt.build(
+    "quickstart/v1",
+    {
+        "wiring": w.summary(),
+        "rule": engine.rule.to_dict(),
+        "gain_selection": {"selected": gain, "table": table},
+        "protocol": protocol.to_dict(),
+        "score": report,
+        "control": control,
+        "conformance": cd.conformance(engine, w.members("sensors")),
+    },
+    sources=[("quickstart.py", Path(__file__))] if "__file__" in globals() else [],
+)
+receipt.write(Path("receipt.json"))
+
+def check(body):
+    for row in body["score"]["rows"]:
+        if row["passed"] != cd.evaluate_predicate(row["predicate"], row["reading"], row["reference"]):
+            return f"row {row['id']} pass flag does not follow from its readings"
+    return None
+
+cd.Receipt.verify(Path("receipt.json"), check=check)
+```
+
+## The same calls on a connectome
+
+A connectome is an edge list with a synapse count and a presynaptic sign. Pin the file,
+fetch it once, verify it always, and build the wiring the same way.
+
+```python
+src = cd.Source(
+    key="edges", file="edges.csv", url="https://example.org/edges.csv",
+    sha256="<64 hex chars>", citation="Who measured it, where it was published",
+)
+paths = cd.fetch([src], root=Path("data"), allow_download=True)
+pre, post, count, sign = load_your_csv(paths["edges"])   # your parser
+w = cd.Wiring.from_edges(n_neurons, pre=pre, post=post, count=count, sign=sign, min_count=5,
+                         sets={"sugar_grn": [...], "mn9": [...]})
+```
+
+From there the protocol, the control, the conformance check, and the receipt are the
+same six calls, with `cd.manifest([src])` embedded in the receipt body as custody.

cadence_net-0.1.0/docs/receipts.md

@@ -0,0 +1,47 @@
+# Receipts
+
+A receipt is a result that can be checked by someone who was not there.
+
+## Shape
+
+```json
+{
+  "kind": "my-lane/v1",
+  "body": { "...": "whatever the lane recorded: readings, rows, gain tables, custody" },
+  "source": { "files": [{"path": "lane.py", "sha256": "..."}], "manifest_sha256": "..." },
+  "digest": "sha256 of the canonical JSON of kind, body, and source"
+}
+```
+
+Written as newline-terminated canonical JSON: sorted keys, no whitespace, no NaN.
+
+## Verification
+
+`Receipt.verify(path, sources=..., check=...)` recomputes four things and fails on the first
+that disagrees:
+
+1. the file is byte-for-byte the canonical form of its own content;
+2. the embedded digest matches;
+3. the source files named in the manifest still hash to what the receipt says;
+4. the caller's `check(body)` finds no arithmetic problem, which for a protocol receipt
+   means every pass flag follows from the stored readings and every tally follows from
+   the rows.
+
+## What belongs in the body
+
+- the wiring summary and digest, and the custody block for measured data;
+- the rule and the engine description;
+- the gain selection table, every gain tried, with its admissibility;
+- the protocol as data, including the reference for every row;
+- the score, with readings and reference readings on every row;
+- the control's score;
+- the conformance report for the backend used;
+- an explicit boundary block: what the lane declares rather than derives, and what it does
+  not claim.
+
+## Editing invalidates, on purpose
+
+Every file named in the source manifest is bound to the receipt. Change one line in the
+lane and the receipt no longer verifies until the lane is re-run. Batch edits, then re-run
+once. When several lanes share a module, an edit to that module re-runs all of them; plan
+it as a versioned break and record the library version in the body.

cadence_net-0.1.0/examples/half_center.py

@@ -0,0 +1,29 @@
+"""Two owners that inhibit each other: a fixed point without adaptation, a rhythm with it.
+
+Run:  python examples/half_center.py
+"""
+
+from __future__ import annotations
+
+import cadence as cd
+
+wiring = cd.Wiring.from_edges(2, pre=[0, 1], post=[1, 0], count=[60, 60], sign=[-1, -1])
+clamp = {0: 1.0, 1: 0.95}  # both driven, one a little harder
+
+still = cd.Settlement(wiring, cd.GradedRule(gain=0.03)).settle(clamp, steps=400, trajectory=True)
+rhythm = cd.Settlement(
+    wiring, cd.GradedRule(gain=0.03, adaptation=cd.Adaptation(tau_steps=40, strength=2.0))
+).settle(clamp, steps=400, trajectory=True)
+
+assert still.trajectory is not None and rhythm.trajectory is not None
+print(
+    "without adaptation, last 100 steps, std per owner:",
+    still.trajectory[-100:].std(axis=0).round(4),
+)
+print(
+    "with adaptation,    last 200 steps, std per owner:",
+    rhythm.trajectory[-200:].std(axis=0).round(3),
+)
+for t in range(300, 400, 10):
+    bar = "".join("#" if x > 0.5 else "." for x in rhythm.trajectory[t])
+    print(f"step {t}: {bar}  {rhythm.trajectory[t].round(2)}")