Skip to main content
Authoring is invite-only private beta. Everything on this page needs an Aethis API key with authoring scopes. Request access, or start on the open evaluate tier with your first decision — no key required. The two tiers are set out on Capabilities and access.
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.
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. 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: The library membership rule, as JSON:
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

PUT /api/v1/public/projects/{project_id}/bundle-contract stores the contract and replaces any contract already stored. It needs the projects:write scope.
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.
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:
Through the API, the same assertion is expectations.field_errors on a test case with expected_outcome: "undetermined":
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, 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.