---
id: GUIDE-BOARD-WP-0006
type: workplan
title: "Service Artifact Access And Durable Run Index"
repo: guide-board
domain: markitect
status: completed
owner: codex
planning_priority: medium
planning_order: 6
created: "2026-05-15"
updated: "2026-05-16"
state_hub_workstream_id: "ba008283-1631-467b-868e-1052c3870ab9"
---

# GUIDE-BOARD-WP-0006: Service Artifact Access And Durable Run Index

## Purpose

Move the local service beyond in-memory job visibility while preserving the CLI
as the execution source of truth. Operators and future UI clients should be able
to discover retained runs, retrieve reports, inspect artifacts, and recover
after service restarts without needing private knowledge of the run directory.

## Background

WP2 intentionally kept service job state in memory and documented run
directories as the durable source. That is a good baseline, but the service
already wraps run start, status, and report retrieval. The next step is to expose
the durable run history and artifact paths directly through service contracts.

## Boundary

This workplan owns local service API and durable run index behavior. It should
not change CLI run semantics, introduce a database dependency, or create a
distributed execution service. Any durable index must be reconstructable from
existing run artifacts.

## D6.1 - Durable Run Index Design

```task
id: GUIDE-BOARD-WP-0006-T001
status: done
priority: high
state_hub_task_id: "4d392fc5-6a1c-46f7-9cbf-6c02bbd744c6"
```

Acceptance:

- Decide whether the service needs a separate durable index file or can rely on
  retained run summaries with helper scans.
- Define reconstruction behavior after service restart.
- Preserve compatibility with existing `retention-summary.json` and run
  directory layout.
- Document the operational tradeoff and failure modes.

Decision:

- Keep the durable index as retained run summaries and helper scans.
- Do not add a separate service index file for the baseline.

Progress:

- Documented reconstruction from `retention-summary.json` files.
- Kept compatibility with older runs that lack newer assessment package or
  submission manifest files.

## D6.2 - Service Run History And Artifact Endpoints

```task
id: GUIDE-BOARD-WP-0006-T002
status: done
priority: high
state_hub_task_id: "8f209920-6b14-4d6f-bfa1-8f1d03bcdbf1"
```

Acceptance:

- Add service endpoints for retained run listing, latest run selection, report
  path lookup, and artifact manifest access.
- Keep endpoint responses aligned with existing CLI `runs` commands.
- Avoid serving arbitrary filesystem paths outside configured run directories.
- Add tests for successful retrieval and path-safety failures.

Progress:

- Added `GET /retained-runs`.
- Added `GET /retained-runs/latest`.
- Added `GET /retained-runs/{run_id}/reports`.
- Added `GET /retained-runs/{run_id}/artifact-manifest`.
- Added path containment checks for report refs and artifact manifest paths.
- Added service tests for retained history retrieval after a fresh service
  process and unsafe artifact path rejection.

## D6.3 - Restart Recovery And Compatibility

```task
id: GUIDE-BOARD-WP-0006-T003
status: done
priority: medium
state_hub_task_id: "0857e7d8-3d23-4426-b7fa-73362d7041a0"
```

Acceptance:

- Prove that a service restart can still expose retained run reports and
  artifacts.
- Keep in-memory job status semantics clear for currently running jobs.
- Add compatibility handling for older run directories that lack newer manifest
  files.
- Update service durability documentation with examples.

Progress:

- Preserved `/runs` as in-memory job history.
- Exposed durable run results through retained-run endpoints after restart.
- Returned a compatibility marker when an older retained run lacks an
  assessment package artifact manifest.
- Updated service durability and local API docs.

## D6.4 - Container And Service Acceptance Tests

```task
id: GUIDE-BOARD-WP-0006-T004
status: done
priority: medium
state_hub_task_id: "900a70fa-65ff-4815-9c0c-31f0da4019f0"
```

Acceptance:

- Add focused service tests for durable run lookup and artifact/report retrieval.
- Extend container or scripted acceptance to prove mounted run directories remain
  readable through service contracts.
- Document service endpoint usage in local and container modes.
- Keep tests dependency-light.

Progress:

- Added dependency-light service tests for durable run lookup, report paths, and
  artifact manifest retrieval.
- Updated container smoke artifact expectations for current run outputs.
- Documented retained-run endpoint usage in local and container modes.

## Definition Of Done

- The local service can expose retained runs and artifacts after restart.
- Endpoint behavior matches CLI run history semantics.
- Filesystem access is constrained to intended run outputs.
- Operators have documented recovery and artifact retrieval paths.