docs: add README for each FunctionFoundry product

README.md

@@ -6,18 +6,20 @@ Each library ships as its own DLL and NuGet package. There is no mandatory aggre
 
 ## Packages
 
-| Package | Purpose |
-|---|---|
-| `FunctionFoundry.Security` | Envelope encryption, deterministic pseudonymization, threshold secret sharing, key-rotation planning |
-| `FunctionFoundry.Storage` | Transactional file-set writes, content-addressed storage, content-defined chunking, Merkle file-tree diffs |
-| `FunctionFoundry.Integrity` | Canonical JSON, hash manifests, Merkle proofs, tamper-evident hash chains |
-| `FunctionFoundry.Observability` | Sensitive-data redaction, event fingerprinting, adaptive sampling, burst coalescing |
-| `FunctionFoundry.Data` | External merge sort, structural tree diff, three-way merge, temporal interval join |
-| `FunctionFoundry.Text` | Unicode spoof detection, secret scanning, near-duplicate indexing, delimited-text dialect inference |
-| `FunctionFoundry.Resilience` | Adaptive concurrency, hedged execution, execution budgets, checkpointed batch execution |
-| `FunctionFoundry.Networking` | Resumable parallel downloads, mirror selection, transfer planning, streaming integrity verification |
-| `FunctionFoundry.Distributed` | Weighted rendezvous hashing, version clocks, phi-accrual failure detection, quorum aggregation |
-| `FunctionFoundry.Scheduling` | Interval-set algebra, recurring availability, business calendars, critical-path scheduling |
+Each product has a dedicated README under `src/<Package>/README.md` describing exactly what it does.
+
+| Package | Purpose | README |
+|---|---|---|
+| `FunctionFoundry.Security` | Envelope encryption, deterministic pseudonymization, threshold secret sharing, key-rotation planning | [README](src/FunctionFoundry.Security/README.md) |
+| `FunctionFoundry.Storage` | Transactional file-set writes, content-addressed storage, content-defined chunking, Merkle file-tree diffs | [README](src/FunctionFoundry.Storage/README.md) |
+| `FunctionFoundry.Integrity` | Canonical JSON, hash manifests, Merkle proofs, tamper-evident hash chains | [README](src/FunctionFoundry.Integrity/README.md) |
+| `FunctionFoundry.Observability` | Sensitive-data redaction, event fingerprinting, adaptive sampling, burst coalescing | [README](src/FunctionFoundry.Observability/README.md) |
+| `FunctionFoundry.Data` | External merge sort, structural tree diff, three-way merge, temporal interval join | [README](src/FunctionFoundry.Data/README.md) |
+| `FunctionFoundry.Text` | Unicode spoof detection, secret scanning, near-duplicate indexing, delimited-text dialect inference | [README](src/FunctionFoundry.Text/README.md) |
+| `FunctionFoundry.Resilience` | Adaptive concurrency, hedged execution, execution budgets, checkpointed batch execution | [README](src/FunctionFoundry.Resilience/README.md) |
+| `FunctionFoundry.Networking` | Resumable parallel downloads, mirror selection, transfer planning, streaming integrity verification | [README](src/FunctionFoundry.Networking/README.md) |
+| `FunctionFoundry.Distributed` | Weighted rendezvous hashing, version clocks, phi-accrual failure detection, quorum aggregation | [README](src/FunctionFoundry.Distributed/README.md) |
+| `FunctionFoundry.Scheduling` | Interval-set algebra, recurring availability, business calendars, critical-path scheduling | [README](src/FunctionFoundry.Scheduling/README.md) |
 
 ## Requirements
 

src/FunctionFoundry.Data/README.md

