Governance Events (Plugin + Config Lifecycle)¶

This page defines the machine-checkable governance event contract used for plugin registration/discovery decisions and ConfigManager lifecycle events.

Scope¶

The contracts apply to runtime governance paths under calibrated_explanations.governance.* loggers.

Plugin decision events (calibrated_explanations.governance.plugins) cover:

accepted_registration
skipped_untrusted
skipped_denied
checksum_failure
denied_registration

Config lifecycle events (calibrated_explanations.governance.config) cover:

resolve
export
validation_failure

Event envelope (v1)¶

Plugin schema file: src/calibrated_explanations/schemas/governance_event_schema_v1.json

Required fields:

schema_version
event_id
event_name
decision
identifier
source
trusted
actor
timestamp

Optional audit/context fields:

provider
reason_code
reason
invocation_id
request_id
tenant_id
plugin_identifier
details

Config schema file: src/calibrated_explanations/schemas/governance_config_event_schema_v1.json

Required config fields:

schema_version
event_id
event_name (config.lifecycle)
event_type (resolve | export | validation_failure)
profile_id
config_schema_version
strict
source_count
validation_issue_count
timestamp

Optional config field:

details

Example payload¶

{
  "schema_version": "1.0",
  "event_id": "4f35b20f-3558-4f31-b6fc-04c70f9975f0",
  "event_name": "plugin.registration.decision",
  "decision": "skipped_denied",
  "identifier": "third.party.interval",
  "provider": "third-party-plugin",
  "source": "entrypoint",
  "trusted": false,
  "actor": "load_entrypoint_plugins",
  "reason_code": "denylist",
  "reason": "Plugin identifier is denied via CE_DENY_PLUGIN",
  "timestamp": "2026-03-19T12:34:56.789012+00:00"
}

Example config lifecycle payloads¶

{
  "schema_version": "1.0",
  "event_id": "6106f0aa-2e5d-4a01-a8e4-68a3d4bcbac8",
  "event_name": "config.lifecycle",
  "event_type": "resolve",
  "profile_id": "default",
  "config_schema_version": "1",
  "strict": true,
  "source_count": 4,
  "validation_issue_count": 0,
  "timestamp": "2026-04-08T10:00:00+00:00",
  "details": null
}

{
  "schema_version": "1.0",
  "event_id": "ca594651-8d37-4ddd-a071-bb2bd6f74087",
  "event_name": "config.lifecycle",
  "event_type": "export",
  "profile_id": "default",
  "config_schema_version": "1",
  "strict": true,
  "source_count": 4,
  "validation_issue_count": 0,
  "timestamp": "2026-04-08T10:00:05+00:00",
  "details": {
    "diagnostic_only": true
  }
}

{
  "schema_version": "1.0",
  "event_id": "1ea42ce4-fb09-4d40-8ca8-129ca109c6ac",
  "event_name": "config.lifecycle",
  "event_type": "validation_failure",
  "profile_id": "default",
  "config_schema_version": "1",
  "strict": false,
  "source_count": 2,
  "validation_issue_count": 1,
  "timestamp": "2026-04-08T10:00:09+00:00",
  "details": {
    "location": "pyproject.plugins",
    "issue_count": 1
  }
}

Enterprise ingest mapping¶

For enterprise governance pipelines that use ce.* namespaced telemetry fields, the following mapping is recommended:

decision -> ce.governance.decision
identifier -> ce.governance.plugin_identifier
source -> ce.governance.source
actor -> ce.governance.actor
reason_code -> ce.governance.reason_code
event_id -> ce.governance.event_id
timestamp -> ce.governance.timestamp

Validation and checks¶

Runtime event payloads are validated by calibrated_explanations.governance.events.validate_governance_event.
Config lifecycle payloads are validated by calibrated_explanations.governance.events.validate_config_governance_event.
CI/local quality gate: python scripts/quality/check_governance_event_schema.py.

Config lifecycle notes¶

resolve events are emitted by ConfigManager.from_sources() only.
Direct ConfigManager(...) construction for injection/testing is silent for resolve events.
export events are diagnostic-only until ADR-034 Open Item 2 is closed.
validation_failure events are emitted in both strict and non-strict validation paths.

Data minimization constraints¶

Governance events must not include raw feature vectors, labels, predictions, or full plugin metadata blobs. Keep payloads limited to identifiers, decision metadata, and reason fields needed for audit reconstruction.

Config lifecycle payloads must not include raw config values, environment strings, or raw pyproject payload blobs. In particular, validation_failure details are restricted to location and issue-count metadata (see ADR-034 Open Item 1 in docs/improvement/adrs/ADR-034-centralized-configuration-management.md).

Entry-point tier: Tier 3