63 lines
5.1 KiB
Markdown
63 lines
5.1 KiB
Markdown
# Application Orchestration Internals
|
|
|
|
`internal/app` owns stateless report generation, batch execution, comparison
|
|
orchestration, atomic output publication, and notification coordination after
|
|
`internal/cli` has parsed arguments and loaded configuration. The user contract
|
|
is owned by the [CLI reference](../cli.md) and [operations guide](../operations.md).
|
|
|
|
## Single-Report Flow
|
|
|
|
`GenerateDetailed` resolves the requested report and output destination before initializing an optional explicit debug writer. An explicit output file wins; otherwise the configured output directory is used, falling back to the captured working directory. Output preflight validates the final filename, permits only an absent or regular final destination, and validates the bounded same-directory temporary form without creating a missing parent. It then validates the report's generated-text catalog binding, exact Promptkit prompt, and selected profile before collecting weather data. The resolved profile, backend, and model are carried in the active result.
|
|
|
|
The workflow builds facts, a module snapshot, briefing metadata, and the YAML prompt package in memory. It executes Promptkit only against the inspected prompt and profile, reconciles the preparation callback and completed result with that identity and the prepared report schema, validates the returned generated text, builds a render context, and renders Markdown. `fileutil` writes the completed Markdown through a same-directory temporary file, rechecks the final destination and context after close and immediately before the atomic rename. Only after that write succeeds does single-report notification run.
|
|
|
|
Failures return an active partial result with safe identity, profile, warning, validation, debug, and output information when available. After rendering and immediately before publication, the workflow checks for cancellation or deadline expiry. Any failure before publication leaves an existing destination unchanged. A notification failure retains the newly published output.
|
|
|
|
## Batches
|
|
|
|
`RunBatchDetailed` selects an explicit output directory first, otherwise the configured directory and then the captured working directory. It does this before creating at most one explicit debug writer or validating generated-text catalog, prompt, and profile candidates for the selected batch. It collects once, calculates the data-dependent plan, then validates and retains the final output path for every planned report before invoking the same generation core sequentially.
|
|
|
|
Each item has an independent result. A failed item does not stop later items; successful items retain their published output paths. Per-report notification is suppressed during a batch. Batch notification runs only after every planned report has published successfully. It is skipped when any item failed. Batch result counters count report items only; a batch notification failure is represented by the top-level notification result and still produces a failed batch outcome.
|
|
|
|
## Comparisons
|
|
|
|
`CompareDetailed` validates ordered explicit profile IDs, resolves the report,
|
|
and preflights the exact bundle destination before initializing optional prompt
|
|
debugging, prompt inspection, or collection. It then validates the report's
|
|
generated-text catalog binding, inspects the one prompt and every selected
|
|
profile, collects once, and delegates shared report
|
|
construction to the prepared-report flow. It does not accept a notifier.
|
|
|
|
Once the destination is resolved, the partial result retains its absolute
|
|
output directory even when later preflight, debug initialization, inspection,
|
|
collection, or preparation fails. Every initialized result is finalized with a
|
|
finished timestamp. If prompt inspection succeeds before a later profile
|
|
inspection fails, the partial result retains the resolved prompt ID, version,
|
|
and hash. Artifact paths are added only after publication commits.
|
|
|
|
The comparison execution core starts each inspected profile independently,
|
|
keeps results in selection order, and waits for all started work. Every profile
|
|
reconciles its callback and completion provenance before its JSON can be
|
|
rendered. Independent profile failures are recorded and do not stop peers.
|
|
Context cancellation marks unfinished work and prevents publication. Details of
|
|
prepared values, execution and debugging, and publication are documented in [prepared report
|
|
internals](prepared-report.md), [comparison execution
|
|
internals](comparison-execution.md), and [comparison publication
|
|
internals](comparison-publication.md).
|
|
|
|
When publication has committed its new bundle, application results contain the
|
|
absolute manifest, data-package, and successful report paths even if removal of
|
|
the previous sibling backup then fails. That cleanup failure is still returned
|
|
as an operational error rather than treating the new bundle as unpublished;
|
|
the returned error retains the recovery path and underlying filesystem cause.
|
|
|
|
## Boundaries And Verification
|
|
|
|
The package does not parse flags, load YAML, implement transport, construct provider SDKs, or define report-period policy. Prompt, profile, weather, and Distributor implementations remain behind project-owned contracts.
|
|
|
|
Focused checks:
|
|
|
|
```sh
|
|
go test ./internal/app ./internal/collect
|
|
```
|