# Arxo Fact Protocol

The Arxo Fact Protocol is what a host submits: the case with its facts and
their origin, the question, and the pinned program the question is asked
under. The same three parts stand behind the conversational tools, behind
the client library in [From code](/guide/from-code/) and behind the
`law ask` command on the command line.

## The case

The case is a list of assertions plus the context they are read in. Each
assertion carries an identifier, a literal (a predicate with its
arguments), and an origin: [`case_input`](/protocols/schemas/evaluation-request/)
for facts that arrived with the case,
[`external_snapshot`](/protocols/schemas/evaluation-request/) for facts
taken from a pinned source, [`derived`](/protocols/schemas/evaluation-request/)
for conclusions of an earlier answer re-submitted as facts, and
[`adjudicated`](/protocols/schemas/evaluation-request/) for facts decided
by an authority. The context holds the three dates of the question: the
legal date, the decision date and the date of knowledge.

A host that has only a list of facts does not need to assemble a full
case. It sends each fact in a short form; the origin and the place in a
document are optional. The short form names the predicate and the
arguments, and may carry a provenance with the origin, a span in a document
(page and quote) and the extractor with its confidence:

`predicate`, `args`, `provenance.origin`, `provenance.span`,
`provenance.extractor.name`, `provenance.extractor.version`,
`provenance.extractor.confidence`.

`confidence` is carried, not evaluated: it travels as a decimal string,
and whether a fact with that confidence counts is decided by the
package's evidence policy, not by the host.

## The question

The question is one of the closed kinds defined by the
[query](/protocols/schemas/query/) schema: `truth`, `focused_truth`,
`why_not`, `argumentation`, `precedent`, `formula`, `collect`, `term`,
`positions`, `weak_permission`, `interpretation_analysis`, `calendar_op`.
Every question carries a `queryId` that ties the answers back to it. A
truth question over one literal looks like this:

<!-- schema: query -->
```json
{
  "queryId": "insured",
  "kind": "truth",
  "literal": {
    "args": [
      {
        "id": "urn:entity:acme",
        "kind": "entity_ref"
      }
    ],
    "kind": "literal",
    "polarity": "positive",
    "predicate": "urn:law:vectors:cp:norms#insured"
  }
}
```

## The pinned program

The request names the program instead of sending it: the compiled package,
its [`semanticVersion`](/protocols/schemas/evaluation-request/), and the
pinned dependencies it was built against. The host names the program; it
never sends a program of its own under someone else's answer. The engine
checks the pin before any computation: a pin it does not know is refused
by name.

## A full request

A complete [evaluation-request](/protocols/schemas/evaluation-request/)
document carries all three parts at once. The example below is a recorded
request: two case assertions about one person, the three dates in the
context, a question about the positions held, and the pinned program it
was asked under.

