Skip to main content
This page is for operators answering compliance, forensics, or post-incident questions. Forge keeps an append-only audit trail. Every governance decision, lifecycle transition, configuration change, and agent execution event is recorded with full actor attribution. No mutation paths can update or delete records. The only deletion path is the daily retention sweep at the configured TTL. Two questions come up most, and each has one call: what happened in one run (its audit packet), and what happened across the deployment in a window (a compliance export). For the live operator surfaces (Watchtower / Events / InterventionCenter), see Observability. For the gate-by-gate provenance, see Trust Fabric in production.

Pull a run’s audit packet

A run’s audit packet answers, in one read, what happened in the run and why governance passed, held or blocked it. It is a summary built for review and export, not every row: it carries counts, the latest decision, and the run’s 15 most recent key events. The calls use the FORGE_BASE and ACCESS_TOKEN set up in the Raw HTTP tab of the quickstart.
1

Find the run

If you kept data.runId from the dispatch response, skip this step. Otherwise list the workflow’s recent runs, newest first:
This needs runs:read. A page can be short while meta.hasMore is true; follow meta.nextCursor to read on.
2

Read the packet

This needs workflows:read where the run lives, and it refuses an External App token: send a Personal key or a platform API key as the bearer. A credential that holds it nowhere gets a recorded 403; one that holds it only elsewhere gets a recorded 404, the same answer as a run that does not exist.
3

Read it top to bottom

Over MCP, forge_call_read_operation reads the same packet. It is in the default start job, so no job selection is needed:
For every audit row of a period rather than one run’s summary, use a compliance export.

Event structure — what every row carries

This is the shape of each record a compliance export returns, alongside a stable id. Only two fields are required — event and timestamp. Everything else is optional, so treat any other field as “present when the emitter had it”, not as guaranteed: The functions that take an actor argument record their authenticated caller instead: the uploader of a workflow document, the creator of a tool, skill, agent or step, the author of a scheduled org change, the actor of a bridge audit event, and who granted or revoked a worker’s raw-bash grant. The argument (uploadedBy, createdBy, authorId, actor, grantedBy or revokedBy) is accepted so existing callers keep working, and is ignored. The resourceType values, in schema order, are agent, skill, model, gateway, deployment, document, workflow, project, worker_role, policy, ai_generation, codebase, run, step, position, evaluationRun, tool, factory, budget, platform, chatDraft, worker, provider, capability, procedure, pod, credential, secret, knowledge_entry, knowledge_export, workflowTriggers, and file. A workflowTriggers event identifies the Capability URL ingress trigger for an accepted or rejected workflow request. Its resourceId is the trigger ID; the audit detail records the outcome and status code, without the request body. A knowledge_entry event is shown only to a reader who can read the knowledge namespace it names. A knowledge_export event, a refused knowledge export, is not fenced that way, so every audit reader sees who asked to export which namespace and why it was refused. It never carries knowledge content. A file event records one allowed read of a stored file: a download link, text, bytes, a copy into a sandbox, or a copy into platform data. It is written before the link or any byte leaves. That covers reads through the API’s file content and inference routes, a procedure, a workflow agent, a chat or builder session, a Console download, and ingestion. Ingestion means adding a file to knowledge and importing an org chart; it records mode: "ingest" and names the person or app that asked for it. A read whose event cannot be written is refused. Its resourceId is the file ID (a stored blob with no file row is named by its storage ID), actor names the reader (Observe › Run history shows it in words: a person, app, agent or API key by name, a procedure or chat session as such, never its id), and detail holds the surface, the mode and a reference (a request, invocation, session, chat message, run or attempt ID). It never carries the file name or content. Some reads write no file event, by design: a run’s output delivered to its declared destination, avatars, and generated exports.

Audit categories

