Publish FOG design documentation and Merkle tree

1 files changed, 184 insertions, 0 deletions

diff --git a/docs/FOG-ALPHA.md b/docs/FOG-ALPHA.md
new file mode 100644
index 0000000..03a712d
--- /dev/null
+++ b/docs/FOG-ALPHA.md
@@ -0,0 +1,184 @@
+# FOG Operator Alpha
+
+Status: Readiness gate, not deployable
+
+Date: 2026-08-18
+
+## 1. Purpose
+
+`FOG-OPERATOR-ALPHA-1` defines the transition from a single-host functional
+fixture to an experimental network operated across independent administrative
+domains. It consolidates the alpha requirements already present in
+`FOG-THREAT-MODEL`, `FOG-ARCHITECTURE`, `FOG-PKI`, and `FOG-WIRE` without
+activating a cryptographic, traffic, or deployment profile.
+
+The current FOG tree is not alpha-ready. No FOG protocol daemon or active
+byte-exact protocol profile exists. The alpha readiness module records this
+state explicitly and fails closed when evidence or operator separation is
+missing.
+
+## 2. Local Alpha Laboratory
+
+A single host may reproduce the alpha role count with separate rootless
+containers or virtual machines. That laboratory can test:
+
+- three-authority quorum and consensus failure;
+- two mix instances in each of three layers;
+- route selection across alternate nodes;
+- replay-state loss, node loss, storage loss, and partitions;
+- key rotation, revocation, epoch transition, and rollback behavior;
+- bounded queues, malformed input, flooding, and restart behavior;
+- deterministic deployment generation and role-specific containment.
+
+The laboratory must keep one executable, service account, secret scope,
+writable state scope, and network policy per role. A single container running
+all roles is not conforming because it erases the process, key, state, and
+network boundaries the test is intended to exercise.
+
+All laboratory binaries are compiled once for the host platform. One
+digest-pinned multi-binary fixture image may then be reused by every container,
+with a different single-role entrypoint. Six mix containers do not cause six
+`fog-mix` compilations.
+
+The laboratory does not demonstrate independent operation, provider or ASN
+diversity, Internet timing, resistance to operator collusion, or anonymity.
+Synthetic operator labels are test inputs only and must not be presented as
+real independence.
+
+## 3. Minimum Distributed Topology
+
+The operator alpha requires:
+
+- three independently administered authority roots and online services with
+  a 2-of-3 quorum;
+- independent consensus mirrors;
+- at least two independent checkpoint monitors or witnesses;
+- three mix layers with at least two independently operated mixes per layer;
+- at least four independently operated storage replicas;
+- separate entry, mix, courier, and storage identities;
+- declared operator family, administration, provider, provider-account, ASN,
+  country, and location relationships;
+- no route that repeats an operator or declared family.
+
+These are minimums, not evidence of sufficient anonymity. Traffic volume,
+cover scheduling, topology diversity, observed network behavior, and
+adversarial results remain part of every claim.
+
+Distributed operators consume verified release artifacts. The release
+pipeline assembles minimal role-specific images from one compiled artifact set
+and shared OCI layers. Operators do not need to compile locally unless they are
+performing an independent reproducibility check.
+
+## 4. Readiness Evidence
+
+Every required readiness item has one of two states: `open` or `pass`. A pass
+requires at least one immutable artifact reference, a lowercase SHA-256 digest,
+an explicit scope, and a date. A note or successful command without retained
+evidence does not close a gate.
+
+The required evidence covers:
+
+1. active byte-exact protocol profiles;
+2. real single-role protocol daemons;
+3. a validated operator inventory;
+4. unit, integration, conformance, fuzz, race, and fault testing;
+5. replay, tagging, n-1, flooding, load, side-channel, clock, consensus,
+   authority, node-loss, and storage-loss tests;
+6. traffic simulation calibrated with observed or conservative distributions;
+7. interoperability between independently built endpoints;
+8. reproducible independent-host deployment and rollback;
+9. rehearsed compromise, revocation, transition, quorum-loss, and restore
+   procedures;
+10. public admission, family, common-control, revocation, and residual-risk
+    policy;
+11. independent security review.
+
+The independent review gate is retained even though a broader production
+review is also required. For alpha it means that someone outside the
+implementation path has reviewed the exact experimental artifacts and that
+unresolved findings are recorded. It is not a production certification.
+
+## 5. Inventory Boundary
+
+The machine-readable operator inventory contains only bounded public or opaque
+identifiers needed to test separation and role counts. It must not contain:
+
+- private keys, recovery material, credentials, tokens, or passwords;
+- host login instructions or management addresses;
+- personal email addresses, phone numbers, or legal identity evidence;
+- private admission evidence or incident details;
+- packet, user, contact, mailbox, or capability identifiers.
+
+The validator rejects unknown fields, duplicate JSON keys, trailing values,
+oversized files, invalid identifiers, duplicate node identities, shared role
+state or secret scopes, insufficient role counts, and common administration,
+provider accounts, or families inside independence-critical role sets.
+
+The validator reports aggregate provider, ASN, country, and location-group
+counts. It does not invent a numeric diversity policy that the normative PKI
+profile has not selected.
+
+## 6. Claim Boundary
+
+The only permitted baseline label is:
+
+```text
+experimental-alpha-no-anonymity-claim
+```
+
+Until every gate passes, public material must say that FOG is a specification
+and laboratory project. Even after the alpha gate passes, results must identify
+the exact software, profiles, topology, traffic conditions, adversary,
+measurement period, known failures, and operator assumptions.
+
+An alpha must not claim production anonymity, global-passive-observer
+resistance, post-quantum security, reliable delivery, or protection against
+collusion merely because the minimum node count exists.
+
+## 7. Implementation
+
+The gate implementation lives in `deploy/alpha/`. It is deliberately separate
+from protocol daemons and uses only the Go standard library. It validates
+readiness evidence and an externally supplied operator inventory. It does not
+generate a deployment manifest because exact ports, transport profiles,
+cryptographic suites, cover schedules, operational limits, and authority time
+parameters remain non-active selections.
+
+## 8. Requirement Traceability
+
+| Alpha control | Requirements |
+| --- | --- |
+| Independent authority, mix, storage, mirror, and witness sets | `TM-PKI-01`, `TM-PKI-03`, `ARC-001`, `ARC-007`, `PKI-INV-01`, `PKI-INV-07` |
+| Six mixes, two per layer | `TM-ROLE-02`, `ARC-003`, `FOG-ARCHITECTURE` section 16.2 |
+| Evidence registry | `TM-SUPPLY-01`, `TM-CRYPTO-02`, `FOG-THREAT-MODEL` section 16.2 |
+| Unique service, state, and secret scopes | `TM-CRYPTO-01`, `ARC-007`, `WIRE-INV-07` |
+| Strict bounded inventory parser | `TM-AVAIL-01`, `ARC-008` |
+| No anonymity claim | `TM-NET-01`, `TM-NET-02`, `TM-NET-03`, `ARC-009` |
+
+## 9. Next Implementation Block
+
+The next safe local block is a simulation-only alpha laboratory with three
+authority fixtures, two mixes per layer, four storage fixtures, alternate-path
+traversal, and an expanded fault matrix. It must reuse no production profile
+identifier and must remain visibly distinct from the later protocol daemons.
+
+The completed laboratory is preserved as `FOG-ALPHA-LAB-POC-1` according to
+`FOG-POC-PRESERVATION.md`. Preservation includes reproducible source and one
+bounded demonstration workflow, not captured mutable containers or runtime
+secrets. The frozen PoC remains functional evidence only.
+
+The checked-in definition gate fixes 17 roles, 23 pairwise permitted edges,
+all eight complete mix routes, and 13 fault families in
+`deploy/alpha/lab-topology.json` and `deploy/alpha/lab-faults.json`. Compatible
+single-role fixtures and deterministic Compose generation now make the strict
+validator report `runnable: true`. The bounded one-command rootless workflow
+completed all eight routes, performed 102 containment and exact-network
+checks and exercised all 13 fault families, including exact stale-state
+rejection and fixture cover-scheduler supervision. It recorded sanitized
+evidence and removed every disposable runtime resource. Dependency and license
+inventory, frozen artifact hashes, and independent clean-room reproduction
+remain required before accepting the preserved PoC. The canonical preservation
+manifest now records zero third-party Go modules, exact external tool versions
+and licenses, required source and evidence hashes, and all eight binary hashes.
+The project license remains `NOASSERTION`; an independent host rebuild and
+repository revision remain outstanding.