@@ -0,0 +1,66 @@
+# FunctionFoundry.Data
+
+Bounded-memory and conflict-aware data processing for hard cases the BCL does not solve as a reusable package.
+
+## What this product does
+
+It handles **large sorts, structured diffs, merges with conflicts, and temporal overlaps** with explicit limits and deterministic outputs.
+
+### 1. Bounded-memory external merge sort (`BoundedMemoryExternalMergeSort`)
+
+Sorts generic records that do not fit in memory:
+
+* configurable memory budget
+* temporary run files and k-way merge
+* optional stable ordering
+* cancellation and cleanup after success, cancel, or failure
+* diagnostics for abandoned temporary data
+
+### 2. Structural tree diff (`StructuralTreeDiff`)
+
+Diffs nested objects, arrays, and scalars into ordered operations:
+
+* add / remove / replace / move
+* configurable identity keys for array elements
+* complexity limits against hostile inputs
+* human-readable and machine-readable results
+
+### 3. Three-way merge (`ThreeWayMerge`)
+
+Merges **base + local + remote** values with:
+
+* explicit conflict objects (no silent conflict loss)
+* configurable merge policies
+* path-level conflict reporting
+* deterministic output ordering
+
+### 4. Temporal interval join (`TemporalIntervalJoin`)
+
+Joins records whose validity intervals overlap:
+
+* open / closed boundary policies
+* sorted-input friendly processing
+* bounded buffering where possible
+* clear handling of invalid intervals
+
+## When to use it
+
+* Offline ETL or analytics sorts larger than RAM
+* Document / config sync that must show structural changes
+* CRDT-adjacent or collaborative edits needing honest conflicts
+* Validity-window joins (pricing, entitlements, employment periods)
+
+## Non-goals
+
+* A general query engine or ORM
+* Silently “winning” merges by last-write-wins defaults
+
+## Install
+
+```bash
+dotnet add package FunctionFoundry.Data
+```
+
+## Runtime dependencies
+
+None beyond the .NET shared framework.

src/FunctionFoundry.Distributed/README.md

@@ -0,0 +1,68 @@
+# FunctionFoundry.Distributed
+
+Reusable distributed-systems algorithms without requiring a network framework.
+
+## What this product does
+
+It provides **membership hashing, causality tracking, failure suspicion, and quorum aggregation** as pure in-process building blocks.
+
+### 1. Weighted rendezvous hashing (`WeightedRendezvousHasher`)
+
+Picks stable nodes for keys with:
+
+* node weights
+* optional bounded-load behavior
+* deterministic hashing
+* minimal remapping when membership changes
+
+### 2. Vector and dotted version clocks (`VectorClock` / `DottedVersionClock`)
+
+Tracks causal history across replicas:
+
+* increment, merge, dominance comparison
+* concurrent-version detection
+* deterministic serialization
+* configurable growth limits and compaction trade-offs
+
+### 3. Phi-accrual failure detector (`PhiAccrualFailureDetector`)
+
+Computes a continuous **suspicion score** from heartbeat intervals:
+
+* sample window and warm-up behavior
+* injectable clock abstraction
+* outlier handling
+* deterministic simulations for tests
+
+Suspicion is **not** proof of failure.
+
+### 4. Quorum result aggregator (`QuorumResultAggregator`)
+
+Collects concurrent replica results under a quorum policy:
+
+* agreement and conflict detection
+* early completion
+* failure evidence
+* cancellation of unnecessary work
+* deterministic winner selection only when the policy allows it
+
+## When to use it
+
+* Client-side shard / replica selection
+* Conflict detection for multi-writer records
+* Heartbeat-based soft failure detection
+* Reading from N replicas and waiting for quorum
+
+## Non-goals
+
+* Shipping a cluster membership protocol or RPC stack
+* Treating phi scores as hard failovers without host policy
+
+## Install
+
+```bash
+dotnet add package FunctionFoundry.Distributed
+```
+
+## Runtime dependencies
+
+None beyond the .NET shared framework.

src/FunctionFoundry.Integrity/README.md

@@ -0,0 +1,60 @@
+# FunctionFoundry.Integrity
+
+Deterministic canonicalization and verifiable data structures.
+
+## What this product does
+
+It makes data **comparable and verifiable** across machines by fixing encoding rules and building cryptographic evidence structures.
+
+### 1. Canonical JSON (`CanonicalJson`)
+
+Converts JSON into a **documented deterministic profile**:
+
+* sorted object properties
+* exact number formatting rules
+* Unicode / escape handling
+* duplicate-property rejection
+* streaming canonicalize where feasible
+
+Identical logical documents produce identical bytes, which is required for hashing and signing.
+
+### 2. Streaming hash manifest (`StreamingHashManifest`)
+
+Hashes many files or streams into a deterministic manifest:
+
+* SHA-256 (SHA-384 optional)
+* path traversal protection
+* explicit metadata inclusion policy
+* verification reports that list exact mismatches
+
+### 3. Merkle tree and inclusion proofs (`MerkleTree`)
+
+Builds a Merkle tree with domain-separated leaf/internal nodes, odd-node handling, and inclusion proof generate/verify — so you can prove one item belongs to a set without shipping the whole set.
+
+### 4. Tamper-evident hash chain (`HashChain`)
+
+Append-only record chain with canonical encoding and verification that identifies the **first invalid record**. Sequence and timestamp policies are explicit.
+
+**Warning:** a hash chain alone is not trusted timestamping or external anchoring.
+
+## When to use it
+
+* Signing / hashing APIs that need stable JSON bytes
+* Release or dataset integrity manifests
+* Light-weight audit logs that detect truncation or mutation
+* Inclusion claims for large collections
+
+## Non-goals
+
+* Replacing a blockchain or TSA
+* Generic JSON helpers unrelated to determinism
+
+## Install
+
+```bash
+dotnet add package FunctionFoundry.Integrity
+```
+
+## Runtime dependencies
+
+None beyond the .NET shared framework.

