Release Intelligence

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Release Intelligence gives you structured answers to two questions before you promote or roll back a release:

1. How does this release differ from another? — binding changes, evaluation regressions, and execution metrics across three structured dimensions.
2. What else does this asset touch? — which releases and workloads reference a given asset, and which of those are currently active.

Release cockpit

The cockpit is the single read that answers “is this release clear to promote?”. It aggregates the release’s bindings, evaluation results, evidence summary, rollout lane health, rollback recommendation, cost delta versus the superseded release, blast radius, and open recommendations into one response.

GET /v1/releases/{release_id}/cockpit

Every section carries an available flag and an unavailable_reason. Sections you lack permission for (for example cost without cost.view) degrade to available: false with unavailable_reason: "permission_denied" rather than failing the whole read, and the cockpit itself requires release.view on the release’s workspace, so it can never expose another tenant’s release.

Read it from the portal (the cockpit summary above the release detail tabs), the SDK, or the CLI:

cockpit = await client.releases.get_cockpit(release_id)
if not cockpit["cost"]["available"]:
    print("cost section:", cockpit["cost"]["unavailable_reason"])

orqestractl release cockpit <release_id>

Promotion stays a governed lifecycle action: the cockpit informs the decision, but a release still advances through review_ready → approved → active via orqestractl release transition (or the portal), never directly from the cockpit read.

Release evidence proof-pack export

After a release evidence bundle has been enriched, operators can export a bounded JSON proof pack for review or procurement workflows.

POST /v1/releases/{release_id}/evidence-bundle/export

The export resolves the owning workspace from the release, requires release.view there, and returns schema-versioned JSON with release metadata, approval timeline, evaluation outcomes, execution cohort metrics, decision provenance, supersession chain, bounded run manifests, and a manifest of section counts. Run manifests give each exported experiment or evaluation run a compact reproducibility record: run/outcome identifiers, release and workload target, suite version, role attributions, config references, caveat flags, and linked evidence refs. Raw judge payloads, prompt/response transcripts, and broad trace exhaust are not exported. Timestamped section records and nested execution samples outside --window-days are omitted before the per-section cap is applied; the manifest reports top-level section omissions and nested execution-sample omissions separately. Aggregate cohort metrics keep the source window from the enriched evidence bundle. It uses the same DSAR-grade redaction contract as subject-rights exports: token-like values and secret-keyed fields are masked before they leave the API.

CLI and SDK surfaces expose the same export:

orqestractl release evidence-bundle-export <release_id> --window-days 30

proof_pack = await client.releases.export_evidence_bundle(release_id, window_days=30)
print(proof_pack["manifest"]["totalRecords"])

Release comparison

Compare any two releases to understand the impact of moving between them.

POST /v1/releases/compare

Request body:

{
  "release_a_id": "r1a2b3c4-0000-0000-0000-000000000009",
  "release_b_id": "r1a2b3c4-0000-0000-0000-000000000010"
}

The response is structured across three dimensions.

Binding diff

Which asset-version bindings were added, removed, or changed between the two releases.

{
  "binding_diff": [
    {
      "role": "prompt_template",
      "asset_slug": "support-prompt",
      "from_version": "v1",
      "to_version": "v2",
      "change_type": "changed"
    },
    {
      "role": "guardrail",
      "asset_slug": "pii-guardrail",
      "from_version": null,
      "to_version": "v1",
      "change_type": "added"
    }
  ]
}

Evaluation diff

Pass-rate delta across evaluation gate results linked to each release. A negative delta is a regression; a positive value is an improvement.

{
  "eval_diff": [
    {
      "suite_slug": "content-safety",
      "pass_rate_a": 0.97,
      "pass_rate_b": 0.94,
      "delta": -0.03
    },
    {
      "suite_slug": "latency-p95",
      "pass_rate_a": 0.88,
      "pass_rate_b": 0.93,
      "delta": 0.05
    }
  ]
}

