@openauditmodel/cli 0.1.0

package/specification/actor-model.md

@@ -0,0 +1,135 @@
+# Actor Model
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. The distinction the model exists to make
+
+Modern applications rarely have a single participant in an operation. A request arrives at a gateway,
+is forwarded to a service, executed by a worker, and performed against a resource owned by someone
+else entirely. "Who did this?" has more than one answer, and an audit model that collapses them is
+useless in exactly the situations that matter most.
+
+OpenAuditModel separates three things:
+
+| Concept      | Question it answers                          | Field      |
+| ------------ | -------------------------------------------- | ---------- |
+| **Actor**    | Who technically performed the operation?     | `actor`    |
+| **Subject**  | On whose behalf was the operation performed? | `subject`  |
+| **Resource** | What was the operation performed on?         | `resource` |
+
+An administrator resetting a customer's password is the actor; the customer is the resource. An
+administrator impersonating a customer to place an order is the actor; the customer is the subject;
+the order is the resource. These are different events and the model MUST be able to tell them apart.
+
+## 2. Principal
+
+`actor` and `subject` share one shape, the **principal**.
+
+### 2.1 Required
+
+| Field  | Meaning                                                          |
+| ------ | ---------------------------------------------------------------- |
+| `type` | Kind of principal.                                               |
+| `id`   | Stable identifier of the principal within its issuing authority. |
+
+### 2.2 Optional
+
+| Field            | Meaning                                 |
+| ---------------- | --------------------------------------- |
+| `displayName`    | Human-readable name. Personal data.     |
+| `tenantId`       | Tenant the principal belongs to.        |
+| `organizationId` | Organization the principal belongs to.  |
+| `roles`          | Roles relevant to **this** operation.   |
+| `attributes`     | Producer-defined additional attributes. |
+
+## 3. Principal types
+
+`type` MUST be one of:
+
+| Value      | Meaning                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------- |
+| `user`     | A human-operated account.                                                                       |
+| `service`  | A workload, service account or automated client acting under its own identity.                  |
+| `system`   | The application itself, for operations with no external initiator, such as scheduled processes. |
+| `admin`    | A human-operated account exercising administrative privilege for this operation.                |
+| `external` | A principal originating outside the operator's identity boundary.                               |
+| `unknown`  | The producer cannot determine the kind of principal.                                            |
+
+Notes:
+
+- `admin` is a statement about **this operation**, not a permanent property of an account. The same
+  account may appear as `user` for ordinary operations and `admin` for privileged ones. Producers
+  that cannot make this distinction reliably SHOULD use `user` and record privilege in `roles`.
+- `unknown` MUST NOT be used to avoid deciding. It exists for imported and legacy data where the
+  information genuinely does not exist.
+- A principal kind that does not fit these values, such as a device, SHOULD use the closest core type
+  and describe the detail in `attributes`. The vocabulary is closed in v0.1 and reopening it is an
+  open question for v0.2.
+
+## 4. Identifiers
+
+- `id` MUST be stable for the lifetime of the principal. A value that changes when the principal is
+  renamed, moves department or changes email address is not an identifier.
+- `id` SHOULD be an opaque internal identifier rather than an email address, username or national
+  identification number. Direct personal identifiers make audit data harder to minimize, harder to
+  retain lawfully, and harder to share for analysis.
+- Personally identifiable display names MUST NOT be required by an implementation. A stable
+  identifier is sufficient to satisfy the model; `displayName` exists for systems that must present
+  the event to humans without a directory lookup, and SHOULD be omitted otherwise.
+- `roles` SHOULD contain only the roles relevant to the audited operation. An event is not the place
+  to snapshot a principal's complete role inventory.
+
+## 5. Subject
+
+`subject` is the principal **on whose behalf** the actor performed the operation.
+
+### 5.1 When to use it
+
+| Situation                                                            | actor                       | subject       |
+| -------------------------------------------------------------------- | --------------------------- | ------------- |
+| An API service performing an operation for a signed-in user          | the service                 | the user      |
+| An administrator impersonating a customer                            | the administrator           | the customer  |
+| A background worker executing a previously requested operation       | the worker service account  | the requester |
+| A delegated administrator performing an approved action for an owner | the delegated administrator | the owner     |
+
+### 5.2 Rules
+
+1. `subject` MUST NOT be used as a generic target of the operation. The audited target belongs in
+   `resource`. This is the single most common modelling mistake this section exists to prevent.
+2. `subject` MUST be omitted when the actor acted for itself. An event where actor and subject are
+   the same principal carries no additional information and SHOULD NOT duplicate it.
+3. When `delegation.type` is `impersonation`, `on-behalf-of` or `delegated`, `subject` is REQUIRED.
+   The canonical schema enforces this.
+4. Service-to-service operations do NOT automatically require a subject. A service that performs
+   scheduled maintenance under its own authority has no subject. See
+   [approval-and-delegation.md](approval-and-delegation.md).
+
+### 5.3 Examples
+
+A service acting for a user:
+
+```json
+{
+  "actor": { "type": "service", "id": "service-account-reporting-worker" },
+  "subject": { "type": "user", "id": "user-8842" },
+  "delegation": { "type": "on-behalf-of", "reference": "export-request-4471" },
+  "resource": { "type": "report", "id": "export-4471" }
+}
+```
+
+An administrator acting **on** a user — no subject, because nobody delegated authority:
+
+```json
+{
+  "actor": { "type": "admin", "id": "admin-4821" },
+  "resource": { "type": "user", "id": "user-7391" }
+}
+```
+
+## 6. Attributes
+
+`attributes` carries producer-defined principal detail that has no core representation, such as a
+workload class or an authentication realm.
+
+`attributes` MUST NOT contain credentials, tokens, keys or session material, and SHOULD NOT contain
+personal data beyond what the audit purpose requires. See [privacy.md](privacy.md).

