The inspector, for compliance and audit staff#

The inspector is the web screen over a BitExact deployment's evidence. This guide is for the people who read that evidence: compliance officers, internal and external auditors, model-risk reviewers. It needs no engineering background. What the evidence proves, and how an auditor checks it independently, is Verifying a bundle.

Signing in#

Open the address your administrator gave you. Either your organization's single sign-on signs you in, or you see a BitExact sign-in page that asks for a viewer token. Your role decides what you can do, and your scope may limit which workflows or environments you can see. Settings ▸ Access shows both. Sign out is in the account menu (top right) and in the main menu (the BitExact mark, top left).

Finding your way around#

The header holds the five screens most work needs: Overview, Runs, Cases, Verify and Trust. More holds Workflows, Replay and fork, and Settings. The account menu, at the right, says who you are signed in as, in which role and environment, and holds the Simple/Advanced choice, the dark theme and Sign out. The environment (for example prod) stays in view beside the BitExact mark. The BitExact mark opens the main menu, which lists every screen you can open and marks the one you are on; on a phone it also holds what the account menu holds. Search (or Ctrl K) finds a run or a screen, and on a run it also offers that run's acts: verify it, download its evidence pack, add it to a case. Press ? for every keyboard shortcut.

If the license is close to its end date, expired, or not accepted, a one-line bar under the header says so on every screen. Details opens what still works and how to check the license. The 30-day warning can be put away until the next day; the others stay until the license is fixed.

A screen your role does not allow says so, with a lock, and points to Settings ▸ Access for what your role can do. A screen Simple mode hides offers to show it. A screen that cannot load says why, with Try again and Go to Runs.

Get started#

On a new deployment with no runs, the inspector opens on Get started: four steps, one open at a time.

Ready to record checks the license, the recorder key and whether the license names that key. Each check that fails shows the one command that fixes it, with a copy button and Check again. Without a recorder key you can skip the step, but runs then verify as intact and unsigned.
Record a run offers a one-minute sample run (recommended), the SDKs, or pointing an OpenAI-compatible client at the recorder. It checks every 3 seconds for the first run and moves on by itself when it arrives, with no reload. It pauses while the tab is hidden and stops after 10 minutes (Keep waiting starts it again).
See it verified shows the run's verdict and its proof lines. An unsigned run says how to have future runs signed.
Hand it to an auditor downloads the run's evidence pack. The step is done when the server has recorded the pack on the run's custody chain.

The main menu offers Get started until every step is done.

If your administrator gave you a token, it should be a read-only (auditor-read) one, so the inspector opens in Simple mode and offers only what reading evidence needs. If it opens in Advanced and offers fork, hold or redaction buttons, you were given an administrator's token: ask for your own. Administrators: Identity and access, "Give compliance staff their own read-only token".

Simple and Advanced#

If your role can only read, the inspector opens in Simple mode. It shows the path from "which decision?" to "hand me the evidence", and folds the engineering views away. Advanced shows everything your role allows, including replay, forks and regression suites. Switch between them in the account menu, or from the main menu; the inspector remembers your choice. The mode only changes what is on screen. Your role decides what you may do, and switching to Advanced never grants anything.

The Overview#

The Overview answers "is anything wrong?" first. Needs attention appears only when something does: runs that fail verification, redaction requests waiting for a second approver (each with the fields it would withhold), a production deployment with no sign-in, a license that has expired or is about to, runs past their retention deadline, and problems the store's health check found. Each is one sentence with the button that deals with it. When nothing needs attention, the list is not there at all.

Under it, four counts: Runs, Verified, signed (how many of them are intact, sealed and signed), Capture (surfaces recorded in some runs but not others, which is worth a look but not proof of a gap) and Retention (runs missing a retention deadline). Each opens the runs it counts. Then the five newest runs. A store with no runs yet opens Get started instead.

Finding the decision a complaint is about#

Runs lists every recorded run, newest first. A complaint, a dispute or a subject-access request names a customer, an application or a person, so start with the search field at the top:

