notebooks + README: wire the teaching stack to the newest edge

Audit: are the zero-to-hero notebooks current and macOS-runnable, and
does the README present the new teaching surfaces and CLI well?

Verified by execution: all 14 notebooks run headlessly cell-by-cell,
offline, pure-Python (zero shell magics), degrading gracefully where
Lean/built binaries are absent — before AND after these edits. That is
also the macOS answer: no GNU userland is touched by any cell.

Gaps found and closed:
- README's notebook list stopped at 10; notebook 11 (the customer's
  eye view) now listed.
- No notebook knew the cockpit era existed. Three pointer cells added:
  00 (course map: the three-track teaching stack — notebooks = code
  track, lab manual = role track, guide = reference), 10 (see the
  wallet you built through the cockpit; --demo and --wallet forms),
  11 (the Inspect instrument is this notebook's recomputation, живой).
- README: cockpit command block now shows --demo, --wallet, --port/
  --host variants; curriculum section names the teaching stack and the
  notebooks' offline/runnable contract.

Suite 144 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
mrwulf 2026-07-21 18:15:57 +02:00
parent 37429335e6
commit aff1c32fc5
4 changed files with 799 additions and 735 deletions

View file

@ -97,7 +97,9 @@ PyYAML is optional. Without it, `pacta` can still read the included simple YAML
```bash ```bash
python -m pacta --help python -m pacta --help
pacta wallet cockpit --demo # the human surface: bridge, deck, lab manual pacta wallet cockpit --demo # human surface from zero: bridge /deck /manual /guide
pacta wallet cockpit --wallet DIR # same cockpit over a real wallet (default port 8471)
pacta wallet cockpit --wallet DIR --port 9000 # --host/--port to taste; localhost-only by design
pacta wallet status --wallet DIR # custody posture from the CLI pacta wallet status --wallet DIR # custody posture from the CLI
pacta scan --config examples/repos.yaml pacta scan --config examples/repos.yaml
pacta doctor --config examples/repos.yaml --repo-name dalek-ed25519-verified pacta doctor --config examples/repos.yaml --repo-name dalek-ed25519-verified
@ -129,9 +131,19 @@ The `notebooks/` directory contains a zero-to-hero teaching sequence for undergr
- `08_capstone_research_program.ipynb`: audit the shipped R4 evidence; design the R5 discharge plan. - `08_capstone_research_program.ipynb`: audit the shipped R4 evidence; design the R5 discharge plan.
- `09_dogfood_verified_crypto.ipynb`: the proven-path verifier in the agent's own loop; hybrid-PQC posture. - `09_dogfood_verified_crypto.ipynb`: the proven-path verifier in the agent's own loop; hybrid-PQC posture.
- `10_verified_custody_wallet.ipynb`: warden - the quorum custody boundary and signing firewall, ratchet-rule (toy 3-of-3, then the real four proven forks), plus the counterparty recomputing a custody card's inclusion proof. - `10_verified_custody_wallet.ipynb`: warden - the quorum custody boundary and signing firewall, ratchet-rule (toy 3-of-3, then the real four proven forks), plus the counterparty recomputing a custody card's inclusion proof.
- `11_the_customers_eye_view.ipynb`: the counterparty's seat - what a customer can and cannot recompute about someone else's wallet from its custody card and the public log.
The course states and keeps a "ratchet rule": every load-bearing idea runs twice - napkin scale, then real scale - and every pair is executable in the notebook. The course states and keeps a "ratchet rule": every load-bearing idea runs twice - napkin scale, then real scale - and every pair is executable in the notebook.
The notebooks are the **code-level track** of a three-part teaching stack;
the **role-level track** is the [lab manual](docs/warden-lab-manual.md)
(served at `/manual` in the cockpit: sessions, drills, self-tests, a
capstone incident across all six roles), and the in-cockpit **Guide**
(`/guide`) is the plain-language reference both lean on. All fourteen
notebooks execute offline, top to bottom, with pure-Python cells (no
shell magics), degrading gracefully where Lean or built binaries are
absent.
The notebooks are committed without execution output. They can be opened in Jupyter, VS Code, or any notebook reader. They import `pacta` directly from this repository and avoid external notebook-only dependencies. The notebooks are committed without execution output. They can be opened in Jupyter, VS Code, or any notebook reader. They import `pacta` directly from this repository and avoid external notebook-only dependencies.
## Consequence Engine ## Consequence Engine

View file

@ -150,6 +150,26 @@
"- NIST FIPS 204, Module-Lattice-Based Digital Signature Standard: https://csrc.nist.gov/pubs/fips/204/final\n", "- NIST FIPS 204, Module-Lattice-Based Digital Signature Standard: https://csrc.nist.gov/pubs/fips/204/final\n",
"- PACTA README: `../README.md`\n" "- PACTA README: `../README.md`\n"
] ]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## The course's operational twin: the cockpit and the lab manual\n",
"\n",
"These notebooks are the *code-level* track: you build the machinery with your own hands.\n",
"Two sibling surfaces teach the *operational* track on the very same system:\n",
"\n",
"- **The custody cockpit** — `pacta wallet cockpit --demo` serves a read-only bridge of six\n",
" role stations (proposer, quorum bench, operator, cryptographer, architect, newcomer) over\n",
" live evidence, with a tmux-style deck (`/deck`) showing every station in parallel.\n",
"- **The lab manual** (`docs/warden-lab-manual.md`, served at `/manual`) — a study-club course\n",
" that teaches each *role* hands-on: labs with checkpoints, a safe ledger-tamper drill,\n",
" self-tests, and a capstone incident walked through all six chairs.\n",
"\n",
"Recommended weave: notebooks 0009 first (build it), then the lab manual (run it as a crew),\n",
"with notebook 10 and the manual's warden sessions read side by side."
]
} }
], ],
"metadata": { "metadata": {

View file

@ -45,7 +45,7 @@
"## Why a quorum, when one proof would do?\n", "## Why a quorum, when one proof would do?\n",
"\n", "\n",
"Each member is *proven* to decide the same predicate,\n", "Each member is *proven* to decide the same predicate,\n",
"`accept(A,m,R,s) \u21d4 decompress(R) = [k](\u2212A) + [s]B`. So on the\n", "`accept(A,m,R,s) ⇔ decompress(R) = [k](A) + [s]B`. So on the\n",
"proven domain they cannot disagree about *meaning*. Classic\n", "proven domain they cannot disagree about *meaning*. Classic\n",
"N-version programming hopes independent code won't share a bug;\n", "N-version programming hopes independent code won't share a bug;\n",
"we do not hope - we know the semantics coincide, so a runtime\n", "we do not hope - we know the semantics coincide, so a runtime\n",
@ -327,6 +327,25 @@
" transactions, and what exactly the RPC provider is still\n", " transactions, and what exactly the RPC provider is still\n",
" trusted for after you do.\n" " trusted for after you do.\n"
] ]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## The human surface: see this wallet through the cockpit\n",
"\n",
"Everything this notebook built programmatically has a read-only human console:\n",
"\n",
"```\n",
"pacta wallet cockpit --demo # throwaway demo wallet, zero setup\n",
"pacta wallet cockpit --wallet DIR # the wallet you just sealed here\n",
"```\n",
"\n",
"Open `/deck` for all six role stations live in parallel (the quorum bench you built is the\n",
"indigo pane; the ledger you hash-chained is re-verified on every page load), and `/manual`\n",
"for the lab-manual sessions that teach each role — Session 4's tamper drill breaks a *copy*\n",
"of a ledger exactly like this notebook's and watches two independent surfaces catch it."
]
} }
], ],
"metadata": { "metadata": {

View file

@ -4,12 +4,12 @@
"cell_type": "markdown", "cell_type": "markdown",
"metadata": {}, "metadata": {},
"source": [ "source": [
"# Lecture 11: The Customer's-Eye View \u2014 You Hold the Ruler\n", "# Lecture 11: The Customer's-Eye View — You Hold the Ruler\n",
"\n", "\n",
"Every earlier lecture looked at the log from the *operator's*\n", "Every earlier lecture looked at the log from the *operator's*\n",
"side: replaying proofs, signing attestations, building the\n", "side: replaying proofs, signing attestations, building the\n",
"tree. This one flips the telescope. You are now a customer \u2014 an\n", "tree. This one flips the telescope. You are now a customer an\n",
"agent, a wallet, a developer \u2014 who wants to trust one of the\n", "agent, a wallet, a developer — who wants to trust one of the\n",
"four verified Ed25519 forks and has no theorem prover, no Lean,\n", "four verified Ed25519 forks and has no theorem prover, no Lean,\n",
"no desire to spend hours re-checking anything. What actually\n", "no desire to spend hours re-checking anything. What actually\n",
"happens on your side? The answer reframes the whole system, and\n", "happens on your side? The answer reframes the whole system, and\n",
@ -24,7 +24,7 @@
"\n", "\n",
"- Separate the three roles that a verification touches:\n", "- Separate the three roles that a verification touches:\n",
" *measurement* (operator), *publication* (the log), and\n", " *measurement* (operator), *publication* (the log), and\n",
" *judgment* (you) \u2014 and see that only the last is yours.\n", " *judgment* (you) — and see that only the last is yours.\n",
"- Understand the \"allowed axioms\" list as a **requirements\n", "- Understand the \"allowed axioms\" list as a **requirements\n",
" card** you own, can read, and could write yourself.\n", " card** you own, can read, and could write yourself.\n",
"- Explain why a self-written card meeting the supply *exactly*\n", "- Explain why a self-written card meeting the supply *exactly*\n",
@ -38,7 +38,7 @@
"cell_type": "markdown", "cell_type": "markdown",
"metadata": {}, "metadata": {},
"source": [ "source": [
"## The card is a requirements card \u2014 and ideally you write it\n", "## The card is a requirements card — and ideally you write it\n",
"\n", "\n",
"The list of axioms a certificate is *allowed* to rest on is not\n", "The list of axioms a certificate is *allowed* to rest on is not\n",
"handed to you by the operator at verification time. It ships\n", "handed to you by the operator at verification time. It ships\n",
@ -85,12 +85,12 @@
"cell_type": "markdown", "cell_type": "markdown",
"metadata": {}, "metadata": {},
"source": [ "source": [
"## Wish meets supply \u2014 and it is no accident\n", "## Wish meets supply — and it is no accident\n",
"\n", "\n",
"Now compare your self-written card against what the four forks\n", "Now compare your self-written card against what the four forks\n",
"actually declare. They match. That convergence is *engineered*:\n", "actually declare. They match. That convergence is *engineered*:\n",
"the supply was deliberately shrunk \u2014 every axiom made to justify\n", "the supply was deliberately shrunk — every axiom made to justify\n",
"its existence \u2014 so that any reasonable person's independently\n", "its existence — so that any reasonable person's independently\n",
"written card lands on the same minimal list. When the wish meets\n", "written card lands on the same minimal list. When the wish meets\n",
"the supply exactly, it is because the supplier spent months\n", "the supply exactly, it is because the supplier spent months\n",
"making the supply as small as honesty allows.\n" "making the supply as small as honesty allows.\n"
@ -131,20 +131,20 @@
"\n", "\n",
"Only judgment is yours, and it is the only step that involves an\n", "Only judgment is yours, and it is the only step that involves an\n",
"opinion. The operator is trusted to *copy down what the kernel\n", "opinion. The operator is trusted to *copy down what the kernel\n",
"printed* \u2014 never to interpret it.\n" "printed* — never to interpret it.\n"
] ]
}, },
{ {
"cell_type": "markdown", "cell_type": "markdown",
"metadata": {}, "metadata": {},
"source": [ "source": [
"## If you are happy \u2014 you are already finished\n", "## If you are happy — you are already finished\n",
"\n", "\n",
"If your card covers the observed cone, verification is: check\n", "If your card covers the observed cone, verification is: check\n",
"one signature, walk ~4 hashes to the signed root, compare cones\n", "one signature, walk ~4 hashes to the signed root, compare cones\n",
"to your card. Milliseconds, standard library, no Lean. Done.\n", "to your card. Milliseconds, standard library, no Lean. Done.\n",
"\n", "\n",
"## If you are NOT happy \u2014 there is nothing to negotiate\n", "## If you are NOT happy — there is nothing to negotiate\n",
"\n", "\n",
"Suppose your card is stricter: *\"I require SHA-512 itself\n", "Suppose your card is stricter: *\"I require SHA-512 itself\n",
"proven, not an oracle.\"* The system has no sales pitch for you.\n", "proven, not an oracle.\"* The system has no sales pitch for you.\n",
@ -152,7 +152,7 @@
"*not in supply; SHA-512-proven is the R5 frontier; here is the\n", "*not in supply; SHA-512-proven is the R5 frontier; here is the\n",
"exact list of what you would be accepting if you proceed\n", "exact list of what you would be accepting if you proceed\n",
"anyway.* Your decision is never \"lower my standards\" in the\n", "anyway.* Your decision is never \"lower my standards\" in the\n",
"abstract \u2014 it is a named line item: *SHA-512 as oracle: yes/no.*\n", "abstract — it is a named line item: *SHA-512 as oracle: yes/no.*\n",
"Informed compromise, not diffuse trust.\n" "Informed compromise, not diffuse trust.\n"
] ]
}, },
@ -180,7 +180,7 @@
"\n", "\n",
"The gap between anyone's dream card and today's supply is a\n", "The gap between anyone's dream card and today's supply is a\n",
"to-do list, not a wall. Prove SHA-512, certify the wire\n", "to-do list, not a wall. Prove SHA-512, certify the wire\n",
"parsers, and the new certificates enter the same log \u2014 and\n", "parsers, and the new certificates enter the same log and\n",
"stricter cards start passing. The log is additive in exactly\n", "stricter cards start passing. The log is additive in exactly\n",
"the way requirements are.\n", "the way requirements are.\n",
"\n", "\n",
@ -211,6 +211,19 @@
" card and the supply)? What single action by a customer\n", " card and the supply)? What single action by a customer\n",
" settles the argument in their favor?\n" " settles the argument in their favor?\n"
] ]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Do it in the cockpit: the Inspect instrument\n",
"\n",
"The recomputation this notebook performs by hand is exactly what the cockpit's **Inspect**\n",
"instrument (`/inspect`) runs on paste — same deployed verifier, verbatim diagnostics —\n",
"and what the lab manual's Cryptographer session drills: verify the sample evidence, then\n",
"deliberately corrupt one character and learn the distinct failure surfaces.\n",
"`pacta wallet cockpit --demo`, then Inspect → “Load the sample evidence”."
]
} }
], ],
"metadata": { "metadata": {