docs: fix ops gaps and architecture.md accuracy (COW-1001 + COW-1002)

[lgahdl]

Grant Review Findings

[F14] Document remaining ops gaps — MINOR (docs/ops) (COW-1001)

Port discrepancy undocumented (pnpm dev → 42069, pnpm start → 3000, but docs only mention 42069); dev vs start restart behavior undocumented (ponder dev re-indexes from scratch on restart, ponder start resumes from checkpoint); default ordering: "multichain" behavior undocumented (one chain's backlog drains before the other gets cycles); ethGetLogsBlockRange per chain undocumented and unset (providers capping at 1000 blocks trigger retry storms); .env.example flag descriptions incomplete/stale.

[F21] Fix docs/architecture.md accuracy, hardcoded counts, and repeated owner-resolution sections — MINOR (docs accuracy/maintainability) (COW-1002)

Hardcoded counts ("Eight order types", "Five live-only block handlers") are doc-drift bait; data-flow diagram implies false sequential dependencies between independent event streams; handler section mixes concerns; owner-resolution details repeated across sections; candidateDiscreteOrder motivation under-explained (what it is, not why — a new maintainer must read 3 files to assemble the picture).

---

Summary

COW-1001 [F14] — Ops gaps:

• .env.example: remove stale C1 ContractPoller / C5 DeterministicCancellationSweeper names; add # escape-hatch / # prod tags per flag
• ponder.config.ts: add ethGetLogsBlockRange: 1000 per chain — prevents InvalidInputRpcError retry storms against providers with a 1k-block cap during backfill
• docs/api-reference.md: document that pnpm dev uses port 42069, pnpm start/Docker uses port 3000
• docs/deployment.md: new sections for pnpm dev vs pnpm start restart semantics, multichain ordering behavior, and RPC provider block-range limits table

COW-1002 [F21] — docs/architecture.md accuracy:

• Replace all hardcoded counts ("Eight order types", "Five live-only block handlers", C1–C5 shorthand) with references to source files as canonical lists
• Data-flow diagram redrawn as three independent parallel on-chain streams (ComposableCow, CoWShedFactory, GPv2Settlement) converging at the schema layer — not a sequential chain
• Block handler section updated to semantic handler names (OrderDiscoveryPoller, CandidateConfirmer, OrderStatusTracker, OwnerBackfill, CancellationWatcher)
• candidate_discrete_order: added "Why candidate orders?" motivational paragraph explaining the watch-tower posting gap and precompute-then-confirm pattern
• Order types section restructured as deterministic vs non-deterministic rather than a hardcoded count

Test plan

• pnpm typecheck — passes
• pnpm test — 19/19 passing
• Port 42069 (dev) / 3000 (prod) documented in api-reference.md
• ponder.config.ts has ethGetLogsBlockRange: 1000 on both chains
• No hardcoded counts remain in architecture.md

🤖 Generated with Claude Code

[linear-code]

COW-1001

COW-1002

[lgahdl]

The new data-flow diagram correctly reflects the three parallel event streams (ComposableCoW, CoWShedFactory, GPv2Settlement) and uses the new semantic handler names throughout — no C1–C5 references remain in docs/architecture.md. The docs/api-reference.md port correction and the candidate_discrete_order explanation are accurate.

One gap: the Debug / Performance Flags table in docs/deployment.md is not touched by this PR (or by #83), so it still names the old handler identifiers in three rows — C1 ContractPoller, C5 DeterministicCancellationSweeper, and "C1 and C5" in the MAX_GENERATORS_PER_BLOCK row. The rename landed in #83; one of these PRs should own updating that table. Currently neither does.

[lgahdl]

Documentation / CI review

docs/deployment.md — Debug/Performance Flags table still has old C1/C5 names.
Lines 33–35 of the current docs/deployment.md (which this PR does not touch) still reference C1 ContractPoller and C5 DeterministicCancellationSweeper. This PR targets COW-1001 [F14] ops gaps and is the right place to fix these stale entries. The three affected rows in the table should read OrderDiscoveryPoller and CancellationWatcher to match blockHandler.ts and ponder.config.ts.

docs/api-reference.md — one residual old name.
Line 129: the timestamp field matrix still says "Block timestamp at C1 discovery." Should be OrderDiscoveryPoller. This PR already touches api-reference.md (port documentation), so it is a natural addition.

.env.example — fully updated and clean. The new escape-hatch comments use the semantic handler names and add the # escape-hatch / # prod tags. No issues here.

ponder.config.ts — ethGetLogsBlockRange: 1000 added on both chains. Correct and documented.

docs/deployment.md new sections (pnpm dev vs start, multichain ordering, RPC block range) — accurate and complete. The port table, restart semantics, and provider limits table all look correct.

docs/architecture.md updates — thorough and accurate. The data-flow diagram rewrite and handler section updates correctly use the new semantic names. No stale C-number references remain in architecture.md.

Overall: Two items to fix before merge — update the three rows in the Debug/Performance Flags table in docs/deployment.md and the one C1 reference in docs/api-reference.md line 129.

[yvesfracari]

It seems to me that there is still something missing here:

• "How to tell if the indexer is caught up" doc
• Remove chain specific things from architecture

[lgahdl]

Addressed both points:

"How to tell if the indexer is caught up" — Added a "Checking If the Indexer Is Caught Up" section to docs/deployment.md explaining: GET /ready (binary: 200 = synced, 503 = still syncing) vs GET /api/sync-progress (per-chain percentage + isSynced flag). Includes a sample JSON response.

"Remove chain-specific things from architecture" — Removed the hardcoded chain IDs, block numbers, and contract addresses from docs/architecture.md. Replaced with: "Currently active chains, their start blocks, and contract addresses are defined in src/chains/. To add a chain, create a chain file there and register it in src/chains/index.ts/."