Publish FOG design documentation and Merkle tree

1 files changed, 321 insertions, 0 deletions

diff --git a/docs/FOG-SIMULATION.md b/docs/FOG-SIMULATION.md
new file mode 100644
index 0000000..00fde5e
--- /dev/null
+++ b/docs/FOG-SIMULATION.md
@@ -0,0 +1,321 @@
+# FOG Traffic and Topology Simulation
+
+Status: Engineering Baseline 0.1
+
+Date: 2026-08-08
+
+## 1. Purpose
+
+This document defines the first reproducible simulation boundary for FOG and
+records its initial scenario matrix. It supplies evidence for `TM-NET-01`,
+`TM-NET-02`, `TM-NET-03`, `TM-ROLE-02`, and `TM-AVAIL-01` without promoting a
+delay, cover, topology, entry, or degraded-mode profile.
+
+The implementation is in `../sim/`. The first complete comparison artifact is
+`../sim/results/2026-08-08-baseline.md`.
+
+The simulator is not a daemon, protocol implementation, packet generator,
+deployment controller, capacity benchmark, or anonymity proof.
+
+## 2. Evidence Boundary
+
+The first model answers narrow comparative questions:
+
+- how mean mix delay changes modeled end-to-end latency and local pool overlap;
+- how real and cover traffic density changes bandwidth and observation proxies;
+- how one, two, or three nodes per layer change route diversity and traffic
+  concentration;
+- how independently compromised entry and mix nodes affect repeated target
+  routes;
+- how selective background suppression affects delivery and isolation;
+- how repeated observations shrink a simplified candidate-recipient set.
+
+It does not answer:
+
+- whether FOG is anonymous against a global passive or active observer;
+- which numeric cover or delay profile is safe;
+- whether a local pool metric composes into end-to-end entropy;
+- whether a timing window matches an optimal correlation attack;
+- whether the storage, retrieval, reply, retry, and acknowledgment processes
+  are indistinguishable;
+- whether loop statistics reliably detect n-1 or ordinary failure;
+- how queue capacity, congestion, network jitter, churn, or operator behavior
+  affect deployment.
+
+Every output is tied to the exact model revision, configuration, seed, and
+threat assumptions. A favorable proxy result is never promoted into a public
+privacy claim.
+
+## 3. Model Contract
+
+### 3.1 Reproducibility
+
+`FOG-SIM-DISCRETE-EVENT-1` uses a pinned simulation-only SplitMix64 sequence.
+The same valid configuration and seed produce the same JSON report. The PRNG
+is isolated inside the simulation package and MUST NOT be imported by future
+protocol, cryptographic, route-construction, or daemon code.
+
+Scenario parsing rejects unknown fields, non-regular files, files over 1 MiB,
+non-finite values, invalid probability ranges, invalid topology, and expected
+work above one million packets per replication or five million packets per
+scenario invocation. Runtime generation also aborts if Poisson sampling
+actually reaches either limit, so the validation estimate is not the only
+resource bound.
+
+### 3.2 Traffic
+
+Each simulated user has independent Poisson real and cover injection
+processes. User 0 sends every real target message to user 1 so repeated
+relationship exposure can be measured. Other real and cover recipients are
+uniform among users other than the sender.
+
+This uniform social graph is deliberately simple. It avoids hiding the model
+behind inferred behavioral data, but it is not realistic enough for a claim.
+Future trace-driven and non-uniform models must remain separately named.
+
+### 3.3 Topology and routes
+
+The model contains:
+
+- one configured entry set;
+- exactly three stratified mix layers;
+- one to three configured mixes per layer in the initial scenarios;
+- four KEMSphinx positions, with the terminal outside the three delay pools;
+- five core link transmissions for a fully delivered forward packet;
+- one 16,150-byte packet on every link.
+
+Nodes receive deterministic operator-family assignments. The route generator
+enumerates only entry, L1, L2, and L3 combinations with four distinct declared
+operator families. A session uses a small entry set for a configured number of
+packets before rotation. It does not rotate entry on every message.
+
+The model does not yet include terminal operator diversity, provider, ASN,
+country, infrastructure-group, capacity, or topology-generation constraints.
+It therefore validates only the narrow declared-family rule.
+
+### 3.4 Delay and fixed costs
+
+Each sender samples one delay for each of the three mix layers. The initial
+matrix uses independent exponential samples, consistent with the evaluated
+Poisson-mix literature and maintained Katzenpost design. A constant-delay mode
+exists only for sensitivity tests and does not define a candidate profile.
+
+Modeled forward latency includes five configured link delays, four configured
+KEMSphinx processing costs, and three sampled mix delays. It excludes entry
+capsule processing, queues, wire handshakes, reassembly, storage, replies,
+imports, retries, and user offline time.
+
+### 3.5 Compromise and active suppression
+
+Each entry and mix is independently marked compromised once per replication
+using configured probabilities. Target route metrics record:
+
+- at least one compromised mix;
+- all three mixes compromised;
+- entry compromised;
+- entry and all three mixes compromised;
+- whether repeated messages eventually use a fully compromised mix route.
+
+The active sensitivity scenario allows a compromised mix to suppress each
+non-target packet independently while always forwarding target packets. This
+is a conservative isolation mechanism, not a complete strategic n-1 attacker.
+It does not infer target packets from encrypted content or model loop-based
+detection and response.
+
+## 4. Metrics
+
+### 4.1 Latency and bandwidth
+
+The report publishes nearest-rank p50, p95, p99, minimum, maximum, and mean
+real-message latency. Core bandwidth counts the actual number of traversed
+links, so suppression reduces downstream byte cost while increasing loss.
+
+### 4.2 Local pool size and entropy
+
+At each target departure from an honest mix, the simulator counts packets
+resident in that mix delay pool. Under the memoryless Poisson-mix assumption,
+the local equal-likelihood entropy proxy is:
+
+```text
+H_local = log2(resident_packet_count)
+```
+
+It also records whether every honest mix on a target route had pool size one.
+This is local opportunity for confusion, not the end-to-end posterior entropy
+of a global observer.
+
+### 4.3 Timing candidate proxy
+
+For each target egress, the simulator counts all delivered packets inside a
+configured centered timing window. A count of one is reported as a unique
+timing candidate.
+
+The metric ignores route likelihood, delay likelihood, ingress history,
+multiple links, user schedules, and machine-learned correlation. It is useful
+only for comparing scenario density under identical rules.
+
+### 4.4 Long-term disclosure proxy
+
+For each target send, the simulator observes the recipients of all delivered
+packets in the following configured interval. It intersects these recipient
+sets across repeated sends and records whether the true fixed recipient is
+still present or uniquely identified.
+
+This deliberately transparent construction demonstrates intersection risk. It
+is not the formal statistical disclosure attack, a probabilistic posterior,
+or the third-party unlinkability metric from the research literature.
+
+## 5. First Scenario Matrix
+
+The initial checked-in configurations compare:
+
+1. a 30-user, one-route functional PoC without cover;
+2. a 100-user, two-mix-per-layer alpha with one cover packet per user per hour;
+3. the same alpha with one cover packet every two minutes per user;
+4. the same covered alpha with mean mix delay raised from 500 ms to 5 seconds;
+5. a 1,000-user, three-mix-per-layer sparse topology;
+6. a sparse alpha with 50 percent independent entry and mix compromise input;
+7. a covered alpha with the same compromise input and 95 percent selective
+   background suppression.
+
+These values are intentionally separated sensitivity points. They are not
+recommended operational defaults.
+
+## 6. Initial Results
+
+### 6.1 Sparse use remains exposed
+
+The no-cover PoC had pool size one at every target departure, a unique
+ten-second timing candidate in 99.2 percent of target messages, and unique
+recipient intersection by five observations in every replication.
+
+The sparse alpha used about 8.47 MiB of five-link core traffic per simulated
+hour and a cover-to-real ratio near 9.9. Its local pool p50 remained one,
+96.8 percent of target routes were isolated at every honest mix, and the
+recipient intersection median fell from 63 candidates after one observation
+to two after ten.
+
+These scenarios support only the existing conclusion that a small or idle
+network cannot acquire anonymity through packet cryptography alone.
+
+### 6.2 Cover and delay protect different proxies
+
+One cover packet every two minutes per user raised five-link core traffic to
+about 231.74 MiB/hour and the cover-to-real ratio to about 294. It removed
+unique ten-second timing candidates and kept all 99 possible recipients in the
+one-hour intersection proxy through ten observations.
+
+With mean mix delay still 500 ms, however, local pool p50 remained one and
+64.9 percent of target routes were isolated at every honest mix. Raising mean
+delay to five seconds at the same traffic level raised local pool p50 to three,
+local entropy p50 to about 1.585 bits, and removed fully isolated target routes
+in the 37 target samples. Modeled latency p50 increased from about 1.44 seconds
+to 13.29 seconds.
+
+Cover volume, mixing overlap, observation windows, and latency are therefore
+different dimensions. A strong result in one proxy does not substitute for
+the others.
+
+### 6.3 More users do not automatically solve dilution
+
+The 1,000-user scenario improved the timing-candidate p50 to four and retained
+a median 14 recipient candidates after ten observations. It also spread
+traffic across three nodes per layer. Local pool p50 remained one and 84.2
+percent of target routes were isolated at every honest mix.
+
+Scaling topology and scaling traffic must be evaluated together. Adding nodes
+without enough traffic per node can dilute mixing opportunity.
+
+### 6.4 Repeated compromise exposure is non-zero
+
+With independent 50 percent compromise inputs in the two-node-per-layer
+alpha, 5.5 percent of sampled target routes used compromised nodes in all
+three layers. Three of sixteen replications encountered at least one such
+route. Entry and all three mixes were compromised together on 1.1 percent of
+target routes.
+
+These sampled values are dependent on entry reuse, topology sampling, route
+reuse, and small target counts. They are not analytical probabilities. They
+do show why repeated routing and long-lived observation must be measured, and
+why declared operator diversity does not remove concealed control risk.
+
+### 6.5 Selective suppression destroys the traffic condition
+
+The n-1 sensitivity scenario delivered only 7.9 percent of all emitted
+packets. Its honest local pool p50 returned to one, 89.5 percent of target
+routes with an honest mix were fully isolated, and half the replications saw a
+fully compromised target route.
+
+This model does not yet determine a shutdown threshold. It confirms that cover
+generation without loop health, anomaly evidence, bounded degraded behavior,
+and active-attack analysis is insufficient.
+
+## 7. Decisions From This Baseline
+
+The baseline establishes only the following stable project decisions:
+
+- retain a deterministic, independent discrete-event simulator before daemon
+  implementation;
+- keep packet geometry fixed and route-family validation enabled in every
+  scenario;
+- reject the functional PoC as anonymity evidence;
+- do not choose cover or delay parameters from intuition or a single metric;
+- measure traffic density per mix, not user count or node count alone;
+- keep active suppression and passive compromise as separate scenarios;
+- withhold degraded-mode thresholds until loop, queue, loss, and operational
+  models exist.
+
+No numeric cover, delay, topology, entry-rotation, polling, or shutdown profile
+is selected.
+
+## 8. Required Extensions
+
+Before the local PoC parameter set is frozen, add:
+
+- end-to-end posterior and Shannon-entropy propagation for a declared
+  observer;
+- formal third-party unlinkability and statistical-disclosure experiments;
+- user availability, non-uniform social graphs, bursts, retries, and traces;
+- forward and reply paths, SURBs, acknowledgments, and rendezvous behavior;
+- storage reads, empty polling, writes, receipts, and capability rotation;
+- loop traffic, loss attribution, n-1 detection, false positives, and
+  degraded-mode state machines;
+- queue service capacity, bandwidth ceilings, congestion, jitter, drops, and
+  flood distributions;
+- topology churn, epochs, provider and ASN correlations, hidden operator
+  families, and compromised-position sweeps;
+- confidence intervals and larger independent replication sets;
+- calibration against PoC traces without collecting privacy-unsafe event logs.
+
+## 9. Reproduction and Checks
+
+From `sim/`:
+
+```sh
+gofmt -d cmd/fog-sim/*.go internal/sim/*.go
+go test ./...
+go test -race ./...
+go vet ./...
+go run ./cmd/fog-sim -scenario-dir scenarios
+```
+
+The CLI emits JSON only to standard output. Checked-in Markdown results are a
+review-oriented comparison; the deterministic JSON is the complete report.
+
+## 10. Primary References
+
+- Ania M. Piotrowska, *Studying the anonymity trilemma with a discrete-event
+  mix network simulator*:
+  <https://arxiv.org/abs/2107.12172>
+- Ania M. Piotrowska et al., *The Loopix Anonymity System*:
+  <https://www.usenix.org/conference/usenixsecurity17/technical-sessions/presentation/piotrowska>
+- George Danezis, *Designing and attacking anonymous communication systems*:
+  <https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-594.html>
+- Katzenpost mix network specification:
+  <https://katzenpost.network/docs/specs/mixnet/>
+- Katzenpost mix decoy loop specification:
+  <https://katzenpost.network/docs/specs/mixdecoy/>
+- FOG threat model: `FOG-THREAT-MODEL.md`
+- FOG architecture: `FOG-ARCHITECTURE.md`
+- FOG wire protocol: `FOG-WIRE.md`
+- FOG KEMSphinx profiles: `FOG-SPHINX-PROFILES.md`