generated from coulomb/repo-seed
115 lines
3.5 KiB
Markdown
115 lines
3.5 KiB
Markdown
---
|
|
id: GUIDE-BOARD-WP-0006
|
|
type: workplan
|
|
title: "Service Artifact Access And Durable Run Index"
|
|
repo: guide-board
|
|
domain: markitect
|
|
status: active
|
|
owner: codex
|
|
planning_priority: medium
|
|
planning_order: 6
|
|
created: "2026-05-15"
|
|
updated: "2026-05-15"
|
|
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: todo
|
|
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.
|
|
|
|
## D6.2 - Service Run History And Artifact Endpoints
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0006-T002
|
|
status: todo
|
|
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.
|
|
|
|
## D6.3 - Restart Recovery And Compatibility
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0006-T003
|
|
status: todo
|
|
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.
|
|
|
|
## D6.4 - Container And Service Acceptance Tests
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0006-T004
|
|
status: todo
|
|
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.
|
|
|
|
## 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.
|