# App Orchestration Internals

This document describes the workflow coordinator in `internal/app`.

## Purpose

`internal/app` coordinates the top-level use cases after CLI parsing and config
loading are complete. It resolves report definitions, fetches weather data,
builds collected and derived facts, builds module snapshots and prompt-input
artifacts, invokes Scriptorium through the adapter boundary, optionally
notifies distributor through an app-owned notifier boundary, persists managed
state, runs batches, and reads existing artifacts for inspection.

## Inputs And Outputs

Inputs:

- `GenerateRequest` for one report command
- `BatchRequest` for morning or evening batch commands
- `FetchBundleRequest` for explicit bundle fetch and save workflows
- `ReportRequest` for single-report generation
- resolved report definitions from `internal/report`
- weather data bundles from `internal/adapters/weatherapi`
- prior snapshots loaded from `internal/state`
- optional renderer, notifier, and state-store fakes for tests

Outputs:

- generated report results with JSON module snapshot, YAML data package,
  preflight, report, metadata, prior snapshot, Recent Changes, Scriptorium
  result details, and notification result when attempted
- batch summaries with per-report status, artifact paths, error text, and
  notification outcome when attempted
- saved Weather API bundle JSON for fetch workflows
- inspection JSON values for reports, metadata, module snapshots, data
  packages, prior snapshots, and source provenance

## Boundaries

`internal/app` owns workflow order and request composition. It does not parse
CLI flags, load YAML files directly, implement HTTP transport, own fact
derivation algorithms, define report periods, compare rendered Markdown, or
construct Scriptorium argv.

Report selection and report identity policy come from `internal/report`.
Collected and derived fact contracts come from `internal/facts`.
Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
subprocess behavior stays in `internal/adapters/scriptorium`. Distributor
upload behavior stays in `internal/adapters/distributor`. Filesystem layout and
persisted metadata stay in `internal/state`.

## Config Fields Used

- `weather_api.*` for Weather API client construction and module metadata
- `scriptorium.*` for renderer construction
- `workspace.*` for filesystem state
- `dayparts` for daily and outlook summarization
- `recent_change.*` for structured Recent Changes thresholds
- `notify.distributor.*` for optional notification after report generation

Output copy flags are command request fields. They are not configuration
defaults.

## Generation Workflow

Single-report generation follows this order:

1. Resolve the command report to a `report.Resolved` value.
2. Create or use a filesystem store.
3. Locate any prior compatible snapshot through `internal/state`.
4. Fetch a Weather API bundle.
5. Build collected and derived facts once.
6. Execute configured modules and save the module snapshot.
7. Compute Recent Changes from structured prior and current module snapshots.
8. Build and save the YAML Scriptorium `data_package`.
9. Run Scriptorium render preflight.
10. Save preflight JSON when a render result is available.
11. Save metadata for inspection.
12. Run Scriptorium report generation to the managed report path.
13. Copy the managed report to the requested `--out` path when provided.
14. Save metadata with the managed report path.
15. If distributor notification is enabled, notify using the managed report
    path as the source file.
16. Save a distributor notification debug artifact and update metadata with its
    path.

If render preflight returns both a result and an error, preflight JSON and
metadata are persisted before the error is returned. If Scriptorium report
generation returns an error after writing output, the managed report and
metadata remain inspectable. Notification is not attempted after Weather API,
module snapshot, prompt input, render, Scriptorium run, or metadata-save
failures.
When notification is attempted, the debug artifact records request identity,
including rendered pipeline ID, bundle paths, accepted upload fields,
distributor status fields, raw status report JSON when available, and redacted
failure context.
`--out` copies are never used as notification source files.

## Batch Workflow

`run morning` resolves Daily Today, 3-Day Outlook, and Weekend Outlook except
on Sunday. `run evening` resolves Daily Tomorrow. Batch output copy names come
from report definitions. Batch generation continues independent reports after a
failure, records each result, writes compact status lines to stderr, emits a
JSON summary to stdout, and returns an aggregate error when any report failed.
When notification is enabled, each successfully generated report is notified
independently. Notification failure marks that report failed, records
notification fields in the batch result, and does not stop later reports.
`--out-dir` copies are never used as notification source files.

## Inspection Workflow

Inspection workflows load existing filesystem state only. They do not fetch
weather data or invoke Scriptorium. Run-specific inspect commands share the same
store and metadata lookup path, then load the requested artifact or derived
inspection view.

## Failure Behavior

- Resolve errors stop the requested workflow before fetching weather data.
- Weather API and module execution errors stop that report before Scriptorium
  runs.
- Prompt input validation fails before render preflight.
- Render and run errors preserve Scriptorium stderr and exit-code context.
- Notification errors are wrapped with report ID, RunID, and managed report path
  context and are recorded separately in batch results.
- Metadata and artifact path errors include filesystem context.
- Batch failures are recorded per report and surfaced through an aggregate
  batch error.

## Tests

Inspect:

- `internal/app/app_test.go`
- `internal/cli/root_test.go`
- `internal/state/filesystem_test.go`

## Invariants

- Report behavior is resolved through `internal/report`.
- Generated reports use the same app request and result types regardless of
  report ID.
- Render preflight precedes Scriptorium report generation.
- Recent Changes are computed from structured module snapshots.
- Metadata links artifacts produced for a run.
- Distributor notification maps the managed Markdown report path to configured
  bundle paths; extra output copies are not upload sources.