v1.2.5

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 Kavach 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

./kavach.sh

No exported bearer token

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

Guided Path Run

bash

uv run kavach 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": "/Kavach/.kavach/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 Kavach'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.

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 .kavach/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 kavach 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.

Automation and Release Smoke Tests

bash

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

KAVACH_SMOKE_API_URL=http://localhost:8000 \
KAVACH_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 kavach walkthrough cleanup --older-than-days 14

# Remove only local .kavach/walkthroughs manifests
uv run kavach 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.