120 lines
6.0 KiB
Markdown
120 lines
6.0 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 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](../cli.md),
|
|
[the configuration reference](../config.md), [operations](../operations.md),
|
|
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](generatedtext.md) and [report-template](reporttemplate.md)
|
|
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](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, 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.
|