dsh-logicprobe 0.5.6 → 0.6.1

package/skills/logicprobe/references/dsh-model-schema.md

@@ -1,204 +1,266 @@
-# DSH Model Schema v1 — logicprobe_verify
-
-The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The engine runs 19 checks (S1-S8 structural, A1-A11 adversarial) and returns a JSON report. When `beforeModel` is supplied, it also runs D1-D4 before/after regression checks. Guards and updates are structured data — no code strings, no arbitrary execution.
-
-## Top-level model
-
-```json
-{
-  "schemaVersion": 1,
-  "init": "INIT",
-  "states": [{ "id": "INIT" }, { "id": "ACTIVE", "terminal": true }],
-  "transitions": [
-    { "from": "INIT", "event": "go", "to": "ACTIVE" }
-  ],
-  "variables": [],
-  "invariants": [],
-  "concurrentPairs": [],
-  "boundaryChecks": [],
-  "resourcePairs": [],
-  "idempotentEvents": []
-}
-```
-
-| Field | Required | Meaning |
-|---|---|---|
-| `schemaVersion` | yes | Must be `1` |
-| `init` | yes | Initial state id |
-| `states` | yes | `{ id, terminal? }`; `terminal` exempts S2/S3/S5/A1 |
-| `transitions` | yes | `{ from, event, to, guard?, updates? }` |
-| `variables` | no | `{ name, kind: integer\|boolean, init, min?, max?, monotonic? }` |
-| `invariants` | no | See invariant kinds below |
-| `concurrentPairs` | no | `["eventA", "eventB"]` pairs for A2 |
-| `boundaryChecks` | no | `{ variable, values: number[] }` for A5 |
-| `resourcePairs` | no | `{ resource, acquireEvent, releaseEvent, failEvent? }` for A4/A6 |
-| `idempotentEvents` | no | Events that must be replay-safe; verified by A8 |
-| `narrative` | no | Natural-language descriptions of states, events, and (state, event) scenarios — echoed in the report |
-
-## Model narrative (natural-language context)
-
-The model may carry a `narrative` block explaining, in natural language, what
-every symbol means in the real scenario. It is what gets shown to the user when
-the extracted model is presented for confirmation, and the report echoes it back
-so findings can be read against real scenarios instead of bare ids.
-
-```json
-"narrative": {
-  "states": {
-    "NEW": "订单已创建，等待支付",
-    "PAID": "已支付，等待发货",
-    "SHIPPED": "已发货，等待签收",
-    "DONE": "已完成（终态）",
-    "CANCELLED": "已取消（终态）"
-  },
-  "events": {
-    "pay": "买家完成支付",
-    "ship": "仓库发货",
-    "deliver": "买家签收",
-    "cancel": "取消订单"
-  },
-  "scenarios": [
-    { "from": "NEW", "event": "pay", "scenario": "下单后支付成功，订单进入待发货" },
-    { "from": "PAID", "event": "ship", "scenario": "已支付订单发货，进入运输中" },
-    { "from": "SHIPPED", "event": "deliver", "scenario": "签收完成，订单结束" },
-    { "from": "NEW", "event": "cancel", "scenario": "未支付订单被取消" },
-    { "from": "PAID", "event": "cancel", "scenario": "已支付订单取消并退款" }
-  ]
-}
-```
-
-**Completeness contract**: when `narrative` is present, all three parts are
-required and must fully cover the model — every declared state needs a
-`narrative.states` entry, every event used in `transitions` needs a
-`narrative.events` entry, and every distinct `(from, event)` group needs a
-`narrative.scenarios` entry. Keys must reference declared ids; unknown
-references, missing coverage, and duplicate scenario keys are model validation
-errors. The report's `narrative` field echoes the block unchanged.
-
-**Presenting the model**: when showing the extracted model for confirmation, render
-the natural language INLINE in the model presentation, not as a separate block.
-Three rendering forms (all derive from the same `narrative` data):
-
-- **Form A — integrated transition table (default)**: one row per transition with
-  state/event meanings in parentheses and the scenario as the last column. Keep
-  meanings short (state/event ≤ 6 characters, scenario ≤ 10) and estimate row
-  width (CJK counts as 2) so rows fit the display area — a wrapped row loses
-  column alignment and readability collapses.
-- **Form B — sentence blocks (reading-accessible)**: scenario sentence first, then
-  a fixed three-line frame (状态…/发生…/进入…). Use for detailed confirmation,
-  users with reading difficulties, or ≤ 10 transitions.
-- **Form C — grouped by source state (large machines / narrow panes)**: one
-  section per state, each rendered as its own small 3-column table
-  （`event（含义）| NEXT（含义）| 场景`）; no cross-group column alignment to
-  track. Use for ≥ 15 transitions or narrow display areas; if a group table would
-  still wrap, fall back to a one-line-per-event bullet list for that group.
-
-## Guards
-
-A guard is exactly one of:
-
-```json
-{ "variable": "retry", "op": "<", "value": 3 }
-{ "all": [ { "variable": "armed", "op": "==", "value": true }, { "variable": "retry", "op": ">", "value": 0 } ] }
-{ "any": [ { "variable": "mode", "op": "==", "value": 1 }, { "variable": "mode", "op": "==", "value": 2 } ] }
-{ "not": { "variable": "locked", "op": "==", "value": true } }
-```
-
-- Boolean variables only support `==` / `!=`.
-- A transition with **no guard** is the default/else branch for its `(from, event)` group. It fires only when no guarded branch in that group is true.
-- Multiple true guards in one `(from, event)` group are reported as S4 nondeterminism; a group with guards and no default must be exhaustive or S6 flags the missing branch.
-
-## Updates
-
-```json
-{ "variable": "retry", "op": "inc", "value": 1 }
-{ "variable": "retry", "op": "set", "value": 0 }
-{ "variable": "retry", "op": "dec", "value": 1 }
-```
-
-`inc`/`dec` default to 1 when `value` is omitted. `set` defaults to 0.
-
-## Invariants
-
-| Kind | Shape | Checks |
-|---|---|---|
-| `never-states` | `{ states: ["ERROR"] }` | No reachable runtime state may be in the forbidden set |
-| `var-in-range` | `{ variable, min?, max? }` | Every reachable runtime state keeps the variable in range |
-| `event-before-state` | `{ event: "power_ready", state: "ACTIVE" }` | Every path entering `state` must have passed through `event` first |
-| `leads-to` | `{ from: "MIGRATING", to: "DONE" }` | Every path from `from` must eventually reach `to` |
-| `sequence` | `{ events: ["backup", "modify", "commit"] }` | Events must occur in the given order |
-| `atomicity` | `{ events: ["write"], commit: "commit", rollback?: "rollback" }` | Atomic group must end with commit/rollback before leaving scope |
-
-A7 reports the shortest violating path for each failed invariant. An empty path means the initial state already violates it.
-
-## Permission presets and interaction mode
-
-| Preset | sandbox | approval | logicprobe behavior |
-|---|---|---|---|
-| `workspace-write` | workspace-write | ask | Evidence stays in workspace; model confirmation defaults to ask |
-| `danger-full-access` | danger-full-access | never | Full file access; interaction resolves to auto; never request sandbox escalation |
-| custom | any | any | The session folds the last `sandbox/mode` and `approval/policy` events; interaction follows approval only |
-
-In `interaction=auto`, do NOT call `ask_user_question` for model confirmation. Round-trip the extracted model into a transition table, compare it against the source extraction, and mark the report `UNCONFIRMED`.
-
-## Minimal example
-
-```json
-{
-  "schemaVersion": 1,
-  "init": "INIT",
-  "states": [
-    { "id": "INIT" },
-    { "id": "RETRY" },
-    { "id": "FATAL", "terminal": true }
-  ],
-  "transitions": [
-    { "from": "INIT", "event": "timeout", "guard": { "variable": "retry", "op": "<", "value": 3 }, "to": "RETRY", "updates": [{ "variable": "retry", "op": "inc" }] },
-    { "from": "INIT", "event": "timeout", "guard": { "variable": "retry", "op": ">=", "value": 3 }, "to": "FATAL" }
-  ],
-  "variables": [{ "name": "retry", "kind": "integer", "init": 0, "min": 0, "max": 3 }],
-  "boundaryChecks": [{ "variable": "retry", "values": [0, 1, 2, 3] }]
-}
-```
-
-## Before/after comparison (D1-D4)
-
-When `beforeModel` is passed to `logicprobe_verify`, the engine treats `model` as AFTER and runs four extra checks after S1-A11:
-
-| Check | Purpose |
-|---|---|
-| D1 Behavioral Preservation | Every BEFORE (state, event) that could fire must still be fireable from the mapped AFTER state |
-| D2 Invariant Continuity | Every BEFORE invariant (mapped through `stateMapping`) must still hold in AFTER |
-| D3 Regression Delta | Lists added/removed states, events, and transitions |
-| D4 Deadlock/Liveness Regression | New deadlock states or closed SCCs not present in BEFORE |
-
-`stateMapping` maps BEFORE state ids to AFTER state ids. Omit it when state names are unchanged.
-
-Example tool call shape:
-
-```json
-{
-  "model": { "...": "AFTER LogicModelV1" },
-  "beforeModel": { "...": "BEFORE LogicModelV1" },
-  "stateMapping": { "OLD_INIT": "INIT", "OLD_ACTIVE": "ACTIVE" }
-}
-```
-
-The report's `comparison` object includes both model hashes, state/transition counts, and delta arrays.
-
-## Idempotent replay (A8)
-
-List events that must be idempotent in `idempotentEvents`. For every reachable state, applying the event twice must produce the same state as applying it once. This is useful for retries, webhook redelivery, and migration replay.
-
-## Advanced constraints (S8, A9-A11)
-
-- **S8 Monotonic Variables**: declare `monotonic: "inc"|"dec"` on a variable; updates must not move in the opposite direction.
-- **A9 Leads-To**: `{ kind: "leads-to", from, to }` — every path from `from` must eventually reach `to`.
-- **A10 Sequence**: `{ kind: "sequence", events }` — events must appear in order.
-- **A11 Atomicity**: `{ kind: "atomicity", events, commit, rollback? }` — once an atomic event starts, the machine must reach commit/rollback before leaving the atomic scope or terminating.
-
-## Limits
-
-- State-space exploration caps at `maxStates` (default 10000); larger guards/domains may report truncation instead of a false pass.
-- A3 samples the first `maxPermutationEvents` events (default 5).
-- The engine is a finite-state model checker. It cannot prove properties of the real implementation; follow with code-level review.
+# DSH Model Schema v1 — logicprobe_verify
+
+The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The engine runs 22 checks (S1-S8 structural, A1-A14) and returns a JSON report. When `beforeModel` is supplied, it also runs D1-D4 before/after regression checks. Guards and updates are structured data — no code strings, no arbitrary execution.
+
+## Top-level model
+
+```json
+{
+  "schemaVersion": 1,
+  "init": "INIT",
+  "states": [{ "id": "INIT" }, { "id": "ACTIVE", "terminal": true }],
+  "transitions": [
+    { "from": "INIT", "event": "go", "to": "ACTIVE" }
+  ],
+  "variables": [],
+  "invariants": [],
+  "concurrentPairs": [],
+  "boundaryChecks": [],
+  "resourcePairs": [],
+  "idempotentEvents": []
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `schemaVersion` | yes | Must be `1` |
+| `init` | yes | Initial state id |
+| `states` | yes | `{ id, terminal?, onEntry?, onExit?, maxTicks? }`; `terminal` exempts S2/S3/S5/A1; `onEntry`/`onExit` are action-name lists fired on entry/exit and treated by A4 as implicit acquire/release; `maxTicks` is an A14 deadline since entry (needs top-level `tickEvents`) |
+| `transitions` | yes | `{ from, event, to, guard?, updates?, cost?, weight? }`; `cost` (non-negative, absent = 1) is checked by A12 against `budget` invariants; `weight` (non-negative, absent = 1) makes the machine a DTMC under A13 `probability` invariants |
+| `variables` | no | `{ name, kind: integer\|boolean, init, min?, max?, monotonic? }` |
+| `invariants` | no | See invariant kinds below |
+| `concurrentPairs` | no | `["eventA", "eventB"]` pairs for A2 |
+| `boundaryChecks` | no | `{ variable, values: number[] }` for A5 |
+| `resourcePairs` | no | `{ resource, acquireEvent, releaseEvent, failEvent? }` for A4/A6 |
+| `idempotentEvents` | no | Events that must be replay-safe; verified by A8 |
+| `narrative` | no | Natural-language descriptions of states, events, and (state, event) scenarios — echoed in the report |
+
+## Model narrative (natural-language context)
+
+The model may carry a `narrative` block explaining, in natural language, what
+every symbol means in the real scenario. It is what gets shown to the user when
+the extracted model is presented for confirmation, and the report echoes it back
+so findings can be read against real scenarios instead of bare ids.
+
+```json
+"narrative": {
+  "states": {
+    "NEW": "订单已创建，等待支付",
+    "PAID": "已支付，等待发货",
+    "SHIPPED": "已发货，等待签收",
+    "DONE": "已完成（终态）",
+    "CANCELLED": "已取消（终态）"
+  },
+  "events": {
+    "pay": "买家完成支付",
+    "ship": "仓库发货",
+    "deliver": "买家签收",
+    "cancel": "取消订单"
+  },
+  "scenarios": [
+    { "from": "NEW", "event": "pay", "scenario": "下单后支付成功，订单进入待发货" },
+    { "from": "PAID", "event": "ship", "scenario": "已支付订单发货，进入运输中" },
+    { "from": "SHIPPED", "event": "deliver", "scenario": "签收完成，订单结束" },
+    { "from": "NEW", "event": "cancel", "scenario": "未支付订单被取消" },
+    { "from": "PAID", "event": "cancel", "scenario": "已支付订单取消并退款" }
+  ]
+}
+```
+
+**Completeness contract**: when `narrative` is present, all three parts are
+required and must fully cover the model — every declared state needs a
+`narrative.states` entry, every event used in `transitions` needs a
+`narrative.events` entry, and every distinct `(from, event)` group needs a
+`narrative.scenarios` entry. Keys must reference declared ids; unknown
+references, missing coverage, and duplicate scenario keys are model validation
+errors. The report's `narrative` field echoes the block unchanged.
+
+**Presenting the model**: when showing the extracted model for confirmation, render
+the natural language INLINE in the model presentation, not as a separate block.
+Three rendering forms (all derive from the same `narrative` data):
+
+- **Form A — integrated transition table (default)**: one row per transition with
+  state/event meanings in parentheses and the scenario as the last column. Keep
+  meanings short (state/event ≤ 6 characters, scenario ≤ 10) and estimate row
+  width (CJK counts as 2) so rows fit the display area — a wrapped row loses
+  column alignment and readability collapses.
+- **Form B — sentence blocks (reading-accessible)**: scenario sentence first, then
+  a fixed three-line frame (状态…/发生…/进入…). Use for detailed confirmation,
+  users with reading difficulties, or ≤ 10 transitions.
+- **Form C — grouped by source state (large machines / narrow panes)**: one
+  section per state, each rendered as its own small 3-column table
+  （`event（含义）| NEXT（含义）| 场景`）; no cross-group column alignment to
+  track. Use for ≥ 15 transitions or narrow display areas; if a group table would
+  still wrap, fall back to a one-line-per-event bullet list for that group.
+
+## Guards
+
+A guard is exactly one of:
+
+```json
+{ "variable": "retry", "op": "<", "value": 3 }
+{ "all": [ { "variable": "armed", "op": "==", "value": true }, { "variable": "retry", "op": ">", "value": 0 } ] }
+{ "any": [ { "variable": "mode", "op": "==", "value": 1 }, { "variable": "mode", "op": "==", "value": 2 } ] }
+{ "not": { "variable": "locked", "op": "==", "value": true } }
+```
+
+- Boolean variables only support `==` / `!=`.
+- A transition with **no guard** is the default/else branch for its `(from, event)` group. It fires only when no guarded branch in that group is true.
+- Multiple true guards in one `(from, event)` group are reported as S4 nondeterminism; a group with guards and no default must be exhaustive or S6 flags the missing branch.
+
+## Updates
+
+```json
+{ "variable": "retry", "op": "inc", "value": 1 }
+{ "variable": "retry", "op": "set", "value": 0 }
+{ "variable": "retry", "op": "dec", "value": 1 }
+```
+
+`inc`/`dec` default to 1 when `value` is omitted. `set` defaults to 0.
+
+## Invariants
+
+| Kind | Shape | Checks |
+|---|---|---|
+| `never-states` | `{ states: ["ERROR"] }` | No reachable runtime state may be in the forbidden set |
+| `var-in-range` | `{ variable, min?, max? }` | Every reachable runtime state keeps the variable in range |
+| `event-before-state` | `{ event: "power_ready", state: "ACTIVE" }` | Every path entering `state` must have passed through `event` first |
+| `leads-to` | `{ from: "MIGRATING", to: "DONE" }` | Every path from `from` must eventually reach `to` |
+| `sequence` | `{ events: ["backup", "modify", "commit"] }` | Events must occur in the given order |
+| `atomicity` | `{ events: ["write"], commit: "commit", rollback?: "rollback" }` | Atomic group must end with commit/rollback before leaving scope |
+| `budget` | `{ budget: n }` | No reachable path may accumulate transition cost greater than n (A12). Costs are non-negative; a transition without `cost` counts 1, so legacy machines keep step-count semantics |
+| `probability` | `{ target, op: one of >= <= > <, p }` | P(ever hitting target) must satisfy the bound (A13, DTMC from transition `weight`, default 1; value iteration) |
+
+A7 reports the shortest violating path for each failed invariant. An empty path means the initial state already violates it.
+
+## Permission presets and interaction mode
+
+| Preset | sandbox | approval | logicprobe behavior |
+|---|---|---|---|
+| `workspace-write` | workspace-write | ask | Evidence stays in workspace; model confirmation defaults to ask |
+| `danger-full-access` | danger-full-access | never | Full file access; interaction resolves to auto; never request sandbox escalation |
+| custom | any | any | The session folds the last `sandbox/mode` and `approval/policy` events; interaction follows approval only |
+
+In `interaction=auto`, do NOT call `ask_user_question` for model confirmation. Round-trip the extracted model into a transition table, compare it against the source extraction, and mark the report `UNCONFIRMED`.
+
+## Cost and budget (A12)
+
+Transitions may carry a non-negative execution cost (`cost`, default 1 per transition — e.g. cycles or microseconds spent in the handler). A `budget` invariant bounds the worst-case accumulated cost over every reachable path:
+
+```json
+{
+  "id": "dispatch-budget",
+  "description": "worst-case dispatch path stays within 100 cycles",
+  "kind": "budget",
+  "budget": 100
+}
+```
+
+A12 reports the shortest over-budget counterexample path. A reachable cycle whose cost is positive is reported as unbounded — under model event semantics it can repeat indefinitely, so no finite budget holds. Budgets on machines with repeatable loops must bound those loops with variables (e.g. a retry counter guard). If transitions declare `cost` but no `budget` invariant exists, A12 emits the advisory `A12_COST_WITHOUT_BUDGET`.
+
+## Probability reachability (A13)
+
+Declare `weight` on transitions (default 1) to interpret the machine as a DTMC, then add a `probability` invariant:
+
+```json
+{ "id": "reliability", "description": "at least 90% of runs reach SAFE", "kind": "probability", "target": "SAFE", "op": ">=", "p": 0.9 }
+```
+
+A13 computes P(ever hitting `target`) from the initial state by value iteration over the absorbing chain (transitions with `weight` 0 never fire; terminals other than the target are absorbing failures) and reports a violation when the bound fails. Converges to the least fixed point; an iteration cap protects against non-convergent models.
+
+## Deadline check (A14)
+
+Declare which events advance the discrete clock (`tickEvents`) and set `maxTicks` on a state that must be left within that many ticks of entering it:
+
+```json
+{ "schemaVersion": 1, "init": "LISTEN", "states": [{ "id": "LISTEN" }, { "id": "CRITICAL", "maxTicks": 2 }, { "id": "SAFE", "terminal": true }], "transitions": [ { "from": "LISTEN", "event": "fault", "to": "CRITICAL" }, { "from": "CRITICAL", "event": "recover", "to": "SAFE" } ], "tickEvents": ["tick"] }
+```
+
+A14 explores residency with a per-entry tick counter: a `tickEvents` step that keeps the machine resident past `maxTicks` reports `A14_DEADLINE_MISS` with the over-residency path. Time advances only when a tick event fires — real-time passage (auto-advancing clocks) is not modeled; dense-time claims still route to timed model checkers. States declaring `maxTicks` without any `tickEvents` yield the advisory `A14_NO_TICK_EVENTS`.
+
+## State entry/exit actions (onEntry / onExit)
+
+States may declare ordered action-name lists that fire automatically:
+
+```json
+{ "id": "ACTIVE", "onEntry": ["sync_lock"], "onExit": ["sync_unlock"] }
+```
+
+Actions never change state or variables. Checks that care about resource discipline see them as implicit events: A4 Pair Symmetry treats an action equal to a pair acquireEvent/releaseEvent as an acquire/release that fires on every entry (resp. exit) of the state, so lock/unlock hidden inside entry/exit actions is verified without hand-written ENTER_x/EXIT_x pseudo-events.
+
+## Composition verification
+
+Two or more machines can be checked together with `runCompositionVerification` (DSH tool `logicprobe_compose_verify`):
+
+- non-rendezvous events advance exactly one firing machine;
+- a rendezvous (handshake) event fires only when at least two machines declare it and every such non-terminal machine has it jointly enabled (guards held); participants advance simultaneously;
+- a terminal machine is stopped and does not participate.
+
+Checks: `C1_COMPOSITION_DEADLOCK` (a reachable composite state with no move while at least one machine is not terminal) and `C2_RENDEZVOUS_NEVER_FIRES`. This is a product-space BFS, so composite state count is the product of the machines; keep `maxStates` in mind.
+
+## Minimal example
+
+```json
+{
+  "schemaVersion": 1,
+  "init": "INIT",
+  "states": [
+    { "id": "INIT" },
+    { "id": "RETRY" },
+    { "id": "FATAL", "terminal": true }
+  ],
+  "transitions": [
+    { "from": "INIT", "event": "timeout", "guard": { "variable": "retry", "op": "<", "value": 3 }, "to": "RETRY", "updates": [{ "variable": "retry", "op": "inc" }] },
+    { "from": "INIT", "event": "timeout", "guard": { "variable": "retry", "op": ">=", "value": 3 }, "to": "FATAL" }
+  ],
+  "variables": [{ "name": "retry", "kind": "integer", "init": 0, "min": 0, "max": 3 }],
+  "boundaryChecks": [{ "variable": "retry", "values": [0, 1, 2, 3] }]
+}
+```
+
+## Before/after comparison (D1-D4)
+
+When `beforeModel` is passed to `logicprobe_verify`, the engine treats `model` as AFTER and runs four extra checks after S1-A11:
+
+| Check | Purpose |
+|---|---|
+| D1 Behavioral Preservation | Every BEFORE (state, event) that could fire must still be fireable from the mapped AFTER state |
+| D2 Invariant Continuity | Every BEFORE invariant (mapped through `stateMapping`) must still hold in AFTER |
+| D3 Regression Delta | Lists added/removed states, events, and transitions |
+| D4 Deadlock/Liveness Regression | New deadlock states or closed SCCs not present in BEFORE |
+
+`stateMapping` maps BEFORE state ids to AFTER state ids. Omit it when state names are unchanged.
+
+Example tool call shape:
+
+```json
+{
+  "model": { "...": "AFTER LogicModelV1" },
+  "beforeModel": { "...": "BEFORE LogicModelV1" },
+  "stateMapping": { "OLD_INIT": "INIT", "OLD_ACTIVE": "ACTIVE" }
+}
+```
+
+The report's `comparison` object includes both model hashes, state/transition counts, and delta arrays.
+
+## Idempotent replay (A8)
+
+List events that must be idempotent in `idempotentEvents`. For every reachable state, applying the event twice must produce the same state as applying it once. This is useful for retries, webhook redelivery, and migration replay.
+
+## Advanced constraints (S8, A9-A14)
+
+- **S8 Monotonic Variables**: declare `monotonic: "inc"|"dec"` on a variable; updates must not move in the opposite direction.
+- **A9 Leads-To**: `{ kind: "leads-to", from, to }` — every path from `from` must eventually reach `to`.
+- **A10 Sequence**: `{ kind: "sequence", events }` — events must appear in order.
+- **A11 Atomicity**: `{ kind: "atomicity", events, commit, rollback? }` — once an atomic event starts, the machine must reach commit/rollback before leaving the atomic scope or terminating.
+- **A12 Budget**: `{ kind: "budget", budget }` — no reachable path may accumulate transition cost above the budget; reports the shortest over-budget path and flags reachable positive-cost cycles as unbounded.
+- **A13 Probability**: `{ kind: "probability", target, op, p }` — P(ever hitting target) must satisfy the bound under the DTMC induced by transition `weight` (default 1).
+- **A14 Deadline**: state `maxTicks` + top-level `tickEvents` — a tick step may not keep a state resident past its deadline; reports the over-residency path.
+
+## Limits
+
+- State-space exploration caps at `maxStates` (default 10000); larger guards/domains may report truncation instead of a false pass.
+- A3 samples the first `maxPermutationEvents` events (default 5).
+- The engine is a finite-state model checker. It cannot prove properties of the real implementation; follow with code-level review.
+- `cost` values are modeler-provided static labels — A12 verifies against them; real execution time/WCET needs binary-level timing analysis.
+- When the model state/event/action names reference semantics the engine does not verify (timing, preemption, hybrid control, probability), the report carries informational `coverageNotes` that route such claims to dedicated tools. These notes are vocabulary-based heuristics, never a substitute for the checks.

package/skills/logicprobe/references/gap-routing-guide.md

@@ -0,0 +1,36 @@
+# Gap Routing Guide
+
+logicprobe is a design-time, qualitative model checker. For semantic dimensions it does
+not model, it does not stay silent: it routes claims to dedicated tools. This reference
+is the routing table shared by the verification report (`coverageNotes`), the
+concurrency scanner (`suggestions` on absolute claims), and manual review.
+
+Routing is a hint, not a proof. A note never verifies the claim — it marks the dimension
+as outside this engine and points at tooling that can handle it.
+
+| Dimension | What logicprobe covers today | Claim examples | Dedicated tooling | Why not here |
+|---|---|---|---|---|
+| Hard real time (timing) | Order, counts, path budgets (A12); time modeled only as counters + events | "500 ms to SAFE", "no deadline miss", "period ≤ 1 ms" | UPPAAL, IMITATOR (timed automata); binary-level timing analysis for WCET | No clocks, deadlines, or period semantics |
+| Preemptive concurrency | Event-order interleavings (A2/A3), resource pairing (A4), idempotent replay (A8) | "thread-safe", "interrupt-safe", "no priority inversion" | TSan/Helgrind (runtime), CBMC (proof), TLA+ (interleaving model), RTOS-aware analysis | Single-threaded event model; no preemption, IRQ nesting, or atomics at instruction level |
+| Hybrid control (continuous plant) | Discrete transitions and modes only | "switching is stable", "no chattering", "settling within T" | SpaceEx, Flow* (hybrid reachability), Simulink/Stateflow verification | No continuous dynamics; stability is not expressible |
+| Probabilistic / reliability | Qualitative reachability and invariants | "MTBF ≥ X", "failure rate ≤ p", "availability ≥ 99.9%" | PRISM, Storm (stochastic model checking), fault-tree / FMEA | No probability semantics |
+| Execution cost / performance | A12 budget checks over declared transition `cost` (absent = 1) | "worst-case dispatch ≤ 100 cycles" | aiT, RapiTime (real WCET at binary level) | `cost` is a modeler label, not measured execution time |
+| Multi-machine composition | Single machine verified; cross-machine contract must be documented separately | "A sends E, B always handles E" | CSP (FDR), mCRL2, TLA+ (compositional models) | No composition semantics between machines |
+| Nested/hierarchical statecharts | Flat models only; flatten before verification | parent/child states, orthogonal regions | SCXML / Stateflow (native hierarchy) | Flat state list only — flatten manually and re-confirm |
+
+## Where the routing surfaces
+
+- `logicprobe_verify` report: a model whose state/event/action names match the timing,
+  preemption, hybrid, or probability vocabulary gets informational `coverageNotes`
+  with the same routing as above.
+- A12 advisory: transitions declaring `cost` without a `budget` invariant produce
+  `A12_COST_WITHOUT_BUDGET`, pointing at the budget check.
+- `logicprobe_concurrency_scan`: absolute concurrency claims (thread-safe, lock-free,
+  interrupt-safe, ...) carry `suggestions` naming dedicated tools.
+- Manual review: when reading a plan, match its claims against the table above and
+  require dedicated evidence before accepting "always"/"never"/"guaranteed" language
+- Generators: `exportModel(model, format)` emits native inputs for UPPAAL (.xta + queries),
+  TLA+ (TLC spec + safety), PRISM (.pm + .pctl), and SPIN (Promela + ltl) from a
+  LogicModelV1 — v1 translates the core machine (guards/updates/weights; booleans as
+  integers) and leaves unrepresentable invariants as explicit warnings.
+  Self-tests: tests/exporters/run.mjs.

package/skills/logicprobe/references/logic-verification-guide.md

@@ -319,6 +319,56 @@ ATOMIC_GROUPS = [
 ]
 ```
 
