120 lines
4.9 KiB
Markdown
120 lines
4.9 KiB
Markdown
# Workspace Artifact Layout Roadmap
|
|
|
|
## Purpose
|
|
|
|
This roadmap defines the target local workspace layout for artifacts generated
|
|
by weatherreporter.
|
|
|
|
Weatherreporter currently writes managed local artifacts for each run and also
|
|
maps the managed Markdown report into distributor bundle paths. Distributor
|
|
bundle paths are publication paths and may include overwrite-oriented aliases
|
|
such as `hourly/index.md`, `today/index.md`, and
|
|
`daily/<valid_start_date>/index.md`. Local workspace paths have a different
|
|
job: they preserve run-specific source artifacts for inspection, troubleshooting,
|
|
retry diagnosis, and future cleanup.
|
|
|
|
## Locked Decisions
|
|
|
|
- Keep managed local workspace paths separate from distributor bundle paths.
|
|
- Do not use distributor-style `index.md` aliases as the canonical managed
|
|
local artifact paths.
|
|
- Store managed local artifacts as immutable run artifacts.
|
|
- Group every durable run artifact by artifact family, report artifact group,
|
|
and local `valid_start_date`.
|
|
- Use `valid_start_date` in the effective report timezone as the directory key.
|
|
- Include the RunID in every durable run artifact filename.
|
|
- Prefer artifact-kind-first filenames: `<kind>.<run_id>.<extension>`.
|
|
- Keep optional `--out` and `--out-dir` copies separate from managed workspace
|
|
artifacts.
|
|
- Future cleanup should delete old managed artifact date directories by
|
|
`valid_start_date`; cleanup should be narrow and opt-in.
|
|
- If a local publication preview is added later, put it in a separate mirror
|
|
tree and treat it as rebuildable output, not canonical run state.
|
|
|
|
## Target Managed Layout
|
|
|
|
The target managed workspace layout is:
|
|
|
|
```text
|
|
<workspace.root>/
|
|
reports/<artifact_group>/<valid_start_date>/report.<run_id>.md
|
|
|
|
snapshots/<artifact_group>/<valid_start_date>/modules.<run_id>.json
|
|
snapshots/<artifact_group>/<valid_start_date>/metadata.<run_id>.json
|
|
snapshots/<artifact_group>/<valid_start_date>/generated_text_raw.<run_id>.json
|
|
snapshots/<artifact_group>/<valid_start_date>/generated_text_result.<run_id>.json
|
|
snapshots/<artifact_group>/<valid_start_date>/generated_text.<run_id>.json
|
|
snapshots/<artifact_group>/<valid_start_date>/render_context.<run_id>.json
|
|
|
|
data-packages/<artifact_group>/<valid_start_date>/data_package.<run_id>.yaml
|
|
preflight/<artifact_group>/<valid_start_date>/render.<run_id>.json
|
|
|
|
notifications/<artifact_group>/<valid_start_date>/distributor.<run_id>.json
|
|
notifications/batches/<batch>/<batch_start_date>/distributor.<batch_run_id>.json
|
|
```
|
|
|
|
`artifact_group` comes from the report definition. `valid_start_date` is the
|
|
resolved report valid period start date in the effective report timezone.
|
|
`batch_start_date` is the batch start date in the effective report timezone.
|
|
|
|
Generated-text-template reports use the generated-text artifacts. Markdown-path
|
|
reports omit generated-text artifacts they do not produce.
|
|
|
|
## Cleanup Compatibility
|
|
|
|
The target layout is designed to support a future cleanup command that removes
|
|
managed local artifacts where `valid_start_date` is more than two days before
|
|
the current local date.
|
|
|
|
Cleanup can operate by deleting matching date directories across managed
|
|
artifact families:
|
|
|
|
```text
|
|
reports/<artifact_group>/<old_date>/
|
|
snapshots/<artifact_group>/<old_date>/
|
|
data-packages/<artifact_group>/<old_date>/
|
|
preflight/<artifact_group>/<old_date>/
|
|
notifications/<artifact_group>/<old_date>/
|
|
```
|
|
|
|
The command should not infer dates from RunIDs when the directory date is
|
|
available. It should use the effective configured report timezone for "current
|
|
date" and for interpreting `valid_start_date` directories.
|
|
|
|
Batch notification cleanup should use `batch_start_date` under
|
|
`notifications/batches/<batch>/`. A future local publication mirror, if added,
|
|
should be ignored by cleanup or rebuilt after cleanup; it should not be treated
|
|
as run history.
|
|
|
|
## Intended Final State
|
|
|
|
`internal/state` owns the managed workspace layout and path construction. The
|
|
app layer continues to ask the state store for managed paths and records those
|
|
paths in metadata and command results.
|
|
|
|
Metadata links every artifact produced for a run using the new managed paths.
|
|
Inspection and prior-snapshot lookup continue to read metadata rather than
|
|
rendered Markdown text. Distributor uploads continue to use the managed
|
|
Markdown report as the source file and map it to separately resolved
|
|
distributor bundle paths.
|
|
|
|
Existing workspace configuration fields remain meaningful:
|
|
|
|
- `workspace.root`
|
|
- `workspace.snapshots_dir`
|
|
- `workspace.reports_dir`
|
|
- `workspace.data_packages_dir`
|
|
- `workspace.preflight_dir`
|
|
- `workspace.notifications_dir`
|
|
|
|
This roadmap does not require a new user-visible workspace path template config
|
|
surface.
|
|
|
|
## Deferred Work
|
|
|
|
- A cleanup command for managed local artifacts.
|
|
- Cleanup dry-run output, retention configuration, and deletion confirmation
|
|
behavior.
|
|
- A rebuildable local publication mirror that uses distributor-style paths.
|
|
- Migration tooling for existing pre-refactor workspace directories.
|