guide-board/workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md

id, type, title, repo, domain, status, owner, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	repo	domain	status	owner	planning_priority	planning_order	created	updated	state_hub_workstream_id
GUIDE-BOARD-WP-0006	workplan	Service Artifact Access And Durable Run Index	guide-board	markitect	completed	codex	medium	6	2026-05-15	2026-05-16	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

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

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

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

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.