The canonical list has 23 categories. The root audit writer validates category against it before writing through the forge-governance component. The component’s category column is a string, but its category list mirrors the root list and its resourceType column validates against the component’s resource-type enum. Contract tests require both lists to stay in parity. The two highlighted categories (governance, safety_gate) carry Trust Fabric decisions and remain fiduciary records — these are the rows compliance and post-incident review will ask for first.

Traceability records

For every governed dispatch, the Trust Fabric also produces a traceability record in the trustFabricEvents table — separately from auditEvents. The traceability record is structured for compliance forensics and ClickHouse export; the audit row is structured for the operator timeline. Both reference the same dispatch. Like auditEvents, this table is component-only; it is not in the root Convex schema. STD-03.3 describes the traceability contract; what is materialized today is the column set below. Query against these names — several plausible-sounding packet names (decisionRecord, executionTrace, explanationPacket, auditRecord) are not columns on this table, and there is no content-hash / environment-ID tamper-evidence column at all. Indexes: by_trace, by_agent, by_disposition, and by_timestamp. Today only workflow dispatch produces these records — chat, factory, and copilot dispatch don’t yet. As governance coverage extends to those paths, traceability records will follow.

Authorization denials — where the row survives

A denial is only useful in the audit trail if the row is still there afterwards. A write is one transaction, so a denial row written inside a write that is then refused is rolled back with the refusal — the evidence disappears exactly when it matters. Forge therefore never records a denial from inside a read or a write. The refused call fails with a typed error (data.code === "FORBIDDEN", carrying the missing permissionKey) and records nothing. Durable denial rows come from contexts that are not part of a caller’s transaction: Those two are the whole list today; they are the only callers of the denial recorder. Both land in the same governanceAuditLog decision record — there is no separate denial table — with disposition: "block", stepId: "authz", and a single permission gate result naming the missing key. Filter on those fields rather than on a surface name. A blocked governance gate is a different row, not a missing one. It is also written durably from an action context, but it carries the gate sequence it actually ran and the dispatch’s own stepId, and its dispatchSurface is the dispatch type (workflow_node, agent_tool, tool, procedure, step, chat, and so on) rather than an authorization surface. Client-reported rows are not enforcement evidence. The console is the only observer of a denial raised inside a query or mutation, so it reports what it saw. That report is authenticated, validated against the closed permission catalog, and capped per user per hour. Because the reporter is the client, those rows are excluded by default from:
  • the governance overview counts (blockCount, blockRate) an operator reads as enforcement metrics,
  • the compliance export — both halves of it, GET /api/v3/compliance-export-governance (the records) and GET /api/v3/compliance-export-summary (the counts) — unless you ask for them with includeClientReported=true, which both routes accept and interpret identically, and
  • the Logs viewer’s governance feed. That one is not a metric, but it maps disposition: "block" to log level error and its return shape cannot carry the reportedBy label — so an unverified self-report would render there as an ERROR-level governance block, indistinguishable from enforcement. It also reads the newest rows per disposition off the index, where a denial is the newest block row by construction.
