From d6458a79ef4bf0814a3d6d45f3c93fbd7a47cd9c Mon Sep 17 00:00:00 2001
From: Samuel Laferriere <9342524+samlaf@users.noreply.github.com>
Date: Mon, 3 Aug 2026 14:44:55 -0400
Subject: [PATCH] docs(tee): document the measurement-admission pipeline in the
 README

Add a measurement-admission pipeline section to the new-network
walkthrough: the make-measure -> promote -> compile+inject -> pin ->
gates chain, with the Rust subprocess boundaries marked so the
on-PATH binary requirements are visible where assemble is explained.

Replaces the orphaned excalidraw/png pair in the seismic repo
(docs/tee/diagrams/measurement-admission-pipeline.*, removed there in
a companion PR): it was embedded nowhere, and the diagram conventions
put structured flowcharts in markdown next to the workflow they
document.
---
 tee/README.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/tee/README.md b/tee/README.md
index 1628842c..8b3ddec1 100644
--- a/tee/README.md
+++ b/tee/README.md
@@ -224,6 +224,46 @@ uv run seismic-tee-network genesis-ceremony \
 After step 3 each node is up; after step 4 they produce blocks. RPC is at
 `https://<fqdn>/rpc` (the `fqdn` from each descriptor).
 
+### The measurement-admission pipeline
+
+What `assemble` does with the measurements input, end to end. Policy
+semantics (normalization, admission-ID derivation, registry storage
+layout) have exactly one implementation — the enclave repo's
+[`seismic-measurement-admission`](https://github.com/SeismicSystems/enclave/blob/seismic/crates/measurement-admission/README.md)
+crate — so this CLI shells out to it rather than mirroring it in
+Python; `[rust: …]` marks those subprocess boundaries (the named
+binaries must be on PATH).
+
+```text
+seismic-images: make measure
+      │   measurements.json — raw measured-boot output, every populated
+      │   register + event log (build artifact, kept for audit)
+      ▼
+assemble: promote                 [rust: seismic-measurement-admission promote]
+      │   measurement-policy.json — the human-reviewed allowlist, exactly
+      │   the admission-schema registers (Azure v1: pcr4/pcr9/pcr11)
+      ▼
+assemble: compile + inject        [rust: seismic-measurement-admission compile]
+      │   admission IDs + registry genesis-storage slots, written verbatim
+      │   into the reth genesis's MeasurementRegistry account
+      ▼
+assemble: pin + render
+      ├─ eth.genesis_hash         [rust: seismic-reth genesis-hash]
+      ├─ measurements.bootstrap_policy_hash = SHA-256(policy bytes)   (python)
+      └─ render network-manifest.json; network_id = SHA-256(bytes)    (python)
+      ▼
+validate / up --network — re-run the same derivations as acceptance gates
+      ▼
+chain: MeasurementRegistry live from block 0 — no init transaction;
+       empty storage fails closed
+```
+
+Runtime consumers of the same derivation (not this CLI): the responder
+answers joins by converting verified PCRs to an admission ID and
+querying `isAccepted()` on its local reth; a joiner compiles the
+manifest-pinned bootstrap policy and checks the responder's ID for
+membership.
+
 ## The config: `--bootnode`, `--manifest`, `--reth-genesis`, `--email`
 
 There is no per-node TOML. The config is assembled from flags + the descriptor,