SHACL Enforcement Migration Runbook

Purpose

This runbook defines the phased rollout for SHACL runtime enforcement, including rollback and legacy data handling.

Pre-Deployment Checklist

• Run python tools/kg_validate.py --graph <snapshot|ttl|nt>
• Run python tools/shape_impact_analysis.py --shape-version v1 --graph <snapshot|ttl|nt>
• Confirm SHACL_SHAPES_VERSION aligns with deployed shapes
• Review shape-governance.md approvals for shared shapes

Rollout Phases

Phase 1: Single Context

• Set SHACL_ENFORCEMENT_ENABLED=true
• Set SHACL_ENFORCEMENT_CONTEXTS=semantic-core
• Monitor validation failures and latency for 24 hours

Phase 2: Add Contexts

• Extend SHACL_ENFORCEMENT_CONTEXTS to include the next context (for example, case-management)
• Run impact analysis and resolve violations

Phase 3: Global Enforcement

• Set SHACL_ENFORCEMENT_CONTEXTS= (empty to mean all)
• Maintain monitoring for 72 hours

Maintenance Mode

• Temporary bypass for refactors: SHACL_MAINTENANCE_MODE=true
• Max window: 4 hours
• Violations must still be logged and tracked

Legacy Data Handling

• Mark existing nonconforming entities with sea:legacyData true
• Add sea:migrationDeadline with a target date
• Past deadline: enforcement escalates to error after grace period
• Run just kg-legacy-overdue <graph> to report overdue entities

Rollback

• Set SHACL_ENFORCEMENT_ENABLED=false
• If version regression: revert SHACL_SHAPES_VERSION to last known good
• Re-run python tools/kg_validate.py after rollback

Remediation Guidance

• Use SHACL reports to locate violations by focus node and path
• Apply SPARQL updates to correct the data
• Re-run validation before re-enabling enforcement