diff --git a/docs/TICKETS.md b/docs/TICKETS.md index 69d9bfe..639ce31 100644 --- a/docs/TICKETS.md +++ b/docs/TICKETS.md @@ -57,6 +57,7 @@ Newest first. Update on every open/close. | ID | Title | Status | Opened | Directive | |----------|------------------------------------------------|-----------------------|------------|-----------| +| #000022 | Adapter LossReport (PRD I9 analogue) | open · awaiting go/no-go | 2026-05-07 | — | | #000021 | 5S/5T/5R benchmark fixtures + harness | open · awaiting go/no-go | 2026-05-07 | — | | #000020 | Capital-cost ledger (8-capital queues) | open · awaiting go/no-go | 2026-05-07 | — | | #000019 | Specification methodology for π* and V | open · awaiting go/no-go | 2026-05-07 | — | @@ -81,4 +82,4 @@ Newest first. Update on every open/close. ## Next ID -`000022` +`000023` diff --git a/docs/_source/api/mesh.rst b/docs/_source/api/mesh.rst index 934da7c..8d5a255 100644 --- a/docs/_source/api/mesh.rst +++ b/docs/_source/api/mesh.rst @@ -1,7 +1,13 @@ +.. _federation: + Federation: multiplayer arborist ================================ -Gossip-based mesh for cross-peer data sharing. +Gossip-based mesh for cross-peer data sharing. Arborist peers +that ingest the same source under the same chunker and +canonicalization compute bit-identical ``document_root`` hashes; +the mesh layer is what lets peers exchange and verify each other's +records without a central authority. .. automodule:: arborist.mesh :members: diff --git a/docs/_source/concepts.rst b/docs/_source/concepts.rst index aac6597..ce8c39a 100644 --- a/docs/_source/concepts.rst +++ b/docs/_source/concepts.rst @@ -52,6 +52,20 @@ Arborist uses fox's existing Go Merkle conventions verbatim See :doc:`api/substrate` for the Python port. +Federation across peers +----------------------- + +Identity-by-content is the federation primitive. Two peers that +ingest the same source with the same chunker and canonicalization +compute the same ``document_root`` and the same ``cache_key``; +that property is what lets peers exchange and verify each other's +providence records without a central authority. The mesh layer +implements gossip-based sync, group key management, and per-peer +audit-chain reconciliation on top of that. + +See :doc:`api/mesh` (also reachable as :ref:`federation`) for the +mesh wire format, member-set semantics, and deploy notes. + The 8-dim cache key ------------------- @@ -177,4 +191,5 @@ Where to go next * :doc:`api/makefile` — every workflow as a ``make`` target * :doc:`api/substrate` — Merkle tree + document primitives * :doc:`api/qa` — Q&A pipeline, verifier, evidence map, run-DAG +* :doc:`api/mesh` — federation primitives across peers * :doc:`license` — full AGPL + Permacomputer Preamble diff --git a/docs/tickets/ticket-000022-adapter-loss-report.md b/docs/tickets/ticket-000022-adapter-loss-report.md new file mode 100644 index 0000000..6030350 --- /dev/null +++ b/docs/tickets/ticket-000022-adapter-loss-report.md @@ -0,0 +1,307 @@ +# Ticket #000022 — Adapter LossReport (PRD I9 analogue) + +**Status:** open · awaiting go/no-go +**Opened:** 2026-05-07 +**Scope:** Design proposal for a typed loss ledger that every source +adapter emits during normalization, so an auditor can answer "what +content did we drop on the way from raw bytes to the prose we +verified?" today's adapters silently strip `` tags, image +wikilinks, HTML chrome, and whitespace runs without recording any +of it. Doc-only — no code in this ticket. Provenance gap analogous +to Donto's PRD I9 LossReport contract surfaced by the +2026-05-07 arborist-vs-donto comparison report. +**Audience:** fox + future blackops shifts + future adapter authors. +**Hard constraint:** adapters never block on loss reporting; LossReport +is additive metadata, not a gate. The Merkle commitment of `chunks.content` +(raw wikitext, raw HTML body) stays bit-identical to today — LossReport +captures *post-chunk* normalization losses, not anything that would +shift `document_root`. Cache-key dimensionality stays at 8. + +--- + +## 1. Problem statement + +Arborist's adapters perform two layers of lossy transformation between +raw bytes and prose the verifier sees: + +| Layer | Adapter | What gets dropped | Where | +|-------|---------|--------------------|-------| +| Ingest-time | `WikipediaSqlDump` family | None at chunk level — raw wikitext is preserved verbatim in `chunks.content`. | `arborist/sources/wikipedia.py` | +| Ingest-time | `HtmlPageSource` | `