--- schema_version: "1.0" project_name: "reasons" updated_at: "2026-08-15T23:54:53+00:00" node_count: 482 generator: ftl-reasons/0.48.0 --- # Belief Registry ## Repos - sdi-implementations: /Users/ben/git/sdi-implementations ## Claims ### abstractions-minimize-new-concepts [IN] DERIVED The codebase minimizes conceptual surface area through two complementary strategies: logical abstractions decouple semantics from physical storage (offsets survive trimming, DLQs are regular topics, tombstones model deletion as metadata), and derivation reuses existing data and structures rather than inventing new mechanisms (IDs from content, capabilities from sign-negated heaps) — together keeping the total concept count far below the feature count. - Depends on: logical-abstraction-decouples-semantics-from-storage, derivation-over-creation ### access-control-defaults-favor-availability-over-security [IN] DERIVED Access control implementations default toward permissiveness: S3 allows requests when no policy exists (opposite of AWS IAM's default-deny), and Google Drive short-circuits the full permission inheritance walk for owners — both reduce access-denied friction at the cost of security strictness. - Depends on: s3-policy-default-allow, gdrive-owner-bypasses-permission ### accumulative-state-scales-without-coordination [IN] DERIVED The architecture scales without state coordination: logical indirection decouples topology from data (adding layers without touching existing state), and irreversibly accumulative state eliminates the need for compaction, migration, or distributed garbage collection — scaling adds abstraction but never revisits existing state. - Depends on: state-is-irreversibly-accumulative, scaling-uses-logically-uniform-indirection ### ad-click-dedup-global-not-per-ad [IN] OBSERVATION Ad click deduplication keys on `event_id` alone (global registry), not per-ad, converting at-least-once delivery into exactly-once aggregation. - Source: entries/2026/06/05/topic-consistency-models.md ### ad-click-window-lifecycle-one-directional [IN] OBSERVATION Ad click aggregation windows follow a one-directional lifecycle: OPEN → CLOSED → FINALIZED, with only `advance_watermark` able to finalize — event processing alone never does. - Source: entries/2026/06/05/topic-consistency-models.md ### adaptation-is-bidimensional-across-frequency-and-risk [IN] DERIVED The architecture adapts along two largely independent dimensions: cost allocation adapts to access frequency (the celebrity threshold converts follower count into a write-vs-read cost placement decision, partitioning authors between eager push and read-time pull), while safety mechanisms adapt to domain risk (explicit locking for financial domains, coordination-free structural discipline for social domains). Both adaptations appear structurally encoded in module design rather than being purely runtime decisions, though the celebrity threshold itself operates as a runtime decision boundary. - Depends on: hybrid-fanout-instantiates-adaptive-cost-model, architecture-adapts-mechanisms-to-domain-risk ### adaptation-over-invention [IN] DERIVED The codebase consistently repurposes existing abstractions for special cases — Python's min-heap via sign negation for descending order, regular topics as dead-letter queues, first message ID as thread ID — rather than introducing new data structures or infrastructure. - Depends on: heap-sign-negation-repurposes-min-heap, special-cases-reuse-existing-abstractions ### adaptive-coordination-enables-quality-preserving-scaling [IN] DERIVED The architecture scales horizontally without quality degradation because coordination strategy adapts to correctness cost: low-risk domains use coordination-free structural mechanisms that inherently preserve triple convergence (correctness, simplicity, performance), while high-risk financial domains add targeted pessimistic or optimistic coordination only where the cost of incorrectness justifies the complexity. - Depends on: coordination-strategy-adapts-to-correctness-cost, coordination-free-scaling-preserves-triple-convergence ### algorithmic-simplicity-is-preferred-over-optimal-performance [IN] DERIVED The codebase consistently favors algorithmic correctness and simplicity over performance optimality: search heuristics use admissible but loose bounds (haversine for road distance, global max speed for time estimates), guaranteeing optimal results at the cost of extra exploration, while data structure operations use brute-force approaches (linear prefix scan, key-by-key Merkle diff, full re-sort on insertion, linear cache purge), correct by simplicity at pedagogical scale. - Depends on: routing-heuristics-prioritize-correctness-over-tightness, brute-force-acceptable-at-pedagogical-scale ### algorithmic-simplicity-reinforces-structural-correctness [IN] DERIVED The codebase exhibits two complementary simplicity strategies — preferring simpler algorithms (loose but admissible heuristics, brute-force at pedagogical scale) and constraining existing structures for correctness (immutable values, synchronized collections) — that appear mutually compatible: simpler algorithms tend to have fewer edge cases that structural constraints must handle, and constraining existing structures is more tractable when the algorithms operating on them are straightforward. - Depends on: algorithmic-simplicity-is-preferred-over-optimal-performance, correctness-through-structural-reuse ### all-monetary-operations-maintain-double-entry-invariant [IN] DERIVED All monetary operations maintain the double-entry invariant under concurrency: payment ledgers create balanced debit-credit pairs for every movement, and wallet transfers are deadlock-free with frozen-check inside the lock — unless the non-atomic balance check allows concurrent payments to create valid double-entry pairs for overdrafted amounts, producing an internally consistent but financially incorrect ledger. - Depends on: payment-double-entry-guarantees-balance-integrity, wallet-transfers-are-safe-under-concurrency - Unless: payment-balance-check-not-atomic ### all-stateful-generators-thread-safe [IN] OBSERVATION Every generator with mutable state (Snowflake, Ticket, Flake, ULID, Coordinator) protects it with a `threading.Lock`. - Source: entries/2026/06/05/unique-id-generator-unique_id_generator.md ### append-only-semantics-span-storage-and-streaming [IN] DERIVED Both versioned storage (S3 version lists, GDrive version histories) and stream processing (finalized aggregation windows) use append-only semantics where history is never overwritten or retracted, ensuring complete audit trails and preventing any form of historical revision — a cross-cutting pattern spanning both persistence and computation. - Depends on: append-only-versioning-makes-restore-non-destructive, watermark-finalization-is-irreversible ### append-only-versioning-makes-restore-non-destructive [IN] DERIVED Both S3 and Google Drive model version history as append-only lists where restoring an old version creates a new entry rather than rolling back, preserving full audit trails and making every restore operation non-destructive. - Depends on: s3-version-list-append-only, gdrive-restore-creates-new-version ### approximation-spans-counting-windowing-and-similarity [IN] DERIVED The codebase's approximation strategies form a complete accuracy-cost spectrum: probabilistic structures (HLL for cardinality, Morris for counting, SimHash for similarity) trade accuracy for space, and the sliding window counter trades exact window boundaries for bounded resource consumption via current/previous window weighting — together covering counting, rate limiting, and content dedup. - Depends on: probabilistic-structures-trade-accuracy-for-space, sliding-window-counter-weighted-approximation ### architectural-invariants-are-scale-independent-and-redundantly-enforced [IN] DERIVED The architecture's core invariants exhibit two orthogonal robustness properties: quality guarantees are scale-and-layer-independent (holding regardless of module count, implementation complexity, or abstraction layer), and state irreversibility is redundantly prevented (operational guards, structural monotonicity, and forward-only state machines enforce it at different architectural levels) — neither property depends on the other, creating a robustness product. - Depends on: quality-guarantees-are-scale-and-layer-independent, state-reversal-is-redundantly-prevented ### architectural-trinity-of-correctness-scaling-and-cost [IN] DERIVED Self-reinforcing correctness, coordination-free scaling, and robust cost allocation form a composable architectural trinity: modules independently generate and verify correctness (closed loop), scale by adding logical indirection without coordination (accumulative state), and safely reallocate work between write and read paths (forward-only semantics prevent cost-shifting from undermining either property). - Depends on: self-reinforcing-correctness-composes-with-coordination-free-scaling, forward-only-enables-robust-cost-allocation ### architecture-adapts-mechanisms-to-domain-risk [IN] DERIVED The architecture systematically adapts its safety mechanisms to domain risk across two independent dimensions: coordination strategy scales with correctness cost (explicit locking for financial domains vs coordination-free construction elsewhere), and cost allocation between write and read paths is robust through forward-only guarantees that prevent shifted computation from requiring re-verification — both the presence and weight of safety mechanisms track the consequence of failure. - Depends on: financial-correctness-combines-locking-with-structural-asymmetry, write-correctness-is-both-structural-and-coordination-free, forward-only-enables-robust-cost-allocation ### autocomplete-cache-consistency [IN] OBSERVATION Every trie mutation (insert, increment, delete) immediately rebuilds `top_k_cache` for all ancestor nodes via `_update_caches_on_path`; caches are never stale between operations. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### autocomplete-decay-is-read-time [IN] OBSERVATION Time decay is computed lazily at query time in `search_prefix` using `raw_freq * decay_factor^hours_elapsed`; raw frequencies stored in the trie are never modified by decay. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### autocomplete-delete-is-soft [IN] OBSERVATION Deleting a query zeroes its frequency and unsets `is_end` but does not remove trie nodes from the tree structure — deleted queries leave structural residue. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### autocomplete-normalize-at-boundary [IN] OBSERVATION All public methods in `AutocompleteTrie` lowercase and truncate queries to 200 characters before any trie operation; internal methods assume normalized input. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### autocomplete-overfetch-compensates-for-filtering [IN] DERIVED The autocomplete service overfetches results (`k + len(blocklist) * 2`) to compensate for blocklist removals, maintaining result count — but substring matching can remove far more results than the linear compensation formula anticipates. - Depends on: autocomplete-service-overfetches-for-blocklist - Unless: autocomplete-blocklist-is-substring ### autocomplete-search-is-robust [IN] DERIVED Autocomplete provides consistent, normalized search through boundary normalization (lowercasing, length truncation) and eagerly-rebuilt top-k caches, but fuzzy matching is limited to single-character edits on the last character only — meaning most mid-word typos produce zero results despite the system's otherwise thorough input handling. - Depends on: normalize-once-at-system-boundary, autocomplete-cache-consistency - Unless: autocomplete-fuzzy-is-last-char-only ### autocomplete-service-overfetches-for-blocklist [IN] OBSERVATION `AutocompleteService` requests `k + len(blocklist) * 2` results from the trie to compensate for results that will be removed by blocklist filtering. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### autocomplete-trie-k-floor-is-10 [IN] OBSERVATION The `AutocompleteService` constructor forces `k=max(k, 10)` for the internal trie, even if the service default is smaller, to provide headroom for blocklist filtering. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### balance-derived-from-ledger [IN] OBSERVATION Account balances are computed by scanning the full ledger on every call to `get_balance`, not cached; the ledger is the single source of truth - Source: entries/2026/06/05/payment-system-payment_system.md ### batch-classification-coupled-to-process-event [IN] OBSERVATION `process_batch` infers per-event rejection reasons by diffing global stats counters, creating an implicit coupling to the check ordering inside `process_event`. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### bloom-filter-add-couples-with-might-contain [IN] OBSERVATION `BloomFilter.add()` internally calls `might_contain()` and then compensates for its side effect on `_negative_check_count` by decrementing — if `might_contain`'s bookkeeping logic changes, `add` breaks silently. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### bloom-filter-prevents-frontier-duplicates [IN] OBSERVATION Every URL is added to the Bloom filter before being pushed into the frontier, so the frontier never enqueues a URL that has already been seen (modulo false positives, which cause URLs to be permanently skipped). - Source: entries/2026/06/05/web-crawler-web_crawler.md ### both-indexes-use-haversine-filter [IN] OBSERVATION Both GeohashIndex.nearby and Quadtree.query_range use the coarse-to-fine pattern: spatial structure narrows candidates, then haversine filters to exact distance - Source: entries/2026/06/05/proximity-service-proximity_service.md ### boundary-normalization-serves-defense-and-correctness [IN] DERIVED Normalizing inputs once at system boundaries serves dual architectural purposes: it establishes the perimeter defense model that maintains internal data quality (enabling trusted internal callers), and it independently enables robust query behavior (autocomplete search operates on consistent normalized state with eagerly-rebuilt caches) — a single mechanism yielding both security and feature correctness. - Depends on: autocomplete-search-is-robust, perimeter-defense-ensures-data-quality ### bounded-collections-trade-completeness-for-memory [IN] DERIVED Four systems use fixed-capacity collections (deque maxlen, list pruning) that silently drop oldest entries to bound memory growth, accepting silent data loss as the tradeoff for guaranteed memory bounds. - Depends on: news-feed-cache-is-bounded-deque, nearby-friends-history-bounded-100, url-shortener-click-history-bounded, gdrive-version-list-bounded ### brute-force-acceptable-at-pedagogical-scale [IN] DERIVED Four systems use algorithmically sub-optimal implementations — linear prefix scan, key-by-key Merkle diff, full re-sort on insertion, linear purge on unfollow — where O(log n) alternatives exist, prioritizing implementation clarity over asymptotic efficiency at the pedagogical scale these modules target. - Depends on: geohash-nearby-prefix-scan-is-linear, kv-merkle-tree-brute-force-diff, stock-exchange-price-sort-is-full-resort, news-feed-unfollow-purges-via-linear-scan ### cascade-effects-propagate-through-graph-traversal [IN] DERIVED Graph-based effects propagate through traversal in two independent domains: folder deletion cascades via BFS to soft-delete all descendants, and pipeline failure cascades through the DAG to skip transitively dependent stages — both use graph structure to scope the blast radius of a triggering event. - Depends on: gdrive-soft-delete-cascade, dag-failure-cascade ### ch-add-remove-idempotent [IN] OBSERVATION `add_node` on an existing node and `remove_node` on a missing node are both no-ops returning empty results, making the ring safe against duplicate operations. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### ch-default-hash-32bit [IN] OBSERVATION The default hash function truncates MD5 to 32 bits (first 4 bytes of the digest), mapping all positions to the `[0, 2^32)` ring space. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### ch-get-nodes-deduplicates-physical [IN] OBSERVATION `get_nodes` walks clockwise and skips virtual nodes belonging to already-collected physical nodes, guaranteeing distinct physical nodes for replication. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### ch-migration-tracking-optional [IN] OBSERVATION Both `add_node` and `remove_node` accept an optional `keys` list and report which keys moved — the ring itself is stateless w.r.t. data and only computes migration impact when given a key set. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### ch-stats-measures-arc-ownership [IN] OBSERVATION `get_stats` computes load standard deviation from ring arc length ownership per physical node, not from actual key counts — it's a theoretical balance metric. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### ch-triple-bookkeeping [IN] OBSERVATION The ring maintains three synchronized structures (`_sorted_positions`, `_position_to_node`, `_node_positions`) as the price of O(log n) lookups via bisect — all three must stay consistent on every add/remove. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### ch-vnode-naming-scheme [IN] OBSERVATION Virtual nodes are keyed as `"{node_id}#{i}"` for `i` in `range(num_virtual_nodes)`, so the hash distribution depends entirely on the hash function's behavior on these strings. - Source: entries/2026/06/05/consistent-hashing-consistent_hashing.md ### chat-contacts-always-bidirectional [IN] OBSERVATION `send_message` adds both directions to the contacts graph as a side effect — contacts are always symmetric. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-dm-conversation-dedup [IN] OBSERVATION DM conversations use a deterministic sorted-pair ID (`dm:{min}:{max}`) guaranteeing exactly one conversation per user pair regardless of who messages first. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-dual-ordering-scheme [IN] OBSERVATION Messages carry both per-conversation sequence numbers (for pagination and read cursors) and global Lamport timestamps (for causal ordering), serving different purposes by design. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-dual-ordering-sequence-and-lamport [IN] OBSERVATION Chat system uses per-conversation monotonic sequence numbers for total order within a conversation and Lamport timestamps for cross-conversation causal ordering. - Source: entries/2026/06/05/topic-consistency-models.md ### chat-fanout-on-write [IN] OBSERVATION `_deliver` routes messages at send time based on recipient presence: online/away users get messages in `inbox`, offline users in `offline_queue` — this is fan-out-on-write, not fan-out-on-read. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-group-size-cap-500 [IN] OBSERVATION `add_member` raises `ValueError` if the group already has 500 or more members, enforcing a hard cap on group size. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-lamport-clock-is-thread-safe [IN] OBSERVATION The Lamport clock and per-conversation sequence numbers are protected by threading.Lock, making all clock/sequence increments atomic across send_message, send_group_message, add_member, and remove_member. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-monotonic-read-progress [IN] DERIVED Chat combines per-conversation sequence numbers with monotonic read cursors, guaranteeing that once a message is marked read, no earlier message in that conversation can regress to unread. - Depends on: chat-dual-ordering-sequence-and-lamport, chat-read-cursors-monotonic ### chat-offline-queue-flush-on-connect [IN] OBSERVATION When a user connects, their `offline_queue` is drained into `inbox` in FIFO order, preserving message arrival ordering. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-read-cursors-monotonic [IN] OBSERVATION `mark_read` only advances the read cursor; it silently ignores attempts to set a lower sequence number, preventing regression. - Source: entries/2026/06/05/chat-system-chat_system.md ### chat-soft-delete-preserves-sequence [IN] OBSERVATION Deleted messages remain in the conversation list with `deleted=True` and content replaced with `"[deleted]"`, preserving sequence number continuity for pagination. - Source: entries/2026/06/05/chat-system-chat_system.md ### click-aggregator-return-value-signaling [IN] OBSERVATION `process_event` returns `True`/`False` to signal acceptance or rejection — invalid states (duplicates, late arrivals) are expected in stream processing, not exceptional, so no exceptions are raised. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### complete-dependency-injection-enables-hermetic-testing [IN] DERIVED The combination of time injection (notification, rate limiter, crawler) and service injection (payment processor) covers both sources of test non-determinism — temporal behavior and external service responses — unless the inconsistent current_time fallback means some code paths silently revert to wall-clock time when injection is omitted. - Depends on: time-injection-enables-deterministic-testing, payment-processor-injectable - Unless: current-time-fallback-inconsistent ### concurrency-safety-strategy-varies-by-financial-risk [IN] DERIVED Financial systems use domain-appropriate concurrency strategies: wallets use pessimistic sorted locking (guaranteed deadlock-free, zero conflict window) while hotels use optimistic versioned locking (retry on conflict, higher throughput), matching strategy strictness to violation cost. - Depends on: wallet-transfers-are-safe-under-concurrency, hotel-occ-prevents-overbooking ### conflict-detection-varies-by-consistency-model [IN] DERIVED Three systems use distinct conflict detection strategies — sibling retention (KV), per-device version vectors (GDrive), and per-date version counters (hotel) — each matched to the system's merge semantics and consistency requirements. - Depends on: kv-node-stores-sibling-versions, gdrive-version-vector-conflict, hotel-reservation-optimistic-locking ### conflict-resolution-depth-scales-with-distribution [IN] DERIVED Conflict detection infrastructure scales with distribution topology: single-node systems detect conflicts at mutation time via optimistic locking, multi-device systems detect at sync time via version vectors, and fully distributed systems maintain ongoing anti-entropy covering both writes and deletes — each matching resolution complexity to the divergence characteristics its topology demands. - Depends on: conflict-detection-varies-by-consistency-model, kv-anti-entropy-covers-writes-and-deletes ### conflict-resolution-is-forward-only-at-all-distribution-levels [IN] DERIVED Conflict resolution at all distribution levels resolves concurrency conflicts by moving forward rather than rolling back: single-node optimistic locking retries with updated state, multi-replica sibling retention adds all concurrent versions, and multi-device version vectors create new version entries — no conflict resolution mechanism discards or reverses already-committed state, containing temporal gaps without reversal. - Depends on: conflict-resolution-depth-scales-with-distribution, forward-only-preserves-correctness-despite-accepted-gaps ### consistency-strategy-scales-uniformly-with-distribution [IN] DERIVED Both conflict resolution and deletion strategy scale in the same way with distribution topology — simple structural mechanisms for single-node systems (optimistic locking, soft delete), metadata-based approaches for replicated systems (version vectors, tombstones) — showing a uniform architectural response where distribution complexity drives strategy sophistication across independent concerns. - Depends on: conflict-resolution-depth-scales-with-distribution, deletion-strategy-scales-with-distribution ### consistent-hashing-is-a-stateless-topology-abstraction [IN] DERIVED The consistent hash ring is a pure topology abstraction with no data-plane state: node operations are idempotent (add/remove on existing/missing nodes are no-ops), migration tracking is optional (callers pass keys in, the ring reports movements), and preference list construction automatically deduplicates physical nodes — making the ring a stateless function from key to node list that is safe to use concurrently and compose freely. - Depends on: ch-add-remove-idempotent, ch-migration-tracking-optional, ch-get-nodes-deduplicates-physical ### consumer-model-prioritizes-simplicity-over-flexibility [IN] DERIVED The message queue's consumer model prioritizes implementation simplicity over operational flexibility: consumer groups are permanently bound to a single topic with no multi-topic subscription mechanism, and rebalancing uses simple modular partition assignment rather than sticky or cooperative protocols. - Depends on: dmq-one-topic-per-consumer-group, dmq-rebalance-modular-assignment ### control-data-separation-enables-forward-progress [IN] DERIVED Pipeline forward progress is architecturally enabled by control-data separation: the DAG control plane determines failure cascading and stage ordering independently of the mutable ctx dict data plane, allowing the forward-only design principle to skip failed branches without corrupting shared state — a concrete mechanism underlying the codebase's maximum-progress philosophy. - Depends on: video-pipeline-separates-control-from-data-flow, forward-only-design-prevents-regression-and-maximizes-progress ### coordination-free-scaling-preserves-triple-convergence [IN] DERIVED The architecture scales horizontally while preserving per-module quality convergence: because correctness, simplicity, and performance are structurally self-contained within each independent module, scaling via accumulative state and logical indirection layers neither introduces coordination overhead nor degrades any of the three convergent properties. - Depends on: accumulative-state-scales-without-coordination, module-level-triple-convergence ### coordination-strategy-adapts-to-correctness-cost [IN] DERIVED The architecture adapts its coordination strategy to the cost of incorrectness: financial domains use explicit locking (pessimistic for wallets, optimistic for hotels) because monetary errors are high-cost and must be prevented, while non-financial domains achieve correctness coordination-free through deterministic identity derivation and structural construction because eventual consistency is acceptable — the mechanism complexity matches the domain's tolerance for inconsistency. - Depends on: financial-correctness-combines-locking-with-structural-asymmetry, write-correctness-is-both-structural-and-coordination-free ### correctness-and-simplicity-share-the-same-mechanism [IN] DERIVED The codebase achieves both correctness and simplicity through the same underlying mechanism: leveraging existing structures (heaps, topics, sorted lists) rather than inventing new ones, so that correctness guarantees of underlying structures are inherited from reuse while construction-time constraints eliminate entire classes of bugs — parsimony and safety are not in tension but emerge from the same design choices. - Depends on: correctness-unifies-reuse-and-construction, derivation-over-creation ### correctness-by-construction-not-validation [IN] DERIVED Correctness is enforced by structural construction rather than runtime validation: immutable values and synchronized data structures prevent state corruption, while monotonic progressions (read cursors, window lifecycles) make regression unrepresentable — together eliminating entire bug classes at compile-time rather than catching them at runtime. - Depends on: structural-discipline-prevents-consistency-bugs, state-ratchets-prevent-regression-across-domains ### correctness-has-universal-floor-and-adaptive-ceiling [IN] DERIVED The architecture achieves layered correctness assurance: scale-independent invariants enforced redundantly at multiple architectural levels provide a universal correctness floor (quality guarantees hold regardless of module count, state reversal prevented by overlapping mechanisms), while domain-adapted coordination and self-reinforcing per-module loops raise the ceiling where domain risk justifies it — the floor is never violated, the ceiling adapts to correctness cost. - Depends on: architectural-invariants-are-scale-independent-and-redundantly-enforced, correctness-scales-through-adaptation-and-self-reinforcement ### correctness-is-layered-and-self-reinforcing [IN] DERIVED The architecture achieves correctness redundancy through two complementary strategies operating at different granularities: defense-in-depth provides layered guarantees across system boundaries (perimeter normalization ensures clean inputs, structural construction prevents internal corruption), while per-module self-reinforcement creates closed verification loops (structural construction generates testable properties that verify the construction itself). - Depends on: defense-in-depth-correctness, correctness-is-self-reinforcing-per-module ### correctness-is-self-reinforcing-per-module [IN] DERIVED Each module independently achieves a closed correctness loop: structural construction generates testable properties, deterministic testing verifies them, and module isolation prevents cross-contamination — making correctness self-reinforcing at the module level rather than depending on codebase-wide coordination. - Depends on: correctness-loop-covers-all-critical-properties, modules-are-independently-correct ### correctness-loop-covers-all-critical-properties [IN] DERIVED The write-available, read-correct architecture with its closed testing-construction loop verifies all critical correctness properties — structural construction prevents write-path corruption while deterministic tests validate those same properties comprehensively — but only when all critical invariants are structurally enforced rather than left as developer assumptions. - Depends on: codebase-architecture-is-write-available-read-correct, testing-and-construction-form-a-closed-correctness-loop - Unless: assumed-invariants-are-unenforced ### correctness-scales-through-adaptation-and-self-reinforcement [IN] DERIVED The architecture's correctness is simultaneously adaptive and self-reinforcing at scale: coordination strategy adapts to domain risk (preserving quality during horizontal scaling), and layered correctness (defense-in-depth at boundaries plus per-module closed verification loops) ensures each module independently maintains its invariants — the two mechanisms compose without interference because adaptation operates on coordination overhead while self-reinforcement operates on invariant coverage. - Depends on: adaptive-coordination-enables-quality-preserving-scaling, correctness-is-layered-and-self-reinforcing ### correctness-simplicity-and-performance-converge [IN] DERIVED Three seemingly independent architectural qualities — correctness, simplicity, and performance — emerge from the same structural approach: reusing existing constructs produces correctness, minimizing new concepts produces simplicity, and aligning cost allocation with access patterns produces performance, such that improving one quality tends to improve the others rather than trading off. - Depends on: correctness-and-simplicity-share-the-same-mechanism, quality-and-performance-strategies-are-aligned ### correctness-through-structural-reuse [IN] DERIVED The codebase achieves correctness by constraining existing structures (immutable values that prevent aliasing, synchronized collections that prevent desync, repurposed min-heaps via sign negation) rather than inventing specialized abstractions, making correctness properties compositional and verifiable from known building blocks. - Depends on: structural-discipline-prevents-consistency-bugs, adaptation-over-invention ### correctness-unifies-reuse-and-construction [IN] DERIVED The codebase achieves correctness through two complementary mechanisms: spatial reuse (repurposing existing structures like heaps, topics, and lists with structural constraints) and temporal ratchets (monotonic cursors, irreversible finalization that prevent state regression) — together covering both structure-domain and time-domain consistency without purpose-built validation. - Depends on: correctness-through-structural-reuse, correctness-by-construction-not-validation ### cost-model-adapts-to-access-frequency [IN] DERIVED The read-heavy default cost model (reads bear increasing correctness burden as distribution complexity grows) is selectively overridden for high-read-frequency paths (autocomplete caches, leaderboard reindexing pre-compute at write time), creating an access-pattern-aware cost allocation rather than a uniform reads-pay policy. - Depends on: read-cost-scales-with-system-complexity, write-cost-allocation-matches-access-pattern ### crawl-uses-simulated-clock [IN] OBSERVATION The crawl loop advances a `sim_time` counter for politeness scheduling rather than calling `time.sleep()`, making the simulation deterministic; real `time.time()` is only used to measure total crawl duration for stats. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### crawler-layered-dedup-bloom-then-simhash [IN] OBSERVATION Deduplication is two-tiered: the Bloom filter rejects exact-URL revisits first (O(k) per check), then SimHash rejects near-duplicate content (linear scan over seen hashes) — content dedup only runs for URLs that pass the Bloom filter. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### crawler-normalize-once-convention [IN] OBSERVATION URLs are normalized via `URLNormalizer.normalize()` at the point of insertion into the Bloom filter, frontier, and SimulatedWeb; downstream code assumes URLs are already canonical. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### crawler-three-layer-dedup [IN] DERIVED The web crawler achieves comprehensive deduplication through three coordinated layers: URL normalization at ingestion boundaries, Bloom filter for O(k) exact-URL rejection, and SimHash for near-duplicate content detection. - Depends on: crawler-layered-dedup-bloom-then-simhash, bloom-filter-prevents-frontier-duplicates, crawler-normalize-once-convention ### dag-failure-cascade [IN] OBSERVATION When a `ProcessingDAG` stage fails, all transitively dependent stages are marked SKIPPED; independent branches continue executing. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### daily-limit-only-counts-outflows [IN] OBSERVATION Daily spending is computed from `withdrawal` and `transfer_out` transactions only; deposits and incoming transfers are uncapped. - Source: entries/2026/06/05/digital-wallet-wallet.md ### data-isolation-gaps-parallel-access-control-gaps [IN] DERIVED Two data-plane isolation gaps exist in the implementations: BCC recipients are stored alongside to/cc in the email record, which could leak BCC information to other recipients in a real system, and the presigned URL signing secret is generated once at class level rather than per instance, so all ObjectStorage instances in the same process share a single HMAC key — widening the blast radius if that key is compromised. - Depends on: email-service-bcc-stored-in-record, s3-presigned-secret-is-class-level ### dedup-and-finalization-are-coordinated [IN] DERIVED Dedup retention outlives the aggregation window by 2×, and finalized results are irrevocable — this is coordinated design: since emitted results cannot be retracted, the system must ensure duplicates are caught before finalization, requiring dedup coverage to extend beyond the window boundary as a correctness invariant. - Depends on: dedup-outlives-aggregation-window, watermark-finalization-is-irreversible ### dedup-is-stratified-across-boundaries-and-accuracy-levels [IN] DERIVED The architecture applies dedup at three independent system boundaries with accuracy adapted to cost: exact key-based dedup at API boundaries (idempotency keys for hotel, payment, ad-click), exact event-based dedup at stream processing boundaries (coordinated dedup with watermark finalization), and approximate content-based dedup at crawling boundaries (Bloom filter + SimHash) — each boundary uses the mechanism whose accuracy-memory tradeoff fits its domain's scale and failure cost. - Depends on: idempotency-keys-ignore-payload-content, forward-only-stream-processing-is-exactly-once, probabilistic-dedup-trades-memory-for-coverage ### dedup-outlives-aggregation-window [IN] DERIVED The dedup registry retains entries for 2× the allowed lateness, ensuring late-arriving duplicates are still caught even after their aggregation window has been finalized by the watermark — the dedup horizon intentionally exceeds the processing horizon. - Depends on: dedup-pruning-uses-2x-lateness, watermark-drives-finalization ### dedup-pruning-uses-2x-lateness [IN] OBSERVATION The dedup registry evicts entries older than `2 * allowed_lateness` on watermark advance, meaning dedup coverage extends beyond the late-event acceptance window. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### defense-in-depth-correctness [IN] DERIVED The architecture pursues defense-in-depth correctness through two complementary layers: perimeter normalization establishes clean inputs at system boundaries (serving both security and feature correctness), while structural construction (immutability, synchronized structures, state ratchets) enforces correct state transitions internally — though this structural discipline is not universally applied, with critical invariants like quorum overlap and payment atomicity remaining assumed but unenforced. Where both layers are present, they reduce an important class of corruption bugs, but gaps in structural enforcement mean full lifecycle coverage is not yet achieved. - Depends on: boundary-normalization-serves-defense-and-correctness, structural-correctness-is-universally-applied ### deletion-is-append-only-across-all-contexts [IN] DERIVED Deletion never destroys data regardless of distribution level or system type: single-node soft deletes preserve structural invariants, distributed tombstones prevent resurrection, versioned storage appends delete markers, and finalized stream results are irrevocable — the entire data lifecycle is append-only from local state through distributed storage to stream processing. - Depends on: deletion-strategy-scales-with-distribution, append-only-semantics-span-storage-and-streaming ### deletion-is-cautious-at-every-level [IN] DERIVED Deletion is uniformly cautious across all system types: single-node systems require preconditions before permanent removal (empty buckets, trash-first workflow), and replicated/versioned systems model deletion as metadata rather than physical erasure (tombstones, delete markers) — the codebase provides no path to immediate, unguarded data destruction. - Depends on: deletion-is-guarded-by-preconditions, deletion-is-metadata-in-replicated-systems ### deletion-is-doubly-preserved [IN] DERIVED Data preservation through deletion is enforced by two independent mechanisms: preconditions prevent premature deletion (empty-bucket requirements, trash-first workflows) and the deletion operation itself preserves data (append-only tombstones, delete markers, version entries) — neither alone suffices, but together they guarantee no data is irrecoverably lost through a delete operation at any distribution level. - Depends on: deletion-is-cautious-at-every-level, deletion-is-append-only-across-all-contexts ### deletion-is-guarded-by-preconditions [IN] DERIVED Permanent deletion requires satisfied preconditions — S3 buckets must be logically empty, emails must be trashed before permanent removal — enforcing a deliberate multi-step process that prevents accidental irreversible data loss through a single operation. - Depends on: s3-bucket-delete-requires-empty, email-service-two-phase-delete ### deletion-is-metadata-in-replicated-systems [IN] DERIVED In replicated and versioned storage, deletion is modeled as appending metadata (tombstones, delete markers, new versions) rather than destroying data, because physical removal would cause resurrection from replicas or loss of restore capability. - Depends on: soft-delete-prevents-distributed-resurrection, append-only-versioning-makes-restore-non-destructive ### deletion-reinforces-monotonic-state [IN] DERIVED State monotonicity has no exception path: because deletion never destroys data (preconditions prevent premature removal, append-only metadata preserves history), the operation most likely to violate monotonic accumulation is itself accumulative — deletion reinforces rather than threatens the monotonic state model. - Depends on: deletion-is-doubly-preserved, state-is-monotonically-accumulative ### deletion-strategy-scales-with-distribution [IN] DERIVED Deletion strategy scales in complexity with system distribution: single-node systems use soft delete to preserve structural invariants (sequence contiguity, trie connectivity), distributed systems additionally require tombstones and delete markers for anti-entropy, and the KV store demonstrates both layers coexisting in a single system. - Depends on: soft-delete-is-dual-purpose, kv-anti-entropy-covers-writes-and-deletes ### delivery-guarantees-follow-write-read-cost-asymmetry [IN] DERIVED Message delivery guarantees enforced at the consumer side instantiate the architecture's broader read-path responsibility pattern: just as KV reads absorb convergence (repair) and computation (lazy evaluation), message consumers absorb delivery semantics (at-least-once vs exactly-once) through their own poll/commit behavior, keeping the write/publish path simple and coordination-free. - Depends on: message-delivery-guarantees-are-consumer-side, reads-are-active-convergence-engines ### derivation-over-creation [IN] DERIVED The codebase systematically derives new capabilities from existing data and structures rather than introducing new mechanisms: identifiers from existing pairs and messages (eliminating coordination), data structures from sign-flipped heaps and repurposed topics (inheriting proven properties) — favoring derivation over creation at both the data and infrastructure levels. - Depends on: identity-derivation-trades-validation-for-simplicity, adaptation-over-invention ### design-to-verification-traceability [IN] DERIVED The codebase achieves end-to-end traceability from design specification to runtime verification: prescriptive plans create verifiable specifications, structural construction ensures correctness properties are testable by design, and deterministic testing validates the correspondence — forming a plan-to-construction-to-verification pipeline. - Depends on: plan-to-implementation-correspondence-is-verifiable, structural-correctness-and-testability-are-co-designed - Unless: no-divergence-annotations ### deterministic-ids-eliminate-coordination [IN] DERIVED Both chat and email derive identifiers deterministically from existing data (sorted user-pair for DM conversations, first message ID for threads) rather than generating separate IDs, eliminating coordination overhead and guaranteeing idempotent ID creation. - Depends on: chat-dm-conversation-dedup, email-service-thread-id-is-first-msg ### deterministic-testability-by-design [IN] DERIVED The combination of standalone stdlib-only modules and explicit time injection creates conditions favorable to hermetic, deterministic testing in several SDI implementations — modules can be verified without external services due to their self-contained design, and the three systems using time injection can be tested without time mocking. However, not all 25 modules inject time, and inconsistent defaults at integration boundaries limit how uniformly this property holds across the full codebase. - Depends on: time-injection-enables-deterministic-testing, sdi-modules-are-standalone-learning-artifacts ### dmq-delivery-semantics-in-poll [IN] OBSERVATION The three delivery modes (at_least_once, at_most_once, exactly_once) are enforced entirely within `poll()` and `commit()`, not in the publish path. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### dmq-dlq-is-regular-topic [IN] OBSERVATION Dead-letter queues are standard topics with `__dlq_` prefix, created lazily on first failure and consumable through the same poll/commit API. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### dmq-one-topic-per-consumer-group [IN] OBSERVATION Each ConsumerGroup is permanently bound to a single topic at creation; there is no mechanism for multi-topic subscription. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### dmq-partition-offset-is-logical [IN] OBSERVATION Partition offsets are logical (not physical array indices); `base_offset` adjusts after trimming so consumers using stored offsets see consistent numbering across retention evictions. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### dmq-rebalance-modular-assignment [IN] OBSERVATION Consumer group rebalancing uses simple modular assignment: partition `p` goes to `consumers[p % len(consumers)]`, producing deterministic assignments for the same consumer list. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### dmq-retention-trimmed-on-publish [IN] OBSERVATION Retention is enforced per-publish: every `publish()` call trims the target partition. Messages are never evicted between publishes. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### dmq-two-tier-offset-tracking [IN] OBSERVATION `current_offset` advances on `poll()` and `committed_offset` advances on explicit `commit()`; the gap between them is the uncommitted window of delivered-but-unconfirmed messages. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### domain-excellence-composes-with-universal-invariant-enforcement [IN] DERIVED Domain-adapted specialization (achieving excellence through financial risk-adaptation and symmetric-domain quality optimization) and scale-independent invariant enforcement (quality guarantees holding regardless of scale or layer, with redundant prevention of state reversal) appear compositionally compatible: the antecedents establish that specialization operates within domain-specific coordination strategies while invariants hold independently of implementation complexity — suggesting that adding new domain specializations would customize coordination mechanisms without necessarily compromising universal invariants, since the redundant enforcement operates at a different architectural level than domain adaptation. - Depends on: domain-specialization-achieves-dual-excellence, architectural-invariants-are-scale-independent-and-redundantly-enforced ### domain-specialization-achieves-dual-excellence [IN] DERIVED The architecture achieves excellence through domain-adapted specialization rather than a single optimal pattern: symmetric domains optimize for quality (structurally correct lifecycle + triple convergence of correctness/simplicity/performance), while financial domains optimize for completeness (domain-adapted coordination strategies + emergent auditability from accumulative state). - Depends on: financial-domains-are-most-completely-realized, symmetric-domains-are-quality-optimal ### double-entry-invariant [IN] OBSERVATION Every money movement (initial funding, payment, refund) creates exactly two ledger entries — one debit and one credit — and `verify_ledger_integrity` audits that total debits equal total credits - Source: entries/2026/06/05/payment-system-payment_system.md ### duplicate-prevention-is-complete-from-api-to-storage [IN] DERIVED The architecture achieves complete duplicate prevention from external API boundary to internal storage through complementary forward-only mechanisms: idempotency keys extend forward-only semantics to the client boundary (making duplicate submissions return cached results permanently), while stratified dedup covers internal processing with accuracy adapted to cost (exact key-based at API boundaries, coordinated window-based at stream boundaries, probabilistic at crawl boundaries). - Depends on: idempotency-extends-forward-only-to-client-boundary, dedup-is-stratified-across-boundaries-and-accuracy-levels ### eager-rebuild-trades-write-cost-for-derived-consistency [IN] DERIVED Autocomplete and leaderboard both eagerly rebuild derived data structures on every mutation rather than deferring recomputation, guaranteeing that derived state (top-k caches, sorted rankings) is always consistent at the cost of write-path performance. - Depends on: autocomplete-cache-consistency, leaderboard-update-by-remove-reinsert ### email-service-bcc-stored-in-record [IN] OBSERVATION BCC recipients are stored in the email dict alongside to/cc, which would leak BCC information to other recipients in a real system. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### email-service-get-email-marks-read [IN] OBSERVATION `get_email` always side-effects a `mark_read`; there is no read-without-marking retrieval path. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### email-service-input-storage-decoupling [IN] OBSERVATION `Email` dataclass objects are the send-time input representation; stored emails are plain dicts created by `_store_email`, decoupling the send API from the query format. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### email-service-lazy-user-init [IN] OBSERVATION `_init_user()` is called at the start of most operations to bootstrap default folders, so accounts don't require explicit `create_account()` before use. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### email-service-single-folder-per-user [IN] OBSERVATION A message can only exist in one folder per user; `move_to_folder` removes from the source before adding to the target. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### email-service-thread-id-is-first-msg [IN] OBSERVATION Thread IDs are the message ID of the thread's first message, not a separately generated identifier. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### email-service-two-phase-delete [IN] OBSERVATION First `delete()` call moves to trash; second call on a trashed message permanently removes it. - Source: entries/2026/06/05/distributed-email-service-email_service.md ### error-boundaries-are-module-local [IN] DERIVED Error contracts are defined per-module with no cross-cutting convention — payment splits exceptions from return codes, the KV store raises generic exceptions, click aggregation uses boolean returns, and routing collapses all failures to None — making each module boundary an error translation boundary that callers must learn independently. - Depends on: error-signaling-lacks-codebase-convention, none-return-collapses-distinct-failure-modes ### error-signaling-lacks-codebase-convention [IN] DERIVED Error signaling varies by module with no cross-cutting convention: payment splits exceptions (programming errors) from return codes (business failures), KV uses generic Exception for quorum failures, click aggregator uses boolean returns for rejection, and wallet propagates all custom exceptions unconditionally — callers cannot implement a single error-handling strategy. - Depends on: payment-error-strategy-split, kv-store-quorum-exception, click-aggregator-return-value-signaling, wallet-no-exceptions-caught ### event-and-task-processing-share-forward-only-correctness [IN] DERIVED Event stream processing (exactly-once via coordinated dedup and finalization) and task graph processing (video pipeline forward progress via control-data separation and failure cascading) achieve their correctness guarantees through the same forward-only principle despite operating on fundamentally different processing models — both prevent regression and maximize useful work through irrevocable transitions. - Depends on: forward-only-stream-processing-is-exactly-once, control-data-separation-enables-forward-progress ### eviction-timing-has-no-codebase-convention [IN] DERIVED Data eviction timing varies across modules with no consistent strategy: message queue trims eagerly on every publish, rate limiter replaces its counter dict on each allowed request, URL shortener checks expiration lazily at read time, and the dedup registry prunes on watermark advance — each module independently decides when to reclaim old data, unlike other cross-cutting patterns (soft delete, time injection) where conventions exist. - Depends on: dmq-retention-trimmed-on-publish, fixed-window-single-key-gc, url-shortener-expiration-lazy, dedup-pruning-uses-2x-lateness ### fan-out-write-pushes-references-not-data [IN] DERIVED Both chat (inbox routing) and news feed (post ID distribution) push lightweight references at write time, deferring full data hydration to the read path — this shared pattern helps decouple write-time fanout cost from payload size in these two systems. - Depends on: chat-fanout-on-write, news-feed-fan-out-write-pushes-ids ### financial-auditability-is-emergent-from-accumulation [IN] DERIVED Payment ledger auditability is supported by the architecture's irreversible accumulation: because double-entry pairs are append-only and balances are derived from complete ledger scans, the full financial history is structurally difficult to lose — though the audit mechanism may have blind spots (such as the integrity verification function's exclusion of transfer transactions), meaning auditability largely follows from the state-growth property but may not guarantee complete traceability without additional verification. - Depends on: payment-ledger-is-fully-auditable, state-is-irreversibly-accumulative ### financial-concurrency-is-comprehensively-safe [IN] DERIVED Financial systems achieve comprehensive monetary safety when domain-appropriate concurrency strategies (pessimistic locking, optimistic version checks) and monotonic state ratchets (cursors that only advance, preconditions before removal) jointly prevent both concurrent corruption and state regression across all money-movement operations. - Depends on: concurrency-safety-strategy-varies-by-financial-risk, monotonicity-and-caution-prevent-state-loss - Unless: payment-balance-check-not-atomic ### financial-correctness-combines-locking-with-structural-asymmetry [IN] DERIVED Financial systems combine domain-appropriate concurrency control (pessimistic locking for wallets, optimistic locking for hotels) with write-read asymmetry (irrevocable ledger entries, reconciling balance derivation) to support end-to-end correctness: concurrency control prevents write-time corruption while structural asymmetry supports read-time consistency — provided the read path does not depend on assumed invariants that are never enforced in code, which would undermine the reconciliation that reads are supposed to perform. - Depends on: concurrency-safety-strategy-varies-by-financial-risk, write-read-asymmetry-is-end-to-end-correct ### financial-correctness-is-end-to-end [IN] DERIVED Financial domains achieve end-to-end correctness when domain-adapted coordination (pessimistic locking for wallets, optimistic control for hotels, combined with structural write-read asymmetry) combines with emergent auditability from irreversible accumulation — producing the architecture's only domains with simultaneous safety, lifecycle correctness, and full traceability. - Depends on: financial-correctness-combines-locking-with-structural-asymmetry, financial-auditability-is-emergent-from-accumulation - Unless: payment-balance-check-not-atomic ### financial-domains-are-most-completely-realized [IN] DERIVED Financial domains illustrate how multiple architectural properties converge to address safety, correctness, and accountability simultaneously: domain-adapted coordination strategies (explicit locking scaled to correctness cost) provide write-path safety, structural write-read asymmetry with forward-only guarantees supports lifecycle correctness, and irreversible accumulation yields emergent auditability — making these domains a notably complete instantiation of the architecture's multi-dimensional risk management. - Depends on: architecture-adapts-mechanisms-to-domain-risk, financial-auditability-is-emergent-from-accumulation ### fixed-window-single-key-gc [IN] OBSERVATION FixedWindowCounterLimiter replaces its entire counter dict with just the current window's entry on every allowed request, effectively garbage-collecting all old windows immediately - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### forward-only-and-monotonicity-are-a-single-constraint [IN] DERIVED Forward-only processing (no-regression ratchets, maximum-progress pipelines, irrevocable failure escalation) and monotonic ordering (ID generators that never produce out-of-order values, cursors that only advance) are manifestations of the same underlying constraint: the codebase only permits state to move in one direction, whether that direction is temporal (processing pipelines) or ordinal (sequencing and tracking). - Depends on: forward-only-design-prevents-regression-and-maximizes-progress, monotonicity-is-the-universal-ordering-primitive ### forward-only-and-monotonicity-jointly-bound-read-path-risk [IN] DERIVED Forward-only design and unconditional state monotonicity jointly bound read-path risk through complementary mechanisms: forward-only prevents temporal regression from creating new convergence obligations, while monotonic growth ensures the read path's active convergence always targets a larger consistent state — together limiting the unbounded verification burden that would otherwise grow with system complexity. - Depends on: forward-only-compensates-for-read-path-verification-gap, state-growth-is-unconditionally-monotonic ### forward-only-compensates-for-read-path-verification-gap [IN] DERIVED Forward-only design specifically compensates for the architecture's most critical verification gap: the read path bears growing responsibility that outpaces test coverage, but forward-only semantics prevent unverified read-path behaviors from causing regression — temporal gaps in the least-tested component cannot propagate backward. - Depends on: forward-only-preserves-correctness-despite-accepted-gaps, read-path-responsibility-exceeds-verification ### forward-only-design-prevents-regression-and-maximizes-progress [IN] DERIVED The codebase's forward-only philosophy combines no-regression state ratchets (monotonic cursors, irreversible window finalization) with failure-tolerant pipelines that continue independent branches on failure, ensuring useful progress is never lost and partial failure never triggers backtracking. - Depends on: state-ratchets-prevent-regression-across-domains, pipeline-processing-maximizes-forward-progress ### forward-only-enables-robust-cost-allocation [IN] DERIVED Cost shifting between write and read paths is robust against two independent failure modes: forward-only semantics ensure shifted computation never needs rollback (temporal robustness), and structural construction guarantees the shifted state remains consistent (spatial robustness) — together they make the write-read cost balance arbitrarily adjustable without correctness risk. - Depends on: forward-only-preserves-correctness-despite-accepted-gaps, structural-correctness-enables-safe-cost-shifting ### forward-only-extends-to-failure-handling [IN] DERIVED The forward-only design principle extends beyond normal state evolution (monotonic cursors, irreversible window finalization, maximum-progress pipeline branching) to failure handling: retry logic escalates transient failures to permanent outcomes via exponential backoff rather than attempting rollback, treating failure resolution as another forward-only state transition that produces irrevocable results. - Depends on: forward-only-design-prevents-regression-and-maximizes-progress, retry-escalates-to-permanent-failure ### forward-only-extends-to-time-generation [IN] DERIVED Forward-only design extends from state ratchets (monotonic cursors, irreversible finalization) to the time dimension of ID generation: Snowflake rejects backward clocks rather than generating out-of-order IDs, applying the same no-regression principle at the time-generation layer that state ratchets enforce at the data layer. - Depends on: state-ratchets-prevent-regression-across-domains, snowflake-rejects-backward-clock ### forward-only-is-the-architectures-load-bearing-constraint [IN] DERIVED Forward-only design is both the architecture's most universally applied pattern (spanning event streams, task pipelines, and notification delivery as a single processing primitive) and its primary correctness mechanism (containing temporal gaps, preventing regression, enabling safe cost shifting despite accepted weaknesses) — making it the single most load-bearing architectural constraint across all 25 modules. - Depends on: forward-only-is-universal-processing-primitive, forward-only-preserves-correctness-despite-accepted-gaps ### forward-only-is-universal-processing-primitive [IN] DERIVED Forward-only correctness is the codebase's universal processing primitive, applying uniformly across all three processing paradigms: event streams (exactly-once via coordinated dedup and finalization), task orchestration (DAG forward progress via control-data separation), and message delivery (bounded retry with escalation to permanent failure). - Depends on: event-and-task-processing-share-forward-only-correctness, notification-instantiates-forward-only-delivery ### forward-only-is-universally-load-bearing-across-all-layers [IN] DERIVED Forward-only design is simultaneously the most broadly applied pattern (independently enforcing no-regression at data, domain, and execution layers) and the single most critical constraint (the load-bearing principle whose removal would compromise correctness across all processing paradigms) — its universality and criticality are the same property viewed from coverage and dependency perspectives. - Depends on: forward-only-spans-data-domain-and-execution-layers, forward-only-is-the-architectures-load-bearing-constraint ### forward-only-preserves-correctness-despite-accepted-gaps [IN] DERIVED The architecture achieves end-to-end correctness not by eliminating temporal gaps but by containing them within a forward-only framework: forward-only design prevents gap-induced regression (non-atomic checks cannot cause backward state transitions) while write-read asymmetry ensures irrevocable writes and reconciling reads remain correct despite accepted temporal weaknesses. - Depends on: temporal-gaps-are-contained-by-forward-only-design, write-read-asymmetry-is-end-to-end-correct ### forward-only-spans-data-domain-and-execution-layers [IN] DERIVED Forward-only design enforces no-regression guarantees independently at three architectural layers: domain-level state machines contain temporal gaps through irrevocable transitions, execution-level stream processing achieves exactly-once through coordinated dedup and finalization, and execution-level task pipelines maximize forward progress through control-data separation — the no-regression principle is layered across the architecture, not singular. - Depends on: state-machines-enforce-temporal-gap-containment, forward-only-stream-processing-is-exactly-once, control-data-separation-enables-forward-progress ### forward-only-stream-processing-is-exactly-once [IN] DERIVED Stream processing achieves exactly-once delivery per entity: dedup outlives finalization windows, finalized results are irrevocable, and the pipeline never backtracks — producing correct per-event semantics when event IDs are globally unique. - Depends on: dedup-and-finalization-are-coordinated, forward-only-design-prevents-regression-and-maximizes-progress - Unless: dedup-is-global-not-per-ad ### forward-only-unifies-processing-and-conflict-resolution [IN] DERIVED Forward-only semantics provide a single consistency guarantee across two independent architectural concerns: processing paradigms (event streams, task pipelines, notification delivery all use irrevocable forward progress) and conflict resolution at all distribution levels (single-node optimistic retry, multi-node sibling retention, cross-replica anti-entropy all resolve by moving forward rather than rolling back) — making forward-only the architecture's universal consistency primitive. - Depends on: forward-only-is-universal-processing-primitive, conflict-resolution-is-forward-only-at-all-distribution-levels ### gdrive-owner-bypasses-permission [IN] OBSERVATION `_check_permission` returns immediately if `meta.owner_id == user_id`, bypassing the full permission inheritance walk. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### gdrive-permission-inheritance [IN] OBSERVATION Permission checks walk up the folder tree via `parent_folder_id` pointers; access granted on any ancestor grants access to all descendants. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### gdrive-quota-reservation [IN] OBSERVATION Chunked uploads reserve full quota at init time and release-then-reaccount at completion, preventing over-commitment from multiple concurrent uploads. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### gdrive-restore-creates-new-version [IN] OBSERVATION `restore_version` delegates to `update_file`, so restoring to an old version creates a new version entry rather than rolling back the version counter — preserving the audit trail. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### gdrive-soft-delete-cascade [IN] OBSERVATION Deleting a folder soft-deletes all descendants via BFS traversal; permanent deletion only occurs in `empty_trash` after a time-based cutoff. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### gdrive-version-list-bounded [IN] OBSERVATION `update_file` prunes the version history to `max_versions` (default 100), keeping only the most recent entries. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### gdrive-version-vector-conflict [IN] OBSERVATION Conflict detection uses per-device version vectors, not simple version counters; a conflict requires a *different* device to have written a version the requesting device hasn't seen. - Source: entries/2026/06/05/design-google-drive-design_google_drive.md ### geohash-encode-longitude-first [IN] OBSERVATION GeohashIndex.encode interleaves bits starting with longitude, matching the standard geohash specification; swapping the order would break neighbor computation and cross-index compatibility - Source: entries/2026/06/05/proximity-service-proximity_service.md ### geohash-nearby-prefix-scan-is-linear [IN] OBSERVATION GeohashIndex.nearby iterates all keys in `_index` to match prefixes, making it O(buckets) per query rather than O(1) — a deliberate simplification vs. a sorted/trie structure - Source: entries/2026/06/05/proximity-service-proximity_service.md ### google-drive-restore-is-append-only [IN] OBSERVATION `restore_version` in Google Drive doesn't roll back — it calls `update_file` with old content, creating a new version and preserving append-only history. - Source: entries/2026/06/05/topic-consistency-models.md ### growing-read-complexity-outpaces-test-coverage [IN] DERIVED As distribution complexity increases, the read path absorbs more correctness burden (deferred consistency, lazy computation, active repair), but the co-designed test infrastructure validates structural rather than temporal properties — the expanding read-path risk surface grows into exactly the domain that deterministic structural tests cannot cover. - Depends on: read-cost-scales-with-system-complexity, structural-correctness-and-testability-are-co-designed ### heap-sign-negation-repurposes-min-heap [IN] DERIVED Both leaderboard (negated scores in SortedList) and URL frontier (sign-flipped sequence numbers in heapq) repurpose ascending-order data structures for alternative orderings by negating sort keys, rather than using custom comparators or different data structures. - Depends on: leaderboard-negated-score-ordering, url-frontier-strategy-via-sequence-sign ### hll-default-precision [IN] OBSERVATION `HyperLogLogCounter` defaults to precision 14 (16384 registers), matching the standard HLL recommendation for ~1% error rate. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### hotel-checkout-exclusive [IN] OBSERVATION Date ranges are half-open `[check_in, check_out)`: a booking from March 15 to March 16 occupies inventory on March 15 only. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### hotel-idempotency-ignores-params [IN] OBSERVATION The idempotency key check returns the cached reservation without validating that guest name, dates, or room type match the original request. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### hotel-occ-prevents-overbooking [IN] DERIVED Hotel reservations prevent overbooking through optimistic concurrency control with per-date version counters, rejecting concurrent conflicting bookings via version mismatch — unless a double-cancel bypasses the underflow guard and drives inventory counts negative, making the system believe more rooms are available than exist. - Depends on: hotel-reservation-optimistic-locking, hotel-search-availability-is-bottleneck-date - Unless: hotel-cancel-no-underflow-guard ### hotel-occ-two-phase-reserve [IN] OBSERVATION `reserve()` implements optimistic concurrency via a read-then-verify-version pattern, but both phases execute synchronously with no actual interleaving, making the version check demonstrative rather than functional. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### hotel-pricing-is-deterministic [IN] DERIVED Hotel dynamic pricing deterministically stacks occupancy and seasonal multipliers on the base price — but when seasonal pricing ranges overlap, the first-match rule makes the price depend on rule insertion order rather than a stable priority scheme. - Depends on: hotel-pricing-stacks-multipliers - Unless: hotel-seasonal-pricing-first-match ### hotel-pricing-stacks-multipliers [IN] OBSERVATION Dynamic occupancy pricing and seasonal pricing multiply independently on the base price; a 90% occupied room during peak season costs `base * seasonal_mult * 1.5`. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### hotel-reservation-optimistic-locking [IN] OBSERVATION Hotel reservation uses optimistic concurrency control with per-date version counters; version mismatch between read and write raises `ConcurrencyError`. - Source: entries/2026/06/05/topic-consistency-models.md ### hotel-search-availability-is-bottleneck-date [IN] OBSERVATION `search()` reports availability as the minimum available rooms across all nights in the requested range; the most-booked date determines what's bookable. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### hybrid-fanout-bounds-both-write-and-read-cost [IN] DERIVED The hybrid fan-out strategy bounds both paths: the follower-count threshold limits write amplification to non-celebrity authors, and heap-merge limits read cost to O(k log n) for pull-based celebrity retrieval. - Depends on: news-feed-hybrid-splits-on-follower-count, news-feed-pull-uses-heap-merge ### hybrid-fanout-instantiates-adaptive-cost-model [IN] DERIVED The hybrid fan-out strategy is the codebase's most explicit instantiation of access-frequency-adapted cost allocation: the celebrity threshold converts the abstract principle (shift work to the cheaper path based on access pattern) into a concrete runtime decision boundary, dynamically partitioning authors between write-amplified push and read-time merge-pull to bound both paths simultaneously. - Depends on: hybrid-fanout-bounds-both-write-and-read-cost, cost-model-adapts-to-access-frequency ### id-generators-preserve-monotonic-order [IN] DERIVED Stateful ID generators maintain monotonic ordering within their time granularity through distinct sub-millisecond strategies: Snowflake uses a bounded sequence counter (4096/ms), ULID increments the random component, and the stock exchange uses a global counter — all thread-safe via locks to prevent ID collision under concurrency. - Depends on: snowflake-sequence-max-4096-per-ms, ulid-monotonic-within-millisecond, stock-exchange-trade-counter-global, all-stateful-generators-thread-safe ### idempotency-extends-forward-only-to-client-boundary [IN] DERIVED Idempotency keys extend forward-only semantics to the external API boundary: once a client-provided key maps to a result, that result is permanent and irrevocable — the same pattern that internal state ratchets apply to stream windows and read cursors, but applied to client-facing retry safety across hotel reservations, payments, and ad click processing. - Depends on: idempotency-keys-ignore-payload-content, forward-only-extends-to-failure-handling ### idempotency-keys-ignore-payload-content [IN] DERIVED Three systems implement idempotency by keying on opaque identifiers (idempotency key, event ID) without verifying that the associated payload matches the original request, silently returning cached results even when parameters differ. - Depends on: hotel-idempotency-ignores-params, payment-idempotency-is-key-based, ad-click-dedup-global-not-per-ad ### identity-derivation-trades-validation-for-simplicity [IN] DERIVED Both deterministic identity derivation (DM conversations from sorted user pairs, threads from first message ID) and idempotency enforcement (key-only matching ignoring payload) share a pattern of deriving operation identity from minimal existing data without examining payloads. This approach eliminates coordination overhead for identity creation, but in the idempotency case introduces silent-mismatch risk when distinct operations share a key. - Depends on: deterministic-ids-eliminate-coordination, idempotency-keys-ignore-payload-content ### immutable-values-prevent-aliasing-bugs [IN] DERIVED KV vector clocks return new instances on every operation and leaderboard updates by remove-then-reinsert rather than mutating in place; both approaches avoid aliasing bugs where shared mutable references could cause unintended state corruption. - Depends on: kv-vector-clock-immutable, leaderboard-update-by-remove-reinsert ### information-preservation-is-doubly-guaranteed [IN] DERIVED Information is never lost through either normal operations or conflict resolution: unconditional state monotonicity ensures even deletion and eviction add metadata rather than removing data, and forward-only conflict resolution at all distribution levels ensures conflicts produce additional state (siblings, new versions, repair writes) rather than overwriting or discarding existing information. - Depends on: state-growth-is-unconditionally-monotonic, conflict-resolution-is-forward-only-at-all-distribution-levels ### input-and-storage-representations-are-decoupled [IN] DERIVED The architecture separates input representations from storage representations: email uses `Email` dataclass for send-time input but stores plain dicts, and KV separates coordinator writes (`local_put` with clock increment) from replication writes (`local_put_raw` with pre-built versions) — enabling internal storage evolution independent of external API. - Depends on: email-service-input-storage-decoupling, kv-local-put-vs-raw-separation ### kv-150-vnodes-per-node [IN] OBSERVATION Consistent hash ring uses 150 virtual nodes per physical node; `_get_preference_list` deduplicates by physical node ID when walking the ring - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-anti-entropy-covers-writes-and-deletes [IN] DERIVED The KV store's anti-entropy strategy is complete across both operation types: read repair converges divergent write versions via sibling detection, and tombstones prevent delete operations from causing data resurrection from lagging replicas. - Depends on: kv-read-path-is-self-healing, soft-delete-prevents-distributed-resurrection ### kv-delete-is-tombstone-write [IN] OBSERVATION Deletes are implemented as a `put` of a `VersionedValue` with `is_tombstone=True` and `value=None`; no data is physically removed - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-hinted-handoff-not-counted-in-quorum [IN] OBSERVATION Hinted handoff writes to backup nodes are fire-and-forget and do not count toward the W quorum acknowledgment count - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-local-put-vs-raw-separation [IN] OBSERVATION `local_put` increments the vector clock (for coordinator-originated writes); `local_put_raw` accepts pre-built `VersionedValue` without advancing causality (for replication, read-repair, anti-entropy) - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-merkle-tree-brute-force-diff [IN] OBSERVATION `MerkleTree.find_differences` checks root hashes for fast equality but falls back to key-by-key comparison on mismatch, not O(log n) tree walking - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-node-stores-sibling-versions [IN] OBSERVATION `KVNode.store` maps each key to a list of `VersionedValue`; concurrent writes produce multiple siblings that the client must resolve - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-read-path-is-self-healing [IN] DERIVED Every KV get is self-healing: sibling versions detect replica divergence and read repair pushes non-dominated versions back to stale replicas as a side effect, converging the cluster toward consistency on every read. - Depends on: kv-read-repair-on-get, kv-node-stores-sibling-versions ### kv-read-repair-on-get [IN] OBSERVATION Every `get` performs read repair — pushing non-dominated, non-tombstone versions back to stale replicas as a side effect of the read path - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-reads-eventually-converge [IN] DERIVED KV reads drive eventual consistency through read repair and sibling version detection — every get actively heals divergence — but this guarantee holds only if W+R>N quorum overlap is actually maintained. - Depends on: kv-read-repair-on-get, kv-node-stores-sibling-versions - Unless: kv-store-quorum-overlap-not-enforced ### kv-store-deletes-use-tombstones [IN] OBSERVATION KV store uses tombstones for deletes because a naive physical delete would be resurrected by anti-entropy from a replica that hasn't seen the deletion. - Source: entries/2026/06/05/topic-consistency-models.md ### kv-store-quorum-exception [IN] OBSERVATION `put`, `get`, and `delete` raise generic `Exception` (not a custom type) when the quorum threshold (W or R) is not met - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-vector-clock-immutable [IN] OBSERVATION `VectorClock` operations (`increment`, `merge`, `prune`) return new instances rather than mutating in place, avoiding aliasing bugs across replicas - Source: entries/2026/06/05/key-value-store-key_value_store.md ### kv-write-path-separates-coordinator-from-replication [IN] DERIVED The KV write path separates coordinator responsibility (local_put increments vector clocks, wraps deletes as tombstones) from replication (local_put_raw accepts pre-built VersionedValues), enabling read repair and anti-entropy to use the raw path without re-incrementing clocks. - Depends on: kv-local-put-vs-raw-separation, kv-delete-is-tombstone-write ### lazy-read-time-evaluation-trades-write-simplicity-for-read-cost [IN] DERIVED Autocomplete (time decay), URL shortener (expiration), and payment (balance derivation) all defer computation to the read path, keeping writes simple and append-only at the cost of read-time complexity and latency. - Depends on: autocomplete-decay-is-read-time, url-shortener-expiration-lazy, payment-balance-never-cached ### leaderboard-dual-index-consistency [IN] OBSERVATION Every mutation in `Leaderboard` must update both `_entries` (SortedList) and `_players` (dict) atomically; a desync between them is a correctness bug that surfaces as `ValueError` on the next operation - Source: entries/2026/06/05/realtime-gaming-leaderboard-leaderboard.md ### leaderboard-negated-score-ordering [IN] OBSERVATION Scores are stored negated in `_entries` so that `SortedList`'s ascending order yields descending-score ranking; the tiebreaker is timestamp-ascending (earlier timestamp = higher rank) - Source: entries/2026/06/05/realtime-gaming-leaderboard-leaderboard.md ### leaderboard-range-query-is-O-m-log-n [IN] OBSERVATION `range_by_score` calls `_entries.index(entry)` per matched result to compute rank, making it O(m log n) rather than the O(m + log n) achievable by tracking the start index and incrementing - Source: entries/2026/06/05/realtime-gaming-leaderboard-leaderboard.md ### leaderboard-rank-is-one-based [IN] OBSERVATION All public-facing rank values are 1-based; internal `SortedList.index()` returns 0-based and every call site adds 1 - Source: entries/2026/06/05/realtime-gaming-leaderboard-leaderboard.md ### leaderboard-sortedcontainers-dependency [IN] OBSERVATION `sortedcontainers.SortedList` is the sole external dependency and the load-bearing data structure; it provides O(log n) add/remove/index that makes the entire leaderboard design viable - Source: entries/2026/06/05/realtime-gaming-leaderboard-leaderboard.md ### leaderboard-update-by-remove-reinsert [IN] OBSERVATION `update_score` removes the old entry from the sorted list and inserts a new one rather than mutating in place, which is the correct approach since in-place mutation would violate sort order - Source: entries/2026/06/05/realtime-gaming-leaderboard-leaderboard.md ### ledger-interpretation-is-consistently-safe [IN] DERIVED The financial ledger's dual interpretation (full balance from complete scan, spending limits from outflows only) provides both audit completeness and focused business metrics from a single data source — unless the non-atomic balance check allows concurrent mutations between balance reads and spending limit enforcement, enabling over-spending that neither interpretation would detect in isolation. - Depends on: payment-ledger-is-fully-auditable, daily-limit-only-counts-outflows - Unless: payment-balance-check-not-atomic ### ledger-supports-asymmetric-read-interpretation [IN] DERIVED The financial ledger supports multiple asymmetric interpretations from a single data source: full-scan balance derivation counts all transactions, while daily spending limits count only outflows (withdrawals, transfers out) — the ledger is the sole source of truth but different read paths apply different projection filters. - Depends on: balance-derived-from-ledger, daily-limit-only-counts-outflows ### logical-abstraction-decouples-semantics-from-storage [IN] DERIVED Both message queues and distributed deletion model operations as logical abstractions decoupled from physical storage: offsets survive partition trimming, tombstones survive replication, and dead-letter queues are just regular topics — the semantic layer insulates consumers from storage implementation changes and physical state evolution. - Depends on: queue-abstraction-is-logical-not-physical, deletion-is-metadata-in-replicated-systems ### logical-physical-separation-spans-topology-storage-and-deletion [IN] DERIVED The architecture systematically separates logical semantics from physical state across three independent dimensions: topology (consistent hashing decouples ring positions from data placement, making node operations stateless), storage (message queue offsets survive partition trimming via base offset adjustment), and deletion (tombstones and delete markers decouple the logical fact of deletion from physical data removal), making logical-physical independence a cross-cutting architectural principle rather than a per-system choice. - Depends on: consistent-hashing-is-a-stateless-topology-abstraction, logical-abstraction-decouples-semantics-from-storage ### maps-astar-heuristic-admissible [IN] OBSERVATION The A* heuristic is admissible: distance mode uses haversine (always ≤ road distance), time mode divides haversine by the global maximum speed limit (always ≤ actual travel time). - Source: entries/2026/06/05/google-maps-map_routing.md ### maps-bidirectional-edges-share-data [IN] OBSERVATION Non-one-way edges are added in both directions sharing the same dict object, meaning both directions always have identical distance and speed limit values. - Source: entries/2026/06/05/google-maps-map_routing.md ### maps-dual-mode-astar-dijkstra [IN] OBSERVATION `_find_path` implements both A* and Dijkstra via a single code path; setting `algorithm != "astar"` zeroes the heuristic, collapsing A* to Dijkstra. - Source: entries/2026/06/05/google-maps-map_routing.md ### maps-no-exceptions-none-returns [IN] OBSERVATION `map_routing.py` raises no exceptions; all failures (missing nodes, unreachable destinations, unknown geocode names) return `None` or empty collections. - Source: entries/2026/06/05/google-maps-map_routing.md ### maps-time-heuristic-uses-global-max-speed [IN] OBSERVATION The time-optimized A* heuristic divides haversine distance by the global maximum speed limit, which is admissible but can be a weak heuristic on heterogeneous-speed networks. - Source: entries/2026/06/05/google-maps-map_routing.md ### maps-yen-k-shortest-for-alternatives [IN] OBSERVATION `alternative_routes` implements Yen's K-shortest paths algorithm, blocking edges from prior paths at each spur node; it always optimizes for distance (hardcoded). - Source: entries/2026/06/05/google-maps-map_routing.md ### memory-is-bounded-at-the-cost-of-silent-information-loss [IN] DERIVED The codebase systematically accepts information loss for bounded resource consumption through two complementary mechanisms: deterministic truncation (fixed-capacity deques and version lists silently dropping oldest entries) and probabilistic approximation (HyperLogLog, Morris counters, SimHash trading exact answers for space-efficient estimates), establishing a consistent architectural preference where memory guarantees take precedence over data completeness or computational accuracy. - Depends on: bounded-collections-trade-completeness-for-memory, probabilistic-structures-trade-accuracy-for-space ### message-delivery-guarantees-are-consumer-side [IN] DERIVED Message queue delivery guarantees (at-least-once, at-most-once, exactly-once) are enforced entirely at the consumer layer through poll/commit semantics and the two-tier offset mechanism (current vs committed), making the broker stateless with respect to delivery semantics and pushing guarantee selection to the consumer. - Depends on: dmq-delivery-semantics-in-poll, dmq-two-tier-offset-tracking ### message-queue-two-tier-offsets [IN] OBSERVATION The message queue separates `current_offset` (advances on every `poll()`) from `committed_offset` (advances on explicit `commit()`), enabling consumer-chosen delivery semantics. - Source: entries/2026/06/05/topic-consistency-models.md ### metrics-alert-state-machine-four-states [IN] OBSERVATION Alert evaluation follows a four-state machine (OK → PENDING → ALERTING → RESOLVED) where PENDING requires `duration_seconds` to elapse before transitioning to ALERTING; PENDING resets to OK (not RESOLVED) if the condition clears early - Source: entries/2026/06/05/metrics-monitoring-and-alerting-metrics.md ### metrics-condition-uses-window-average [IN] OBSERVATION Threshold alert conditions (`gt`, `lt`, `gte`, `lte`) compare against the average of all points in the lookback window (sized `max(duration_seconds, 60)`), not the most recent value - Source: entries/2026/06/05/metrics-monitoring-and-alerting-metrics.md ### metrics-downsample-two-tier [IN] OBSERVATION Downsampling uses two age-based tiers: 1–7 days old → 5-minute buckets, >7 days old → 1-hour buckets, both using averaging which loses min/max/percentile fidelity - Source: entries/2026/06/05/metrics-monitoring-and-alerting-metrics.md ### metrics-indexing-separates-write-key-from-read-matching [IN] DERIVED Metrics separates write-path identity (frozen tag sets as immutable hash-safe keys) from read-path flexibility (subset matching enables partial-tag queries without key enumeration). - Depends on: metrics-series-keyed-by-frozen-tags, metrics-tag-matching-is-subset ### metrics-instantiates-write-read-cost-pattern [IN] DERIVED Metrics is a concrete instantiation of the codebase's per-use-case write-read cost allocation: frozen tag sets and sorted insertion keep the write path structurally simple (O(log n) per point), while subset matching and multi-tier downsampling absorb read-path flexibility and cost — the module explicitly allocates complexity to reads for query expressiveness. - Depends on: metrics-indexing-separates-write-key-from-read-matching, metrics-sorted-invariant-survives-downsampling, write-read-cost-allocation-is-per-use-case ### metrics-is-complete-write-read-exemplar [IN] DERIVED Metrics combines both structural write-read separation (frozen tags for write identity, subset matching for read flexibility) and per-use-case cost optimization (eager sorted insertion on writes, deferred matching on reads) within a single module — suggesting that structural and economic separation can be two facets of the same design. - Depends on: metrics-instantiates-write-read-cost-pattern, metrics-write-read-separation-is-structurally-complete ### metrics-series-keyed-by-frozen-tags [IN] OBSERVATION Series are stored keyed by `(metric_name, frozenset(tags.items()))`, so each unique tag combination creates a distinct time series — the standard cardinality model - Source: entries/2026/06/05/metrics-monitoring-and-alerting-metrics.md ### metrics-series-sorted-invariant [IN] OBSERVATION Every time series in `_data` is maintained in sorted timestamp order; `ingest` (bisect insertion), `downsample` (re-sort), and `apply_retention` (bisect truncation) all preserve this invariant - Source: entries/2026/06/05/metrics-monitoring-and-alerting-metrics.md ### metrics-sorted-invariant-survives-downsampling [IN] DERIVED Metrics maintains its sorted timestamp invariant through both ingestion (bisect insertion for O(log n) per-point insert) and two-tier downsampling (re-sort after age-based aggregation), ensuring temporal queries are correct across all retention tiers. - Depends on: metrics-series-sorted-invariant, metrics-downsample-two-tier ### metrics-tag-matching-is-subset [IN] OBSERVATION `_matching_keys` performs subset matching: a query with `tags_filter={"a": 1}` matches any series whose tags include `a=1`, regardless of additional tags present - Source: entries/2026/06/05/metrics-monitoring-and-alerting-metrics.md ### metrics-write-read-separation-is-structurally-complete [IN] DERIVED Metrics achieves complete write-read structural separation: the write path uses frozen tag sets as immutable hash-safe keys with bisect insertion maintaining sorted temporal order, while the read path provides flexible subset matching for partial-tag queries and two-tier downsampling for bounded historical access — neither path compromises the other's invariants. - Depends on: metrics-indexing-separates-write-key-from-read-matching, metrics-sorted-invariant-survives-downsampling ### module-boundary-is-universal-containment-mechanism [IN] DERIVED The module boundary serves as the architecture's universal containment mechanism across two independent concerns: quality properties (each module's simplicity-to-verification cycle is hermetically self-contained with no cross-module dependencies) and pragmatic tradeoffs (brute-force algorithms, bounded collections, and simplified implementations are safely confined by module isolation) — ensuring that per-module design choices neither constrain nor compromise other modules. - Depends on: verified-simplicity-is-hermetically-contained, pedagogical-breadth-is-safely-contained ### module-isolation-is-pedagogical-and-architectural [IN] DERIVED Module isolation exhibits two complementary properties: each module is a hermetic, standalone unit with only stdlib dependencies and no real I/O (supporting independent testability), while operational conventions — error signaling strategies, eviction timing, failure reporting — remain module-scoped rather than codebase-wide (producing locally reasonable but collectively unpredictable operational surfaces). These properties appear to reinforce each other: standalone modules with no shared infrastructure naturally avoid convention coupling across module boundaries. - Depends on: operational-conventions-are-module-scoped, deterministic-testability-by-design ### module-level-triple-convergence [IN] DERIVED Each module independently achieves the convergence of correctness, simplicity, and performance: module isolation ensures these properties are self-contained rather than emerging only at codebase scale, and structural correctness being universally applied means the convergence holds per-module, not just in aggregate. - Depends on: modules-are-independently-correct, correctness-simplicity-and-performance-converge ### modules-are-independently-correct [IN] DERIVED Module isolation and structural correctness support independent reasoning about each module's behavior: hermetic, standalone modules with no shared infrastructure avoid convention coupling across boundaries, while structural construction techniques (immutability, state ratchets) enforce many correctness properties within each module. However, this per-module correctness reasoning has limits — structural discipline is not universally applied, leaving critical invariants assumed but unenforced, and operational conventions that are locally reasonable may produce collectively unpredictable behavior across modules. - Depends on: module-isolation-is-pedagogical-and-architectural, structural-correctness-is-universally-applied - Unless: dmq-reused-by-stock-exchange ### modules-are-independently-runnable [IN] DERIVED Each SDI module is independently runnable with only stdlib dependencies, in-process simulation, and no shared code — unless the stock exchange's cross-module import of the message queue is considered, which introduces a runtime dependency that breaks strict module independence. - Depends on: sdi-modules-are-standalone-learning-artifacts - Unless: dmq-reused-by-stock-exchange ### monotonic-state-is-bounded-by-fidelity-not-reversal [IN] DERIVED The architecture resolves the tension between unconditionally growing state (forward-only, append-only) and finite physical resources through fidelity reduction rather than state reversal: bounded collections truncate old entries and probabilistic structures approximate counts, but no mechanism reverses or rolls back accumulated state — old data is forgotten, never undone. - Depends on: state-growth-is-unconditionally-monotonic, resource-bounding-uses-dual-fidelity-strategies ### monotonicity-and-caution-prevent-state-loss [IN] DERIVED Monotonic state ratchets (cursors only advance, windows never reopen) and cautious deletion (preconditions before permanent removal, two-phase trash workflows) together ensure that committed state can never be silently lost or regressed — unless wallet creation silently overwrites existing state, demonstrating that creation operations bypass both guards because the codebase protects against destructive deletion and regression but not destructive creation. - Depends on: state-ratchets-prevent-regression-across-domains, deletion-is-guarded-by-preconditions - Unless: wallet-creation-silently-overwrites ### monotonicity-is-the-universal-ordering-primitive [IN] DERIVED Monotonic progression is a primary mechanism in the codebase for establishing order and preventing regression: ID generators maintain monotonic ordering within their time granularity through distinct sub-millisecond strategies, while read cursors and window lifecycles use one-directional state progressions to prevent consumption regression and enforce irreversible finalization — all encoding progress as a non-decreasing value. - Depends on: id-generators-preserve-monotonic-order, state-ratchets-prevent-regression-across-domains ### morris-counter-32-estimators [IN] OBSERVATION `MorrisCounter` uses 32 independent counters averaged together for improved accuracy — each incremented probabilistically with probability `1/2^c`. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### multi-structure-sync-invariant [IN] DERIVED Both consistent hashing and leaderboard implementations maintain parallel data structures (three in consistent hashing, two in leaderboard) that must stay synchronized on every mutation. In consistent hashing, all three structures must stay consistent on every add/remove; in leaderboard, a desync between the sorted list and dict is a correctness bug that surfaces as a ValueError on the next operation. - Depends on: ch-triple-bookkeeping, leaderboard-dual-index-consistency ### multiple-algorithms-behind-unified-interface [IN] DERIVED Multiple systems offer interchangeable algorithm variants through a single interface — routing toggles A*/Dijkstra via a heuristic flag, URL shortening selects counter/hash strategy, and rate limiting provides four algorithm implementations — enabling strategy changes without API changes. - Depends on: maps-dual-mode-astar-dijkstra, rate-limiter-four-algorithms, url-shortener-two-strategies ### multiple-algorithms-serve-pedagogical-breadth [IN] DERIVED Offering interchangeable algorithm variants through unified interfaces (A*/Dijkstra routing, four rate limiter algorithms, two URL shortening strategies) serves the pedagogical goal of demonstrating multiple approaches to the same problem within self-contained learning artifacts, maximizing educational coverage per module rather than production flexibility. - Depends on: multiple-algorithms-behind-unified-interface, sdi-modules-are-standalone-learning-artifacts ### nearby-friends-bidirectional-visibility [IN] OBSERVATION For user A to see friend B as nearby, both A and B must have location sharing enabled and fresh locations; checked on both update and query paths - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### nearby-friends-friendship-always-symmetric [IN] OBSERVATION `add_friendship` and `remove_friendship` always update both directions; there is no one-way follow relationship - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### nearby-friends-grid-cell-size-tied-to-threshold [IN] OBSERVATION Grid cell size is `distance_threshold_km / 111.0` degrees (111 km ≈ 1° latitude), meaning changing the distance threshold automatically rescales the spatial index - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### nearby-friends-grid-is-thread-safe [IN] OBSERVATION Location storage, grid index updates, and candidate snapshots in update_location and get_nearby_friends are protected by threading.Lock, preventing concurrent corruption of the spatial index. - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### nearby-friends-history-bounded-100 [IN] OBSERVATION Per-user location history uses `deque(maxlen=100)`, silently dropping oldest entries to prevent unbounded memory growth - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### nearby-friends-staleness-enforced-on-both-paths [IN] OBSERVATION Both notification (`update_location`) and query (`get_nearby_friends`) paths reject friend locations older than `location_ttl_seconds` - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### news-feed-cache-is-bounded-deque [IN] OBSERVATION Feed caches use `deque(maxlen=cache_size)` which silently drops the oldest post IDs when full, providing implicit eviction without explicit cache management - Source: entries/2026/06/05/news-feed-system-news_feed.md ### news-feed-cache-is-rebuildable [IN] OBSERVATION rebuild_cache reconstructs the feed cache from the social graph and post store, providing a repair path when cache state is lost — skipping celebrity posts in hybrid mode to match the write-time fan-out policy. - Source: entries/2026/06/05/news-feed-system-news_feed.md ### news-feed-cache-silently-drops-oldest [IN] OBSERVATION News feed caches use `deque(maxlen=cache_size)` which silently drops the oldest post IDs when full — no error or notification on eviction. - Source: entries/2026/06/05/topic-consistency-models.md ### news-feed-celebrity-threshold-at-write-time [IN] OBSERVATION Fan-out strategy selection via `celebrity_threshold` is evaluated at write time and not retroactively applied to existing posts. - Source: entries/2026/06/05/topic-consistency-models.md ### news-feed-fan-out-write-pushes-ids [IN] OBSERVATION Fan-out-on-write pushes post IDs (not full post objects) into followers' deques at write time, deferring hydration to read time so engagement metrics are always current - Source: entries/2026/06/05/news-feed-system-news_feed.md ### news-feed-hybrid-splits-on-follower-count [IN] OBSERVATION Hybrid strategy uses `celebrity_threshold` (default 1000) to decide push vs. pull per-author; the threshold is evaluated at write time and not retroactively applied to already-cached posts - Source: entries/2026/06/05/news-feed-system-news_feed.md ### news-feed-only-exception-is-missing-post-comment [IN] OBSERVATION The only raised exception in the module is `ValueError` from `PostStore.add_comment` when the target post doesn't exist; all other error cases return sentinel values or silently skip - Source: entries/2026/06/05/news-feed-system-news_feed.md ### news-feed-pull-uses-heap-merge [IN] OBSERVATION Fan-out-on-read merges all followed users' timelines via `heapq.merge` with negated timestamps, avoiding full materialization of all posts - Source: entries/2026/06/05/news-feed-system-news_feed.md ### news-feed-unfollow-purges-via-linear-scan [IN] OBSERVATION `_remove_author_from_cache` does a full linear scan and rebuild of the follower's deque to purge the unfollowed author's posts - Source: entries/2026/06/05/news-feed-system-news_feed.md ### no-operation-is-truly-reversible [IN] DERIVED The codebase has no genuine undo or reversal: deletion is append-only metadata across all contexts (tombstones, delete markers, version entries), and failure handling escalates forward to permanent outcomes (retry-to-permanent-failure, independent-branch continuation) — both intentional removal and error recovery strictly add information rather than removing or reversing prior state. - Depends on: deletion-is-append-only-across-all-contexts, forward-only-extends-to-failure-handling ### no-window-merging-or-retraction [IN] OBSERVATION Once an `AggregationResult` is emitted from `advance_watermark`, there is no mechanism to update or retract it — finalized windows reject all further events. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### none-return-collapses-distinct-failure-modes [IN] DERIVED S3 and map routing both return None for all failure conditions (missing objects, unreachable destinations, unknown inputs), collapsing distinct error causes into a single sentinel value that simplifies callers but makes failure diagnosis impossible. - Depends on: s3-get-returns-none-for-missing, maps-no-exceptions-none-returns ### normalize-once-at-system-boundary [IN] DERIVED Autocomplete and web crawler both normalize inputs (query strings, URLs) exactly once at the system boundary, ensuring all internal operations work with canonical forms and preventing duplicate entries from case or format differences. - Depends on: autocomplete-normalize-at-boundary, crawler-normalize-once-convention ### notif-caller-controls-time [IN] OBSERVATION `process_queue` takes `current_time` as an explicit parameter rather than reading the system clock, making the notification system fully deterministic and testable - Source: entries/2026/06/05/notification-system-notification_system.md ### notif-exponential-backoff-with-jitter [IN] OBSERVATION Delivery retry uses exponential backoff (`2^(retry-1)`) multiplied by a random jitter factor in [0.5, 1.5] to prevent thundering herd on provider recovery - Source: entries/2026/06/05/notification-system-notification_system.md ### notif-priority-heap-stable [IN] OBSERVATION The priority queue uses a three-element key `(priority, timestamp, seq)` where `seq` is a monotonic counter, ensuring stable FIFO ordering within the same priority level - Source: entries/2026/06/05/notification-system-notification_system.md ### notif-quiet-hours-midnight-crossing [IN] OBSERVATION `_is_quiet_hours` handles overnight spans (start > end, e.g., 22–8) with `hour >= start or hour < end`, correctly wrapping across midnight - Source: entries/2026/06/05/notification-system-notification_system.md ### notif-rate-limit-on-success-only [IN] OBSERVATION Rate limit budget (`RateLimiter.record`) is consumed only after successful delivery, not on failed send attempts — failed attempts don't eat rate limit quota - Source: entries/2026/06/05/notification-system-notification_system.md ### notif-template-rendering-strict [IN] OBSERVATION `TemplateRegistry.render` raises `KeyError` for missing templates or missing context variables — fail-fast with no silent defaults, but uncaught in `process_queue` so bad templates crash queue processing - Source: entries/2026/06/05/notification-system-notification_system.md ### notif-two-phase-rate-limit [IN] OBSERVATION Rate limits are checked both at `send()` time (fast rejection before queuing) and again at `process_queue()` time (because budget may have been consumed between enqueue and delivery) - Source: entries/2026/06/05/notification-system-notification_system.md ### notification-defensive-double-rate-check [IN] DERIVED The notification system checks rate limits at both send time (fast rejection) and process time (after queue delay) because the rate window can shift between enqueue and dequeue, and only successful deliveries consume budget — making the two checks complementary, not redundant. - Depends on: notif-two-phase-rate-limit, notif-rate-limit-on-success-only ### notification-delivery-is-bounded [IN] DERIVED The notification delivery pipeline is bounded: double rate checks at send and process time prevent over-delivery even across queue delays, and retry escalation to permanent failure ensures every notification eventually terminates — no notification retries indefinitely or escapes rate control. - Depends on: notification-defensive-double-rate-check, retry-escalates-to-permanent-failure ### notification-instantiates-forward-only-delivery [IN] DERIVED Notification delivery is a concrete instantiation of forward-only failure handling: double rate checks bound over-delivery, exponential backoff spaces retries, and escalation to permanent failure ensures the delivery pipeline terminates in finite time — the forward-only principle applied to the entire attempt-retry-escalate lifecycle. - Depends on: notification-delivery-is-bounded, forward-only-extends-to-failure-handling ### notification-system-is-delivery-complete [IN] DERIVED The notification system achieves delivery completeness when bounded delivery (double rate checks, retry escalation), strict rendering (fail-fast on missing templates/variables), and stable ordering (deterministic priority queue) all function correctly — unless the unused group-key infrastructure signals an incomplete aggregation feature needed for batch delivery scenarios. - Depends on: notification-delivery-is-bounded, notif-template-rendering-strict, notif-priority-heap-stable - Unless: notif-group-key-unused ### one-directional-state-machines-span-domains [IN] DERIVED One-directional state machines appear across unrelated domains: stream processing windows (OPEN→CLOSED→FINALIZED) use irreversible state progression to control event acceptance at each stage, and metrics alerting (OK→PENDING→ALERTING→RESOLVED) uses ordered states to gate alert firing through a duration threshold. Both employ forward-progressing state to reduce complexity, though the alerting machine allows a partial regression (PENDING→OK) when conditions clear early, making it not strictly one-directional. - Depends on: window-lifecycle-one-directional, metrics-alert-state-machine-four-states ### operational-conventions-are-module-scoped [IN] DERIVED Operational concerns — error signaling strategies (exceptions vs return codes vs None), eviction timing (eager vs lazy vs deferred), and failure reporting — are designed per-module with no cross-cutting conventions, meaning each module makes locally reasonable choices that collectively produce an unpredictable system-wide operational surface for callers. - Depends on: error-boundaries-are-module-local, eviction-timing-has-no-codebase-convention ### payment-balance-never-cached [IN] OBSERVATION `PaymentSystem.get_balance()` derives balance by scanning the full ledger on every call; no running total or balance cache is maintained. - Source: entries/2026/06/05/topic-consistency-models.md ### payment-double-entry-guarantees-balance-integrity [IN] DERIVED The double-entry ledger invariant (every movement creates balanced debit-credit pairs) and full-ledger balance derivation guarantee that balances reflect the true sum of all operations — unless the non-atomic overdraft check allows concurrent payments to both pass validation and create conflicting ledger entries. - Depends on: double-entry-invariant, balance-derived-from-ledger - Unless: payment-overdraft-not-atomic ### payment-error-strategy-split [IN] OBSERVATION Programming errors (unknown account, duplicate account, invalid refund state) raise `ValueError`; business-rule failures (insufficient balance, currency mismatch, processor failure) return a `Payment` with `status="FAILED"` - Source: entries/2026/06/05/payment-system-payment_system.md ### payment-idempotency-is-key-based [IN] OBSERVATION Idempotency is enforced by mapping client-provided keys to payment IDs in `_idempotency`; a repeated key returns the original `Payment` without re-processing - Source: entries/2026/06/05/payment-system-payment_system.md ### payment-ledger-is-fully-auditable [IN] DERIVED The double-entry ledger creates balanced debit-credit pairs for every money movement and derives balances from complete ledger scans, making the payment system's financial state fully reconstructible from its transaction history — unless the integrity verification function's exclusion of transfer transactions means the audit mechanism itself has blind spots that the ledger design was supposed to prevent. - Depends on: double-entry-invariant, balance-derived-from-ledger - Unless: verify-integrity-ignores-transfers ### payment-processor-injectable [IN] OBSERVATION The external payment processor is injected via `set_processor()` as a callable returning a status dict, decoupling processing logic from payment orchestration - Source: entries/2026/06/05/payment-system-payment_system.md ### pedagogical-breadth-is-safely-contained [IN] DERIVED Module isolation safely enables pedagogical breadth: multiple algorithm variants and simplified implementations serve learning goals without production risk, because module boundaries contain the impact of any performance or correctness tradeoff. - Depends on: multiple-algorithms-serve-pedagogical-breadth, pedagogical-tradeoffs-are-safe-within-module-boundaries ### pedagogical-tradeoffs-are-safe-within-module-boundaries [IN] DERIVED Brute-force algorithms, bounded collections, and in-process simulation are acceptable pedagogical trade-offs because each module is a standalone learning artifact with no cross-module dependencies — simplifications that would be dangerous in production are safe when confined to self-contained demonstrations. - Depends on: brute-force-acceptable-at-pedagogical-scale, bounded-collections-trade-completeness-for-memory, sdi-modules-are-standalone-learning-artifacts - Unless: dmq-reused-by-stock-exchange ### per-module-design-to-verification-is-hermetic [IN] DERIVED Each module achieves a hermetic design-to-verification cycle: prescriptive plans create verifiable specifications, structural construction produces testable properties, deterministic testing validates those properties, and the entire chain is contained within the module with no cross-module dependencies — the full plan-implement-verify pipeline is self-contained per module. - Depends on: design-to-verification-traceability, modules-are-independently-correct ### perimeter-and-forward-only-jointly-bound-state-space [IN] DERIVED The architecture constrains its state space through complementary entry and progression mechanisms: perimeter normalization restricts what enters the system (clean, canonicalized inputs only), and forward-only design restricts how state evolves (monotonically, irreversibly, without regression) — together defining a wedge-shaped state space that narrows at entry and only expands forward. - Depends on: boundary-normalization-serves-defense-and-correctness, forward-only-preserves-correctness-despite-accepted-gaps ### perimeter-defense-enables-cheap-writes [IN] DERIVED The write path's cheapness is partially enabled by the perimeter defense model: because inputs are normalized once at system boundaries and internal callers are trusted, writes operate on pre-validated data without redundant checking, keeping the asymmetric cost model's write side genuinely lightweight beyond just routing simplicity. - Depends on: perimeter-defense-ensures-data-quality, writes-are-cheap-reads-pay ### perimeter-defense-ensures-data-quality [IN] DERIVED The codebase's perimeter defense model — normalize inputs once at system boundaries, then trust all internal callers — ensures internal operations work on clean, canonical data throughout the processing pipeline. - Depends on: normalize-once-at-system-boundary, callers-trusted-at-internal-boundaries - Unless: proximity-no-coordinate-validation ### pipeline-processing-maximizes-forward-progress [IN] DERIVED Processing pipelines are designed to maximize forward progress and never backtrack: the video DAG continues independent branches when siblings fail (partial success over total failure), and stream processing makes finalization irreversible (no retraction of emitted results) — ensuring that completed work is never undone. - Depends on: video-pipeline-maximizes-useful-work-on-failure, watermark-finalization-is-irreversible ### pipeline-status-contract [IN] OBSERVATION `VideoUploadPipeline` sets video status to FAILED if and only if the `finalize` stage does not reach COMPLETED. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### plan-review-documents-known-gaps [IN] OBSERVATION The `plan_review.md` pattern explicitly catalogues TOCTOU, blocking sleep, and permanent-failure-on-idempotency-key as accepted divergences rather than bugs. - Source: entries/2026/06/05/topic-plan-to-implementation-fidelity.md ### plan-to-implementation-correspondence-is-verifiable [IN] DERIVED Prescriptive plans specify exact signatures and data models, and design reviews document known gaps — together they should create a verifiable plan-to-implementation correspondence where deviations are traceable — but the absence of divergence annotations means actual implementation deviations are invisible post-implementation, making the correspondence unauditable. - Depends on: plans-are-prescriptive, plan-review-documents-known-gaps - Unless: no-divergence-annotations ### plans-are-prescriptive [IN] OBSERVATION Plans specify exact method signatures, data models, and assertion examples, leaving implementations with near-zero design freedom at the API level. - Source: entries/2026/06/05/topic-plan-to-implementation-fidelity.md ### precision-table-descending-radius [IN] OBSERVATION GeohashIndex._PRECISION_TABLE is ordered by descending radius threshold; _precision_for_radius returns the precision for the first threshold the radius exceeds, defaulting to maximum precision 8 - Source: entries/2026/06/05/proximity-service-proximity_service.md ### probabilistic-dedup-trades-memory-for-coverage [IN] DERIVED The crawler's multi-layer dedup combines deterministic normalization with probabilistic structures (Bloom filter for O(k) exact-URL rejection, SimHash for O(1) near-content detection), achieving coverage across three dimensions while maintaining bounded memory through tunable accuracy-space tradeoffs. - Depends on: crawler-three-layer-dedup, probabilistic-structures-trade-accuracy-for-space ### probabilistic-structures-trade-accuracy-for-space [IN] DERIVED Three systems deploy probabilistic data structures with explicitly tunable accuracy-space tradeoffs: HyperLogLog with 16384 registers for ~1% cardinality error, Morris counters averaging 32 independent estimators for approximate counting, and SimHash with a 3-bit Hamming threshold for near-duplicate detection — each accepting bounded inaccuracy to achieve sub-linear space consumption. - Depends on: hll-default-precision, morris-counter-32-estimators, simhash-threshold-default-3 ### quadtree-boundary-first-child-wins [IN] OBSERVATION Quadtree `_contains` uses inclusive bounds (`<=`), so a point on the boundary of multiple children is inserted into the first matching child in NW → NE → SW → SE order - Source: entries/2026/06/05/proximity-service-proximity_service.md ### quadtree-no-remove [IN] OBSERVATION Quadtree supports insert and query but has no removal operation, unlike GeohashIndex which supports O(1) removal via its dual-map design - Source: entries/2026/06/05/proximity-service-proximity_service.md ### quality-and-performance-strategies-are-aligned [IN] DERIVED Structural correctness (supported by immutable values, synchronized structures, and hermetic testing) and per-use-case cost allocation (shifting work to writes or reads based on access pattern) address different levels of system quality — component-level safety and system-level efficiency, respectively. These strategies are complementary: structural invariants can reduce the need for some runtime validation, potentially simplifying the cost allocation decisions at system boundaries. - Depends on: structural-correctness-and-testability-are-co-designed, write-cost-allocation-matches-access-pattern ### quality-convergence-is-scale-independent [IN] DERIVED Each module's correctness-simplicity-performance convergence is independent of implementation scale: the structural patterns (immutability, synchronized structures, state ratchets, forward-only transitions) that produce triple convergence are identical whether the algorithms underneath are production-optimized or pedagogically simplified — because the trade-offs (brute-force algorithms, bounded collections) are safely contained within module boundaries and do not affect the structural layer where convergence occurs. - Depends on: module-level-triple-convergence, pedagogical-breadth-is-safely-contained ### quality-guarantees-are-scale-and-layer-independent [IN] DERIVED The architecture's quality guarantees hold without regard to either scale or abstraction layer: per-module triple convergence (correctness, simplicity, performance) is independent of implementation scale, and forward-only correctness (no-regression state machines, monotonic ordering, irrevocable finalization) applies independently at the data, domain, and execution layers — quality neither degrades with growth nor varies across architectural levels. - Depends on: quality-convergence-is-scale-independent, forward-only-spans-data-domain-and-execution-layers ### queue-abstraction-is-logical-not-physical [IN] DERIVED The message queue is designed as a logical abstraction layer, not a physical storage system: offsets are logical (surviving partition trimming via base_offset adjustment), dead-letter queues are regular topics with a naming convention (no special infrastructure), and delivery guarantees are enforced entirely at the consumer layer through poll/commit semantics — the broker provides ordering and retention while consumers own correctness. - Depends on: message-delivery-guarantees-are-consumer-side, dmq-partition-offset-is-logical, dmq-dlq-is-regular-topic ### rate-limiter-four-algorithms [IN] OBSERVATION The rate limiter provides exactly four algorithms: token bucket, fixed window counter, sliding window log, and sliding window counter, all interchangeable via the `RateLimiter` ABC - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### rate-limiter-middleware-path-routing [IN] OBSERVATION `HTTPRateLimitMiddleware` supports per-path rate limiting via `path_rules` dict, falling back to `default_limiter` for unmatched paths - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### rate-limiter-no-persistence [IN] OBSERVATION All rate limiter state is in-memory with no persistence or distribution mechanism; the implementation is single-process only - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### rate-limiter-per-client-state [IN] OBSERVATION All rate limiting state is tracked per `client_id` string; there is no global (cross-client) rate limiting - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### rate-limiter-time-injectable [IN] OBSERVATION Every rate limiter method that depends on wall-clock time accepts an optional `current_time` parameter defaulting to `time.time()`, making all algorithms deterministically testable - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### read-cost-scales-with-system-complexity [IN] DERIVED The read path's correctness burden grows with distribution complexity: single-node reads handle lazy computation and soft-delete interpretation, while distributed reads additionally perform repair, tombstone filtering, and multi-version conflict resolution — the more distributed the system, the more reads pay. - Depends on: reads-bear-full-correctness-burden, deletion-strategy-scales-with-distribution ### read-path-absorbs-consistency-and-computation-cost [IN] DERIVED Multiple systems deliberately shift both computation (lazy evaluation) and convergence work (read repair) to the read path, keeping writes simple and fast at the cost of heavier, more complex reads. - Depends on: lazy-read-time-evaluation-trades-write-simplicity-for-read-cost, kv-read-path-is-self-healing ### read-path-is-universal-site-of-deferred-work [IN] DERIVED The read path's responsibility encompasses three orthogonal dimensions: active convergence (repair, lazy computation, consistency enforcement), entity-state filtering (lifecycle-aware result exclusion for search and recommendations), and delivery guarantee enforcement (consumer-side poll/commit semantics determine at-least-once vs exactly-once) — making reads the universal site where the architecture's deferred and delegated correctness work is performed. - Depends on: read-responsibility-spans-convergence-and-filtering, delivery-guarantees-follow-write-read-cost-asymmetry ### read-path-responsibility-exceeds-verification [IN] DERIVED The read path's active convergence role (healing divergence via repair, computing deferred state via lazy evaluation, interpreting metadata-as-deletion) grows in responsibility as distribution complexity increases, yet the co-designed test infrastructure validates structural write-path properties most effectively — creating a widening gap where the component bearing maximum correctness responsibility has the weakest verification coverage relative to its burden. - Depends on: reads-are-active-convergence-engines, growing-read-complexity-outpaces-test-coverage ### read-path-verification-is-improving [IN] DERIVED Two read-path verification mechanisms were added — S3 ETag integrity checking (detect corruption on read) and news feed cache rebuild (repair lost cache state) — narrowing the gap between the read path's growing responsibility and its verification coverage, though the broader pattern persists for KV read-repair, lazy evaluation, and metadata-as-deletion in other systems. - Depends on: s3-etag-verified-on-read, news-feed-cache-is-rebuildable, read-path-responsibility-exceeds-verification ### read-paths-filter-by-entity-state [IN] DERIVED Read paths systematically exclude entities based on lifecycle state: video search returns only READY/UPLOADING statuses, and recommendations exclude already-watched videos — adding read-time filtering cost proportional to the number of state categories that must be checked. - Depends on: search-status-filter, recommendation-excludes-watched ### read-responsibility-spans-convergence-and-filtering [IN] DERIVED The read path's responsibility extends beyond active convergence (repair, lazy computation, consistency enforcement) to include systematic entity-state filtering (excluding processing/failed/watched items) — both are deferred-to-read decisions whose complexity grows with the system's state space, compounding the read path's total correctness burden. - Depends on: reads-are-active-convergence-engines, search-status-filter, recommendation-excludes-watched ### reads-are-active-convergence-engines [IN] DERIVED Reads in this architecture are active convergence engines rather than passive data retrievals: they perform the deferred computation and consistency work that writes skip (lazy evaluation, read repair, tombstone interpretation) AND mutate system state as a side effect (triggering replica repair, advancing read markers), making the read path simultaneously the system's primary workload, its primary state-evolution mechanism, and its primary consistency enforcement layer. - Depends on: reads-are-not-pure-across-domains, read-path-absorbs-consistency-and-computation-cost ### reads-are-not-pure-across-domains [IN] DERIVED Reading has side effects across multiple domains: KV get triggers read repair (pushing non-dominated versions back to stale replicas), and email get unconditionally marks messages as read — observation modifies state as an unavoidable consequence, making "read-only" a leaky abstraction throughout the codebase. - Depends on: kv-read-repair-on-get, email-service-get-email-marks-read ### reads-bear-full-correctness-burden [IN] DERIVED Reads bear the full correctness burden: they absorb lazy computation and active repair to converge state, and must interpret metadata-as-deletion (tombstones, delete markers, soft-deleted records) to present a correct view — making the read path the primary site of system complexity across the codebase. - Depends on: read-path-absorbs-consistency-and-computation-cost, deletion-is-metadata-in-replicated-systems ### recommendation-excludes-watched [IN] OBSERVATION `get_feed` excludes videos the user has already watched from popular and content-based scores; collaborative filtering excludes them in its own co-occurrence logic. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### representation-decoupling-spans-module-and-architecture-scales [IN] DERIVED Representation decoupling operates at two architectural scales through the same principle: within modules, input representations are separated from storage representations (dataclasses vs dicts, coordinator writes vs raw replicas); across the architecture, logical semantics are separated from physical state (offsets survive partition trimming, hash positions decouple from topology, delete markers decouple from data removal) — both enabling independent evolution of interfaces and implementations at their respective granularities. - Depends on: input-and-storage-representations-are-decoupled, logical-physical-separation-spans-topology-storage-and-deletion ### reservation-strategies-prevent-over-commitment [IN] DERIVED Two systems illustrate complementary approaches to preventing over-commitment of shared resources: Google Drive reserves full quota at upload initiation (capacity locked upfront via chunked upload protocol), while the hotel reservation system uses an optimistic read-then-verify-version pattern on per-date inventory — though the hotel implementation executes both phases synchronously, making its concurrency check demonstrative rather than functionally necessary under real interleaving. - Depends on: gdrive-quota-reservation, hotel-occ-two-phase-reserve ### resource-bounding-uses-dual-fidelity-strategies [IN] DERIVED The codebase systematically bounds resource consumption through two orthogonal fidelity-reduction strategies: deterministic truncation (bounded deques, version pruning, click history caps) silently drops the oldest data in time-ordered domains, while probabilistic approximation (Bloom filters, SimHash, HyperLogLog, Morris counters) tolerates statistical error in set-membership domains — together covering both sequential and presence/absence resource bounding. - Depends on: memory-is-bounded-at-the-cost-of-silent-information-loss, probabilistic-dedup-trades-memory-for-coverage ### retry-converts-timeout-to-failure [IN] OBSERVATION `_call_processor_with_retry` retries only on `"timeout"` status with exponential backoff (0.1s × 2^attempt); after `_max_retries` exhausted timeouts, it returns `{"status": "failure"}` — the caller never sees a timeout as a final result - Source: entries/2026/06/05/payment-system-payment_system.md ### retry-escalates-to-permanent-failure [IN] DERIVED Retry logic converts transient failures to permanent outcomes: exponential backoff with jitter spaces out attempts to prevent thundering herd, but after exhausting retries the failure is made permanent and final — no infinite retry loop, no silent swallow of the underlying error. - Depends on: notif-exponential-backoff-with-jitter, retry-converts-timeout-to-failure ### robots-longest-prefix-match [IN] OBSERVATION `RobotsParser.is_allowed` resolves conflicting allow/disallow rules by selecting the rule with the longest matching path prefix, falling back from agent-specific rules to `*`. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### routing-heuristics-prioritize-correctness-over-tightness [IN] DERIVED Routing heuristics prioritize guaranteed optimality over search efficiency: A* uses haversine distance (always underestimates road distance) and time optimization divides by the global maximum speed limit (always underestimates travel time) — both are admissible heuristics that guarantee optimal paths at the cost of exploring unnecessary nodes. - Depends on: maps-astar-heuristic-admissible, maps-time-heuristic-uses-global-max-speed ### run-tests-is-repo-convention [IN] OBSERVATION Multiple modules use identical `run_tests.py` wrapper scripts that derive the test file path via `__file__.replace("run_tests.py", ...)` and invoke `pytest.main()` programmatically. - Source: entries/2026/06/05/search-autocomplete-run_tests.md ### s3-bucket-delete-requires-empty [IN] OBSERVATION Bucket deletion requires the bucket to be logically empty: no live objects, and in versioned buckets, no non-marker versions at all. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-delete-marker-hides-not-removes [IN] OBSERVATION Deleting a versioned object appends a delete marker; all prior versions remain accessible by explicit `version_id`. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-etag-verified-on-read [IN] OBSERVATION get_object re-computes the MD5 ETag from stored data and compares against the stored ETag before returning, raising ValueError on mismatch — detecting data corruption at read time rather than silently serving corrupted data. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-get-returns-none-for-missing [IN] OBSERVATION `get_object` and `head_object` return `None` for missing objects rather than raising, matching S3's HTTP 404 semantics. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-multipart-sorts-by-part-number [IN] OBSERVATION `complete_multipart` assembles parts by sorting on part number, so upload order is irrelevant. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-policy-default-allow [IN] OBSERVATION `check_bucket_policy` returns `True` (allow) when no policies exist or when no policy matches — opposite of AWS IAM's default-deny. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-presigned-secret-is-class-level [IN] OBSERVATION `_SECRET` is generated once per class load (`uuid4().hex`), not per instance, so all `ObjectStorage` instances in the same process share the same HMAC signing key. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-unversioned-put-replaces [IN] OBSERVATION In unversioned buckets, `put_object` replaces the entire version list with a single-element list, making previous data unrecoverable. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### s3-version-list-append-only [IN] OBSERVATION Each object key maps to a `list[ObjectVersion]` where the latest version is always `versions[-1]`; versioned puts append, unversioned puts replace the entire list. - Source: entries/2026/06/05/s3-object-storage-s3_object_storage.md ### scaling-is-safe-for-both-quality-and-risk [IN] DERIVED Horizontal scaling is safe along two independent dimensions: coordination-free scaling preserves per-module quality convergence (the correctness-simplicity-performance triad holds regardless of scale), and forward-only design with state monotonicity jointly bounds the read-path risk that would otherwise accumulate with growing state — scaling neither degrades quality nor amplifies risk. - Depends on: coordination-free-scaling-preserves-triple-convergence, forward-only-and-monotonicity-jointly-bound-read-path-risk ### scaling-uses-logically-uniform-indirection [IN] DERIVED The architecture follows a single scaling pattern as distribution complexity increases: add logical indirection that decouples semantics from physical state — consistency strategies add semantic layers (tombstones, vector clocks) while topology and storage add logical abstractions (stateless rings, logical offsets, metadata-as-deletion) through the same mechanism of inserting a logical interpretation layer between operations and physical state. - Depends on: consistency-strategy-scales-uniformly-with-distribution, logical-physical-separation-spans-topology-storage-and-deletion ### sdi-implementations-are-in-process-simulations [IN] OBSERVATION All implementations simulate distributed behavior in-process with no real network or storage dependencies — they are pedagogical reference implementations, not production systems. - Source: entries/2026/06/05/scan-sdi-implementations.md ### sdi-implementations-use-only-stdlib [IN] OBSERVATION All implementations use only Python standard library imports (no external dependencies), keeping each module self-contained and dependency-free. - Source: entries/2026/06/05/scan-sdi-implementations.md ### sdi-modules-are-standalone-learning-artifacts [IN] DERIVED Each of the 25 modules is independently runnable with only stdlib, no shared code, and in-process simulation of distributed behavior, making each a complete self-contained teaching artifact that can be understood in isolation. - Depends on: sdi-repo-is-25-independent-modules, sdi-implementations-use-only-stdlib, sdi-implementations-are-in-process-simulations ### sdi-repo-is-25-independent-modules [IN] OBSERVATION Each of the 25 system design implementations is fully self-contained in its own directory with no shared libraries, no common base classes, and no cross-module imports. - Source: entries/2026/06/05/scan-sdi-implementations.md ### sdi-repo-lifecycle-convention [IN] OBSERVATION Every module follows a consistent lifecycle: `plan.md` → `plan_review.md` → Python implementation → pytest-based tests. - Source: entries/2026/06/05/scan-sdi-implementations.md ### search-status-filter [IN] OBSERVATION `VideoStore.search` returns only videos with status READY or UPLOADING, excluding PROCESSING and FAILED videos. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### self-reinforcing-correctness-composes-with-coordination-free-scaling [IN] DERIVED The architecture's self-reinforcing correctness composes with coordination-free scaling: each module's closed correctness loop generates and validates its own structural properties independently, while accumulative state scales through logical indirection — adding modules neither disrupts existing correctness loops nor requires coordination, because both correctness and scaling are structurally module-local. - Depends on: correctness-is-self-reinforcing-per-module, accumulative-state-scales-without-coordination ### simhash-threshold-default-3 [IN] OBSERVATION Two pages are considered near-duplicates if their 64-bit SimHash fingerprints differ in 3 or fewer bits, configurable via the `duplicate_threshold` parameter. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### simplicity-is-dual-minimization [IN] DERIVED The codebase achieves simplicity through two orthogonal minimization strategies: conceptual minimization (deriving capabilities from existing data and structures rather than inventing new mechanisms) and algorithmic minimization (preferring simpler algorithms at pedagogical scale), both independently reducing the surface area for correctness bugs. - Depends on: abstractions-minimize-new-concepts, algorithmic-simplicity-reinforces-structural-correctness ### simplicity-mechanisms-independently-produce-correctness [IN] DERIVED Both axes of the codebase's dual minimization strategy independently produce correctness: conceptual minimization (deriving from existing data, reusing abstractions) inherits proven invariants, and mechanical minimization (simpler algorithms, structural constraints) reduces bug surface — the simplicity-correctness convergence holds along each axis, not just in aggregate. - Depends on: simplicity-is-dual-minimization, correctness-and-simplicity-share-the-same-mechanism ### sliding-window-counter-weighted-approximation [IN] OBSERVATION SlidingWindowCounterLimiter approximates a sliding window by keeping current and previous fixed-window counters, weighting the previous window's count by `(1 - elapsed_fraction)` as time progresses - Source: entries/2026/06/05/rate-limiter-rate_limiter.md ### snowflake-rejects-backward-clock [IN] OBSERVATION SnowflakeGenerator raises RuntimeError on clock regression, while FlakeIDGenerator and ULIDGenerator silently handle it (spin-wait and random increment respectively). - Source: entries/2026/06/05/unique-id-generator-unique_id_generator.md ### snowflake-sequence-max-4096-per-ms [IN] OBSERVATION SnowflakeGenerator allows at most 4096 IDs per millisecond per worker (12-bit sequence 0–4095), then spin-waits for the next millisecond. - Source: entries/2026/06/05/unique-id-generator-unique_id_generator.md ### social-domains-fully-realize-ideal-write-path [IN] DERIVED Social domains exemplify the write-path ideal described in the codebase: graph symmetry provides both routing completeness (all recipients reachable without lookup) and coordination freedom (no distributed ID generation needed), achieving the write-path triad of cheapness, correctness, and coordination-free operation through properties that emerge from non-interfering mechanisms rather than from a single structural property alone. - Depends on: social-writes-are-complete-and-coordination-free, write-path-is-cheap-correct-and-coordination-free ### social-systems-combine-symmetric-graphs-and-lightweight-fanout [IN] DERIVED Social systems pair symmetric graph structures (bidirectional contacts and friendships with no one-way follow) with reference-based fan-out (IDs pushed at write time, data hydrated at read time), achieving simplified visibility rules at the graph layer and minimal write amplification at the delivery layer. - Depends on: symmetric-social-graphs-simplify-visibility, fan-out-write-pushes-references-not-data ### social-writes-are-complete-and-coordination-free [IN] DERIVED Social domains achieve the codebase's most streamlined write path: graph symmetry guarantees complete routing (all recipients are reachable without lookup), and deterministic identity derivation eliminates coordination (no distributed ID generation needed) — two independent properties that emerge from the same lightweight write-time decision framework. - Depends on: symmetric-graphs-enable-complete-lightweight-routing, write-path-eliminates-coordination-across-identity-and-routing ### soft-delete-is-dual-purpose [IN] DERIVED Soft delete serves two independent purposes across the codebase: preserving structural invariants (sequence contiguity, trie connectivity) in single-system contexts, and preventing distributed resurrection (tombstones, delete markers) in replicated contexts — making it a universal deletion strategy whose value transcends distribution model. - Depends on: soft-delete-preserves-structural-invariants, soft-delete-prevents-distributed-resurrection ### soft-delete-preserves-structural-invariants [IN] DERIVED Chat and autocomplete use soft delete to preserve structural invariants that physical deletion would break — sequence number contiguity and trie node connectivity — independently of the distributed-resurrection concern that motivates tombstones in replicated systems. - Depends on: chat-soft-delete-preserves-sequence, autocomplete-delete-is-soft ### soft-delete-prevents-distributed-resurrection [IN] DERIVED In distributed or versioned storage, physical deletion causes data resurrection from replicas or versions that haven't seen the delete; both KV (tombstones) and S3 (delete markers) solve this by writing a deletion marker instead of removing data. - Depends on: kv-store-deletes-use-tombstones, s3-delete-marker-hides-not-removes ### spatial-queries-combine-adaptive-resolution-with-exact-filtering [IN] DERIVED Spatial query systems pair structurally adaptive resolution with exact distance filtering: both geohash and quadtree narrow candidates via spatial structure then filter by haversine, and the structural resolution itself is derived from query parameters (grid cell size from distance threshold, geohash precision from radius table). - Depends on: both-indexes-use-haversine-filter, nearby-friends-grid-cell-size-tied-to-threshold, precision-table-descending-radius ### special-cases-reuse-existing-abstractions [IN] DERIVED Special-case concepts are implemented as instances of existing abstractions rather than introducing new infrastructure: dead-letter queues are regular topics with a naming prefix, and thread IDs are the first message's ID rather than a separately generated concept — keeping the operational and data model uniform by avoiding special-case machinery. - Depends on: dmq-dlq-is-regular-topic, email-service-thread-id-is-first-msg ### state-bounding-and-quality-scaling-are-orthogonal [IN] DERIVED The architecture bounds state evolution and supports quality preservation at scale through complementary mechanisms: state is bounded temporally (forward-only progression prevents regression) and spatially (fidelity reduction limits resource consumption), while quality-preserving scaling is supported by adaptive coordination that selects correctness mechanisms based on domain risk — together these constrain physical resources while maintaining logical correctness guarantees in the domains where targeted coordination is applied. - Depends on: state-is-temporally-and-spatially-bounded, adaptive-coordination-enables-quality-preserving-scaling ### state-growth-is-unconditionally-monotonic [IN] DERIVED The system's state lattice is unconditionally growing: irreversible accumulation ensures state never shrinks through normal operations, and even the mechanism explicitly designed for removal (deletion) adds metadata that expands the lattice — the growth property has no exception path, making monotonic expansion a structural invariant. - Depends on: state-is-irreversibly-accumulative, deletion-reinforces-monotonic-state ### state-is-bounded-and-authority-preserving [IN] DERIVED The architecture bounds state space through complementary entry and progression mechanisms (perimeter normalization restricts what enters, forward-only progression constrains evolution) while the two-tier state model ensures bounding never sacrifices authority: deterministic truncation and probabilistic approximation affect only derived/cached state (deques, HLL registers), never authoritative state (ledgers, version histories, tombstones). - Depends on: perimeter-and-forward-only-jointly-bound-state-space, two-tier-state-preserves-authority-under-monotonicity ### state-is-irreversibly-accumulative [IN] DERIVED The system's state space is a monotonically expanding, append-only lattice: state only grows (monotonic accumulation from stream ratchets and append-only deletion) because no operation ever removes it (all deletes are additive, all finalization is permanent, all state changes are forward-only). - Depends on: state-is-monotonically-accumulative, no-operation-is-truly-reversible ### state-is-monotonically-accumulative [IN] DERIVED State only accumulates across the full codebase: stream processing uses doubly-forward-only ratchets preventing regression (windows never reopen, dedup outlives finalization), and deletions across all system types append metadata rather than destroying data (tombstones, delete markers, soft-delete flags) — the system's information content is monotonically non-decreasing. - Depends on: stream-processing-correctness-is-doubly-forward-only, deletion-is-append-only-across-all-contexts - Unless: wallet-creation-silently-overwrites ### state-is-temporally-and-spatially-bounded [IN] DERIVED The architecture bounds state evolution in two independent dimensions: temporal regression is structurally impossible (one-directional state machines and monotonic accumulation prevent backward movement), and spatial growth is bounded by dual-fidelity strategies (deterministic truncation and probabilistic structures cap resource consumption) — the system can neither go backward nor grow unbounded. - Depends on: temporal-regression-is-structurally-impossible, resource-bounding-uses-dual-fidelity-strategies ### state-machines-enforce-temporal-gap-containment [IN] DERIVED One-directional state machines are the concrete enforcement mechanism for temporal gap containment: their irrevocable transitions (OPEN→CLOSED→FINALIZED, OK→PENDING→ALERTING) mechanically prevent temporal gaps from causing state regression, making gap containment structurally enforced rather than conventionally assumed. - Depends on: state-machines-instantiate-forward-only-monotonicity, temporal-gaps-are-contained-by-forward-only-design ### state-machines-instantiate-forward-only-monotonicity [IN] DERIVED One-directional state machines across domains (window lifecycles, alert evaluators) are concrete instantiations of the codebase's forward-only/monotonicity constraint: the architectural primitive that discourages regression and supports progress manifests at the domain level as largely irreversible state progressions, though partial regressions (e.g., PENDING→OK in alerting) show the constraint is applied with domain-specific flexibility rather than as a strict universal rule. - Depends on: one-directional-state-machines-span-domains, forward-only-and-monotonicity-are-a-single-constraint ### state-ratchets-prevent-regression-across-domains [IN] DERIVED Both messaging and stream processing use one-directional state progressions — read cursors that only advance, windows that never reopen — to eliminate entire classes of regression bugs where state could move backwards. - Depends on: chat-monotonic-read-progress, watermark-finalization-is-irreversible ### state-reversal-is-redundantly-prevented [IN] DERIVED State reversal is prevented by redundant mechanisms at different architectural levels: operational guards (preconditions before permanent removal, two-phase trash workflows) prevent accidental data loss at the operation level, while structural ratchets (one-directional state machines, monotonic accumulation) prevent regression at the architectural level — defense-in-depth against the single most dangerous failure mode. - Depends on: state-reversal-is-uniformly-guarded, temporal-regression-is-structurally-impossible ### state-reversal-is-uniformly-guarded [IN] DERIVED The codebase guards state reversal through layered mechanisms: soft delete serves dual purposes (preserving invariants locally, preventing resurrection distributedly), and permanent deletion requires preconditions (empty buckets, trashed state) — unless non-deletion reversals like hotel cancellation lack equivalent underflow guards, showing the reversal-safety pattern is incomplete. - Depends on: soft-delete-is-dual-purpose, deletion-is-guarded-by-preconditions - Unless: hotel-cancel-no-underflow-guard ### stock-exchange-aggressive-then-rest [IN] OBSERVATION `place_order` first attempts to match the incoming order against the opposite side (`_match_order`), then adds any unfilled remainder to the book — the standard aggressor/resting model. - Source: entries/2026/06/05/stock-exchange-solution.md ### stock-exchange-fifo-matching [IN] OBSERVATION Orders at the same price level are matched in FIFO order, enforced by `deque` append/popleft semantics — this is the price-time priority algorithm. - Source: entries/2026/06/05/stock-exchange-solution.md ### stock-exchange-market-orders-never-rest [IN] OBSERVATION Market orders that can't be fully filled have their remainder cancelled; they are never added to the order book. - Source: entries/2026/06/05/stock-exchange-solution.md ### stock-exchange-matching-produces-valid-trades [IN] DERIVED The stock exchange correctly implements price-time priority matching (best price first, FIFO within price, execute at resting price), producing valid trades — but only when callers provide valid order fields, since the engine performs no input validation. - Depends on: stock-exchange-price-time-priority - Unless: stock-exchange-no-input-validation ### stock-exchange-price-sort-is-full-resort [IN] OBSERVATION `_add_to_book` re-sorts the entire price list on every insertion (O(n log n)) rather than using `bisect.insort` — acceptable for interview scope but not production-grade. - Source: entries/2026/06/05/stock-exchange-solution.md ### stock-exchange-price-time-priority [IN] DERIVED The stock exchange implements standard price-time priority matching: incoming orders match aggressively against the best resting price, FIFO within each price level via deque ordering, with trades always executing at the resting order's price. - Depends on: stock-exchange-aggressive-then-rest, stock-exchange-fifo-matching, stock-exchange-resting-price-execution ### stock-exchange-resting-price-execution [IN] OBSERVATION Trades always execute at the resting (maker) order's price, not the incoming (taker) order's price — standard exchange behavior. - Source: entries/2026/06/05/stock-exchange-solution.md ### stock-exchange-trade-counter-global [IN] OBSERVATION `Trade._counter` is a class-level counter that monotonically increases across all symbols and never resets, making trade IDs globally sequential but test-order-dependent. - Source: entries/2026/06/05/stock-exchange-solution.md ### stock-exchange-validates-complex-write-correctness [IN] DERIVED The stock exchange demonstrates that write-path structural correctness scales to complex multi-step mutations: price-time priority matching is a composite write operation (match against book, fill partial orders, cancel or rest the remainder) where structural discipline (FIFO deques, sorted price levels) ensures each step is valid — write correctness handles compositional complexity, not just single-step simplicity. - Depends on: stock-exchange-matching-produces-valid-trades, write-path-is-self-consistent-by-design ### stream-processing-correctness-is-doubly-forward-only [IN] DERIVED Stream processing achieves its correctness guarantees through two coordinated forward-only mechanisms: state ratchets prevent regression (windows never reopen, cursors never reverse), and dedup retention outlives finalization (2x allowed lateness), ensuring the system never double-counts events and never revises emitted results. - Depends on: dedup-and-finalization-are-coordinated, forward-only-design-prevents-regression-and-maximizes-progress ### structural-correctness-and-testability-are-co-designed [IN] DERIVED The codebase's preference for structural correctness (immutable values, synchronized structures, state ratchets) and its hermetic test design (stdlib-only, injectable time, in-process simulation) reinforce each other — structural invariants reduce the state space to valid subsets, and hermetic modules make those invariants exhaustively testable without non-deterministic infrastructure. - Depends on: correctness-by-construction-not-validation, deterministic-testability-by-design ### structural-correctness-enables-safe-cost-shifting [IN] DERIVED Where structural correctness disciplines (immutability, synchronized structures, state ratchets) are applied, shifting computation between write and read paths is primarily a performance decision rather than a correctness risk — the structural construction approach reduces (though does not eliminate) the chance that cost reallocation introduces consistency bugs. However, this safety does not extend to invariants that remain assumed but unenforced (such as quorum overlap and payment atomicity), where shifting computation could expose unguarded correctness gaps. - Depends on: structural-correctness-is-universally-applied, cost-model-adapts-to-access-frequency ### structural-correctness-is-universally-applied [IN] DERIVED The codebase enforces correctness through structural construction (immutability, synchronized data structures, state ratchets) rather than runtime validation — but this discipline is not universally applied, with critical invariants like quorum overlap and payment atomicity remaining assumed but unenforced. - Depends on: correctness-by-construction-not-validation - Unless: assumed-invariants-are-unenforced ### structural-discipline-prevents-consistency-bugs [IN] DERIVED The codebase favors structural invariants — immutable value objects and synchronized parallel data structures — over runtime validation to prevent consistency bugs, eliminating aliasing and index-divergence defects by construction rather than by checking. - Depends on: immutable-values-prevent-aliasing-bugs, multi-structure-sync-invariant ### symmetric-domains-achieve-strongest-lifecycle-correctness [IN] DERIVED Symmetric domains combine two independent correctness properties: the write-read lifecycle is structurally correct (bidirectional symmetry supports complete routing, active reads converge state), and temporal gaps are contained by forward-only design that prevents gap-induced regression — together these close both structural and temporal correctness concerns in these domains. - Depends on: write-read-lifecycle-is-correct-in-symmetric-domains, forward-only-preserves-correctness-despite-accepted-gaps ### symmetric-domains-are-quality-optimal [IN] DERIVED Symmetric domains achieve the codebase's highest quality ceiling: structurally correct write-read lifecycle (bidirectional symmetry enables reliable routing and active convergence) intersects with per-module triple convergence (correctness, simplicity, and performance) — symmetric modules are simultaneously lifecycle-complete and optimally balanced across all three quality dimensions. - Depends on: symmetric-domains-achieve-strongest-lifecycle-correctness, module-level-triple-convergence ### symmetric-graphs-enable-complete-lightweight-routing [IN] DERIVED Social graph symmetry is the enabling constraint for lightweight write-time routing: because relationships are always bidirectional, write-time routing decisions (who receives fan-out, who sees nearby friends) are fully determined by a single graph traversal — the combination of symmetric relationships with irrevocable reference-based fan-out eliminates the need for read-time routing correction that asymmetric follow graphs would require. - Depends on: social-systems-combine-symmetric-graphs-and-lightweight-fanout, write-time-decisions-are-lightweight-but-binding ### symmetric-social-graphs-simplify-visibility [IN] DERIVED Both chat contacts and nearby-friends enforce bidirectional relationships with no one-way follow mechanism, trading social model expressiveness for simpler visibility logic — if A sees B, B always sees A. - Depends on: chat-contacts-always-bidirectional, nearby-friends-friendship-always-symmetric ### symmetry-is-both-simplifier-and-routing-enabler [IN] DERIVED Bidirectional symmetry serves a dual architectural role: it simplifies reasoning across both social and spatial graph domains (eliminating one-way edge complexity) and specifically enables complete lightweight write-time routing in social systems through reference-based fan-out. - Depends on: symmetry-simplifies-across-graph-domains, social-systems-combine-symmetric-graphs-and-lightweight-fanout ### symmetry-simplifies-across-graph-domains [IN] DERIVED Bidirectional symmetry is enforced across social graphs (contacts, friendships) and spatial graphs (road edges), eliminating one-way edge complexity in visibility checks, nearby-friend computations, and shortest-path routing — a cross-domain preference for simpler invariants over expressive asymmetry. - Depends on: symmetric-social-graphs-simplify-visibility, maps-bidirectional-edges-share-data ### temporal-gaps-are-contained-by-forward-only-design [IN] DERIVED Forward-only design (irrevocable writes, monotonic cursors, irreversible finalization) contains the blast radius of temporal correctness gaps by preventing them from cascading backward — a TOCTOU race can produce a wrong result but cannot undo prior correct results. - Depends on: forward-only-design-prevents-regression-and-maximizes-progress, temporal-correctness-gaps-are-known-and-accepted - Unless: assumed-invariants-are-unenforced ### temporal-regression-is-structurally-impossible [IN] DERIVED Temporal regression is prevented by two independent structural mechanisms operating at different architectural levels: one-directional state machines enforce irrevocable transitions (OPEN→CLOSED→FINALIZED) that contain temporal gaps at the control-flow level, while unconditional state monotonicity ensures the underlying data lattice only grows — making backward state motion impossible at both control-flow and data-flow levels. - Depends on: state-machines-enforce-temporal-gap-containment, state-growth-is-unconditionally-monotonic ### ticket-server-first-value-equals-offset [IN] OBSERVATION TicketServerGenerator initializes its counter to `offset - step` so the first `generate()` call returns exactly `offset`. - Source: entries/2026/06/05/unique-id-generator-unique_id_generator.md ### time-injection-enables-deterministic-testing [IN] DERIVED Three systems inject wall-clock time as an explicit parameter (notification, rate limiter, crawler), enabling deterministic testing without mocking — but inconsistent defaults across systems undermine the pattern's reliability at integration boundaries. - Depends on: notif-caller-controls-time, rate-limiter-time-injectable, crawl-uses-simulated-clock, current-time-fallback-inconsistent ### time-injection-is-a-complete-testing-strategy [IN] DERIVED Time injection enables fully deterministic testing by making wall-clock time an explicit parameter across notification, rate limiting, and crawling — unless the inconsistent fallback defaults (rate limiter falls back to `time.time()` while chat defaults to `0.0`) mean that tests omitting the time parameter exercise fundamentally different behavior depending on which module's convention they inherit. - Depends on: time-injection-enables-deterministic-testing - Unless: current-time-fallback-inconsistent ### two-tier-state-preserves-authority-under-monotonicity [IN] DERIVED The codebase exhibits a pattern where state accumulates irreversibly (append-only, monotonically growing) while resource bounding is achieved through fidelity-reduction strategies — deterministic truncation (bounded deques, version pruning, history caps) and probabilistic approximation (Bloom filters, SimHash, HyperLogLog, Morris counters). This suggests a two-tier model where authoritative state grows without bound while derived or cached state is bounded and lossy, though the antecedents do not explicitly classify which specific structures (e.g., ledgers vs. feed caches) belong to which tier. - Depends on: state-is-irreversibly-accumulative, resource-bounding-uses-dual-fidelity-strategies - Unless: wallet-creation-silently-overwrites ### ulid-monotonic-within-millisecond [IN] OBSERVATION ULIDGenerator maintains sort order within the same millisecond by incrementing the random component rather than generating new random bits. - Source: entries/2026/06/05/unique-id-generator-unique_id_generator.md ### url-frontier-strategy-via-sequence-sign [IN] OBSERVATION BFS vs DFS is implemented by flipping the sign of the sequence number in the heapq min-heap — ascending for BFS (FIFO), negated for DFS (LIFO) — not by swapping data structures. - Source: entries/2026/06/05/web-crawler-web_crawler.md ### url-shortener-click-history-bounded [IN] OBSERVATION Click history per URL is capped at 1000 entries; older events are silently dropped on each redirect. - Source: entries/2026/06/05/url-shortener-url_shortener.md ### url-shortener-expiration-lazy [IN] OBSERVATION Expired URLs are never eagerly removed from storage; expiration is checked at read time in `redirect` and `list_urls` — no background reaper. - Source: entries/2026/06/05/url-shortener-url_shortener.md ### url-shortener-hash-collision-loop-unbounded [IN] OBSERVATION The hash strategy's collision resolution loop has no max-attempts guard — it will loop indefinitely if the keyspace is near-saturated. - Source: entries/2026/06/05/url-shortener-url_shortener.md ### url-shortener-rate-limit-sliding-window [IN] OBSERVATION Rate limiting uses a per-creator sliding window of 60 seconds, pruned eagerly on each `_check_rate_limit` call. - Source: entries/2026/06/05/url-shortener-url_shortener.md ### url-shortener-two-strategies [IN] OBSERVATION URLShortener supports two short code generation strategies: "counter" (monotonic base62) and "hash" (truncated SHA-256 with collision retry), selected at construction time. - Source: entries/2026/06/05/url-shortener-url_shortener.md ### verified-simplicity-is-hermetically-contained [IN] DERIVED Each module achieves a self-contained simplicity-to-verification cycle: dual minimization strategies (conceptual reuse + algorithmic simplicity) independently produce correctness properties, which are then verified within the module's hermetic design-to-verification pipeline — no cross-module dependency is needed to close the loop from simplicity through correctness to verification. - Depends on: per-module-design-to-verification-is-hermetic, simplicity-mechanisms-independently-produce-correctness ### video-pipeline-maximizes-useful-work-on-failure [IN] DERIVED The video pipeline DAG runs independent branches (transcode, thumbnail, metadata) in parallel and lets them continue even when a sibling fails, marking only transitive dependents as skipped — maximizing useful work completion on partial failures. - Depends on: dag-failure-cascade, youtube-pipeline-dag-structure ### video-pipeline-separates-control-from-data-flow [IN] DERIVED The video processing pipeline decouples control flow (DAG determines stage ordering and failure cascading) from data flow (mutable ctx dict blackboard passes state between stages without return-value threading). - Depends on: youtube-ctx-dict-blackboard, youtube-pipeline-dag-structure ### wallet-currency-immutable-after-creation [IN] OBSERVATION Currency is immutable after wallet creation; `transfer` checks currency match before acquiring locks, which is safe because the field never changes. - Source: entries/2026/06/05/digital-wallet-wallet.md ### wallet-deadlock-free-concurrent-transfers [IN] DERIVED Wallet achieves deadlock-free concurrent transfers through sorted lock acquisition (prevents cycles), two-tier locking (isolates balance vs transaction-list contention), and frozen checks inside the lock (eliminates TOCTOU between freeze and movement). - Depends on: wallet-lock-ordering-prevents-deadlock, wallet-frozen-check-inside-lock, wallet-two-tier-locking ### wallet-frozen-check-inside-lock [IN] OBSERVATION Frozen status is checked inside the wallet lock, eliminating TOCTOU races between freeze/unfreeze and money movement operations. - Source: entries/2026/06/05/digital-wallet-wallet.md ### wallet-lock-ordering-prevents-deadlock [IN] OBSERVATION Transfers acquire wallet locks sorted by `wallet_id`, preventing deadlock when two concurrent transfers involve the same pair of wallets in opposite directions. - Source: entries/2026/06/05/digital-wallet-wallet.md ### wallet-no-exceptions-caught [IN] OBSERVATION The wallet service has no `try`/`except` blocks; all seven custom exceptions propagate to the caller unconditionally. - Source: entries/2026/06/05/digital-wallet-wallet.md ### wallet-transfers-are-safe-under-concurrency [IN] DERIVED Wallet concurrent transfers are deadlock-free via sorted lock acquisition with frozen-check inside the lock — but this safety guarantee assumes stable wallet identity, which silent creation-overwrite could violate mid-transfer. - Depends on: wallet-deadlock-free-concurrent-transfers - Unless: wallet-creation-silently-overwrites ### wallet-two-tier-locking [IN] OBSERVATION Per-wallet locks protect balance mutations; a separate `_tx_lock` protects the shared transactions list. The wallet lock is always acquired before `_tx_lock`, never the reverse. - Source: entries/2026/06/05/digital-wallet-wallet.md ### watermark-drives-finalization [IN] OBSERVATION Windows are never finalized by event processing alone; only `advance_watermark` transitions windows to FINALIZED and emits `AggregationResult`s. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### watermark-finalization-is-irreversible [IN] DERIVED Aggregation windows are finalized only by watermark advance, follow a one-directional state lifecycle (OPEN→CLOSED→FINALIZED), and provide no mechanism to update or retract emitted results — finalization is a permanent commitment. - Depends on: watermark-drives-finalization, window-lifecycle-one-directional, no-window-merging-or-retraction ### webhook-errors-swallowed [IN] OBSERVATION Webhook callback exceptions are caught with bare `except Exception: pass`, making observer failures invisible but preventing them from disrupting payment processing - Source: entries/2026/06/05/payment-system-payment_system.md ### window-lifecycle-one-directional [IN] OBSERVATION Window state follows a one-way ratchet: OPEN → CLOSED → FINALIZED. Windows never reopen; OPEN accepts all events, CLOSED accepts late events within the lateness allowance, FINALIZED rejects everything. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### write-coordination-freedom-is-safe-under-module-isolation [IN] DERIVED Write-path coordination-free correctness (deterministic identity, lightweight routing, structural discipline) is reinforced by module isolation, which prevents cross-module state corruption by ensuring no shared mutable state or cross-cutting dependencies — together, the coordination-free write path and independent module correctness support end-to-end write-path safety within each module's boundary. - Depends on: write-correctness-is-both-structural-and-coordination-free, modules-are-independently-correct - Unless: assumed-invariants-are-unenforced ### write-correctness-is-both-structural-and-coordination-free [IN] DERIVED The write-read architecture achieves end-to-end correctness with a coordination-free write path: deterministic identity derivation and lightweight routing eliminate distributed coordination, while structural construction ensures the asymmetric model's validity — coordination cost exists only on the reconciling read side. - Depends on: write-path-is-coordination-free-and-correct, write-read-asymmetry-is-end-to-end-correct ### write-correctness-scales-from-routing-to-matching [IN] DERIVED Write-path structural correctness spans a range of mutation complexity without requiring distributed coordination: social domains achieve complete, coordination-free routing through graph symmetry and deterministic identity derivation, while the stock exchange achieves correct price-time priority matching with partial fills through structural discipline (FIFO deques, sorted price levels) — both rely on local structural properties rather than distributed coordination, differing primarily in the compositional complexity of their write operations. - Depends on: social-writes-are-complete-and-coordination-free, stock-exchange-validates-complex-write-correctness ### write-cost-allocation-matches-access-pattern [IN] DERIVED The codebase's default cost model pushes deferred costs to reads, but this default is selectively overridden: eagerly rebuilt derived state (such as autocomplete caches and leaderboard indexes) and lazily deferred computation (such as time decay, expiration, and balance derivation) coexist as deliberate per-use-case design choices, suggesting that access-pattern considerations influence where the cost boundary is placed. - Depends on: write-read-cost-allocation-is-per-use-case, writes-are-cheap-reads-pay ### write-path-eliminates-coordination-across-identity-and-routing [IN] DERIVED Write-time operations eliminate coordination needs across two complementary dimensions: deterministic identity derivation (sorted user-pairs, first-message IDs) removes central ID assignment, and reference-based routing (post IDs, inbox pointers) removes data-payload coordination — together, writes commit binding decisions using only local computation and lightweight references, requiring neither a coordinator nor full data payloads. - Depends on: identity-derivation-trades-validation-for-simplicity, write-time-decisions-are-lightweight-but-binding ### write-path-is-cheap-correct-and-coordination-free [IN] DERIVED Write-path cheapness, correctness, and coordination freedom form a mutually enabling triad: perimeter normalization eliminates internal validation costs (cheap), structural discipline prevents corruption without runtime checks (correct), and deterministic identity derivation eliminates distributed lookups (coordination-free) — three seemingly competing properties that emerge from non-interfering mechanisms rather than trading off against each other. - Depends on: perimeter-defense-enables-cheap-writes, write-path-is-coordination-free-and-correct ### write-path-is-complete-and-consistent-in-symmetric-domains [IN] DERIVED In graph-based systems, write-path correctness is reinforced by two independent properties: structural discipline (immutable values, synchronized data structures) prevents state corruption during writes, while domain symmetry (bidirectional relationships with no one-way edges) guarantees that lightweight write-time routing reaches all affected parties without edge cases — together ensuring that writes are both valid in state and complete in dispatch. - Depends on: symmetric-graphs-enable-complete-lightweight-routing, write-path-is-self-consistent-by-design ### write-path-is-coordination-free-and-correct [IN] DERIVED The write path achieves correctness without distributed coordination: deterministic identity derivation and lightweight binding decisions eliminate consensus needs, while structural discipline and forward-only semantics guarantee every write produces valid, non-regressive state transitions. - Depends on: writes-always-produce-valid-forward-progress, write-path-eliminates-coordination-across-identity-and-routing ### write-path-is-self-consistent-by-design [IN] DERIVED Write-path consistency is achieved through two reinforcing mechanisms: structural discipline (immutable values, synchronized data structures) prevents data-level corruption, while lightweight-but-binding routing (reference-only fan-out, irrevocable strategy selection) keeps control-flow decisions simple enough to be correct by inspection. - Depends on: structural-discipline-prevents-consistency-bugs, write-time-decisions-are-lightweight-but-binding ### write-path-validity-spans-the-full-complexity-spectrum [IN] DERIVED The write path supports valid forward progress across a range of complexity: structural correctness scales from simple fan-out routing (social domains) to complex multi-step matching (stock exchange) without adding distributed coordination, and forward-only design — the architecture's most load-bearing constraint — acts as a primary correctness mechanism that contains temporal gaps and prevents regression. Together these properties provide strong architectural support for writes producing irreversible state advancement, though the absolute guarantee of no invalid or reversible state is an architectural intent rather than a formally proven invariant. - Depends on: write-correctness-scales-from-routing-to-matching, forward-only-is-the-architectures-load-bearing-constraint ### write-read-asymmetry-is-end-to-end-correct [IN] DERIVED The write-read asymmetric model (irrevocable lightweight writes with reconciling reads, enforced through structural construction rather than runtime validation) is end-to-end correct — unless the read path depends on assumed invariants (quorum overlap, payment atomicity) that are never enforced in code, undermining the reconciliation that reads are supposed to perform. - Depends on: writes-commit-irrevocably-reads-reconcile, correctness-by-construction-not-validation - Unless: assumed-invariants-are-unenforced ### write-read-cost-allocation-is-per-use-case [IN] DERIVED The codebase demonstrates both strategies for derived state maintenance — eagerly rebuilding on every write (autocomplete caches, leaderboard reindexing) and lazily deferring computation to reads (time decay, expiration, balance derivation) — showing that write-vs-read cost allocation is a deliberate per-use-case design choice, not a single architectural pattern. - Depends on: eager-rebuild-trades-write-cost-for-derived-consistency, lazy-read-time-evaluation-trades-write-simplicity-for-read-cost ### write-read-lifecycle-is-correct-in-symmetric-domains [IN] DERIVED In structurally regular domains (symmetric graphs, forward-only state), the complete data lifecycle from mutation to retrieval is correct: writes commit complete, consistent state via symmetric routing with structural discipline, and reads actively converge any remaining divergence through repair and lazy evaluation — the write path's structural completeness and the read path's active convergence together close the correctness loop. - Depends on: write-path-is-complete-and-consistent-in-symmetric-domains, reads-are-active-convergence-engines ### write-time-decisions-are-lightweight-but-binding [IN] DERIVED Systems that route at write time push only lightweight references (post IDs, inbox pointers) and defer data hydration to reads — but these routing decisions are permanently locked in at write time with no retroactive correction mechanism, meaning a fast, cheap write path produces irrevocable outcomes. - Depends on: fan-out-write-pushes-references-not-data, write-time-routing-is-irrevocable ### write-time-routing-is-irrevocable [IN] DERIVED Both news feed and chat make irrevocable routing decisions at write time — selecting push vs pull strategy and routing to inbox vs offline queue respectively — with no mechanism to retroactively re-route messages when conditions change. - Depends on: news-feed-celebrity-threshold-at-write-time, chat-fanout-on-write ### writes-always-produce-valid-forward-progress [IN] DERIVED The write path both produces valid state (structural discipline prevents corruption, lightweight routing reaches all parties) and advances system progress forward-only (no-regression ratchets, maximum-progress pipelines) — unless cancel operations can underflow inventory below zero, enabling a write to produce invalid state and regress past a logical lower bound. - Depends on: write-path-is-self-consistent-by-design, forward-only-design-prevents-regression-and-maximizes-progress - Unless: hotel-cancel-no-underflow-guard ### writes-are-cheap-reads-pay [IN] DERIVED The codebase implements an asymmetric cost model where writes push minimal data and make binding routing decisions, while reads absorb all deferred costs — lazy computation, consistency repair, data hydration, and metadata interpretation. - Depends on: write-time-decisions-are-lightweight-but-binding, read-path-absorbs-consistency-and-computation-cost ### writes-commit-irrevocably-reads-reconcile [IN] DERIVED The codebase's asymmetric cost model and forward-only design are mutually reinforcing: writes make irrevocable routing decisions with minimal data, and the forward-only constraint (state ratchets, irreversible finalization) means reads can never ask writes to undo — reads must fully reconcile all accumulated complexity themselves. - Depends on: writes-are-cheap-reads-pay, forward-only-design-prevents-regression-and-maximizes-progress ### youtube-ctx-dict-blackboard [IN] OBSERVATION Pipeline stages communicate through a mutable `ctx` dict rather than return values — a blackboard pattern that avoids inter-stage type coupling but sacrifices type safety. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### youtube-pipeline-dag-structure [IN] OBSERVATION The video processing pipeline wires a 5-stage DAG: validate → (transcode | thumbnail | metadata) → finalize, where the three middle stages are independent after validation. - Source: entries/2026/06/05/design-youtube-design_youtube.md ### youtube-reciprocal-rank-fusion [IN] OBSERVATION `get_feed` blends recommendation strategies using reciprocal rank fusion: each strategy contributes `weight * 1/(rank+1)` to a video's score, with default weights favoring collaborative (0.5) over popular (0.3) over content-based (0.2). - Source: entries/2026/06/05/design-youtube-design_youtube.md ### architectural-coherence-is-bounded-at-the-write-read-split [OUT] DERIVED The write-available, read-correct architecture is coherent exactly at the structural boundary: everything within the structural safety net (immutability, construction-based guarantees, deterministic testing) reinforces itself in a self-consistent system, but coherence cannot extend past what structural enforcement reaches — the write-read split is simultaneously the source of the architecture's strength and the edge where its guarantees end. - Depends on: codebase-architecture-is-write-available-read-correct, design-coherence-bounded-by-enforceability ### architecture-is-correctly-self-limiting [OUT] DERIVED The architecture's correctness properties are self-limiting: coherence holds at the structural enforcement boundary (not beyond), and read correctness is structural rather than temporal — the system provides guarantees precisely where they can be mechanically enforced, while temporal consistency on the read path remains an accepted rather than guaranteed property. - Depends on: architectural-coherence-is-bounded-at-the-write-read-split, read-correctness-is-structural-not-temporal ### assumed-invariants-are-unenforced [OUT] DERIVED Critical correctness invariants exist only as developer assumptions, not as code-enforced constraints: the KV store relies on W+R>N quorum overlap without validating it, and the payment system assumes atomic balance checks despite non-atomic reads — both creating correctness guarantees that hold only when callers cooperate, with silent violations under edge conditions the code structurally permits. - Depends on: kv-quorum-consistency-assumed-not-enforced, payment-toctou-double-jeopardy ### autocomplete-blocklist-is-substring [OUT] OBSERVATION The blocklist filter removes results where any blocklisted term appears as a **substring** of the query, not just exact matches. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### autocomplete-fuzzy-is-last-char-only [OUT] OBSERVATION `fuzzy_suggest()` only tries single-character edits (substitution, deletion, insertion) on the **last character** of the prefix — it is not a full edit-distance search. - Source: entries/2026/06/05/search-autocomplete-search_autocomplete.md ### callers-trusted-at-internal-boundaries [OUT] DERIVED Multiple systems omit input validation entirely at internal module boundaries — the stock exchange accepts any order fields without checking quantity or price, and proximity search accepts any coordinates without range validation — reflecting a convention of trusting callers within the module perimeter rather than validating defensively. - Depends on: stock-exchange-no-input-validation, proximity-no-coordinate-validation ### codebase-architecture-is-write-available-read-correct [OUT] DERIVED The codebase converges on a write-available, read-correct architecture: writes are structurally simple, irrevocable, and forward-only (maximizing availability), while reads absorb all deferred correctness work (reconciliation, lazy computation, conflict resolution), with structural enforcement and selective pre-computation preventing the read-path cost from becoming unsustainable. - Depends on: quality-and-performance-strategies-are-aligned, read-path-is-architectures-critical-surface ### complexity-increases-both-read-cost-and-read-risk [OUT] DERIVED As system distribution complexity increases, the read path becomes simultaneously more expensive (absorbing deferred consistency, lazy computation, and soft-delete interpretation costs) and more vulnerable (temporal correctness gaps and permissive safety enforcement compound at the same boundaries) — creating a correlation where the most burdened reads are also the least protected. - Depends on: read-cost-scales-with-system-complexity, safety-and-correctness-gaps-compound ### compounding-gaps-are-in-the-testing-blind-spot [OUT] DERIVED Safety and correctness weaknesses compound at temporal boundaries (TOCTOU, non-atomic checks), which are precisely the properties that the co-designed structural test infrastructure cannot verify — the most dangerous gaps are systematically outside the test surface. - Depends on: safety-and-correctness-gaps-compound, structural-correctness-and-testability-are-co-designed ### correctness-gaps-cluster-at-temporal-boundaries [OUT] DERIVED Both classes of correctness weakness — assumed-but-unenforced invariants (quorum overlap, payment balance checks) and temporal check gaps (payment double-spend race, notification rate-limit re-checks) — share a common pattern: conditions that must hold across a time interval but are verified only at a single point, creating windows where silent violations can occur under edge conditions the code structurally permits. - Depends on: assumed-invariants-are-unenforced, temporal-check-gaps-are-systematic-risk ### correctness-profile-is-structurally-split [OUT] DERIVED The codebase has a bifurcated correctness guarantee: structural properties (immutability, synchronized structures, state ratchets) are enforced by construction and verified deterministically, while temporal properties (atomicity, TOCTOU) are documented as known gaps and left unenforced — creating a predictable divide between what the code guarantees and what it merely aspires to. - Depends on: structural-correctness-and-testability-are-co-designed, temporal-correctness-gaps-are-known-and-accepted ### cost-shifting-is-fully-verifiable [OUT] DERIVED The architecture's cost shifting between write and read paths is both structurally safe and fully verifiable — the testing infrastructure covers the read path's growing responsibility as computation shifts toward it. - Depends on: structural-correctness-enables-safe-cost-shifting - Unless: read-path-responsibility-exceeds-verification ### critical-path-is-least-verified [OUT] DERIVED The read path bears maximum responsibility (deferred consistency, lazy computation, active repair, tombstone interpretation) and accumulates maximum risk (temporal correctness gaps, TOCTOU windows), yet the testing strategy is co-designed to verify structural properties that are already safe by construction — making the architecture's most critical surface its least verified. - Depends on: read-path-is-architectures-critical-surface, compounding-gaps-are-in-the-testing-blind-spot ### current-time-fallback-inconsistent [OUT] OBSERVATION Rate limiter defaults `current_time` to `time.time()` while chat system defaults to `0.0`, creating different behavior when the parameter is omitted. - Source: entries/2026/06/05/topic-plan-to-implementation-fidelity.md ### dedup-is-global-not-per-ad [OUT] OBSERVATION The `seen_events` dedup registry keys on `event_id` alone; the same event ID arriving for different `ad_id`s will be deduplicated. - Source: entries/2026/06/05/ad-click-event-aggregation-click_aggregator.md ### default-to-permissive-across-security-dimensions [OUT] DERIVED The codebase defaults to permissive behavior across independent security dimensions — authorization (S3 default-allow, GDrive owner bypass) and input validation (stock exchange accepts any order fields, proximity accepts any coordinates) — prioritizing availability and simplicity over defense-in-depth. - Depends on: access-control-defaults-favor-availability-over-security, callers-trusted-at-internal-boundaries ### design-coherence-bounded-by-enforceability [OUT] DERIVED The codebase's alignment between quality and performance strategies (structural correctness reinforcing efficient runtime behavior, verified through deterministic testing) forms a mutually supportive system for properties enforceable by construction. This coherence does not extend to temporal correctness, where gaps are documented and accepted rather than enforced — suggesting that design investment concentrates where structural guarantees are achievable. - Depends on: quality-and-performance-strategies-are-aligned, correctness-profile-is-structurally-split ### dmq-reused-by-stock-exchange [OUT] OBSERVATION The message queue is imported by `stock-exchange/test_exchange.py` as an event bus for order matching, demonstrating cross-module reuse across SDI implementations. - Source: entries/2026/06/05/distributed-message-queue-solution.md ### documented-gaps-manifest-as-implementation-risks [OUT] DERIVED Design reviews explicitly document TOCTOU and atomicity gaps as known divergences, and similar temporal check-gap patterns appear as systematic risks in the implementations (payment TOCTOU windows, notification rate-limit re-checks), suggesting the pedagogical approach may intentionally preserve documented gaps rather than preventing them. - Depends on: plan-review-documents-known-gaps, temporal-check-gaps-are-systematic-risk ### enforceability-boundary-adapts-through-write-shifting [STALE] DERIVED The design's enforceability boundary is not static: where the self-reinforcing structural correctness loop holds, selective write-shifting adjusts the read/write cost split to match access frequency, extending the effectively-enforced region for high-traffic paths by pre-computing at write time what would otherwise be deferred to the riskier read path. - Depends on: design-coherence-bounded-by-enforceability, read-burden-is-managed-through-selective-write-shifting - Stale reason: research: abandoned — The derivation commits a category error: write-shifting changes *when* computation occurs (read vs write path), not *what* is structurally enforceable. The enforceability boundary in ant-1 distinguishes structural from temporal correctness guarantees — a distinction orthogonal to computation timing. No softening can rescue a claim whose core mechanism (performance optimization expands correctness enforcement) conflates two independent dimensions. At depth 7 with a flagged ancestor, the chain is too far removed to repair. ### enforcement-boundary-and-testing-blind-spot-converge [OUT] DERIVED The architecture's structural enforcement boundary (where self-limiting correctness holds) and the testing strategy's blind spot (where temporal gaps compound) converge on the same dividing line — structural properties are both enforced by construction and verified by deterministic tests, while temporal properties are neither enforced nor testable, revealing a single coherent design boundary rather than two independent gaps. - Depends on: architecture-is-correctly-self-limiting, compounding-gaps-are-in-the-testing-blind-spot ### gap-containment-requires-module-independence [OUT] DERIVED Module isolation limits the blast radius of compounding safety and correctness gaps: because modules are standalone artifacts with module-local error boundaries, temporal-boundary risks (TOCTOU, atomicity) compound within a module but cannot cascade across modules — but only if module boundaries are truly independent with no cross-module dependencies. - Depends on: module-isolation-is-pedagogical-and-architectural, safety-and-correctness-gaps-compound - Unless: dmq-reused-by-stock-exchange ### growth-does-not-increase-maintenance-burden [OUT] DERIVED The architecture's monotonically expanding verified state does not create a growing maintenance burden: self-reinforcing correctness means new state inherits verification from structural construction rather than requiring runtime checks, coordination-free scaling means adding state requires no coordination overhead, and robust cost allocation means read/write cost ratios remain stable as state grows — all structural properties of the architectural trinity. - Depends on: architectural-trinity-of-correctness-scaling-and-cost, monotonically-expanding-verified-state - Unless: assumed-invariants-are-unenforced ### hotel-cancel-no-underflow-guard [OUT] OBSERVATION `cancel()` decrements `booked` without checking for `booked >= 0`, so a double-cancel bug (if the status check were bypassed) could produce negative inventory counts. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### hotel-seasonal-pricing-first-match [OUT] OBSERVATION If seasonal pricing date ranges overlap, the first appended rule wins due to a `break` after the first match in `_get_price`. - Source: entries/2026/06/05/hotel-reservation-system-hotel_reservation.md ### irreversibility-is-the-simplicity-mechanism [STALE] DERIVED By eliminating reversal from the design vocabulary entirely (all deletes are additive, all state changes are forward-only, all finalization is permanent), the codebase removes an entire complexity class — undo, compensation, rollback, conflict-from-regression — achieving both correctness and simplicity through the same irreversibility constraint rather than trading one for the other. - Depends on: no-operation-is-truly-reversible, correctness-and-simplicity-share-the-same-mechanism - Stale reason: research: abandoned — The derivation commits a substitution fallacy: antecedent 2 identifies structural reuse as the mechanism unifying correctness and simplicity, but the conclusion swaps in irreversibility as that mechanism. This isn't an overstatement fixable by softening — the two antecedents establish unrelated facts (irreversibility exists; structural reuse unifies correctness+simplicity) and the conclusion incorrectly attributes one's role to the other. Nor is it a missing-link problem: even with an additional antecedent, ant 2 about structural reuse would remain a non-sequitur in a chain about irreversibility. ### irreversibility-produces-both-availability-and-simplicity [OUT] DERIVED Irreversibility is the shared root of two seemingly independent architectural properties: write availability (irrevocable writes need no rollback mechanism, undo log, or coordination overhead, making them inherently fast and failure-tolerant) and design simplicity (eliminating reversal from the vocabulary removes entire categories of state transitions, failure modes, and test scenarios), with the read path absorbing the cost of both. - Depends on: codebase-architecture-is-write-available-read-correct, irreversibility-is-the-simplicity-mechanism ### irreversibility-unifies-simplicity-ordering-and-correctness [OUT] DERIVED Temporal irreversibility functions as a unifying architectural primitive in this codebase, yielding at least two properties from a single constraint: simplicity (eliminating reversal removes an entire complexity class including undo, compensation, and rollback) and ordering (forward-only processing and monotonic progression are manifestations of the same directional constraint). Because irreversibility simultaneously addresses correctness and simplicity rather than trading one for the other, forward-only design represents one of the codebase's most economical architectural commitments. - Depends on: irreversibility-is-the-simplicity-mechanism, forward-only-and-monotonicity-are-a-single-constraint ### kv-quorum-consistency-assumed-not-enforced [OUT] DERIVED The KV store's consistency model depends on W+R>N quorum overlap but never validates the constraint, and hinted handoff writes bypass quorum entirely — consistency is a caller convention, not a system guarantee. - Depends on: kv-store-quorum-overlap-not-enforced, kv-hinted-handoff-not-counted-in-quorum ### kv-store-quorum-overlap-not-enforced [OUT] OBSERVATION The key-value store's W+R>N read-write overlap guarantee is assumed by callers but never validated in code. - Source: entries/2026/06/05/topic-consistency-models.md ### module-autonomy-enables-per-use-case-cost-optimization [OUT] DERIVED Module autonomy is the structural precondition for per-use-case cost optimization: because each module independently chooses its error conventions, eviction timing, and safety boundaries, it can also independently select the optimal write-read cost allocation for its specific access pattern — autocomplete and leaderboard pay at write time for read-heavy workloads, while payment and URL shortener defer to reads for write-heavy or low-frequency paths — without cross-cutting constraints imposing a uniform cost model. - Depends on: module-autonomy-spans-conventions-and-safety, write-cost-allocation-matches-access-pattern ### module-autonomy-spans-conventions-and-safety [OUT] DERIVED Module autonomy extends beyond implementation to encompass both operational conventions (error signaling varies by module, eviction timing has no codebase standard) and safety enforcement (error boundaries are module-local, access control defaults favor permissiveness), meaning there are no cross-cutting architectural constraints — each module is entirely self-governing in how it handles errors, manages resources, and enforces security. - Depends on: operational-conventions-are-module-scoped, safety-is-local-and-permissive ### monotonically-expanding-verified-state [STALE] DERIVED The architecture achieves permanently accumulating verified state: per-module self-reinforcing correctness composes with coordination-free scaling, and unconditional state monotonicity ensures no operation can reduce accumulated correctness guarantees — each module's verified properties persist and grow as the system scales, never regressing. - Depends on: self-reinforcing-correctness-composes-with-coordination-free-scaling, state-growth-is-unconditionally-monotonic - Stale reason: research: abandoned — Category error is structural, not a matter of degree: 'state lattice only grows' is a property of the data domain, while 'correctness never regresses' is a property of the semantic/verification domain. No softening of wording bridges this gap — you can monotonically append state that violates every invariant. A bridge premise like 'all state transitions preserve correctness' would need to exist, but that would be an extremely strong claim about the system that is unlikely to be justified in the network, and even if found, the depth-10 chain would still be making an unsupported universal ('no operation can reduce correctness'). The insight is too far removed from what the antecedents actually establish. ### nearby-friends-update-location-skips-grid-filtering [OUT] OBSERVATION `update_location` iterates all friends and computes haversine for each (O(friends)), while `get_nearby_friends` uses the grid index to narrow candidates before distance checks - Source: entries/2026/06/05/nearby-friends-nearby_friends.md ### nearby-friends-visibility-scales [STALE] DERIVED Nearby-friends correctly enforces bidirectional visibility with staleness rejection on both notification and query paths, but `update_location` iterates all friends with haversine for each (O(friends)) rather than using the spatial grid that `get_nearby_friends` uses — meaning notification throughput degrades linearly with social graph density while query performance does not. - Depends on: nearby-friends-bidirectional-visibility, nearby-friends-staleness-enforced-on-both-paths - Unless: nearby-friends-update-location-skips-grid-filtering - Stale reason: research: abandoned — The belief has a fundamental structural contradiction: its unless clause requires the grid-skipping fact to be OUT (disbelieved), but the claim text asserts that exact grid-skipping behavior as true. This means the belief is only IN when its own core claim is unsupported, and is OUT when its claim is actually true. This isn't a missing antecedent or overstated wording — it's an inverted logical structure that cannot be fixed by linking or softening. The belief needs to be reconstructed from scratch with correct dependency direction. ### no-divergence-annotations [OUT] OBSERVATION The rate limiter, payment system, and chat system contain zero TODO/FIXME/HACK comments; deviations from plans are undocumented in the code itself. - Source: entries/2026/06/05/topic-plan-to-implementation-fidelity.md ### notif-group-key-unused [OUT] OBSERVATION `_pending_groups` dict and `_group_window` field are initialized in `NotificationService.__init__` but never used — appears to be a planned notification batching/digest feature that was never implemented - Source: entries/2026/06/05/notification-system-notification_system.md ### payment-balance-check-not-atomic [OUT] OBSERVATION `process_payment` checks balance before processing but the check and ledger write are not atomic — a race condition under concurrency that real systems solve with optimistic locking or serializable transactions - Source: entries/2026/06/05/payment-system-payment_system.md ### payment-overdraft-not-atomic [OUT] OBSERVATION The overdraft check in `process_payment` reads balance and then processes without atomicity — a TOCTOU race in any concurrent context. - Source: entries/2026/06/05/topic-consistency-models.md ### payment-toctou-double-jeopardy [STALE] DERIVED The payment system has two independent TOCTOU windows in the same code path: the balance sufficiency check and the overdraft guard are both non-atomic, meaning concurrent payments can independently pass both validations. - Depends on: payment-balance-check-not-atomic, payment-overdraft-not-atomic - Stale reason: research: abandoned — The two antecedents describe the same single non-atomic balance check from different angles, not two independent TOCTOU windows. The core claim of 'two independent TOCTOU windows' is factually wrong — there is only one vulnerability described twice. Softening would require changing the claim so fundamentally (from 'two independent windows compound' to 'one window exists') that it would just duplicate either antecedent. No linking can fix this since the problem is redundant antecedents, not a missing one. ### proximity-no-coordinate-validation [OUT] OBSERVATION Neither GeohashIndex nor Quadtree validates input coordinates; latitude outside [-90, 90] silently produces garbage geohashes, and Quadtree.insert silently returns False for out-of-bounds points - Source: entries/2026/06/05/proximity-service-proximity_service.md ### read-burden-is-managed-through-selective-write-shifting [OUT] DERIVED The read path's growing cost and risk as system complexity increases is managed by selectively shifting work to writes for high-frequency access paths — eager cache rebuilds, write-time index maintenance — concentrating write-time optimization exactly where the read-heavy default model creates the most pressure rather than applying a blanket strategy. - Depends on: complexity-increases-both-read-cost-and-read-risk, cost-model-adapts-to-access-frequency ### read-correctness-is-structural-not-temporal [OUT] DERIVED The write-available, read-correct architecture achieves its read-correctness guarantee only for structural properties (immutable values arrive intact, synchronized structures reconcile deterministically); temporal correctness on the read path — where TOCTOU gaps and non-atomic checks are most consequential because reads must converge divergent state — remains an accepted rather than enforced property. - Depends on: codebase-architecture-is-write-available-read-correct, correctness-profile-is-structurally-split ### read-path-is-architectures-critical-surface [OUT] DERIVED The codebase's core contract — irrevocable writes with reconciling reads — places the read path under significant responsibility, and temporal correctness gaps (documented and accepted limitations) are likely to concentrate where reads must reconcile divergent state, since the forward-only constraint prevents reads from requesting write corrections. - Depends on: writes-commit-irrevocably-reads-reconcile, temporal-correctness-gaps-are-known-and-accepted ### safety-and-correctness-gaps-compound [OUT] DERIVED Correctness weaknesses cluster at temporal boundaries (TOCTOU, non-atomic checks) while safety enforcement is local and permissive (per-module error contracts, default-allow access control) — the most temporally sensitive code paths operate under the least standardized safety nets, creating compounding rather than independent risk. - Depends on: safety-is-local-and-permissive, correctness-gaps-cluster-at-temporal-boundaries ### safety-is-local-and-permissive [OUT] DERIVED Safety enforcement is both locally scoped (error contracts vary by module with no cross-cutting convention) and default-permissive (access control favors availability over restriction), producing a system where each module is individually lenient and no cross-cutting safety net catches errors that escape module boundaries. - Depends on: error-boundaries-are-module-local, default-to-permissive-across-security-dimensions ### security-permissiveness-spans-policy-and-data-boundaries [OUT] DERIVED Security permissiveness is systematic across two independent dimensions: policy enforcement (default-allow access control, trusted internal callers, no input validation) and data isolation (BCC recipients stored alongside visible recipients, presigned URL secrets shared across instances), creating a consistent availability-over-security bias that compounds — permissive policies let requests through, and weak data isolation lets those requests see more than intended. - Depends on: data-isolation-gaps-parallel-access-control-gaps, default-to-permissive-across-security-dimensions ### stock-exchange-no-input-validation [OUT] OBSERVATION The matching engine performs no validation on order fields (quantity, price, side); callers are trusted to provide valid inputs. - Source: entries/2026/06/05/stock-exchange-solution.md ### sustainable-architecture-quality-under-enforcement [OUT] DERIVED The architecture supports sustainable quality through two composing properties: domain-adapted specialization operates below universal invariant enforcement, so adding new specializations cannot compromise structural guarantees; and monotonically expanding verified state inherits verification from construction rather than requiring runtime checks, so growth does not proportionally increase maintenance burden. Together these properties suggest quality can be maintained — and potentially improved — as the system grows, provided structural invariants remain enforced. - Depends on: domain-excellence-composes-with-universal-invariant-enforcement, growth-does-not-increase-maintenance-burden - Unless: assumed-invariants-are-unenforced ### temporal-check-gaps-are-systematic-risk [OUT] DERIVED The gap between checking a condition and acting on it is a recurring design concern: the payment system has two independent TOCTOU windows in the same code path, while the notification system defensively re-checks rate limits at both send and process time — demonstrating that temporal check gaps require explicit architectural mitigation rather than assuming atomicity. - Depends on: payment-toctou-double-jeopardy, notification-defensive-double-rate-check ### temporal-correctness-gaps-are-known-and-accepted [OUT] DERIVED Design reviews explicitly document temporal boundary risks (TOCTOU, atomicity), these same patterns appear as systematic implementation weaknesses clustering at check-act boundaries, and the implementations ship without fixing them — indicating the codebase treats temporal correctness gaps as documented, accepted limitations rather than bugs to resolve. - Depends on: documented-gaps-manifest-as-implementation-risks, correctness-gaps-cluster-at-temporal-boundaries ### tested-properties-are-already-safe-by-construction [OUT] DERIVED The codebase's deterministic test infrastructure validates structural correctness properties (immutability, synchronized structures, state ratchets) that are already guaranteed by construction, while the compounding safety-correctness gaps at temporal boundaries — where actual production risks concentrate — fall outside the deterministic testing regime, creating an inverse relationship between test coverage confidence and residual risk. - Depends on: structural-correctness-and-testability-are-co-designed, safety-and-correctness-gaps-compound ### testing-and-construction-form-a-closed-correctness-loop [OUT] DERIVED The codebase's deterministic test infrastructure validates exactly the properties that structural construction already guarantees (immutability, synchronized structures, state ratchets), while the performance strategy (write-time caching, stdlib-only hermetic modules) ensures these constructions remain testable — creating a closed loop where correctness, testability, and performance are mutually reinforcing but collectively unable to reach temporal properties outside the loop. - Depends on: tested-properties-are-already-safe-by-construction, quality-and-performance-strategies-are-aligned ### verification-gap-is-precisely-at-the-write-read-boundary [OUT] DERIVED The architecture's verification coverage is inversely correlated with responsibility: write-path properties generate their own verification through structural construction that the test infrastructure validates, while the read path — bearing maximum responsibility for deferred consistency, lazy computation, and active repair — sits precisely in the testing blind spot, creating an exact correspondence between verification absence and correctness burden. - Depends on: write-available-architecture-is-self-verifying, critical-path-is-least-verified ### verify-integrity-ignores-transfers [OUT] OBSERVATION `verify_integrity` sums only `deposit` and `withdrawal` amounts against total balances, because `transfer_in`/`transfer_out` pairs are zero-sum and cancel out. - Source: entries/2026/06/05/digital-wallet-wallet.md ### wallet-creation-silently-overwrites [OUT] OBSERVATION `create_wallet` does not check for an existing `wallet_id`; calling it twice with the same ID replaces the wallet and loses the original balance. - Source: entries/2026/06/05/digital-wallet-wallet.md ### write-available-architecture-is-self-verifying [OUT] DERIVED The write-available, read-correct architecture generates its own verification: the structural properties that emerge from write-availability and read-correctness (immutability, synchronization, state ratchets) are exactly the properties that the closed testing-construction loop validates, making the architecture self-verifying within its structural domain. - Depends on: codebase-architecture-is-write-available-read-correct, testing-and-construction-form-a-closed-correctness-loop ### write-shifting-extends-the-irreversibility-boundary [OUT] DERIVED Write-shifting works as the architecture's self-improvement mechanism specifically because it moves computation from the reconciling read path (where guarantees are temporal and hard to enforce) to the irrevocable write path (where guarantees are structural and self-enforcing), extending the irreversibility-based simplicity and enforceability boundary to cover properties that would otherwise require runtime validation on reads. - Depends on: enforceability-boundary-adapts-through-write-shifting, irreversibility-is-the-simplicity-mechanism