@openauditmodel/cli 0.1.0

package/specification/delivery.md

@@ -0,0 +1,136 @@
+# Delivery
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. OpenAuditModel defines no transport
+
+The model defines the **event**, not how it moves. There is no OpenAuditModel protocol, wire format,
+endpoint, envelope or delivery guarantee, and none will be introduced.
+
+An event is equally valid when it is:
+
+- Written to a local file or standard output.
+- Inserted into a table.
+- Published to a topic or queue.
+- Sent as an HTTP request body.
+- Emitted as an OpenTelemetry log record.
+- Wrapped in a CloudEvents envelope.
+- Held in memory in a test.
+
+Producers MUST NOT be required to adopt any pipeline in order to conform. See
+[ADR 0003](../decisions/0003-backend-and-transport-independence.md).
+
+## 2. Producing
+
+A producer:
+
+1. MUST emit events that validate against the canonical schema.
+2. SHOULD emit an event for an auditable operation regardless of its outcome. Recording only
+   successes produces an audit trail that cannot answer the questions failures raise.
+3. SHOULD emit the event as close to the operation as possible, so that `time` reflects the operation
+   rather than a later batch.
+4. SHOULD NOT make the success of the audited operation depend on the success of audit emission,
+   unless the operator has explicitly chosen that trade-off. This is a genuine design decision:
+   dropping audit records under load and refusing business operations when the audit path is down are
+   both defensible, and the specification does not choose for the operator.
+5. MUST record the decision it made, in its own documentation. A consumer cannot tell from the data
+   whether missing events mean "nothing happened" or "the buffer overflowed".
+
+## 3. Identity and idempotency
+
+`id` is the basis of safe delivery.
+
+- A producer that retries emission of the same audited operation MUST reuse the same `id`.
+- A producer MUST NOT reuse an `id` for a different operation.
+- A consumer SHOULD deduplicate by `id`.
+- A consumer MUST NOT assume that receiving an event twice means the operation happened twice.
+
+This is what makes at-least-once transports safe to use for audit data, and it is why `id` is
+required rather than optional.
+
+## 4. Time and observation
+
+`time` is when the operation occurred. `observedTime` is when a component in the path observed the
+event.
+
+- A producer SHOULD set `time` and SHOULD NOT set `observedTime`.
+- The first component that receives an event MAY set `observedTime`. Later components SHOULD NOT
+  overwrite it.
+- A consumer MUST NOT assume the two are equal, and MUST NOT compute pipeline latency from `time`
+  alone. Backfilled, queued and replayed events legitimately arrive long after they occurred.
+- Clocks differ. A consumer MUST NOT assume that `time` values from different producers are directly
+  comparable at fine resolution, and SHOULD NOT reconstruct causality from timestamps alone.
+  `request.traceId` and `request.correlationId` group events that belong to the same execution or
+  logical operation; neither establishes which event caused another. See
+  [event-model.md §10.3](event-model.md).
+
+## 5. Ordering
+
+The model provides no global ordering and no total order.
+
+- `sequence` orders events **within** one producer, partition or chain. It is meaningless across
+  producers.
+- A consumer MUST NOT assume events arrive in `time` order, in `sequence` order, or in the order the
+  operations occurred.
+- A consumer that needs ordering MUST establish it from `sequence` within a chain, and MUST tolerate
+  gaps. Trace context groups related events but does not order them.
+
+## 6. Loss, duplication and gaps
+
+Any realistic pipeline will duplicate or drop events. The model responds to this by being explicit
+rather than by promising a guarantee it cannot enforce:
+
+| Situation          | What the model provides                               |
+| ------------------ | ----------------------------------------------------- |
+| Duplicate delivery | `id` for deduplication                                |
+| Reordering         | `sequence` within a chain; trace context for grouping |
+| Silent loss        | `integrity.previousHash` chains make gaps detectable  |
+| Delay              | `observedTime` separate from `time`                   |
+
+Detecting a gap requires that something was chained or counted. A pipeline with no chain and no
+counter cannot distinguish a quiet period from a broken exporter, and operators SHOULD monitor
+production rates independently of the audit data itself.
+
+## 7. Enrichment
+
+Components between producer and consumer MAY enrich events. When they do:
+
+1. They MUST NOT alter `event`, `actor`, `subject`, `resource`, `application`, `change`,
+   `authorization`, `approval` or `id`. Those describe what the producer observed, and a collector
+   was not there.
+2. They MUST NOT set `application` to describe themselves. `application` is the producer. A pipeline
+   that rewrites it destroys the provenance of the entire trail.
+3. They MAY set `observedTime` if it is not already present.
+4. They MAY add `extensions` under their own reverse-domain namespace.
+5. They MUST NOT invalidate an event. Any enriched event MUST still validate against the canonical
+   schema.
+6. They MUST NOT modify an event that carries `integrity.hash` or `integrity.signature`, because any
+   modification invalidates it. Enrichment of a sealed event MUST be carried alongside it, not inside
+   it. This includes `observedTime`: every field except the two excluded pointers is part of the
+   digest, so adding an observation timestamp to a sealed event breaks its verification. See
+   [integrity.md](integrity.md) §4.2.
+
+## 8. Batching
+
+Batching is a transport concern, and the model defines no batch envelope. Producers that batch:
+
+- MUST keep each event individually valid. A batch is a list of complete events, not a shared header
+  plus fragments.
+- MAY record `integrity.batchId` to identify the batch an event was sealed with.
+- SHOULD NOT let batching distort `time`.
+
+## 9. Optional envelopes
+
+Where an envelope is used, the complete audit event SHOULD be carried as the envelope's payload
+without being flattened or restructured, so that it can be validated on arrival exactly as it was
+produced. Conceptual mappings for CloudEvents and OpenTelemetry are described in
+[mappings/](../mappings/), which is informative.
+
+Using an envelope MUST NOT change the event. An event that is only valid after being unwrapped and
+transformed is not a conforming event.
+
+## 10. Storage
+
+Out of scope, deliberately and permanently. The specification says nothing about schemas for storage,
+indexes, partitioning, retention enforcement, compaction or query. It says only that whatever the
+store does, it MUST be able to return the event as it was produced if the trail is to mean anything.

