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 collaborators for tests; single-report generation uses a Promptkit executor, while batch requests retain a renderer for their compatibility workflow.

A report result contains the module snapshot, prompt package, prompt provenance, 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.

InspectPromptExecution is a side-effect-free preflight helper for the prompt workflow. It verifies the exact report prompt version, its required YAML input, the generated-text JSON Schema contract, the selected profile, and any required environment credential before collection or persistence begins. It returns only safe project-owned identity and provenance values.

Single-Report Workflow

GenerateDetailed resolves the requested report using the configured registry and current time, verifies the exact Promptkit prompt and selected profile, and only then collects weather data. Inspection failure produces no collection or managed artifacts.

Single-report generation 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. Serialize and save the prompt data package once, then use those exact bytes for Promptkit execution.
4. Save preparation provenance and V2 metadata from the preparation callback before provider execution. Save execution provenance after raw output is persisted, then save updated metadata.
5. Validate and save generated text, build and save a render context, and render the managed Markdown template.
6. 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 single report looks up its catalog definition, saves raw Promptkit output, preserves safe preparation and execution provenance separately, validates and saves generated text, builds and saves a render context, then renders the embedded Markdown template. Schema and template details remain in their generated-text and report-template owners.

Preparation and operational execution failures save classified receipts and metadata before returning. A completed Promptkit validation rejection saves raw output, an execution receipt, and metadata before returning. If later report generation fails, the result retains every reached safe artifact path; output copies and notification are skipped until rendering succeeds.

Batch And Inspection Workflows

RunBatchDetailed collects once, asks the report registry to plan the batch from that collection, and invokes its isolated Scriptorium compatibility helper 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, invoke provider SDKs, or define report registry policy. It coordinates the relevant collaborators and preserves their error context.

• Prompt inspection failure stops a single report before collection or durable writes. Collection failure stops a single report or batch before planning.
• State, fact, module, prompt-input, preparation, or execution failures stop that report before later 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.
• Prompt preparation provenance and metadata are persisted before provider execution.
• 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.