rootsign 0.2.0__tar.gz → 0.3.0__tar.gz

{rootsign-0.2.0 → 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.3.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+# Dependabot keeps the SHA-pinned GitHub Actions fresh.
+#
+# Why this file exists: `.github/workflows/release.yml` pins
+# pypa/gh-action-pypi-publish to an immutable commit SHA rather than the
+# mutable `release/v1` branch (CodeQL actions/unpinned-tag). That closes the
+# supply-chain hole on the step that mints our PyPI Trusted Publishing OIDC
+# token — but a hand-pinned SHA rots silently, which is its own risk. Dependabot
+# bumps the pin and rewrites the trailing `# vX.Y.Z` comment for us, so the pin
+# stays both immutable and current.
+#
+# Scope note: only `github-actions` is enabled. The Python dependency surface is
+# deliberately left to security alerts rather than routine version-update PRs —
+# the framework-contract CI jobs pin langgraph/crewai to specific minor ranges
+# on purpose, and version-bump PRs against those would be noise.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      # Matches the repo convention: type(scope): short description
+      prefix: "chore(ci)"
+    labels:
+      - dependencies
+    groups:
+      # One PR per week for routine action bumps instead of one per action.
+      # Security-relevant bumps still arrive on their own via alerts.
+      github-actions:
+        patterns:
+          - "*"

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

@@ -6,6 +6,13 @@ on:
   pull_request:
     branches: [main]
 
+# Least privilege for every job below. CI only ever reads the repo — no job
+# publishes, comments, or writes checks — so the read-only default holds for
+# all of them and no job needs an override. Without this block the workflow
+# inherits the repo-wide default token scopes (CodeQL actions/missing-workflow-permissions).
+permissions:
+  contents: read
+
 jobs:
   unit-tests:
     name: Unit tests (Python ${{ matrix.python-version }})
@@ -38,8 +45,8 @@ jobs:
       TEST_DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
       TEST_DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install
@@ -81,8 +88,8 @@ jobs:
       TEST_DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
       TEST_DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       # mcp extra so the DB-backed MCP proxy integration test
@@ -118,8 +125,8 @@ jobs:
     env:
       ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install with langgraph extra
@@ -146,8 +153,8 @@ jobs:
     env:
       ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install with crewai extra
@@ -170,8 +177,8 @@ jobs:
     env:
       ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install with mcp extra
@@ -188,20 +195,23 @@ jobs:
     name: No-extras install (DB-free core)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           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: |
@@ -231,6 +241,120 @@ 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
+        # checks above never touch — a module-level `from rootsign.database
+        # import AsyncSessionLocal` there crashed EVERY `rootsign ...`
+        # invocation on a bare install (even `version` and `verify --local`,
+        # neither of which needs a DB) while this job stayed green. This step
+        # exercises the script itself so that class of regression fails here.
+        run: |
+          set -euo pipefail
+          rootsign version
+          rootsign --help > /dev/null
+          # The operator CLI is a separate entry point (rootsign.cli:app) with
+          # its own import graph. --help and the docker-only subcommands must
+          # work without the postgres extra.
+          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).
+          SESSION_ID="$(python - <<'PY'
+          import asyncio, rootsign
+
+          rootsign.init(agent="ci-tripwire")
+
+          @rootsign.trace()
+          async def add(a: int, b: int) -> int:
+              return a + b
+
+          async def main():
+              async with rootsign.session() as ctx:
+                  await add(2, 3)
+                  return ctx.session_id
+
+          print(asyncio.run(main()))
+          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
+        # extra, but must say so in one line and exit 1 rather than dumping a
+        # ModuleNotFoundError traceback at the user.
+        run: |
+          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-admin init"; do
+            out="$($cmd 2>&1)" && { echo "expected failure: $cmd"; exit 1; }
+            echo "$out" | grep -q "rootsign\[postgres\]" || {
+              echo "missing install hint for: $cmd"; echo "$out"; exit 1; }
+            echo "$out" | grep -qi "Traceback" && {
+              echo "leaked traceback for: $cmd"; echo "$out"; exit 1; }
+            echo "$cmd -> actionable error OK"
+          done
       # NOTE: we deliberately do NOT run `pytest tests/contract/no_extras/`
       # here — the root tests/conftest.py imports sqlalchemy at module level
       # (for the DB fixtures), so pytest cannot even collect in a DB-free env.

