gnomonlearn
Docs/RFC-0047/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Audit log entryA single structured record describing an operation invocation: who called what, when, with what arguments (hashed), with what result.
Correlation IDAn opaque string that ties together related work across operation calls, sagas, event handlers.
MetricA typed counter, gauge, or histogram emitted by the runtime, tagged by operation FQN and other dimensions.
RedactionThe replacement of a sensitive value with a placeholder before the value enters any audit, log, trace, or metric emission.
Required emissionAn audit/trace/metric event that the runtime MUST emit; suppression is a defect.
SpanAn OpenTelemetry tracing primitive: a typed, timed, attributed slice of work. Every operation invocation produces at least one span.

Diagnostics

CodeSeverityDescription
M47010ErrorAudit log emission failed; runtime escalated to higher-severity log
M47011DefectAudit log entry violates the schema (missing required field, wrong type)
M47020WarningCustom metric name conflicts with the reserved gnomon.* prefix
M47021WarningMetric tag cardinality exceeded the recommended limit; performance impact possible
M47030DefectSensitive value leaked into log, audit, trace, or metric emission
M47031WarningSensitive field marked omit was referenced in a query path that requires its existence
M47040ErrorSpan emission failed (OpenTelemetry SDK error); falling back to log line
M47050WarningCorrelation ID supplied by caller does not match expected format; generated fresh
M47060DefectOperation completed but emitted no audit log entry; runtime invariant violated
M47070WarningRequired emission was suppressed by operation; ignored
M47080InfoTrace 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

  1. Audit emission failure on a successful operation forces the operation to fail and roll back. (enforced by: runtime)
  2. Correlation IDs propagate through internal operation calls, outbound clients, and event emissions. (enforced by: runtime)
  3. Every operation invocation produces at least one OpenTelemetry span. (enforced by: runtime)
  4. Every operation invocation produces exactly one audit log entry on completion. (enforced by: runtime)
  5. Leakage of a sensitive value into any emission boundary is a defect (M47030). (enforced by: runtime + tests)
  6. Metric tag cardinality is bounded; per-principal data is audit-only and never a metric tag. (enforced by: runtime)
  7. Required metrics are emitted by every runtime and suppression is a defect. (enforced by: runtime)
  8. Sensitive values must be redacted at every audit, span, metric, and log emission boundary. (enforced by: runtime)
  9. Stack traces are recorded on spans and excluded from audit log entries. (enforced by: runtime)
  10. 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

  1. MUST_NOT — Audit emission MUST NOT be suppressible by the operation being invoked.
  2. MUST — On audit-emission failure for a successful operation, the runtime MUST roll back and return core.errors.InternalError.

Compatibility and Migration

  1. 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)
  2. MUST — Modules MUST opt into boundary-based redaction by tagging fields sensitive.
  3. MUST — OpenTelemetry instrumentation MUST be added if not already present.

Correlation IDs

  1. MUST_NOT — Caller-supplied correlation IDs MUST NOT be trusted as authentication.
  2. SHOULD — Implementations SHOULD use UUIDv7 or ULID-format values for correlation IDs.
  3. MUST — The runtime MUST accept caller-supplied correlation IDs from a well-known header.
  4. MUST — The runtime MUST treat correlation IDs as opaque — no parsing or semantics beyond equality.

Error Reporting

  1. SHOULD — Stack traces SHOULD be included in span exception records and excluded from audit log entries.
  2. MUST_NOT — The runtime MUST NOT emit stack traces in responses to external callers.

Invariants

  1. MUST — Every operation invocation produces exactly one audit log entry on completion.
  2. MUST — Sensitive values MUST be redacted at every emission boundary.

Metrics

  1. MUST — Every runtime MUST emit the required metrics listed in §5.1. (proof citation: rfc0047_b1_grounded; verification pending)
  2. MUST_NOT — Implementations MUST NOT add metric tags that multiply cardinality, such as principal_id.
  3. SHOULD — The runtime SHOULD lint custom metrics that conflict with the gnomon.* reserved prefix (M47020). (proof citation: rfc0047_b18_grounded; verification pending)
  4. SHOULD — gnomon.operation.duration_ms SHOULD use exponential buckets covering 1ms to 60s.

PII Redaction

  1. SHOULD — Implementations SHOULD have automated tests that scan emissions for known sensitive values and fail the build on detection.
  2. MUST — Sensitive values MUST be replaced with redaction placeholders at every emission boundary listed in §6.2.

Tracing (OpenTelemetry)

  1. MUST — Every operation invocation MUST produce at least one OpenTelemetry span.
  2. MUST — Internal operation calls MUST propagate trace context through the runtime’s correlation ID mechanism.
  3. MUST — On operation failure, the span MUST record the exception via OpenTelemetry’s recordException API and set status to ERROR.
  4. MUST_NOT — The runtime MUST NOT internally drop spans before passing them to the SDK; sampling is the SDK’s responsibility.
  5. MUST — The runtime MUST extract inbound trace context and use it as the parent of the operation span.
  6. MUST — The span MUST emit events at key pipeline boundaries (auth, guards, effects, transaction).

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0002
Depends onRFC-0005
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0008
Depends onRFC-0010
Depends onRFC-0016
Depends onRFC-0024
Depends onRFC-0033
Depends onRFC-0034
Depends onRFC-0035
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040
Depends onRFC-0041
Depends onRFC-0042
Depends onRFC-0043
Depends onRFC-0045
Depends onRFC-0046
Depends onRFC-0048