Rows written before the reportedBy label existed carry no value and are treated as server-side, so the label never shortens a historical export. The exclusion is applied inside the index range rather than to the fetched page, so an excluded row never displaces a real decision out of a capped window. A denial row is not a latency sample, a gate result, or a dispatch — whoever reported it. Every denial carries stepId: "authz", no durationMs, and one synthetic always-failing permission gate. Three surfaces therefore exclude the whole authz step rather than a reporter: the governance p99 in the weekly performance report, the per-gate pass/block tallies on the Gates dashboard, and the “recent blocked dispatches” card. That exclusion is by stepId, not by reportedBy, because a server-observed denial is real enforcement evidence — it stays in the compliance export, the overview counts and the decision aggregates. It just cannot express latency, it is not an engine gate outcome, and it is not a dispatch. permission is a real member of the governance gate sequence, which is precisely why the exclusion is by stepId and not by gate name. A denial row’s permission result is an authorization refusal wearing a gate-shaped field — always failing, never marked skipped, and never produced by the engine evaluating that gate. Counting it would conflate the authz seam with the real gate, so the gate’s genuine pass rate would read as polluted by every 403 the platform served. The displacement risk is what makes this load-bearing rather than cosmetic. by_disposition is keyed [disposition, timestamp], so on the block leg a denial is among the newest rows by construction — any reader that takes the newest N blocks would otherwise show denials and crowd genuine decisions out of a capped window entirely. A client-reported row is also deliberately unattached: its runId is the constant authz:console, never a workflow run, so a report cannot appear on a run’s audit packet as if a gate had blocked that run. The route the person was on is recorded in the row’s explanation. Read a client-reported row for what it is: a person hit a wall on a specific page, which is worth knowing when you are calibrating entitlements — and is not a claim that a gate held. Where you can read them is the decision explorer on Trust Fabric → Decisions, which returns whole rows and keeps the reportedBy field. The console does not render that field yet, so on that page a self-report currently looks like any other block. Until it does, tell the two apart by the fields the row does show: a denial has stepId: "authz", a single permission gate, and a runId of authz:console (client) or a route path (server) rather than a workflow run id. The compliance export carries reportedBy verbatim, so a scripted read can filter on it today.

The permission gate — what a decision row says about authority

The permission gate answers a different question from the authorization denials above: not “may this person call this function” but “may this dispatch’s principal take this action”. It is a real member of the governance gate sequence, evaluated in the engine’s early phase right after the identity check, and it runs on three surfaces: A procedure invocation is the newest of the three. It previously produced only a procedureInvocationAudits row, so the decision record — and every metric built on it — was silent about that surface. It now writes a governanceAuditLog row like any other dispatch. What the row records is the shortfall, not the authority. The gate computes effective = principal ∩ role ∩ tier; a required key absent from that intersection lands on the row as missingPermissionKeys. The keys the principal holds are never persisted — that snapshot is resolved once per dispatch and is an input to the decision, not part of it. So a decision row can tell you what an action needed and did not have; it cannot be mined for who can do what. Read entitlements from the entitlement surfaces instead. The gate has two evaluation arms, and they mean different things. (A third code, required_keys_undeclared, comes from the tool seam rather than from the gate’s own evaluation — see An undeclared tool is not an unrestricted one below.)
  • permission_denied — the principal resolved, and a required key was missing. missingPermissionKeys names exactly which.
  • principal_unresolved — the dispatch could not be attributed to anyone. This is a refusal, not a pass: an action nobody is accountable for is the case the gate exists to stop.
Enforced decisions. The permission gate refuses a missing key or an unresolved principal. missingPermissionKeys records the required keys that were absent; blockedByGate identifies the control that refused the action. Agent and tool decisions also retain the gate result’s errorCode, including permission_denied, principal_unresolved, and required_keys_undeclared. The retired shadow flag is absent from decision storage and exports. Passed gate results may still carry advisory causes such as nhi_not_configured, si02_no_hash, si02_version_resolution_error, or policy_advisory_require_approval_not_held. A passed result is advisory evidence; stopping-check readers and gate statistics select passed: false. Publish-judge warn remains a separate advisory mode and records its audit event. An undeclared tool is not an unrestricted one. The keys an action requires come from its own definition. A tool or procedure that declares requiredPermissionKeys: [] requires no key, so it has no key to be missing. One that declares nothing at all falls to a stricter default: an internal tool is evaluated against tools:read, and an external tool is refused outright with required_keys_undeclared, because defaulting an outbound call to a read-shaped key would authorize egress on the weakest key in the catalog. An empty required set is not a bypass of the gate. principal_unresolved is decided before the required keys are consulted at all, so a dispatch nobody could be attributed to is still refused even when the action it was calling required nothing. Declaring [] waives the key check, never the accountability check.

Protected data classification

