Rule sets

A rule set is a versioned set of rules for one domain — gifts and client entertainment, say. There are three kinds:

• law — maintained once and shared by every account: the consequences the law attaches, such as how much of an expense is deductible. The first is German gifts and client entertainment; the platform is not tied to one jurisdiction.
• policy — your company's own rules, layered after the law: limits, conditions and approvals. A policy may add to the law; it can never change a consequence the law decides. See Policies.
• matching — your rules for when two recipient records are one person. See Recipients.

The catalogue

GET /v1/rules, GET /v1/rules/{rule_set} and GET /v1/rules/{rule_set}/{version} are readable without a key for the rule sets of the law, so you can build a form or a validator before you have an account. With a key, you also see your own policies and matching rules - a key that may read the rules (rules:read), as every read of them asks: one made only to check is 403 insufficient-scope.

Each version lists:

• its facts — every fact it takes, with its type, whether it is required, what it means, for a code the pattern its values must match, and for a number that may go below zero signed — any other is zero or more. These are the only things it will ever ask you for, and every one is observable: a date, an amount, an account, a recipient, whether a receipt names its guests. Never a conclusion.
• your settings it reads, such as your fiscal year start.
• the currency its limits are in (currency): every amount its rules read is read in it, and an amount in another currency at the figure you send beside it (An amount in another currency); a rule set whose rules read no amount, such as your matching rules, says none.
• its outcomes, such as deductible and not_deductible.
• what it does not check, and why — a topic the rule set leaves alone on purpose, such as an election made for a whole year rather than for one booking.
• its versions, each with the date it applies from and its changelog.

With a key for an account that has the rule set enabled, each rule's wording and citations are listed too. A version is named here, never chosen: which version answers today, and which of its rules run, is what an agent reads before it starts (below). The worked examples are on each rule's confirmation page (Confirmations).

What an agent reads before it starts

GET /v1/agents/{agent_id}/rules gives an agent the rules it is held to today, for it to read at the start of each run and plan within. It reads what a check reads: every rule set of your account that answers what an agent may do - your own policies, then the law you have switched on, never your matching rules, which say who is who - each with the version that answers today (version, never a draft) and one published to apply from a later date (next). Of that version:

• rules - the rules that run: those your rule owner has confirmed, in the order they run, each in the words confirmed (title, wording), with what it cites (clauses), its worked example (example), the people it names through your settings, by Himmel id (people), and who_acts where it turns on who acts - an agent rather than a person, say - so it may hold an agent tighter than a person.
• waiting - the rules not confirmed yet, or marked not right, never in their words: an action one reaches is answered not_covered.
• facts, what a check of the agent's sends, as the catalogue lists them, and never_sent, the facts it never sends — a person, the figure an approval was given for — which Himmel holds for it (An agent never names a person); settings, your settings it reads, with their values today; outcomes; and not_checked.

text is all of it in words, for the agent's instructions - who it is, how to ask before each action and report what became of it, through the MCP server's tools or the API's two calls, how an amount is written, the four answers, what requests says where an answer names a person and how to ask again about the action (When an answer names a person), keeping its check_id with the work for a later session that starts afresh, and that where the agent's own tools ask Himmel through the SDK they ask and report for it, while it plans within the rules, then each rule set's rules in your rule owner's words, with the name of its check tool - and checksum, its SHA-256, changes whenever what the agent is told changes, so whatever hands it to the agent can tell. Every agent is answered under every playbook of your account, so every agent is given every one. People are named by their Himmel id, never by name. These words are not the check: each action is still asked about, and answered under the rules in force when it is.

Any key or person reads it (rules:read): an agent with its own key, your software for the agents it runs, a person to see what an agent is told. A key of an agent switched off is refused, 403 agent-switched-off, as every request of its keys; an agent your account has not registered is 404 not-found.

When the agent reads it with its own key, the read is kept, so that whoever owns a playbook sees a change to it reach the agents that work by it: the agent's record (GET /v1/agents/{agent_id}, Your agents) says when it last read its rules, in the environment you ask in (rules_read_at), and what it was given (rules_read): the versions of your rule sets, and the checksum of the text. It is kept to the minute - a read within a minute of the last that was given the same is not written again - and a read given anything else is written at once. A read by a person, your own software's key or another agent is not the agent reading. The text names its day, so a read on another day has another checksum: to tell whether an agent has read what applies now, compare its versions with what it would read now.

Your settings

What your rules read about your company — who approves a refund above a limit, who decides a question the rules leave to a person, where your financial year begins — are your account's settings. A version lists the settings it reads as tenant_facts; GET /v1/tenant-facts lists them for your account, as settings: each one a rule set your account has reads, with every rule set that reads it and what each says it is for, and unset where nothing is in force today — a check that reaches a rule reading it asks for it. Their values are beside them: each as it applies today (in_force), and every version (history). Himmel reads one setting itself, whatever your rules read: your financial year's start (fiscal_year_start, as MM-DD), which decides how long a customer's name is kept.

PUT /v1/tenant-facts/{key} writes a new version from valid_from, today when you leave it out. Nothing is overwritten, and every answer keeps the settings it was given with. It is checked first, in this order:

A person — who approves, who signs off — is named by their Himmel id, never by name. An amount — a limit, a sign-off amount — is in the currency the rule sets that read it state their limits in, which settings lists for it as currencies; where two rule sets read it in two currencies, it is in one of them with what it comes to in the other beside it, under equivalents, as a check's amount is (An amount in another currency). Himmel picks no rate. A change dated back reaches answers already given: the answers dated from valid_from on that read the setting are checked again by a re-run, whose id comes back as rerun_id, and those it changes are issued again, with one checks.rerun alert. A change from today on reaches none given before. In the console, an admin changes settings under Settings, and everybody signed in reads them there.

Versions

A published version never changes. A change to the law is a new version, with the date it applies from — effective_from — and a changelog, and old answers keep citing the version that gave them.

Which version answers a check depends on the transaction's date. For some rule sets the date that counts is the transaction's own; for others it is the start of the fiscal year it falls in (effective_basis: fiscal_year_start), because the law changed from a fiscal year onward. A company whose fiscal year began in July 2023 books a gift in March 2024 under the old version. A check that names rule_version says which version it expects, and is refused (409 rule-version-not-in-force) where another is in force: the version in force always answers.

A version also has a status: draft while it is being written, published, and superseded once a later version takes over. A draft can be confirmed and tried, but it is marked as a draft wherever it is shown.