Governance Trace Naming Standard¶

Purpose: Canonical span names, attribute keys, retention tiers, severity levels, and sampling policy for governance OTel projections. Spans are projections over typed evidence records — the authoritative audit record is always the typed evidence, not the span.

Cross-references: dsl-style.md, error-messages.md, test-style.md

1. Span Naming Pattern¶

{domain}.{operation}[.{detail}]

• domain: lower-case governance subsystem.
• operation: lower-case verb or lifecycle noun.
• detail: optional qualifier for lifecycle events.
• Existing two-part names are canonical when unambiguous: gate.evaluate, evidence.emit, policy.resolve.

Allowed domains in v0:

governance  gate  breakglass  evidence  certificate  charter  sod  registry  policy  permit

2. Common Required Attributes¶

Attach to every governance span where the value is known:

3. Retention Tiers¶

Spans are telemetry projections. Authoritative records live in typed evidence and tier-aware logs.

4. Span Registry¶

5. Value Conventions¶

• Attribute keys: dot-separated lower-case.
• Retention tiers: uppercase MUTABLE, PROTECTED, IMMUTABLE.
• Gate verdict enums (gate.verdict): uppercase ALLOW, DENY, ADVISORY (ADR-0044 canonical values).
• Gate enforcement in spans: uppercase HARD, SOFT, ADVISORY.
• DSL enforcement values are lowercase (hard, soft, advisory) — map to uppercase in spans.
• Booleans: native boolean.
• Hashes: sha256:<64-hex-chars>.
• IDs: stable strings for the duration of the operation.
• Paths and prompts: excluded unless explicitly redacted and approved by evidence policy.
• trace_id and span_id: stored in evidence records as correlation fields.
• Evidence hashes: stored in span attributes as correlation pointers to authoritative records.

6. Severity¶

Use governance.severity when a generic severity field is needed:

For charter-specific spans, use charter.severity with values INFO, WARN, BLOCK.

7. Sampling Policy¶

• Sample 100% of IMMUTABLE spans.
• Sample 100% of PROTECTED session and flow lifecycle spans for governed sessions.
• MUTABLE debug spans may be sampled at lower rates, but sampling must never drop the authoritative governance record.
• When telemetry export is backpressured, write local evidence first and mark export failure with protected operational evidence.
• Never sample away: failures, break-glass events, permit events, certificate transitions, or policy conflicts.

8. Example A: Hard Gate Denial Span¶

{
  "name": "gate.evaluate",
  "parent": "governance.operation",
  "attributes": {
    "governance.schema.version": "2026-05-27.v1",
    "governance.retention.tier": "IMMUTABLE",
    "governance.session.id": "sess_01",
    "governance.operation.id": "op_42",
    "governance.actor.id": "agent:reader",
    "governance.actor.role": "reader",
    "governance.policy.version": "policy.gov.v1",
    "governance.charter.id": "charter.reader.basic",
    "gate.id": "verify_in_registry",
    "gate.tool.name": "tool.write_file",
    "gate.verdict": "DENY",
    "gate.enforcement": "HARD",
    "gate.reason": "Tool is not in the ratified registry snapshot.",
    "gate.evidence.hash": "sha256:9ac1000000000000000000000000000000000000000000000000000000000001",
    "governance.severity": "ERROR"
  }
}

9. Example B: Break-Glass Open Span¶

{
  "name": "breakglass.open",
  "parent": "governance.session",
  "attributes": {
    "governance.schema.version": "2026-05-27.v1",
    "governance.retention.tier": "IMMUTABLE",
    "governance.session.id": "sess_02",
    "governance.operation.id": "op_77",
    "governance.policy.version": "policy.gov.v1",
    "governance.charter.id": "charter.prod.support",
    "breakglass.window.id": "bg_20260527_001",
    "breakglass.activated.at": "2026-05-27T00:12:00Z",
    "breakglass.requested.by": "agent:prod_support",
    "breakglass.approved.by": "human:oncall_lead",
    "breakglass.reason": "incident_response",
    "breakglass.max.duration": "30m",
    "breakglass.evidence.hash": "sha256:1b0e000000000000000000000000000000000000000000000000000000000002",
    "governance.severity": "CRITICAL"
  }
}