artifact-store/docs/pilots/guide-board.md

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:

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:

{
  "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:

artifactstore guide-board ingest /tmp/guide-board-run \
  --schema schemas/guide-board.run.v1.json

Output is 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:

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:

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:

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:

cd /home/worsch/artifact-store
cp .env.example .env
make migrate-fresh
make dev

3. Register the schema and ingest the run:

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:

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:

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.