RFC-0047 observability and audit contract proposal
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.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: first-release public-contract proposal. The authored RFC, Lean catalog, and RDF facts remain unchanged pending the owner decision.
Source conflicts
- RFC-0047 §3.1 and invariant 9.1 promise exactly one audit entry for every invocation, including failed ones. Section 3.2 says audit failure for an already failed operation only raises M47010 and leaves the result alone; that invocation can finish with no audit entry. Its successful-operation rollback promise also lacks a transaction boundary between graph effects and an external audit sink.
- The required audit schema gives
startedAtas first effect time andcompletedAtas commit/rollback, but authentication or authorization can fail before any effect or transaction. These fields have no values for those required audit records. Idempotency replays also execute no effects. - Sections 3.3 and 6.2 hash a redacted input. Replacing different sensitive
values with the same placeholder makes their
argHashequal, so it cannot verify that the same full input was used. A plain SHA-256 digest of predictable nonsecret input is also vulnerable to dictionary guessing; “non-reversible” overstates the privacy guarantee. - Sections 4.1 and 9.3 say every invocation produces a span, while §4.5 delegates sampling to the OpenTelemetry SDK. An SDK sampler may decline recording/exporting a span. The runtime can guarantee a span creation attempt and context propagation, not exported span delivery.
- Section 4.4 says trace context propagates through the correlation ID mechanism, but §7.4 gives child operations fresh correlation IDs. W3C traceparent/span context and application correlation IDs need separate carriers and parent rules.
- Section 6.2 relies on substring replacement for error text and stack traces. That cannot guarantee redaction when sensitive values are encoded, formatted, truncated, or transformed. The declared field-path registry can enforce structured redaction before serialization; free text needs a bounded fallback and a rule against including raw sensitive payloads.
- The audit entry crosses process, storage, and export boundaries. Per the
repository’s DTO rule, its canonical wire/storage schema should be a
versioned
.protomessage, with JSON as a generated presentation. - Section 10 prescribes a migration for existing emitters, but the owner confirmed nothing is deployed. First-release conformance has no legacy audit consumers to migrate.
Recommended first-release contract
- Define
AuditLogEntryand its outcome, timestamps, operation identity, principal, tenant, effect counts, correlation, and hash metadata as a versioned proto. MakestartedAt,effectStartedAt, and transaction completion timestamps optional where that phase did not occur. Preserve a mandatoryinvokedAtand final attempt outcome. - For a successful mutation, write one audit record or audit-outbox record
in the same database transaction as graph effects and the idempotency
result. A failed audit write rolls back that transaction. Export records
after commit with at-least-once delivery and deduplicate by stable
recordId. Do not claim an external sink can undo committed graph writes. - For pre-transaction failures and rolled-back attempts, persist an audit
record through a separate bounded path before returning when possible.
If every durable audit path is unavailable, emit M47010 through an
independent emergency channel and surface an audit-health failure. State
this availability limit explicitly; do not promise physical delivery under
total storage failure. Each invocation constructs one logical record and
retries delivery with the same
recordId. - Replace plain
argHashwith a key-versioned HMAC-SHA-256 fingerprint of canonical input, computed inside the trusted runtime before redaction and emitted only as a digest. Define canonical encoding and key rotation. Keep emitted argument detail redacted or omitted. If no HMAC key is configured, omit the fingerprint rather than making a privacy claim about plain hashes.argSizeBytescan describe the original encoded size without exposing content, if the threat model permits it. - Create an operation span and pass it to the configured SDK for every invocation. The sampler decides whether it is recorded/exported. Audit completeness is independent of trace sampling. Propagate W3C trace context through internal and outbound calls separately from correlation IDs; create a fresh child correlation ID with the parent ID recorded as §7.4 specifies.
- Redact structured values by declared sensitive paths before formatting. Never place raw sensitive payloads in exception text or metric labels. Apply a best-effort value scrub to unstructured third-party messages and classify unsafely scrubbed messages as generic errors. Keep tests with encoded and transformed secrets, not only literal substring matches.
- Remove deployed-system migration wording; require first-release producers and consumers to use the versioned schema.
Acceptance fixtures
- Successful graph mutation, audit record, and idempotency result commit atomically; injected audit write failure leaves none of them committed.
- Replayed request, authentication denial, guard failure, timeout, and
effect rollback each produce one logical audit
recordIdwith nullable phase timestamps and the correct outcome. - Exporter retry may deliver twice, but storage/consumer deduplication
exposes one record per
recordId. A total audit-storage outage triggers M47010 and degrades audit health rather than asserting delivery. - Two inputs differing only in a sensitive field have distinct keyed fingerprints without exposing that field; a changed key version is explicit. No plain SHA digest of low-entropy input is emitted.
- A zero-sampling SDK still receives span creation attempts and trace context propagates; no exported-span completeness claim is made.
- Structured and free-text emission tests cover raw, encoded, transformed, and nested sensitive values across audit, log, span, and metric boundaries.