Document distributor notification behavior

docs/internal/distributor-adapter.md

@@ -0,0 +1,106 @@
+# Distributor Adapter Internals
+
+This document describes the distributor upload adapter in
+`internal/adapters/distributor`.
+
+## Purpose
+
+The adapter submits generated weatherreporter Markdown reports to a configured
+distributor HTTP upload endpoint. It isolates distributor package types,
+token-env lookup, upload client construction, source-bundle file mapping,
+timeout handling, and upload error wrapping from app orchestration.
+
+## Inputs And Outputs
+
+Inputs:
+
+- distributor endpoint URL
+- token environment variable name
+- upload timeout
+- bundle ID
+- idempotency key
+- source Markdown report path
+- bundle-relative Markdown path
+- context for cancellation
+
+Outputs:
+
+- accepted distributor run ID
+- accepted distributor status
+- weatherreporter-owned idempotency conflict error when applicable
+
+## Boundaries
+
+`internal/adapters/distributor` is the only weatherreporter package that imports
+`gitea.maximumdirect.net/eric/distributor/pkg/upload` or
+`gitea.maximumdirect.net/eric/distributor/pkg/bundle`.
+
+The app layer passes weatherreporter-owned request values to the adapter. The
+adapter does not choose report types, render templates, select output copies,
+configure destinations, wait for downstream publication, transform Markdown, or
+persist notification state.
+
+Full upstream distributor package and HTTP contract details stay under
+`docs/integrations/distributor/`.
+
+## Config Fields Used
+
+The adapter is built from `notify.distributor` config:
+
+- `endpoint`
+- `token_env`
+- `timeout`
+
+The app layer renders bundle ID, idempotency key, and bundle path from:
+
+- `bundle_id_template`
+- `idempotency_key_template`
+- `report_path_template`
+
+The token value is read from the environment variable named by `token_env`
+after config loading and `secrets.directory` processing.
+
+## Upload Behavior
+
+The adapter calls distributor `UploadFiles` with exactly one file:
+
+- source path: the managed Markdown report path selected by app orchestration
+- bundle path: the rendered bundle-relative report path
+
+The adapter creates a distributor upload client with the configured endpoint,
+bearer token, and timeout-backed HTTP client. It also wraps the upload context
+with the configured timeout when the timeout is greater than zero.
+
+## Failure Behavior
+
+The adapter validates required endpoint, token env name, token value, bundle ID,
+idempotency key, source path, bundle path, and upload client inputs before
+uploading.
+
+Upload failures include endpoint, bundle ID, idempotency key, source path, and
+bundle path context. Token values are redacted from adapter errors.
+
+Distributor idempotency conflicts are exposed as a weatherreporter-owned
+`IdempotencyConflictError`, so callers do not depend on upstream distributor
+types.
+
+## Tests
+
+Inspect:
+
+- `internal/adapters/distributor/client_test.go`
+- `internal/app/app_test.go`
+- `internal/cli/root_test.go`
+
+Adapter tests use a fake upload client factory and do not require a live
+distributor service.
+
+## Invariants
+
+- Distributor package types do not leak outside the adapter.
+- Only the managed Markdown report is uploaded.
+- The adapter never scans the workspace.
+- Token values are not included in errors, CLI output, metadata, docs, or
+  examples.
+- Destination routing and Markdown-to-HTML transformation belong to
+  distributor, not weatherreporter.