+### A12: Budget (Worst-Case Path Cost)
+
+For performance-sensitive claims ("the dispatch path stays within 100 cycles", "worst-case latency ≤ budget"), model each transition with an execution cost and declare a budget:
+
+```python
+TRANSITION_COSTS = {  # (from, event): cost; absent entries count as 1
+    ("BOOT", "calibrate_done"): 40,
+    ("IDLE", "enable"): 5,
+    ("RUN", "watchdog_expiry"): 15,
+}
+BUDGETS = [
+    {"id": "dispatch-budget", "description": "worst-case path within budget", "budget": 100},
+]
+```
+
+Probe: find the shortest path from init whose accumulated cost exceeds the budget; report it verbatim. A reachable cycle with positive total cost means cost can grow without bound — flag it as a budget violation regardless of the declared budget.
+
+In DSH (`logicprobe_verify`), `cost` is an optional field on transitions (absent = 1) and `budget` is an invariant kind; A12 runs automatically. Cost values are modeler-provided static labels — they verify the model against the declared budget, not the real WCET, which needs binary-level timing analysis.
+
+### A13: Probability Reachability (DTMC)
+
+For claims with a reliability/probability flavor ("at least 90% of runs reach SAFE", "P(broke first) ≥ 0.75"), attach a relative weight to each branch and declare the bound. Absent weight = 1; weight 0 means the branch never fires probabilistically.
+
+```python
+TRANSITION_WEIGHTS = {  # (from_state, event): weight; absent entries count as 1
+    ("RUN", "ok"): 9,
+    ("RUN", "bad"): 1,
+}
+PROBABILITY_INVARIANTS = [
+    {"id": "reliability", "target": "SAFE", "op": ">=", "p": 0.9},
+]
+```
+
+Probe: solve P(ever reaching `target`) from INIT by value iteration over the reachable absorbing chain; compare against the bound. In DSH (`logicprobe_verify`), `weight` on transitions plus a `probability` invariant runs A13 automatically. This is a qualitative DTMC check of the modeler's weights — real MTBF/failure-rate numbers need PRISM/Storm or fault-tree analysis.
+
+### A14: Deadline (Discrete Tick Clock)
+
+For real-time-sounding claims ("must leave BUSY within 3 ticks", "watchdog resets before deadline"), declare which events advance the clock and cap per-state residency:
+
+```python
+TICK_EVENTS = {"tick"}
+STATE_MAX_TICKS = {"BUSY": 3}
+```
+
+Probe: explore residency — a `tick` step that keeps the machine resident past `maxTicks` is a deadline miss; report the over-residency path. In DSH (`logicprobe_verify`), state `maxTicks` plus top-level `tickEvents` run A14 automatically. This checks the model's declared deadlines, not real execution time (see Known Limitations below; hard real-time semantics route to UPPAAL).
+
+### Standalone engine (non-DSH, JSON models)
+
+`references/logicprobe-engine.py` is an exact Python mirror of the DSH tools: `verify model.json` runs all 22 checks + D1-D4 with a `--before-model`/optional `--state-mapping`; `compose m1.json m2.json ... --rendezvous a,b` runs C1/C2 composition; `export model.json --format uppaal|tla|prism|spin` reproduces the four exporters byte-for-byte. It reads the same LogicModelV1 JSON as DSH, so a model verified in one host verifies identically in the other (checked by tests/python/run.mjs).
+
 ## Counter-Example Interpretation
 
 When a probe finds a counter-example, classify it:
