loopmarket 0.1.0__tar.gz

loopmarket-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Peter Foldiak
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

loopmarket-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: loopmarket
+Version: 0.1.0
+Summary: Universal combinatorial marketplace: uniform offers over an OntoDAG catalogue, a versioned offer book on recordstore/Swarm, and solver agents hunting profitable loops
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/petfold/loopmarket
+Project-URL: Repository, https://github.com/petfold/loopmarket
+Project-URL: Issues, https://github.com/petfold/loopmarket/issues
+Keywords: marketplace,combinatorial-exchange,ontology,dag,subsumption,swarm,web3,decentralized,solver,negative-cycle,barter,mutual-credit,coincidence-of-wants
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ontodag>=0.13.0
+Requires-Dist: recordstore>=0.16.0
+Provides-Extra: swarm
+Requires-Dist: recordstore[bee,feeds]>=0.16.0; extra == "swarm"
+Provides-Extra: sig
+Requires-Dist: eth-keys; extra == "sig"
+Requires-Dist: eth-hash[pycryptodome]; extra == "sig"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# loopmarket
+
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+
+A universal combinatorial marketplace over the
+[ontodag](https://github.com/petfold/ontodag) /
+[recordstore](https://github.com/petfold/recordstore) /
+[Ethereum Swarm](https://www.ethswarm.org/) stack.
+
+Every economic intention is one uniform, content-addressed **offer** — a
+thing described as a conjunction of OntoDAG categories, with a service time
+window and region, priced on the maker's **personal scale** (a personal
+numeraire; the record encoding calls it the maker's personal token). A
+distributed, versioned **offer book** holds them (recordstore keyspace;
+Swarm-backed via `BeeBytesStore` + a signed `SwarmFeedPointer`). Competing
+**solver agents** hunt profitable **loops** — cycles whose exchange-rate
+product exceeds one, i.e. negative cycles under −log weights — and a
+**clearing** layer re-verifies every leg from scratch and commits the
+whole loop atomically.
+
+```python
+from recordstore import MemoryBytesStore, RecordStore
+from loopmarket import (Ontology, OfferRegistry, MockClearing,
+                        SolverAgent, Thing, give, want, ...)
+
+ontology = Ontology().load({"produce": [], "vegetable-box": ["produce"], ...})
+registry = OfferRegistry(RecordStore(MemoryBytesStore()))
+registry.publish_many([...])          # gives and wants, one uniform form
+registry.commit()
+
+agent = SolverAgent(registry, ontology, MockClearing(registry, ontology))
+agent.step()                          # snapshot → match → hunt loops → clear
+```
+
+## Try it
+
+```bash
+pip install -e ".[test]"              # (--break-system-packages or a venv)
+python3 -m pytest tests/ -v           # 59 tests (two need a live Bee node)
+PYTHONPATH=src python3 examples/demo_triangle.py     # P0 in one file
+PYTHONPATH=src python3 examples/demo_federation.py   # P1: books, fold, forgery, follower
+```
+
+The first demo publishes the smallest nontrivial book — a piano teacher, a
+market gardener and a bicycle mechanic, no pair of whom can trade — and
+watches the solver find, verify and clear the triangle at a 12% surplus.
+The second runs the federation: per-maker books, two aggregators folding
+to byte-identical manifests, a forged offer dying at the fold, a
+tombstoned offer staying closed, clearing provably based on the fold,
+and a follower reading it all back — in memory by default, live against a
+Bee node when `BEE_API` and `BEE_BATCH` are set. New here? Start with the
+**[User Guide](docs/USER-GUIDE.md)** (tutorial) and the
+**[Reference Manual](docs/REFERENCE.md)** (API, record formats,
+invariants).
+
+Candidate generation can also run through ontodag's **parametric
+dimensions**: `DimensionIndex` files gives under their exact service window
+and centre cell, and `candidate_matches_indexed` prunes by concept cones
+and window overlap — provably the same matches as the exhaustive baseline
+(the recall test enforces set-equality), with far fewer exact checks. The
+index is a derived, per-solver copy; the shared catalogue and its pinned
+roots never move because of it. Swap the in-memory store for
+`recordstore.swarm_store("offers", signer=...)` (extra:
+`pip install -e ".[swarm]"`, plus a Bee node and a postage batch) and the
+same code runs with the book on Swarm.
+
+## What is built, and what is designed
+
+**Built (P0, plus the live-Swarm milestone):** the full pipeline above runs
+in memory, and since 2026-08-01 also end-to-end on a real Gnosis-mainnet
+Bee node — catalogue and book on Swarm, book head in a signed feed, fills
+atomic (the gated `tests/test_swarm_book.py`). Since 2026-08-21 the
+federation layer runs too — in memory *and* live (the gated
+`tests/test_swarm_federation.py`, 96.5s on a Bee 2.8.1 node): per-maker
+books under their own feeds and signers, an `Aggregator` folding them
+under the U8 admission rules into a four-root manifest published on its
+own feed, withdrawal tombstones, and a scorched-earth follower
+reconstructing the cleared world from (address, topic) alone. Since
+2026-09-04 the federation demo adopts ontodag's `core` pack as the
+catalogue and includes a censoring aggregator: `audit_manifest` convicts
+it from its own manifest with absence proofs, and a solver folding the
+announced maker books itself recovers the honest fold (T14).
+Alpha; interfaces will move.
+
+**Designed (2026-08-07):** most of what loopmarket *is* now lives as a
+decided, research-grounded plan corpus under `docs/plans/` — one document
+per work package, each with measurable gates, named open problems, and a
+closing "what this document does not promise" section. Anything implying
+unbuilt code carries a dated marker ("decided 2026-08, lands with the v2
+bump / P1 / P2"). Planned invariants **U8–U14** are specified in the
+documents that motivate them and summarized across `ARCHITECTURE.md`'s
+update notes and §11; they enter `CLAUDE.md` as binding invariants only
+when their enforcing code and tests land. factbond's mirror corpus is
+`factbond/docs/plans/`.
+
+## Vocabulary
+
+Three words carry the design and are used precisely since 2026-09-07:
+
+- **loop** — any cleared circulation: the essay's word and the name in code (`Loop`, `LoopProposal`, `loop/`, `loop_id`).
+- **cycle** (simple loop) — the strict circle; all the P0 solver finds, and the only case where "the product of rates around it" means anything.
+- **circulation** — the technical name for the cleared object: a flow conserved at every maker on that maker's own scale, with composed legs where one want takes several gives (`docs/plans/P2-loop-selection.md` §10–11).
+- **hyper-leg** — a composed leg: several givers as tails, one wanting maker as head, one flow variable, so it fills every tail or none. The maker graph with hyper-legs is a hypergraph; its flow is an LP for divisible legs and an ILP where a hyper-leg is all-or-nothing.
+
+And two more: **clearing** is the atomic commit that fixes obligations; **settlement** is the makers delivering.
+
+## The plan corpus
+
+| Document | One line |
+|---|---|
+| [`P1-federated-book.md`](docs/plans/P1-federated-book.md) | Per-maker books under own feeds/signers; announcement, aggregation, merge discipline, lifecycle, postage economics, spam floors. |
+| [`P2-batch-auction.md`](docs/plans/P2-batch-auction.md) | The beat: sealed proposals, numeraire-free scoring, the fairness floor, capped solver rewards, collusion resistance, fees. |
+| [`P2-clearing-pricing.md`](docs/plans/P2-clearing-pricing.md) | Turning a winning loop's surplus into per-leg prices: equal log-surplus split under uniform directional clearing; clearing prices as node potentials (§10). |
+| [`P2-loop-selection.md`](docs/plans/P2-loop-selection.md) | Clearing as optimization: flow LP vs packing ILP, chains, failure-aware objective, pre-commit compression; composition on the want side (§10); the cleared object is a circulation, clearing prices its node potentials (§11). |
+| [`proof-fabric.md`](docs/plans/proof-fabric.md) | Cross-phase proofs and certificates: trie proofs vs POT, the pin table, certificate envelopes, absence proofs. |
+| [`P3-guarantee-coupling.md`](docs/plans/P3-guarantee-coupling.md) | loopmarket's half of the factbond coupling: witness edges, reliance-capped insurance, oracle consumption, risk-priced routing. |
+| [`P4-privacy.md`](docs/plans/P4-privacy.md) | Staged privacy: Tier 1 with zero new cryptography, the P2 format-freeze list, explicit dead/deferred rulings. |
+| [`ontodag-coupling.md`](docs/plans/ontodag-coupling.md) | The catalogue contract: dimension terms, unit families, match degrees, the upstream-vs-local tripwire table. |
+| [`catalogue-bootstrap.md`](docs/plans/catalogue-bootstrap.md) | Seeding and governing the shared catalogue: seed taxonomies, the import pipeline, norms as protocol rules. |
+| [`adoption-and-thickness.md`](docs/plans/adoption-and-thickness.md) | Where the first loops come from: launch verticals, the broker surface, bridge liquidity, thickness engineering. |
+| [`THREATS.md`](docs/plans/THREATS.md) | The threat register, T1–T9, ordered by expected damage to a young system; mirrored in factbond. |
+| [swarm-da](https://github.com/petfold/swarm-da) (separate repo) | Memo, 2026-09-09: what building this book on Swarm taught about Swarm as a data-availability layer — the archival-DA opportunity, Bee's push-sync receipts as the half-built publication primitive, and what loopmarket sheds the day they are exposed and anchored. |
+
+**Phase ↔ document map.** P1 (federation): `P1-federated-book.md`,
+supported by `ontodag-coupling.md` and `catalogue-bootstrap.md`. P2
+(verifiable clearing): the three P2 docs plus `proof-fabric.md`,
+*constrained* by `P4-privacy.md`'s format-freeze list and gated by
+`THREATS.md` tripwires. P3 (guarantee fabric): `P3-guarantee-coupling.md`
+plus factbond's entire corpus — gated by factbond's Phase-0 simulation
+going green *and* the P2 format freeze. P4 (privacy): `P4-privacy.md`,
+whose Tier 1 may ship alongside P2. Cross-phase: `proof-fabric.md`,
+`THREATS.md`, `adoption-and-thickness.md`, `catalogue-bootstrap.md`,
+`ontodag-coupling.md`.
+
+**Reading order.** First pass: `ARCHITECTURE.md` → `THREATS.md` →
+`P1-federated-book.md`. Clearing track: `P2-loop-selection.md` →
+`P2-clearing-pricing.md` → `P2-batch-auction.md` → `proof-fabric.md`.
+Guarantee track: factbond `DESIGN.md` → `mechanism-design.md` →
+`insurance-products.md` → `phase0-simulation.md` →
+`P3-guarantee-coupling.md`. Market track: `adoption-and-thickness.md` →
+`catalogue-bootstrap.md` → `ontodag-coupling.md`.
+
+Order of documents is not order of construction — gates decide that; and a
+document's existence proves nothing about feasibility. The Phase-0
+simulation and the named empirical gates can kill designs recorded here;
+the corpus is built so that they can.
+
+## Documentation
+
+- **[docs/USER-GUIDE.md](docs/USER-GUIDE.md)** — the tutorial: from your
+  first offer to a federated book on a live Swarm network, every snippet
+  runnable.
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — the reference manual:
+  every public class and function, the keyspace, record formats,
+  invariants, environment.
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — the design and its rationale:
+  the uniform offer form, time/place as fits-within dimensions, the book's
+  keyspace and multi-writer story, the loop arithmetic (and why prices are
+  never negative), the trust model, the proof fabric, economic security,
+  and what the architecture does not promise.
+- **[ROADMAP.md](ROADMAP.md)** — the phase index with status:
+  P0 (built) → P1 (federated book, live since 2026-08-21) → P2 (verifiable
+  clearing, batch auctions) → P3 (guarantee fabric via factbond) →
+  P4 (privacy), each linking to its plan document.
+- **[CLAUDE.md](CLAUDE.md)** — working rules for development: dependency
+  boundaries, core invariants U1–U7, known simplifications.
+- **[docs/loop-economy.md](docs/loop-economy.md)** — the vision essay: the
+  loop economy, its gallery of loops, the solver ecology, judges without
+  swords, and the path in.

loopmarket-0.1.0/README.md

@@ -0,0 +1,169 @@
+# loopmarket
+
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+
+A universal combinatorial marketplace over the
+[ontodag](https://github.com/petfold/ontodag) /
+[recordstore](https://github.com/petfold/recordstore) /
+[Ethereum Swarm](https://www.ethswarm.org/) stack.
+
+Every economic intention is one uniform, content-addressed **offer** — a
+thing described as a conjunction of OntoDAG categories, with a service time
+window and region, priced on the maker's **personal scale** (a personal
+numeraire; the record encoding calls it the maker's personal token). A
+distributed, versioned **offer book** holds them (recordstore keyspace;
+Swarm-backed via `BeeBytesStore` + a signed `SwarmFeedPointer`). Competing
+**solver agents** hunt profitable **loops** — cycles whose exchange-rate
+product exceeds one, i.e. negative cycles under −log weights — and a
+**clearing** layer re-verifies every leg from scratch and commits the
+whole loop atomically.
+
+```python
+from recordstore import MemoryBytesStore, RecordStore
+from loopmarket import (Ontology, OfferRegistry, MockClearing,
+                        SolverAgent, Thing, give, want, ...)
+
+ontology = Ontology().load({"produce": [], "vegetable-box": ["produce"], ...})
+registry = OfferRegistry(RecordStore(MemoryBytesStore()))
+registry.publish_many([...])          # gives and wants, one uniform form
+registry.commit()
+
+agent = SolverAgent(registry, ontology, MockClearing(registry, ontology))
+agent.step()                          # snapshot → match → hunt loops → clear
+```
+
+## Try it
+
+```bash
+pip install -e ".[test]"              # (--break-system-packages or a venv)
+python3 -m pytest tests/ -v           # 59 tests (two need a live Bee node)
+PYTHONPATH=src python3 examples/demo_triangle.py     # P0 in one file
+PYTHONPATH=src python3 examples/demo_federation.py   # P1: books, fold, forgery, follower
+```
+
+The first demo publishes the smallest nontrivial book — a piano teacher, a
+market gardener and a bicycle mechanic, no pair of whom can trade — and
+watches the solver find, verify and clear the triangle at a 12% surplus.
+The second runs the federation: per-maker books, two aggregators folding
+to byte-identical manifests, a forged offer dying at the fold, a
+tombstoned offer staying closed, clearing provably based on the fold,
+and a follower reading it all back — in memory by default, live against a
+Bee node when `BEE_API` and `BEE_BATCH` are set. New here? Start with the
+**[User Guide](docs/USER-GUIDE.md)** (tutorial) and the
+**[Reference Manual](docs/REFERENCE.md)** (API, record formats,
+invariants).
+
+Candidate generation can also run through ontodag's **parametric
+dimensions**: `DimensionIndex` files gives under their exact service window
+and centre cell, and `candidate_matches_indexed` prunes by concept cones
+and window overlap — provably the same matches as the exhaustive baseline
+(the recall test enforces set-equality), with far fewer exact checks. The
+index is a derived, per-solver copy; the shared catalogue and its pinned
+roots never move because of it. Swap the in-memory store for
+`recordstore.swarm_store("offers", signer=...)` (extra:
+`pip install -e ".[swarm]"`, plus a Bee node and a postage batch) and the
+same code runs with the book on Swarm.
+
+## What is built, and what is designed
+
+**Built (P0, plus the live-Swarm milestone):** the full pipeline above runs
+in memory, and since 2026-08-01 also end-to-end on a real Gnosis-mainnet
+Bee node — catalogue and book on Swarm, book head in a signed feed, fills
+atomic (the gated `tests/test_swarm_book.py`). Since 2026-08-21 the
+federation layer runs too — in memory *and* live (the gated
+`tests/test_swarm_federation.py`, 96.5s on a Bee 2.8.1 node): per-maker
+books under their own feeds and signers, an `Aggregator` folding them
+under the U8 admission rules into a four-root manifest published on its
+own feed, withdrawal tombstones, and a scorched-earth follower
+reconstructing the cleared world from (address, topic) alone. Since
+2026-09-04 the federation demo adopts ontodag's `core` pack as the
+catalogue and includes a censoring aggregator: `audit_manifest` convicts
+it from its own manifest with absence proofs, and a solver folding the
+announced maker books itself recovers the honest fold (T14).
+Alpha; interfaces will move.
+
+**Designed (2026-08-07):** most of what loopmarket *is* now lives as a
+decided, research-grounded plan corpus under `docs/plans/` — one document
+per work package, each with measurable gates, named open problems, and a
+closing "what this document does not promise" section. Anything implying
+unbuilt code carries a dated marker ("decided 2026-08, lands with the v2
+bump / P1 / P2"). Planned invariants **U8–U14** are specified in the
+documents that motivate them and summarized across `ARCHITECTURE.md`'s
+update notes and §11; they enter `CLAUDE.md` as binding invariants only
+when their enforcing code and tests land. factbond's mirror corpus is
+`factbond/docs/plans/`.
+
+## Vocabulary
+
+Three words carry the design and are used precisely since 2026-09-07:
+
+- **loop** — any cleared circulation: the essay's word and the name in code (`Loop`, `LoopProposal`, `loop/`, `loop_id`).
+- **cycle** (simple loop) — the strict circle; all the P0 solver finds, and the only case where "the product of rates around it" means anything.
+- **circulation** — the technical name for the cleared object: a flow conserved at every maker on that maker's own scale, with composed legs where one want takes several gives (`docs/plans/P2-loop-selection.md` §10–11).
+- **hyper-leg** — a composed leg: several givers as tails, one wanting maker as head, one flow variable, so it fills every tail or none. The maker graph with hyper-legs is a hypergraph; its flow is an LP for divisible legs and an ILP where a hyper-leg is all-or-nothing.
+
+And two more: **clearing** is the atomic commit that fixes obligations; **settlement** is the makers delivering.
+
+## The plan corpus
+
+| Document | One line |
+|---|---|
+| [`P1-federated-book.md`](docs/plans/P1-federated-book.md) | Per-maker books under own feeds/signers; announcement, aggregation, merge discipline, lifecycle, postage economics, spam floors. |
+| [`P2-batch-auction.md`](docs/plans/P2-batch-auction.md) | The beat: sealed proposals, numeraire-free scoring, the fairness floor, capped solver rewards, collusion resistance, fees. |
+| [`P2-clearing-pricing.md`](docs/plans/P2-clearing-pricing.md) | Turning a winning loop's surplus into per-leg prices: equal log-surplus split under uniform directional clearing; clearing prices as node potentials (§10). |
+| [`P2-loop-selection.md`](docs/plans/P2-loop-selection.md) | Clearing as optimization: flow LP vs packing ILP, chains, failure-aware objective, pre-commit compression; composition on the want side (§10); the cleared object is a circulation, clearing prices its node potentials (§11). |
+| [`proof-fabric.md`](docs/plans/proof-fabric.md) | Cross-phase proofs and certificates: trie proofs vs POT, the pin table, certificate envelopes, absence proofs. |
+| [`P3-guarantee-coupling.md`](docs/plans/P3-guarantee-coupling.md) | loopmarket's half of the factbond coupling: witness edges, reliance-capped insurance, oracle consumption, risk-priced routing. |
+| [`P4-privacy.md`](docs/plans/P4-privacy.md) | Staged privacy: Tier 1 with zero new cryptography, the P2 format-freeze list, explicit dead/deferred rulings. |
+| [`ontodag-coupling.md`](docs/plans/ontodag-coupling.md) | The catalogue contract: dimension terms, unit families, match degrees, the upstream-vs-local tripwire table. |
+| [`catalogue-bootstrap.md`](docs/plans/catalogue-bootstrap.md) | Seeding and governing the shared catalogue: seed taxonomies, the import pipeline, norms as protocol rules. |
+| [`adoption-and-thickness.md`](docs/plans/adoption-and-thickness.md) | Where the first loops come from: launch verticals, the broker surface, bridge liquidity, thickness engineering. |
+| [`THREATS.md`](docs/plans/THREATS.md) | The threat register, T1–T9, ordered by expected damage to a young system; mirrored in factbond. |
+| [swarm-da](https://github.com/petfold/swarm-da) (separate repo) | Memo, 2026-09-09: what building this book on Swarm taught about Swarm as a data-availability layer — the archival-DA opportunity, Bee's push-sync receipts as the half-built publication primitive, and what loopmarket sheds the day they are exposed and anchored. |
+
+**Phase ↔ document map.** P1 (federation): `P1-federated-book.md`,
+supported by `ontodag-coupling.md` and `catalogue-bootstrap.md`. P2
+(verifiable clearing): the three P2 docs plus `proof-fabric.md`,
+*constrained* by `P4-privacy.md`'s format-freeze list and gated by
+`THREATS.md` tripwires. P3 (guarantee fabric): `P3-guarantee-coupling.md`
+plus factbond's entire corpus — gated by factbond's Phase-0 simulation
+going green *and* the P2 format freeze. P4 (privacy): `P4-privacy.md`,
+whose Tier 1 may ship alongside P2. Cross-phase: `proof-fabric.md`,
+`THREATS.md`, `adoption-and-thickness.md`, `catalogue-bootstrap.md`,
+`ontodag-coupling.md`.
+
+**Reading order.** First pass: `ARCHITECTURE.md` → `THREATS.md` →
+`P1-federated-book.md`. Clearing track: `P2-loop-selection.md` →
+`P2-clearing-pricing.md` → `P2-batch-auction.md` → `proof-fabric.md`.
+Guarantee track: factbond `DESIGN.md` → `mechanism-design.md` →
+`insurance-products.md` → `phase0-simulation.md` →
+`P3-guarantee-coupling.md`. Market track: `adoption-and-thickness.md` →
+`catalogue-bootstrap.md` → `ontodag-coupling.md`.
+
+Order of documents is not order of construction — gates decide that; and a
+document's existence proves nothing about feasibility. The Phase-0
+simulation and the named empirical gates can kill designs recorded here;
+the corpus is built so that they can.
+
+## Documentation
+
+- **[docs/USER-GUIDE.md](docs/USER-GUIDE.md)** — the tutorial: from your
+  first offer to a federated book on a live Swarm network, every snippet
+  runnable.
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — the reference manual:
+  every public class and function, the keyspace, record formats,
+  invariants, environment.
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — the design and its rationale:
+  the uniform offer form, time/place as fits-within dimensions, the book's
+  keyspace and multi-writer story, the loop arithmetic (and why prices are
+  never negative), the trust model, the proof fabric, economic security,
+  and what the architecture does not promise.
+- **[ROADMAP.md](ROADMAP.md)** — the phase index with status:
+  P0 (built) → P1 (federated book, live since 2026-08-21) → P2 (verifiable
+  clearing, batch auctions) → P3 (guarantee fabric via factbond) →
+  P4 (privacy), each linking to its plan document.
+- **[CLAUDE.md](CLAUDE.md)** — working rules for development: dependency
+  boundaries, core invariants U1–U7, known simplifications.
+- **[docs/loop-economy.md](docs/loop-economy.md)** — the vision essay: the
+  loop economy, its gallery of loops, the solver ecology, judges without
+  swords, and the path in.

loopmarket-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "loopmarket"
+version = "0.1.0"
+description = "Universal combinatorial marketplace: uniform offers over an OntoDAG catalogue, a versioned offer book on recordstore/Swarm, and solver agents hunting profitable loops"
+readme = "README.md"
+license = { text = "BSD-3-Clause" }
+requires-python = ">=3.11"
+keywords = [
+    "marketplace", "combinatorial-exchange", "ontology", "dag", "subsumption",
+    "swarm", "web3", "decentralized", "solver", "negative-cycle", "barter",
+    "mutual-credit", "coincidence-of-wants",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "ontodag>=0.13.0",        # catalogue: subsumption, dimensions, is_below
+    "recordstore>=0.16.0",   # the book: canonical versioned KV, merge, snapshots,
+                             # diff/merge_delta (O(divergence) folds), prove/verify_proof
+]
+
+[project.optional-dependencies]
+# The Swarm deployment path: BeeBytesStore blobs + signed SwarmFeedPointer
+# head, both reached through recordstore so versions stay in step with it
+# (mirrors ontodag's own [swarm] extra).
+swarm = ["recordstore[bee,feeds]>=0.16.0"]
+# Detached offer signatures (U8's off-feed layer): the same secp256k1
+# identity that owns the maker's feed, recoverable without a node.
+sig = ["eth-keys", "eth-hash[pycryptodome]"]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/petfold/loopmarket"
+Repository = "https://github.com/petfold/loopmarket"
+Issues = "https://github.com/petfold/loopmarket/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

loopmarket-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loopmarket-0.1.0/src/loopmarket/__init__.py

@@ -0,0 +1,43 @@
+"""loopmarket — a universal combinatorial marketplace over OntoDAG + recordstore + Swarm.
+
+One uniform offer form; a shared OntoDAG catalogue in which meanings, minutes
+and map regions are ordered by the same fits-within relation; a distributed,
+versioned offer book over recordstore (Swarm-backed via BeeBytesStore +
+SwarmFeedPointer); competing solver agents hunting profitable loops as
+negative cycles; clearing that re-verifies everything and trusts no one.
+
+Dependency direction (boundary B2, enforced by tests/test_boundaries.py):
+
+    loopmarket  ->  ontodag  ->  recordstore  ->  (Swarm, optional)
+
+The core imports work with no network and no Bee node (boundary B1); Swarm
+is a persistence backend chosen at the edges (registry.swarm_offer_book,
+Ontology.persistent over a swarm_store), never a requirement of the model.
+"""
+
+from .schema import (
+    ASK, BID, GIVE, WANT, GeoDisc, Offer, Thing, TimeWindow, Tokens,
+    ask, bid, give, want,
+)
+from .federation import Aggregator, Manifest, Omission, audit_manifest
+from .ontology import Ontology
+from .registry import OfferRegistry, PartialLoopError, swarm_offer_book
+from .matching import Match, candidate_matches, check_match
+from .sigs import maker_address, recover_maker, sign_offer, verify_offer_sig
+from .dimensions import DimensionIndex, candidate_matches_indexed
+from .graph import ExchangeGraph, Loop
+from .clearing import LoopProposal, MockClearing, Receipt, Clearing
+from .solver.agent import SolverAgent
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GIVE", "WANT", "ASK", "BID", "GeoDisc", "Offer", "Thing", "TimeWindow",
+    "Tokens", "give", "want", "ask", "bid",
+    "Aggregator", "Manifest", "Omission", "audit_manifest", "Ontology", "OfferRegistry",
+    "PartialLoopError", "swarm_offer_book",
+    "Match", "candidate_matches", "check_match",
+    "maker_address", "recover_maker", "sign_offer", "verify_offer_sig",
+    "DimensionIndex", "candidate_matches_indexed", "ExchangeGraph", "Loop",
+    "LoopProposal", "MockClearing", "Receipt", "Clearing", "SolverAgent",
+]

loopmarket-0.1.0/src/loopmarket/clearing.py

@@ -0,0 +1,147 @@
+"""Clearing: where a proposed loop becomes a bundle of commitments.
+
+Trust model (the one non-negotiable): clearing *never trusts the solver*.
+A `LoopProposal` names the book root and ontology root it was solved
+against; the clearing layer re-derives every leg with `check_match`, the
+chaining, the product, and the not-already-filled status — cheap, linear in
+the loop — before atomically marking every offer filled. Discovery is
+expensive and competitive; verification is cheap and neutral.
+
+`MockClearing` is the in-process stand-in: its "atomic stroke" is one
+recordstore commit (all fills + the loop record land under a single new
+root, or none do). The on-chain path it stands in for (roadmap P2) keeps
+the same interface: a contract receives the loop plus *inclusion proofs*
+that each offer is present under the pinned book root — recordstore's
+canonical-trie `prove`/`verify_proof` (>= 0.16.0) is the primary route;
+POT ForkPathProof is the conditional fallback only if the on-chain
+verifier demands BMT-native proofs (docs/plans/proof-fabric.md). Batch
+auctions across competing sealed proposals are P2 as well
+(docs/plans/P2-batch-auction.md); the mock is first-valid-wins.
+"""
+
+from __future__ import annotations
+
+import time as _time
+from dataclasses import dataclass
+from typing import Protocol
+
+from .graph import Loop
+from .matching import check_match
+from .ontology import Ontology
+from .registry import OfferRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class LoopProposal:
+    loop: Loop
+    book_root: str        # the registry version the loop was solved against
+    ontology_root: str    # the catalogue version subsumption was checked under
+    solver: str           # who found it (fee/reputation address)
+    found_at: int
+
+    def to_record(self) -> dict:
+        return {
+            "loop_id": self.loop.loop_id,
+            "solver": self.solver,
+            "found_at": self.found_at,
+            "book_root": self.book_root,
+            "ontology_root": self.ontology_root,
+            "surplus": self.loop.surplus,
+            "nodes": list(self.loop.nodes),
+            "legs": [
+                {"give": m.give.offer_id, "want": m.want.offer_id, "rate": m.rate}
+                for m in self.loop.matches
+            ],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Receipt:
+    accepted: bool
+    loop_id: str
+    reason: str = ""
+    book_root: str = ""   # the new root, if accepted
+
+
+class Clearing(Protocol):
+    def submit(self, proposal: LoopProposal) -> Receipt: ...
+
+
+class MockClearing:
+    """In-process clearing over the shared registry."""
+
+    #: Oracle types this clearing knows how to verify — the P3 refusal
+    #: gate (docs/plans/P3-guarantee-coupling.md, enforcement rule 1): a leg
+    #: naming a witness type outside this set never clears here, in U7's
+    #: shape — unknown fails closed rather than silently clearing with a
+    #: guarantee nobody can check. The mock declares exactly the P0
+    #: countersign semantics.
+    VERIFIABLE_ORACLES = frozenset({"countersign"})
+
+    def __init__(self, registry: OfferRegistry, ontology: Ontology, *,
+                 min_surplus: float = 0.0, require_per_node: bool = True,
+                 clock=_time.time, verifiable_oracles=VERIFIABLE_ORACLES):
+        self.registry = registry
+        self.ontology = ontology
+        self.min_surplus = min_surplus
+        self.require_per_node = require_per_node
+        self.clock = clock  # injectable for tests / deterministic replay
+        self.verifiable_oracles = frozenset(verifiable_oracles)
+
+    def submit(self, proposal: LoopProposal) -> Receipt:
+        loop = proposal.loop
+        lid = loop.loop_id
+        now = int(self.clock())
+
+        def reject(reason: str) -> Receipt:
+            return Receipt(False, lid, reason)
+
+        # 0. pins — the rehearsal of U10's clearing half (full enforcement,
+        #    with proofs, lands with P2): the proposal's catalogue pin must
+        #    *equal* this clearing's own, refused before any leg work.
+        #    Plain equality covers mismatch and absence in both directions:
+        #    a pinned clearing refuses unpinned proposals, an unpinned
+        #    (development) one refuses proposals claiming ground it cannot
+        #    confirm; '' == '' keeps the in-memory flow working.
+        if proposal.ontology_root != self.ontology.root:
+            return reject("ontology pin mismatch")
+
+        # 1. every offer must exist in the *current* book, be unfilled, and
+        #    name a witness type this clearing can actually verify
+        seen: set[str] = set()
+        for oid in loop.offer_ids:
+            if oid in seen:
+                return reject(f"offer used twice: {oid[:12]}")
+            seen.add(oid)
+            try:
+                offer = self.registry.get(oid)
+            except KeyError:
+                return reject(f"unknown offer: {oid[:12]}")
+            if self.registry.is_filled(oid):
+                return reject(f"already filled: {oid[:12]}")
+            if self.registry.is_withdrawn(oid):
+                return reject(f"withdrawn: {oid[:12]}")
+            if offer.oracle not in self.verifiable_oracles:
+                return reject(f"unverifiable oracle type: {offer.oracle}")
+
+        # 2. re-derive every leg — never trust the solver's matches
+        for m in loop.matches:
+            fresh_give = self.registry.get(m.give.offer_id)
+            fresh_want = self.registry.get(m.want.offer_id)
+            if check_match(fresh_give, fresh_want, self.ontology, now=now) is None:
+                return reject(
+                    f"leg fails re-verification: {m.give.offer_id[:8]}"
+                    f" -> {m.want.offer_id[:8]}"
+                )
+
+        # 3. the arithmetic
+        if loop.surplus < self.min_surplus - 1e-12:
+            return reject(f"surplus {loop.surplus:.4f} below minimum")
+        if self.require_per_node and not loop.all_divisible \
+                and not loop.per_node_ok:
+            return reject("indivisible legs without per-node surplus")
+
+        # 4. atomic commitment: all fills land under one new root, or none
+        self.registry.mark_filled(loop.offer_ids, lid, proposal.to_record())
+        root = self.registry.commit()
+        return Receipt(True, lid, book_root=root)