release: implement site registry v0.4 trust pipeline

docs/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Architecture
+
+Argand Site Registry is a local Rust library and CLI around a mutable SQLite
+writer and immutable, content-pinned reader generations. Source acquisition,
+evidence normalization, editorial decisions, and release authority remain
+separate.
+
+```mermaid
+flowchart LR
+  S[Allowlisted source objects] --> I[Streaming adapters]
+  I --> W[(Writer store)]
+  O[Bounded candidate observer] --> B[Immutable observation batches]
+  B --> W
+  W --> G[Candidate generation]
+  G --> Q[Evidence bundles and review queue]
+  Q --> V[Signed reviewer votes]
+  V --> W
+  W --> R[Reviewed generation]
+  R --> P[Separate publisher signature]
+  P --> C[Verified lookup and resolve]
+  R --> E[Signed cumulative revocation feed]
+  E --> C
+```
+
+## Data boundaries
+
+`sources`, `records`, and `facts` preserve provider-native evidence. Typed
+coverage selects a coherent active set without deleting older snapshots.
+`selected_sources` and `active_records` record that derivation. Names, entities,
+web properties, edges, popularity, and rejected facts are deterministic
+projections.
+
+Names, website edges, and entity equivalences have separate material
+fingerprints. Adding an alias therefore cannot inherit an approved destination,
+and changing unrelated entity metadata does not invalidate an unchanged website
+edge. Every evidence bundle contains the exact current assertion, provenance, and
+attached observations that a vote signs.
+
+Observation batches are append-only. Redirects, canonicals, hreflang, JSON-LD
+`sameAs`, sitemaps, country selectors, HTTP state, public DNS-set hashes, TLS
+certificate hashes, and bounded failures remain observations. They never create
+an entity, ownership edge, role, or approval.
+
+Votes are exact signed JSON documents. The writer records its own `accepted_at`,
+the SSH signature, physical public-key digest, evidence-bundle digest, policy
+digest, scope, expiry, and any explicitly superseded revocation IDs. Policy
+compilation counts independent identities, groups, and physical keys. The
+reference policy requires two independent approvals and makes one revocation
+sticky.
+
+## Trust boundaries
+
+- Source HTTPS and a content digest establish what was imported, not whether the
+  assertion is true.
+- Reviewer signatures establish who made an exact decision, not site safety.
+- Publisher signatures authenticate a complete generation, not every assertion.
+- `lookup` is an audit surface. `resolve` is the policy-enforced navigation
+  surface.
+- Automated acquisition, observation, and builds stop at candidates. They have no
+  review, publisher, or activation authority.
+
+Strict generation receipts bind database bytes, license and attribution files,
+selected coverage, the review policy, reviewer trust-root bytes, and the trusted
+acceptance-time rule. Readers copy authenticated SQLite bytes into a private
+unlinked snapshot before opening them.
+
+## Main modules
+
+| Module | Responsibility |
+| --- | --- |
+| `download`, `crux` | Allowlisted, bounded source acquisition and resumable cache |
+| `source`, `store`, adapters | Manifest validation and streaming source-specific import |
+| `coverage` | Full/partition/delta graph validation and active-record masking |
+| `normalize` | Deterministic URL, hostname, registrable-domain, suffix, and name normalization |
+| `build` | Canonical immutable generation and receipt creation |
+| `bundle`, `policy`, `vote` | Review evidence, policy epochs, authenticated quorum, revocation |
+| `observer`, `observation`, `queue` | Candidate-only collection, replay/import, reverse lookup, drift and queues |
+| `query`, `resolution`, `identity`, `catalog` | Audit lookup, equivalence, resolution, statistics |
+| `release`, `revocation`, `generation`, `ssh` | Export, signature verification, emergency overlays, activation, rollback protection |
+
+The database schema lives in ordered migrations. JSON and receipt contracts have
+their own schema strings and fail closed on unknown versions. See
+[FORMATS.md](FORMATS.md) and [MIGRATING-0.4.md](MIGRATING-0.4.md).