generated from coulomb/repo-seed
Add guide-board pilot ingestion
This commit is contained in:
162
docs/pilots/guide-board.md
Normal file
162
docs/pilots/guide-board.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Guide-Board Pilot
|
||||
|
||||
Status: active pilot
|
||||
Updated: 2026-05-16
|
||||
|
||||
This guide wires the first real producer into artifact-store. A guide-board run
|
||||
directory becomes one artifact package; State Hub records the package identity
|
||||
and manifest digest, but never stores artifact bytes.
|
||||
|
||||
## One-Time Schema Registration
|
||||
|
||||
Start artifact-store and register the pilot metadata schema:
|
||||
|
||||
```sh
|
||||
cd /home/worsch/artifact-store
|
||||
export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
|
||||
export ARTIFACTSTORE_API_TOKEN=dev-token
|
||||
python3 scripts/register-guide-board-schema.py
|
||||
```
|
||||
|
||||
The script posts this payload shape to `POST /metadata-schemas`:
|
||||
|
||||
```json
|
||||
{
|
||||
"slug": "guide-board.run.v1",
|
||||
"json_schema": {
|
||||
"$id": "artifactstore:schemas:guide-board.run.v1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Ingest A Run
|
||||
|
||||
The local CLI path opens the configured database and storage backend directly:
|
||||
|
||||
```sh
|
||||
artifactstore guide-board ingest /tmp/guide-board-run \
|
||||
--schema schemas/guide-board.run.v1.json
|
||||
```
|
||||
|
||||
Output is JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"package_id": "00000000-0000-0000-0000-000000000000",
|
||||
"manifest_digest": "blake3:...",
|
||||
"file_count": 8,
|
||||
"reused_existing": false
|
||||
}
|
||||
```
|
||||
|
||||
The helper is idempotent by guide-board `run_id`. Re-ingesting the same
|
||||
finalized run returns the existing package id and manifest digest with
|
||||
`reused_existing: true`.
|
||||
|
||||
## State Hub Linkage
|
||||
|
||||
After ingest, record a progress event with structured `detail`. This is the
|
||||
canonical linkage shape:
|
||||
|
||||
```sh
|
||||
curl -s -X POST "$STATE_HUB_URL/progress/" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"event_type": "artifact_link",
|
||||
"author": "artifact-store",
|
||||
"workstream_id": "701c4d8c-5cf4-4a4a-ab60-1dcae53fe771",
|
||||
"task_id": "bffa3573-4a1f-4c12-8c73-6d55bd8f6297",
|
||||
"summary": "guide-board run <run_id> artifacts stored in artifact-store package <package_id>",
|
||||
"detail": {
|
||||
"producer": "guide-board",
|
||||
"artifact_store_api_url": "http://127.0.0.1:8000",
|
||||
"run_dir": "/tmp/guide-board-run",
|
||||
"run_id": "<run_id>",
|
||||
"target_profile_ref": "<target>",
|
||||
"assessment_profile_ref": "<assessment>",
|
||||
"result_status": "<status>",
|
||||
"package_id": "<package_id>",
|
||||
"manifest_digest": "<manifest_digest>",
|
||||
"file_count": 8,
|
||||
"retention_class": "release-evidence"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Use the checked-in helper to build the same event from environment variables:
|
||||
|
||||
```sh
|
||||
export STATE_HUB_URL=http://127.0.0.1:8000
|
||||
export STATE_HUB_WORKSTREAM_ID=701c4d8c-5cf4-4a4a-ab60-1dcae53fe771
|
||||
export STATE_HUB_TASK_ID=bffa3573-4a1f-4c12-8c73-6d55bd8f6297
|
||||
export GUIDE_BOARD_RUN_DIR=/tmp/guide-board-run
|
||||
export ARTIFACTSTORE_INGEST_RESULT_PATH=/tmp/artifactstore-guide-board-ingest.json
|
||||
python3 scripts/link-guide-board-package.py
|
||||
```
|
||||
|
||||
The helper posts only identifiers, summary metadata, and links. Artifact bytes
|
||||
remain in artifact-store storage backends.
|
||||
|
||||
## Real Producer Smoke
|
||||
|
||||
This path uses the real guide-board core and the external `open-cmis-tck`
|
||||
extension. It is expected to complete under five minutes on a developer
|
||||
workstation once Python dependencies and local candidate prerequisites are in
|
||||
place.
|
||||
|
||||
1. Produce a guide-board run:
|
||||
|
||||
```sh
|
||||
cd /home/worsch/guide-board
|
||||
mkdir -p /tmp/guide-board-artifact-store-smoke
|
||||
PYTHONPATH=src python3 -m guide_board \
|
||||
--extension-dir ../open-cmis-tck \
|
||||
run \
|
||||
--target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
|
||||
--assessment ../open-cmis-tck/profiles/assessments/cmis-browser-baseline.json \
|
||||
--output-dir /tmp/guide-board-artifact-store-smoke/open-cmis-tck-baseline
|
||||
```
|
||||
|
||||
2. Start artifact-store:
|
||||
|
||||
```sh
|
||||
cd /home/worsch/artifact-store
|
||||
cp .env.example .env
|
||||
make migrate-fresh
|
||||
make dev
|
||||
```
|
||||
|
||||
3. Register the schema and ingest the run:
|
||||
|
||||
```sh
|
||||
export ARTIFACTSTORE_API_TOKEN=dev-token
|
||||
python3 scripts/register-guide-board-schema.py
|
||||
artifactstore guide-board ingest \
|
||||
/tmp/guide-board-artifact-store-smoke/open-cmis-tck-baseline \
|
||||
--schema schemas/guide-board.run.v1.json \
|
||||
> /tmp/artifactstore-guide-board-ingest.json
|
||||
cat /tmp/artifactstore-guide-board-ingest.json
|
||||
```
|
||||
|
||||
4. Verify the manifest:
|
||||
|
||||
```sh
|
||||
PACKAGE_ID=$(python3 -c 'import json; print(json.load(open("/tmp/artifactstore-guide-board-ingest.json"))["package_id"])')
|
||||
artifactstore manifest "$PACKAGE_ID"
|
||||
```
|
||||
|
||||
5. Record State Hub linkage:
|
||||
|
||||
```sh
|
||||
export STATE_HUB_URL=http://127.0.0.1:8000
|
||||
export STATE_HUB_WORKSTREAM_ID=701c4d8c-5cf4-4a4a-ab60-1dcae53fe771
|
||||
export STATE_HUB_TASK_ID=bffa3573-4a1f-4c12-8c73-6d55bd8f6297
|
||||
export GUIDE_BOARD_RUN_DIR=/tmp/guide-board-artifact-store-smoke/open-cmis-tck-baseline
|
||||
export ARTIFACTSTORE_INGEST_RESULT_PATH=/tmp/artifactstore-guide-board-ingest.json
|
||||
python3 scripts/link-guide-board-package.py
|
||||
```
|
||||
|
||||
To smoke the storage swap after enabling WP-0004 S3 settings, keep the same
|
||||
guide-board ingest command and set
|
||||
`ARTIFACTSTORE_STORAGE_BACKEND_ROUTES='guide-board:release-evidence=s3,*:*=local'`
|
||||
before starting artifact-store.
|
||||
Reference in New Issue
Block a user