src/FunctionFoundry.Networking/README.md

@@ -0,0 +1,68 @@
+# FunctionFoundry.Networking
+
+Robust large-data transfer orchestration over HTTP using a **caller-provided** `HttpClient`.
+
+## What this product does
+
+It plans and executes **resumable, integrity-aware downloads** with mirror selection and streaming verification.
+
+### 1. Resumable parallel downloader (`ResumableParallelDownloader`)
+
+Downloads large objects using HTTP range requests when available:
+
+* ETag / Last-Modified validation
+* persistent checkpoint format
+* configurable parallelism
+* partial-file integrity and final cryptographic verification
+* safe restart after interruption
+* capability detection and correct fallback when ranges are unsupported
+
+Never creates a new `HttpClient` per request.
+
+### 2. Mirror selector (`MirrorSelector`)
+
+Scores candidate mirrors using latency, throughput, availability, and integrity failures:
+
+* failure decay over time
+* hysteresis to avoid rapid oscillation
+* deterministic tie-breaking
+* exportable selection evidence
+
+### 3. Transfer plan (`TransferPlan`)
+
+Generates chunk assignments independently from execution:
+
+* resumable state
+* incompatible checkpoint detection
+* no overlapping writes
+* full-coverage verification
+* repair assignments after corrupt chunks
+
+### 4. Streaming integrity verifier (`StreamingIntegrityVerifier`)
+
+Verifies data while it streams:
+
+* per-chunk and complete-object checks
+* detailed mismatch location
+* bounded memory (no full-file buffering)
+
+## When to use it
+
+* IDE/plugin/runtime update downloaders
+* Multi-CDN artifact fetchers
+* Resumable media or dataset transfers with integrity requirements
+
+## Non-goals
+
+* Owning `HttpClient` lifetime / DNS / proxy policy for the host
+* A general REST client library
+
+## Install
+
+```bash
+dotnet add package FunctionFoundry.Networking
+```
+
+## Runtime dependencies
+
+None beyond the .NET shared framework (`HttpClient` supplied by the caller).

src/FunctionFoundry.Observability/README.md

@@ -0,0 +1,60 @@
+# FunctionFoundry.Observability
+
+Advanced processing for structured logs and diagnostics — without forcing a logging framework.
+
+## What this product does
+
+It transforms diagnostic events for **privacy, grouping, and volume control** before they hit expensive storage or sinks.
+
+### 1. Sensitive-data redactor (`SensitiveDataRedactor`)
+
+Walks nested objects, dictionaries, and collections (with cycle protection) and redacts:
+
+* property-name policies (`password`, `token`, …)
+* pattern-based values
+* high-entropy secret candidates
+
+Supports replacement strategies and hard limits on depth / item counts so inspection stays bounded. Designed to avoid arbitrary user-code invocation where practical.
+
+### 2. Deterministic event fingerprinting (`EventFingerprinter`)
+
+Normalizes exception stacks and strips unstable values (timestamps, GUIDs, correlation noise) while keeping causal structure. Equivalent failures get a **stable fingerprint** plus an explanation of which normalized parts contributed.
+
+### 3. Adaptive deterministic sampling (`AdaptiveSampler`)
+
+Decides whether to keep an event based on fingerprint and observed volume:
+
+* always preserves high-severity events
+* identical fingerprints get stable decisions
+* adapts rates under high cardinality / volume
+* bounded memory, thread-safe, exportable stats
+
+### 4. Burst coalescing (`BurstCoalescer`)
+
+Merges repeated events inside a time window:
+
+* keeps first and last occurrence
+* keeps representative samples
+* emits dropped / coalesced counts
+* handles concurrent producers without unbounded cardinality growth
+
+## When to use it
+
+* Log pipelines that must strip secrets before export
+* Alert grouping / error fingerprinting across instances
+* Cost control when a single bug floods telemetry
+
+## Non-goals
+
+* Being a full logging framework (Serilog/MEL replacement)
+* Guaranteeing zero secret leakage for all custom objects
+
+## Install
+
+```bash
+dotnet add package FunctionFoundry.Observability
+```
+
+## Runtime dependencies
+
+None beyond the .NET shared framework. Logging-framework-neutral by design.