docs(mdcode): second pass on the actions guide — state it once, state it plainly

[libei]

Follow-up to #427. Reading the merged guide straight through turned up passages
that are clean by the checklist and still hard to get through. They fail in
three related ways: a passage explains a rule by pointing somewhere else
instead of stating it, it says something the page has already said, or it uses
a term of art the guide never defined. Two commits then act on the structural
version of the same complaint, one for each of the guide's two crossed-over
subjects, and the last one fixes what a second review found in all of it.

Nothing in the prose contradicts the code. Eight lines of fenced YAML were
deliberately deleted, named below; the other 470 are byte-identical to main as
a multiset, every frozen heading is unchanged, and the five inbound anchors from
reference.md, model_spec.md and the agent demo README resolve.

Each kind of constraint now has a section of its own

A constraint carries one of two bodies, and section 2 taught them in an order
that kept crossing between the two. An 88-line preamble opened on the concept,
ran two expression examples, then spent twenty lines on guards, on_violation
and the moment a guard is checked — machinery that belongs to both kinds —
before "When no expression decides it" reached the judged body. A reader
deciding which body to write had to carry all of it.

The section now states the fork once, in the preamble, and keeps the three
subjects apart afterwards. "Naming a constraint as a guard" holds everything
true of either kind: the guards list, why the reference sits on the action,
when a guard is checked, why guards and on_violation are independent, and
the push error and load warning that report a mismatch between them. "Rules a
query settles" holds the expression body, what it can read, and how far a
guard over stored data actually reaches. "Rules no query settles" holds the
judgment body, followed by the existing "Writing a judgment". The two
worked-example sections are unchanged and still take both kinds together.

Two facts were stated once per kind and are now stated once. Both copies of the
pre-write timing rule — "Every guard is checked before the call" in the
expression material, "Guards run before the transaction opens" in the judged
material — collapse into one sentence in the shared section, and each kind keeps
only the consequence that is its own. The derived evaluation field was defined
in the status note and again in the policy example; it is now defined in the
preamble, where it makes the two-body distinction visible in the catalog, and
the policy example only uses it.

The status note split along the same line, because it was one paragraph
reporting three unrelated states. What kcmd does with an expression sits under
the expression section, what --judge does with a judgment sits under the
judged section, and the run-time precedence gap stays with the strictest-outcome
prose it qualifies.

The eight deleted fenced lines are the ones that made the guards example
reprint TransferFunds whole — executor, server URI, three parameters — to
teach the single line guards: [AmountIsPositive], for an action the reader has
already seen declared twice. The example now shows the constraint and that line.

The DML material is now one section

Three subsections of step 1 were about writing DML — "The executor is a
binding", "Writing the statements in the model" and "Statements use your
database names" — with concept material between them, so a reader who had not
yet decided how the write happens met physical detail twice before finishing
the declaration. Step 1 ran 229 lines, and three quarters of the span below its
four-kind list was detail rather than concept or procedure.

Step 1 now ends at the declaration, at 106 lines: the name and parameters, the
model, the four executor kinds, entity-typed parameters, and where an executor
comes from. Everything about DML follows under one unnumbered H2, "##
Carrying the write as DML", skippable by its title for anyone using mcp,
rest or grpc. Inside it the statements come first, then the names they use,
then which file to put them in — so the profile override fence sits under the
rule it demonstrates rather than 80 lines above it.

Two facts left step 1 for the step that owns them. Key generation is an
affects fact, so it is now "### A created row gets its key from kcmd" in step
3, whose Status paragraph already said affects drives it; that paragraph
stops re-explaining the binding and opens on what it actually reports. The
three statement rules are push-time rules, so they are now "### What push holds
a statement to" in step 4, beside the four static action errors already there.

"The executor is a binding" is gone. Its rationale and its inheritance rule
restate profiles.md:104-123, which says it better — "the same action, the
same blast radius, performed by whatever mechanism the bound store actually
has." Step 1 keeps the part a reader needs there: the executor is physical, a
profile can supply or replace it, and an action a profile says nothing about
keeps the model's.

The push rules moved without being reworded. validate.ts:299 tests
text.slice(0, -1).includes(';'), which strips the last character before
looking, so a trailing ; passes and an interior one fails — exactly what "a
; inside a statement is rejected" says, and what model_spec.md:490 and
reference.md:458 say as "other than a trailing one". There was nothing to
correct.

A gate claim the runtime does not implement

"The gate sees the write" said a check observes the uncommitted result of
the write it is gating. Guards settle before the transaction exists
(run_action.ts:181-198), there is no expression evaluator at all — an action
guarded by one is refused rather than run (run_action.ts:529-535) — and
nothing runs between the last statement and the commit. The guide already
stated the true version twice, including in section 2: "Guards run before the
transaction opens, so 'an order's total equals the sum of its lines' has
nothing to look at yet." The bullet is gone. It predates #427.