@@ -360,14 +410,16 @@ When a probe finds a counter-example, classify it:
 - **Hardware-specific behavior**: Memory-mapped I/O timing, DMA races, cache coherency
 - **Undocumented behavior**: If the plan doesn't describe a transition, the model can't either
 - **Real concurrency**: The model is single-threaded; true preemptive multitasking bugs are out of scope
-- **Entry/exit actions**: State entry/exit side effects (e.g., `lock()` on enter, `unlock()` on exit) are not modeled as events. A4 Pair Symmetry may miss unbalanced pairs that exist only in entry/exit actions. If the plan describes these, manually extract them as pseudo-events (`ENTER_state`, `EXIT_state`) before running verification.
+- **Entry/exit actions**: State entry/exit side effects (e.g., `lock()` on enter, `unlock()` on exit) are not modeled as events. A4 Pair Symmetry may miss unbalanced pairs that exist only in entry/exit actions. If the plan describes these, manually extract them as pseudo-events (`ENTER_state`, `EXIT_state`) before running verification. In DSH (`logicprobe_verify`), state `onEntry`/`onExit` declarations are modeled natively and A4 treats them as implicit acquire/release events — no manual pseudo-events needed.
+- **Execution cost is modeler-annotated**: transition `cost` (absent = 1) and `budget` invariants are static labels; A12 verifies the model against them. Real execution time/WCET needs binary-level timing analysis (e.g. aiT, RapiTime).
+- **Unverified semantic dimensions**: when model or document vocabulary references hard real time, preemptive concurrency, hybrid control stability, or probability/reliability, logicprobe reports informational notes / routes to dedicated tools — it never verifies those claims itself. See `references/gap-routing-guide.md`.
 - **Guard variable scope**: The model treats guard variables as global to the machine. If a guard variable's lifetime is state-scoped (reset on entry) but the model assumes it accumulates globally, boundary-blast results will be wrong. Verify guard variable scope during extraction.
 - **Nested/hierarchical states (Harel statecharts)**: The model only supports flat state machines. Parent/child state nesting, history pseudostates, and orthogonal regions are not supported — flatten them manually before verification.
 - **Cross-machine protocols**: Two interacting state machines are verified independently. Composition bugs (e.g., Machine A sends event E to Machine B, but B is in a state that doesn't handle E) are invisible to single-machine verification. If the plan describes multi-machine interaction, document the protocol contract separately.
 
 ### Model Fidelity Warning
 
-The Python model is an APPROXIMATION. It models state transitions, not execution semantics. A model that passes all 14 checks means the plan's LOGIC is consistent — NOT that the implementation will work. Always follow logic verification with code-level review.
+The Python model is an APPROXIMATION. It models state transitions, not execution semantics. A model that passes all 22 checks (S1-S8 structural, A1-A14) means the plan's LOGIC is consistent — NOT that the implementation will work. Always follow logic verification with code-level review.
 
 ## Refactoring Verification
 
@@ -485,8 +537,8 @@ Manual verification takes longer but produces identical-quality findings. The ke
 6a. Python ≥ 3.6 → load verification-harness.py → fill in MODEL → run
 6b. No Python → use Manual Verification Mode (see above) — execute each check step by step
 7. Extract model → show transition table → GET USER CONFIRMATION
-8. Run Phase 2a (7 structural primitives) → log results
-9. Run Phase 2b (7 adversarial probes) → log results
+8. Run Phase 2a (8 structural primitives) → log results
+9. Run Phase 2b (14 adversarial probes) → log results
 10. Classify counter-examples (true positive / model error / acceptable risk)
 11. Feed confirmed findings into Phase 3 (gap analysis)
 12. Include in Phase 5 (structured output)