Cerbi.Governance.Runtime 2.0.43

Cerbi.Governance.Runtime

Real-time governance enforcement and scoring for structured logging in .NET.

Cerbi.Governance.Runtime loads canonical governance profiles, validates structured event fields, annotates records with governance metadata, computes optional score impact, and can ship compact score events asynchronously.

Supported profile documents

FileGovernanceSource supports two document shapes.

Root-level canonical profile

{
  "$schema": "https://schemas.cerbi.io/governance/profile.schema.json",
  "name": "Orders",
  "requiredFields": ["requestId"],
  "fieldTypes": {
    "requestId": "Guid"
  },
  "allowRelax": true
}

Load a root-level profile with the one-argument constructor:

var source = new FileGovernanceSource("cerbi_governance.json");

Legacy wrapper containing canonical profiles

{
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "Orders": {
      "name": "Orders",
      "requiredFields": ["requestId"],
      "fieldTypes": {
        "requestId": "Guid"
      },
      "allowRelax": true
    }
  }
}

Load a wrapped profile with an explicit profile name:

var source = new FileGovernanceSource("cerbi_governance.json", "Orders");

Wrapper-level noncanonical metadata is tolerated. A document that combines LoggingProfiles with canonical root-profile markers is rejected as ambiguous. Wrapped entries must themselves conform to the canonical Profile schema.

Profile selection prefers an exact ordinal name match. When there is no exact match, one case-insensitive match is accepted. Missing or ambiguous matches throw InvalidDataException.

Runtime validation

var validator = new RuntimeGovernanceValidator(
    isEnabled: () => true,
    profileName: "Orders",
    source: new FileGovernanceSource("cerbi_governance.json", "Orders"));

var record = new Dictionary<string, object>
{
    ["requestId"] = Guid.NewGuid(),
    ["Status"] = "Pending"
};

validator.ValidateInPlace(record);

The validator mutates the supplied dictionary in place and can add:

• GovernanceProfileUsed
• GovernanceEnforced
• GovernanceRelaxed
• GovernanceViolations
• GovernanceViolationsStructured
• GovernanceScoreImpact
• GovernanceScoringVersion

Supported canonical rule areas include required and disallowed fields, field severity, field type, enum constraints, allowed topics, sensitive-field overrides, relaxation, and scoring.

Scoring and shipping

When Scoring.Enabled is true, the runtime calculates governance score impact using profile severity weights and optional plugin multipliers. Relaxed events have zero impact while retaining governance metadata.

ScoreShipper provides nonblocking channel-based batching, retry, and optional transport of canonical scoring envelopes from CerbiShield.Contracts.

ILogger integration

LoggerGovernanceExtensions applies validation before forwarding the structured event to the configured logging pipeline. It can also enrich events with application, instance, region, and cloud-provider metadata.

Extensibility

Implement IRuntimeGovernanceSource to load profiles from another backing store:

public interface IRuntimeGovernanceSource
{
    Profile? Load();
    DateTime GetLastUpdatedUtc();
}

Implement IRuntimeGovernancePlugin to contribute custom runtime checks and score impact.

Performance

The runtime is designed for high-throughput event processing:

• compiled and cached profile rules
• in-place record mutation
• allocation-conscious required-field tracking
• timestamp-based file reload checks
• nonblocking score shipping

License

MIT