package/specification/approval-and-delegation.md

@@ -0,0 +1,150 @@
+# Approval and Delegation
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. Three questions that are routinely confused
+
+| Question                                               | Field            | Nature                                |
+| ------------------------------------------------------ | ---------------- | ------------------------------------- |
+| How did the actor prove who it is?                     | `authentication` | Identity evidence                     |
+| Is the actor permitted to do this?                     | `authorization`  | Policy evaluation, usually automatic  |
+| Did someone decide this may proceed?                   | `approval`       | Decision by principals, usually human |
+| How did the actor obtain authority to act for another? | `delegation`     | Transfer of authority                 |
+
+They are independent. An operation may be authenticated and authorized but unapproved; approved but
+denied by policy; or performed by a delegated actor whose own authorization is what was evaluated.
+Each has its own object, and a producer MUST NOT use one to express another.
+
+## 2. Approval
+
+`approval` records a decision, usually by humans, that the operation may proceed. It is OPTIONAL.
+
+### 2.1 Structure
+
+All fields are OPTIONAL; when the object is present it MUST contain at least one.
+
+| Field               | Meaning                                                |
+| ------------------- | ------------------------------------------------------ |
+| `status`            | State of the approval at the time of the event.        |
+| `workflowId`        | Approval workflow definition or instance.              |
+| `requestId`         | The approval request itself.                           |
+| `requiredApprovals` | Number of approvals required by policy.                |
+| `receivedApprovals` | Number of approvals received at the time of the event. |
+| `approvers`         | Principals that approved.                              |
+| `approvedAt`        | When the approval reached its current status.          |
+
+### 2.2 Status
+
+`status`, when present, MUST be one of:
+
+| Value          | Meaning                                                           |
+| -------------- | ----------------------------------------------------------------- |
+| `not-required` | Policy determined that no approval was needed for this operation. |
+| `pending`      | Approval was requested and has not been decided.                  |
+| `approved`     | The required approvals were received.                             |
+| `rejected`     | Approval was refused.                                             |
+| `expired`      | The approval request lapsed before it was decided.                |
+| `unknown`      | The producer cannot determine the approval state.                 |
+
+`not-required` is not the same as omitting the object. `not-required` asserts that the question was
+asked and answered; omission says nothing at all. Producers that evaluate approval requirements
+SHOULD record `not-required` explicitly, because "no approval was needed" is itself an auditable
+statement.
+
+### 2.3 Rules
+
+1. Approval MUST NOT be required for all events. Most operations in most applications have no
+   approval step, and forcing an approval object onto them produces noise, not evidence.
+2. A profile MAY require approval for a specific class of events. That requirement belongs to the
+   profile, never to the core model. See [profiles/](../profiles/).
+3. `approvers` SHOULD identify the principals whose decisions were counted, not everyone who was
+   notified.
+4. `receivedApprovals` SHOULD be consistent with the length of `approvers` when both are present. The
+   schema does not enforce this, because an approver may legitimately be recorded without being
+   identifiable to the producing application.
+5. An event with `status` of `pending` or `rejected` and a successful outcome describes a control
+   bypass. Producers SHOULD record it accurately rather than suppressing it; that combination is
+   exactly what a reviewer needs to find.
+
+## 3. Delegation
+
+`delegation` records **how the actor obtained authority to act for the subject**. It is OPTIONAL.
+
+### 3.1 Structure
+
+| Field        | Required | Meaning                                                  |
+| ------------ | -------- | -------------------------------------------------------- |
+| `type`       | Yes      | Kind of delegation.                                      |
+| `reason`     | No       | Why delegation was used.                                 |
+| `reference`  | No       | Grant, ticket or session that authorized the delegation. |
+| `approvedBy` | No       | Principal that approved the delegation.                  |
+
+`type` is REQUIRED when the object is present. Delegation without a type cannot be interpreted, and
+the conditional rule in §3.3 depends on it.
+
+### 3.2 Types
+
+| Value           | Meaning                                                                                       |
+| --------------- | --------------------------------------------------------------------------------------------- |
+| `impersonation` | The actor assumed the subject's identity. The system behaved as if the subject acted.         |
+| `on-behalf-of`  | The actor acted for the subject using its own identity.                                       |
+| `delegated`     | Authority was granted to the actor in advance, for example a delegated administrator.         |
+| `service-chain` | The operation traversed intermediate services. Describes transport, not a person's authority. |
+
+### 3.3 Subject requirement
+
+When `delegation.type` is `impersonation`, `on-behalf-of` or `delegated`, the event MUST contain
+`subject`. The canonical schema enforces this.
+
+The reason is simple: each of these types asserts that someone else's authority was used. An
+assertion of borrowed authority that does not say whose authority was borrowed is not auditable.
+
+`service-chain` does **not** require a subject. Service-to-service operations are routine and often
+have no human principal behind them at all. Requiring a subject for every service call would force
+producers to invent one, which is worse than recording nothing.
+
+### 3.4 Impersonation
+
+Impersonation is the highest-risk case in this model, because the system's own records elsewhere will
+show the subject acting. Producers that support impersonation:
+
+- MUST record `actor` as the impersonating principal, never as the subject.
+- SHOULD record `reason` and `reference`.
+- SHOULD record `approvedBy` where the impersonation required approval.
+- SHOULD include `privileged-access` in `controlCategories`.
+
+## 4. Worked example
+
+An administrator impersonates a customer to reproduce a fault, with an approved support case:
+
+```json
+{
+  "event": {
+    "name": "identity.session.impersonate",
+    "category": "identity",
+    "outcome": "success",
+    "severity": "critical"
+  },
+  "actor": { "type": "admin", "id": "admin-4821" },
+  "subject": { "type": "user", "id": "user-7391" },
+  "delegation": {
+    "type": "impersonation",
+    "reason": "Reproducing a reported checkout failure.",
+    "reference": "support-case-3391",
+    "approvedBy": { "type": "user", "id": "user-1180" }
+  },
+  "resource": { "type": "session", "id": "session-impersonation-5f21" },
+  "authorization": { "decision": "allow", "policy": "support-impersonation" },
+  "approval": {
+    "status": "approved",
+    "requestId": "approval-request-7781",
+    "requiredApprovals": 1,
+    "receivedApprovals": 1,
+    "approvedAt": "2026-03-14T10:02:00Z"
+  },
+  "controlCategories": ["privileged-access", "change-approval"]
+}
+```
+
+Note what each object contributes: `authorization` says policy permitted it, `approval` says a person
+sanctioned it, `delegation` says whose authority was used, and `subject` says who that was.

