doctrine: §13 — the verb table and refusal codes are built

docs/SESSION-AUTHORITY-DOCTRINE.md

@@ -347,20 +347,24 @@ verbs, decided by the agent. Today every surface exposes verbs one at a time
 and nothing lets it plan across them. This was queued as "agent command
 chaining" on 2026-07-16 and never designed.
 
-What a chain needs beyond what exists:
+**Built 2026-07-26, in sessiond:** the surface is enumerable and its refusals
+are branchable. `describe` returns the verb table — every op, whether it
+mutates, which refusal codes it can return, and a request line that parses,
+because knowing an op exists is not enough to call it. Refusals carry a code
+(`unsupported_op`, `invalid_argument`, `refused_by_state`, `not_permitted`,
+`unavailable`) alongside the prose: not-now, never, and wrong-arguments are
+three different next moves and a sentence does not distinguish them.
+`not_permitted` is issued by nothing yet — it exists so callers already branch
+on it when capability tokens land. A test round-trips every advertised example
+through the parser, so a verb table that lies fails the build rather than the
+agent.
+
+The shell's surfaces (`dock.*`, `apps.*`, `shell.*`, and the settings authority)
+owe the same two things. Until they have them, a chain can compose over the
+device and not over the surfaces.
+
+What a chain still needs:
 
-- **Results that are data.** Already fixed once — quickshell marshalled `var`
-  returns to void and the `{ok, reason}` contract had never reached a caller.
-  Every new surface inherits the JSON-string convention or it cannot be
-  chained.
-- **Refusals that branch.** A refusal carries a reason the agent can act on,
-  not a bare false. `{ok:false, reason}` is the minimum; a chain reads it and
-  picks a different path.
-- **A declared verb vocabulary.** Fixed operations, discoverable, so the agent
-  composes over a stable surface rather than emitting new logic per call. The
-  net-policy design already has this shape (`set-policy`, `enroll-cgroup`, …)
-  and it is the right one — a model expresses intent over enumerated verbs and
-  cannot ask for one that does not exist.
 - **Failure semantics.** A chain that refuses at step three is not the same as
   one that never started. Whether the earlier steps roll back is per-chain and
   must be stated, not discovered.