Source mapping and preservation ledger
All paths in this table are links to the unchanged source files. C = components; L = loop primitives. The source collections contain 45 Markdown files and 530 fenced blocks, including diagrams and implementation examples; no separate binary asset or nested source file was found in those two trees. Exact headings, line numbers, links, fenced-block languages/ranges, and SHA-256 hashes are in SOURCE_INVENTORY.json.
The discovery snapshot predates commit 0a6e4d67, which separately expanded C24 with active-passive recovery. The C24 inventory entry now describes that committed version and retains its earlier discovery_sha256 alongside the reviewed commit. The current total is 530 fenced assets (529 at discovery). Lesson 25 includes the added standby distinctions and a capacity puzzle. No original source file was edited by this transformation.
File-to-lesson coverage
| Original | New lessons | Consolidation and retained scope |
|---|---|---|
| C01 · 01-consistent-hashing | 12, 13, 14, 17 | Ring lookup, virtual nodes, routing choices → 12; load skew → 13; streaming, Merkle repair, hints, ownership cutover → 14/17. Engine-specific ring implementations remain reference comparisons. |
| C02 · 02-distributed-rate-limiting | 08, 09 | Algorithm definitions and traces consolidated with L14. Separate local atomicity from fleet/global allocation; no billing guarantees inferred from throttling. |
| C03 · 03-bloom-filters-and-counting-filters | 05 | Bit trace, sizing, two-hash construction, deletion hazards, rotating/counting/cuckoo/blocked/XOR/Ribbon choices → 05. Vendor filter APIs and sizing calculators remain reference. |
| C04 · 04-distributed-cache-patterns-and-eviction | 10, 11 | Patterns, LRU/LFU, memory sizing, invalidation races, stampedes, edge keys → 10/11. Replace universal invalidation advice with a versioned interleaving. |
| C05 · 05-message-queues-vs-event-streams | 19, 21 | Queue/log contrast, acknowledgements, groups, retention, partition skew, poison messages → 19/21. Engine comparison and service setup remain reference. |
| C06 · 06-distributed-locks-and-leases | 16 | Lease lifecycle, owner-checked release, clock assumptions, failure of unfenced work → 16. Provider APIs retained as reference, not interchangeable guarantees. |
| C07 · 07-write-ahead-log-and-lsm-trees | 02, 03, 04, 22 | Split durability, manifest recovery, and compaction into 02–04; reinforce storage in metrics. Avoid suggesting every B-tree write rewrites the whole tree. |
| C08 · 08-database-sharding-and-partition-keys | 12, 13, 17 | Partition keys and query locality → 12; skew → 13; migration/cross-shard choices → 17. Provider quotas remain version-sensitive reference. |
| C09 · 09-distributed-consensus-raft-and-paxos | 14, 15 | Replication versus consensus, persistent terms/votes, elections, commit rule, snapshots, membership → 14/15. |
| C10 · 10-two-phase-commit-and-saga-orchestration | 18, 23, 24 | Local effects → 18; prepared decision recovery → 23; durable saga/compensation/TCC → 24. Long language-specific orchestration examples remain reference. |
| C11 · 11-geospatial-geohash-quadtree-s2 | 33 | Geohash, quadtree, S2/H3, spherical distance, coverage, antimeridian, moving points → 33. Remove fixed precision and flush-interval prescriptions. |
| C12 · 12-change-data-capture-and-outbox-pattern | 20 | Atomic outbox, poll/CDC choice, aggregate ordering, snapshot handoff, WAL retention, poison events → 20. |
| C13 · 13-trie-data-structure-and-inverted-index | 32 | Trie/radix/top-K, inverted postings, intersection, BM25, compression, snapshot swap → 32. |
| C14 · 14-api-gateway-and-reverse-proxy | 07, 29 | Gateway isolation and adaptive admission → 07; L4/L7, pools, trace propagation, trust boundaries → 29. |
| C15 · 15-distributed-unique-id-generators | 27 | Snowflake bit budget, worker allocation, clock rollback, restart, JSON precision → 27. Capacity becomes encoding ceiling, not measured throughput. |
| C16 · 16-gossip-protocol-and-failure-detection | 28 | SWIM, indirect probes, incarnation, phi suspicion, packet budgets and failure amplification → 28. |
| C17 · 17-vector-databases-and-approximate-nn | 34 | Exact baseline, HNSW, IVF/PQ/SQ, filtered recall, embedding version, memory → 34. Do not promise logarithmic worst-case search or guaranteed K filtered hits. |
| C18 · 18-websocket-sse-and-long-polling | 30 | Long polling/SSE/WebSocket, gateway registry/backplane, heartbeat, reconnect, capacity → 30. Service quotas and kernel tuning retained for review. |
| C19 · 19-api-protocols-http1-http2-http3-quic-grpc | 29 | HTTP/1.1/H2/H3, HOL boundaries, HPACK/QPACK, gRPC, connection reuse, UDP fallback, replay → 29. |
| C20 · 20-oauth2-oidc-and-distributed-token-authentication | 31 | OAuth/OIDC/PKCE, sessions/JWT/PASETO/WebAuthn distinction, JWKS, rotation/revocation → 31. Correct stale Bloom-filter authorization bypass. |
| C21 · 21-database-isolation-levels-acid-and-concurrency-anomalies | 01 | Lost update, write skew, anomalies, MVCC, constraints, sorted locking, retry → 01. Correct engine-independent isolation claims and simplified xmin visibility. |
| C22 · 22-circuit-breaker-bulkhead-and-fault-tolerance-patterns | 06, 07 | Deadline, breaker, bulkhead, adaptive concurrency, brownout, goodput → 06/07. Thresholds become workload hypotheses. |
| C23 · 23-event-sourcing-and-cqrs-architecture | 26 | Event store, CQRS independence, expected version, snapshots, ordered/idempotent projections, upcasting → 26. |
| C24 · 24-cloud-disaster-recovery-and-multi-region-active-active | 25 | Active-passive/pilot light/warm/hot standby, quota arithmetic, DR ladder, RTO/RPO, LWW/CRDT limits, capacity, routing, home-region fencing → 25. |
| C25 · 25-bot-defense-sybil-resistance-and-registration-abuse | 35 | Sybil cost model, risk ladder, layered enforcement, appeal and monitoring → 35. |
| C26 · 26-honeypot-fields-and-canary-traps | 35 | Honeypots/canaries, autofill and accessibility false positives, escalation → 35. UI boilerplate and timing heuristics remain reference, not identity proofs. |
| C27 · 27-disposable-email-and-domain-blocklists | 35 | Domain normalization, disposable-provider churn, Bloom prefilter, ownership verification, atomic list refresh → 35. Do not reject from probabilistic evidence alone. |
| C28 · 28-cloudflare-turnstile-managed-challenges | 36 | Server verification, scope, expiry, single use, ambiguous validation and retry, fallback → 36. Undocumented fingerprint/PAT internals and legal conclusions excluded from guarantees. |
| C29 · 29-google-recaptcha-v2-and-enterprise-risk-analysis | 36 | v2 challenge versus score/assessment, per-action policy, replay, accessible alternative → 36. Solver pricing, success rates, latency rankings excluded as unstable evidence. |
| C30 · 30-hashcash-and-client-side-proof-of-work | 37 | Expected work, partial-bit verification, signed challenge binding, one-time spending, device asymmetry → 37. No blanket privacy or decentralization claim. |
| L01 · 01-write-ahead-log-fsync-and-group-commit | 02, 03 | Failure classes, sync modes/errors, records, group commit → 02; torn tails, segments, checkpoints, B-tree redo → 03. Storage-stack I/O accounting retained as measurement exercise. |
| L02 · 02-lsm-trees-and-compaction | 03, 04 | MemTable/SSTable, visibility and snapshots, flush/manifest, recovery, corruption → 03/04; amplification, compaction policy and stalls → 04. |
| L03 · 03-leases-fencing-tokens-and-distributed-locks | 16 | Acquire/renew/release, monotonic durations, skew/RVN, fencing, orphans, lock-service failover, lock alternatives → 16; migration and region reuse linked later. |
| L04 · 04-idempotency-and-effectively-once-processing | 18, 21 | Intent keys, fingerprint, local atomic inbox, external UNKNOWN, takeover, replay horizon → 18; checkpoint/sink-generation details → 21. Notification-specific replacement APIs remain reference. |
| L05 · 05-change-streams-and-transactional-outbox | 20 | Outbox and cursor trap, ordering chain, CDC retention, bootstrap/gaps/deletes/schema → 20. Complete provider relay configurations remain reference. |
| L06 · 06-replication-quorums-and-read-your-writes | 14, 15 | Stored/applied/committed, RYW tokens, quorum overlap, failover, election, snapshots/repair/tombstones → 14/15. |
| L07 · 07-event-time-watermarks-and-checkpoints | 21 | Event/processing time, windows/watermarks, idle input, late path, preaggregation, barriers, replay, generation/sink recovery → 21. Bespoke per-writer checkpoint-tag flush protocol stays an explicitly scoped reference design. |
| L08 · 08-sharding-hot-keys-and-rebalancing | 12, 13, 17 | Routing/keys → 12; hot reads/writes and salting → 13; copy/tail/fence/flip, fan-out, cross-shard decisions → 17. |
| L09 · 09-multi-region-failover | 25 | Evidence/gate, RPO/RTO critical path, writer fencing, capacity/residency, failback, cells/shuffle sharding, game days → 25. Provider control-plane procedures remain reference. |
| L10 · 10-retries-timeouts-backpressure-and-load-shedding | 06, 07 | Deadline/retry/backoff/budgets/hedging → 06; admission/breakers/bulkheads/brownouts/metastability → 07. Repeated event-by-event snapshots consolidated. |
| L11 · 11-caching-and-invalidation | 10, 11 | Write patterns, refill races, versioned invalidation, RYW → 10; single-flight, eviction, cold starts, negative caching, CDN/browser policy → 11. |
| L12 · 12-queues-and-delivery-semantics | 19 | Lease receive loop, batch timers, errors/DLQ/redrive, FIFO/log head blocking, consumer rebalances, backlog/fan-out/claim check → 19. |
| L13 · 13-distributed-transactions-sagas-vs-two-phase-commit | 23, 24 | 2PC prepare/durable decision/recovery and isolation → 23; saga pivot, holds/TCC, uncertain partners, failed compensation, recovery and choreography → 24. |
| L14 · 14-rate-limiting-algorithms | 08, 09 | Fixed/sliding windows, token bucket/GCRA/leaky queue, atomic clock/state/TTL → 08; dimensions, hot budgets, live rules, regional grants, quotas, bypass → 09. |
| L15 · 15-time-series-storage-and-roll-ups | 22 | Labels/cardinality, head/WAL/chunks/blocks, delta/XOR, mergeable aggregates, percentiles/sketches/HLL, tiers/rates/gaps, lateness/re-roll/alerts → 22. |
What is intentionally outside the new teaching path
The original sources remain the reference shelf. The new path does not reproduce repeated definitions, end-to-end retellings of the same trace, fixed ten-section component scaffolds, engine-by-engine marketing comparisons, or repeated interview answers. The concept is taught once and recalled under a new constraint later.
Large provider configurations, complete UI widgets, long JSON exchanges, per-service limits/defaults, price tables, and operational recipes remain accessible in their original files. They are reference-retained, not asserted to have been ported or independently validated. Their exact code/diagram locations are indexed in SOURCE_INVENTORY.json. The new lessons supply small implementations and traces of the mechanism; they are not replacements for provider SDK documentation or full production applications.
Unsupported vendor internals, universal performance claims, fixed risk thresholds, and blanket privacy/compliance guarantees are intentionally excluded from the new assertions. CONTENT_AUDIT identifies representative corrections and remaining verification work. Do not treat a source citation as endorsement of every sentence in that source.
Per-lesson provenance
01 · Two successful transactions, one impossible result
lessons/01-the-last-seat.md draws from 21-database-isolation-levels-acid-and-concurrency-anomalies.
02 · The write that survived the process but not the machine
lessons/02-the-promise-in-ok.md draws from 07-write-ahead-log-and-lsm-trees, 01-write-ahead-log-fsync-and-group-commit.
03 · The file exists, but recovery must ignore it
lessons/03-recovering-the-right-history.md draws from 07-write-ahead-log-and-lsm-trees, 01-write-ahead-log-fsync-and-group-commit, 02-lsm-trees-and-compaction.
04 · Fast writes, then a completely frozen database
lessons/04-the-compaction-debt.md draws from 07-write-ahead-log-and-lsm-trees, 02-lsm-trees-and-compaction.
05 · Can we prove the key is absent without reading it?
lessons/05-asking-a-cheaper-question.md draws from 03-bloom-filters-and-counting-filters.
06 · The client gave up; the server kept working
lessons/06-the-timeout-that-did-not-cancel.md draws from 22-circuit-breaker-bulkhead-and-fault-tolerance-patterns, 10-retries-timeouts-backpressure-and-load-shedding.
07 · An optional widget exhausts the checkout pool
lessons/07-saving-the-healthy-half.md draws from 14-api-gateway-and-reverse-proxy, 22-circuit-breaker-bulkhead-and-fault-tolerance-patterns, 10-retries-timeouts-backpressure-and-load-shedding.
08 · The limiter that allows twice its advertised limit
lessons/08-one-bucket-one-decision.md draws from 02-distributed-rate-limiting, 14-rate-limiting-algorithms.
09 · Twenty correct limiters enforce the wrong limit
lessons/09-sharing-a-budget.md draws from 02-distributed-rate-limiting, 14-rate-limiting-algorithms.
10 · Deleting the cache resurrected the old price
lessons/10-the-price-that-came-back.md draws from 04-distributed-cache-patterns-and-eviction, 11-caching-and-invalidation.
11 · The database cannot survive a successful cache
lessons/11-when-the-cache-disappears.md draws from 04-distributed-cache-patterns-and-eviction, 11-caching-and-invalidation.
12 · Adding a server moved almost everything
lessons/12-where-a-key-lives.md draws from 01-consistent-hashing, 08-database-sharding-and-partition-keys, 08-sharding-hot-keys-and-rebalancing.
13 · The cluster is idle and one customer is throttled
lessons/13-the-hot-key.md draws from 01-consistent-hashing, 08-database-sharding-and-partition-keys, 08-sharding-hot-keys-and-rebalancing.
14 · The database acknowledged a write the replica cannot read
lessons/14-copies-that-disagree.md draws from 01-consistent-hashing, 09-distributed-consensus-raft-and-paxos, 06-replication-quorums-and-read-your-writes.
15 · Two machines both say they are the leader
lessons/15-who-may-commit.md draws from 09-distributed-consensus-raft-and-paxos, 06-replication-quorums-and-read-your-writes.
16 · The lease expired; the old worker did not
lessons/16-the-worker-that-returned.md draws from 06-distributed-locks-and-leases, 03-leases-fencing-tokens-and-distributed-locks.
17 · The copy finished, then the old owner accepted a write
lessons/17-moving-live-data.md draws from 01-consistent-hashing, 08-database-sharding-and-partition-keys, 08-sharding-hot-keys-and-rebalancing.
18 · The payment succeeded twice after one timeout
lessons/18-one-intent-many-attempts.md draws from 10-two-phase-commit-and-saga-orchestration, 04-idempotency-and-effectively-once-processing.
19 · The queue is healthy; the customer is still waiting
lessons/19-the-message-that-will-not-leave.md draws from 05-message-queues-vs-event-streams, 12-queues-and-delivery-semantics.
20 · The order committed, but nobody heard about it
lessons/20-the-announcement-that-never-happened.md draws from 12-change-data-capture-and-outbox-pattern, 05-change-streams-and-transactional-outbox.
21 · Yesterday changed after the stream restarted
lessons/21-counting-time-not-arrivals.md draws from 05-message-queues-vs-event-streams, 07-event-time-watermarks-and-checkpoints, 04-idempotency-and-effectively-once-processing.
22 · The dashboard recovered by hiding the incident
lessons/22-the-average-that-lied.md draws from 07-write-ahead-log-and-lsm-trees, 15-time-series-storage-and-roll-ups.
23 · All participants voted yes; no participant can finish
lessons/23-waiting-for-a-decision.md draws from 10-two-phase-commit-and-saga-orchestration, 13-distributed-transactions-sagas-vs-two-phase-commit.
24 · The refund failed after the booking failed
lessons/24-undo-is-another-operation.md draws from 10-two-phase-commit-and-saga-orchestration, 13-distributed-transactions-sagas-vs-two-phase-commit.
25 · Traffic failed over before authority did
lessons/25-moving-the-writer.md draws from 24-cloud-disaster-recovery-and-multi-region-active-active, 09-multi-region-failover.
26 · The current balance cannot explain its own history
lessons/26-rebuilding-a-view.md draws from 23-event-sourcing-and-cqrs-architecture.
27 · The unique ID generator repeated itself after restart
lessons/27-an-id-is-not-a-clock.md draws from 15-distributed-unique-id-generators.
28 · The failure detector removed a healthy machine
lessons/28-suspected-is-not-dead.md draws from 16-gossip-protocol-and-failure-detection.
29 · More connections did not fix the slow page
lessons/29-following-one-request.md draws from 14-api-gateway-and-reverse-proxy, 19-api-protocols-http1-http2-http3-quic-grpc.
30 · The socket reconnected; the messages did not
lessons/30-reconnecting-without-forgetting.md draws from 18-websocket-sse-and-long-polling.
31 · The token is genuine and the request is forbidden
lessons/31-a-valid-signature-is-not-permission.md draws from 20-oauth2-oidc-and-distributed-token-authentication.
32 · Autocomplete found the prefix and still timed out
lessons/32-the-prefix-that-scanned-everything.md draws from 13-trie-data-structure-and-inverted-index.
33 · The closest driver is invisible to the index
lessons/33-across-the-cell-boundary.md draws from 11-geospatial-geohash-quadtree-s2.
34 · The vector index returns ten excellent unauthorized matches
lessons/34-nearest-among-whom.md draws from 17-vector-databases-and-approximate-nn.
35 · Every account obeyed the limit; the attack still worked
lessons/35-cheap-accounts-expensive-consequences.md draws from 25-bot-defense-sybil-resistance-and-registration-abuse, 26-honeypot-fields-and-canary-traps, 27-disposable-email-and-domain-blocklists.
36 · The browser passed the challenge twice
lessons/36-the-proof-that-was-replayed.md draws from 28-cloudflare-turnstile-managed-challenges, 29-google-recaptcha-v2-and-enterprise-risk-analysis.
37 · The puzzle was hard once and free thereafter
lessons/37-paying-for-each-attempt.md draws from 30-hashcash-and-client-side-proof-of-work.