Document service job durability contract

docs/ASSESSMENT-OPERATIONS.md

@@ -147,7 +147,8 @@ curl -sf http://127.0.0.1:8080/runs/JOB_ID/reports | python3 -m json.tool
 
 Service job state is currently in memory for the running service process. Run
 artifacts are durable in the output directory and can still be inspected after a
-service restart.
+service restart. See `docs/SERVICE-JOB-DURABILITY.md` for the restart and
+recovery contract.
 
 ## Status Vocabulary
 

docs/LOCAL-SERVICE-API.md

@@ -87,7 +87,8 @@ run directory; the assessment result itself is still reported separately as
 
 ### `GET /runs`
 
-Lists known in-memory jobs for the current service process.
+Lists known in-memory jobs for the current service process. Job records are not
+durable across service restarts.
 
 ### `GET /runs/{job_id}`
 
@@ -111,4 +112,5 @@ podman run --rm -p 8080:8080 \
 ```
 
 The service keeps job state in memory. Durable run evidence remains in the
-mounted output directory.
+mounted output directory. See `docs/SERVICE-JOB-DURABILITY.md` for the explicit
+restart and recovery contract.

docs/SERVICE-JOB-DURABILITY.md

@@ -0,0 +1,90 @@
+# Service Job Durability
+
+Status: draft
+Created: 2026-05-15
+
+## Decision
+
+The guide-board local service keeps HTTP job state in memory for the baseline.
+This is intentional. The service is a thin local transport over the CLI
+contracts, not a workflow database.
+
+Durable state lives in run directories:
+
+- `run.json`
+- `plan.json`
+- `retention-summary.json`
+- `normalized/evidence.json`
+- `normalized/findings.json`
+- `normalized/mappings.json`
+- `reports/assessment-package.json`
+- `reports/report.md`
+- `artifacts/`
+
+The durable recovery index is the set of `retention-summary.json` files under a
+runs directory.
+
+## Why In-Memory Jobs Stay The Baseline
+
+In-memory service jobs keep the first service layer dependency-light and easy to
+embed in local, container, and extension-specific environments. Operators can
+restart the service without migrating or repairing a service database, and the
+CLI remains the source of truth for execution semantics.
+
+This also keeps interrupted service runs easy to reason about:
+
+- if the process exits before a run completes, the HTTP job record is gone,
+- any partial run directory remains for inspection,
+- completed runs are recoverable through retained run summaries,
+- repeated runs should use a new output directory or an intentional overwrite
+  policy chosen by the operator.
+
+## Restart Semantics
+
+After a service restart:
+
+- `GET /runs` returns only jobs created since the new service process started,
+- old `job_id` values are invalid,
+- `GET /runs/{job_id}` cannot recover pre-restart job metadata,
+- `GET /runs/{job_id}/reports` only works for jobs known to the current process,
+- run artifacts from earlier service processes remain available on disk.
+
+Operators should recover previous results with the CLI run-history commands:
+
+```sh
+PYTHONPATH=src python3 -m guide_board runs list --runs-dir runs
+PYTHONPATH=src python3 -m guide_board runs latest --runs-dir runs
+PYTHONPATH=src python3 -m guide_board runs report --runs-dir runs --run-id RUN_ID
+```
+
+## Recovery Flow
+
+Use this flow when the service process restarted or a browser/UI lost its job
+state:
+
+1. Identify the output directory passed to `POST /runs`.
+2. Confirm whether `retention-summary.json` exists.
+3. If it exists, use `guide-board runs report --runs-dir <parent>` to retrieve
+   report paths.
+4. If only partial files exist, inspect `run.json`, `plan.json`, and artifacts
+   before rerunning.
+5. Rerun into a fresh output directory when the prior status is unclear.
+
+## Future Durable Index Option
+
+A future durable service index may be added if UI or automation workflows need
+cross-restart job lookup. If added, it should remain reconstructable from run
+directories and should not become the authority for assessment results.
+
+The minimum acceptable durable index would contain:
+
+- job id,
+- request payload,
+- job transport status,
+- run id,
+- output directory,
+- result paths,
+- error summary.
+
+The index should be optional, dependency-light, and repairable by scanning
+retained run summaries.