<!-- schema: evaluation-request -->
```json
{
  "case": {
    "assertions": [
      {
        "contentHash": "sha256:a9cd219133b0c1ef8f814cdc4478809d4f8d75288c70adc9c525289d7b1fe6d3",
        "evidence": [],
        "id": "urn:law:vectors:err-e0218-judgment#assert-trigger-positive",
        "kind": "assertion",
        "literal": {
          "args": [
            {
              "id": "urn:entity:p1",
              "kind": "entity_ref"
            }
          ],
          "kind": "literal",
          "polarity": "positive",
          "predicate": "urn:law:vectors:err-e0218-judgment#trigger"
        },
        "origin": "case_input",
        "package": "urn:law:vectors:err-e0218-judgment"
      },
      {
        "contentHash": "sha256:61a3bb8c8dc2b9a85043cd577279044496e2d2c08b2e9661f85823fd3f2ee176",
        "evidence": [],
        "id": "urn:law:vectors:err-e0218-judgment#assert-done_a-negative",
        "kind": "assertion",
        "literal": {
          "args": [
            {
              "id": "urn:entity:p1",
              "kind": "entity_ref"
            }
          ],
          "kind": "literal",
          "polarity": "negative",
          "predicate": "urn:law:vectors:err-e0218-judgment#done_a"
        },
        "origin": "case_input",
        "package": "urn:law:vectors:err-e0218-judgment"
      }
    ],
    "context": {
      "decisionTime": "2026-08-26T12:00:00+05:00",
      "knowledgeTime": "2026-08-26T12:00:00+05:00",
      "legalTime": "2026-08-26",
      "timezone": "Asia/Qyzylorda"
    },
    "options": {}
  },
  "ir": {
    "artifactHash": "sha256:6cad5bcbbd19de9b0fc84f45d0bd39c68b48f369da8a5a7c50541a638370c189",
    "features": [
      "core-executable"
    ],
    "imports": [],
    "metadata": {},
    "nodes": [
      {
        "contentHash": "sha256:c6b4c892888ba08d8fad2b249d1fd604905d3177b45dfb0fd46e48c9ba5ac5c6",
        "id": "urn:law:vectors:err-e0218-judgment#Keep",
        "kind": "norm_template",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "обязанность с составным условием цели"
          }
        ],
        "modality": "duty",
        "package": "urn:law:vectors:err-e0218-judgment",
        "payload": {
          "bearer": {
            "kind": "var",
            "var": "v0"
          },
          "goal": {
            "condition": {
              "items": [
                {
                  "formula": {
                    "args": [
                      {
                        "kind": "var",
                        "var": "v0"
                      }
                    ],
                    "kind": "literal",
                    "polarity": "positive",
                    "predicate": "urn:law:vectors:err-e0218-judgment#respectful"
                  },
                  "kind": "status",
                  "status": "established"
                },
                {
                  "formula": {
                    "args": [
                      {
                        "kind": "var",
                        "var": "v0"
                      }
                    ],
                    "kind": "literal",
                    "polarity": "positive",
                    "predicate": "urn:law:vectors:err-e0218-judgment#done_a"
                  },
                  "kind": "status",
                  "status": "established"
                }
              ],
              "kind": "and"
            },
            "kind": "achievement",
            "window": {
              "end": {
                "kind": "value",
                "type": {
                  "name": "urn:law:std#Date"
                },
                "value": "2026-12-31"
              },
              "endInclusive": true,
              "kind": "interval",
              "start": {
                "kind": "value",
                "type": {
                  "name": "urn:law:std#Date"
                },
                "value": "2026-01-01"
              },
              "startInclusive": true
            }
          },
          "kind": "duty"
        }
      },
      {
        "body": {
          "formula": {
            "args": [
              {
                "kind": "var",
                "var": "v0"
              }
            ],
            "kind": "literal",
            "polarity": "positive",
            "predicate": "urn:law:vectors:err-e0218-judgment#trigger"
          },
          "kind": "status",
          "status": "established"
        },
        "contentHash": "sha256:2e5e496e5e366eec880c100267efc5867999bc65ca102a2b74e5e091009def9f",
        "head": {
          "id": "urn:law:vectors:err-e0218-judgment#Keep",
          "kind": "norm_template_ref"
        },
        "id": "urn:law:vectors:err-e0218-judgment#KeepRule",
        "interpretations": [],
        "kind": "rule",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "обязанность с составным условием цели"
          }
        ],
        "package": "urn:law:vectors:err-e0218-judgment",
        "scope": {
          "kind": "boolean",
          "value": true
        },
        "strength": "strict",
        "variables": [
          {
            "id": "v0",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ]
      },
      {
        "contentHash": "sha256:0e1a1590a1a94b68d9d9146461d6352340c6dc6c4d5e40c1a895bda4f1aff48c",
        "id": "urn:law:vectors:err-e0218-judgment#Party",
        "kind": "type_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "сторона"
          }
        ],
        "name": "Party",
        "package": "urn:law:vectors:err-e0218-judgment",
        "typeKind": "entity"
      },
      {
        "contentHash": "sha256:c2f65ae9e80542f05ab91714ba6da2a0521dcf86f4229a3c29dfaf0e7302917b",
        "id": "urn:law:vectors:err-e0218-judgment#bad_a",
        "kind": "symbol_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "вещь не сохранена"
          }
        ],
        "name": "bad_a",
        "package": "urn:law:vectors:err-e0218-judgment",
        "parameters": [
          {
            "id": "urn:law:vectors:err-e0218-judgment#bad_a/arg/p",
            "name": "p",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ],
        "relationKind": "empirical",
        "symbolKind": "relation"
      },
      {
        "contentHash": "sha256:8327070ff7856f427264a86a939aa7ac4fa41b93ba99a5a85f69d28f9eb9cc66",
        "id": "urn:law:vectors:err-e0218-judgment#bad_b",
        "kind": "symbol_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "отчёт о плодах не дан"
          }
        ],
        "name": "bad_b",
        "package": "urn:law:vectors:err-e0218-judgment",
        "parameters": [
          {
            "id": "urn:law:vectors:err-e0218-judgment#bad_b/arg/p",
            "name": "p",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ],
        "relationKind": "empirical",
        "symbolKind": "relation"
      },
      {
        "contentHash": "sha256:38eda3f727f9112e501c7ddbfbcf0353ddc9f345c08ca1fff13f7ebfdb296599",
        "id": "urn:law:vectors:err-e0218-judgment#done_a",
        "kind": "symbol_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "первое действие совершено"
          }
        ],
        "name": "done_a",
        "package": "urn:law:vectors:err-e0218-judgment",
        "parameters": [
          {
            "id": "urn:law:vectors:err-e0218-judgment#done_a/arg/p",
            "name": "p",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ],
        "relationKind": "empirical",
        "symbolKind": "relation"
      },
      {
        "contentHash": "sha256:5bec7831a13826ecea5c199e2708cd44c3a3e0a3851e35a87fb07c68f574c15c",
        "id": "urn:law:vectors:err-e0218-judgment#done_b",
        "kind": "symbol_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "второе действие совершено"
          }
        ],
        "name": "done_b",
        "package": "urn:law:vectors:err-e0218-judgment",
        "parameters": [
          {
            "id": "urn:law:vectors:err-e0218-judgment#done_b/arg/p",
            "name": "p",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ],
        "relationKind": "empirical",
        "symbolKind": "relation"
      },
      {
        "contentHash": "sha256:55ef3403909eedbd1fa6e99857383d56a8c1e594f6ca1ca82f049acc1ce43881",
        "effect": "judgment",
        "id": "urn:law:vectors:err-e0218-judgment#respectful",
        "judgment": {
          "authority": "urn:law:vectors:err-e0218-judgment#Court"
        },
        "kind": "symbol_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "суд признал причину уважительной"
          }
        ],
        "name": "respectful",
        "package": "urn:law:vectors:err-e0218-judgment",
        "parameters": [
          {
            "id": "urn:law:vectors:err-e0218-judgment#respectful/arg/p",
            "name": "p",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ],
        "relationKind": "judgment",
        "symbolKind": "relation"
      },
      {
        "authority": {
          "id": "urn:law:vectors:err-e0218-judgment#Court",
          "kind": "const_ref"
        },
        "capability": "judgment:Court",
        "contentHash": "sha256:ad1f09de49133fc475faad42f1b7e9f11ff05a44759267888f21795d1072cfa4",
        "effect": "judgment",
        "id": "urn:law:vectors:err-e0218-judgment#respectful/external",
        "kind": "external_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "суд признал причину уважительной"
          }
        ],
        "package": "urn:law:vectors:err-e0218-judgment",
        "symbol": "urn:law:vectors:err-e0218-judgment#respectful"
      },
      {
        "contentHash": "sha256:ad2a7c7b46978fa3cdc3aa79fee65e1f02abcbb8161b4c5913aeba7a2d3319bf",
        "id": "urn:law:vectors:err-e0218-judgment#trigger",
        "kind": "symbol_decl",
        "labels": [
          {
            "language": "ru-KZ",
            "status": "unofficial",
            "text": "посылка обязанности"
          }
        ],
        "name": "trigger",
        "package": "urn:law:vectors:err-e0218-judgment",
        "parameters": [
          {
            "id": "urn:law:vectors:err-e0218-judgment#trigger/arg/p",
            "name": "p",
            "type": {
              "name": "urn:law:vectors:err-e0218-judgment#Party"
            }
          }
        ],
        "relationKind": "empirical",
        "symbolKind": "relation"
      }
    ],
    "package": {
      "name": "vectors.err_e0218_judgment",
      "namespace": "urn:law:vectors:err-e0218-judgment",
      "semanticHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "version": "0.1.0"
    },
    "schemaVersion": "law.core.ir/0.2",
    "semanticHash": "sha256:a47956edfca7cf7af1f9c1b5d93ddd3ae22f06aacbc87c22f0da85c76aac65cf",
    "semanticVersion": "0.2.4",
    "strata": [],
    "theoryHash": "sha256:a47956edfca7cf7af1f9c1b5d93ddd3ae22f06aacbc87c22f0da85c76aac65cf"
  },
  "query": {
    "kind": "positions",
    "queryId": "urn:query:lq6-e0218-judgment-leaf-dead-v02"
  },
  "schemaVersion": "law.core.evaluation-request/0.2",
  "semanticVersion": "0.2"
}
```

## Typical rejections

A request that steps outside the shape is refused before anything is
computed:

- an unknown field anywhere in the document is rejected, not silently
  skipped;
- a `schemaVersion` the reader does not know is refused by name — the host
  reads the version it knows;
- a pin the engine cannot resolve is refused before any inference;
- a question outside the [query](/protocols/schemas/query/) schema is
  rejected with the code `QUERY_INVALID` instead of being answered.

A refusal names the document and the place: every refusal body carries a
stable `code`, a `location` with the document and the pointer into it, and
a human-readable `message`.