# Inference contract

This describes supported structures, not a guarantee that English intent will be
recognized correctly. Inputs outside these structures may be falsely accepted.

## Input

Each JSONL record is an object with:

- `instruction`: an English string explicitly naming catalog tools and arguments.
- `tools`: 1–8 catalog entries, each containing exactly `name`, `arguments`,
  `required`, and `returns`.

A catalog entry looks like:

```json
{
  "name": "list_users",
  "arguments": { "team": "string" },
  "required": ["team"],
  "returns": { "kind": "array", "properties": ["id", "name"] }
}
```

Tool names must be JavaScript identifiers. Argument schemas contain at most four
properties of type `string`, `number` or `boolean`; nested objects, arrays and
null arguments are unsupported. Required argument names must exist in the schema.
Return kinds are `text`, `object` or `array`, with declared property names where
projection is needed. Quoted values use JSON string syntax and remain opaque.
Numbers must be finite and compatible with exact JavaScript numeric handling.

The frontend diagnoses inputs over 128 tokens rather than truncating them.
The model does not discover tools or interpret free-form tool descriptions.

## Plan

A successful response contains a `plan`, for example:

```json
{
  "mode": "single",
  "calls": [{ "tool": "list_users", "args": { "team": "blue" } }],
  "output": { "kind": "last" }
}
```

Supported schedules are one call, or 2–3 independent calls sequentially or in
parallel. Repeated tools are allowed. Sequential calls do not pass earlier
results into later arguments. Dependencies, mixed serial/parallel groups,
conditions, retries, loops and arbitrary code generation are unsupported.

`output.kind` is `all` or `last`. For one array-returning call only, optional
`fields` projects 1–3 declared properties and optional `limit` takes the first
0–100 rows. Projection precedes the limit. Filtering, sorting and aggregation
are unsupported.

Rejected requests return a `diagnostic` string instead of a plan. Diagnostics are
not evidence of reliable semantic rejection. Valid plans can be semantically
wrong even when schema checks pass.

## Compilation, not execution

The CLI's `--js` option also returns a `js` string: an async-function body intended
for a host exposing `tools[name](args)`, top-level `await` and `return`. Nothing in
the CLI invokes these tools.

Generated code awaits every started call. Parallel mode uses `Promise.allSettled`;
serial mode catches each call's failure and continues in mention order. Results
are `{ok: true, value: ...}` or `{ok: false, error: ...}` records. `all` returns
records in call order; `last` returns the final call's record, not the last call to
finish. Single-array shaping reports invalid result shapes explicitly.

The compiler escapes names and values mechanically and validates structural
constraints. These properties do not grant permission, establish intended
semantics, or provide execution isolation. Real tool use needs independently
implemented authorization, intent review and a suitable execution environment.