rootsign 0.2.1__tar.gz → 0.3.0__tar.gz

{rootsign-0.2.1 → rootsign-0.3.0}/.env.example

@@ -17,11 +17,30 @@ DB_POOL_TIMEOUT=30
 # ---------------------------------------------------------------------------
 
 # Transport: 'local' calls IngestHandler in-process (Phase 1 default).
-# 'cloud' would POST to the hosted backend, but Phase 1 stubs that path —
-# HttpIngestClient raises NotImplementedError until Phase 2.
+# 'cloud' POSTs batched envelopes to the hosted backend via HttpIngestClient
+# (ADR-013). Needs the cloud extra:  pip install 'rootsign[cloud]'
 ROOTSIGN_BACKEND=local
+# NOTE: CLOUD_URL already ends in /v1 — the request path is {CLOUD_URL}/ingest.
 # ROOTSIGN_CLOUD_URL=https://ingest.getprovidex.com/v1
 # ROOTSIGN_API_KEY=your-api-key-here
+# Cloud transport tuning. HTTP_MAX_RETRIES counts TOTAL attempts (one send
+# plus at most two retries at the default of 3), and the transport is the only
+# layer that retries — the buffering client stands down when it wraps this one.
+# ROOTSIGN_HTTP_TIMEOUT_SECONDS=10
+# ROOTSIGN_HTTP_MAX_RETRIES=3
+# Offline spool root. Defaults to $ROOTSIGN_DATA_DIR/spool, so moving DATA_DIR
+# moves the spool with it; set this only to split them (e.g. a durable volume).
+# When the endpoint is unreachable, records land in <spool>/sessions/<id>.jsonl
+# — ordinary session files, so `rootsign verify --local` reads them while still
+# offline. Upload them later with `rootsign-admin sync`.
+# ROOTSIGN_SPOOL_DIR=~/.rootsign/spool
+# What to do when a record cannot be persisted at all — endpoint unreachable
+# AND the spool write failing (disk full, read-only mount). 'warn' (default)
+# drops telemetry with accounting: one CRITICAL, a loss tally at session close,
+# and a hash-evident gap so verify reports INCOMPLETE rather than VALID.
+# 'fail' raises into the caller instead — a halted agent over an incomplete
+# record. HiTL/approval records fail closed either way.
+# ROOTSIGN_ON_RECORD_LOSS=warn
 
 # Capture per-step Decision records (the agent's reasoning). Off by default
 # because Decision payloads are the largest and most PII-sensitive surface.
@@ -32,7 +51,8 @@ ROOTSIGN_CAPTURE_DECISIONS=false
 # The decorator drains this on the next successful call. Default: ~/.rootsign/wal
 ROOTSIGN_WAL_PATH=~/.rootsign/wal
 
-# Retry policy for HttpIngestClient (Phase 2 — unused in Phase 1).
+# LEGACY retry knobs — read by no code path. The cloud transport honors
+# ROOTSIGN_HTTP_TIMEOUT_SECONDS / ROOTSIGN_HTTP_MAX_RETRIES instead (above).
 ROOTSIGN_MAX_RETRIES=3
 ROOTSIGN_RETRY_BASE_DELAY=0.1
 ROOTSIGN_RETRY_MAX_DELAY=5.0

{rootsign-0.2.1 → rootsign-0.3.0}/.github/workflows/ci.yml

@@ -201,14 +201,17 @@ jobs:
           python-version: '3.12'
       - name: Install core only (no extras)
         run: pip install .
-      - name: Zero database packages resolved
+      - name: Zero database or cloud packages resolved
+        # httpx is in the `test`/`dev`/`mcp` extras, so a developer env always
+        # has it — this job is the only place its absence can be asserted
+        # (ADR-013 Decision 2).
         run: |
           python - <<'PY'
           import importlib.util as u
-          bad = [m for m in ("sqlalchemy","asyncpg","psycopg2","greenlet","alembic")
+          bad = [m for m in ("sqlalchemy","asyncpg","psycopg2","greenlet","alembic","httpx")
                  if u.find_spec(m) is not None]
-          assert not bad, f"core install pulled DB packages: {bad}"
-          print("no DB packages installed — OK")
+          assert not bad, f"core install pulled optional-extra packages: {bad}"
+          print("no DB or cloud packages installed — OK")
           PY
       - name: import rootsign + facade surface works DB-free
         run: |
@@ -238,6 +241,24 @@ jobs:
               assert "rootsign[postgres]" in str(e), e
               print("RootSignPostgresExtraRequired raised OK")
           PY
+      - name: cloud backend without extra raises actionable error
+        # The `cloud` extra's twin of the postgres check above (ADR-013 D2 /
+        # Sprint B T2.1). HttpIngestClient must stay importable without httpx
+        # and fail with the install command when it is actually selected.
+        env:
+          ROOTSIGN_BACKEND: cloud
+        run: |
+          python - <<'PY'
+          from rootsign.errors import RootSignCloudExtraRequired
+          from rootsign.sdk.client import HttpIngestClient, get_ingest_client
+          assert HttpIngestClient.owns_retry is True  # importable without the extra
+          try:
+              get_ingest_client()
+              raise SystemExit("expected RootSignCloudExtraRequired")
+          except RootSignCloudExtraRequired as e:
+              assert "rootsign[cloud]" in str(e), e
+              print("RootSignCloudExtraRequired raised OK")
+          PY
       - name: Console scripts run DB-free (CLI tripwire)
         # `import rootsign` passing is NOT sufficient. The console script entry
         # point imports `rootsign.sdk.cli`, a different import graph that the
@@ -256,6 +277,12 @@ jobs:
           rootsign-admin --help > /dev/null
           rootsign-admin start-db --help > /dev/null
           rootsign-admin stop-db --help > /dev/null
+          # `sync` is the cloud-extra command (ADR-013 D4 / T2.5). Its --help
+          # and its --dry-run must work on a bare install: reading the spool
+          # needs no extra, and --dry-run is how an operator finds out what is
+          # waiting before deciding whether to install anything.
+          rootsign-admin sync --help > /dev/null
+          rootsign-admin sync --dry-run > /dev/null
           # Store-exported fixture, not a checked-in file: let the JSONL backend
           # write a real session so the chain is produced by the same code path
           # that verifies it. Never hand-construct a self_hash (ADR-001).
@@ -277,6 +304,36 @@ jobs:
           PY
           )"
           rootsign verify --local "$HOME/.rootsign/sessions/$SESSION_ID.jsonl"
