docs: document the trust-core vs. portfolio-crate architecture (auths-evidence + the four portfolios)

[bordumb]

Summary

We need a canonical architecture doc in this repo explaining the split between auths-evidence (the shared trust core) and the four portfolio product crates that depend on it. The layering is easy to confuse — auths-evidence vs auths-receipts especially — and it is the load-bearing structure behind the "one implementation of the trust logic" rule. This issue captures the content; the deliverable is to land it as a doc (proposed home below).

State note. auths-evidence and the four portfolio crates are planned / greenfield per the auths-receipts PRD (in the auths-site repo: docs/plans/tools/auths-receipts.md §0.1–§0.3 and docs/plans/tools/seed-tools.md). auths-verifier, the language bindings (auths-node, auths-python), and verify-spend (in auths-mcp-gateway) already exist. This doc is the canonical statement of the target layering — update it as the crates land.

auths-evidence — the shared trust core (the how)

• One implementation of the trust logic, in this monorepo next to auths-verifier: resolveChain, judgeCall / judgeLog, EvidenceBundle build + verify, verify_spend, escrow rule evaluation.
• Shared by all four portfolios and bound out to every language: PyO3 → auths on PyPI, napi → @auths-dev/sdk, WASM → @auths-dev/verifier, native Rust. The gateway's verify-spend CLI is also just a thin caller of it.
• No product / tool surface — no MCP tools, no HTTP API, no listings. Pure, re-derivable trust math.
• (Formerly auths-tools-core in early drafts; renamed to auths-evidence — same crate if you see the old name.)

The four portfolio crates — the what

Each is a product / listing boundary: a sibling crate that depends on auths-evidence and never the reverse. One core, four products:

Portfolio	Crate	What it ships
1 · Accountability & dispute	auths-receipts	T1 receipts-server, T2 escrow-server, RC-E3.3 receipts-api HTTP retainer
2 · Compliance & risk	auths-compliance	sanctions / AML screening, spend & policy audit
3 · Identity & reputation	auths-reputation	counterparty / reputation oracle
4 · Proof & verified data	auths-proof	verified fetch, signed notary

auths-receipts in detail (Portfolio 1, the exemplar)

• src/lib.rs — the receipts domain: dispute assembly + escrow rules.
• src/bin/ — the shippable servers: receipts-server (T1), escrow-server (T2), receipts-api (RC-E3.3 HTTP retainer).
• This is what a customer buys: receipt_build, dispute_evidence, escrow, ReversalDetermination, the retainer API.

The relationship

graph LR
  V["auths-verifier<br/>(exists)"] --> E["auths-evidence<br/>the one trust core"]
  E --> R["auths-receipts<br/>Portfolio 1 · dispute / escrow"]
  E --> C["auths-compliance<br/>Portfolio 2 · sanctions / audit"]
  E --> P["auths-reputation<br/>Portfolio 3 · reputation oracle"]
  E --> F["auths-proof<br/>Portfolio 4 · verified fetch / notary"]

Loading

Language bindings — one Rust core, every rail:

graph TD
  E["auths-evidence<br/>one Rust implementation"]
  E -->|PyO3| PY["auths → PyPI"]
  E -->|napi| N["@auths-dev/sdk → npm"]
  E -->|WASM| W["@auths-dev/verifier"]
  E -->|native Rust| G["verify-spend CLI + first-party servers"]

Loading

Plain-text (for terminals):

auths-verifier ──► auths-evidence ──►  auths-receipts   (Portfolio 1 — dispute/escrow tools)
                     (one core)     ├─► auths-compliance (Portfolio 2)
                                    ├─► auths-reputation (Portfolio 3)
                                    └─► auths-proof      (Portfolio 4)

The load-bearing rules

• One-way dependency. Portfolio crates import auths-evidence; auths-evidence never imports a portfolio crate. (Same anti-drift discipline as the existing SDK/core boundary.)
• One implementation. The verification / re-derivation / signing / judging logic lives in auths-evidence only. A bundle built by any tool, in any language binding, verifies identically — because they all ran the same code. Put trust logic in a product crate and you get four copies that drift.
• Core has no product surface. MCP tools, HTTP APIs, and market listings live in the portfolio crates, never in the core.

One-liner: auths-evidence proves things; the portfolio crates are the products that sell the proving.

Deliverable / acceptance

• Land this as a canonical doc — proposed: docs/architecture/portfolio-crate-layering.md (or a section in the existing architecture docs), linked from the README's architecture section.
• Mark current vs. planned crate state (greenfield markers) so the doc stays honest as crates land.
• Cross-link the source PRDs in auths-site (docs/plans/tools/auths-receipts.md §0.1–§0.3, seed-tools.md).
• Extend CLAUDE.md's dependency-model section to mention the trust-core → portfolio layering alongside the existing SDK/core rules.