weatherreporter/docs/roadmap/ephemeral-state.md

Stateless Execution Roadmap

Status: Accepted.

Purpose

Weatherreporter should be a stateless report transformation pipeline. Each invocation fetches current inputs from the Weather API, derives deterministic facts, executes Promptkit, renders Markdown, and writes or distributes the completed report. It does not retain application-owned history or operational state between invocations.

Weather reports are ephemeral products rather than business records. Forecasts and current conditions change continuously, and the normal response to an old or failed report is to generate a new one rather than recover, replay, or inspect the prior generation.

This roadmap defines the desired lifecycle, output contract, compatibility policy, and architectural boundaries.

User Intent

The target design reflects these product expectations:

• each invocation is independent and requires no prior Weatherreporter state;
• routine operation creates only the requested report outputs;
• reports are written somewhere useful even when the operator omits an explicit output flag;
• Weatherreporter does not maintain forecast history merely to compare runs;
• regenerating replaces a same-named output atomically instead of creating an archive;
• Distributor receives the completed report produced by the current invocation; and
• sensitive diagnostics are retained only through an explicit, operator-controlled debug option.

Current State

Each generation currently writes a run-addressed collection containing a module snapshot, data package, prompt preparation receipt, prompt execution receipt, raw generated text, validated generated text, render context, managed report, metadata, and optional notification receipt. Successful and failed runs accumulate beneath the configured workspace.

Metadata links these artifacts and supports lookup by RunID. The CLI can list historical runs and inspect their metadata, modules, data packages, prior snapshots, and source provenance. The reader retains V1 compatibility while new runs write V2 metadata.

Weatherreporter also loads a compatible prior module snapshot for Daily, Today, and Tomorrow and compares it with the current snapshot. Configurable thresholds determine whether structured Recent Changes are included in the Promptkit data package. This is the only current product behavior that depends on state from an earlier invocation.

Desired End State

Weatherreporter has no durable application-managed workspace. Its dataflow is:

Weather API input
  -> deterministic facts and modules
  -> Promptkit data package and generated text
  -> repository-owned Markdown rendering
  -> operator-owned report output
  -> optional Distributor upload

Intermediate values remain in memory wherever practical. A narrowly scoped temporary file may be used when an external interface requires a file path, but it exists only for the active invocation and is removed on return. Temporary material is not a supported recovery or inspection surface.

RunIDs may remain as in-process correlation identifiers in action summaries, errors, Distributor idempotency values, and explicit debug paths. They do not identify a collection that Weatherreporter can locate or decode later.

Configuration files, operator-owned report outputs, and explicitly requested debug captures are inputs or outputs, not Weatherreporter state.

Report Output Contract

Every successful report generation writes one operator-owned Markdown output. An explicit output option selects its destination. When no explicit destination is supplied, Weatherreporter uses the process working directory captured at invocation start.

Default single-report filenames are:

Report	Default output
Daily	daily-YYYY-MM-DD.md, using the report's valid local date
Today	today.md
Tomorrow	tomorrow.md
Hourly	hourly.md

--out PATH replaces the default destination for generate; it no longer means an extra copy of a separately managed report. Relative paths are resolved from the invocation's working directory.

For run, --out-dir PATH selects the report-output directory and the current working directory is the default when it is omitted. Existing batch filenames remain: today.md, tomorrow.md, and daily-YYYY-MM-DD.md. Successful items in a partially failed batch retain their outputs.

Output publication is atomic. A completed generation may atomically replace an existing file at the selected path, but a failed or canceled generation must not truncate or partially replace it. Weatherreporter does not rotate, archive, expire, or otherwise manage an output after publication.

The JSON action summary reports the final output path. It does not expose paths to transient intermediates. --quiet continues to suppress the action summary, not report creation.

Distributor Contract

Distributor uploads use the completed Markdown output from the active invocation. There is no separate durable managed-report copy and no workspace scan.

For a single report, local output publication completes before notification. A notification failure leaves the report output intact and returns a safe error through the active result. It does not create a notification receipt.

Batches continue to suppress per-report notification and attempt their batch-level upload only after every planned report succeeds. A report failure leaves other successful output files intact, skips the batch upload, and returns an aggregate failure. Distributor status remains active-workflow information rather than retained Weatherreporter history.

Recent Changes Deprecation And Removal

The local Recent Changes feature is deprecated by this accepted direction and is removed when the stateless execution change lands. Its low practical value does not justify retaining a historical state subsystem.

Removal includes:

• prior-snapshot discovery and compatibility rules;
• the internal/changes comparison implementation;
• report-registry comparison strategies and compatible-prior declarations;
• recent_change configuration and threshold validation;
• Recent Changes values in application results, prompt inputs, fixtures, and tests;
• the recent_changes Promptkit data-package stanza; and
• prompt instructions that refer to supplied recent changes.

Removing the prompt-input field is a breaking prompt contract change. The data package schema advances from weatherreporter.data_package.v3 to weatherreporter.data_package.v4, and all four prompt definitions advance from version 1.1.0 to 2.0.0 together. Generated-text schemas and report templates do not change; neither has a direct dependency on Recent Changes.

Weatherreporter does not retain an empty compatibility field and does not keep a local fallback comparator. Reports simply omit change commentary after this feature is removed.

A future upstream Weather API change product may allow Weatherreporter to reintroduce structured change commentary without local state. That work is recorded in Future Roadmap and is not a prerequisite for this refactor.

Debugging

Prompt inspection before weather collection and prepared execution remain runtime safety requirements. Preparation details, effective profile and model, validation outcomes, source warnings, and safe errors remain available to the active workflow and its action summary where useful.

