Northroot Proofs v0.2 — “5W1H” Executive Guide
Codename: 5W1H
Goal: A clean, modular proof system that’s easy to reason about, implement, and extend.
Why: Separate what is being proven from how it’s used. Keep proofs small, typed, and linkable so FinOps, audit, and marketplaces can compose them without bloating the core.
⸻
0) The Decision (TL;DR)
We are splitting the proof surface into four minimal, linkable proofs:
• PoSH — Proof of Shape (How)
Identity of a method’s transformation (operator/method shape), independent of any run.
• PoX — Proof of Execution (What + When; bound to How)
Evidence that a specific run occurred on specific bytes, at specific times.
• Po$ — Proof of Spend (How much)
Normalized usage + price context, linked to PoX; used for reconciliation.
• PoΣ — Proof of Semantics (Was it good?)
Checker/verifier outcomes (inline or sampled), linked to PoX.
Unifying idea (5W1H):
• Who = identity_route (trace/tenant/org) → used in identity_root
• What = method_ref + data_shape_hash → PoX
• When = start_time/end_time → PoX
• Where = content_route + evidence URIs (context, not hashed) → PoX
• Why = policy_id (rules) → PoX / verify
• How = span_shape_hash + method_shape_root → PoSH
Each proof is small and typed; they are linked by IDs, not crammed into one mega-blob.
⸻
1) Concept Map (how proofs relate)
MethodShape (PoSH) --(method_ref)--> Trace (run context)
\
\--> SignedSpan(s) (PoX) -----> TraceRoots (PoX rollup)
| \
| \--> CheckerReceipt(s) (PoΣ)
|
+-------> SpendReceipt(s) (Po$)
• PoSH pins How (method/operator shapes, artifact digests).
• PoX pins What/When with content hashes; rolls up to trace roots.
• Po$ & PoΣ add business and quality layers—without polluting PoSH/PoX hashes.
⸻
2) Proofs at a Glance
PoSH — Proof of Shape (How)
• Proves: transformation contract is exactly this (no values).
• Anchors:
• span_shape_hash = H({tool_id, tool_version, param_schema})
• method_shape_root = H(sorted(span_shape_hash_i,"|")) (rename from content_root)
• Artifacts: Method manifest (pinned image/WASM, DAG).
• Use: routing, plan caching, method equivalence, reproducible packaging.
• Excludes: data values, time, identities, spend.
PoX — Proof of Execution (What, When; bound to How)
• Proves: run occurred as claimed on specific bytes at a time.
• Anchors (per span):
• trace_id, span_id, method_ref, data_shape_hash, span_shape_hash
• inputs/outputs content_hash (bytes or chunk Merkle)
• normalized start_time, end_time, status
• Rollups (per trace):
• trace_set_root = H(sorted(C_span_i,"|"))
• identity_root = H({trace_id, entity_id, sorted(C_span_i)})
• carry method_shape_root from PoSH
• Use: audit, replay, delta/partial-materialization lineage.
Po$ — Proof of Spend (How much)
• Proves: normalized usage + price context tied to a run.
• Fields: trace_id, optional span_ids, provider SKU/region/contract, tokens/vCPU·s/GB·s/egress/energy, unit prices, totals.
• Use: FinOps, chargeback/showback, invoice reconciliation & disputes.
• Note: Separate receipt; references PoX; never hashes into PoX/PoSH.
PoΣ — Proof of Semantics (Was it good?)
• Proves: checker(s) passed for outputs (inline or sampled).
• Fields: trace_id, span_ids?, checker_ref (pinned), pass/fail, metrics, sample plan.
• Use: SLAs, quality claims, marketplace trust.
⸻
3) API v0.2 — End Goals
Stable nouns, slim endpoints:
Catalog
• POST /methods → register MethodShape (PoSH)
• GET /methods/{id}@{version}
Run & Execution
• POST /trace/begin → { trace_id }
requires: method_ref {method_id, version, method_shape_hash, image_digest, method_fingerprint}, data_shape_hash, policy_id, identity_route, content_route
• POST /proofs → batch SignedSpan (PoX); idempotent on (trace_id, span_id)
• POST /trace/{trace_id}/chunks → optional delta plan/receipts
• POST /trace/{trace_id}/end → { TraceRoots, server_sig? }
• GET /traces/{trace_id} → returns trace, roots, (optionally expand: spans/spend/checks)
Verification
• Inline Tier-0/1 on ingest (schema, sigs, pins, policy).
• POST /verify?mode=sampling&rate=…&unit=span (PoΣ job runner)
• GET /verify/{job_id} → pass-rate, CIs, breakdowns
Reconciliation
• POST /spend → ingest SpendReceipt(s) (Po$)
• POST /recon/import → provider invoices/logs
• GET /recon/report?period=…&provider=… → variance report
(Soon) Cache
• GET /cache/probe?mode=plan|output|chunk&method_ref=…&data_shape_hash=…&input_content_hash=…
⸻
4) Implementation Priority (v0.2)
1. PoSH (MethodShape) [P0]
• span_shape_hash (tool id/version + param schema)
• method_shape_root (sorted span shapes)
• Method manifest + signature; registry endpoints.
2. PoX core [P0]
• SignedSpan commitment (content hashes, data_shape_hash, span_shape_hash, times)
• Trace lifecycle + TraceRoots (set root, identity root, carry method_shape_root)
• Canonicalization (JCS/BTreeMap), SHA-256, ed25519 envelopes
• Inline Tier-0/1 verification, idempotency
3. DataShape [P0]
• Minimal schema + sketches → data_shape_hash (trace-level required)
4. Delta/Chunking [P1]
• Chunk plan + chunk receipts
• Partial-materialization lineage (reuse by content hash)
5. Po$ Spend [P1]
• SpendReceipt + Recon import/report
6. PoΣ Semantics [P2]
• CheckerReceipt; sampling jobs; pass-rate CI
7. Cache Probe [P2]
• plan/output/chunk hit signaling (no execution)
⸻
5) Data & Hashing Rules (one-time decisions)
• Canonicalization: JSON Canonicalization (JCS) or BTreeMap-sorted JSON; normalized RFC3339 ms UTC times; numeric normalization.
• Hashing: sha256:<64hex> in v0.2 (keep hash_algo field for future BLAKE3).
• What is hashed: the commitment struct only (not signatures).
• Signatures: ed25519 envelope per SignedSpan; optional server countersign on trace end.
• Rename: POSH content_root → method_shape_root (avoid confusion with content_route).
⸻
6) Acceptance Criteria (v0.2)
• Determinism: Equal inputs → equal commitments across machines/runs.
• Replay safety: Given method pins + inputs’ content hashes, re-execution reproduces commitments.
• Isolation: Removing Po$ or PoΣ does not change PoX/PoSH commitments.
• Idempotency: Re-post of same (trace_id, span_id) is a no-op.
• Delta: If only input chunk C11 changes, only spans touching C11 recompute; lineage links reused chunks.
• Policy: Tier-0/1 checks block non-conforming proofs; Tier-2 jobs sample as configured.
⸻
7) Minimal Storage Model
• methods/ → PoSH manifests (by method_id@version)
• traces/ → Trace documents + TraceRoots
• spans/ → SignedSpan blobs (indexed by (trace_id, span_id))
• chunks/ → Chunk plans & receipts
• spend/ → SpendReceipt(s) (Po$)
• checks/ → CheckerReceipt(s) (PoΣ)
Everything joins by trace_id (+ optional span_id).
⸻
8) Migration Notes (v0.1 → v0.2)
• Keep your current C_span and C_trace during migration; emit TraceRoots alongside to compare.
• Add method_ref + data_shape_hash at /trace/begin.
• Strengthen span-shape → {tool_id, tool_version, param_schema}.
• Move economics out of hashed span receipts into Po$ SpendReceipt.
• Rename POSH content_root → method_shape_root.
⸻
9) Risks & Mitigations
• Operator collisions (different tools, same name):
Mitigate: span-shape includes tool_id, tool_version, param schema.
• Hash drift (ordering/serialization bugs):
Mitigate: JCS/BTreeMap + exhaustive tests + golden vectors.
• Over-collection (bloated receipts):
Mitigate: Po$ and PoΣ are optional, linked by IDs; PoX stays minimal.
• Policy ambiguity:
Mitigate: versioned policy_id; Tier-0/1 validation strict and documented.
⸻
10) Quick Glossary
• MethodShape (PoSH): how a method transforms inputs, pinned to artifacts.
• DataShape: structure/sketches of input data; no values.
• SignedSpan (PoX): atomic run proof with content hashes and times.
• TraceRoots (PoX): set root, identity root, carry method_shape_root.
• SpendReceipt (Po$): costs/usage, linked to trace/spans.
• CheckerReceipt (PoΣ): quality checks, linked to trace/spans.
⸻
What to do next
• Create docs/5W1H_EXEC_GUIDE_v0.2.md with this content.
• Spin a v0.2 branch:
• Add MethodShape, DataShape, Trace, SignedSpan, TraceRoots, SpendReceipt, CheckerReceipt.
• Implement canonicalization/signing once; use everywhere.
• Wire /methods, /trace/begin, /proofs, /trace/end (PoSH + PoX).
• Add Tier-0/1 verification.
• Add migrations.md (v0.1→v0.2 mapping) and a half-dozen golden test vectors.
If you want, I can follow up with modular mini-specs for each proof type (PoSH, PoX, Po$, PoΣ) that you can drop in /docs/specs/ and wire to JSON Schemas.