The statements and the transaction

The example is a two-statement list, and nothing beside it said why an action
would have more than one statement or what running them together guarantees.
The transaction facts were in the guide but roughly seven hundred lines
downstream, in a figure caption and the run-time outcomes section, and the
figure there shows a single statement between BEGIN and COMMIT, so a
multi-statement list is never shown as one unit. A paragraph under the example
now says it: one transaction, statements in the order written, committed at the
end. Verified in run_action.ts — the transaction opens once at 212-222, the
loop at 291-293 is a serial for…of over plan.statements, commit is a single
call at 325-327, and any statement throwing lands in the rollback at 354-360.

"A statement runs in the caller's own transaction and can be rolled back" names
a transaction no external caller can supply: RunActionOptions has no way to
pass one in, and the runner opens its own. A refusal also rolls nothing back,
because it happens before there is a transaction.

An action that creates a row led with a prohibition and never named the
mechanism. It now says kcmd generates the key, that the key is a UUID
(run_action.ts:897, crypto.randomUUID), and that affects turns the
generation on, before explaining why a caller-chosen key would be unsafe.

Physical names, and what was never defined

The metric comparison is gone. "kcmd does translate a metric. You write
Account.balance… an action's statements get no such pass" taught a second
feature so the reader could infer a rule the bolded sentence above it already
states outright.

"Nothing catches a model name before the call" opened on an absence and then
listed what validation does check, which is the push-rule list further down the
same section. A reader hunting that list found it split across two places. The
paragraph now says what happens when you get it wrong: nothing tells you until
the action runs, the error comes from the store, and it can read like a fault
in the statement rather than a typo in a name. That last phrasing is
validate.ts's own, from the comment above validateRunnable.

"Carrying the write, instead of pointing at it, buys you three things" made the
reader decode that carrying means a sql executor and pointing means the other
three, and it restated a contrast the section opening already drew forty lines
earlier.

"Model name" was never defined. The section opened on the concrete pair — the
model's Account and accountId reach the store as account and account_id
— but labelled only the database half, then used "model names" as vocabulary.
The guide also uses "model name" in a second, unrelated sense further down,
where --judge-model takes the name of a Gemini model.

"Write a model name anywhere else and nothing tells you until the action runs"
compounded that: it opens in the imperative, so it reads as an instruction to
do the wrong thing, and "anywhere else" only resolves against the paragraph
above. The subject is now a statement rather than a command, and it leads with
the rule before the consequence.

Constraints

The "four stages" lead-in above Figure 2 duplicated the figure's own caption
and restated, as an abstraction, the inert-constraint fact stated plainly two
paragraphs above it. Figure 1 has no lead-in and this one does not need one.

"A constraint on its own does nothing. An action has to name it as a guard
before anything checks it." was the third statement of that fact inside
thirty-six lines, and it forward-referenced guards, which prose does not
introduce for another twenty-five lines. The first two statements stay.

The five habits for writing a judgment become a numbered list. They were five
bold-led paragraphs under a sentence announcing a count, so the count and its
members lived in different blocks and nothing tied a habit to its position.

"The judge" was the other undefined term. "Writing a judgment" opens by saying
a language model reads your sentence at review time, then eleven lines later
starts calling that reader the judge, which the guide never attaches to
anything even though --judge-model and --judge-reads-store both depend on
it. One clause now attaches it.

The policy table's intro announced the table in almost the caption's own words,
and "no query can settle two of the five" made the reader go back to the table
to learn which two, so the two judged rules are named. "The second body" points
at judgment by position over a set given far earlier, so it names judgment.

Two gaps in the sibling docs

profiles.md tells a profile author the engine lowers each expression to the
bound store's query language, and never says an action's statements are exempt.
They are — kcmd passes them to the store verbatim, which is why actions.md
tells you to write physical names in them. The file's own CancelOrder
override depends on the exemption without stating it, writing UPDATE Orders SET Status = 'CANCELLED' against a model whose entity is Order and whose
field is key. A fourth note under ## Notes states the rule.

reference.md says "Every check here is static, so it runs on every push,
regardless of destination" and stops. One sentence now draws the consequence an
action author actually hits: nothing in the push path asks the store a
question, so a statement naming a table or a column that does not exist passes
every check and fails when the action runs.

What the first review caught

Eight defects, six introduced by the edits above.

A case-only difference is not an error. "A statement that says Account where
it means account" would commit fine on both supported stores — GoogleSQL
matches identifiers case-insensitively and PostgreSQL folds unquoted ones to
lower case — so the sentence promised a failure that never happens. The example
is now accountId against a column named account_id.

