111 lines
5.4 KiB
Markdown
111 lines
5.4 KiB
Markdown
# 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](../cli.md),
|
|
[the configuration reference](../config.md), [operations](../operations.md),
|
|
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](generatedtext.md),
|
|
[report-template](reporttemplate.md), and [Scriptorium adapter](scriptorium-adapter.md)
|
|
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](distributor-adapter.md).
|
|
|
|
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.
|