Find a run searches every run, not only the page on screen. Type a customer or application id, the party a run acted for, the identity the agent acted as, a run id, a model, or the first characters of a run's last entry hash. A run is listed when any of them matches, and under its id it says what matched ("matched subject", "matched on behalf of", "matched acting principal", "matched run id"). The Subject column shows each run's subject and, under it, the identity the agent acted as.
The filter buttons under it narrow the list: Workflow, Environment, Period, Status and, in Advanced mode, Agent. A set filter shows its value on its button, with a button beside it to clear it; Clear clears them all. Period takes two days: from the start of the first day to the start of the second, UTC, so a run that started exactly on the second day belongs to the next period and two packs never count a run twice. Status offers the same names the runs show (Verified, signed; Intact, unsigned; and so on), plus "On legal hold" and "Anchored".

Workflow, environment, period, agent and the search ask the server, so they reach every run in the store, and the count at the top is how many runs match in the whole store. The list itself shows the newest 500 of them; when more match, a note under the list says "Showing the newest 500 of N runs", and narrowing the filters brings the rest into view. The status filter applies to the runs shown.

On a phone each run is a card: its id and status, its workflow and environment, and its subject (or step count) and when it last changed. The filters are behind one Filter button; Select shows the boxes for choosing runs.

A run's id, subject and principal are set by the system that recorded it. If the search finds nothing for a customer you expect, ask the engineering team which business key their runs record (integrations.md, "Finding the decision a complaint is about").

Reading a run#

Open a run and you see, top to bottom: Runs / the run's id (with a copy button), the verdict, What this run is, the run's acts, and its tabs.

The verdict. It is the first block on the page. A run is in one of six states, and each has one name, one color and one icon everywhere the inspector shows it: in Runs, the Overview, a workflow's runs, a case's pinned runs, the run itself, its Verify drawer and the Verify page. A list shows the short name; the run shows the headline.

In a list	On the run	What it means
Verified, signed	Intact, sealed and signed	It verifies, it is sealed, and a recorder key signed it.
Intact, unsigned	Intact and sealed, not signed	It verifies and is sealed, but no key attests who recorded it.
Intact, not sealed	Intact so far, never sealed	It verifies, but nothing closed it, so steps lost from its end would not show. The run says how to seal it.
Recording	Recording now	It is still being written. Its integrity is attested when it seals.
Fails verification	Do not rely on this run	Do not use it as evidence. The line that fails says which check, in plain words.
Not checked	Not checked yet	The inspector could not check it just now; it says why.

"Verified" is said only of a signed run. Under the headline, each check is its own labeled line, so what was recorded and who signed it are never one statement:

Unchanged: nothing recorded has been changed or removed.
Sealed: the end of the run is attested, so steps lost from its end would show.
Signed by: the recorder key that signed it, and whether this deployment's license names that key. When it does not - a run another deployment signed, or one this inspector holds no license for - the line says so: the signature then proves the record is intact under that key, not who holds it. Confirm the key with the producer through a channel of your own.
Anchored (only when an anchor exists): the outside timestamp or write-once copy that pins it.
Withheld fields (only when something is withheld): each one is accounted for by a redaction on the chain.

Every state except a failing one ends with the one thing never claimed: "Not claimed: that this is every call the agent made." BitExact proves the record is intact. It does not prove the agent did nothing outside what was recorded.

In Runs, the Status column and the Status filter use the same six names; ticking two shows the runs in either.

At the verdict's right are the two acts an auditor needs: Verify it yourself and Evidence pack, which downloads the pack at once. On a phone they are a bar at the bottom of the screen. A run that nothing is sealing gives the seal command with a copy button. A failing run names the failing check first, says "Do not use this run as evidence. Tell your administrator.", and offers only Verify. Technical details, closed until you open it, holds the last entry's hash (with a copy button), the entry count, the platform and the anchors.