{rootsign-0.2.0 → rootsign-0.3.0}/.github/workflows/release.yml

@@ -22,8 +22,8 @@ jobs:
     permissions:
       id-token: write # required for Trusted Publishing (OIDC)
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 
@@ -48,4 +48,10 @@ jobs:
           twine check dist/*
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        # Pinned to an immutable commit SHA, not the mutable `release/v1`
+        # branch. This step runs with `id-token: write` and mints the OIDC
+        # token that PyPI Trusted Publishing exchanges for upload rights to
+        # the `rootsign` project — anyone able to move that branch could
+        # publish a release under our name. SHA below == tag v1.14.2.
+        # Bump deliberately; verify the new SHA against the release tag.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

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

@@ -20,6 +20,7 @@ docker-compose up -d db          # PostgreSQL + TimescaleDB
 rootsign-admin init              # alembic upgrade head
 python -m pytest tests/unit/ -v          # unit tests (no DB needed at runtime — see note)
 python -m pytest tests/integration/ -v   # integration tests (needs DB)
+python -m pytest -m benchmark -v         # performance budgets (opt-in — see note)
 ```
 
 > **Python:** RootSign requires Python 3.11 or 3.12. We do not support 3.10 or below.
@@ -29,6 +30,12 @@ python -m pytest tests/integration/ -v   # integration tests (needs DB)
 > **Always invoke pytest as `python -m pytest`.** If you `brew install`-ed pytest, the system binary will resolve ahead of the venv's pytest on PATH and run under the system Python — which does not see your venv's site-packages and will fail with confusing `ModuleNotFoundError` (typically on `sqlalchemy` first). `python -m pytest` always uses the venv's interpreter.
 >
 > **Note on unit tests:** The session-scoped `_bootstrap_test_db` fixture in `tests/conftest.py` runs alembic against the test DB before any test (including unit tests). Bring `docker-compose up -d db` up first.
+>
+> **Performance benchmarks are opt-in.** Everything under `tests/performance/` is marked `benchmark` and is **skipped** by a default `python -m pytest` run; pass `-m benchmark` to execute it. These tests assert wall-clock budgets, so they are the most hardware-sensitive part of the suite — `test_1000_actions_under_2_seconds` has only ~1.36x headroom on a developer laptop. They are deliberately kept out of every CI gating job: a timing budget that reddens `main` for reasons unrelated to the diff teaches people to ignore red. Run them locally (or on purpose in CI) when touching the ingest, hashing, or verify paths.
+>
+> **The thresholds are ACs and do not move.** To keep them honest without making them flaky, each budget is sampled several times and asserted on the **median** (`tests/performance/_bench.py`). A single stalled run barely shifts a median, while a real regression shifts every sample — so the AC stays exactly as specified and the measurement stops reacting to background load, cold caches, or a noisy neighbour. Failures print every sample, not just the median, so you can see the spread. `test_p99_overhead_under_5ms` is the exception: it already asserts on the p99 of 1,000 calls, so it is a distribution by construction.
+>
+> These numbers are still **hardware- and environment-dependent** — they measure your disk, your Postgres tuning, and whatever else the machine is doing. Treat a failure as a prompt to investigate on an idle machine, not as proof of a regression. For scale: a trial run of `test_1000_actions_under_2_seconds` produced samples of 1.6s / 2.4s / 1.4s on an idle laptop; the 2.4s sample alone exceeds the 2.0s budget, which is exactly why the median exists.
 
 ## Branch naming
 
@@ -62,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.0 → rootsign-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rootsign
-Version: 0.2.0
+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.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.
+**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.