Execution metrics

Aggregate runtime metrics for each release.

{
  "metrics_a": {
    "execution_count": 14200,
    "error_rate": 0.012,
    "avg_latency_ms": 320,
    "total_cost_usd": 142.5
  },
  "metrics_b": {
    "execution_count": 0,
    "error_rate": 0.0,
    "avg_latency_ms": null,
    "total_cost_usd": null
  }
}

metrics_b fields are null until the release accumulates execution history. Both metrics_a and metrics_b may be null if no execution data exists for that release.

Blast radius

Understand the downstream impact before updating or deprecating an asset.

GET /v1/assets/{id}/blast-radius

The response lists every release that references the asset (through any binding role) and groups them by workload, with active releases sorted first.

{
  "asset_id": "a1a2b3c4-0000-0000-0000-000000000001",
  "asset_slug": "support-prompt",
  "asset_kind": "prompt_template",
  "total_affected_releases": 4,
  "total_affected_workloads": 2,
  "affected_releases": [
    {
      "release_id": "r1a2b3c4-0000-0000-0000-000000000010",
      "workload_id": "w1a2b3c4-0000-0000-0000-000000000001",
      "workload_slug": "customer-support-bot",
      "environment": "production",
      "state": "active",
      "role": "prompt_template",
      "version_label": "v2"
    },
    {
      "release_id": "r1a2b3c4-0000-0000-0000-000000000009",
      "workload_id": "w1a2b3c4-0000-0000-0000-000000000001",
      "workload_slug": "customer-support-bot",
      "environment": "production",
      "state": "superseded",
      "role": "prompt_template",
      "version_label": "v1"
    }
  ],
  "affected_workloads": [
    {
      "workload_id": "w1a2b3c4-0000-0000-0000-000000000001",
      "slug": "customer-support-bot",
      "active_release_count": 1,
      "total_release_count": 2
    },
    {
      "workload_id": "w2a2b3c4-0000-0000-0000-000000000002",
      "slug": "internal-knowledge-bot",
      "active_release_count": 1,
      "total_release_count": 2
    }
  ]
}

affected_releases is sorted: active releases appear first within each workload group, then by lifecycle state recency.

Portal

Compare tab on release detail

The Compare tab on the release detail view includes:

• A release selector to choose the counterpart for comparison (defaults to the predecessor release).
• A binding diff panel grouped by role, with added/removed/changed entries and version labels.
• An evaluation diff table sorted by magnitude of delta, with color coding for regressions (red) and improvements (green).
• An execution metrics panel with side-by-side values for each release.

Impact tab on asset detail

The Impact tab on the asset detail view shows the blast radius response as:

• A summary banner: “This asset is referenced by N releases across M workloads, including X active releases.”
• A grouped list of affected releases with lifecycle state badges, sorted active-first.
• A workload summary table with active release counts.

SDK

from orqestra_sdk import OrqestraClient
 
async with OrqestraClient() as client:
    # Compare two releases
    comparison = await client.releases.compare(
        "r1a2b3c4-0000-0000-0000-000000000009",
        "r1a2b3c4-0000-0000-0000-000000000010",
    )
 
    for entry in comparison["binding_diff"]:
        print(entry["role"], entry["change_type"], entry["from_version"], "->", entry["to_version"])
 
    for entry in comparison["eval_diff"]:
        print(entry["suite_slug"], entry["delta"])
 
    print(comparison["metrics_a"]["error_rate"])
    print(comparison["metrics_b"]["error_rate"])
 
    # Check blast radius before updating an asset
    blast = await client.assets.blast_radius("a1a2b3c4-0000-0000-0000-000000000001")
 
    print(f"Affected: {blast['total_affected_releases']} releases")
    for workload in blast["affected_workloads"]:
        print(workload["slug"], workload["active_release_count"], "active")
 
    # Export the minimized release evidence proof pack.
    proof_pack = await client.releases.export_evidence_bundle(
        "r1a2b3c4-0000-0000-0000-000000000010",
        window_days=30,
    )
    print(proof_pack["packType"], proof_pack["manifest"]["totalRecords"])
 
    # Persist an operator proof pack and verify/fetch it later.
    receipt = await client.releases.persist_evidence_bundle_proof_pack(
        "r1a2b3c4-0000-0000-0000-000000000010",
        window_days=30,
    )
    print(receipt["proofPackId"], receipt["objectSha256"], receipt["retentionMode"])
 
    page = await client.releases.list_evidence_bundle_proof_packs(
        "r1a2b3c4-0000-0000-0000-000000000010",
    )
    fetched = await client.releases.get_evidence_bundle_proof_pack(
        "r1a2b3c4-0000-0000-0000-000000000010",
        page["items"][0]["proofPackId"],
    )
    print(fetched["proofPack"]["packType"])

