Update README.md

README.md

@@ -10,18 +10,18 @@ pinned: false
 license: other
 short_description: Tamper-evident, hash-chained event logging for AI/agent runs
 ---
-# RFT Agent Flight Recorder — Black Box Behaviour Trace
+# RFT Agent Flight Recorder — Black Box Trace + Third-Party Verification
 
 A proof-first flight recorder for AI/agent runs. This Space writes an **append-only, hash-chained event log** so you can verify **what happened, when it happened, and what triggered it**—without taking anyone’s word for it.
 
-It’s built to be boringly audit-friendly: deterministic hashing, optional Ed25519 signatures, session verification, and exportable proof bundles that third parties can check.
+It’s designed to be boringly audit-friendly: **canonical JSON hashing**, optional **Ed25519 signatures**, **session verification**, and **exportable proof bundles** that third parties can check.
 
 ---
 
 ## What this Space does
 
 ### ✅ Records a tamper-evident timeline
-Each action becomes an **event** (JSON) written to `flightlog.jsonl`:
+Each action becomes an **event** (one JSON object per line) written to `flightlog.jsonl`:
 
 - `prompt`
 - `output`
@@ -35,28 +35,34 @@ Each action becomes an **event** (JSON) written to `flightlog.jsonl`:
 Every event includes:
 
 - `seq` (monotonic step number)
-- `ts_utc` (timestamp)
+- `ts_utc` (UTC timestamp)
 - `prev_event_hash_sha256` (links to previous event)
 - `event_hash_sha256` (hash of this event)
 - optional `signature_ed25519` (Ed25519 signature)
 
 If any event is edited, removed, or reordered, verification fails.
 
+### ✅ Concurrency-safe writes (public Space reality)
+Multiple users can click around at the same time. The log is protected with a **file lock** so “two tabs / two users” don’t corrupt the chain.
+
+### ✅ Refuses writes after finalisation
+Once a session records `session_end`, the recorder **refuses any further writes** to that session. No silent “post-hoc edits”.
+
 ### ✅ Verifies sessions end-to-end
-The verifier recomputes hashes and confirms the chain is intact. Optionally, it can require a valid signature on every event.
+The verifier recomputes hashes and confirms the chain is intact. Optionally, it can require a valid signature on every event (only enable this if you signed every event).
 
 ### ✅ Exports proof bundles
 Exports `rft_flight_bundle_<session_id>.zip` containing:
 
-- `<session_id>_events.jsonl` (the session timeline)
-- `<session_id>_verify_report.txt` (verification report)
+- `<session_id>_events.jsonl` (the full session timeline)
+- `<session_id>_verify_report.txt` (human-readable verification report)
 
 ### ✅ Imports and verifies third-party bundles
 Upload a bundle and verify it locally. Optionally store PASSed events into your local `flightlog.jsonl`.
 
 ---
 
-## How to use
+## How to use (step-by-step)
 
 ### 1) Generate keys (optional)
 Go to **Keys** → **Generate Keypair**.
@@ -64,11 +70,11 @@ Go to **Keys** → **Generate Keypair**.
 - **Private key** signs events (keep it private).
 - **Public key** verifies signatures (safe to share).
 
-> demo note: don’t paste production private keys here.
+**Public demo note:** don’t paste production private keys here.
 
 ### 2) Start a session
 Go to **Start Session** → **Start New Session**.  
-Copy the `session_id`.
+Copy the `session_id` (the UI fans it out across tabs).
 
 ### 3) Record events
 Go to **Record Event** and append events as they occur.
@@ -85,16 +91,16 @@ Go to **Timeline** → **Load timeline**.
 ### 5) Verify
 Go to **Verify Session** → **Verify**.
 
-Enable “Require signatures” only if you signed every event.
+Enable **Require signatures** only if you signed every event you expect to verify.
 
 ### 6) Finalise + Export
 Go to **Finalise + Export**:
-- **Finalise session** creates a session anchor.
+- **Finalise session** appends `session_end` with a **session anchor**.
 - **Export session bundle** produces the ZIP proof bundle.
 
 ### 7) Import bundle (third-party verification)
 Go to **Import Bundle**, upload `rft_flight_bundle_*.zip`, and verify.  
-If you want to retain verified sessions, tick **Store imported events**.
+If you want to retain verified sessions, tick **Store imported events** (only stores on PASS).
 
 ---
 
@@ -113,7 +119,57 @@ If you want to retain verified sessions, tick **Store imported events**.
   "payload": { "tool": "search", "input": { "q": "…" } },
   "meta": { "model_id": "audit-demo", "run_mode": "deterministic" },
   "event_hash_sha256": "…",
-  "signature_ed25519": "…"  // optional
+  "signature_ed25519": "…" 
+}
+Session anchor (what finalisation commits to)
+
+Finalisation creates an anchor that describes the pre-end chain (so it doesn’t depend on itself):
+{
+  "spec": "rft-flight-session-root-v0",
+  "session_id": "…",
+  "first_event_hash_sha256": "…",
+  "last_event_hash_sha256": "…",
+  "event_count": 42,
+  "root_hash_sha256": "…",
+  "signature_ed25519": "…" 
 }
+Brutal tests (included)
+
+This repo includes brutal_test.py with two hard tests:
+
+Two-tab spam test: concurrent writers attempt to append hundreds of events; the session must still verify PASS.
+
+Tamper ZIP test: modifies an exported event payload without updating hashes; import verification must FAIL.
+
+Run locally:
+
+python brutal_test.py
+
+Expected:
+
+both tests PASS
+
+tampered bundle fails verification as intended
+
+Security / limitations (read this)
+
+This Space is a public demo. Treat anything you paste as public.
+
+The log file is shared by all users of the Space instance.
+
+Signatures prove authorship by a key, not “truth”. If you sign lies, you still signed lies—this tool proves integrity and provenance, not honesty.
+
+Files
+
+app.py — Gradio UI
+
+rft_flightrecorder.py — recorder + verification library
+
+brutal_test.py — stress + tamper tests
+
+flightlog.jsonl — append-only log (created at runtime)
+
+licence
 
+::contentReference[oaicite:0]{index=0}
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference