From 8be9b020d4579b019f7f4eea4a68478b50b90ed0 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Sat, 1 Aug 2026 19:18:45 +0000
Subject: [PATCH] Record stateless execution architecture decision

---
 docs/adr/0001-stateless-execution.md | 99 ++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 docs/adr/0001-stateless-execution.md

diff --git a/docs/adr/0001-stateless-execution.md b/docs/adr/0001-stateless-execution.md
new file mode 100644
index 0000000..89cf4a8
--- /dev/null
+++ b/docs/adr/0001-stateless-execution.md
@@ -0,0 +1,99 @@
+# 0001: Make Weatherreporter Execution Stateless
+
+Status: Accepted
+
+Date: 2026-08-01
+
+## Context
+
+Weather reports are ephemeral products. Forecasts and current conditions change
+continuously, so the useful response to an old, failed, or superseded report is
+normally a new generation rather than replaying or inspecting a prior run.
+
+The existing run-addressed workspace retains module snapshots, prompt inputs,
+execution receipts, generated text, rendered reports, metadata, and
+notification receipts. That provenance store accumulates operational history
+whose recovery and compatibility obligations are disproportionate to the value
+of an ephemeral weather report. It also exists solely to support local Recent
+Changes comparison for a rarely used report section.
+
+The accepted [Stateless Execution Roadmap](../roadmap/ephemeral-state.md)
+defines the feature scope and implementation plan. This decision records the
+durable rationale for the resulting architecture.
+
+## Decision
+
+Weatherreporter will operate as a stateless transformation pipeline:
+
+```text
+Weather API input
+  -> deterministic facts and modules
+  -> Promptkit data package and generated text
+  -> repository-owned Markdown rendering
+  -> operator-owned report output
+  -> optional Distributor upload
+```
+
+Ordinary invocations will retain intermediate values only for the active
+process and will publish one operator-owned Markdown output atomically. A
+failed or canceled generation must not truncate or partially replace an
+existing selected output. Single-report Distributor notification follows
+successful publication; batch notification follows successful publication of
+every planned report.
+
+Weatherreporter will remove local Recent Changes comparison instead of
+retaining application state to support it. It will remove run-addressed
+workspace artifacts, historical inspection, and backward-compatible workspace
+decoding. RunIDs may remain active correlation and Distributor idempotency
+values, but will not identify retained application history.
+
+Explicit `--llm-debug-dir` capture remains the sole diagnostic-file exception.
+The operator selects and manages that secure location; ordinary execution does
+not create an implicit debug location or a general logging store, and debug
+capture must continue to exclude credentials.
+
+Any future forecast comparison must use a structured product supplied by the
+Weather API rather than local Weatherreporter history. The proposed
+[Upstream Forecast Change Product](../roadmap/future.md#upstream-forecast-change-product)
+defines the required upstream direction. A future integration must not add a
+local snapshot fallback.
+
+## Alternatives Considered
+
+### Retain The Bounded Current-State Design
+
+Retaining a managed workspace with current metadata, receipts, and snapshots
+would preserve inspection and local comparison, but keeps an application-owned
+history subsystem, artifact compatibility burden, and recovery surface that do
+not match the report lifecycle.
+
+### Time-Based Retention
+
+Expiring workspace material after a fixed period reduces accumulation but still
+requires retention policy, cleanup behavior, failure handling, and historical
+format support. It does not remove the mismatch between retained provenance and
+ephemeral report products.
+
+### Bounded Run History
+
+Keeping only a fixed number of prior runs limits storage volume but still makes
+Weatherreporter responsible for run selection, comparison, inspection, and
+state migration. It also creates arbitrary history gaps without establishing an
+authoritative forecast baseline.
+
+## Consequences
+
+The CLI, configuration, prompt-input, workspace, and inspection contracts will
+change together. Legacy workspace material will not be migrated, decoded, or
+automatically deleted; operators remain responsible for any desired cleanup.
+
+Current action results will carry active identity, selected profile, safe
+effective model information, output location, notification result, and safe
+errors instead of historical artifact paths. Tests will protect atomic output,
+batch and notification ordering, explicit secure debug capture, and the
+absence of ordinary application-managed state.
+
+This decision deliberately leaves the Weather API responsible for any future
+forecast-history comparison. It avoids a cache, archive, retention engine,
+manifest, resume mechanism, or replacement inspection surface in
+Weatherreporter.