Reconcile internal implementation guides

docs/internal/collect.md

@@ -1,59 +1,36 @@
 # Collection Internals
 
-`internal/collect` is the application-facing boundary for collecting the
+`internal/collect` is the small application-facing boundary that obtains one
 normalized Weather API bundle. The external HTTP contract belongs in the
-[Weather API integration guide](../integrations/weatherapi.md); normalized data
-semantics belong in [weather-data internals](weather-data.md).
+[Weather API integration guide](../integrations/weatherapi.md); normalized
+source values belong in [weather-data internals](weather-data.md).
 
 ## Contract
 
-`Run` accepts a `context.Context` and a `Request` containing effective
-`config.Config`. It constructs the Weather API adapter from that configuration,
-calls `FetchBundle`, and returns `Result{Bundle: *weatherdata.Bundle}`.
+`Run` receives a context and effective configuration in `Request`. It creates
+the Weather API adapter, calls `FetchBundle`, and returns the adapter's
+normalized bundle in `Result`. Adapter construction errors are wrapped as
+weather-collection setup errors and fetch errors as bundle-collection errors.
 
-The adapter's successful readiness request for current conditions is reused as
-that normalized source; collection does not trigger a second identical current
-conditions request.
+The package neither chooses reports nor derives facts, builds modules, invokes
+Promptkit, writes files, or sends notifications. Request scheduling, endpoint
+retrieval, response limits, and source-level warnings belong to the Weather
+API adapter and its integration contract.
 
-After readiness succeeds, the adapter obtains the other independent source
-responses concurrently. It merges their normalized results in the established
-source order, so provenance, warnings, and source-local failures remain
-deterministic. Cancellation remains authoritative for every in-flight request.
+## Application Use
 
-The package wraps adapter construction failures, including an invalid Weather
-API base URL, as weather-collection setup errors and fetch failures as
-bundle-collection errors. It does not retry, persist, select reports, derive
-facts, build modules, invoke Promptkit, or notify Distributor.
+`internal/app` owns the `Collector` interface used by report workflows and
+tests. Its default implementation delegates to `collect.Run`; callers may
+substitute a collector at that boundary. Application orchestration owns
+collection timing, reuse across a workflow, and the handling of nil collection
+results. See [app orchestration internals](app-orchestration.md) for that
+flow.
 
-Fetch failures retain Weather API endpoint context but do not project upstream
-response bodies into application-facing errors. Oversized response bodies fail
-collection before source decoding.
+## Verification
 
-The required hourly product must contain one or more periods with usable time
-bounds. An invalid hourly product fails collection before derivation begins.
+Focused package tests cover a successful fetch and wrapping failures from
+adapter construction and bundle retrieval:
 
-## Application Composition
-
-`internal/app` owns the narrow `Collector` interface used by workflow tests;
-the production implementation delegates to `collect.Run`. Generation, batch
-execution, and explicit bundle fetching all use this boundary. Application
-orchestration rejects a nil collector result or a nil bundle before report work
-can continue.
-
-Single-report generation and a batch each collect once. A batch passes the same
-normalized collection to planning and to every report it generates. Collection
-failure prevents later workflow work for that request.
-
-## Boundaries And Invariants
-
-Collection owns adapter creation and retrieval of one normalized bundle. It
-must not make report, period, batch, prompt, module, filesystem, or notification
-decisions.
-
-- App-facing Weather API collection always passes through this package.
-- The returned value is normalized source data, not facts or prompt input.
-- Context cancellation is passed to the Weather API adapter.
-- Errors retain whether setup or fetching failed.
-
-Focused tests are in `internal/collect/collect_test.go`; orchestration use is
-also covered by `internal/app/app_test.go`.
+```sh
+go test ./internal/collect
+```