# SDK reference

Two facades over the same idea: your application opens a pinned canon,
sends facts with a closed question, and reads back a computed answer
with its grounds. The engine runs locally in WebAssembly; after
install, nothing on this page needs the network except the calls that
say so.

Start here if you are new:

- [Quickstart](/guide/quickstart/) asks one question end to end in ten
  minutes, in TypeScript and in Python.
- [The deadline app](/build/start/) builds the same
  canon into a small working application with a form, an API, and a
  command line.

## The two facades

```text
TypeScript   npm i @arxo/law @arxo/canon-bgb-fristen
Python       pip install arxo arxo-canon-bgb-fristen
```

Both open `de.bgb.fristen@0.1.0` — the canon of the German Civil Code
provisions on periods — ask `frist_ende`, and read the same fields:
`evaluationStatus`, `truthStatus`, `value`, `proof`, `sources`,
`hashes`, `issues`, `document`. The section map below says where each
piece is documented; the compatibility chapter pins every version.

## One case through both facades

Every chapter reuses the quickstart case so the calls stay comparable:
an event on 6 March 2026 starts a period of 14 calendar days, and the
question is whether the period ends on 20 March 2026. The legal time is
17 September 2026, the time zone is Europe/Berlin, and the counting
policy is the canon's own `BGB_FRISTEN_TAG`.

```js
import { open } from '@arxo/law';

const fristen = await open('de.bgb.fristen@0.1.0');
const r = await fristen.truth('frist_ende', ['frist', '2026-03-20'], {
  legalTime: '2026-09-17',
  timezone: 'Europe/Berlin',
  deadlinePolicy: 'urn:de:corpus:clir:bgb-fristen#BGB_FRISTEN_TAG',
  answers: [
    { predicate: 'frist_ereignis', args: ['frist', '2026-03-06'] },
    { predicate: 'frist_dauer_tage', args: ['frist', '14 calendar_day'] },
  ],
});
// r.evaluationStatus === 'COMPUTED', r.truthStatus === 'TRUE_ONLY'
```

```python
from arxo import open

fristen = open("de.bgb.fristen@0.1.0")
r = fristen.truth("frist_ende", ["frist", "2026-03-20"], {
    "legalTime": "2026-09-17",
    "timezone": "Europe/Berlin",
    "deadlinePolicy": "urn:de:corpus:clir:bgb-fristen#BGB_FRISTEN_TAG",
    "answers": [
        {"predicate": "frist_ereignis", "args": ["frist", "2026-03-06"]},
        {"predicate": "frist_dauer_tage", "args": ["frist", "14 calendar_day"]},
    ],
})
# r.evaluationStatus == "COMPUTED", r.truthStatus == "TRUE_ONLY"
```

## Section map

| Page | What it answers |
|---|---|
| [TypeScript](/build/sdk/typescript/) | Install, entry points, `open` overloads, the `LawPackage` lifecycle from open to archive, error classes |
| [Python](/build/sdk/python/) | Install, the real API with its `snake_case` aliases, the operations Python does not ship and their workaround |
| [Loading and pinning](/build/sdk/loading-and-pinning/) | Why the spec is always `name@version`, the installed-canon hash check, lock files, checkout trees, offline mode |
| [Facts and context](/build/sdk/facts-and-context/) | The `Fact` shape, how a bare value is wrapped by its declared type, every `CaseInput` field, what `legalTime` must be |
| [Query types](/build/sdk/query-types/) | When to use `truth`, `focused_truth`, `why_not`, `collect`, `deadline`, `calc`, `positions`, `unfold`, `questions` |
| [Results and errors](/build/sdk/results-and-errors/) | Every `evaluationStatus`, the four `truthStatus` values, value shapes, local versus host answers, the error table |
| [Compatibility](/build/sdk/compatibility/) | Version, capability, environment, and network matrices, each cell with its source |

## How to use this reference

Each chapter follows the same compact shape: the contract in one
paragraph, the quoted signatures, the types and errors involved, the
limits, and one short example over the shared frist scenario. Read
the two facade chapters for the surface you code against, then the
loading chapter for reproducibility, then facts and queries for the
call shape, then results for the answer shape. Compatibility stays
open beside your editor while versions move.

The facades are thin by design: they transport your facts to the
engine and project the answer's fields back. They never fill in a
missing fact, never default a type, and never guess a policy. When a
call needs something you did not supply, the answer names it — a
status, a blocker, a missing input — and the chapters on queries and
results show how your code turns each one into the next question.

## Where the signatures come from

Signatures on these pages are quoted from the shipped declarations.
The TypeScript declarations live in the facade package, the Python
signatures in the facade modules:

```text
@arxo/law            canonical declarations of open, LawPackage, Answer, Fact, CaseInput
@arxo/law-client     error classes shared by both facades
arxo                 open, LawPackage, Answer, and errors in Python
@arxo/canon-bgb-fristen   the canon build: linked world, calendar, lock file, manifest
```

Hashes and versions on these pages are published ones. Where an
operation exists in only one facade, the page says so and names the
workaround.

When a version moves, start from the compatibility chapter: it maps
every claim on these pages to the manifest field or declaration block
it came from, so the update is a checklist instead of a search.