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.
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 withschema_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:
Limits
- Up to 32 invariants per ruleset.
expris 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 toInt,Real,DateandDurationfields. 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.
Set the bundle contract
- REST
- CLI
- MCP
PUT /api/v1/public/projects/{project_id}/bundle-contract stores the
contract and replaces any contract already stored. It needs the
projects:write scope.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.Test an invariant
A test case can assert the error. Give the inputs that break the invariant, expect the outcomeundetermined, and state the exact message for each field.
In tests/scenarios.yaml:
expectations.field_errors on a test case
with expected_outcome: "undetermined":
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.