+          # Evidence export is a bare-install path too (ADR-014 / T3.5): it is
+          # how a cloud-mode user turns a spooled session into something they
+          # can hand to a compliance officer, and it must not need a database.
+          rootsign export --local "$HOME/.rootsign/sessions/$SESSION_ID.jsonl" \
+            --out "$HOME/bundles" | tee /tmp/export.out
+          grep -q "manifest.json SHA-256" /tmp/export.out || {
+            echo "export did not print the manifest anchor"; exit 1; }
+          rootsign export --check "$HOME/bundles/evidence-$SESSION_ID" | grep -q "INTACT" || {
+            echo "a freshly written bundle failed its own --check"; exit 1; }
+          # Verifying a *spooled* copy of that session must print the replay
+          # breadcrumb — `sync` lives on the operator CLI, so the developer CLI
+          # is where it has to be discoverable (ADR-013 Decision 4).
+          mkdir -p "$HOME/.rootsign/spool/sessions"
+          cp "$HOME/.rootsign/sessions/$SESSION_ID.jsonl" \
+             "$HOME/.rootsign/spool/sessions/$SESSION_ID.jsonl"
+          rootsign verify --local "$HOME/.rootsign/spool/sessions/$SESSION_ID.jsonl" \
+            | grep -q "rootsign-admin sync" || {
+              echo "verify --local on a spool file lost the sync breadcrumb"; exit 1; }
+          # And syncing it on a bare install must name the cloud extra rather
+          # than dying inside httpx's import graph.
+          out="$(ROOTSIGN_API_KEY=sk-ci rootsign-admin sync 2>&1)" && {
+            echo "expected sync to fail without the cloud extra"; exit 1; }
+          echo "$out" | grep -q "rootsign\[cloud\]" || {
+            echo "missing cloud install hint:"; echo "$out"; exit 1; }
+          # `if`, not `&& { }`: this block runs under `set -e`, where a
+          # grep that finds nothing would end the whole step with status 1.
+          if echo "$out" | grep -qi "Traceback"; then
+            echo "leaked traceback from sync"; echo "$out"; exit 1
+          fi
+          rm -rf "$HOME/.rootsign/spool"
           echo "console scripts OK, DB-free"
       - name: DB-backed subcommands fail with the install hint, not a traceback
         # The other half of the same bug: these commands legitimately need the
@@ -286,6 +343,7 @@ jobs:
           set -uo pipefail
           # Every DB-backed subcommand across BOTH console scripts.
           for cmd in "rootsign verify 550e8400-e29b-41d4-a716-446655440001" \
+                     "rootsign export 550e8400-e29b-41d4-a716-446655440001" \
                      "rootsign approve --list" \
                      "rootsign approve 550e8400-e29b-41d4-a716-446655440001" \
                      "rootsign-admin status" \

{rootsign-0.2.1 → rootsign-0.3.0}/CONTRIBUTING.md

@@ -69,12 +69,37 @@ docs(adr): add ADR-004 for retry strategy
 - Framework integrations must pass contract tests on all supported framework versions (see CI matrix)
 - Run `ruff check .` and `ruff format .` before pushing
 
