proof-aware-crypto-tooling-agent/notebooks/02_claim_cards_and_risk_model.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Lecture 2: Claim Cards and the R0-R5 Risk Model\n",
        "\n",
        "A claim card is a machine-readable assurance artifact. It records what was checked, what theorem names were involved, what axioms were observed, what exclusions remain, what trusted base is assumed, and what risk score follows.\n",
        "\n",
        "A claim card is not a marketing page. It is a structured input to policy.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Learning Objectives\n",
        "\n",
        "- Read the claim card schema.\n",
        "- Explain risk levels R0 through R5.\n",
        "- Generate an offline fixture claim card.\n",
        "- Understand why R3 can authorize lower-layer library use but not wallet construction.\n",
        "- Identify blockers and deployment constraints in a claim card.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Risk Levels\n",
        "\n",
        "- `R0`: Unknown or untrusted. No usable evidence.\n",
        "- `R1`: Tests, audits, or informal claims only.\n",
        "- `R2`: Formal model exists, but incomplete, weakly tied to production code, or major proof gaps remain.\n",
        "- `R3`: A specific lower-layer implementation artifact is Lean-checked for a specific backend and theorem boundary.\n",
        "- `R4`: End-to-end primitive proof covers public API, parsing/encoding, scalar arithmetic, hashing interface, signature equation, rejection rules, and implementation boundary.\n",
        "- `R5`: R4 plus reproducible production builds, compiler/build assurance, side-channel analysis, hardware/KMS/MPC integration, and operational controls.\n",
        "\n",
        "Ed25519 field plus Edwards arithmetic alone reaches R3. Since the corpus completed its four-tier signature apex (2026-07-06), the FULL configured certificate set - arithmetic, scalars, encoding/decoding, and the four apex tiers, each with its axiom cone pinned to the fork's documented boundary - reaches **R4**, always with explicit residual blockers (the SHA-512 oracle, hypothesis-parametric wire parses, translation faithfulness, and the missing side-channel/build assurance that gates R5).\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from pathlib import Path\n",
        "import sys\n",
        "\n",
        "repo_root = Path.cwd()\n",
        "if not (repo_root / \"src\" / \"pacta\").exists():\n",
        "    repo_root = repo_root.parent\n",
        "sys.path.insert(0, str(repo_root / \"src\"))\n",
        "\n",
        "from pacta.claims import build_claim_card\n",
        "from pacta.config import load_config\n",
        "\n",
        "config = load_config(repo_root / \"examples\" / \"repos.yaml\")\n",
        "repo = config.repo_named(\"dalek-ed25519-verified\")\n",
        "card = build_claim_card(repo, repo_root / \"repos\" / repo.name, offline_fixture=True)\n",
        "\n",
        "print(card[\"component\"])\n",
        "print(card[\"risk\"][\"level\"])\n",
        "print(card[\"risk\"][\"rationale\"])\n",
        "print(card[\"certificates\"][0])\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "important_fields = [\n",
        "    \"component\",\n",
        "    \"repo_url\",\n",
        "    \"repo_commit\",\n",
        "    \"verification_dir\",\n",
        "    \"kind\",\n",
        "    \"verified_backend\",\n",
        "    \"certificates\",\n",
        "    \"guarantees\",\n",
        "    \"preconditions\",\n",
        "    \"exclusions\",\n",
        "    \"trusted_base\",\n",
        "    \"evidence\",\n",
        "    \"risk\",\n",
        "]\n",
        "for field in important_fields:\n",
        "    print(field, \"=>\", type(card.get(field)).__name__)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Reading a Certificate Entry\n",
        "\n",
        "A certificate entry contains:\n",
        "\n",
        "- `name`: theorem or aggregate certificate name.\n",
        "- `status`: `proven`, `missing`, `failed`, or `unknown`.\n",
        "- `axiom_status`: `clean`, `dirty`, or `not_checked`.\n",
        "- `observed_axioms`: axioms reported by Lean.\n",
        "- `expected_axioms`: allowed standard axioms for this profile.\n",
        "\n",
        "A clean result requires more than a theorem name. It requires a successful replay or trusted attestation, the RIGHT axiom set per certificate (standard-three below the apex, the fork's documented boundary at the apex tiers - deviation in either direction is dirty), and no policy-blocking exclusions.\n",
        "\n",
        "### The ratchet, run both ways\n",
        "\n",
        "First the napkin: a two-certificate card you can score in your head. Then the real thing: the shipped R4 fixture with sixteen certificates and per-tier boundary axioms.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# NAPKIN: an arithmetic-only card. Two certificates, standard axioms.\n",
        "from pacta.risk import score_claim_card\n",
        "\n",
        "napkin_card = {\n",
        "    \"kind\": \"ed25519\",\n",
        "    \"certificates\": [\n",
        "        {\"name\": \"CurveFieldProofs.fieldImplementation\", \"status\": \"proven\", \"axiom_status\": \"clean\"},\n",
        "        {\"name\": \"CurveFieldProofs.edwardsImplementation\", \"status\": \"proven\", \"axiom_status\": \"clean\"},\n",
        "    ],\n",
        "    \"exclusions\": [\"full EdDSA signature verification\"],\n",
        "    \"meta\": {\"r4_requirements\": []},\n",
        "}\n",
        "napkin = score_claim_card(napkin_card)\n",
        "print(napkin.level, \"-\", napkin.rationale)\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# REAL: the shipped R4 fixture - sixteen certificates, apex tiers carrying\n",
        "# the dalek fork's documented boundary axioms. Same scoring function.\n",
        "from pacta.yamlio import load_data\n",
        "\n",
        "real_card = load_data(repo_root / \"examples\" / \"dalek-ed25519.claims.yaml\")\n",
        "real = score_claim_card(real_card)\n",
        "print(real.level)\n",
        "print(real.rationale[:180], \"...\")\n",
        "print(\"residual blockers:\")\n",
        "for blocker in real.blockers:\n",
        "    print(\" -\", blocker)\n",
        "apex = [c for c in real_card[\"certificates\"] if c[\"name\"].endswith(\"_decompress\")][0]\n",
        "print(\"full-lift tier expects:\", apex[\"expected_axioms\"])\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "for cert in card[\"certificates\"]:\n",
        "    print(f\"{cert['name']}: {cert['status']} / {cert['axiom_status']}\")\n",
        "    print(\"  observed:\", cert[\"observed_axioms\"])\n",
        "    print(\"  expected:\", cert[\"expected_axioms\"])\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Deployment Constraints\n",
        "\n",
        "Deployment constraints are where many assurance cases become honest. For Ed25519 arithmetic, constraints include:\n",
        "\n",
        "- Use exact pinned source or reviewed diff.\n",
        "- Use verified serial/u64 backend only.\n",
        "- Disable accelerator/syscall/hardware/SIMD paths unless separately certified.\n",
        "- Do not treat this as full EdDSA verification.\n",
        "- Keep key custody behind HSM/MPC/policy firewall until signing stack proof coverage improves.\n",
        "- Use ordinary tests/fuzzing at encoding/API/transaction boundaries.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "for constraint in card[\"risk\"][\"deployment_constraints\"]:\n",
        "    print(\"-\", constraint)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Exercises\n",
        "\n",
        "- Change the generated card in memory so one certificate is `missing`. Rescore it and explain the change.\n",
        "- Write a short policy that allows `build-library` at R3 but denies `build-wallet-demo` below R4.\n",
        "- Compare the trusted base for local replay versus third-party attestation.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from copy import deepcopy\n",
        "from pacta.risk import score_claim_card\n",
        "\n",
        "weaker = deepcopy(card)\n",
        "weaker[\"certificates\"][0][\"status\"] = \"missing\"\n",
        "weaker[\"certificates\"][0][\"axiom_status\"] = \"not_checked\"\n",
        "assessment = score_claim_card(weaker)\n",
        "print(assessment.level)\n",
        "print(assessment.rationale)\n",
        "print(assessment.blockers)\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "pygments_lexer": "ipython3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}