Confirmations

Nothing runs for your account until your rule owner has confirmed it. Every rule — of the law, of your own policies, of your matching rules — is written in plain language, cites the paragraph or clause it applies, and comes with worked examples. Your rule owner reads each one and confirms it, or flags it with a comment. Until then, a check that reaches the rule answers not_covered with the reason awaiting_confirmation.

There is no outside review step. Himmel is not a law firm and gives no advice: your company owns the decision to confirm a rule, and if you want a rule looked at, you take it to your own adviser.

What there is to confirm

GET /v1/confirmations lists every rule set your account has on, and each of its versions with what waits in it: how many rules it has, how many are pending — nobody has confirmed or flagged them — how many are flagged, and waiting, the answers that wait on it (below). The law comes first, then your policies, drafts included, then your matching rules. A rule set of the law is on once it is switched on for your account; until then it is not listed, and its page answers 403 rule-set-not-enabled, as a check naming it does.

The confirmation page

GET /v1/confirmations/{rule_set}/{version} is one page per rule set version. For each rule it gives:

• its wording, the sentence your rule owner confirms;
• every citation, with the passage it points at (excerpt) and what kind of source that is (source_kind: statute, official_guidance, case, policy_document, or default for the documented defaults your matching rules start from);
• its worked examples, each as one sentence;
• its status: pending; confirmed on this page; flagged; or carried_over, confirmed on another version's page where the rule reads exactly as it does here;
• its decision, once there is one: confirmed or flagged, by whom, when, and on which version's page (version);
• waiting: how many of your answers stopped at this rule, the first they could not pass.

The page's own waiting counts every answer that waits on a rule of this version — what confirming everything pending will check again. An answer names only the first rule it could not pass, so confirming that one may leave it waiting on the next; the page's figure is the one to read.

Confirming and flagging

curl https://api.gethimmel.com/v1/confirmations/de_gifts_entertainment/1.1.0 \
  -H "Authorization: Bearer $HIMMEL_KEY" -H "Content-Type: application/json" \
  -d '{ "by_user": "usr_01J9Q4TZ8M...",
        "rules": [
          { "rule": "de_gifts_entertainment.gifts.limit", "action": "confirm" },
          { "rule": "de_gifts_entertainment.entertainment.documented", "action": "flag",
            "comment": "We book restaurant invoices without the guest list; the list is on the expense report." }
        ] }'

Each confirmation binds to the rule's rule_hash. A rule whose wording, logic, citations or worked examples change has a new hash, and is confirmed again. A flagged rule stays off for your account — checks that reach it answer not_covered with the reason rule_flagged — and the comment reaches whoever maintains it: us, for a rule of the law; your policy's draft, for one of your own.

A rule of your own policy, drafted from its document and flagged with a comment, is drafted again by itself, in the background — a few minutes, not a new draft of the whole playbook. The response's drafting_again names the document it follows on (document_id), the job and the rules; it is null for a rule of the law or of your matching rules, a policy posted as files, a flag without a comment, or a deployment that drafts nothing. The rule is drafted again from the document and what you said - your comment masked, as the document is, so no name in it reaches the model - into your policy's draft, or into a draft of the next version where the flagged one is already switched on. It comes back to this page to be confirmed as it then reads, and every rule it did not touch keeps its confirmation. It is written only where nothing else moves: where drafting it again would change what an example of another rule comes out as, it is not written, the flag stands, and the document's latest entry in drafts says which examples it would have changed. Where your comment asks for what the document does not say, the rule comes back as the document says it: change the playbook itself by revising its document (Policies).

by_user is the Himmel id of the person confirming, which the console shows them on its Developers page, and every colleague's on Settings' People page. It has to be an admin of your account, because only an admin confirms; a name, or anybody else's id, is refused. The confirmation records that person, and the record of the request also keeps which key sent it: a key can only claim who it acts for. Signed in to the console, you confirm as yourself and leave by_user out.

What confirming checks again

Every answer your rule owner's decision may change is checked again, in the background, in live and test alike — the response's rerun_id names this re-run:

• answers that waited on the owner: not_covered, awaiting_confirmation or rule_flagged;
• answers that used a rule the owner has now flagged;
• answers given under an earlier version of the rule set, or without a policy that now applies to their date.

An answer that moved is issued again as a new check that replaces it (supersedes_check_id, recheck_reason: rerun); the earlier one is kept, unchanged. Several decisions in a row check each answer again once. When the re-run is done, one checks.rerun alert says how many answers were issued again and how many changed state or outcome, and GET /v1/checks?rerun={rerun_id} lists them. A proposal nobody has reported as executed is left as it was answered: ask again — or report it done, which checks it again as it then stands.

So the order of the first steps does not matter: send your bookings before the rules are confirmed, and confirming them afterwards answers them again. A flag applies at once: the answers that used the rule are issued again as not_covered, rule_flagged, and confirming the rule later issues them again.

New versions

When the law changes, a new version is published with the date it applies from, and your admins are told in an alert. Only the rules that changed are pending on its page: every rule whose hash did not change is carried_over from your earlier confirmation, and runs without being confirmed again. It works the other way too: confirm the newer version first, and the rules an older version shares with it read carried_over on the older version's page, with only the ones it words differently left pending.

GET /v1/rules/{rule_set}/{version}/diff?from={version} says what changed in the words your rule owner confirms in: each rule changed, added, removed or unchanged, its wording before and after, and every worked example that now comes out differently. The examples are run under both versions, not compared as text — "these four examples now answer differently" is what makes a change readable.

A rule can change in none of its own words: the clause it cites is reworded, its worked examples move with a figure they are worked out from, a fact it reads now records an approval. It is confirmed again all the same, so each rule changed says what moved in it - moved: whether its title and wording changed; clauses, each passage it cites that reads otherwise now, before and after; examples, each worked example that changed, its sentence before and after and the facts that moved, and whether the answer it expects, its history or anything other moved; logic, whether its conditions or what it decides changed; and reads, each fact, setting, value, total or table it reads whose definition changed, and what of it. The console shows it under the rule.

Until the changed rules are confirmed, a transaction that falls under the new version and reaches one of them answers not_covered with awaiting_confirmation. Once the version applies and answers for actions taken wait on rules of it still unconfirmed, a confirmation.overdue alert says how many.

A version nobody has confirmed takes no answer away. The answers you were given under the earlier version stand until your rule owner confirms the changed rules; then each is checked again under the new version, with one checks.rerun alert for all of them. A new version with nothing left to confirm — every rule carried over — answers them again as soon as it is published. The same holds for a policy of your own: published, it applies to your earlier answers once its rules are confirmed.