package/specification/design-principles.md

@@ -0,0 +1,137 @@
+# Design Principles
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+These principles are the reason the model looks the way it does. They are normative in the sense that
+a proposed change to the core model MUST be evaluated against them, and a change that violates one
+MUST be rejected or must first change the principle.
+
+## 1. The core stays small
+
+The core model contains only concepts that are meaningful in **every** business application,
+regardless of industry, jurisdiction or architecture.
+
+A field belongs in the core only if all of the following hold:
+
+1. It is meaningful to a document system, a payment system, a hospital system, a message broker
+   console and an internal admin tool alike.
+2. Omitting it would make an audit event ambiguous in a way no other field resolves.
+3. It cannot be expressed as `metadata`, an extension, or a profile requirement without losing
+   cross-application comparability.
+
+Everything else belongs in `metadata`, `extensions` or a profile. A core model that grows to cover
+every domain stops being a common model.
+
+## 2. The core is explainable
+
+An engineer MUST be able to read [event-model.md](event-model.md) and instrument an application
+correctly without reading the rest of the specification. Concepts that require a diagram of five
+interacting objects to explain are a sign that the model is wrong, not that the reader is slow.
+
+## 3. Composition, not inheritance
+
+The model has no type hierarchy, no discriminated event subclasses and no abstract base event.
+An event is a flat set of optional context objects attached to a small required core. A privileged
+configuration change is not a subclass of a change: it is an event with `change`, `approval`,
+`authorization` and `controlCategories` populated.
+
+This keeps the schema flat, keeps validation cheap, and keeps profiles additive.
+
+## 4. Backend independence
+
+The model MUST NOT require, assume or favour any storage system, message broker, telemetry pipeline,
+SIEM, cloud provider or vendor product. An event MUST be equally valid when it is written to a file,
+inserted into a table, published to a topic or held in memory.
+
+Consequences that are enforced today:
+
+- No field describes a storage location, index, partition key or retention backend.
+- `application` describes the **producer**, never a collector or a store.
+- Schema identifiers never have to be dereferenced: no `$ref` resolves remotely, so validation never requires a network call.
+- Validation is fully offline.
+
+See [ADR 0003](../decisions/0003-backend-and-transport-independence.md).
+
+## 5. Transport independence
+
+The model defines no transport, envelope or delivery guarantee. It MAY be carried by CloudEvents,
+OpenTelemetry, HTTP, a broker, a file or a database write. Delivery concerns — retries, duplicates,
+ordering, batching — are addressed by making the event **idempotent and self-describing**, not by
+defining a protocol. See [delivery.md](delivery.md).
+
+## 6. Machine-verifiable by default
+
+Every rule that **can** be expressed in JSON Schema Draft 2020-12 **is** expressed there, so that
+conformance is testable rather than aspirational. This includes conditional rules such as "a failure
+carries an error" and "acting for a principal identifies that principal".
+
+Where a rule cannot be machine-checked — such as "do not log secrets" — the specification says so
+explicitly rather than pretending validation covers it. See [privacy.md](privacy.md).
+
+Schema patterns MUST remain portable across regular expression engines: no look-around and no
+back-references, so that the same schema behaves identically in JavaScript, Python, Go, Java and .NET
+validators.
+
+## 7. Strict where it matters, open where it must be
+
+Core objects reject unknown properties. This is deliberate: silently accepting an unknown field means
+a producer can believe it is recording something that no consumer will ever read.
+
+Vocabularies are treated differently depending on whether the value space is universal:
+
+| Kind                  | Enforcement                         | Examples                                                                  |
+| --------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
+| **Closed vocabulary** | `enum` in the schema                | `event.outcome`, `event.severity`, `actor.type`, `authorization.decision` |
+| **Open vocabulary**   | Form constrained, membership is not | `resource.type`, `resource.classification`, `application.environment`     |
+
+A vocabulary is closed only when the value set is small, universal, and load-bearing for
+interpretation. A vocabulary is open when organizations legitimately differ — classification schemes
+and environment names differ between companies, and forcing them into a fixed list would produce
+false data rather than comparable data.
+
+Both are constrained in **form**: open vocabulary values are lower-case, hyphen-separated tokens, so
+that they remain comparable even when they are not identical.
+
+## 8. Privacy is a first-class constraint
+
+Audit data is high-risk data: it concentrates who did what to whom. The model therefore:
+
+- Prohibits specific values outright, in normative language.
+- Prefers stable identifiers over personal identifiers.
+- Prefers route templates over resolved URLs.
+- Prefers changed field names over changed field values.
+- Prefers references over embedded payloads.
+- Treats capture as an **allowlist**: a producer records the fields it decided to record, never
+  "whatever the request contained".
+
+See [privacy.md](privacy.md).
+
+## 9. Regulation-neutral, industry-neutral, jurisdiction-neutral
+
+The core model MUST NOT contain a regulation identifier, an article number, a control identifier, a
+country-specific field or an industry-specific field. Not because compliance does not matter, but
+because a model that encodes one framework becomes unusable everywhere that framework does not apply,
+and becomes wrong when the framework is revised.
+
+Regulatory interpretation is a **mapping over** audit data, produced and maintained separately from
+the data model. `controlCategories` exists to carry the neutral half of that relationship.
+
+## 10. Stability of meaning
+
+An event name, once published, keeps its meaning. A field, once defined, keeps its meaning. If the
+meaning must change, the name changes.
+
+Silent redefinition is worse than a breaking change: a breaking change is detected by a validator,
+while a silent redefinition corrupts historical analysis without anyone noticing.
+
+## 11. Specification before implementation
+
+The normative model, the canonical schema and the conformance tooling come before production SDKs.
+An SDK written first would freeze accidental implementation details into the standard. See
+[ADR 0001](../decisions/0001-specification-first.md).
+
+## 12. Do not confuse completeness with quality
+
+An event that populates every optional object is not a better audit event than one that populates
+five fields correctly. Optional fields exist so that applications with a real need can express it —
+not as a checklist. Producers SHOULD populate what their audit purpose requires and omit the rest.

