Skip to content

Governance templates

Definition

A governance template is a named, versioned rule template owned by a tenant. Each template records which EU AI Act / GDPR obligations it covers and how those obligations map onto controls the gateway already enforces — guardrail configurations, the project three-tier policy, and tenant retention/logging switches. Templates form a per-tenant catalogue: the reusable building blocks of the KI-Governance layer.

Function

The catalogue is the data foundation of KI-Governance. A template names an obligation set and carries an opaque mapping onto existing config leaves, so a tenant can keep its regulatory intent in one versioned, auditable place instead of re-deriving it per gateway. The catalogue stores and versions these templates; it does not itself change any live configuration.

The apply and diff-preview engine compares a template's target controls against a gateway's current effective configuration and applies them (see below). The admin UI for browsing, creating, and applying templates is the Governance view.

Apply and diff engine

The engine reads a template's target_controls and, for a chosen gateway, either previews (diff) or performs (apply) the change. It never re-implements policy: it folds a hypothetical candidate configuration through the same resolver the live request path uses, then reports what the effective configuration would become — so a preview can never disagree with what a subsequent load produces.

target_controls shape

target_controls is a JSON array; each element maps one obligation onto one config leaf:

[
  { "leaf": "eu_region_routing", "value": true, "obligation": "eu-ai-act-art-10" },
  { "leaf": "pii_masking_enforced", "value": true, "obligation": "gdpr-art-32" }
]
  • leaf (required string) — the config leaf to govern. Must be one of the governable leaves below; an unknown leaf is rejected (the payload is untrusted and validated fail-closed — a template can never write an arbitrary key into a gateway config).
  • value (required) — the target value. For every governable leaf today this must be a real JSON boolean; a number, string, or null is rejected.
  • obligation (optional string) — provenance, carried through to the diff.

Extra element keys are ignored (forward-compatible). The payload evolves by additive optional fields; it is not tied to the template's template_version (which is a catalogue revision, not a payload schema version). A non-array payload, a non-object element, a missing/mistyped field, or a duplicate leaf is rejected with an error and no change is made.

Governable leaves

The engine governs three top-level residency / PII controls: eu_region_routing, provider_allowlist_enforced, and pii_masking_enforced. Nested leaves (for example a guardrail sub-setting such as the illustrative guardrail.human_review), list controls (the provider allowlist itself), and retention/logging switches are a planned extension; until then they are rejected rather than silently accepted. Seed-template authors should therefore target the three flat leaves above with an explicit boolean value — an obligation-to-leaf mapping without a value, or one naming a not-yet-governable leaf, is not applyable today.

The residency floor is never lowered

Apply may tighten a residency control but can never lower it below the tenant's armed floor. Each control in the diff carries a status:

  • apply — a gateway-level control whose effective value will change to the requested value (persisted).
  • unchanged — already at the requested value (not persisted; re-applying a template is a no-op).
  • blocked_by_floor — a gateway-level control (eu_region_routing, provider_allowlist_enforced) whose requested value would drop below the enforced floor — the tenant's armed floor or the deployment-wide residency backstop (applied by your operator on a sovereign deployment); the floor clamps it, the resulting value stays at the enforced value, and the downgrade is not persisted. Status is read through the same enforcement authority the request path uses, so a preview can never disagree with runtime enforcement.
  • tenant_scoped — pii_masking_enforced is controlled at the tenant level, so a gateway apply can neither raise nor lower it; the request is reported and not persisted (enforce PII on the tenant instead).

Only apply controls are written, onto the gateway's own configuration. Because the residency floor is re-applied on every configuration load, a stored configuration can never present an effective value below the tenant floor.

Deny-all safety

If applying provider_allowlist_enforced: true would leave the gateway enforcing the provider allowlist with no usable providers (an absent, empty, or all-invalid list) — which would refuse all inference — the diff surfaces a warning and apply refuses with an error, so a template can never take a gateway offline. Re-arming a gateway that is already in that state is not refused (the apply did not introduce it).

Rules and facts

  • Per-tenant and isolated. Every template belongs to exactly one tenant. A template is only ever visible to, and mutable by, its owning tenant — there is no cross-tenant read or write path.
  • Versioned identity. A template is identified within its tenant by a stable key plus an integer version. The same key can carry multiple versions; a given key-and-version pair is unique per tenant.
  • Authoritative flag. Each template carries an is_authoritative flag that defaults to false. The flag marks whether the template's obligation-to-control mapping is compliance-signed content. First-party templates ship non-authoritative until a compliance owner signs off; the flag is data-model plumbing, and a non-authoritative template makes no first-party compliance claim.
  • Soft delete. Deleting a template is reversible-safe at the storage layer: the row is tombstoned, not physically removed, so it immediately stops appearing in the catalogue while its key-and-version slot stays reserved. Reusing a retired key is done by publishing a new version.
  • Auditable content, purged on offboarding. A template's name and obligation/control mapping are tenant governance content. When a tenant is offboarded, its templates are removed as part of the irreversible tenant purge, leaving no residue.
  • Guardrails — one of the control surfaces a template's mapping targets.
  • EU data residency — the residency floor that a governance apply flow must respect.
  • Multi-tenancy — the tenant isolation model the catalogue inherits.