diff --git a/README.md b/README.md index 5c58957..2a9ad05 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ three-phase safety engine (DIAGNOSE → APPROVE → VERIFY). Current production path: ```text -Dashboard -> FastAPI Cloud Run (opens approval gate) +Dashboard -> FastAPI Cloud Run (creates gated read-only run) -> Diagnose Agent Engine -> Candidate Agent Engine -> Rationale Agent Engine -> deterministic controller validates + emits DIAGNOSED EvidencePack -> /packs/{id}/decision hash-bound approval ticket @@ -25,9 +25,10 @@ Dashboard -> FastAPI Cloud Run (opens approval gate) The three Agent Engine resources perform read-only Mongo diagnosis, candidate testing, and rationale generation with Python-native tools. Deterministic Python remains the safety authority: it recomputes the ESR winner, evidence -hash, phase transitions, index apply, and verification. `/run` opens the approval gate -before diagnosis and remains read-only; `/packs/{run_id}/decision` is the only path that -can issue the one-time approval ticket required for mutation. +hash, phase transitions, index apply, and verification. `/run` creates a gated read-only +run. Mutation remains impossible until the operator approves a matching EvidencePack hash; +`/packs/{run_id}/decision` is the only path that can issue the one-time internal apply +action required for mutation. The dashboard reads only `EvidencePack` JSON, including `approval_gate` state and `agent_trace` proof that the gate opened before Agent Engine participation. Internally, diff --git a/contracts/examples/evidence_pack.example.json b/contracts/examples/evidence_pack.example.json index f466fa9..63a0d69 100644 --- a/contracts/examples/evidence_pack.example.json +++ b/contracts/examples/evidence_pack.example.json @@ -8,7 +8,7 @@ "resource": null, "stage": "gate", "status": "ok", - "summary": "Approval gate opened before diagnosis.", + "summary": "/run created a gated read-only run; mutation requires matching evidence hash approval.", "tool": "approval_gate" }, { diff --git a/dashboard/README.md b/dashboard/README.md index 003ba28..64dcdf5 100644 --- a/dashboard/README.md +++ b/dashboard/README.md @@ -88,15 +88,16 @@ lib/ diagnosis; during a run it is collecting evidence, then it moves to pending approval with the required hash. - **Ask the agent** calls the same-origin `/api/run` proxy, which forwards to the - Cloud Run API with the server-side token. The backend opens the approval gate - first, then asks the Diagnose, Candidate, and Rationale Agent Engine resources - for read-only diagnosis. + Cloud Run API with the server-side token. The backend creates a gated read-only + run, then asks the Diagnose, Candidate, and Rationale Agent Engine resources for + read-only diagnosis. - The returned pack is `diagnosed`, shown as **pending approval**. No database mutation happens during this step. `agent_trace` starts with `approval_gate/gate`, then shows the split Agent Engine role events plus deterministic validation. -- **Approve fix** posts the displayed `evidence_hash` through the same-origin - decision proxy. The backend issues a one-time approval ticket and applies/verifies - the index only after that hash-bound approval. If the API is not configured, the - UI shows an error and does not fake a saved decision. +- **Approve this evidence hash** posts the displayed `evidence_hash` through the + same-origin decision proxy. The backend verifies the hash, issues a one-time + internal apply action, and applies/verifies the index only after that hash-bound + approval. If the API is not configured, the UI shows an error and does not fake a + saved decision. - The trace panel and footer show when the pack came from the live API, where the EvidencePack aggregate and internal ledger event collections are persisted. diff --git a/demo/architecture.md b/demo/architecture.md index 1ce186d..4e7f0a6 100644 --- a/demo/architecture.md +++ b/demo/architecture.md @@ -40,7 +40,7 @@ flowchart TB end DASH -- "GET /packs/:id" --> API - DASH -- "POST /run opens gate first" --> API + DASH -- "POST /run creates gated read-only run" --> API DASH -- "POST /packs/:id/decision" --> API API -- "/run asks diagnose role" --> DIAG API -- "/run asks candidate role" --> CAND @@ -66,7 +66,7 @@ flowchart TB | Stage (UI) | Engine phase | What happens | Who does it | |------------|-------------|--------------|-------------| -| **Gate** | (pre) | Approval gate opens before diagnosis; mutation is blocked | **human gate / controller** | +| **Gate** | (pre) | `/run` creates a gated read-only run; mutation is blocked | **human gate / controller** | | **Detect** | (pre) | Slow query surfaced from the fixture / logs | Diagnose Agent Engine | | **Diagnose** | `DIAGNOSE` | Read `explain`, extract stages + counters, identify the blocking-sort root cause | Diagnose Agent Engine, deterministic code validates | | **Test** | `DIAGNOSE` | Compare B vs C and propose index **C** (correct ESR) from measured evidence | Candidate Agent Engine, deterministic code recomputes | @@ -78,8 +78,8 @@ flowchart TB Three things make it a real plan-and-execute system (and the reason we run on **Agent Engine + ADK**, not the no-code console): -1. **Gate-first control plane** — `/run` opens an approval gate before diagnosis, - and every emitted pack records that gate plus the required evidence hash. +1. **Gated read-only run** — `/run` creates a gated run record and keeps mutation + impossible until the operator approves a matching EvidencePack hash. 2. **Hash-bound approval ticket** — the controller blocks at `APPROVE` until a decision arrives carrying the matching `evidence_hash`. Only the decision route can issue the one-time ticket required by `apply_and_verify`; stale diff --git a/demo/dashboard-walkthrough.md b/demo/dashboard-walkthrough.md index 1847df1..80c642a 100644 --- a/demo/dashboard-walkthrough.md +++ b/demo/dashboard-walkthrough.md @@ -42,13 +42,13 @@ done and it's waiting at **Approve**. > Annotation: "Five visible stages over a phase-gated engine — the agent can't > skip ahead or apply early." -### Predicted vs Observed (`03-plan.png`) — the centerpiece +### Before / After Explain Diff (`03-plan.png`) — the centerpiece Two columns, Before (serving index B) and After (recommended index C): - **Stage chain** — each plan stage as a chip. `SORT` renders **red**, `IXSCAN` **green**, so the eye lands on the blocking sort immediately. - **Metrics** — keys examined, docs examined, returned, millis. The *keys examined* figure is the headline: **17,209 (B) vs 64 (C)**. -- A **blocking sort / no sort** badge per column. +- A **SORT present / SORT removed** badge per column. > Annotation: "The color *is* the diagnosis — red SORT on the left, gone on the > right. 269× fewer index keys for the same 20 rows." diff --git a/demo/demo-script.md b/demo/demo-script.md index 89c16ae..4a836b0 100644 --- a/demo/demo-script.md +++ b/demo/demo-script.md @@ -50,11 +50,11 @@ This is the **prediction** — state it before showing the result. ## 2:10–2:35 — Approve: the human gate > "Nothing gets applied automatically. The operator sees the evidence pack — and -> its hash — inside the gate that was opened before diagnosis — and approves. The +> its hash — inside the gated read-only run — and approves. The > approval route issues the one-time ticket bound to that exact evidence hash; if > the evidence changed, the approval is rejected." -Click **Approve fix**. The gate closes as verified after apply + verify completes. +Click **Approve this evidence hash**. The gate closes as verified after apply + verify completes. ## 2:35–3:00 — Verify: predicted vs observed diff --git a/deploy/cloudrun.md b/deploy/cloudrun.md index f5a7bf2..db056e6 100644 --- a/deploy/cloudrun.md +++ b/deploy/cloudrun.md @@ -74,11 +74,12 @@ in the repo root and push the image to Artifact Registry automatically. > > **Agent Engine:** all three split resources are required for deploy: > `AGENT_ENGINE_DIAGNOSE_RESOURCE`, `AGENT_ENGINE_CANDIDATE_RESOURCE`, and -> `AGENT_ENGINE_RATIONALE_RESOURCE`. `/run` opens the approval gate first, then -> calls the Diagnose, Candidate, and Rationale Agent Engine resources in order. -> The deterministic controller validates the winner/hash and emits the DIAGNOSED -> EvidencePack. `MONGO_SECRET_NAME` is also required; production must read MongoDB -> credentials from Secret Manager. +> `AGENT_ENGINE_RATIONALE_RESOURCE`. `/run` creates a gated read-only run, then calls +> the Diagnose, Candidate, and Rationale Agent Engine resources in order. Mutation remains +> impossible until the operator approves a matching EvidencePack hash. The deterministic +> controller validates the winner/hash and emits the DIAGNOSED EvidencePack. +> `MONGO_SECRET_NAME` is also required; production must read MongoDB credentials from +> Secret Manager. ### What the script does