# Rulings

A ruling is the witness's decision on a protected tool call: allow or block. The witness makes it while it co-signs the call's decision record, and returns it on the record's receipt, signed with the same service key. The tool runs only on allow.

A ruling proves three things to someone who trusts neither you nor us: what the witness allowed or blocked, under which version of your rule set, and when. It carries the witness's time and names the co-signed record and the batch that holds it, which a public timestamp fixes in time. The client keeps the receipt it was given at decision time, and two different rulings for one record fail verification. A ruling attests the witness's decision, never that the call was right.

How a tool is protected: [Recorded and protected](/docs/checks#recorded-and-protected). What the witness rules with: [Rules](/docs/rules) and the [list of known bad tools](/docs/fingerprints#the-shared-list).

## What a ruling holds

This is a ruling from the [quickstart](/docs/quickstart)'s run: a payout of 640 EUR, allowed, while the Calibrating rule "Block approve_payout when currency is not "GBP"" would have blocked it.

```json
{
  "basis": "default",
  "batch_hash": "373a647b33d01eb696683a06b711520ce09a1bf775a4294995151a3c9ffc8b38",
  "fingerprints": 0,
  "matched": [],
  "missing": [],
  "mode": "enforce",
  "reason": "Allowed (default).",
  "record_hash": "4b4bffbe631e6cf9830ef52728266780e398f1d9f87c47c186f735f17c8c8023",
  "rules": {
    "hash": "6e64caf7900982fb72a2932e1f7dc2adfd69f64e834a0f4545a4cd1137129c6b",
    "set": "rs_01JD2K8Z5X3V7N2M4K6H8G0F1A",
    "version": 2
  },
  "ruling": "allow",
  "server_time": "2026-11-17T23:42:10.283Z",
  "v": 1,
  "would_block": [
    "approve_payout-currency"
  ]
}
```

| field | meaning |
|---|---|
| `record_hash`, `batch_hash`, `server_time` | the co-signed decision record it rules on, and the batch that holds it |
| `ruling` | `allow` or `block`. Nothing lies between them |
| `mode` | `enforce` (On); `watch` (Calibrating) only for a rule set still Calibrating from before rules had their own state |
| `would_block` | the Calibrating rules that would have blocked the call |
| `excepted` | the rules an exception kept from matching: the call was allowed from now on |
| `enforce_ruling` | for a Calibrating rule set only: the ruling On would have given |
| `basis` | why, below |
| `matched` | the rules that matched, for basis `rule` and `error` |
| `missing` | for basis `fields_missing`: the fields the tool must send (`signafaide pull` asks for them), by name, never by value |
| `rules` | the version of your rules the witness ruled with: always its newest |
| `fingerprints` | the version of the list of known bad tools the witness held |
| `reason` | one sentence for people; it never quotes a sent value |

## Basis

The witness takes the first that applies:

| basis | ruling | when |
|---|---|---|
| `rules_version` | block | the client names a rule set version newer than the witness holds |
| `fields_missing` | block | a field an On rule needs for this call was not sent |
| `fingerprint` | block | the tool, its description or its MCP server is on the list of known bad tools |
| `error` | block | a rule's condition met a value of the wrong type |
| `rule` | block or allow | an On block rule matched, else an allow rule matched |
| `default` | the rule set's default | no rule matched; allow when there is no rule set |

The witness evaluates only your rules and the list of known bad tools, over the fields you sent. A project with no rules gets rulings all the same: a call to a known bad tool is blocked, every other call is allowed.

## Calibrating rules and exceptions

A Calibrating rule never makes a ruling block and never asks for a field. When it would have blocked the call, the ruling names it in `would_block`, and the call runs. When an exception kept a rule from matching, the ruling names that rule in `excepted`. The auditor view lists both under "Allowed despite a rule, or by exception", with the version each call was ruled under.

A rule set made before rules had their own state may still be Calibrating: then every ruling is `allow`, and `enforce_ruling` says what On would have done.

## No ruling

A protected call whose ruling does not come within 10 seconds (unless the checks file sets `ruling_timeout_ms`) does what the console says for that tool if signafAIde can't be reached. Stop, the default: it does not run and raises `no_ruling`. Let it run: it runs and its outcome says `ruling: none`. Either way the decision is sent, and the witness rules on it when it arrives, so a call that ran without a ruling still gets one on record, and the verifier reports it.

The witness rules once per record: a record sent again gets its original ruling, never a new one. A blocked decision is still accepted and co-signed: it is the evidence that the call was asked for and stopped.

## In the records

The decision record holds what the client's checks found, the versions of the rules it applied, whether the call was protected, and the names of the fields it sent. The outcome record says whether the tool ran and which ruling it had: `allow`, `block`, `none` (no ruling received) or `not_asked` (not protected, or blocked on the client first). A blocked call's outcome holds the error, naming the check or rule. From the quickstart's run:

```json
{"error":{"check":"rule","message":"approve_payout did not run: signafAIde blocked it under \"Block approve_payout when amount is above 1,000\" (rule set version 1). To allow such calls, change the rule in the console. https://signafaide.co.uk/r/f1d759e8989a9c1a5605400f4406db5c6bc3214bd01b4f0264c0ed4d6e88804b","rule":"approve_payout-amount","type":"Blocked"}}
```

## What verify reports

`signafaide verify`, locally or on a pack, adds `tool-call checks:` lines for each agent, then the rules the pack holds in words, each with its state. From the quickstart's pack:

```text
tool-call checks: payout-bot: 2 tool calls checked: 1 allowed, 1 blocked by the witness
tool-call checks: payout-bot: notes: rule 1
tool-call checks: payout-bot: 2 protected calls ruled by the witness: 1 allowed, 1 blocked
tool-call checks: payout-bot: rule sets used: rs_01JD2K8Z5X3V7N2M4K6H8G0F1A version 1
rules: rs_01JD2K8Z5X3V7N2M4K6H8G0F1A version 1: rule approve_payout-amount: Block approve_payout when amount is above 1,000 (On)
rules: rs_01JD2K8Z5X3V7N2M4K6H8G0F1A version 1: rule approve_payout-currency: Block approve_payout when currency is not "GBP" (Calibrating)
```

Other lines name the notes by check, protected calls that had no ruling when they were decided, and calls that ran after a block, by sequence number. These are reports, not failures: a pack that shows a call ran after a block is an authentic pack showing exactly that. The signatures of the rulings and of the rule set versions are part of the 12 checks, and each rule set version a kept record names is kept and goes into the pack, so an auditor can read the rules a ruling used.

## In the console

- **Each tool's page** lists its calls with the ruling, the rule in words and the version. A blocked call's link from the error opens it there, with Allow from now on for an admin.
- **Block alerts** email you when a call is blocked, and when a call ran after a block (Solo and up; webhooks on Enterprise).
- **Reports**: the verification report for a period shows the checked calls, the rulings and the rule set versions in force (Solo and up).

On the machine that holds the records, the local MCP server's `signafaide_explain_ruling` explains one record's ruling in words: its basis, the rules that matched, the version of the rules, the fields not sent and how to allow the call. It never prints a sent value.
