RFC-0047 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0047: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0047.This page is generated from the
lean/Gnomon/Spec/module for RFC-0047. Edit that source and regenerate this catalog.
Title: Observability Contract
Status: draft
Owners: Compliance, Runtime
Diagnostic range: M47000-M47099
Depends on: RFC-0001, RFC-0002, RFC-0005, RFC-0006, RFC-0007, RFC-0008, RFC-0010, RFC-0016, RFC-0024, RFC-0033, RFC-0034, RFC-0035, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040, RFC-0041, RFC-0042, RFC-0043, RFC-0045, RFC-0046, RFC-0048
Proof citations in source: 3 / 3. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Audit log entry | A single structured record describing an operation invocation: who called what, when, with what arguments (hashed), with what result. |
| Correlation ID | An opaque string that ties together related work across operation calls, sagas, event handlers. |
| Metric | A typed counter, gauge, or histogram emitted by the runtime, tagged by operation FQN and other dimensions. |
| Redaction | The replacement of a sensitive value with a placeholder before the value enters any audit, log, trace, or metric emission. |
| Required emission | An audit/trace/metric event that the runtime MUST emit; suppression is a defect. |
| Span | An OpenTelemetry tracing primitive: a typed, timed, attributed slice of work. Every operation invocation produces at least one span. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M47010 | Error | Audit log emission failed; runtime escalated to higher-severity log |
M47011 | Defect | Audit log entry violates the schema (missing required field, wrong type) |
M47020 | Warning | Custom metric name conflicts with the reserved gnomon.* prefix |
M47021 | Warning | Metric tag cardinality exceeded the recommended limit; performance impact possible |
M47030 | Defect | Sensitive value leaked into log, audit, trace, or metric emission |
M47031 | Warning | Sensitive field marked omit was referenced in a query path that requires its existence |
M47040 | Error | Span emission failed (OpenTelemetry SDK error); falling back to log line |
M47050 | Warning | Correlation ID supplied by caller does not match expected format; generated fresh |
M47060 | Defect | Operation completed but emitted no audit log entry; runtime invariant violated |
M47070 | Warning | Required emission was suppressed by operation; ignored |
M47080 | Info | Trace sampling rate is below 1%; some operations will not appear in traces |
Dependency neighborhood
graph LR
nRFC_0047["RFC-0047"]
nRFC_0001["RFC-0001"]
nRFC_0047 --> nRFC_0001
nRFC_0002["RFC-0002"]
nRFC_0047 --> nRFC_0002
nRFC_0005["RFC-0005"]
nRFC_0047 --> nRFC_0005
nRFC_0006["RFC-0006"]
nRFC_0047 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0047 --> nRFC_0007
nRFC_0008["RFC-0008"]
nRFC_0047 --> nRFC_0008
nRFC_0010["RFC-0010"]
nRFC_0047 --> nRFC_0010
nRFC_0016["RFC-0016"]
nRFC_0047 --> nRFC_0016
nRFC_0024["RFC-0024"]
nRFC_0047 --> nRFC_0024
nRFC_0033["RFC-0033"]
nRFC_0047 --> nRFC_0033
nRFC_0034["RFC-0034"]
nRFC_0047 --> nRFC_0034
nRFC_0035["RFC-0035"]
nRFC_0047 --> nRFC_0035
nRFC_0036["RFC-0036"]
nRFC_0047 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0047 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0047 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0047 --> nRFC_0039
nRFC_0040["RFC-0040"]
nRFC_0047 --> nRFC_0040
nRFC_0041["RFC-0041"]
nRFC_0047 --> nRFC_0041
nRFC_0042["RFC-0042"]
nRFC_0047 --> nRFC_0042
nRFC_0043["RFC-0043"]
nRFC_0047 --> nRFC_0043
nRFC_0045["RFC-0045"]
nRFC_0047 --> nRFC_0045
nRFC_0046["RFC-0046"]
nRFC_0047 --> nRFC_0046
nRFC_0048["RFC-0048"]
nRFC_0047 --> nRFC_0048
Invariants
- Audit emission failure on a successful operation forces the operation to fail and roll back. (enforced by: runtime)
- Correlation IDs propagate through internal operation calls, outbound clients, and event emissions. (enforced by: runtime)
- Every operation invocation produces at least one OpenTelemetry span. (enforced by: runtime)
- Every operation invocation produces exactly one audit log entry on completion. (enforced by: runtime)
- Leakage of a sensitive value into any emission boundary is a defect (M47030). (enforced by: runtime + tests)
- Metric tag cardinality is bounded; per-principal data is audit-only and never a metric tag. (enforced by: runtime)
- Required metrics are emitted by every runtime and suppression is a defect. (enforced by: runtime)
- Sensitive values must be redacted at every audit, span, metric, and log emission boundary. (enforced by: runtime)
- Stack traces are recorded on spans and excluded from audit log entries. (enforced by: runtime)
- The boot-populated redaction registry is the authoritative source for whether a field is sensitive. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Audit Log
- MUST_NOT — Audit emission MUST NOT be suppressible by the operation being invoked.
- MUST — On audit-emission failure for a successful operation, the runtime MUST roll back and return core.errors.InternalError.
Compatibility and Migration
- MUST — Existing audit-log emitters MUST be brought into compliance with the §3.1 schema; new emitters MUST use the schema defined here. (proof citation:
rfc0047_audit_log_emitters_conform; verification pending) - MUST — Modules MUST opt into boundary-based redaction by tagging fields sensitive.
- MUST — OpenTelemetry instrumentation MUST be added if not already present.
Correlation IDs
- MUST_NOT — Caller-supplied correlation IDs MUST NOT be trusted as authentication.
- SHOULD — Implementations SHOULD use UUIDv7 or ULID-format values for correlation IDs.
- MUST — The runtime MUST accept caller-supplied correlation IDs from a well-known header.
- MUST — The runtime MUST treat correlation IDs as opaque — no parsing or semantics beyond equality.
Error Reporting
- SHOULD — Stack traces SHOULD be included in span exception records and excluded from audit log entries.
- MUST_NOT — The runtime MUST NOT emit stack traces in responses to external callers.
Invariants
- MUST — Every operation invocation produces exactly one audit log entry on completion.
- MUST — Sensitive values MUST be redacted at every emission boundary.
Metrics
- MUST — Every runtime MUST emit the required metrics listed in §5.1. (proof citation:
rfc0047_b1_grounded; verification pending) - MUST_NOT — Implementations MUST NOT add metric tags that multiply cardinality, such as principal_id.
- SHOULD — The runtime SHOULD lint custom metrics that conflict with the gnomon.* reserved prefix (M47020). (proof citation:
rfc0047_b18_grounded; verification pending) - SHOULD — gnomon.operation.duration_ms SHOULD use exponential buckets covering 1ms to 60s.
PII Redaction
- SHOULD — Implementations SHOULD have automated tests that scan emissions for known sensitive values and fail the build on detection.
- MUST — Sensitive values MUST be replaced with redaction placeholders at every emission boundary listed in §6.2.
Tracing (OpenTelemetry)
- MUST — Every operation invocation MUST produce at least one OpenTelemetry span.
- MUST — Internal operation calls MUST propagate trace context through the runtime’s correlation ID mechanism.
- MUST — On operation failure, the span MUST record the exception via OpenTelemetry’s recordException API and set status to ERROR.
- MUST_NOT — The runtime MUST NOT internally drop spans before passing them to the SDK; sampling is the SDK’s responsibility.
- MUST — The runtime MUST extract inbound trace context and use it as the parent of the operation span.
- MUST — The span MUST emit events at key pipeline boundaries (auth, guards, effects, transaction).
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0002 |
| Depends on | RFC-0005 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0008 |
| Depends on | RFC-0010 |
| Depends on | RFC-0016 |
| Depends on | RFC-0024 |
| Depends on | RFC-0033 |
| Depends on | RFC-0034 |
| Depends on | RFC-0035 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |
| Depends on | RFC-0041 |
| Depends on | RFC-0042 |
| Depends on | RFC-0043 |
| Depends on | RFC-0045 |
| Depends on | RFC-0046 |
| Depends on | RFC-0048 |