v1.0.3

Governed Replay Walkthrough

A deterministic, public-API path through observed assets, immutable data, evidence, replay preparation, lineage, and audit-ready output.

What you will complete

This walkthrough follows one governed path without using a privileged demo database or repository calls. It observes prompt and model runtime identity, selects immutable evaluation data and replayable source evidence, inspects evaluation and governance evidence, prepares a replay, and opens the resulting assets in Studio and the ontology graph.

Observed assets→

Immutable dataset→

Evidence→

Prepared replay→

Lineage + manifest

Prerequisites

Run this from a AI Governance Platform repository clone with Python 3.12+, uv, and Docker available. The supported local startup path provisions Keycloak, discovers service-account subjects, starts the control plane and workers, and seeds the scenario evidence.

bash

./servers.sh

No exported bearer token

The walkthrough exchanges its configured AI_GOVERNANCE_OAUTH_* client credentials in memory. Local startup generates .env.oauth.generated. Do not export AI_GOVERNANCE_TOKEN; the walkthrough ignores it. Pass --token only when you deliberately want to override the workload identity.

Guided Path Run

bash

uv run ai-governance walkthrough governed-replay

The command completes these public API actions in order:

Observe a stable prompt identity and optional protected content hash.
Observe the model provider, revision, and runtime configuration.
Select the registered immutable evaluation dataset.
Select a replayable source workflow execution.
Inspect baseline evaluation and governance-decision evidence.
Prepare a replay using the normal replay API and idempotency key.
Inspect the bounded ontology neighbourhood for the observed prompt version.

walkthrough-manifest.json

