> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Input invariants

> Declare consistency rules across a ruleset's inputs, set them in a project's bundle contract, and test the error they return.

> [!WARNING]
>
> **Authoring is invite-only private beta.** Everything on this page needs an
> Aethis API key with authoring scopes. [Request access](https://aethis.ai/developer-access),
> or start on the open evaluate tier with
> [your first decision](https://docs.aethis.ai/getting-started/first-decision.md) — no key required.
> The two tiers are set out on [Capabilities and access](https://docs.aethis.ai/reference/capabilities.md).

An **input invariant** is a consistency rule that you declare over a ruleset's
inputs. It checks that the values a caller supplies make sense together, before
any eligibility rule runs. For example, in a library membership ruleset,
`member.renewal_date` must not be before `member.joined_date`.

The engine never infers such a rule from a field name or a date type. Every
invariant exists because an author declared it.

Invariants live in a project's **bundle contract**: a project-level document
that holds them. Every generation of the project copies the invariants into the
compiled ruleset.

## What a decision returns

When the inputs break an invariant, `/decide` returns:

* `decision: "undetermined"`;
* `undetermined_reason: "input_errors"`;
* `field_errors`, mapping each field the invariant names to its message;
* no `next_question`.

```json theme={null}
{
  "decision": "undetermined",
  "undetermined_reason": "input_errors",
  "field_errors": {
    "member.renewal_date": "The renewal date must not be before the date the member joined."
  }
}
```

This uses the same blocking `field_errors` channel as an unknown field or a value
of the wrong type. See [Blocking errors versus advisory signals](https://docs.aethis.ai/interfaces/rest-api.md#blocking-errors-versus-advisory-signals).

An invariant is skipped while any input it reads is missing. It cannot fire on
an answer the caller has not given yet. If several invariants name the same
field, their messages are joined with a single line feed.

In a rulebook decision, a section reports `pending` in `section_results` when it owns a
violated invariant, or when one of its criteria reads a field the invariant
references (directly, through a computed any-true field, or as a review's
resolution field), instead of a status computed from inputs that cannot be right. Other sections
keep their computed status.

## Write an invariant

A bundle contract is a JSON object with `schema_version` (always `1`) and a list
of `input_invariants`. Each invariant has four required members, plus an optional `provenance`:

| Member | Meaning |
| - | - |
| `id` | A name for the invariant, unique within the contract. Letters, digits, `_`, `.` and `-`, starting with a letter or digit. At most 256 bytes. |
| `expr` | One comparison, described below. |
| `error_fields` | The fields that receive the message. Between 1 and 16 unique field ids, each one read by `expr`. |
| `message` | The text returned in `field_errors`. Non-empty, at most 512 bytes. |

The library membership rule, as JSON:

```json theme={null}
{
  "schema_version": 1,
  "input_invariants": [
    {
      "id": "renewal_not_before_joined",
      "expr": {
        "type": "op",
        "operator": ">=",
        "args": [
          { "type": "field_ref", "key": "member.renewal_date" },
          { "type": "field_ref", "key": "member.joined_date" }
        ]
      },
      "error_fields": ["member.renewal_date"],
      "message": "The renewal date must not be before the date the member joined."
    }
  ]
}
```

The expression states what must be **true**. The invariant fires when it is false.

### Limits

* Up to 32 invariants per ruleset.
* `expr` is exactly one comparison: `=`, `!=`, `<`, `<=`, `>` or `>=`, with exactly
  two operands. Nested expressions are not accepted.
* Each operand is a field reference (`{"type": "field_ref", "key": ...}`) or a
  typed constant (`{"type": "const", "sort": ..., "value": ...}`), and at least one
  operand is a field reference.
* Both operands have the same type. `<`, `<=`, `>` and `>=` apply to `Int`,
  `Real`, `Date` and `Duration` fields. Other types use `=` or `!=`.
* Invariants range over fields the caller supplies, not derived fields.
* An invariant over an enum field whose members come from a value space is refused
  when a ruleset is generated.

Field names and types are checked against the project's fields when a ruleset
is generated, not when you store the contract.

## Set the bundle contract

> [tab] REST
>
> `PUT /api/v1/public/projects/{project_id}/bundle-contract` stores the
> contract and replaces any contract already stored. It needs the
> `projects:write` scope.
>
> ```bash theme={null}
> curl -X PUT https://api.aethis.ai/api/v1/public/projects/proj_8CzLVwyx53rTGEJv/bundle-contract \
>   -H @<(printf 'x-api-key: %s\n' "$AETHIS_API_KEY") \
>   -H "Content-Type: application/json" \
>   -d '{
>     "schema_version": 1,
>     "input_invariants": [
>       {
>         "id": "renewal_not_before_joined",
>         "expr": {
>           "type": "op",
>           "operator": ">=",
>           "args": [
>             { "type": "field_ref", "key": "member.renewal_date" },
>             { "type": "field_ref", "key": "member.joined_date" }
>           ]
>         },
>         "error_fields": ["member.renewal_date"],
>         "message": "The renewal date must not be before the date the member joined."
>       }
>     ]
>   }'
> ```
>
> The response is the project, including `bundle_contract_digest`. The digest is
> `null` when no contract is stored. To clear the contract, send
> `{"schema_version": 1}` with no `input_invariants`. The request checks only shape and
> size, and is refused with `422` for an unknown key, too many invariants, a
> duplicate id, an id that does not match the pattern, an id or message over its
> byte limit, a breach of the `error_fields` rules, or a constant that is not a
> finite number. The type rules (operands of the same type, ordering operators
> only on number and date-like fields, no derived fields, no enum from a value
> space) are checked when a ruleset is generated; a breach fails that generation
> with a message.

> [tab] CLI
>
> Put the contract in `contracts/bundle.yaml` in the project folder, beside
> `fields/` and `tests/`:
>
> ```yaml theme={null}
> schema_version: 1
> input_invariants:
>   - id: renewal_not_before_joined
>     expr:
>       type: op
>       operator: ">="
>       args:
>         - {type: field_ref, key: member.renewal_date}
>         - {type: field_ref, key: member.joined_date}
>     error_fields: [member.renewal_date]
>     message: The renewal date must not be before the date the member joined.
> ```
>
> `aethis generate` and `aethis refine` send the file before generation starts and
> check that the finished build captured the same contract. This needs aethis-cli
> 0.54.0 or later. To clear a stored contract, delete the file. See the
> [CLI page](https://docs.aethis.ai/interfaces/cli.md#contractsbundleyaml).

> [tab] MCP
>
> Call `aethis_set_bundle_contract` with the project and the invariants. Omit
> `input_invariants`, or pass `null` or `[]`, to clear the contract. This needs
> aethis-mcp 0.24.0 or later. See the
> [tools reference](https://docs.aethis.ai/mcp-server/tools.md#aethis_set_bundle_contract).

Storing a contract changes nothing until the project is generated again.

## Test an invariant

A test case can assert the error. Give the inputs that break the invariant, expect
the outcome `undetermined`, and state the exact message for each field.

In `tests/scenarios.yaml`:

```yaml theme={null}
tests:
  - name: Renewal before joined
    inputs:
      member.joined_date: "2026-05-01"
      member.renewal_date: "2026-04-01"
    expect:
      outcome: undetermined
      field_errors:
        member.renewal_date: The renewal date must not be before the date the member joined.
```

Through the API, the same assertion is `expectations.field_errors` on a test case
with `expected_outcome: "undetermined"`:

```json theme={null}
{
  "name": "Renewal before joined",
  "field_values": {
    "member.joined_date": "2026-05-01",
    "member.renewal_date": "2026-04-01"
  },
  "expected_outcome": "undetermined",
  "expectations": {
    "field_errors": {
      "member.renewal_date": "The renewal date must not be before the date the member joined."
    }
  }
}
```

The map is matched exactly: every field and message must be present, and no other
entry may appear. `field_errors` must be a non-empty object and is valid only with
`undetermined`. It is part of an [acceptance contract](https://docs.aethis.ai/authoring/rule-generation.md#structured-acceptance-contracts),
so the CLI needs 0.55.0 or later.

Under an acceptance contract, a test case whose inputs break an invariant but
which does not declare `field_errors` fails: the error is reported as unexpected.
Adding a `field_errors` expectation to `scenarios.yaml` makes the suite an
acceptance contract.

A project without an acceptance contract can still expect `undetermined` for
inputs that break an invariant, but that checks the outcome only, not the message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.