+### Golden fixtures
+
+Three fixtures in `tests/fixtures/` freeze contracts that other people's code
+depends on. A failure against one is a decision, not a bug:
+
+| Fixture | Freezes | If it fails |
+| --- | --- | --- |
+| `hash_vectors.json` | the canonical Action hash (ADR-001) | stop — a new ADR is required, see below |
+| `redaction_vectors.json` | the PII rule-set mappings (ADR-006) | confirm the mapping change is intended |
+| `evidence_bundle_v1.json` | the `rootsign export` bundle schema (ADR-014) | see below |
+
+The bundle schema is read by Phase 2 tooling and by anything a partner builds
+on an exported bundle. **Additive** changes (a new optional field, content in
+the reserved `compliance` block) are fine — regenerate and commit the diff:
+
+```bash
+ROOTSIGN_UPDATE_GOLDEN=1 python -m pytest tests/unit/test_export_golden.py
+```
+
+Renaming or removing a field is a **bundle version bump**: change
+`EVIDENCE_BUNDLE_VERSION` in `rootsign/sdk/export.py` in the same PR, and say
+why in the description. Never regenerate a fixture to make a red test green
+without first deciding which of the two you are doing.
+
 ## What we will NOT merge
 
 - Changes to `compute_action_self_hash` canonical spec (see [ADR-001](docs/adr/ADR-001-hash-canonical-spec.md)) without a new ADR approved by the maintainer
 - Synchronous SQLAlchemy in any non-Alembic code
 - Mock-based integration tests (real PostgreSQL + TimescaleDB only — see [the data model rationale](AGENTS.md))
 - Any PR that reduces test coverage below 85% overall