What this run is: the decision the run recorded, each fact shown only when the run has it: the workflow and its version, the environment, the subject, the identity the agent Acts as, the party it acted On behalf of (with the party's type), whether a Person in session was there, whether it was an Adverse action and a Solely automated decision, whether a Human review is recorded, when it started and sealed, and a legal hold in force. Each fact the agent stated carries the asserted mark, as the Steps timeline draws it. A run that changed the party it acted for, or whether a person was in the session, says at which step and from what to what; the facts show the latest. Full decision record opens the Decision record tab. A run with no decision record says so. A failing run shows none of this: its recorded contents are not evidence.
The acts: Add to case and Place hold (or Release hold), as your role allows, then More, which holds Export (the evidence pack for an auditor, the bundle as JSON or JSONL for your own tooling, or telemetry spans, which are not evidence), Run info and, in Advanced mode and as your role allows, Replay, Fork, Fork matrix and Lineage. The menu moves with the arrow keys and closes with Escape.
The tabs: Steps, Decision record, Capture scope, Custody, Reviews, plus Sources for a run several hosts wrote and Compared to source for a fork. A tab's count is in its label, as "Steps (10)".
Steps: each step the agent took, in order, at the left, and the step you chose at the right. A row gives the step's number, a mark for how it was captured, its name, the tool or person that acted (and, for a run several hosts wrote, the agent), and its time. The marks, with the word on hover and read out by a screen reader:
- a filled dot, observed: BitExact captured it at the wire. For a run recorded on several machines, the step says which host relayed it.
- a half-filled circle, asserted: the system told BitExact. It records who said so; it is not an authenticated fact.
- an outlined diamond, synthetic: a counterfactual written by a "what if" fork. It is never part of the production record.
A declared capture gap is the one tinted row, "Gap: " and its cause: BitExact saying what it could not capture, and why, the honest alternative to a silent hole. Up and Down move through the steps (Home and End to the ends), and [ and ] do the same from anywhere on the page; the detail follows without the page redrawing. The detail's heading names the step ("Step 4 · Model call · observed") with a button that copies its exhibit reference. Its tabs are named for the step's kind: Request and Response for a model call, Arguments and Result for a tool call, Recorded data for any other step, then Integrity and Raw. A recorded value is a tree: each object or list folds and opens (Enter or Space on its line), those below the second level start folded, text is shown whole, and a long hash is shortened in the middle with a copy of the whole. Search in this step keeps only the keys and values that match. Raw is the step exactly as recorded. On a phone, tapping a step opens it full-screen, with Prev and Next; closing it returns you to the step's row.
Decision record: under what model, policy and prompt version the decision was made, and whether a human review is recorded. A recorded review is asserted by the system that reported it. Whether it meets a regulation such as GDPR Art. 22(3) or the EU AI Act Art. 14 is your judgment; the record does not conclude it.

Verifying, and handing evidence over#

Verify it yourself (on a run) opens the Verify drawer. It leads with the Result in this inspector: the verdict and a table of every check, each with what it proves in plain words. That is the inspector checking itself. Under it, Verify it yourself, offline gives three numbered steps: Download evidence pack (it carries the verifier, its runbook and the bundle); unzip it and run the command its runbook gives, python data/verification/bitexact_verifier.py ., from the folder that holds bagit.txt; then run it again pinning the recorder key with --expect-recorder-key. The drawer shows the key this deployment's license names; confirm it with the producer by phone or signed email, because a key read from the system being audited proves nothing on its own. Verifying the bundle alone with pip is under "Advanced", closed until you open it.
A run still being written shows Recording, never Fails verification, even before its writer has signed its first checkpoint: nothing recorded so far contradicts it, and its Signed by line says it is not signed yet. Its recorded content (its decision, identity and step values) is not shown until a licensed key signs it, and the run says "Recording — content is shown once the run is signed.": anyone who can write the store could hold a run open, so being written proves nothing about who wrote it. Once it is sealed, a run the license's recorder key did not sign fails as before.
Verify ▸ Verify a file you were handed is one drop zone for any file someone gave you: an evidence pack's zip, a bundle (whole or streamed), a signed envelope, or a signed regress-suite or model-qualification report. The page tells which it is from the file; when the file does not say, it asks. Options, closed until you open them, pin an expected signing key, another deployment's recorder key or witnesses, require a seal, or stop pinning this deployment's licensed recorder key. The result takes the drop zone's place, with Verify another file to bring it back. For evidence it runs the same verifier an auditor runs offline, and shows the command it ran, with a copy button, so you can repeat it on your own machine and depend on nothing in this system. A signed report's result is two statuses, never one: whether its Signature verifies, and The report's own verdict (a valid signature over a failed gate shows both).
Verify ▸ Verify a run in this system re-checks a stored run, and Verify offline instead holds the commands and what each pin flag pins.
Evidence pack (on a run, a case, a ticked selection of runs, or the filtered list) builds a sealed folder an auditor can verify with Python and the two libraries its runbook names. It contains every run's evidence, a workpaper, the verifier itself, and a record of what was asked for. Taking evidence out is recorded in each run's custody log. In Runs, ticking a run brings up a bar at the bottom of the window ("2 runs selected · Evidence pack · Save as pack · Clear"); Evidence pack for this list, at the top, packs every run the workflow, environment, agent and period filters match. Either opens a drawer that says what the pack will hold and what it proves before you download it. The search and the status narrow the screen only, never the pack, and the drawer says so.
Pack library saves a selection under a name, such as "Q3 claims sample", to issue again later. It is rebuilt from the store each time, so a run redacted since then is redacted in the pack too.

Cases and reviews#

A case is an investigation file: an incident, an examination sample, an inquiry. The Cases list leads with each case's title (its id under it), then its kind, status, who is assigned, how many runs it holds, whether its chain verifies, and when it last changed. New case opens a sheet for the case's id, title, kind and description.

A case's page reads first. Its title is the heading, with the id, kind and who opened it under it, and Case evidence pack at the right. Below are the pinned runs, each with its verdict and why it was pinned (unpin one from its row's actions menu; you are asked first), and one Activity feed: every note, finding and act on the case, in the order it happened. One box at the foot writes a Note or a Finding (with its disposition), about the whole case, a pinned run, or one step of it.

