Eve library

OSHUN Studio Cross-Domain Entity Model Runbook

Runbook

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0022-oshun-studio-cross-domain-entity-model.md
  • docs/releases/v1/specs/studio-cross-domain-entity-model-dependency-and-data-contract-map.md
  • docs/releases/v1/specs/studio-cross-domain-entity-model-user-journeys-and-edge-cases.md
  • apps/oshun/web/src/components/studio/StudioCrossDomainEntityModelWorkspace.tsx
  • apps/oshun/web/src/analytics/studioCrossDomainEntityModelTelemetry.ts

Purpose#

Define operational ownership, SLOs, incident playbooks, and escalation paths for Studio cross-domain entity model governance workflows.

This document is the execution artifact for OST-00080.

1. Ownership Model#

Surface Primary Owner Backup Owner Dependencies
Entity model workspace route OSHUN Web Platform Web route + analytics contracts
Canonical entity schema governance OSHUN Studio Architecture Domain Integrators schema contracts + compatibility policies
Entity resolution contract validation Navigation Platform Domain Integrators route/action contracts
Relation graph integrity and lineage Domain Integrators + Data Platform SRE graph sync + lineage pipelines
Telemetry and audit pipeline Data Platform SRE analytics sinks + ingestion pipelines

2. Core SLOs#

Metric Target Alert Threshold
Entity-model flow success rate >= 99.0% < 98.0% over 15 min
Envelope validation integrity 100% deterministic any false pass
Resolution-contract coverage 100% governed types covered any missing required mapping
Entity-model flow p95 latency <= 2200ms > 3200ms over 15 min
Entity-model audit completeness >= 99.5% < 99.0% over 15 min

3. Operational Playbooks#

3.1 Canonical Envelope Publish Failures#

Trigger: repeated ENTITY_ENVELOPE_VALIDATION_FAILED outcomes.

Actions:

  1. Inspect envelope diagnostics for required fields and immutable identity constraints.
  2. Validate schema versioning and extension namespace contracts.
  3. Re-run publish in preview with validation logging enabled.
  4. Roll back to the last certified schema bundle if needed.

3.2 Entity Resolution Contract Failures#

Trigger: repeated ENTITY_RESOLUTION_CONTRACTS_FAILED outcomes.

Actions:

  1. Identify entity types missing route/action mappings.
  2. Validate required context contracts (programId, projectId, workspaceId).
  3. Patch missing fallback routes and deterministic action capabilities.
  4. Re-run validation and block promotion until all mappings pass.

3.3 Relation Graph Integrity Failures#

Trigger: repeated ENTITY_RELATION_GRAPH_INTEGRITY_FAILED outcomes.

Actions:

  1. Generate relation diagnostics for cycles and orphaned targets.
  2. Quarantine invalid edges and restore authoritative references.
  3. Re-run lineage continuity checks across all governed domains.
  4. Freeze promotion until relation graph integrity is restored.

3.4 Policy Denial Spike#

Trigger: unexpected increase in ROLE_POLICY_DENIED outcomes.

Actions:

  1. Compare workspace flow policy map against entitlement contracts.
  2. Verify recent identity payload/version changes.
  3. Apply policy hotfix or rollback entitlement drift.
  4. Confirm deny-rate normalization after mitigation.

3.5 Telemetry and Audit Degradation#

Trigger: missing or delayed cross-domain entity-model telemetry events.

Actions:

  1. Validate analytics sink health and queue depth.
  2. Enable degraded-observability warning in workspace.
  3. Reconcile missed events from buffered traces.
  4. Confirm event completeness and SLO recovery.

4. Release Checklist#

  • Validate /studio/cross-domain-entity-model renders and executes required flows.
  • Validate optimistic, error, and retry behavior for each flow.
  • Validate role-policy allow/deny behavior.
  • Validate telemetry/audit emissions and SLO panel updates.
  • Validate integration/e2e/accessibility evidence artifacts.

5. Incident Communication Templates#

Incident Start#

text
[P{severity}] Studio Cross-Domain Entity Model Incident
Detected: {timestamp}
Impact: {envelope/resolution/relation integrity impact}
Suspected cause: {schema regression | contract drift | lineage failure | policy drift}
Owner: {on-call}

Incident Update#

text
[P{severity}] Studio Cross-Domain Entity Model Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {canonicalEnvelopePublish | entityResolutionValidation | relationGraphSync}
ETA: {time}

Incident Resolved#

text
[P{severity}] Studio Cross-Domain Entity Model Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}

6. Escalation Paths#

Area Primary Channel Escalate To
Web runtime and workspace #oshun-web Platform on-call
Schema governance and compatibility #oshun-architecture Architecture council
Route/action resolution contracts #oshun-navigation Navigation architecture lead
Policy and permissions #oshun-security Security lead
Telemetry pipeline and reliability #oshun-data-platform SRE lead

7. Acceptance Criteria (OST-00080)#

OST-00080 is complete only when:

  1. Ownership and decision authority are documented.
  2. Cross-domain entity-model SLOs and alert thresholds are documented.
  3. At least five playbooks are documented for major failure modes.
  4. Release checklist, communication templates, and escalation paths exist.