The existing --llm-debug-dir PATH option remains the explicit exception to stateless output. When supplied, it may retain rendered prompts, schemas, input bodies, generated bodies, and effective parameters according to its secure capture contract. The operator selects and manages that location; Weatherreporter does not clean or archive it. Credentials remain excluded.

Adding a broader logging framework or an implicit persistent debug directory is outside this feature. A future rename or generalization to --debug should be considered separately so this state refactor does not expand the sensitive capture contract incidentally.

Removed State And Inspection Contracts

The target removes:

• the workspace configuration section and its directory settings;
• durable module snapshots, data packages, preparation and execution receipts, raw and validated generated text, render contexts, run metadata, managed reports, and notification receipts;
• historical artifact path fields from action results and summaries;
• V1 and V2 metadata models, readers, validators, and compatibility behavior;
• state lookup, prior selection, and run-history discovery; and
• inspect reports, inspect metadata, inspect modules, inspect data-package, inspect prior, and inspect sources.

No replacement inspection command or current-state manifest is introduced. The active action summary, final output, command error, and opt-in debug capture are the supported diagnostic surfaces.

State-independent atomic file helpers may remain outside a state abstraction. The target architecture should not preserve internal/state merely as a compatibility wrapper after its state responsibilities disappear.

Compatibility And Upgrade Policy

This is an intentional breaking change to the CLI, configuration, prompt-input, workspace, and inspection contracts. Weatherreporter does not migrate old V1 or V2 metadata or other historical artifacts.

Legacy workspace trees are ignored. Weatherreporter must not discover, interpret, or automatically delete them. Release notes and operations documentation identify the obsolete configuration and commands and provide a precise manual cleanup procedure for operators who want to remove the legacy workspace.

Existing report files explicitly written through --out or --out-dir remain operator-owned and are never treated as legacy workspace material.

The change should land in a release whose notes identify the removed Recent Changes behavior, configuration fields, inspection commands, artifact paths, and metadata compatibility; the new default output destinations; and any operator action required during upgrade.

Required Architecture Decision Record

The target state includes an Accepted ADR recording the durable decision to make Weatherreporter stateless.

The ADR should record:

• the mismatch between run-addressed provenance storage and ephemeral weather reports;
• the decision to remove local change detection rather than retain state for a rarely used report section;
• the transformation-pipeline model and operator-owned output boundary;
• the absence of historical inspection and backward-compatibility guarantees;
• atomic output and failure behavior;
• the separation of explicit debug capture from ordinary execution;
• the upstream-service path for any future forecast comparison; and
• alternatives considered, including the former bounded-current-state design, time-based retention, and a bounded run history.

Once accepted, the ADR owns the rationale. Architecture owns the resulting stateless invariant, while CLI, operations, configuration, integrations, and focused internal documents own implemented contracts.

Scope

The completed feature includes:

• removal of local Recent Changes and all prior-run dependencies;
• removal of the durable workspace, artifact persistence, metadata compatibility, and historical inspection surfaces;
• in-memory or invocation-temporary processing with safe cleanup;
• atomic operator-owned output for every successful report;
• current-working-directory defaults and explicit output overrides;
• preservation of report generation, batch membership, Promptkit execution, Distributor delivery, action summaries, and opt-in secure debug capture;
• removal or simplification of state-only packages, fields, configuration, fixtures, tests, and documentation;
• exact-version prompt updates for the breaking input-contract change;
• deterministic offline tests for output atomicity, failure isolation, default path selection, Distributor sequencing, and absence of durable state;
• an Accepted ADR documenting the decision; and
• canonical documentation describing the implemented contract and clear release-note requirements for the release that publishes it.

Non-Goals

This feature does not include:

• the future upstream forecast-change API or reintroduced change commentary;
• a cache, database, archive, retention engine, manifest, or resume mechanism;
• migration or automatic deletion of legacy workspace artifacts;
• retaining a bounded report or snapshot history;
• changing weather derivation, report periods, report membership, generated prose schemas, profile selection, or the provider model ladder;
• changing Distributor's remote API or bundle-content contract;
• deleting or managing operator-owned report and debug outputs;
• a general logging or observability subsystem; or
• live external services in the default test suite.

Safety And Testing Policy

Tests should emphasize observable stateless behavior rather than removed file choreography. Important risks requiring durable offline coverage include:

• a failed or canceled generation truncating or replacing an existing output;
• default paths resolving somewhere other than the invocation working directory;
• Daily output using the wrong valid local date;
• a batch item overwriting another planned output;
• a notification attempt occurring before its report output is complete;
• one batch failure deleting or corrupting another report's successful output;
• summaries exposing nonexistent transient paths;
• temporary files surviving an ordinary success or handled failure;
• default operation recreating a workspace or historical artifact tree; and
• debug capture leaking credentials or being created without explicit opt-in.

Tests remain deterministic, offline, credential-free, and use real temporary directories plus narrow external-boundary fakes. Existing tests whose only purpose is to preserve removed state, metadata, inspection, or Recent Changes contracts should be deleted rather than translated into assertions about private replacement mechanics.

Completion Criteria

The target state is achieved when:

• a clean invocation requires no prior Weatherreporter-created files;
• ordinary runs leave only their selected Markdown outputs;
• omitted output flags resolve to the documented filenames in the current working directory;
• failed and canceled attempts preserve any existing destination file;
• no local prior-run comparison or Recent Changes contract remains;
• no workspace configuration, run-history command, metadata compatibility, or durable intermediate-artifact contract remains;
• Distributor uses only completed current-invocation outputs;
• debug files are created only through explicit secure capture;
• repeated successful and failed runs do not create application-owned history;
• the test suite proves the stateless, atomic-output, batch, notification, and security boundaries offline;
• an Accepted ADR records the architectural decision; and
• canonical current-state documentation describes only the implemented stateless lifecycle.