feat(mdcode): evaluate an action's guards against the store

[libei]

Third of the constraint split. #398 added the construct, #413 added the action runtime and refused a guarded action outright. This turns that refusal into a real check.

What it does

lowerGuards resolves each name in guards and turns the constraint's expression into one query against the store. When a guard runs follows from what its expression reads, and the model never states it:

• a rule over the action's parameters is settled before any statement runs
• a rule over stored data runs after the statements and inside the same transaction, where it reads the state the write produced

A violation rolls the write back and reports which rule stopped the call, in the words the constraint's description gives.

$ kcmd action run TransferFunds --arg source="Alice Checking" --arg target=ACC-2 --arg amount=0
Running 'TransferFunds' on projects/my-project/instances/my-instance/databases/semantic_agent_demo...
Refused (reject): Action 'TransferFunds' was refused and nothing was written. A transfer must move at least one unit. Ask the caller for the amount again before retrying. Stopped by 'AmountIsPositive' (amount > 0).

Refused (escalate): Action 'IssueCredit' needs an approval, and nothing was written. A credit over 25 dollars is above the self-service limit. A supervisor decides it. Stopped by 'CreditUnderSelfServiceLimit' (amount <= 25). Nothing is held while somebody decides: the transaction was rolled back, so run the action again once it is approved.

Outcomes

ActionOutcome gains a refused arm carrying the effect, the violated rules and the message. committed gains warnings for advisory violations and unchecked for advisory rules the runtime could not evaluate. Several violations combine by the strictest effect: any reject refuses, failing that any escalate holds, failing that any warn reports.

What still cannot be checked

A judgment, since nothing calls a judge; and an expression outside the grammar. A rule that would reject or escalate and cannot be checked stops the action, and every such rule is named rather than only the first:

Error: Action 'IssueCredit' cannot be run: constraint 'OrderTotalMatchesLineItems' cannot be checked: it uses parentheses or a function call (Order.total = SUM(LineItem.amount)), which the grammar does not parse; constraint 'CreditIsNotSplitToAvoidReview' cannot be checked: it is settled by judgment rather than by an expression, and this runtime runs no judge. Running it would apply a write the model says is checked first, so it is refused rather than run unchecked.

An advisory rule is the exception, and this is the one design call worth flagging. A warn rule reports a violation rather than stopping one, so failing to check it cannot be grounds for stopping the write either — treating it as one would leave a model that states advisory rules permanently unrunnable, which is exactly the carve-out #413 made deliberately. The write goes ahead and the rule is reported as not checked:

  not checked: advisory rule 'CreditMemoNamesAServiceFailure' (constraint 'CreditMemoNamesAServiceFailure' cannot be checked: it is settled by judgment rather than by an expression, and this runtime runs no judge)
Committed at 2026-09-13T18:00:00Z.

The grammar

Comparisons over an entity's stored fields, the action's parameters and literals, joined by AND and OR. = NULL and != NULL become IS NULL / IS NOT NULL; <> normalises to !=. It refuses a function call, a parenthesised subexpression, an expression spanning two entities, an abstract entity, a composite-keyed entity, an unbound or expression-bound field, and an entity the action takes no reference parameter for — each with the reason in the message. The expression language is GoogleSQL, so equality is a single =; == is refused with that said explicitly.

Probe shapes:

-- over stored data
SELECT OrderId FROM Orders WHERE OrderId = @order AND NOT COALESCE((Total >= 0), FALSE) LIMIT 5
-- over the parameters
SELECT 1 AS violated FROM UNNEST([1]) WHERE NOT COALESCE((@amount <= 25), FALSE)

The NOT COALESCE(…, FALSE) wrapper makes a predicate that returns NULL count as a breach rather than as silence.

Tests

44 new tests for the evaluator; #413's refusal tests replaced one for one by tests of the check that now happens. 1012 pass, 0 fail, tsc --noEmit clean. The CLI tests keep a judged guard so they still stop hermetically before any session opens.

Docs

actions.md §2 and §7, and reference.md, are rewritten against real command output rather than by hand: the status paragraphs, the four-stage diagram (timing is derived, not "before the call"), the run flow, the outcome set (committed · refused · nothing written · unknown), and the kcmd agent tools listing, where transfer_funds is no longer [NOT RUNNABLE]. Order.total == SUM(...) is corrected to = in the guide and the demo model.

Wiring the demo's own guards: so the $30 credit escalates is the next change; the demo README says so rather than claiming the old behaviour.