CLI

Compare two releases

orqestractl release compare <release-a-id> <release-b-id>

Output sections:

BINDING DIFF
  changed: prompt_template (v1 -> v2)
  added:   guardrail (v1)

EVALUATION DIFF
  content-safety    0.97 -> 0.94   -0.03  regression
  latency-p95       0.88 -> 0.93   +0.05  improvement

EXECUTION METRICS
  release_a: 14200 executions, 1.2% errors, avg 320ms, $142.50
  release_b: no execution history yet

Add --json for structured output.

Asset blast radius

orqestractl asset blast-radius <asset-id>

Output:

AFFECTED RELEASES: 4 across 2 workloads

customer-support-bot
  r1a2b3c4  production  active      prompt_template  v2
  r1a2b3c4  production  superseded  prompt_template  v1

internal-knowledge-bot
  r2a2b3c4  staging     active      prompt_template  v2
  r3a2b3c4  development draft       prompt_template  v2

Add --json for machine-readable output.

Persist and fetch a proof pack

orqestractl release evidence-bundle-persist <release-id> --window-days 30
orqestractl release evidence-bundle-list <release-id>
orqestractl release evidence-bundle-fetch <release-id> <proof-pack-id>

Custody for reviewed documentation

Documentation snapshot receipts preserve a reviewed file supplied by an external estate workflow. The receipt records an opaque systemRef, server computed byte digest and size, the release’s asset, connection, and runtime version-pin hashes, and the storage retention acknowledgement. It does not fetch the reference, model the external system, or attest that a review or a particular retention mode was completed. Each submission creates a new receipt; later release or source changes do not rewrite its pins or bytes.

Save the exact version context reviewed with the documentation file. Persist submits those saved pins unchanged; if a release or source changed after review, the server rejects the request rather than replacing the reviewed context with newer pins. The saved context is also bound to the file’s SHA-256 so the CLI refuses to submit file bytes changed after that context was saved:

orqestractl release documentation-snapshot-context <release-id> \
  --input-file reviewed.md \
  --output-file reviewed-context.json
orqestractl release documentation-snapshot-persist <release-id> \
  --system-ref 'estate:opaque-system-id' --input-file reviewed.md \
  --review-context-file reviewed-context.json
orqestractl release documentation-snapshot-list <release-id>
orqestractl release documentation-snapshot-fetch <release-id> <snapshot-id> \\
  --output-file restored.md

The SDK exposes the same context, persist, list, and verified fetch operations. The fetch command writes the original bytes to the requested file after the server verifies the stored digest and size. Keep the returned receipt with the external review record; it is separate from execution evidence proof packs.

An approved AI Estate documentation revision can be stored through this custody path: orqestractl estate docs snapshot <doc-id> --revision <n> fetches the deterministic payload, creates the receipt above with your own release permissions, and then links the receipt to the revision after Estate verifies its digest, systemRef and version pins. Estate never writes to the release record itself. The documentation screen shows when the release or a bound source has changed since the latest linked snapshot.

Related guides

• Releases
• Assets
• Evidence Graph