package/specification/event-model.md

@@ -0,0 +1,387 @@
+# Event Model
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. Structure
+
+An audit event is a JSON object with a small required core and a set of optional context objects.
+
+### 1.1 Required fields
+
+A conforming event MUST contain exactly these seven fields:
+
+| Field         | Type   | Meaning                                   |
+| ------------- | ------ | ----------------------------------------- |
+| `specVersion` | string | Specification version. MUST be `"0.1"`.   |
+| `id`          | string | Globally unique identifier of this event. |
+| `time`        | string | When the audited operation occurred.      |
+| `event`       | object | What happened and how it ended.           |
+| `actor`       | object | Who technically performed the operation.  |
+| `resource`    | object | What the operation acted upon.            |
+| `application` | object | Which application produced the event.     |
+
+### 1.2 Optional fields
+
+| Field               | Type    | Defined in                                               |
+| ------------------- | ------- | -------------------------------------------------------- |
+| `observedTime`      | string  | This document, §4                                        |
+| `sequence`          | integer | This document, §5                                        |
+| `subject`           | object  | [actor-model.md](actor-model.md)                         |
+| `delegation`        | object  | [approval-and-delegation.md](approval-and-delegation.md) |
+| `relatedResources`  | array   | [resource-model.md](resource-model.md)                   |
+| `organization`      | object  | This document, §9                                        |
+| `authentication`    | object  | [authentication.md](authentication.md)                   |
+| `authorization`     | object  | [authorization.md](authorization.md)                     |
+| `approval`          | object  | [approval-and-delegation.md](approval-and-delegation.md) |
+| `request`           | object  | This document, §10                                       |
+| `change`            | object  | [change-model.md](change-model.md)                       |
+| `reason`            | object  | This document, §11                                       |
+| `evidence`          | array   | [evidence-model.md](evidence-model.md)                   |
+| `integrity`         | object  | [integrity.md](integrity.md)                             |
+| `privacy`           | object  | [privacy.md](privacy.md)                                 |
+| `controlCategories` | array   | This document, §12                                       |
+| `tags`              | array   | This document, §13                                       |
+| `metadata`          | object  | [extension-model.md](extension-model.md)                 |
+| `extensions`        | object  | [extension-model.md](extension-model.md)                 |
+
+### 1.3 Strictness
+
+The event object and every core object within it MUST reject unknown properties.
+
+Domain-specific data MUST NOT be added as a new top-level property. It belongs in `metadata`,
+`extensions`, an object's `attributes`, or a profile.
+
+An OPTIONAL object, when present, MUST contain at least one property. An empty object carries no
+information and is rejected, so that "the producer had nothing to say" and "the producer said
+nothing" are not confused.
+
+## 2. Event identity
+
+`id` MUST be a globally unique, idempotent identifier for the event.
+
+- The specification does NOT mandate an identifier technology.
+- UUIDv4, UUIDv7 and ULID are RECOMMENDED. Any collision-resistant identifier is acceptable.
+- A database-generated sequential integer MUST NOT be required by an implementation of this
+  specification, because it is not unique across producers and is not available before the event is
+  stored.
+- A producer that retries emission of the same audited operation MUST reuse the same `id`, so that
+  consumers can deduplicate. See [delivery.md](delivery.md).
+- `id` SHOULD be opaque. It MUST NOT encode personal data.
+
+## 3. Event time
+
+`time` is when the audited operation **occurred**, as observed by the producer.
+
+- MUST be an RFC 3339 compatible date-time string.
+- UTC is RECOMMENDED. A producer that records a local offset MUST include the offset.
+- `time` MUST reflect the operation, not the moment the event object was serialized, when those
+  differ meaningfully.
+
+## 4. Observed time
+
+`observedTime` is when a collector, exporter, gateway or receiving system **observed** the event.
+
+- MUST be an RFC 3339 compatible date-time string.
+- MUST NOT be assumed equal to `time`. Queued, batched, retried and backfilled events legitimately
+  have an observed time much later than their event time.
+- A producer SHOULD NOT set `observedTime`; it is normally set by the first component that receives
+  the event.
+- A consumer that needs to reason about pipeline latency MUST use `observedTime`, and MUST NOT infer
+  latency from `time` alone.
+
+## 5. Sequence
+
+`sequence` is a producer-assigned, monotonically increasing, non-negative integer used to order
+events that share a timestamp.
+
+- Ordering is meaningful only **within** a single producer, partition or integrity chain.
+- A consumer MUST NOT assume that sequence numbers are comparable across producers, or that they are
+  contiguous.
+
+## 6. Event descriptor
+
+The `event` object describes what happened.
+
+### 6.1 Required
+
+| Field      | Meaning                            |
+| ---------- | ---------------------------------- |
+| `name`     | Hierarchical event name. See §7.   |
+| `category` | Coarse grouping of the event name. |
+| `outcome`  | Result of the audited operation.   |
+
+### 6.2 Optional
+
+| Field      | Meaning                                                                      |
+| ---------- | ---------------------------------------------------------------------------- |
+| `type`     | Domain-independent activity classifier, such as `create`, `read`, `approve`. |
+| `severity` | Audit significance of the event.                                             |
+| `summary`  | Short human-readable description.                                            |
+| `error`    | Sanitized failure descriptor. See §6.5.                                      |
+
+### 6.3 Outcome
+
+`outcome` MUST be one of:
+
+| Value     | Meaning                                                                                   |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `success` | The operation completed as requested.                                                     |
+| `failure` | The operation did not complete.                                                           |
+| `partial` | The operation completed for some targets and failed for others.                           |
+| `unknown` | The producer cannot determine the result, for example after a timeout on a remote system. |
+
+A denied authorization is a `failure` outcome with an `authorization.decision` of `deny`. It is not a
+separate outcome value.
+
+### 6.4 Severity
+
+`severity`, when present, MUST be one of `debug`, `info`, `low`, `medium`, `high`, `critical`.
+
+Severity describes the **audit significance** of the operation, not the severity of a software fault.
+A successful privileged configuration change in production is `critical` even though nothing went
+wrong. A failed read of a public resource is `info` even though it failed.
+
+The scale is closed in v0.1 because an ordinal scale with producer-defined members cannot be
+compared. Reopening it is an open question for v0.2.
+
+### 6.5 Error
+
+When `event.outcome` is `failure`, the event MUST contain `event.error`.
+
+`event.error` MUST contain `code`, a stable machine-readable failure code defined by the producer.
+It MAY contain `type`, `message` and `retryable`.
+
+When `outcome` is `partial`, the event SHOULD contain `event.error` describing the failing portion.
+
+`event.error` MUST NOT contain:
+
+- Secrets, tokens, credentials or connection strings.
+- Personal data beyond what the audit purpose requires.
+- Full request or response payloads.
+- Internal stack traces, unless explicitly permitted by the operator's policy.
+
+Error text is for humans. A consumer MUST NOT parse `message` to make decisions; that is what `code`
+is for.
+
+### 6.6 Summary
+
+`summary` is optional human-readable text. A consumer MUST NOT parse it. It MUST NOT contain values
+prohibited by [privacy.md](privacy.md).
+
+## 7. Event naming
+
+### 7.1 Form
+
+Event names are hierarchical, lower-case, dot-separated names of the general form:
+
+```text
+domain.resource.action
+```
+
+At least two segments are REQUIRED. Segments are lower-case and may contain digits and hyphenated
+words, for example `offset-reset`.
+
+```text
+authentication.login
+identity.role.assign
+document.share.create
+incident.case.close
+configuration.setting.update
+deployment.release.approve
+queue.consumer.offset-reset
+```
+
+The core schema MUST NOT enumerate event names. Recommended names are published as
+[semantic conventions](../semantic-conventions/event-naming.md), which producers SHOULD follow.
+
+### 7.2 Rules
+
+1. Event names MUST be stable across releases.
+2. Event names MUST NOT contain product names.
+3. Event names MUST NOT contain company names.
+4. Event names MUST NOT contain jurisdiction names.
+5. Event names MUST describe the audited operation, not the implementation method. `identity.role.assign`,
+   not `identity.role.update-via-graph-api`.
+6. Success and failure of the same operation SHOULD use the **same** event name with different
+   `outcome` values. `authentication.login` with `outcome: failure`, not `authentication.login-failed`.
+7. The meaning of an event name MUST NOT change silently between versions. If the meaning changes,
+   the name changes.
+
+## 8. Application context
+
+`application` describes the **producer** of the event.
+
+### 8.1 Required
+
+| Field         | Meaning                                             |
+| ------------- | --------------------------------------------------- |
+| `name`        | Stable name of the producing application.           |
+| `environment` | Deployment environment the producer was running in. |
+
+### 8.2 Optional
+
+`version`, `instance`, `service`, `component`, `region`, `zone`, `deploymentId`.
+
+### 8.3 Rules
+
+1. `application` MUST describe the application that **produced** the event. It MUST NOT describe a
+   collector, forwarder, gateway, storage backend or SIEM that later received it. An audit trail in
+   which every event claims to come from the log pipeline is not an audit trail.
+2. `application.name` SHOULD be stable across releases and SHOULD be lower-case and hyphenated.
+3. `environment` is an open vocabulary. The RECOMMENDED values are `local`, `development`, `test`,
+   `staging`, `production`, `disaster-recovery` and `unknown`. Organizations that use additional
+   environment names, such as a user acceptance environment, MAY use their own token rather than
+   forcing it into one of the recommended values.
+4. `region` and `zone` are operator-defined identifiers. They MUST NOT be assumed to follow any
+   particular provider's naming.
+
+## 9. Organization context
+
+`organization` is OPTIONAL and MAY contain `tenantId`, `organizationId`, `departmentId`,
+`workspaceId` and `businessUnitId`.
+
+Not every application is multi-tenant. The core specification MUST NOT require organization context,
+and a consumer MUST NOT treat its absence as an error.
+
+Where a tenant applies to a specific principal or resource rather than to the operation as a whole,
+`actor.tenantId` and `resource.tenantId` are the more precise place to record it.
+
+## 10. Request and correlation context
+
+`request` is OPTIONAL and describes how the operation was requested.
+
+| Field                             | Notes                                                       |
+| --------------------------------- | ----------------------------------------------------------- |
+| `requestId`                       | The inbound request currently being served.                 |
+| `correlationId`                   | The logical operation the event belongs to. See §10.1.      |
+| `traceId`, `spanId`               | W3C Trace Context compatible. See §10.2.                    |
+| `ipAddress`, `forwardedFor`       | IPv4 or IPv6 literals. Personal data in many jurisdictions. |
+| `userAgent`, `protocol`, `method` | Client and protocol context.                                |
+| `route`                           | Route template. See §10.4.                                  |
+
+Guidance on choosing between these identifiers is in
+[semantic-conventions/correlation-and-tracing.md](../semantic-conventions/correlation-and-tracing.md),
+which is informative.
+
+### 10.1 Correlation identifiers
+
+`requestId` identifies the inbound request currently being served. It is scoped to one service
+handling one call, and SHOULD NOT be propagated into asynchronous messages: a message consumer is not
+serving the request that produced the message.
+
+`correlationId` identifies the logical operation, workflow, job, conversation or business process the
+event belongs to. It MAY span services, messages, trace boundaries and time, and it is the identifier
+that remains stable when a `traceId` does not.
+
+### 10.2 Trace identifiers
+
+`traceId` MUST be 32 lower-case hexadecimal characters and `spanId` MUST be 16 lower-case
+hexadecimal characters, matching W3C Trace Context. The all-zero value is invalid for both.
+
+This makes audit events correlatable with distributed traces without requiring any particular
+telemetry stack. See [mappings/opentelemetry.md](../mappings/opentelemetry.md), which is informative.
+
+Producers SHOULD obtain `traceId` and `spanId` from the active trace context rather than generating
+identifiers specifically for the audit event. An identifier minted for the audit record is
+well-formed and correlates with nothing.
+
+`spanId` SHOULD be recorded only together with `traceId`. A span identifier alone cannot be resolved,
+because there is nothing to resolve it against.
+
+Raw `traceparent` and `tracestate` values SHOULD NOT be stored. Producers SHOULD extract the trace and
+span identifiers and discard the remainder: the version and flag fields describe the tracing system's
+own decisions, and `tracestate` is vendor-specific and may carry tenant or account information.
+
+### 10.3 Trust and independence
+
+Correlation identifiers — `requestId`, `correlationId`, `traceId` and `spanId` — are **observational
+metadata**. They MUST NOT be used as proof of identity, authorization, authenticity, integrity or
+tenant isolation. Each can be supplied by a caller, guessed, replayed or copied between tenants.
+`authentication`, `authorization` and `integrity` are the fields that carry those guarantees.
+
+A shared `traceId` indicates that two events belong to the same execution. It does NOT establish
+which event caused another, nor the order in which they occurred. Ordering within a producer is
+established by `sequence`; see [delivery.md](delivery.md).
+
+Audit event generation MUST NOT depend on trace sampling. An audit event MUST be produced whether or
+not a trace is sampled, recorded or retained, and a `traceId` that resolves to no stored trace is a
+normal outcome rather than an error.
+
+Personal data, credentials, account numbers and sensitive business values SHOULD NOT be used as
+correlation identifiers. A non-reversible surrogate SHOULD be used instead; see
+[privacy.md](privacy.md).
+
+### 10.4 Route templates
+
+`route` SHOULD be the **route template**, not the resolved URL:
+
+```text
+/users/{userId}/roles          ← RECOMMENDED
+/users/472918/roles            ← NOT RECOMMENDED
+```
+
+The resolved identifier belongs in `resource.id`, where it is structured and can be redacted
+independently.
+
+Query strings and fragments are rejected by the schema. Producers MUST NOT capture query strings
+automatically: they routinely carry search terms, filters, tokens and personal identifiers that no
+one decided to audit.
+
+## 11. Reason
+
+`reason` is OPTIONAL and records **why** the operation was performed: a business justification,
+support request, change ticket, incident response or emergency access explanation.
+
+| Field       | Meaning                                                |
+| ----------- | ------------------------------------------------------ |
+| `code`      | Machine-readable justification code.                   |
+| `text`      | Human-readable justification.                          |
+| `reference` | Identifier of the record that justifies the operation. |
+
+`reason` MUST NOT be used for technical error information. A justification explains intent; an error
+explains failure. An event may legitimately carry both.
+
+## 12. Control categories
+
+`controlCategories` is an OPTIONAL array of regulation-neutral labels describing the kind of control
+this event provides evidence for:
+
+```text
+authentication-logging
+privileged-access
+data-access-logging
+external-data-sharing
+change-approval
+separation-of-duties
+configuration-integrity
+incident-traceability
+```
+
+Control categories MUST NOT contain regulation names, article numbers, control framework identifiers
+or jurisdiction names. Mapping a control category to a specific framework is the job of a separate,
+optional mapping artifact maintained outside the core specification.
+
+## 13. Tags
+
+`tags` is an OPTIONAL array of producer-defined labels for filtering and routing. Tags carry no
+normative meaning, and a consumer MUST NOT derive audit semantics from them.
+
+## 14. Complete minimal event
+
+```json
+{
+  "specVersion": "0.1",
+  "id": "018f1b5c-6d2a-7c3e-9a1b-4f5e6d7c8b9a",
+  "time": "2026-03-14T09:24:31.412Z",
+  "event": {
+    "name": "data.record.update",
+    "category": "data-modification",
+    "outcome": "success"
+  },
+  "actor": { "type": "user", "id": "user-123" },
+  "resource": { "type": "record", "id": "resource-123" },
+  "application": { "name": "application-service", "environment": "production" }
+}
+```
+
+This is a complete, conforming audit event. Nothing else is required.