Skip to main content

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.

​
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. 
thisHash_n = sha256(
    seq_n
  · kind_n
  · actor_n
  · subjectRef_n
  · payloadHash_n   = sha256(canonical(payload_n))
  · prevHash_n      = thisHash_(n-1)
  · at_n
)
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

FamilyEvent 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.
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.