{
  "api_version": "v1",
  "completed_at": "2026-07-21T03:36:28.849982+00:00",
  "created_assets": [
    "prompt:4c5a044b-8eb4-531f-bee4-38c75c32e831",
    "model:1f441b88-28ad-58f3-8185-0f5175103633",
    "replay:ed169549-ef95-4c8e-997a-0ffbfe782f0c"
  ],
  "failure": null,
  "manifest_path": "/AI Governance Control Plane/.ai-governance/walkthroughs/governed-replay-20260721T033628Z-walkthrough-5fd7611d7e66.json",
  "organization_id": "org_default",
  "outcome": "COMPLETED",
  "project_id": "project_default",
  "resources": {
    "baseline_evaluation_id": "demo-source-evaluation-01",
    "dataset_id": "demo-dataset-evaluation",
    "decision_id": "decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7",
    "model_id": "1f441b88-28ad-58f3-8185-0f5175103633",
    "prompt_id": "4c5a044b-8eb4-531f-bee4-38c75c32e831",
    "replay_id": "ed169549-ef95-4c8e-997a-0ffbfe782f0c",
    "source_execution_id": "demo-source-execution-01"
  },
  "run_id": "walkthrough-5fd7611d7e66",
  "scenario": {
    "description": "Observe the exact prompt and model evidence, select immutable evaluation and execution records, inspect governance evidence, and prepare a replay through AI Governance Platform's public REST API.",
    "title": "Governed Replay Walkthrough"
  },
  "selected_assets": [
    "dataset:demo-dataset-evaluation",
    "execution:demo-source-execution-01",
    "decision:decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7"
  ],
  "started_at": "2026-07-21T03:36:28.775955+00:00",
  "steps": [
    {
      "action": "Observe prompt identity",
      "endpoint": "POST /api/v1/prompts/observations",
      "inspect_url": "http://localhost:3000/assets/prompts/4c5a044b-8eb4-531f-bee4-38c75c32e831",
      "result": {
        "name": "walkthrough-support-assistant",
        "prompt_id": "4c5a044b-8eb4-531f-bee4-38c75c32e831",
        "provenance": "OBSERVED",
        "version": "v1"
      },
      "status": "COMPLETED",
      "step_id": "observe_prompt"
    },
    {
      "action": "Observe model runtime configuration",
      "endpoint": "POST /api/v1/models/observations",
      "inspect_url": "http://localhost:3000/assets/models/1f441b88-28ad-58f3-8185-0f5175103633",
      "result": {
        "model_id": "1f441b88-28ad-58f3-8185-0f5175103633",
        "model_name": "walkthrough-general",
        "provenance": "OBSERVED",
        "provider": "mock",
        "version": "2026.07"
      },
      "status": "COMPLETED",
      "step_id": "observe_model"
    },
    {
      "action": "Select immutable evaluation dataset",
      "endpoint": "GET /api/v1/datasets",
      "inspect_url": "http://localhost:3000/assets/datasets/demo-dataset-evaluation",
      "result": {
        "checksum": "demo-evaluation-v1-checksum",
        "dataset_id": "demo-dataset-evaluation",
        "name": "Demo Evaluation Set",
        "record_count": 120,
        "version": "v1.0"
      },
      "status": "COMPLETED",
      "step_id": "select_dataset"
    },
    {
      "action": "Select replayable workflow execution",
      "endpoint": "GET /api/v1/replay-executions/search",
      "inspect_url": "http://localhost:3000/replay-executions/demo-source-execution-01",
      "result": {
        "execution_id": "demo-source-execution-01",
        "replayable": true,
        "workflow_name": "Customer support resolution",
        "workflow_version": "2026.03"
      },
      "status": "COMPLETED",
      "step_id": "select_execution"
    },
    {
      "action": "Inspect baseline evaluation evidence",
      "endpoint": "GET /api/v1/evaluations/history/demo-source-execution-01",
      "inspect_url": "http://localhost:3000/replay-executions/demo-source-execution-01",
      "result": {
        "evaluation_count": 1,
        "execution_id": "demo-source-execution-01"
      },
      "status": "COMPLETED",
      "step_id": "inspect_baseline_evaluation"
    },
    {
      "action": "Inspect governance decision evidence",
      "endpoint": "GET /api/v1/decisions/decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7/detail",
      "inspect_url": "http://localhost:3000/decisions/decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7",
      "result": {
        "audit_record_count": 1,
        "decision_id": "decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7",
        "status": "APPROVED"
      },
      "status": "COMPLETED",
      "step_id": "inspect_decision"
    },
    {
      "action": "Prepare governed replay from immutable source evidence",
      "endpoint": "POST /api/v1/replays",
      "inspect_url": "http://localhost:3000/replays/ed169549-ef95-4c8e-997a-0ffbfe782f0c",
      "result": {
        "mode": "FULL",
        "replay_id": "ed169549-ef95-4c8e-997a-0ffbfe782f0c",
        "source_execution_id": "demo-source-execution-01",
        "status": "COMPLETED"
      },
      "status": "COMPLETED",
      "step_id": "create_replay"
    },
    {
      "action": "Queue replay execution",
      "endpoint": "POST /api/v1/replays/ed169549-ef95-4c8e-997a-0ffbfe782f0c/submit",
      "inspect_url": "http://localhost:3000/replays/ed169549-ef95-4c8e-997a-0ffbfe782f0c",
      "result": {
        "reason": "Pass --submit-replay to queue the prepared replay."
      },
      "status": "NOT_REQUESTED",
      "step_id": "submit_replay"
    },
    {
      "action": "Inspect ontology projection",
      "endpoint": "GET /api/v1/ontology/entities/PromptVersion/4c5a044b-8eb4-531f-bee4-38c75c32e831/neighbourhood",
      "inspect_url": "http://localhost:3000/graph?entityType=PromptVersion&entityId=4c5a044b-8eb4-531f-bee4-38c75c32e831&depth=3",
      "result": {
        "node_count": 7,
        "relationship_count": 0
      },
      "status": "COMPLETED",
      "step_id": "inspect_lineage"
    }
  ],
  "tenant_id": "org_default/project_default",
  "urls": {
    "dataset": "http://localhost:3000/assets/datasets/demo-dataset-evaluation",
    "decision": "http://localhost:3000/decisions/decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7",
    "lineage": "http://localhost:3000/graph?entityType=PromptVersion&entityId=4c5a044b-8eb4-531f-bee4-38c75c32e831&depth=3",
    "model": "http://localhost:3000/assets/models/1f441b88-28ad-58f3-8185-0f5175103633",
    "prompt": "http://localhost:3000/assets/prompts/4c5a044b-8eb4-531f-bee4-38c75c32e831",
    "replay": "http://localhost:3000/replays/ed169549-ef95-4c8e-997a-0ffbfe782f0c",
    "source_execution": "http://localhost:3000/replay-executions/demo-source-execution-01"
  },
  "walkthrough_id": "governed-replay"
}