STD-06 defines six duty-of-care classes for data flowing through agent interactions. Read this section as the standard’s taxonomy, not a shipped audit feature — see the warning below it before you plan a compliance workflow around it. What the durable record does carry per dispatch is fiduciaryFlag — a boolean on trustFabricEvents, taken from the dispatching agent’s own fiduciaryFlag and mirrored inside governancePacket. It tells you the agent was fiduciary-flagged at dispatch; it does not tell you which class of data it touched, and it is not indexed, so it is not a filter dimension either. The filter dimensions that do exist on audit rows are category, resourceType / resourceId, actorType, runId, and a full-text search over event. In the console’s audit view they surface as time range, category, and search.

Evidence explorer and reports

The Console Decisions page reads organization-scoped decision evidence with fixed-window, filter-bound cursor pagination. Exact recorded person, run, step, agent, tool, policy, gate, and dispatch-surface fields are shown when present; absent historical values remain Unknown. Client-reported evidence is excluded by default and visibly labeled when included. The Reports tab on Decisions provides bounded reports with explicit scanned, eligible, unknown, sampled, and coverage metadata. Its on-behalf-of access report shows current-grant-only context for a validated published run’s version. It no longer correlates approvals, because approvals stopped recording grant descriptors. Current grants are never used to reconstruct historical authority. JSON, Markdown, and RFC 4180 CSV exports describe their authorized organization scope, fixed filters/window, loaded population, and coverage. A capped scan, sampled aggregate, unavailable source, or loaded-row cap remains labeled as such in the export.

Compliance exports over the Platform API

Three reads cover a window of at most 90 days: GET /api/v3/compliance-export-audit pages the audit events, GET /api/v3/compliance-export-governance pages the governance decision records, and GET /api/v3/compliance-export-summary counts the decisions. startTime and endTime are epoch milliseconds; make several requests for a longer period.
Each page is newest first, up to 1,000 records (limit). Pass the page’s data.cursor back as cursor until it is null; add category to export one audit category. Over MCP, forge_call_read_operation runs the same export:
The quickstart’s ACCESS_TOKEN does not carry audit:read: mint a token with scope=audit:read, or send a Personal key whose scopes include it. Compliance exports cover the whole deployment, so they require audit:read granted at the deployment root; a credential granted only below it receives 403. A key or app holding audit:read at a tenant org unit, or at a partner organization’s own root, gets 403 forbidden with requiredPermission: "audit:read", and the refusal is recorded as an authorization denial. Platform-scope grants and every migrated key’s root compatibility grant keep the exports. Records keep their stored shape, including principal, because the reader is a deployment-root auditor. The governance export pages to the end of any window; a page that had to skip records sharing one millisecond says partial: true with saturatedAt. See Compliance.

Retention

A daily retention sweep deletes audit events older than 365 days. It caps each run at 2,000 deletes or 20 seconds of elapsed time to stay within mutation limits, and resumes simply by scanning oldest-first: the rows it removes are the progress, so the next run necessarily starts after the last one. There is no stored cursor to get stuck. Retention is currently a flat 365 days across all categories — there is no category-level override today. Related signals have their own sweeps: token events and execution events run on independent retention periods. If your compliance regime requires longer than 365-day retention (some financial / health / pastoral contexts do), configure an external archive: page the compliance exports into S3 or a data warehouse on a schedule, and treat Forge’s retention as the working window, not the system of record.

Operator runbook

When you operate the audit surface day-to-day:
  1. Build saved filters for your common questions. “All governance decisions for the Customer Success team this week” or “every approval rejected in the last 30 days.” Operators who type the filter every time eventually stop looking.
  2. Pull run audit packets early. The moment a run looks suspicious, export its packet. It is much faster to look at the export than to re-navigate the live UI when the question turns into a multi-stakeholder review.
  3. Review an export by hand before sharing. The audit row carries no data classification, so nothing marks a sensitive row for you. Read the detail payloads in a packet you are about to hand to a stakeholder — the export carries whatever the emitter put there, and the recipient may not have access to the underlying data.
  4. Archive before the window closes. Retention deletes audit events after 365 days. If you need them longer, export each window well before its oldest events reach that age.