> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayerup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit, Decision Lineage & Action Lineage

> Tamper-evident by construction: every governance-relevant event is appended to a hash-chained log per tenant. Decision and Action lineage are graph projections over the audit chain.

# 17 — Audit, decision lineage & action lineage.

Layerup's audit substrate is tamper-evident by construction: every governance-relevant event
is appended to a hash-chained log per tenant. Decision and Action lineage are graph
projections over the audit chain; both are queryable, replayable, and exportable.

## 17.1  Audit chain construction

Each tenant has its own append-only audit log. Each event holds a hash that includes the previous event's hash, forming an immutable sequence.

```text theme={null}
thisHash_n = sha256(
    seq_n
  · kind_n
  · actor_n
  · subjectRef_n
  · payloadHash_n   = sha256(canonical(payload_n))
  · prevHash_n      = thisHash_(n-1)
  · at_n
)
```

```mermaid theme={null}
flowchart LR
  E0[event 0<br/>genesis]
  E1[event 1]
  E2[event 2]
  E3[event 3]
  E0 -- prevHash --> E1 -- prevHash --> E2 -- prevHash --> E3
  A[anchor T0] -. covers seq 0 to N0 .-> E1
  B[anchor T1] -. covers seq after N0 .-> E3
```

*Fig. 17.1 — Hash chain with periodic anchors. Anchors commit the chain root to a tamper-evident store.*

## 17.2  Anchoring

Periodically, the chain root is committed to a tamper-evident store. Three anchoring strategies are supported and selectable per tenant:

* **KMS-signed anchor** — the root is signed by a tenant-controlled HSM-backed KMS key on a fixed cadence.
* **Internal transparency log** — the root is committed to a separate append-only Merkle tree maintained by the platform; tenant can audit inclusion proofs.
* **External transparency log** — the root is committed to a tenant-chosen external transparency log (e.g. RFC 6962-style).

## 17.3  Event taxonomy

| Family      | Event kinds (illustrative)                                                                     |
| ----------- | ---------------------------------------------------------------------------------------------- |
| identity.\* | `identity.login` · `identity.scope_grant` · `identity.break_glass` · `identity.session_revoke` |
| policy.\*   | `policy.allow` · `policy.deny` · `policy.update`                                               |
| data.\*     | `data.ingest` · `data.mapping.applied` · `data.calibrator.update` · `data.retention.exception` |
| ontology.\* | `ontology.fork` · `ontology.promote` · `ontology.merge` · `ontology.deprecate`                 |
| tool.\*     | `tool.dispatch` · `tool.result` · `tool.exception`                                             |
| model.\*    | `model.promote` · `model.demote` · `model.train.opt_in`                                        |
| decision.\* | `decision.commit` · `decision.supersede`                                                       |
| action.\*   | `action.stage` · `action.approval.*` · `action.commit` · `action.revert`                       |
| config.\*   | `config.change` · `config.rollback`                                                            |

## 17.4  Decision lineage

The Decision lineage of a Decision *D* is the connected subgraph reachable backwards from *D* through:

* the AgentRun that produced *D* (or the human Principal),
* every Tool call recorded by that run, with their args / results / model lineage,
* every EvidenceSpan cited by *D* and the Documents they reach,
* every Property read by the run with its provenance record.

## 17.5  Action lineage

The Action lineage of an Action *A* is the connected graph forward from *A* and backward to the Decision that proposed it:

* backward: the Decision *D* that proposed *A*, the Run that produced *D*, the EvidenceSpans for *D*,
* forward: the approval chain (Tasks / human Decisions), the SoR commit receipt, any compensation,
* the AuditEvents covering each transition.

## 17.6  Replay bundle export

Replay bundles (§8.7) extend to Decisions and Actions: a bundle for Decision *D* includes its Decision lineage; a bundle for Action *A* includes both lineages plus the SoR receipt. Bundles are signed with the tenant's audit key.

## 17.7  Evidentiary export formats

* **CEF** (Common Event Format) and **OCSF** (Open Cybersecurity Schema Framework) for SIEM ingestion.
* **JSONL** per-event, signed and chain-anchored.
* **.lrb** (Layerup Replay Bundle) for full reconstructability.
* **Regulator-package** — a tenant-configured combination of the above with redaction rules applied.

## 17.8  Legal-hold pinning

Subjects under legal hold are pinned: their objects, evidence, decisions, actions and audit slice cannot be deleted regardless of retention configuration. The pin is itself an AuditEvent; release of the hold is another. The substrate refuses any deletion that would break a hold.

## 17.9  Tamper-detection

The audit verifier walks the chain forwards and validates every `thisHash` against its computed value. Any breach raises a critical incident; the chain is sealed at the breach point and a new chain is started under operator supervision. Original chain contents are preserved.

## 17.10  Retention floor

The audit chain has a minimum retention longer than any related object retention so that lineage queries remain answerable for the full life of the underlying data, including for data subject to legal hold.