Reading an audit log

The Yig audit log is the source of truth for what happened during a workflow run. It is designed to be sufficient — without access to the agent runtime — for a downstream audit, a compliance review, or a post-incident investigation. This article explains what each record contains, how records chain together, and how an auditor reads the trail.

The structure of a run trail

A run trail is a chain, not a log. A gap is visible as a gap. Each Yig workflow execution produces a sequence of append-only records. No record is modified or deleted after it is written. The argument for why the chain has this shape is in the shape of an audit trail; this is the field reference.

A complete run trail contains:

1. A run record — the opening record that identifies the run.
2. One or more tool records — one per tool call made during execution.
3. A draft record — written when the agent produces a reviewable output.
4. One or more reviewer action records — written each time a reviewer acts on the draft.
5. An approval record — written when the reviewer gate is satisfied and the output ships.

If a run does not complete — because it was halted by a yellow flag, a tool failure, or a reviewer rejection — the trail ends without an approval record. Incomplete runs are not errors; they are a normal part of the workflow. An incomplete trail is itself an audit-meaningful record.

The run record

The run record anchors the chain. Without one, the trail has no head.

Fields:

• run_id — a stable, time-ordered identifier for this run. Unique across the deployment.
• workflow — the name and version of the template that was executed.
• invoked_by — the identity of the user or process that triggered the run.
• invoked_at — timestamp (UTC) of when the invocation was received.
• surface — the surface from which the run was invoked (CLI, Slack, Teams, API gateway).
• entity and period — the scope parameters passed to the workflow.

What it answers: Who started this run, what were they running, and from where?

Tool records

One record is written for each tool call made during execution.

Fields:

• run_id — links this record to the containing run.
• step — the sequence number of this tool call within the run.
• tool — the name of the tool called.
• input_shape — a typed description of the inputs provided to the tool. Not the data itself — the shape (field names, types, scope parameters).
• output_shape — a typed description of what the tool returned.
• duration_ms — elapsed time for the tool call.
• status — success, failure, or flagged.

What it answers: What did the agent do, in what order, and did each step succeed?

The input and output shapes are structural descriptions, not the underlying data. They establish that the agent called the right tool with the right scope — without exposing the financial data in the log.

The draft record

Written when the agent produces the structured output to be reviewed.

Fields:

• run_id — links to the containing run.
• draft_id — a stable identifier for this specific draft version.
• draft_version — an incrementing counter. If the agent regenerates a draft after a reviewer resolves a flag, the new draft is a new version; the original version is retained.
• output_shape — the structure of the draft (table, schedule, narrative, etc.).
• flag_count — the number of yellow flags in this draft.
• presented_to — the identity of the reviewer(s) to whom the draft was presented.
• presented_at — timestamp.

What it answers: What was the reviewer asked to review, in what form, and when?

Reviewer action records

One record per reviewer action. A reviewer may take multiple actions on a single draft (for example, resolving flags one by one before a final approval).

Fields:

• run_id and draft_id — link to the run and draft being acted on.
• action — accept, reject, accept-with-edits, or comment.
• reviewer — the authorised identity who took the action.
• timestamp — when the action was taken.
• target — if the action applies to a specific line or flag rather than the whole draft, the identifier of that item.
• comment — the reviewer’s free-text judgment, if provided.
• diff — if the reviewer edited the draft, the structured difference between the pre-edit and post-edit version.

What it answers: Who reviewed what, when, and what did they decide?

The approval record

The entry the external auditor cites when asked “who signed this.” It binds a specific draft version to a named human and a destination in the customer’s stack.

Written when the gate is satisfied — when a reviewer action of accept or accept-with-edits is received from an authorised reviewer.

Fields:

• run_id and draft_id — the approved run and draft version.
• approved_by — the authorised reviewer.
• approved_at — timestamp.
• shipped_to — the destination to which the approved output was written.
• model_provider and model_id — the model provider and model identifier used for this run.

What it answers: Who approved the output, when, which version was approved, where did it go, and which model produced it?

How to read a run trail in an audit

Six questions are answerable from the trail alone. If any are not, the chain has a gap.

An auditor reading a Yig run trail should be able to answer six questions from the records alone:

1. Who triggered the run? Run record: invoked_by.
2. What data did the agent access? Tool records: tool and input_shape for each data read.
3. What did the agent produce? Draft record: output_shape, flag_count, draft_version.
4. Who reviewed it? Reviewer action records: reviewer for each action.
5. What did the reviewer change? Reviewer action records: diff for any accepted-with-edits actions.
6. Who approved it, and when? Approval record: approved_by and approved_at.

If any of these cannot be answered from the trail, the run is incomplete or the trail is damaged. An incomplete trail — a run that produced a draft but has no approval record — indicates a workflow that was not completed. The draft was not shipped. This is auditable and expected.

What the audit log does not contain

A debug trace records what the system did so a developer can fix it. An evidence-of-process record contains what an external reviewer needs to reconstruct a decision they did not witness. The first is for the inside; the second is for the outside. The Yig log is the second.

The audit log records shapes, identities, and timestamps. It does not contain:

• The raw financial data read from source systems.
• The full text of model prompts or responses.
• The content of the draft (only its shape and identifier).

Evidence of process is a structurally different artefact than logging for debugging. Leaving business content in the customer’s source systems is what makes the log defensible to a stranger three years from now. If the trail ever contains raw data — prompts, financial values, draft text — the log stopped being evidence and became a vendor-side copy of the customer’s books. That day is not on the roadmap.