package/specification/authentication.md

@@ -0,0 +1,116 @@
+# Authentication Context
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. Purpose
+
+`authentication` records **how the actor proved its identity** for the session behind this operation.
+It is OPTIONAL.
+
+It answers questions such as: was this a password sign-in or a certificate? Was multi-factor
+authentication satisfied? Which identity provider asserted the identity? How old is the session?
+
+## 2. Structure
+
+All fields are OPTIONAL. When the object is present it MUST contain at least one of them.
+
+| Field             | Meaning                                                             |
+| ----------------- | ------------------------------------------------------------------- |
+| `method`          | Authentication method used. Closed vocabulary, see §3.              |
+| `provider`        | Identity provider that performed authentication.                    |
+| `mfa`             | Whether multi-factor authentication was satisfied for this session. |
+| `assuranceLevel`  | Producer-defined assurance level.                                   |
+| `sessionId`       | Session correlation identifier.                                     |
+| `authenticatedAt` | When the session behind this operation was authenticated.           |
+
+## 3. Methods
+
+`method`, when present, MUST be one of:
+
+```text
+password   mfa       oidc      saml       certificate
+api-key    service-account     session    anonymous
+other      unknown
+```
+
+Notes:
+
+- `mfa` as a _method_ means the producer knows only that a multi-factor flow was used and cannot
+  identify the primary factor. Where the primary factor is known, producers SHOULD record it in
+  `method` and set the `mfa` boolean to `true`. The two are not redundant: `method` is _what_ was
+  used, `mfa` is _whether a second factor was satisfied_.
+- `session` means the operation reused an established session rather than performing a fresh
+  authentication.
+- `other` and `unknown` are escape values. `unknown` MUST NOT be used to avoid deciding.
+
+## 4. Absence is not anonymity
+
+This is the most important rule in this document.
+
+**An absent `authentication` object and `method: anonymous` mean different things.**
+
+| Situation                                                 | Correct representation                 |
+| --------------------------------------------------------- | -------------------------------------- |
+| No authentication context is available or applicable      | Omit `authentication` entirely         |
+| The principal was deliberately unauthenticated            | `authentication.method` is `anonymous` |
+| The producer knows a session existed but not how it began | `authentication.method` is `unknown`   |
+
+A consumer MUST NOT treat a missing `authentication` object as evidence that the operation was
+unauthenticated, and MUST NOT treat it as an error.
+
+The model MUST allow authentication context to be absent for:
+
+- System-generated operations.
+- Background jobs and scheduled processes.
+- Non-interactive service-to-service operations.
+- Events imported from legacy systems that never recorded it.
+
+## 5. Assurance level
+
+`assuranceLevel` is a producer-defined token describing how strongly the identity was established,
+for example `low`, `substantial` or `high`.
+
+The core specification deliberately does NOT define an assurance scale and does NOT map to any
+external assurance framework. Assurance frameworks are jurisdiction-specific and revised on their own
+schedules; binding the core model to one would violate
+[design principle 9](design-principles.md#9-regulation-neutral-industry-neutral-jurisdiction-neutral).
+Producers that need a framework mapping SHOULD publish it alongside their own value definitions.
+
+## 6. Session identifiers
+
+`sessionId` is a **correlation identifier**, not a credential.
+
+`sessionId` MUST NOT be a usable session token, bearer token, cookie value or anything else that
+would allow a reader of the audit event to assume the session. Where the underlying session
+identifier is itself the credential, producers MUST record a derived, non-reversible correlation
+value instead — for example a keyed hash — or omit the field.
+
+See [privacy.md](privacy.md) for the complete list of values that MUST NOT be recorded.
+
+## 7. Relationship to authorization and approval
+
+Authentication, authorization and approval are three different questions and MUST NOT be conflated:
+
+| Question                                             | Field            |
+| ---------------------------------------------------- | ---------------- |
+| Who is this principal, and how do we know?           | `authentication` |
+| Is this principal permitted to do this?              | `authorization`  |
+| Did someone decide this should be allowed to happen? | `approval`       |
+
+See [authorization.md](authorization.md) and
+[approval-and-delegation.md](approval-and-delegation.md).
+
+## 8. Example
+
+```json
+{
+  "authentication": {
+    "method": "oidc",
+    "provider": "corporate-idp",
+    "mfa": true,
+    "assuranceLevel": "high",
+    "sessionId": "session-b71f",
+    "authenticatedAt": "2026-03-14T09:58:02Z"
+  }
+}
+```

package/specification/authorization.md

@@ -0,0 +1,117 @@
+# Authorization Context
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. Purpose
+
+`authorization` records the **decision** that permitted or denied the operation. It is OPTIONAL.
+
+The purpose is to make the decision reviewable after the fact: which policy applied, which version of
+it, what it decided, and why. Without this, a reviewer looking at a denied operation cannot tell
+whether the control worked or whether the request never reached it.
+
+## 2. Structure
+
+| Field           | Required | Meaning                                              |
+| --------------- | -------- | ---------------------------------------------------- |
+| `decision`      | Yes      | Outcome of the authorization evaluation.             |
+| `engine`        | No       | Component that produced the decision.                |
+| `policy`        | No       | Identifier of the policy that produced the decision. |
+| `policyVersion` | No       | Version of that policy.                              |
+| `reason`        | No       | Sanitized explanation of the decision.               |
+| `permissions`   | No       | Permissions evaluated or required for the operation. |
+
+When `authorization` is present, `decision` is REQUIRED. An authorization object that records a
+policy but no decision is not useful and is rejected by the schema.
+
+## 3. Decisions
+
+`decision` MUST be one of:
+
+| Value            | Meaning                                                    |
+| ---------------- | ---------------------------------------------------------- |
+| `allow`          | The operation was permitted.                               |
+| `deny`           | The operation was refused by the authorization evaluation. |
+| `not-applicable` | No authorization evaluation applied to this operation.     |
+| `unknown`        | The producer cannot determine what the evaluation decided. |
+
+A `deny` decision normally accompanies `event.outcome` of `failure`, and the event MUST then carry
+`event.error`. Recording the denial as a successful operation misrepresents the control.
+
+`not-applicable` is meaningful: it distinguishes "no policy governs this" from "we did not record
+it". Producers SHOULD prefer omitting the object entirely when they simply have no information.
+
+## 4. This is a record, not an engine
+
+OpenAuditModel records authorization **results**. It MUST NOT become an authorization system.
+
+Consequently:
+
+1. The model defines no policy language, no rule syntax and no evaluation semantics.
+2. The schema MUST NOT require any particular policy engine, and MUST NOT contain any engine's
+   vocabulary. `engine` is a free identifier precisely so that no engine is privileged.
+3. A consumer MUST NOT attempt to re-evaluate a policy from an audit event. Audit events describe
+   what happened; they are not an input to access control.
+4. Nothing in this specification should be read as requiring centralized policy evaluation. An
+   application whose authorization is ordinary code in a service can populate `decision`, `reason`
+   and `permissions` perfectly well.
+
+## 5. Policy identification
+
+`policy` and `policyVersion` exist so that a reviewer can reconstruct **which rule** produced the
+decision. Recording a decision without identifying the rule that produced it makes historical review
+unreliable, because policies change.
+
+Producers that version their policies SHOULD populate `policyVersion`. A `policy` value SHOULD be
+stable across releases in the same way an event name is.
+
+## 6. Reason
+
+`authorization.reason` is a sanitized, human-readable explanation of the decision, such as
+"role does not grant the requested permission on this tenant".
+
+It MUST NOT contain the full policy document, the complete attribute set that was evaluated,
+credentials, or personal data beyond what the audit purpose requires. A consumer MUST NOT parse it.
+
+This field is distinct from the top-level `reason` object, which records the **business
+justification for performing the operation**. One explains the machine decision; the other explains
+human intent. An event may carry both.
+
+## 7. Permissions
+
+`permissions` lists the permissions evaluated or required for the operation, using the producer's own
+permission vocabulary. It SHOULD contain the permissions relevant to **this** operation, not the
+principal's complete permission set.
+
+## 8. Example
+
+```json
+{
+  "authorization": {
+    "decision": "allow",
+    "engine": "policy-service",
+    "policy": "privileged-configuration-change",
+    "policyVersion": "23",
+    "reason": "Actor holds the platform administrator role within an approved change window.",
+    "permissions": ["configuration.setting.update"]
+  }
+}
+```
+
+A denial:
+
+```json
+{
+  "event": {
+    "name": "document.file.download",
+    "category": "data-access",
+    "outcome": "failure",
+    "error": { "code": "permission-denied", "type": "authorization", "retryable": false }
+  },
+  "authorization": {
+    "decision": "deny",
+    "policy": "document-access",
+    "reason": "Requested classification exceeds the actor's clearance."
+  }
+}
+```

package/specification/change-model.md

@@ -0,0 +1,134 @@
+# Change Model
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. Purpose
+
+`change` records **what the operation changed**. It is OPTIONAL.
+
+The difficulty is that the most useful audit answer — "what was it before?" — is also the most
+dangerous one to record. A naive implementation that serializes the whole record before and after
+turns the audit log into a second, less protected copy of the production database. This document
+exists to make the safe options first-class.
+
+## 2. Structure
+
+All fields are OPTIONAL; when the object is present it MUST contain at least one.
+
+| Field           | Meaning                                                    |
+| --------------- | ---------------------------------------------------------- |
+| `type`          | Kind of change performed.                                  |
+| `changedFields` | Paths of the fields that changed.                          |
+| `before`        | Sanitized prior state, or the part of it that changed.     |
+| `after`         | Sanitized resulting state, or the part of it that changed. |
+| `beforeHash`    | Digest of the prior state.                                 |
+| `afterHash`     | Digest of the resulting state.                             |
+| `ticketId`      | Change or service ticket associated with the change.       |
+| `incidentId`    | Incident associated with the change.                       |
+| `deploymentId`  | Deployment or release associated with the change.          |
+
+## 3. Change types
+
+`type`, when present, MUST be one of:
+
+```text
+create   update   delete   restore   move   execute   none   other
+```
+
+Notes:
+
+- `execute` describes an operation that ran something without changing stored state in the ordinary
+  sense — resetting a consumer offset, triggering a job, rotating a key.
+- `none` records that an operation completed without changing anything. This is meaningful for
+  idempotent operations, where "nothing changed" is a real result rather than a missing value.
+- `other` exists so that producers are not forced into a wrong value.
+
+## 4. Complete state is never required
+
+The schema MUST NOT require complete `before` and `after` objects. A producer MAY describe a change
+in whichever of these ways fits its risk profile:
+
+| Approach                | What it records                          | When to prefer it                                   |
+| ----------------------- | ---------------------------------------- | --------------------------------------------------- |
+| **Changed field names** | `changedFields` only                     | The fact of change matters; values are sensitive    |
+| **Sanitized state**     | `before` and `after` for selected fields | Values are needed for review and are safe to record |
+| **Hashes**              | `beforeHash` and `afterHash`             | Verification is needed without disclosure           |
+| **References**          | `ticketId`, `incidentId`, `deploymentId` | The authoritative detail lives in another system    |
+
+These compose. Recording `changedFields` together with hashes gives a reviewer the shape of a change
+and the ability to verify a claimed prior state, while disclosing neither.
+
+## 5. What MUST NOT go into before and after
+
+`before` and `after` MUST NOT contain:
+
+- Passwords, password hashes, or password history.
+- Access tokens, refresh tokens, API keys, private keys or connection strings.
+- Complete database records copied verbatim.
+- Full request or response payloads.
+- Special-category personal data that the audit purpose does not require.
+
+A change to a credential MUST be recorded as the **fact** of the change, never as its values:
+
+```json
+{
+  "event": { "name": "identity.credential.rotate", "category": "identity", "outcome": "success" },
+  "change": { "type": "update", "changedFields": ["clientSecret"], "ticketId": "change-4410" }
+}
+```
+
+Recording `{"before": {"clientSecret": "..."}}` is a defect, not a more complete audit event.
+
+## 6. Guidance for before and after values
+
+1. Producers SHOULD record only the fields named in `changedFields`, not the entire object.
+2. Producers SHOULD apply the same masking rules to `before` and `after` that they apply to any other
+   sensitive output, and SHOULD record `privacy.processing` when they do. See
+   [privacy.md](privacy.md).
+3. Large collections SHOULD be summarized rather than embedded. A permission change affecting 4,000
+   users is better recorded as a count and a scope than as 4,000 identifiers.
+4. `before` and `after` SHOULD be structurally comparable. Recording an object in one and a rendered
+   string in the other prevents automated diffing.
+5. Where a change is not expressible as a field diff — a document body replaced, a binary uploaded —
+   producers SHOULD use hashes or an evidence reference instead. See
+   [evidence-model.md](evidence-model.md).
+
+## 7. Hashes
+
+`beforeHash` and `afterHash` allow a reviewer to verify a claimed prior or resulting state without
+the audit event containing it.
+
+- The algorithm and encoding SHOULD be documented by the producer, and SHOULD match the algorithm
+  recorded in `integrity.hashAlgorithm` where an integrity object is present.
+- A hash of a low-entropy value is reversible by enumeration. Producers MUST NOT treat a hash of a
+  small value space, such as a boolean flag or a status enumeration, as a privacy control.
+
+## 8. Correlation to change management
+
+`ticketId`, `incidentId` and `deploymentId` connect the technical change to the process that
+authorized it. They are plain identifiers: the model deliberately does not define a change management
+process, a ticket format or a workflow.
+
+Where the change was approved, `approval` records the approval itself; `change.ticketId` records the
+record it was approved under. See [approval-and-delegation.md](approval-and-delegation.md).
+
+## 9. Example
+
+```json
+{
+  "change": {
+    "type": "update",
+    "changedFields": ["sessionLifetimeMinutes", "requireReauthenticationForPrivilegedActions"],
+    "before": {
+      "sessionLifetimeMinutes": 720,
+      "requireReauthenticationForPrivilegedActions": false
+    },
+    "after": {
+      "sessionLifetimeMinutes": 60,
+      "requireReauthenticationForPrivilegedActions": true
+    },
+    "ticketId": "change-9910",
+    "deploymentId": "deployment-2026-03-16-3"
+  }
+}
+```