The local scenario is deliberately idempotent. Re-running it reuses the same observed prompt/model identities and prepared replay rather than leaving yesterday’s demo records behind.

Interactive Quest Mode

For a guided developer experience, use the opt-in retro-platform theme. It presents each evidence check as a level, then closes with a mission summary and a learning milestone. The visual treatment is original and does not use Nintendo artwork, music, sprites, or branding.

bash

uv run ai-governance walkthrough governed-replay --interactive --theme retro

The only prompts are optional choices: source execution selection, replay submission, Studio-link actions, and aged local checkpoint cleanup. At a Studio link, press O to open it, C to copy its URL, or N to continue. Add --no-color for terminals where colour is not appropriate.

Inspect Outcome

The human-readable output contains direct Studio links for each durable resource. Follow them to inspect the Prompt Catalog, Model Catalog, Dataset Registry, source execution, decision, replay, and ontology projection. The selected asset version—not merely its display name—is the unit of lineage.

walkthrough-manifest.json

{
  "dataset": "http://localhost:3000/assets/datasets/demo-dataset-evaluation",
  "decision": "http://localhost:3000/decisions/decision:Candidate:candidate-1:APPROVE:6b5c8da0340292f7",
  "lineage": "http://localhost:3000/graph?entityType=PromptVersion&entityId=4c5a044b-8eb4-531f-bee4-38c75c32e831&depth=3",
  "model": "http://localhost:3000/assets/models/1f441b88-28ad-58f3-8185-0f5175103633",
  "prompt": "http://localhost:3000/assets/prompts/4c5a044b-8eb4-531f-bee4-38c75c32e831",
  "replay": "http://localhost:3000/replays/ed169549-ef95-4c8e-997a-0ffbfe782f0c",
  "source_execution": "http://localhost:3000/replay-executions/demo-source-execution-01"
}

The final JSON manifest is written under .ai-governance/walkthroughs/. It contains the exact tenant, API version, completed step status, prompt, model, dataset, execution, evaluation, decision, and replay IDs, plus deep links for debugging and handoff.

Submit a Replay Deliberately

The default walkthrough stops after replay preparation. This keeps onboarding safe: preparation is durable, but worker execution is an explicit action.

bash

uv run ai-governance walkthrough governed-replay --submit-replay

Queuing a replay does not imply that execution, evaluation, comparison, or drift has finished. Those results appear only after the regular worker lifecycle has produced them.

A prepared replay may not be ready to submit

A replay can be prepared successfully while a required approval, projection, or worker precondition is still pending. In interactive mode, a rejected submission is reported in the final scorecard and the walkthrough preserves its manifest and prepared replay for inspection; it does not hide the evidence or claim a queued job.

Automation and Release Smoke Tests

bash

uv run ai-governance walkthrough governed-replay \
  --non-interactive \
  --output-json \
  --manifest artifacts/governed-replay-manifest.json

AI_GOVERNANCE_SMOKE_API_URL=http://localhost:8000 \
AI_GOVERNANCE_SMOKE_STUDIO_URL=http://localhost:3000 \
uv run python smoke_tests/smoke_governed_replay_walkthrough.py

The smoke script invokes the installed CLI twice and verifies stable resource IDs, manifest fields, and Studio deep links. It remains persistence-neutral: the same public path is valid for SQLite and PostgreSQL.

Recovery and Cleanup

The manifest is checkpointed after every successful step. If a request fails, the partial manifest records the resources already resolved; rerun the command after fixing the dependency or credentials. The public API idempotency boundary prevents duplicate walkthrough assets.

bash

# Preview local manifests older than 14 days
uv run ai-governance walkthrough cleanup --older-than-days 14

# Remove only local .ai-governance/walkthroughs manifests
uv run ai-governance walkthrough cleanup --older-than-days 14 --apply

What the walkthrough does not do

The CLI does not bypass RBAC, query persistence directly, or recreate governance logic. It does not claim that a replay, evaluation, comparison, drift result, or ontology projection exists until the standard platform has produced it. This is a product path, not a disguised test harness.

Continue with the Asset Catalogs guide for ownership and immutable dataset artifacts, or Replay Management for the full worker lifecycle.