# The FablePool end-to-end demo, act by act

`demo/run_demo.py` (wrapped by `demo/run_demo.sh`) is the scripted public
demo that ties all six milestones together in a single run. It creates three
nodes in a scratch directory:

- **phone** — a user-owned node, imports `datasets/phone/` (calendar `.ics`,
  photo metadata `.json`)
- **laptop** — a user-owned node, imports `datasets/laptop/notes/` (markdown)
- **coach** — a third-party delegate node with its own key, owned by someone
  else

Each act below names the milestone it demonstrates and the code and tests
that back it.

## Act 1 — Ingest evidence (Milestones 2 & 3)

The phone imports calendar events (marathon training sessions, a quarterly
appointment with Dr. Okafor) and photo metadata (geotagged run photos); the
laptop imports notes about health, training, and trip planning. Every
imported item becomes a **signed evidence op** in that node's append-only
log: canonical bytes, Ed25519 signature, hash-chained to the author's
previous op.

- Code: `fablepool/adapters/{calendar,notes,photos}.py`, `fablepool/ops.py`,
  `fablepool/canonical.py`, `fablepool/store.py`
- Tests: `tests/test_canonical.py`, `tests/test_ops.py`,
  `tests/test_adapters.py`
- Wire format ground truth: `conformance/vectors/`

## Act 2 — Derive claims with provenance (Milestone 4)

The derivation engine runs its deterministic rules over the evidence and
asserts claims such as *trains for a marathon*, *sees Dr. Okafor quarterly*,
*planning a trip to Lisbon* — each with a confidence value and a provenance
list naming the exact evidence ops and rule that produced it. Some claims
derive from other claims, forming the derivation graph.

- Code: `fablepool/derive.py`, `fablepool/claims.py`
- Tests: `tests/test_derivation_cascade.py`

## Act 3 — "What do you know about me and why?" (Milestone 5)

The demo invokes the inspection interface (the same code behind the
`fablepool` CLI) to list every claim with its confidence and a provenance
tree down to the raw evidence: *which calendar entry, which note paragraph,
which photo*. Nothing is unexplainable by construction — a claim without
provenance cannot exist.

- Code: `fablepool/cli.py` (also runnable standalone: `python -m fablepool`)

## Act 4 — Refute, and watch the cascade (Milestone 4 + 5)

The user refutes one claim (the demo refutes the trip-planning claim — the
notes were research for a friend). The refutation is itself a signed op. The
engine invalidates the claim and **every claim transitively derived from
it**, then re-derives from surviving evidence. The demo prints the
before/after claim sets so the cascade is visible.

- Tests: `tests/test_derivation_cascade.py`

## Act 5 — Sync phone ↔ laptop, with a conflict (Milestone 6)

Phone and laptop sync over the local transport: heads exchange, delta fetch,
validate-on-ingest. The demo deliberately creates a **conflict** — both
devices concurrently assert different values for the same predicate while
offline — then syncs and shows both nodes converging to the identical winner
via the deterministic resolution order (user-asserted > confidence >
timestamp > op id), with the loser still visible in the audit log.

- Code: `fablepool/sync.py`, `fablepool/transport.py`, `fablepool/node.py`
- Tests: `tests/test_sync_convergence.py`

## Act 6 — Delegate a narrow slice to the coach (Milestone 6)

The user signs a **capability grant** scoped to fitness predicates only. The
coach node syncs and receives exactly the in-scope claims in **redacted
projection**: provenance references replaced by opaque hashes, **zero
evidence ops transferred**. The demo asserts, from inside the coach's store,
that no evidence and no out-of-scope claim (the medical appointment claim,
for instance) is present.

- Code: `fablepool/capability.py`
- Tests: `tests/test_capability_revocation.py`

## Act 7 — Revoke, mechanically and verifiably (Milestone 6)

The user signs a **revocation**. On the coach's next sync it receives the
revocation instead of new claims, marks its slice revoked, stops serving it,
and emits a **signed acknowledgment** of the revocation op id. The user's
nodes ingest the ack — the user now holds cryptographic proof the delegate
saw the revocation. The demo then shows the coach's further access attempt
being refused by the user's nodes, and the coach's own API refusing to answer
from the revoked slice.

- Code: `fablepool/capability.py`, `fablepool/sync.py`
- Tests: `tests/test_capability_revocation.py`

## Act 8 — Conformance receipt (Milestone 2 ↔ 6)

Finally, the demo (and `python conformance/run_conformance.py` on its own)
replays the milestone-2 vectors — canonicalization, signing, and full op
scenarios — and prints a pass/fail report. This is the same harness a second
implementation runs to prove interoperability; see `INTEROP.md` §10 and
`conformance/README.md`.

## What the demo deliberately does *not* show

Per the project non-goals (README): no networked transport hardening, no key
management UX, no forced deletion on a defecting delegate, no statistical
privacy of shared slices. The demo shows the protocol's enforceable
guarantees — auditability, mechanical scoping, verifiable revocation — and is
honest about where guarantees end.