Document batch distributor uploads

docs/internal/distributor-adapter.md

@@ -6,10 +6,10 @@ This document describes the distributor upload adapter in
 ## 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, status polling, and upload error wrapping from app
-orchestration.
+distributor HTTP upload endpoint. It supports one or more file mappings per
+upload request. It isolates distributor package types, token-env lookup, upload
+client construction, source-bundle file mapping, timeout handling, status
+polling, and upload error wrapping from app orchestration.
 
 ## Inputs And Outputs
 
@@ -21,7 +21,7 @@ Inputs:
 - pipeline ID
 - bundle ID
 - idempotency key
-- source Markdown report path and bundle-relative path mappings
+- source Markdown report paths and bundle-relative path mappings
 - bundle created timestamp
 - context for cancellation
 
@@ -40,8 +40,9 @@ Outputs:
 
 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.
+decide whether an upload represents one report or a batch, 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/`.
@@ -54,14 +55,19 @@ The adapter is built from `notify.distributor` config:
 - `token_env`
 - `timeout`
 
-The app layer renders pipeline ID, bundle ID, idempotency key, and bundle paths
-from:
+The app layer renders single-report pipeline ID, bundle ID, idempotency key,
+and bundle paths from:
 
 - `pipeline_id_template`
 - `bundle_id_template`
 - `idempotency_key_template`
 - `report_path_templates`
 
+For batch uploads, the app layer renders pipeline ID, bundle ID, and
+idempotency key from `notify.distributor.batch.*`, renders
+`report_path_templates` once per included report, and passes the resulting
+multi-file request to this adapter.
+
 The token value is read from the environment variable named by `token_env`
 after config loading and `secrets.directory` processing.
 
@@ -70,9 +76,9 @@ after config loading and `secrets.directory` processing.
 The adapter calls distributor `UploadFiles` with one or more file mappings:
 
 - pipeline ID: the rendered distributor workflow selector
-- source path: the managed Markdown report path selected by app orchestration
-- bundle paths: rendered bundle-relative report paths
-- created: the report generation timestamp
+- source paths: managed Markdown report paths selected by app orchestration
+- bundle paths: rendered bundle-relative report paths for each source
+- created: the report or batch generation timestamp
 
 The adapter creates a distributor upload client with the configured endpoint,
 bearer token, and timeout-backed HTTP client. It also wraps the upload context
@@ -115,7 +121,8 @@ distributor service.
 ## Invariants
 
 - Distributor package types do not leak outside the adapter.
-- Only the managed Markdown report is uploaded.
+- Only managed Markdown report paths selected by app orchestration are
+  uploaded.
 - The adapter never scans the workspace.
 - Token values are not included in errors, CLI output, metadata, docs, or
   examples.