ADR-040: SHACL Runtime Enforcement Policy

Status: Accepted
Version: 1.0
Date: 2026-01-15
Related ADRs: ADR-004, ADR-006
Related PRDs: PRD-006, PRD-007, PRD-008

Context

SHACL shapes exist for the Knowledge Graph, but runtime enforcement is inconsistent, fail-open in key paths, and not versioned. This creates silent data quality drift and makes safe rollouts difficult.

Decision

Adopt a fail-closed, context-aware SHACL enforcement policy with a single configuration source of truth and versioned shape loading:

Configuration flags:
- SHACL_ENFORCEMENT_ENABLED (default: true)
- SHACL_ENFORCEMENT_CONTEXTS (CSV, empty = all)
- SHACL_MAINTENANCE_MODE (default: false)
- SHACL_SHAPES_VERSION (default: v1)
Validation contracts return a consistent ValidationResult type and only raise ShaclValidationError when enforcement is enabled, the context is active, and maintenance mode is false.
Shapes are versioned (sea-shapes.vN.shacl) with fallback to sea-shapes.shacl.
Shared constraints live in ontologies/shared/core.shacl and are imported via owl:imports.
Cross-context constraints are annotated with sea:requiresContext and surfaced in diagnostics.

Rationale

Fail-closed enforcement prevents data corruption, while context scoping and maintenance mode allow safe rollout and emergency operations. Versioned shapes enable compatibility management and impact analysis across releases.

Constraints

Validation must be deterministic and cache-safe.
No hidden global configuration reads in runtime code paths.
Diagnostics must be actionable (shape URI, focus node, property path, expected values).

Quality Attributes

Data integrity
Observability
Rollout safety
Determinism

Consequences

Positive

Consistent enforcement guarantees and reproducible validations
Safer rollouts with versioned shapes and impact analysis

Negative

Requires governance process for shared shapes
Increased validation cost mitigated via caching and delta validation

Bounded Contexts Impacted

Semantic Core
Knowledge Graph Service
Governance Runtime