@widnyana/design-thinking 0.0.1

package/references/effect-ts.md

@@ -0,0 +1,156 @@
+> **Source**: Design Thinking by [r17x](https://github.com/r17x) —
+> https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a
+> Bundled verbatim as the original Effect-TS instantiation of the method.
+> The generalized, stack-agnostic version lives in [method.md](method.md);
+> the notation spec lives in [protocol.md](protocol.md).
+
+# Design Thinking
+
+```
+X → Graph → Effect<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ what each node needs     (§5)
+│              │   │  └──── where the graph breaks   (§4)
+│              │   └─────── what flows through nodes  (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem: what you’re trying to build
+
+§1  Shapes       the nouns: records, IDs, variants, errors
+§2  A            happy path as call graph
+§3  Cardinality  one-shot (Effect) or many (Stream)
+§4  E            break points: retry, escape, die
+§5  R            dependencies: compile-time proof
+§6  Boundary     Schema: unknown → trusted at edges
+§7  Behavior     .pipe() wraps without changing the graph
+§8  Scope        acquire/release tied to lifecycle
+§9  Test         swap R, same graph shape
+§10 Code         gen body = A, .pipe() = E
+```
+
+Read the problem. Draw the data flow as a call graph. Write code that IS the graph. If the code doesn't match the graph, something is wrong.
+
+## 1. Name the shapes
+
+What are the things? Before drawing a graph, define the domain language.
+
+- **Records** -- entities that flow through nodes. A User, a Product, an Order.
+- **IDs** -- identity of things. Branded, constrained, never a bare string.
+- **Variants** -- internal state transitions. A step is Continue or Finished. A status is Pending, Active, or Cancelled.
+- **Errors** -- named failure modes. Not strings. Tagged, structured, carrying context.
+
+These are the nouns. The graph is the verbs. You cannot draw the graph until you know what flows through it.
+
+## 2. Think A first
+
+Map the happy path as a call graph before writing any code.
+
+```
+F1(A) -> F2(A) -> F3(A)
+```
+
+What is the success data flow? What goes in, what comes out, what transforms happen in between? This graph IS your program structure. Draw it first. The code follows.
+
+## 3. One or many?
+
+Is each node one-shot or a flow?
+
+- **One value** -- the node runs, produces A, done. This is Effect.
+- **Many values over time** -- the node emits A repeatedly. Events, subscriptions, paginated pulls. This is Stream.
+- **Time-bounded** -- the result is valid for a window. Cache it. Deduplicate concurrent lookups.
+
+Same three channels (A, E, R) in all cases. Different cardinality. Mark it on the graph so the code matches.
+
+## 4. Think E second
+
+Mark where the graph can break. Each break point is one of three things:
+
+- **Retry** -- transient failure, try again. Network timeout, rate limit, connection reset.
+- **Escape Hatch** -- recoverable, return an alternative. Fallback value, cached result, default.
+- **Die** -- defect, invariant violation, programmer bug. NOT a domain error. Something is fundamentally wrong.
+
+Errors are VALUES in the E channel until you truly cannot handle them. They flow through the graph like data. You decide at each node: retry, escape, or let it propagate. Only `die` when the program's assumptions are violated.
+
+## 5. Think R third
+
+Mark what each node in the graph needs to exist. "We cannot do X if we don't have Y."
+
+R is compile-time proof that dependencies are satisfied. Every node declares what it requires -- a database connection, a config value, an HTTP client. R shrinks as you provide layers. When R is empty (`never`), the program can run. If R is not empty, the compiler tells you exactly what's missing.
+
+## 6. Trust at boundary
+
+Where does untrusted data enter the graph? HTTP requests, file reads, environment variables, user input, third-party API responses.
+
+Schema converts `unknown -> trusted` at the edges. One definition = type + validator + transformer. Define it once, use it everywhere.
+
+Trust nothing at the boundary. Trust everything inside. The boundary is the only place you parse. After that, the types guarantee shape.
+
+## 7. Layer behavior
+
+What cross-cutting concerns wrap nodes? Retry policies, timeouts, logging, tracing, caching.
+
+These wrap via `.pipe()` WITHOUT changing the core graph. The happy path stays clean -- you can read it without wading through retry logic and timeout configuration. Behavior is composed orthogonally. The graph says WHAT happens. The layers say HOW it behaves under pressure.
+
+## 8. Scope resources
+
+What nodes acquire resources? Database connections, file handles, WebSocket connections, child processes.
+
+Acquire/release is a type guarantee. If a node opens a connection, scope ensures it closes -- even on error, even on interrupt. Cleanup is structural, not a TODO comment you hope someone remembers.
+
+## 9. Swap R to prove it
+
+The call graph doesn't change between production and tests. Only R changes.
+
+Same graph shape. Same A flowing through. Same E possible. Different layer behind R. If the graph can't run with a test R, the design has hidden dependencies. If you have to mock the world to test one node, the node is doing too much.
+
+This is the payoff of separating A, E, and R -- you prove the graph correct by swapping what's behind R.
+
+## 10. gen is A, pipe is E
+
+The separation of A (step 2) and E (step 4) maps directly to Effect code structure:
+
+- **`Effect.gen` body** -- the happy path. Every `yield*` is an A flowing through the graph. No error handling inside.
+- **`.pipe()` after gen** -- the complete E enumeration. Before writing the pipe, read the actual E type of every yielded effect. The pipe catches, retries, or transforms every E that the gen body can produce.
+
+This is not a stylistic preference. If error handling lives inside the gen body, the A path and E path are tangled -- you cannot read the happy path without wading through catches and retries. The gen body IS the call graph from step 2. The pipe IS the error annotation from step 4.
+
+### E scoping at graph layers
+
+Each layer in the call graph scopes its own E before passing to the next layer:
+
+```
+Services  →  Auth  →  Handlers
+E=SqlError    E=DatabaseError    E=AuthError    E=RPC errors
+  ↓ scope       ↓ scope            ↓ scope
+DatabaseError  AuthError          RPC errors
+```
+
+A service catches SqlError and produces DatabaseError. Auth catches DatabaseError and produces AuthError. The handler catches AuthError and produces the RPC-declared error. Each layer's pipe is a complete enumeration of what IT received -- not what originated three layers down. Consumers never see implementation errors from deeper layers.
+
+### Divergent strategies
+
+When two effects in the same gen body need different E handling -- one should fail hard, the other should fall back gracefully -- that is a **divergent strategy**. Handle each effect's E inline within the gen body, because the outer pipe cannot distinguish which yield produced which error.
+
+This is the ONE exception to "no error handling in gen." It exists because the graph has a fork: two branches with different failure semantics sharing a node. Mark it clearly -- it should be rare.
+
+---
+
+## The Pipeline
+
+```
+PROBLEM
+  -> "What are the shapes?"                       -> define the domain language
+  -> "What is the happy path?"                    -> draw the call graph (A)
+  -> "Is each node one-shot or a flow?"           -> mark cardinality
+  -> "Where can it break?"                        -> annotate errors on the graph (E)
+  -> "What does each node need?"                  -> annotate requirements on the graph (R)
+  -> "Where does untrusted data enter?"           -> Schema at graph boundaries
+  -> "What wraps nodes without changing them?"    -> pipe behavior orthogonally
+  -> "What resources need cleanup?"               -> scope lifecycle
+  -> "Can I swap R and the graph still works?"    -> verify with test layers
+  -> "Does my code separate A from E structurally?" -> gen body = A, pipe = E
+  -> CODE                                         -> the code IS the graph
+```
+
+**If the code doesn't match the call graph, the implementation is wrong.**

package/references/method.md

@@ -0,0 +1,229 @@
+# Design Thinking — The Method
+
+A stack-agnostic design methodology. Read the problem. Draw the data flow as a
+call graph (the **Design Graph**). Write code that IS the graph. If the code
+doesn't match the graph, something is wrong.
+
+The method is language-neutral. Where it says "Effect", "gen", or "pipe" in the
+Effect-TS appendix (`effect-ts.md`), substitute your stack's equivalent: Result
+types, exceptions at layer joins, middleware, RAII, constructor injection —
+whatever your language provides. The discipline never changes, only the vocabulary.
+
+Render every result in [Graph Protocol](protocol.md) format.
+
+```
+X → DesignGraph<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ what each node needs     (§5)
+│              │   │  └──── where the graph breaks   (§4)
+│              │   └─────── what flows through nodes  (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem: what you're trying to build
+
+§1  Shapes       the nouns: records, IDs, variants, errors
+§2  A            happy path as call graph
+§3  Cardinality  one-shot (1), many (N), or time-bounded (T)
+§4  E            break points: retry, escape, die
+§5  R            dependencies: compile-time or wiring-time proof
+§6  Boundary     parse: unknown → trusted at edges
+§7  Behavior     orthogonal layers wrap without changing the graph
+§8  Scope        acquire/release tied to lifecycle
+§9  Test         swap R, same graph shape
+§10 Structure    happy path = A, failure handling = E, never tangled
+```
+
+## 1. Name the shapes
+
+What are the things? Before drawing a graph, define the domain language.
+
+- **Records** — entities that flow through nodes. A User, a Product, an Order.
+- **IDs** — identity of things. Branded, constrained, never a bare string.
+- **Variants** — internal state transitions. A step is Continue or Finished.
+  A status is Pending, Active, or Cancelled.
+- **Errors** — named failure modes. Not strings. Structured, carrying context.
+
+These are the nouns. The graph is the verbs. You cannot draw the graph until
+you know what flows through it.
+
+→ *Protocol section: SHAPES.*
+
+## 2. Think A first
+
+Map the happy path as a call graph before writing any code.
+
+```
+F1(A) -> F2(A) -> F3(A)
+```
+
+What is the success data flow? What goes in, what comes out, what transforms
+happen in between? This graph IS your program structure. Draw it first. The
+code follows.
+
+→ *Protocol section: GRAPH (edges) + header tree (A).*
+
+## 3. One or many?
+
+Is each node one-shot or a flow?
+
+- **One value** — the node runs, produces A, done. `(1)`
+- **Many values over time** — the node emits A repeatedly: events,
+  subscriptions, paginated pulls, batches. `(N)`
+- **Time-bounded** — the result is valid for a window. Cache it. Deduplicate
+  concurrent lookups. `(T)`
+
+Same three channels (A, E, R) in all cases. Different cardinality. Mark it on
+the graph so the code matches.
+
+→ *Protocol section: CARDINALITY.*
+
+## 4. Think E second
+
+Mark where the graph can break. Each break point is one of three things:
+
+- **Retry** `⟳` — transient failure, try again. Network timeout, rate limit,
+  connection reset.
+- **Escape Hatch** `↯` — recoverable, return an alternative. Fallback value,
+  cached result, default, skip-and-continue.
+- **Die** `☠` — defect, invariant violation, programmer bug. NOT a domain
+  error. Something is fundamentally wrong.
+
+Failures are first-class values in the E channel until you truly cannot handle
+them. They flow through the graph like data — whether your language expresses
+that as Result types, checked exceptions, error returns, or a strict rule that
+exceptions only cross at layer joins. You decide at each node: retry, escape,
+or propagate. Only `die` when the program's assumptions are violated.
+
+→ *Protocol section: GRAPH (E annotations) + VERDICT.*
+
+## 5. Think R third
+
+Mark what each node in the graph needs to exist. "We cannot do X if we don't
+have Y."
+
+R is proof that dependencies are satisfied — at compile time (injected via
+constructors, generics, typeclasses, traits) or at wiring time (composition
+root, DI container, context object). Every node declares what it requires: a
+database connection, a config value, an HTTP client. R shrinks as you provide
+layers. When R is empty, the program can run. If R is not empty, the compiler
+or the wiring tells you exactly what's missing.
+
+→ *Protocol section: GRAPH (R annotations) + TEST LAYERS.*
+
+## 6. Trust at boundary
+
+Where does untrusted data enter the graph? HTTP requests, file reads,
+environment variables, user input, third-party API responses.
+
+Convert `unknown → trusted` at the edges — a schema, a parsing constructor, a
+validating factory, a DTO boundary. One definition = type + validator +
+transformer. Define it once, use it everywhere.
+
+Trust nothing at the boundary. Trust everything inside. The boundary is the
+only place you parse. After that, the types guarantee shape.
+
+→ *Protocol section: BOUNDARIES.*
+
+## 7. Layer behavior
+
+What cross-cutting concerns wrap nodes? Retry policies, timeouts, logging,
+tracing, caching.
+
+These wrap WITHOUT changing the core graph — middleware, decorators,
+higher-order functions, aspects. The happy path stays clean: you can read it
+without wading through retry logic and timeout configuration. Behavior is
+composed orthogonally. The graph says WHAT happens. The layers say HOW it
+behaves under pressure.
+
+→ *Protocol section: BEHAVIOR.*
+
+## 8. Scope resources
+
+What nodes acquire resources? Database connections, file handles, WebSocket
+connections, child processes, locks.
+
+Acquire/release must be structurally bound: RAII, `defer`, context managers,
+`try/finally` at the owning node — even on error, even on interrupt. Cleanup
+is structural, not a TODO comment you hope someone remembers.
+
+→ *Protocol section: SCOPE.*
+
+## 9. Swap R to prove it
+
+The call graph doesn't change between production and tests. Only R changes.
+
+Same graph shape. Same A flowing through. Same E possible. Different layer
+behind R. If the graph can't run with a test R, the design has hidden
+dependencies. If you have to mock the world to test one node, the node is
+doing too much.
+
+This is the payoff of separating A, E, and R — you prove the graph correct by
+swapping what's behind R.
+
+→ *Protocol section: TEST LAYERS.*
+
+## 10. Separate A from E structurally
+
+The separation of A (§2) and E (§4) maps directly onto code structure, in any
+language:
+
+- **The happy path body** — one readable place. Every call is an A flowing
+  through the graph. No error handling inside. (In Effect-TS: the `Effect.gen`
+  body. Elsewhere: the main function, the do-notation block, the straight-line
+  pipeline of calls.)
+- **The failure join points** — the complete E enumeration. Before writing
+  them, read the actual failure modes of every node on the happy path. The
+  join points catch, retry, or translate every E the happy path can produce.
+  (In Effect-TS: `.pipe()` after gen. Elsewhere: the middleware stack, the
+  Result chain, the try/catch at the layer boundary.)
+
+This is not a stylistic preference. If error handling lives inside the happy
+path body, the A path and E path are tangled — you cannot read the happy path
+without wading through catches and retries. The happy path body IS the call
+graph from §2. The join points ARE the error annotations from §4.
+
+### E scoping at graph layers
+
+Each layer scopes its own E before passing to the next layer. A service catches
+storage errors and produces a domain error. Auth catches domain errors and
+produces an access error. The handler catches access errors and produces the
+declared interface error. Each layer's handling is a complete enumeration of
+what IT received — not what originated three layers down. Consumers never see
+implementation errors from deeper layers. *(See protocol.md for the diagram.)*
+
+### Divergent strategies
+
+When two nodes in the same happy path need different failure handling — one
+should fail hard, the other should fall back gracefully — that is a
+**divergent strategy**. Handle each node's E inline within the happy path at
+the fork, because the outer join point cannot distinguish which node produced
+which error. This is the ONE exception to "no error handling in the happy
+path." It exists because the graph has a fork: two branches with different
+failure semantics sharing a node. Mark it clearly — it should be rare.
+
+---
+
+## The Pipeline
+
+```
+PROBLEM
+  -> "What are the shapes?"                       -> define the domain language
+  -> "What is the happy path?"                    -> draw the call graph (A)
+  -> "Is each node one-shot or a flow?"           -> mark cardinality
+  -> "Where can it break?"                        -> annotate errors on the graph (E)
+  -> "What does each node need?"                  -> annotate requirements on the graph (R)
+  -> "Where does untrusted data enter?"           -> parse at graph boundaries
+  -> "What wraps nodes without changing them?"    -> layer behavior orthogonally
+  -> "What resources need cleanup?"               -> scope lifecycle
+  -> "Can I swap R and the graph still works?"    -> verify with test layers
+  -> "Does my code separate A from E structurally?" -> happy path = A, joins = E
+  -> CODE                                         -> the code IS the graph
+```
+
+**If the code doesn't match the call graph, the implementation is wrong.**
+
+---
+
+*For the original Effect-TS instantiation of this method, see
+[effect-ts.md](effect-ts.md).*

package/references/protocol.md

@@ -0,0 +1,228 @@
+# Graph Protocol
+
+The notation spec for **Design Graphs**. A Design Graph is the annotated call graph
+of a concrete problem: nodes are functions, edges are data flow, and every node
+carries annotations for data (A), cardinality, failure (E), and requirements (R).
+
+The Protocol is stack-agnostic. A graph written for Go, Rust, Python, TypeScript,
+SQL, or a spreadsheet renders identically. Only the vocabulary inside the
+annotations changes (e.g. what "retry" means in your language).
+
+Every tool in this package (`/cg`, `/cg-plan`, `/cg-review`, `/cg-map`, and the
+`/dt` active mode) MUST emit output in the format below.
+
+---
+
+## Canonical output skeleton
+
+Sections appear in this fixed order. Omit a section only when it is genuinely
+empty for the problem at hand (say so: `SCOPE: none`), never to skip thinking.
+
+```
+PROBLEM: <one-line statement of what you're building or examining>
+
+X → DesignGraph<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ R: what each node needs      (§5)
+│              │   │  └──── E: where the graph breaks    (§4)
+│              │   └─────── A: what flows through nodes  (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem
+
+SHAPES:  <the nouns: records, IDs, variants, errors>
+
+GRAPH:
+  <ascii call graph, annotated inline>
+
+CARDINALITY: <node (1|N|T) list>
+BOUNDARIES:  <every edge crossing untrusted → trusted>
+BEHAVIOR:    <cross-cutting layers that wrap nodes>
+SCOPE:       <resources: acquire@… → release@…>
+TEST LAYERS: <the R that tests provide — same GRAPH, zero code change>
+VERDICT:     <code matches graph? what is missing/tangled?>
+```
+
+---
+
+## The header tree
+
+The header names the problem and anchors the three channels. `X` is your problem;
+everything after it is the graph you build.
+
+```
+X → DesignGraph<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ R: what each node needs      (§5)
+│              │   │  └──── E: where the graph breaks    (§4)
+│              │   └─────── A: what flows through nodes  (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem: what you're trying to build
+```
+
+---
+
+## Section rules
+
+### PROBLEM
+
+One line. The thing you're building or the question you're answering. If you
+cannot write it in one line, the problem is not understood — stop and refine.
+
+### SHAPES
+
+The domain nouns. Name them before drawing anything:
+
+- **Records** — entities that flow through nodes (User, Order, Config).
+- **IDs** — identity, never a bare primitive (UserId, Email).
+- **Variants** — internal state transitions (pending|active|cancelled).
+- **Errors** — named failure modes, structured, carrying context (not strings).
+
+Format: comma-separated list. These are the nouns; the graph is the verbs.
+
+### GRAPH
+
+ASCII call graph. Nodes are functions/steps; edges are data flow. Annotate
+**inline**, using the branch conventions from the header tree:
+
+```
+parse → Handler → Service → Repo
+│                      │        │
+│                      │        └─ R: DbConn · (N)
+│                      └─ E: timeout ⟳retry×3 → ↯escape(cached)
+└─ 🔒 HTTP body → trusted
+```
+
+Inline annotation grammar:
+
+| Annotation | Meaning | Example |
+|---|---|---|
+| `R: a, b` | what the node requires (§5) | `R: DbConn, Config` |
+| `E: <err> ⟳retry[×n] → ↯escape(alt)` | failure handling (§4) | `E: NetErr ⟳retry×3 → ↯escape(fallback)` |
+| `E: <err> ☠die` | defect, not domain error (§4) | `E: NullConfig ☠die` |
+| `🔒 x → y` | untrusted → trusted boundary (§6) | `🔒 JSON → Settings` |
+| `(1) (N) (T)` | cardinality (§3) | `(N)` = many over time |
+| `⛈ name` | behavior layer wrapping the node (§7) | `⛈logging wraps Service` |
+| `@scope` | resource bound to a scope (§8) | `DbConn @main` |
+
+### CARDINALITY
+
+One line listing each node's arity:
+
+- `(1)` — one-shot: runs once, produces one value.
+- `(N)` — many: emits values over time (stream, iterator, subscription, pages).
+- `(T)` — time-bounded: result valid for a window; cache it, dedupe concurrent lookups.
+
+Same three channels (A, E, R) in all cases. Different cardinality. The code must
+match: don't implement a `(N)` node as a one-shot.
+
+### BOUNDARIES
+
+Every place untrusted data enters the graph: HTTP requests, file reads, env
+vars, user input, third-party responses. The rule: **parse, don't validate** —
+convert `unknown → trusted` once, at the edge, then trust the types everywhere
+inside. One definition per shape = type + validator + transformer, reused
+everywhere.
+
+### BEHAVIOR
+
+Cross-cutting concerns that wrap nodes WITHOUT changing the core graph:
+retry policies, timeouts, logging, tracing, caching. Composed orthogonally
+(middleware, decorators, higher-order wrappers, aspects). The graph says WHAT
+happens; the layers say HOW it behaves under pressure. If removing logging
+forces you to edit business logic, behavior is not orthogonal.
+
+### SCOPE
+
+Resources that must be released: connections, file handles, sockets, child
+processes. Acquire/release must be structurally bound (RAII, `defer`, context
+managers, `try/finally`) — never convention or a TODO. Notation:
+
+```
+SCOPE: DbConn acquire@main → release@main · WS acquire@Handler → release@Handler
+```
+
+### TEST LAYERS
+
+The R that tests provide. The call graph does not change between production and
+tests — only R changes. Same graph, same A, same E, different layers behind R.
+If the graph can't run with a test R, the design has hidden dependencies. If
+you must mock the world to test one node, the node does too much.
+
+### VERDICT
+
+The structural check. Answer explicitly:
+
+- Is the happy path (A) readable on its own, free of failure handling?
+- Is every E the graph can produce handled at a defined join point?
+- Do per-layer E scopes translate errors (inner errors never leak through)?
+- Does the code match the graph? **If the code doesn't match the call graph,
+  the implementation is wrong.**
+
+---
+
+## E scoping at graph layers
+
+Each layer scopes its own E before passing to the next:
+
+```
+Services  →  Auth  →  Handlers
+E=SqlErr      E=DbErr      E=AuthErr      E=RPC errs
+  ↓ scope       ↓ scope      ↓ scope
+DbErr          AuthErr      RPC errs
+```
+
+A service catches `SqlErr` and produces `DbErr`. Auth catches `DbErr` and
+produces `AuthErr`. The handler catches `AuthErr` and produces the declared
+error. Each layer's handling enumerates what IT receives — never what originated
+three layers down. Consumers never see implementation errors from deeper layers.
+
+## Divergent strategies (the one exception)
+
+When two nodes in the same happy path need different failure semantics — one
+must fail hard, another must fall back gracefully — handle that node's E
+inline at the fork, because the outer layer cannot distinguish which node
+produced which error. Mark it clearly; it should be rare.
+
+---
+
+## Worked example (non-TS: Python CLI)
+
+```
+PROBLEM: sync a list of URLs to local files, resumable, with a status line
+
+X → DesignGraph<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ R: Http, Clock, Logger      (§5)
+│              │   │  └──── E: NetErr, DiskErr          (§4)
+│              │   └─────── A: (url, bytes), Status     (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem
+
+SHAPES:  Url, Target(path), Downloaded(url, bytes), Status(pending|done|failed), NetErr, DiskErr
+
+GRAPH:
+  load_state → plan → fetch … download → write → report
+  │                │              │                    │
+  │                │              ├─ E: NetErr ⟳retry×3(-backoff) → ↯escape(skip, mark failed)
+  │                │              └─ 🔒 raw bytes → Downloaded (size, content-type checked)
+  │                └─ R: StateFile · (1)
+  └─ 🔒 state file → trusted (schema-validated; corrupt → ↯escape(empty, warn))
+
+CARDINALITY: load_state (1) · plan (1) · fetch (N) · download (1) · write (1) · report (T)
+BOUNDARIES:  load_state 🔒 file → State · fetch 🔒 wire → Downloaded
+BEHAVIOR:    ⛈retry wraps fetch · ⛈rate-limit wraps fetch · ⛈progress wraps write
+SCOPE:       Http acquire@main → release@main · StateFile @main (context manager)
+TEST LAYERS: R = {Http: FakeHttp, Clock: FrozenClock, Logger: Silent} — same GRAPH, no stubs in nodes
+VERDICT:     happy path reads as the pipeline above; all NetErr handling lives at the
+             write/report join, not inside download; state corruption escapes at the edge.
+             Matches graph → implementation valid.
+```
+
+Note the stack vocabulary: `context manager` for scope, exceptions caught at
+layer joins for E, plain functions for nodes. Protocol unchanged.