The Properties beside them save as you change them: the status (closing a case asks first), the assignees (type a name and press Enter), and Pin a run, which searches the store's run ids as you type. On a phone they fold into one line under the heading that opens them.

From a run's own screen, Add to case pins it into an open case, or into a new one opened in the same drawer; you stay on the run. A finding about a whole run is a reviewer's sign-off on that run, and shows on the run's own screen. The case file is itself tamper-evident: it records who did what, when, in a chain like a run's.

Holds and redaction#

Legal hold (on a run, for roles that may place one) stops the run from being deleted by retention until the hold is released. Placing and releasing a hold are both recorded on the run. Both work even after the license has expired, as does redaction: they are legal obligations, and a late renewal must never block one.
Redaction withholds personal data from a run while the run still verifies: each withheld field keeps a cryptographic commitment that proves a value was there. It takes two people. One requests it, choosing the fields and giving a reason; a different person approves, or rejects it with a reason of their own. The two must sign in as two principals: with viewer tokens, each person needs a named token (docs/identity-access.md). Only fields that can be withheld are offered. A step that closes a run, or one that records a hold or a redaction, cannot be withheld.

The Trust page#

What a party outside your organization needs in order to rely on this evidence:

Recorder keys: one table of every recorder key, each with where it comes from: Signed runs in the store, Held by this inspector, or Named by the license. One key seen in several places is one row. Settings ▸ Keys shows the same table. Download trust file gives the keys found in the evidence to the offline verifier; send the producer's key to your auditor through a separate channel;
the transparency log: every run's signed end goes into one log that independent witnesses can cosign, so this deployment cannot show two parties two different histories. The log card names any run the log remembers that the store no longer holds;
External anchors, with how to add one;
a numbered checklist for a relying party, each item linking to where it is had in the inspector. A signed report someone handed you (a regress suite or a model qualification) is checked on the Verify page.

Keyboard#

Press ? for the list of shortcuts; Keyboard shortcuts in the main menu opens the same list.

Ctrl K (⌘K on a Mac) searches runs and jumps to any screen.
/ puts you in the screen's search field.
G then O, R, C, V, T or S goes to Overview, Runs, Cases, Verify, Trust or Settings.
In a list, J and K move between rows (and the arrow keys, once a row has the focus), Enter opens one, and X ticks it for an evidence pack. Esc clears the ticks.
On a run, [ and ] step through its steps (in the step list, the arrow keys too), V opens Verify and E downloads its evidence pack. Esc closes what is open, then goes back to Runs.

A single-key shortcut works only while you are not typing in a field. If you use a screen reader, its browse mode reads letters as its own commands: press its pass-through key first (NVDA+Space in NVDA), or turn the single-key shortcuts off in the list. The inspector remembers that choice in this browser.

When something looks wrong#

A run fails verification: do not use it as evidence. The first line under its verdict says which check failed. Tell your administrator, who will see the same thing on Settings ▸ Health.
A refused action shows the server's reason, for example that your role may not perform it, that the license has expired (reading, exporting and placing a legal hold keep working), or that the run is under hold.
A page about the license instead of the inspector: the license is missing or failed its check. The page says which, and where this deployment's license file goes; your administrator installs it.
Your session ended: sign in again, and the inspector returns you to the same screen.
"Too many failed sign-ins": after several wrong tokens from your address, the sign-in page asks you to wait a few seconds before the next try, and says how long. Nobody else is held up by it. Check the token you were given, then try again.