Skip to main content

Operations Playbook

This is the practical runbook for common situations in the current repo.

Use it when you are operating Vesanor rather than learning the concepts.

New workspace, no approval yet​

Typical signals:

  • Governance Studio shows a workspace with no active approval
  • zero-config runtime behaves as review-first
  • governanceAttachment may show no_plan

What to do:

  1. Open Governance Studio
  2. Start at Atlas for the workspace-level model
  3. Move into Control if one control path is clearly blocked
  4. Move into Focus when one judgment needs an explicit decision
  5. Check the approval preview
  6. Approve when ready

Approval exists, but runtime is not attaching​

Typical signals:

  • governanceAttachment: fetch_failed
  • governanceAttachment: artifact_invalid
  • governanceAttachment: attachment_failed

What to do:

  1. Check the runtime environment (development, staging, production)
  2. Check whether the hosted governance lookup succeeded
  3. Check whether the approved artifact is valid
  4. Re-approve or repair the underlying approval/artifact path if needed

Treat artifact_invalid differently from no_plan:

  • no_plan means nothing approved yet
  • artifact_invalid means approval exists but the runtime artifact is broken

Approval preview says you are not ready​

Typical signals:

  • approval preview has blockers
  • snapshot is not ready_for_approval
  • approval_state.ready_for_approval is false

What to do:

  1. Stay in the workspace workbench
  2. Review open judgments
  3. Review impact preview / Focus consequence
  4. Clear blockers before retrying approval

The approval path fails closed. It will not “best effort” an approval through blockers.

Conformance findings appear after approval​

Typical signals:

  • conformance findings panel shows findings
  • drift items accumulate for the approved lineage
  • evidence freshness degrades

What to do:

  1. Review the finding against the active approval
  2. Use Atlas / Control / Focus to locate the affected control path and judgment context
  3. Decide whether it indicates:
    • expected evidence drift
    • a draft change
    • loss of confidence in the current approval
  4. If needed, return to review work instead of treating the old approval as current truth forever

Drift and conformance findings are review work. They are not supposed to mutate approval truth in place.

Runtime says compromised​

Typical signals:

  • authorityState: compromised
  • bypass_detected: true

What to do:

  1. Check whether code called the original client directly instead of session.client
  2. Stop treating that session as authoritative
  3. Start a fresh session after fixing the call path

This is a governance integrity problem, not just a warning.

Unresolved receipts exist​

Typical signals:

  • unresolvedReceiptCount > 0
  • status: degraded
  • durability: degraded-local

What to do:

  1. Assume a side effect may already have happened
  2. Reconcile with the control plane before proceeding
  3. Avoid continuing as if the runtime still has clean authority

This is the “ambiguous pending work” state.

No runs yet​

Typical signals:

  • Runs page is empty
  • references do not exist yet
  • baselines page cannot show an active reference

What to do:

  1. Generate real traffic through the wrapped runtime
  2. Verify the integration is actually using session.client
  3. Confirm hosted auth is configured correctly

Without runs, you should not expect references or trustworthy operational comparisons.

References are stale​

Typical signals:

  • References page shows STALE
  • comparisons are advisory
  • no replacement reference is active yet

What to do:

  1. Keep submitting runs with the same relevant configuration
  2. Let a new candidate accumulate successful runs
  3. Promote the replacement when ready, or let the automatic promotion path do its work where applicable

Do not treat stale references as current enforced truth.

Promotion-ready references exist​

Typical signals:

  • a candidate has enough successful runs
  • the references page shows it as ready/promotable

What to do:

  1. Confirm the candidate is the one you actually want to trust
  2. Promote if needed from the references surface
  3. Expect older stale references with the same contract hash to retire on promotion

What to check first in any incident​

When something looks wrong, check in this order:

  1. Governance Studio workspace state
  2. Atlas / Control / Focus state for the affected workspace
  3. Approval preview / active approval state
  4. ReplayHealthSnapshot
  5. Runs page
  6. References page

That order usually tells you whether the issue is:

  • authoring/readiness
  • approval/artifact
  • runtime attachment
  • execution history
  • trust posture