"@parameter references … are the only names in a statement that come from
your model" is contradicted by @new<Concept>Key, which is derived from a
concept name and is not a declared parameter. validate.ts:282-286 adds it to
bindable as a separate case for exactly that reason.

The affects status note dropped a condition. The composite-key and
non-String refusals fire only where a statement actually binds the generated
key — run_action.ts:474 skips the check otherwise, so that an INT64-keyed
entity whose DML supplies its own key is not refused over a value it never
uses. As written it read as unconditional, which would push a reader into
deleting a correct affects record.

"A guard becomes a real gate" lost the sentence that justified it when the
false "gate sees the write" bullet went, leaving a headline about gating over a
body about atomicity. The body now states the gate property the runtime does
have: every guard on a sql action settles before the transaction opens, so a
refusal leaves the store untouched.

Three smaller ones. "Rule 3 is the one rule here that a guard enforces more
narrowly than it reads" claims a uniqueness rule 5 falsifies. Reordering put a
model description immediately before a colon and a YAML block showing
constraints instead. "The on_violation column" pointed at a column in a block
that has keys. And "Claim no more in it than a judge can settle" made the
pronoun reach past "All five" to "wording".

What the second review caught

Ten defects. Five are claims about kcmd that the code contradicts, and the
ir.ts changes below are comment-only — every changed line in that file is
inside a doc comment.

"kcmd can run it rather than publishing it for another system to dispatch" made
carrying the write an alternative to publishing. kc_actions.ts:225-226 copies
sqlStatements onto the published action verbatim, so a sql action is
published like any other and what changes is who performs the write.

"kcmd settles every guard on a sql action before it opens a transaction"
overclaims twice. A guard kcmd cannot settle is refused rather than settled
(run_action.ts:530-535 for an expression), and a warn guard left unsettled
produces a warning rather than a refusal (run_action.ts:199-204). The bullet
now claims only the gate property the runtime has: the guards settle before the
transaction opens (run_action.ts:180-204, ahead of withSession at 212-222),
and a call that does not clear them never reaches one.

"Because IssueCredit's other three guards are expressions, kcmd refuses it
outright" names a cause never reached. IssueCredit has an mcp executor, so
whyRefusedWithoutRunning stops at the executor-kind check
(run_action.ts:429) before it looks at the guards.

"Pass every value as a bound @parameter naming a parameter your action
declares" omits @new<Concept>Key, which validate.ts:282-286 seeds into
bindable for every create in affects. As written the rule forbids the
guide's own create example. The same omission was in ir.ts's SqlExecutor
comment.

ir.ts also still carried the "gate sees the write" bullet that #427 removed
from the guide — "the statements run where the constraints are probed, so the
gate observes the uncommitted result of the write it is gating". Guards settle
before the transaction exists, so nothing observes that. The bullet is gone and
the count above it drops from three to two.

Five are prose defects the restructure introduced or left behind. "Section 1
gave you an action that runs" was true before the DML material became its own
section. "Four things about an action can be statically wrong" reads as four
things about the particular action on the page. "All of these checks are
static" reaches back past an intervening list. "Expect no control flow" tells
the reader to hold an expectation when the point is a property of statements.
And moving the no-post-write paragraph left "however much it can read" pointing
at the store-reading flag twenty lines ahead of it.

Five findings were checked and rejected. warn guards are evaluated and
reported (run_action.ts:580, 608-609, 622-623) rather than skipped, so the
existing wording holds. Figure 2's lead-in was deleted in #427 on purpose and
Figure 1 has none either. The unnumbered ## Carrying the write as DML heading
is the requested shape. The Integer-keyed Transfer is the known defect
recorded below. And the semicolon rule is not factually wrong: validate.ts:299
tests text.slice(0, -1).includes(';'), so a trailing ; passes and an
interior one fails, exactly as claimed. It was ambiguous rather than wrong, and
now reads "anywhere but the end" to match reference.md:458.

Known defects not fixed here

Three live inside fenced blocks, which this branch has otherwise left
byte-identical:

• Transfer.transferId is datatype: Integer, but the create example binds
  @newTransferKey and the runtime generates a UUID string, so
  unusableGeneratedKey (run_action.ts:903-925) refuses it. The guide's only
  key-generation example is the one example that cannot run. Fixing it ripples
  into the captured agent-tool listing, which should come from a live run.
• Figure 3 invokes TransferFunds with source and amount, omitting the
  required target, and shows one UPDATE between BEGIN and COMMIT for an
  action that declares two statements.
• The profile example is labelled # commerce.profiles/operational.yaml but
  the model inside it is payments; the convention everywhere else is
  <model>.profiles/<name>.yaml.