russell@unturf.com
0cd96ab1d7
Pyramid web app for inspecting arborist Merkle trees over sharded SQLite: document roots, inclusion proofs, an interactive 3D Merkle lattice (six.js / WebGL with graceful fallback), audit-chain linkage, and a live SSE event stream. Generated artifacts (env/, vendored static/six/ bundles, demo databases) are gitignored and rebuilt via the Makefile (venv, six, init-db, serve).
103 lines
3.8 KiB
ReStructuredText
103 lines
3.8 KiB
ReStructuredText
arborist-viz — Merkle Command Center
|
||
====================================
|
||
|
||
A configurable, proof-native browser dashboard for inspecting arborist's
|
||
content-addressed state — Merkle roots, proof paths, claim warrants,
|
||
audit trails, run-DAGs, claim graveyards, and (gated) 3D state geometry
|
||
and circuit/activation traces.
|
||
|
||
This is the **sibling repo** for ticket #000069 (arborist VIZ / Merkle
|
||
Command Center). The §3-corrected unturf-native stack:
|
||
|
||
* **Backend** — Pyramid + Jinja2 + SQLAlchemy + waitress (Python 3.10+).
|
||
* **Streaming** — SSE (``text/event-stream``) directly off arborist's
|
||
audit chain. No NATS, no WebSockets, no Node.
|
||
* **Frontend** — vanilla JS, no build step. ``six.js`` (fox's
|
||
CWE-407-patched three.js fork, vendored from ``~/git/cupPCB/cdn/six``)
|
||
drives the 3D widgets in later phases.
|
||
* **Storage** — SQLite for dashboard metadata. arborist shards stay the
|
||
source of truth and are imported read-only via ``arborist.embed``.
|
||
|
||
Hard constraints (from the ticket)
|
||
----------------------------------
|
||
|
||
1. **Projects state, never asserts it.** Every widget exposes the query
|
||
and source roots it derived from (§19.3).
|
||
2. **Soft signals never enter the proof path** (CLAUDE.md soft/hard-hash
|
||
rule). Activation/circuit traces inherit #000049's cage verbatim.
|
||
3. **Private-leaf default-deny.** ``privacy.reveal_private_leaves`` is
|
||
``false`` by default; commitments and selective-disclosure objects
|
||
only.
|
||
4. **Pyramid stays the truth.** Browser-side proof verification is a
|
||
v1 non-goal — the Pyramid view computes the proof and returns
|
||
PASS/FAIL + receipt.
|
||
|
||
Quick start
|
||
-----------
|
||
|
||
::
|
||
|
||
git clone https://git.unturf.com/engineering/arborist-viz
|
||
cd arborist-viz
|
||
make all # creates venv, installs, vendors six.js, inits DB, serves
|
||
|
||
Then open http://127.0.0.1:6543/.
|
||
|
||
Layout
|
||
------
|
||
|
||
::
|
||
|
||
arborist_viz/
|
||
__init__.py # Pyramid main() factory
|
||
routes.py # add_route() declarations
|
||
schemas.py # VizNode / VizEdge / GraphPatch / ProofPath /
|
||
# AuditEvent / ActivationTrace / CircuitTrace /
|
||
# DashboardConfig / WidgetSpec (Phase 0)
|
||
views/
|
||
home.py # GET /, GET /version
|
||
dashboards.py # GET/POST/PUT /api/dashboards[/:id]
|
||
roots.py # GET /api/root/:hash[/leaves]
|
||
proofs.py # GET /api/proof/:root/:leaf_index
|
||
claims.py # GET /api/claim/:id[/neighborhood]
|
||
audit.py # GET /api/audit/:event_hash[/chain]
|
||
sse.py # SSE: /sse/audit/live, /sse/run/:id, /sse/root/:hash
|
||
models/ # SQLAlchemy: Dashboard, Widget, Layout
|
||
templates/ # Jinja2 server-rendered HTML
|
||
base.jinja2
|
||
dashboard.jinja2
|
||
widgets/
|
||
root_explorer.jinja2
|
||
claim_warrant.jinja2
|
||
audit_timeline.jinja2
|
||
run_dag.jinja2
|
||
static/
|
||
six/ # vendored six.js bundles (run `make six`)
|
||
viz/ # vanilla JS: dashboard.js, sse-client.js
|
||
css/ # viz.css (command-center dark theme)
|
||
scripts/
|
||
init_db.py
|
||
alembic/
|
||
env.py
|
||
versions/
|
||
tests/
|
||
|
||
Phase status
|
||
------------
|
||
|
||
Phase 0 (schema + dashboard shell + proof/root/claim/audit/run widgets,
|
||
ticket §17 phases 0–3) is the default scope. Later phases:
|
||
|
||
* Phase 4 — SSE live streaming (this scaffold ships the endpoint surface;
|
||
arborist→SSE bridge follows).
|
||
* Phase 5 — 3D Merkle lattice via six.js.
|
||
* Phase 6 — large-graph widgets (vanilla canvas + six.js;
|
||
Cosmograph/sigma.js only if a measured need surfaces).
|
||
* Phase 7 — circuit/activation tracing, **gated on arborist #000062**
|
||
producing a ``MechanisticWitnessRoot``.
|
||
* Phase 8 — embeddable web-components.
|
||
|
||
License
|
||
-------
|
||
|
||
AGPL-3.0-only — matches the arborist parent.
|