+- A regenerated `evidence_bundle_v1.json` that renames or removes a field without a matching `EVIDENCE_BUNDLE_VERSION` bump (see [ADR-014](docs/adr/ADR-014-export-evidence-bundle.md))
 - Code that swallows ingest failures silently (RootSign's promise is that ingest never raises into the agent, but failures *must* be logged at WARNING level — see [ADR-002](docs/adr/ADR-002-transport-agnostic-client.md))
 
 ## Adding a new framework integration

{rootsign-0.2.1 → rootsign-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootsign
-Version: 0.2.1
+Version: 0.3.0
 Summary: RootSign — tamper-evident provenance logging for AI agents (powered by Providex AI)
 Author: Providex AI Inc.
 License: Apache-2.0
@@ -20,6 +20,8 @@ Requires-Dist: python-dotenv<2.0,>=1.0
 Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: autogen
 Requires-Dist: pyautogen>=0.2; extra == 'autogen'
+Provides-Extra: cloud
+Requires-Dist: httpx<1.0,>=0.27; extra == 'cloud'
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.28; extra == 'crewai'
 Provides-Extra: dev
@@ -89,13 +91,14 @@ Compliance-grade audit trails. Zero changes to your agent code.
 
 ## Status
 
-**v0.2.1.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping.
+**v0.3.0.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping — plus evidence bundles (`rootsign export`), the cloud transport with its offline spool, and a published wire spec.
 
 | Phase | Scope | Status |
 |---|---|---|
 | 0 | Data model + storage + ingest handler | ✅ Complete |
 | 1 | Python SDK — `@rootsign.trace`, LangGraph + CrewAI + MCP proxy, `rootsign verify` CLI, redaction, HiTL checkpoint, decision capture, micro-batching | ✅ v0.1.5 |
 | 1.5 | Zero-dependency onboarding — JSONL default backend, `rootsign.init()` facade | ✅ v0.2.0 |
+| 1.6 | Evidence bundles (`rootsign export`), cloud transport + offline spool, published ingest spec | ✅ v0.3.0 |
 | 2 | Hosted ingest backend + compliance dashboard | Planned |
 | 3 | Policy enforcement + incident workflow | Planned |
 | 4 | Cross-platform governance | Planned |
@@ -138,7 +141,7 @@ VALID ✓  —  2 records, chain intact
   Session:  f758a636-7bcd-4f96-8940-eff7d80e760a
 ```
 
-Exit code is `0` for VALID and `1` for TAMPERED, so this drops into CI or a cron audit. Change any character in any record and the verifier names the broken link:
+Exit code is `0` for VALID, `1` for TAMPERED (a record was altered) and `2` for INCOMPLETE (a record is missing) — so this drops into CI or a cron audit, and a script can tell theft from loss. Change any character in any record and the verifier names the broken link:
 
 ```bash
 $ rootsign verify --local ~/.rootsign/sessions/f758a636-7bcd-4f96-8940-eff7d80e760a.jsonl
@@ -148,7 +151,27 @@ TAMPERED ✗  —  chain broken at record #1
 WARNING: This session log may have been tampered with.
 ```
 
-That's the whole surface: **`init()` → `session()` → `@trace` / `wrap_tools()` → `verify`.** `init()` is synchronous and does no I/O, so it's safe at module scope and inside a running event loop (notebooks, FastAPI startup); the agent record is get-or-created on the first `session()` entry, keyed on `(name, environment)`. Re-running your script never re-registers.
+When someone outside engineering needs to see it, turn the same session into a self-contained evidence bundle:
+
+```bash
+$ rootsign export --local ~/.rootsign/sessions/f758a636-7bcd-4f96-8940-eff7d80e760a.jsonl
+VALID — 2 records, chain intact
+  Bundle:   ./evidence-f758a636-7bcd-4f96-8940-eff7d80e760a
+            redaction.json
+            report.html
+            report.md
+            timeline.json
+            verification.json
+            manifest.json
+
+  manifest.json SHA-256:  a1d61338d0f793ea03ac472863fadea5660e1e94846913ce7613d8c117d67cc5
+  Record that hash outside the bundle — a ticket, an email, a chain-of-custody log.
+  It is what proves a bundle you receive later is the one that was generated.
+```
+
+Open `report.html` in any browser — [see below](#evidence-bundles).
+
+That's the whole surface: **`init()` → `session()` → `@trace` / `wrap_tools()` → `verify` → `export`.** `init()` is synchronous and does no I/O, so it's safe at module scope and inside a running event loop (notebooks, FastAPI startup); the agent record is get-or-created on the first `session()` entry, keyed on `(name, environment)`. Re-running your script never re-registers.
 
 A runnable version of the above is [`examples/quickstart-jsonl`](examples/quickstart-jsonl/).
 
@@ -384,6 +407,94 @@ tools = rootsign.wrap_tools([send_invoice], redaction_config=redaction)
 
 `FinancialPIIConfig` adds account / routing / IBAN patterns; `HealthcarePIIConfig` adds MRN / NPI / DOB. Each accepts `extra_rules={...}` for domain-specific patterns without subclassing. See [ADR-006](docs/adr/ADR-006-redaction-contract.md).
 
+## Evidence bundles
+
+A verified hash chain answers a developer's question. A compliance officer asks a different one — *what did this agent do, who approved it, and can I trust this file?* — and cannot read JSONL to find out.
+
+`rootsign export` turns one session into a directory that answers it:
+
+```bash
+$ rootsign export --local ~/.rootsign/sessions/<session_id>.jsonl --out ./bundles
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Providex-AI/rootsign/main/docs/evidence-report.png" alt="RootSign evidence report — a VALID verdict banner, the session and agent identity block, the per-record chain table with self_hash and prev_action_hash, and the start of the session narrative" width="700" />
+</p>
+
+<p align="center"><em><code>report.html</code> — the verdict first, then the chain, then what happened.</em></p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Providex-AI/rootsign/main/docs/evidence-report-approval.png" alt="Further down the same report: the wire_transfer action recorded as human_rejected with no output hash, directly above the approval that rejected it — approver, reason, latency, and the context they were shown" width="700" />
+</p>
+
+<p align="center"><em>Further down: a £250,000 transfer the agent proposed, the human who refused it, and the context they were shown.</em></p>
+
+| File | What it holds |
+|---|---|
+| `manifest.json` | bundle version, generator, agent identity, source backend, a SHA-256 for every other file, and a reserved `compliance` block |
+| `verification.json` | the verdict plus a per-record listing — sequence, `action_id`, `self_hash`, `prev_action_hash`, and whether that record was verified |
+| `timeline.json` | the session narrative in order: open → decisions → actions → approvals → close, with every field each record carries |
+| `redaction.json` | which field paths held the `[REDACTED]` sentinel — the "PII was never stored" evidence |
+| `report.md` / `report.html` | human renderings of exactly the above; the verdict is the first thing on the page |
+
+Three properties make the bundle worth handing over:
+
+**It is rendered from the JSON, never assembled twice.** Markdown and HTML are pure functions of the three JSON documents, so a fact that is not in the machine-readable evidence cannot appear in the human-readable report. The HTML has no JavaScript and no external requests — it opens identically from a file share, an email attachment, or an air-gapped review machine.
+
+**It says what it does not know.** A session that stored only hashes says *"payload previews not retained for this session"* rather than showing empty fields. Records after a chain break are marked `unverified`, not `verified` — the verifier stopped there and proved nothing about them. `redaction.json` reports the paths that were redacted and explicitly does not claim which rule fired, because RootSign does not record that.
+
+**It is self-verifying, and honest about the limit.** `manifest.json` carries a SHA-256 for every file, and the manifest's own hash is printed at export. Record that hash somewhere outside the bundle:
+
+```bash
+$ rootsign export --check ./bundles/evidence-<session_id>
+✓  INTACT — 5 file(s) match manifest.json
+
+  manifest.json SHA-256:  a1d61338d0f793ea03ac472863fadea5660e1e94846913ce7613d8c117d67cc5
+  Compare this against the hash recorded when the bundle was exported.
+  The file checks above cannot detect an edit that also updated the manifest.
+```
+
+Re-hashing files against the manifest proves the bundle is internally consistent — nothing more. Someone who edits a file *and* updates the manifest passes that check trivially. The out-of-band manifest hash is the only anchor they cannot forge, which is why `--check` prints it whether or not anything is wrong.
+
+For bundles leaving the building, `--redact-previews` withholds every field that carries stored content — payload previews, the context a human was shown at a checkpoint, and captured decision summaries — and names what it withheld, so the recipient knows what to ask for rather than guessing whether a field was stripped or never existed. Hashes, identities and timings are unaffected: the chain still verifies.
+
+`--format json|md|html` narrows the renderings; it never drops the machine truth. `rootsign export <session_id>` reads a Postgres-backed session (agent name, owner and risk tier come along, since those live in the registration row). See [ADR-014](docs/adr/ADR-014-export-evidence-bundle.md).
+
+## Offline & sync (cloud mode)
+
+Set `ROOTSIGN_BACKEND=cloud` and records go to the hosted ingest endpoint (`pip install 'rootsign[cloud]'`). The interesting part is what happens when that endpoint is not there.
+
+**Nothing is lost, and the agent never notices.** When retries are exhausted, the SDK fails over to the same append-only writer the local backend uses, rooted at `$ROOTSIGN_DATA_DIR/spool/`. One WARNING is logged — not one per record — and your tool calls keep returning their real results, because an audit layer that halts the business it observes has inverted its own value.
+
+**Spooled records are ordinary session files**, so the evidence is usable before it is uploaded:
+
+```bash
+$ rootsign verify --local ~/.rootsign/spool/sessions/<session_id>.jsonl
+VALID ✓  —  2 records, chain intact
+  Session:  2d333ca5-7b28-4cd3-80b4-8f67350d19ba
+
+This is a spooled session — recorded locally because the cloud endpoint was unreachable.
+Upload it (and everything else waiting) with:
+
+    rootsign-admin sync
+```
+
+> A file that spooled **mid-session** verifies as `INCOMPLETE`, not `VALID` — the records from before the outage went over the wire and are not in it. That is the honest answer: the verifier is reading one file, and "this file is the whole session" is not a claim anyone can make offline. Sync it and the store's copy verifies `VALID`.
+
+**When connectivity returns, upload:**
+
+```bash
+$ rootsign-admin sync
+1 spooled session(s), 4 record(s) under ~/.rootsign/spool
+Uploading to https://ingest.getprovidex.com/v1/ingest
+  synced    2d333ca5-7b28-4cd3-80b4-8f67350d19ba  4 accepted, 0 already present -> synced/
+All spooled sessions uploaded.
+```
+
+Safe to re-run: idempotency is server-side by `event_id`, so a partially uploaded session resumes and records the store already has count as delivered. Fully-uploaded files move to `spool/synced/`; a partial one stays put and reports the first rejected sequence. `--dry-run` lists what is waiting without contacting anything, and works on a bare install.
+
+**The chain spans the outage.** Records written to the spool continue the sequence the wire path started, because the chain is sealed before the SDK chooses a destination — so after sync the store holds one unbroken session, not two fragments. If the disk *also* fails, telemetry drops with accounting (one CRITICAL, a loss ledger, and a chain gap that makes the loss provable as `INCOMPLETE`) while anything gated by a human approval fails closed and the tool never runs. See [ADR-013](docs/adr/ADR-013-http-ingest-client-spool.md).
+
 ## Micro-batching (opt-in)
 
 `BufferedIngestClient` wraps any ingest client and buffers `ACTION_RECORD`s in memory, flushing asynchronously — so a long, tool-heavy pipeline doesn't pay a per-call ingest round-trip. Enable it with `ROOTSIGN_BUFFERED=true` (the factory wraps the transport for you), or wrap explicitly:
@@ -426,14 +537,16 @@ The `-m benchmark` marker keeps the performance suite opt-in. Run it **without**
 * **`@rootsign.trace`** wraps a tool callable and emits an `ACTION_RECORD` envelope per call. LangGraph `BaseTool` and CrewAI tools are detected automatically.
 * **MCP proxy** — `create_proxy_app` intercepts MCP `tools/call` at the protocol layer, so any MCP-compatible agent is instrumented without a framework adapter (ADR-010).
 * **`rootsign.init()`** stores config with no I/O; `rootsign.session()` resolves the backend lazily on first entry and publishes `(ctx, client)` in a `ContextVar`, which is how `wrap_tools` / `@trace` / the MCP proxy find them without arguments (ADR-012).
-* **`JsonlIngestClient`** is the default transport: append-only JSONL under `~/.rootsign`, no dependencies (ADR-011). **`LocalIngestClient`** is the Postgres in-process path; a `HttpIngestClient` for the hosted backend lands in Phase 2. **`BufferedIngestClient`** optionally wraps any of them for async micro-batching (ADR-009).
+* **`JsonlIngestClient`** is the default transport: append-only JSONL under `~/.rootsign`, no dependencies (ADR-011). **`LocalIngestClient`** is the Postgres in-process path. **`HttpIngestClient`** is the hosted-backend transport behind the optional `cloud` extra — it seals the chain client-side, owns its retry budget, and fails over to an on-disk spool rather than losing records (ADR-013). **`BufferedIngestClient`** optionally wraps any of them for async micro-batching (ADR-009).
 * **Hash chain** is per-session: each `Action` carries `prev_action_hash` so reconstructing the chain detects any after-the-fact modification.
+* **The wire format is published**, not internal: [docs/ingest-spec-v1.md](docs/ingest-spec-v1.md) specifies the envelope, the five event types, the full error-code registry, idempotency by `event_id`, batch semantics, and the client-side hashing contract for cloud mode — the server recomputes every hash and never trusts one. It is the contract the Phase 2 backend, the TypeScript SDK, and any community connector implement, and the document a design partner's security reviewer asks for.
 * **`HiTLCheckpoint`** is an async poll loop that opens its own DB session per cycle — see ADR-007 for the loop-binding rationale.
+* **`rootsign export`** builds the evidence bundle: JSON documents first, Markdown and HTML rendered from those and nothing else, with a SHA-256 per file in `manifest.json` (ADR-014). `rootsign-admin sync` is its counterpart on the operator CLI — batch replay of anything the spool caught while the endpoint was down.
 * **Storage** is either the JSONL writer (default, zero-dependency) or PostgreSQL 16 + TimescaleDB 2.14, where the `actions` table is a hypertable and the chain stays intact across chunks. Both use the same frozen canonical hash formula (ADR-001) — `rootsign verify` gives the same verdict either way.
 
 ## What's next
 
-* **Phase 2 cloud backend** — `HttpIngestClient` + hosted compliance dashboard. Drop-in replacement for `LocalIngestClient`; `BufferedIngestClient` already removes the per-call round-trip latency it would otherwise add.
+* **Phase 2 hosted backend** — the ingest service and compliance dashboard the client already speaks to. `HttpIngestClient` ships now against the published [wire spec](docs/ingest-spec-v1.md), so the SDK half is done and tested against a mock server; cloud-sourced `rootsign export` waits on the server read API.
 * **Web UI for HiTL** — approve/reject pending actions from a browser instead of the CLI.
 * **AutoGen integration** — same duck-typing shape as CrewAI.
 

{rootsign-0.2.1 → rootsign-0.3.0}/README.md

@@ -27,13 +27,14 @@ Compliance-grade audit trails. Zero changes to your agent code.
 
 ## Status
 
-**v0.2.1.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping.
+**v0.3.0.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping — plus evidence bundles (`rootsign export`), the cloud transport with its offline spool, and a published wire spec.
 
 | Phase | Scope | Status |
 |---|---|---|
 | 0 | Data model + storage + ingest handler | ✅ Complete |
 | 1 | Python SDK — `@rootsign.trace`, LangGraph + CrewAI + MCP proxy, `rootsign verify` CLI, redaction, HiTL checkpoint, decision capture, micro-batching | ✅ v0.1.5 |
 | 1.5 | Zero-dependency onboarding — JSONL default backend, `rootsign.init()` facade | ✅ v0.2.0 |
+| 1.6 | Evidence bundles (`rootsign export`), cloud transport + offline spool, published ingest spec | ✅ v0.3.0 |
 | 2 | Hosted ingest backend + compliance dashboard | Planned |
 | 3 | Policy enforcement + incident workflow | Planned |
 | 4 | Cross-platform governance | Planned |
@@ -76,7 +77,7 @@ VALID ✓  —  2 records, chain intact
   Session:  f758a636-7bcd-4f96-8940-eff7d80e760a
 ```
 
-Exit code is `0` for VALID and `1` for TAMPERED, so this drops into CI or a cron audit. Change any character in any record and the verifier names the broken link:
+Exit code is `0` for VALID, `1` for TAMPERED (a record was altered) and `2` for INCOMPLETE (a record is missing) — so this drops into CI or a cron audit, and a script can tell theft from loss. Change any character in any record and the verifier names the broken link:
 
 ```bash
 $ rootsign verify --local ~/.rootsign/sessions/f758a636-7bcd-4f96-8940-eff7d80e760a.jsonl
@@ -86,7 +87,27 @@ TAMPERED ✗  —  chain broken at record #1
 WARNING: This session log may have been tampered with.
 ```
 
-That's the whole surface: **`init()` → `session()` → `@trace` / `wrap_tools()` → `verify`.** `init()` is synchronous and does no I/O, so it's safe at module scope and inside a running event loop (notebooks, FastAPI startup); the agent record is get-or-created on the first `session()` entry, keyed on `(name, environment)`. Re-running your script never re-registers.
+When someone outside engineering needs to see it, turn the same session into a self-contained evidence bundle:
+
+```bash
+$ rootsign export --local ~/.rootsign/sessions/f758a636-7bcd-4f96-8940-eff7d80e760a.jsonl
+VALID — 2 records, chain intact
+  Bundle:   ./evidence-f758a636-7bcd-4f96-8940-eff7d80e760a
+            redaction.json
+            report.html
+            report.md
+            timeline.json
+            verification.json
+            manifest.json
+
+  manifest.json SHA-256:  a1d61338d0f793ea03ac472863fadea5660e1e94846913ce7613d8c117d67cc5
+  Record that hash outside the bundle — a ticket, an email, a chain-of-custody log.
+  It is what proves a bundle you receive later is the one that was generated.
+```
+
+Open `report.html` in any browser — [see below](#evidence-bundles).
+
+That's the whole surface: **`init()` → `session()` → `@trace` / `wrap_tools()` → `verify` → `export`.** `init()` is synchronous and does no I/O, so it's safe at module scope and inside a running event loop (notebooks, FastAPI startup); the agent record is get-or-created on the first `session()` entry, keyed on `(name, environment)`. Re-running your script never re-registers.
 
 A runnable version of the above is [`examples/quickstart-jsonl`](examples/quickstart-jsonl/).
 
@@ -322,6 +343,94 @@ tools = rootsign.wrap_tools([send_invoice], redaction_config=redaction)
 
 `FinancialPIIConfig` adds account / routing / IBAN patterns; `HealthcarePIIConfig` adds MRN / NPI / DOB. Each accepts `extra_rules={...}` for domain-specific patterns without subclassing. See [ADR-006](docs/adr/ADR-006-redaction-contract.md).
 
+## Evidence bundles
+
+A verified hash chain answers a developer's question. A compliance officer asks a different one — *what did this agent do, who approved it, and can I trust this file?* — and cannot read JSONL to find out.
+
+`rootsign export` turns one session into a directory that answers it:
+
+```bash
+$ rootsign export --local ~/.rootsign/sessions/<session_id>.jsonl --out ./bundles
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Providex-AI/rootsign/main/docs/evidence-report.png" alt="RootSign evidence report — a VALID verdict banner, the session and agent identity block, the per-record chain table with self_hash and prev_action_hash, and the start of the session narrative" width="700" />
+</p>
+
+<p align="center"><em><code>report.html</code> — the verdict first, then the chain, then what happened.</em></p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Providex-AI/rootsign/main/docs/evidence-report-approval.png" alt="Further down the same report: the wire_transfer action recorded as human_rejected with no output hash, directly above the approval that rejected it — approver, reason, latency, and the context they were shown" width="700" />
+</p>
+
+<p align="center"><em>Further down: a £250,000 transfer the agent proposed, the human who refused it, and the context they were shown.</em></p>
+
+| File | What it holds |
+|---|---|
+| `manifest.json` | bundle version, generator, agent identity, source backend, a SHA-256 for every other file, and a reserved `compliance` block |
+| `verification.json` | the verdict plus a per-record listing — sequence, `action_id`, `self_hash`, `prev_action_hash`, and whether that record was verified |
+| `timeline.json` | the session narrative in order: open → decisions → actions → approvals → close, with every field each record carries |
+| `redaction.json` | which field paths held the `[REDACTED]` sentinel — the "PII was never stored" evidence |
+| `report.md` / `report.html` | human renderings of exactly the above; the verdict is the first thing on the page |
+
+Three properties make the bundle worth handing over:
+
+**It is rendered from the JSON, never assembled twice.** Markdown and HTML are pure functions of the three JSON documents, so a fact that is not in the machine-readable evidence cannot appear in the human-readable report. The HTML has no JavaScript and no external requests — it opens identically from a file share, an email attachment, or an air-gapped review machine.
+
+**It says what it does not know.** A session that stored only hashes says *"payload previews not retained for this session"* rather than showing empty fields. Records after a chain break are marked `unverified`, not `verified` — the verifier stopped there and proved nothing about them. `redaction.json` reports the paths that were redacted and explicitly does not claim which rule fired, because RootSign does not record that.
+
+**It is self-verifying, and honest about the limit.** `manifest.json` carries a SHA-256 for every file, and the manifest's own hash is printed at export. Record that hash somewhere outside the bundle:
+
+```bash
+$ rootsign export --check ./bundles/evidence-<session_id>
+✓  INTACT — 5 file(s) match manifest.json
+
+  manifest.json SHA-256:  a1d61338d0f793ea03ac472863fadea5660e1e94846913ce7613d8c117d67cc5
+  Compare this against the hash recorded when the bundle was exported.
+  The file checks above cannot detect an edit that also updated the manifest.
+```
+
+Re-hashing files against the manifest proves the bundle is internally consistent — nothing more. Someone who edits a file *and* updates the manifest passes that check trivially. The out-of-band manifest hash is the only anchor they cannot forge, which is why `--check` prints it whether or not anything is wrong.
+
+For bundles leaving the building, `--redact-previews` withholds every field that carries stored content — payload previews, the context a human was shown at a checkpoint, and captured decision summaries — and names what it withheld, so the recipient knows what to ask for rather than guessing whether a field was stripped or never existed. Hashes, identities and timings are unaffected: the chain still verifies.
+
+`--format json|md|html` narrows the renderings; it never drops the machine truth. `rootsign export <session_id>` reads a Postgres-backed session (agent name, owner and risk tier come along, since those live in the registration row). See [ADR-014](docs/adr/ADR-014-export-evidence-bundle.md).
+
+## Offline & sync (cloud mode)
+
+Set `ROOTSIGN_BACKEND=cloud` and records go to the hosted ingest endpoint (`pip install 'rootsign[cloud]'`). The interesting part is what happens when that endpoint is not there.
+
+**Nothing is lost, and the agent never notices.** When retries are exhausted, the SDK fails over to the same append-only writer the local backend uses, rooted at `$ROOTSIGN_DATA_DIR/spool/`. One WARNING is logged — not one per record — and your tool calls keep returning their real results, because an audit layer that halts the business it observes has inverted its own value.
+
+**Spooled records are ordinary session files**, so the evidence is usable before it is uploaded:
+
+```bash
+$ rootsign verify --local ~/.rootsign/spool/sessions/<session_id>.jsonl
+VALID ✓  —  2 records, chain intact
+  Session:  2d333ca5-7b28-4cd3-80b4-8f67350d19ba
+
+This is a spooled session — recorded locally because the cloud endpoint was unreachable.
+Upload it (and everything else waiting) with:
+
+    rootsign-admin sync
+```
+
+> A file that spooled **mid-session** verifies as `INCOMPLETE`, not `VALID` — the records from before the outage went over the wire and are not in it. That is the honest answer: the verifier is reading one file, and "this file is the whole session" is not a claim anyone can make offline. Sync it and the store's copy verifies `VALID`.
+
+**When connectivity returns, upload:**
+
+```bash
+$ rootsign-admin sync
+1 spooled session(s), 4 record(s) under ~/.rootsign/spool
+Uploading to https://ingest.getprovidex.com/v1/ingest
+  synced    2d333ca5-7b28-4cd3-80b4-8f67350d19ba  4 accepted, 0 already present -> synced/
+All spooled sessions uploaded.
+```
+
+Safe to re-run: idempotency is server-side by `event_id`, so a partially uploaded session resumes and records the store already has count as delivered. Fully-uploaded files move to `spool/synced/`; a partial one stays put and reports the first rejected sequence. `--dry-run` lists what is waiting without contacting anything, and works on a bare install.
+
+**The chain spans the outage.** Records written to the spool continue the sequence the wire path started, because the chain is sealed before the SDK chooses a destination — so after sync the store holds one unbroken session, not two fragments. If the disk *also* fails, telemetry drops with accounting (one CRITICAL, a loss ledger, and a chain gap that makes the loss provable as `INCOMPLETE`) while anything gated by a human approval fails closed and the tool never runs. See [ADR-013](docs/adr/ADR-013-http-ingest-client-spool.md).
+
 ## Micro-batching (opt-in)
 
 `BufferedIngestClient` wraps any ingest client and buffers `ACTION_RECORD`s in memory, flushing asynchronously — so a long, tool-heavy pipeline doesn't pay a per-call ingest round-trip. Enable it with `ROOTSIGN_BUFFERED=true` (the factory wraps the transport for you), or wrap explicitly:
@@ -364,14 +473,16 @@ The `-m benchmark` marker keeps the performance suite opt-in. Run it **without**
 * **`@rootsign.trace`** wraps a tool callable and emits an `ACTION_RECORD` envelope per call. LangGraph `BaseTool` and CrewAI tools are detected automatically.
 * **MCP proxy** — `create_proxy_app` intercepts MCP `tools/call` at the protocol layer, so any MCP-compatible agent is instrumented without a framework adapter (ADR-010).
 * **`rootsign.init()`** stores config with no I/O; `rootsign.session()` resolves the backend lazily on first entry and publishes `(ctx, client)` in a `ContextVar`, which is how `wrap_tools` / `@trace` / the MCP proxy find them without arguments (ADR-012).
-* **`JsonlIngestClient`** is the default transport: append-only JSONL under `~/.rootsign`, no dependencies (ADR-011). **`LocalIngestClient`** is the Postgres in-process path; a `HttpIngestClient` for the hosted backend lands in Phase 2. **`BufferedIngestClient`** optionally wraps any of them for async micro-batching (ADR-009).
+* **`JsonlIngestClient`** is the default transport: append-only JSONL under `~/.rootsign`, no dependencies (ADR-011). **`LocalIngestClient`** is the Postgres in-process path. **`HttpIngestClient`** is the hosted-backend transport behind the optional `cloud` extra — it seals the chain client-side, owns its retry budget, and fails over to an on-disk spool rather than losing records (ADR-013). **`BufferedIngestClient`** optionally wraps any of them for async micro-batching (ADR-009).
 * **Hash chain** is per-session: each `Action` carries `prev_action_hash` so reconstructing the chain detects any after-the-fact modification.
+* **The wire format is published**, not internal: [docs/ingest-spec-v1.md](docs/ingest-spec-v1.md) specifies the envelope, the five event types, the full error-code registry, idempotency by `event_id`, batch semantics, and the client-side hashing contract for cloud mode — the server recomputes every hash and never trusts one. It is the contract the Phase 2 backend, the TypeScript SDK, and any community connector implement, and the document a design partner's security reviewer asks for.
 * **`HiTLCheckpoint`** is an async poll loop that opens its own DB session per cycle — see ADR-007 for the loop-binding rationale.
+* **`rootsign export`** builds the evidence bundle: JSON documents first, Markdown and HTML rendered from those and nothing else, with a SHA-256 per file in `manifest.json` (ADR-014). `rootsign-admin sync` is its counterpart on the operator CLI — batch replay of anything the spool caught while the endpoint was down.
 * **Storage** is either the JSONL writer (default, zero-dependency) or PostgreSQL 16 + TimescaleDB 2.14, where the `actions` table is a hypertable and the chain stays intact across chunks. Both use the same frozen canonical hash formula (ADR-001) — `rootsign verify` gives the same verdict either way.
 
 ## What's next
 
-* **Phase 2 cloud backend** — `HttpIngestClient` + hosted compliance dashboard. Drop-in replacement for `LocalIngestClient`; `BufferedIngestClient` already removes the per-call round-trip latency it would otherwise add.
+* **Phase 2 hosted backend** — the ingest service and compliance dashboard the client already speaks to. `HttpIngestClient` ships now against the published [wire spec](docs/ingest-spec-v1.md), so the SDK half is done and tested against a mock server; cloud-sourced `rootsign export` waits on the server read API.
 * **Web UI for HiTL** — approve/reject pending actions from a browser instead of the CLI.
 * **AutoGen integration** — same duck-typing shape as CrewAI.