weatherreporter/docs/internal/app-orchestration.md

Application Orchestration Internals

internal/app composes top-level generation, batch, collection-save, and inspection workflows after CLI parsing and configuration loading. It owns workflow ordering, request composition, partial-result handling, and the application-facing interfaces used for tests.

Inputs And Outputs

The package accepts generate, resolved-report, batch, explicit-collection, and inspection requests. Generation and batch requests may supply collector, renderer, store, and notifier implementations for tests; production defaults use the focused packages.

A report result contains the module snapshot, prompt package, Scriptorium results, generated-text artifacts, report and metadata paths, prior snapshot, Recent Changes, and notification information. A batch result contains aggregate counts, per-report outcomes, and an optional batch notification. Inspection returns persisted values only.

Exact public command syntax, configuration fields, workspace layout, external protocols, and report definitions belong in the CLI reference, the configuration reference, operations, and their focused integration and internal documents.

Single-Report Workflow

GenerateDetailed first collects weather data, then resolves the requested report using the configured registry and current time, and finally calls GenerateReport with that explicit collection. It returns no result when collection or resolution fails.

GenerateReport requires a non-nil normalized bundle and then performs this ordered work:

1. Select a state store, determine artifact destinations, and locate a prior compatible snapshot.
2. Build report facts and deterministic module snapshots, then save the module snapshot and calculate Recent Changes.
3. Build and save the prompt data package, run Scriptorium render preflight, save any preflight result, and save initial metadata.
4. Run structured Scriptorium generation, validate and save generated text, build and save a render context, and render the managed Markdown template.
5. Optionally make an output copy, save final metadata, optionally notify Distributor from the managed report path, and save metadata again when a notification path is produced.

Every report looks up its catalog definition, runs structured Scriptorium output to the raw artifact, preserves the structured run result, validates and saves generated text, builds and saves a render context, then renders the embedded Markdown template. Schema, template, and subprocess details remain in their generated-text, report-template, and Scriptorium adapter owners.

If preflight returns a result with an error, the result and initial metadata are saved before the error returns. If report generation fails after a managed path is prepared, metadata still records that path; output copies and notification are skipped. Generated-text failures preserve the latest artifact reached before failure when it was saved.

Batch And Inspection Workflows

RunBatchDetailed collects once, asks the report registry to plan the batch from that collection, and invokes GenerateReport independently for every planned report using the same collection and state store. Per-report notification is suppressed. A failed report is recorded and does not prevent later planned reports from running.

After report generation, the batch notifier is considered once. It is omitted when Distributor or batch notification is disabled, skipped when any report failed, and otherwise receives one multi-file request. A batch notification failure increments the aggregate failure count but does not rewrite successful report items. Notification identities, path mappings, polling, and redaction are owned by the Distributor adapter.

Inspection methods create a state store and load existing report records, metadata, module snapshots, prompt packages, prior snapshots, or source provenance. They neither collect data nor invoke Scriptorium or Distributor.

Boundaries And Failure Propagation

The app layer does not parse flags, load configuration files, implement Weather API transport, construct Scriptorium argv, or define report registry policy. It coordinates the relevant collaborators and preserves their error context.

• Collection failure stops a single report or batch before resolution or planning completes.
• State, fact, module, prompt-input, or preflight failures stop that report before report generation.
• A terminal Distributor failure is returned with the saved notification information when available.
• Batch failures are represented per report and through aggregate batch status.
• Persisted artifact paths are carried in results so callers can inspect work completed before a later failure.

Tests And Invariants

Focused tests are in internal/app/app_test.go and internal/app/batch_plan_test.go, with collection coverage in internal/collect/collect_test.go.

• Production workflows collect through internal/collect.
• A report uses one explicit normalized collection throughout its generation.
• Render preflight precedes report generation.
• Recent Changes compare structured module snapshots.
• Reports render from a validated typed context, never directly from a raw prompt package.
• Only managed Markdown reports are notification sources; output copies are never uploaded.