dsh-logicprobe 0.8.1 → 0.9.0

package/lib/concurrency-tool.js

@@ -9,7 +9,7 @@ export const LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME = 'logicprobe_concurrency_sca
  */
 export const logicProbeConcurrencyScanTool = defineTool({
     name: LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME,
-    description: 'Scan a document or plan text for concurrency risk points. Use ONLY after confirming the target actually has concurrency requirements or behavior (threads, async tasks, interrupts, shared state, parallel execution). If the target is purely sequential, do not call this tool. Returns findings for keywords like thread-safe, lock-free, data race, race condition, atomic, synchronized, mutex, semaphore, shared variable, reentrant, interrupt-safe. Absolute claims (thread-safe, lock-free, no data race) are flagged as errors requiring dedicated verification.',
+    description: 'Scan a document or plan text for concurrency risk points. Use ONLY after confirming the target actually has concurrency requirements or behavior (threads, async tasks, interrupts, shared state, parallel execution). If the target is purely sequential, do not call this tool. Returns findings for keywords like thread-safe, lock-free, wait-free, data race, race condition, atomic, synchronized, mutex, semaphore, spinlock, shared variable, shared memory, reentrant, interrupt-safe, ISR, IRQ, NMI, critical section, disable_irq/enable_irq. Absolute claims (thread-safe, lock-free, no data race, interrupt-safe, ISR-safe) are flagged as errors requiring dedicated verification, and each carries suggestions naming the analysis to run instead (TSan/Helgrind, CBMC, TLA+, or RTOS-aware interrupt analysis). logicprobe does not prove concurrency safety.',
     parameters: {
         text: {
             type: 'string',

package/lib/engine.js

@@ -308,10 +308,36 @@ export function validateModel(input) {
                         bad(path + '.from', 'must be a non-empty string');
                     else if (!invariantStateIds.has(invariant.from))
                         bad(path + '.from', 'references unknown state ' + invariant.from);
-                    if (typeof invariant.to !== 'string' || invariant.to.length === 0)
-                        bad(path + '.to', 'must be a non-empty string');
-                    else if (!invariantStateIds.has(invariant.to))
-                        bad(path + '.to', 'references unknown state ' + invariant.to);
+                    // `to` is one state id or a target set. A set with a duplicate member is a
+                    // model-authoring slip that would otherwise give one meaning two hashes, so it
+                    // is rejected rather than silently deduplicated.
+                    if (typeof invariant.to === 'string') {
+                        if (invariant.to.length === 0)
+                            bad(path + '.to', 'must be a non-empty string');
+                        else if (!invariantStateIds.has(invariant.to))
+                            bad(path + '.to', 'references unknown state ' + invariant.to);
+                    }
+                    else if (Array.isArray(invariant.to)) {
+                        if (invariant.to.length === 0)
+                            bad(path + '.to', 'must be a non-empty array of state ids');
+                        else {
+                            const targets = new Set();
+                            invariant.to.forEach((target, targetIndex) => {
+                                const at = path + '.to[' + targetIndex + ']';
+                                if (typeof target !== 'string' || target.length === 0)
+                                    bad(at, 'must be a non-empty string');
+                                else if (!invariantStateIds.has(target))
+                                    bad(at, 'references unknown state ' + target);
+                                else if (targets.has(target))
+                                    bad(at, 'duplicates state ' + target + ' in the target set');
+                                else
+                                    targets.add(target);
+                            });
+                        }
+                    }
+                    else {
+                        bad(path + '.to', 'must be a state id or a non-empty array of state ids');
+                    }
                 }
                 else if (invariant.kind === 'sequence') {
                     if (!Array.isArray(invariant.events) || invariant.events.length === 0)
@@ -1007,6 +1033,103 @@ function shortestViolationForInvariant(model, options, invariant) {
     }
     return undefined;
 }
+/**
+ * Whether an invariant asserts a property of whole runs rather than of a single
+ * runtime state. These kinds cannot be decided by a state predicate, so they are not
+ * part of `shortestViolationForInvariant` (and therefore not of S7), which owns the
+ * states; A9-A13 own the verdicts, and `pathPropertyViolation` below makes the same
+ * verdicts available to A7 and D2.
+ */
+function isPathPropertyInvariant(invariant) {
+    return invariant.kind === 'leads-to'
+        || invariant.kind === 'sequence'
+        || invariant.kind === 'atomicity'
+        || invariant.kind === 'budget'
+        || invariant.kind === 'probability';
+}
+/** Whether a probability invariant's bound fails for the computed hit probability. */
+function probabilityViolated(invariant, probability) {
+    const eps = 1e-9;
+    if (invariant.op === '>=')
+        return probability < invariant.p - eps;
+    if (invariant.op === '>')
+        return probability <= invariant.p + eps;
+    if (invariant.op === '<=')
+        return probability > invariant.p + eps;
+    return probability >= invariant.p - eps;
+}
+/** Every runtime state reachable from init, capped like the other searches. */
+function reachableRuntimeStates(model, options) {
+    const init = initialState(model);
+    const visited = new Set([runtimeKey(init)]);
+    const reached = [init];
+    const queue = [init];
+    let steps = 0;
+    while (queue.length > 0) {
+        if (++steps > options.maxStates)
+            break;
+        const current = queue.shift();
+        for (const event of allEvents(model)) {
+            for (const next of stepRuntime(model, current, event)) {
+                const key = runtimeKey(next);
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                reached.push(next);
+                queue.push(next);
+            }
+        }
+    }
+    return reached;
+}
+/**
+ * Violation of a path-property invariant, or undefined when it holds. Each kind
+ * delegates to the search its dedicated probe uses (A9 leads-to, A10 sequence, A11
+ * atomicity, A12 budget, A13 probability), so a verdict reported here can never
+ * disagree with the probe that owns the kind.
+ */
+function pathPropertyViolation(model, options, invariant) {
+    if (invariant.kind === 'leads-to') {
+        const targets = new Set(leadsToTargets(invariant));
+        const label = leadsToTargetLabel(invariant);
+        for (const runtime of reachableRuntimeStates(model, options)) {
+            if (runtime.state !== invariant.from)
+                continue;
+            const bad = findLeadsToBadPath(model, runtime, targets, label);
+            if (bad !== undefined)
+                return { invariant, path: bad.path, reason: bad.reason };
+        }
+        return undefined;
+    }
+    if (invariant.kind === 'sequence')
+        return findSequenceViolation(model, options, invariant);
+    if (invariant.kind === 'atomicity')
+        return findAtomicityViolation(model, options, invariant);
+    if (invariant.kind === 'budget') {
+        const violation = findBudgetViolation(model, options, invariant);
+        if (violation === undefined)
+            return undefined;
+        return {
+            invariant,
+            path: violation.path,
+            reason: violation.unbounded
+                ? 'a reachable cycle keeps accumulating cost, so no finite budget holds'
+                : 'a run accumulates cost ' + String(violation.cost) + ', above the declared budget ' + String(invariant.budget),
+        };
+    }
+    if (invariant.kind === 'probability') {
+        const { probability, converged } = computeHitProbability(model, options, invariant.target);
+        if (!probabilityViolated(invariant, probability))
+            return undefined;
+        return {
+            invariant,
+            path: [],
+            reason: 'P(hit ' + invariant.target + ') = ' + probability.toFixed(6) + ' does not satisfy ' + invariant.op + ' ' + String(invariant.p)
+                + (converged ? '' : ' (value iteration did not converge)'),
+        };
+    }
+    return undefined;
+}
 function shortestEventBeforeStateViolation(model, options, invariant) {
     const init = initialState(model);
     const seenInitially = false;
@@ -1038,10 +1161,12 @@ function shortestEventBeforeStateViolation(model, options, invariant) {
     }
     return undefined;
 }
-function runInvariants(model, options) {
+function runInvariants(model, options, includePathProperties = false) {
     const violations = [];
     for (const invariant of model.invariants ?? []) {
-        const violation = shortestViolationForInvariant(model, options, invariant);
+        const violation = includePathProperties && isPathPropertyInvariant(invariant)
+            ? pathPropertyViolation(model, options, invariant)
+            : shortestViolationForInvariant(model, options, invariant);
         if (violation !== undefined)
             violations.push(violation);
     }
@@ -1415,14 +1540,27 @@ function A6_resourceInjection(model) {
     return checkResult('A6', 'Resource Injection', findings, findings.length === 0 ? 'No resource vulnerabilities detected' : 'Resource failure paths missing: ' + findings.length);
 }
 function A7_shortestViolations(model, options) {
-    const violations = runInvariants(model, options);
-    const findings = violations.map((violation) => ({
-        code: 'A7_SHORTEST_COUNTEREXAMPLE',
-        severity: 'warning',
-        message: 'Invariant "' + violation.invariant.id + '" shortest violating path length: ' + violation.path.length + (violation.path.length === 0 ? ' (initial state)' : ''),
-        path: violation.path,
-        evidence: { invariant: violation.invariant.id },
-    }));
+    // Path-property invariants are included: "for any invariant that fails" is this
+    // check's contract, and a check that silently skips five of the eight kinds cannot
+    // honour it. The searches for the state kinds, for sequence, atomicity and budget
+    // are breadth-first, so their first witness is the shortest one; the leads-to walk
+    // and the probability bound have no such guarantee, and their message says what it
+    // found instead of claiming minimality.
+    const violations = runInvariants(model, options, true);
+    const findings = violations.map((violation) => {
+        const pathLength = violation.path.length;
+        const message = isPathPropertyInvariant(violation.invariant)
+            ? 'Invariant "' + violation.invariant.id + '" violated: ' + violation.reason
+                + (pathLength === 0 ? '' : ' (witness path length: ' + pathLength + ')')
+            : 'Invariant "' + violation.invariant.id + '" shortest violating path length: ' + pathLength + (pathLength === 0 ? ' (initial state)' : '');
+        return {
+            code: 'A7_SHORTEST_COUNTEREXAMPLE',
+            severity: 'warning',
+            message,
+            path: violation.path,
+            evidence: { invariant: violation.invariant.id },
+        };
+    });
     return checkResult('A7', 'Minimal Counter-Example', findings, violations.length === 0 ? 'All invariants hold for all reachable paths' : 'Violated invariants: ' + findings.length);
 }
 function mapStateId(mapping, state) {
@@ -1500,6 +1638,25 @@ function mapInvariantForComparison(invariant, mapping) {
         }
         return mapped;
     }
+    if (invariant.kind === 'leads-to') {
+        // A target set maps member by member; a rename that drops a state is reported by
+        // D2's own mapped-state check rather than silently changing the property.
+        return {
+            ...invariant,
+            id: invariant.id + ':before',
+            description: invariant.description + ' (from BEFORE)',
+            from: mapStateId(mapping, invariant.from),
+            to: typeof invariant.to === 'string' ? mapStateId(mapping, invariant.to) : invariant.to.map((state) => mapStateId(mapping, state)),
+        };
+    }
+    if (invariant.kind === 'probability') {
+        return {
+            ...invariant,
+            id: invariant.id + ':before',
+            description: invariant.description + ' (from BEFORE)',
+            target: mapStateId(mapping, invariant.target),
+        };
+    }
     return { ...invariant, id: invariant.id + ':before', description: invariant.description + ' (from BEFORE)' };
 }
 function D2_invariantContinuity(before, after, options, mapping) {
@@ -1541,7 +1698,37 @@ function D2_invariantContinuity(before, after, options, mapping) {
                 continue;
             }
         }
-        const violation = shortestViolationForInvariant(after, options, mapped);
+        else if (mapped.kind === 'leads-to') {
+            // The state references of a path-property invariant must follow stateMapping too,
+            // otherwise a pure rename searches for a state AFTER does not declare.
+            for (const state of [mapped.from, ...leadsToTargets(mapped)]) {
+                if (!afterStates.has(state)) {
+                    findings.push({
+                        code: 'D2_MAPPED_STATE_MISSING',
+                        severity: 'warning',
+                        message: 'BEFORE invariant "' + invariant.id + '" maps to state ' + state + ', which is not declared in AFTER.',
+                        evidence: { invariant: invariant.id, state },
+                    });
+                }
+            }
+        }
+        else if (mapped.kind === 'probability') {
+            if (!afterStates.has(mapped.target)) {
+                findings.push({
+                    code: 'D2_MAPPED_STATE_MISSING',
+                    severity: 'warning',
+                    message: 'BEFORE invariant "' + invariant.id + '" maps to state ' + mapped.target + ', which is not declared in AFTER.',
+                    evidence: { invariant: invariant.id, state: mapped.target },
+                });
+            }
+        }
+        // Every invariant the engine can decide is re-decided against AFTER. Path-property
+        // kinds go through the same searches their dedicated probes use, so D2 can no
+        // longer report "all BEFORE invariants continue to hold" while A9-A13 fail on the
+        // very same model.
+        const violation = isPathPropertyInvariant(mapped)
+            ? pathPropertyViolation(after, options, mapped)
+            : shortestViolationForInvariant(after, options, mapped);
         if (violation !== undefined) {
             findings.push({
                 code: 'D2_INVARIANT_REGRESSION',
@@ -1722,15 +1909,27 @@ function S8_monotonicVariables(model) {
     return checkResult('S8', 'Monotonic Variables', findings, findings.length === 0 ? 'Monotonic variables are respected' : 'Monotonic findings: ' + findings.length);
 }
 /**
- * Find a run from `start` that never reaches `target`, or return undefined when
- * every run does. The property is universal (see the A9 row in `SKILL.md`): one
- * branch that loops forever, or that stops before the target, refutes it.
+ * Target states of a `leads-to` invariant. The schema accepts one state id or a
+ * non-empty array of them, so "reach any of these" needs no separate invariant kind.
+ */
+function leadsToTargets(invariant) {
+    return typeof invariant.to === 'string' ? [invariant.to] : invariant.to;
+}
+/** Target list as findings print it. A single target renders as its bare id, so existing messages stay byte-identical. */
+function leadsToTargetLabel(invariant) {
+    return leadsToTargets(invariant).join(', ');
+}
+/**
+ * Find a run from `start` that reaches none of `targets`, or return undefined when
+ * every run reaches at least one of them. The property is universal (see the A9 row
+ * in `SKILL.md`): one branch that loops forever, or that stops before any target,
+ * refutes it.
  *
- * The search is a depth-first walk of the run graph with three colours, and target
- * runs are success leaves that are never expanded:
+ * The search is a depth-first walk of the run graph with three colours, and runs at a
+ * target are success leaves that are never expanded:
  *
  * - a node reached while it is on the current walk (GRAY) closes a cycle that avoids
- *   the target, so some run never reaches it;
+ *   every target, so some run never reaches one;
  * - a node with no outgoing step at all stops the machine where it stands, which is
  *   the same violation for a different reason;
  * - a node whose walk completed without a violation is BLACK, and reaching it again
@@ -1741,8 +1940,8 @@ function S8_monotonicVariables(model) {
  * A run is identified by its state plus its variable values, so the same state id
  * with different values is a different node.
  */
-function findLeadsToBadPath(model, start, target) {
-    if (start.state === target)
+function findLeadsToBadPath(model, start, targets, label) {
+    if (targets.has(start.state))
         return undefined;
     const GRAY = 1;
     const BLACK = 2;
@@ -1759,7 +1958,7 @@ function findLeadsToBadPath(model, start, target) {
             }
             frame.nexts = nexts;
             if (nexts.length === 0)
-                return { path: frame.path, reason: 'Dead end before target ' + target };
+                return { path: frame.path, reason: 'Dead end before target ' + label };
         }
         if (frame.index >= frame.nexts.length) {
             color.set(runtimeKey(frame.runtime), BLACK);
@@ -1769,18 +1968,18 @@ function findLeadsToBadPath(model, start, target) {
         const { next, event } = frame.nexts[frame.index];
         frame.index += 1;
         const step = { from: frame.runtime.state, event, to: next.state };
-        if (next.state === target)
+        if (targets.has(next.state))
             continue;
         const key = runtimeKey(next);
         const seen = color.get(key);
         if (seen === GRAY)
-            return { path: [...frame.path, step], reason: 'Cycle avoids target ' + target };
+            return { path: [...frame.path, step], reason: 'Cycle avoids target ' + label };
         if (seen === BLACK)
             continue;
         color.set(key, GRAY);
         stack.push({ runtime: next, path: [...frame.path, step], nexts: undefined, index: 0 });
     }
-    // Every branch either reached the target or rejoined a branch that did.
+    // Every branch either reached a target or rejoined a branch that did.
     return undefined;
 }
 function A9_leadsTo(model, exploration) {
@@ -1788,10 +1987,12 @@ function A9_leadsTo(model, exploration) {
     for (const invariant of model.invariants ?? []) {
         if (invariant.kind !== 'leads-to')
             continue;
+        const targets = new Set(leadsToTargets(invariant));
+        const label = leadsToTargetLabel(invariant);
         for (const runtime of exploration.reachable) {
             if (runtime.state !== invariant.from)
                 continue;
-            const bad = findLeadsToBadPath(model, runtime, invariant.to);
+            const bad = findLeadsToBadPath(model, runtime, targets, label);
             if (bad !== undefined) {
                 findings.push({
                     code: 'A9_LEADS_TO_VIOLATION',
@@ -2199,21 +2400,11 @@ function computeHitProbability(model, options, targetState) {
 }
 function A13_probability(model, options) {
     const findings = [];
-    const eps = 1e-9;
     for (const invariant of model.invariants ?? []) {
         if (invariant.kind !== 'probability')
             continue;
         const { probability, converged } = computeHitProbability(model, options, invariant.target);
-        let violated = false;
-        if (invariant.op === '>=')
-            violated = probability < invariant.p - eps;
-        else if (invariant.op === '>')
-            violated = probability <= invariant.p + eps;
-        else if (invariant.op === '<=')
-            violated = probability > invariant.p + eps;
-        else
-            violated = probability >= invariant.p - eps;
-        if (violated) {
+        if (probabilityViolated(invariant, probability)) {
             findings.push({
                 code: 'A13_PROBABILITY_VIOLATION',
                 severity: 'error',

package/lib/index.js

@@ -49,7 +49,7 @@ const GATE_SOURCE_KIND = 'plugin:logicprobe';
 const DEFAULT_GATE_CONTENT = `<EXTREMELY_IMPORTANT>
 Plugin logicprobe is active. Documents are not truth — code is. Verify every verifiable claim before accepting or acting on any design.
 
-**1% Rule**: If there is even a 1% chance the logicprobe skill applies — reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, mechanism feasibility, state machines, protocol logic, data models, schema migrations, data invariants, or behavioral guarantees ("always"/"never"/"guaranteed") — load it with the skill tool before responding. The cost of loading is trivial compared to the cost of a false claim.
+**1% Rule**: If there is even a 1% chance the logicprobe skill applies — reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, mechanism feasibility, state machines, protocol logic, data models, schema migrations, data invariants, behavioral guarantees ("always"/"never"/"guaranteed"), worst-case path cost or declared budgets, probabilistic reachability ("≥90% of runs reach SAFE"), deadlines ("must leave within 2 ticks"), cross-machine handshakes, or concurrency guarantees ("thread-safe"/"lock-free"/"ISR-safe") — load it with the skill tool before responding. The cost of loading is trivial compared to the cost of a false claim.
 
 **Red Flags** — if you think any of these, STOP. You are rationalizing:
 
@@ -60,7 +60,16 @@ Plugin logicprobe is active. Documents are not truth — code is. Verify every v
 | "I'll verify while implementing" | Verification happens before implementation, not during. |
 | "I can check this with reasoning alone" | Behavioral claims are verified with code/models, not intuition. One counter-example refutes a universal claim. |
 
-**Native verification path**: In dsh, prefer the \`logicprobe_verify\` tool for state-machine checks and \`logicprobe_datamodel_verify\` for data-model/schema migration checks. Both support before/after regression and common domain constraints (idempotency, monotonic, sequence, leads-to, atomicity). To model a code flow as UML, or to audit such a modelling, use \`logicprobe_uml\` (render | parse | review). Python harnesses remain the fallback for non-dsh hosts.
+**Native verification path** (dsh) — six model-invocable tools:
+
+- \`logicprobe_verify\` — state machines: S1-S8 structural + A1-A14 adversarial, including A12 worst-case path cost against a declared \`budget\`, A13 probabilistic reachability over a DTMC, and A14 discrete-tick deadlines. Pass \`beforeModel\` + \`stateMapping\` to add the D1-D4 before/after regression.
+- \`logicprobe_datamodel_verify\` — data models and schema migrations: DS/DA checks, migration coverage, copy consistency, rollback symmetry, DD1-DD4 data regression.
+- \`logicprobe_compose_verify\` — two or more machines checked together (rendezvous handshake semantics): C1 composition deadlock, C2 rendezvous that never fires.
+- \`logicprobe_concurrency_scan\` — mine concurrency claims (thread-safe, lock-free, race condition, mutex, ISR-safe) and route them to dedicated verification; logicprobe does not prove concurrency safety.
+- \`logicprobe_export\` — emit external-checker input from a verified model: UPPAAL, TLA+, PRISM, SPIN.
+- \`logicprobe_uml\` — model a code flow as UML (render), read a diagram back into a model (parse), or audit the modelling (review: UML001-UML019 structural defects, documentation gaps, diagram-versus-model round-trip fidelity).
+
+Python harnesses in the skill references remain the fallback for non-dsh hosts.
 
 **Proactive suggestion**: When a user asks code-level behavioral questions — "could this state machine deadlock", "is this retry limit safe", "check this timing sequence for bugs", "is this migration non-breaking", "does this copy cover all required fields" — suggest logicprobe as an optional verification pass (do not auto-escalate).
 </EXTREMELY_IMPORTANT>`;
@@ -146,7 +155,7 @@ function resolveInteraction(config, session) {
 function modeContextText(config, session) {
     const interaction = resolveInteraction(config, session);
     const lines = [
-        'logicprobe: use `logicprobe_verify` for state machines and `logicprobe_datamodel_verify` for data models; both cover before/after regression and common domain constraints.',
+        'logicprobe: native tools — `logicprobe_verify` (state machines: S1-S8 + A1-A14, incl. A12 budget/worst-case path cost, A13 probabilistic reachability, A14 deadlines; `beforeModel` adds D1-D4 regression), `logicprobe_datamodel_verify` (data models and schema migrations: DS/DA, migration coverage, copy consistency, rollback symmetry, DD1-DD4), `logicprobe_compose_verify` (two or more machines: C1 composition deadlock, C2 rendezvous never fires), `logicprobe_concurrency_scan` (mine concurrency claims — it does not prove concurrency safety), `logicprobe_export` (UPPAAL, TLA+, PRISM, SPIN input from a verified model).',
         'logicprobe: use `logicprobe_uml` to model a code flow as UML (render), to read a UML diagram back into a model (parse), or to audit the modelling (review: structural defects, documentation gaps, diagram-vs-model round-trip fidelity).',
         interaction === 'auto'
             ? 'logicprobe interaction=auto: do NOT call ask_user_question for model confirmation; run round-trip validation of the extracted transition table and mark the result UNCONFIRMED.'

package/lib/tool.js

@@ -12,7 +12,7 @@ export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify';
  */
 export const logicProbeVerifyTool = defineTool({
     name: LOGICPROBE_VERIFY_TOOL_NAME,
-    description: 'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?, cost?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?, narrative?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range ({variable, min?, max?, when?} — when scopes the range to a state ({state}) or a guard node, is evaluated on the post-state of every transition, leaves the initial state checked unconditionally, and is rejected on any other invariant kind), event-before-state, leads-to, sequence, atomicity, budget (transition cost defaults to 1; A12 checks every reachable path stays within the declared budget and reports the shortest over-budget counterexample), and probability (transition weight, default 1, makes the model a DTMC; A13 checks P(hit target) against the bound by value iteration). The schema is closed: an undeclared key on any model part (model, state, transition, update, variable, invariant, boundaryCheck, resourcePair, narrative, scenario) is a validation error, never ignored. Variables support monotonic inc/dec. The optional narrative block carries natural-language descriptions of states (narrative.states), events (narrative.events), and (state, event) scenarios (narrative.scenarios: [{from, event, scenario}]); when present it must fully cover the model and is echoed in the report. Returns a report with S1-S8 structural checks and A1-A13 adversarial/probability probes including shortest counterexample paths. If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
+    description: 'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?, cost?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?, narrative?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range ({variable, min?, max?, when?} — when scopes the range to a state ({state}) or a guard node, is evaluated on the post-state of every transition, leaves the initial state checked unconditionally, and is rejected on any other invariant kind), event-before-state, leads-to (`to` is one state id or a non-empty array of them: every path must reach at least one member), sequence, atomicity, budget (transition cost defaults to 1; A12 checks every reachable path stays within the declared budget and reports the shortest over-budget counterexample), and probability (transition weight, default 1, makes the model a DTMC; A13 checks P(hit target) against the bound by value iteration), and deadline (declaring maxTicks on a state is how many tick steps it may stay resident and the top-level tickEvents list names those steps; A14 reports the over-residency path, and A14_NO_TICK_EVENTS when maxTicks is declared without tickEvents). The schema is closed: an undeclared key on any model part (model, state, transition, update, variable, invariant, boundaryCheck, resourcePair, narrative, scenario) is a validation error, never ignored. Variables support monotonic inc/dec. The optional narrative block carries natural-language descriptions of states (narrative.states), events (narrative.events), and (state, event) scenarios (narrative.scenarios: [{from, event, scenario}]); when present it must fully cover the model and is echoed in the report. Returns a report with S1-S8 structural checks and A1-A14 adversarial, cost, probability and deadline probes, including counterexample paths (shortest where the search is breadth-first). If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
     parameters: {
         model: {
             type: 'json',

package/lib/types/engine.d.ts

@@ -110,7 +110,7 @@ export type InvariantSpec = {
     description: string;
     kind: 'leads-to';
     from: string;
-    to: string;
+    to: string | string[];
 } | {
     id: string;
     description: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-logicprobe",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Design document & plan claim verification — enumerate claims, verify against codebase facts, then escalate to state-machine verification (S1-S8/A1-A12, including budget/worst-case path-cost checks) and data-model verification (DS/DA/DD) for behavioral claims. Supports before/after regression, idempotency/monotonic/sequence/leads-to/atomicity constraints, and concurrency risk mining. Ships a native DeepSeek Harness (dsh) bundle that injects the claim-verification gate into the first model step.",
   "type": "module",
   "main": "lib/index.js",

package/skills/logicprobe/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: logicprobe
-description: "Use when reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, or mechanism feasibility. When the document contains state machines, protocol logic, or behavioral claims (≥3 states, ACK/NACK/retry sequences, 'always'/'never'/'guaranteed' assertions, or refactoring that modifies state topology), escalate into logic-primitive verification — generate and run executable models to check mathematical completeness before trusting any claim. For refactoring specifically, the pipeline compares before/after models to verify behavioral preservation and regression freedom. ALSO use when the task is to model a code flow as UML, or to audit a diagram somebody drew. That covers reverse-engineering a handler and documenting a protocol. The skill renders the model as a state, activity or sequence diagram, reads a hand-drawn diagram back into a model, and reviews the modelling: unreachable states, dead ends, ambiguous branches, documentation gaps, and diagram-versus-model fidelity. ALSO proactively SUGGEST this skill (do not require) when a user asks code-level behavioral questions — 'check this timing for bugs', 'could this state machine deadlock', 'is this retry limit safe' — since plan-level verification has usually already been done."
+description: "Use when reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, or mechanism feasibility. Escalate into logic-primitive verification — generate and run an executable model before trusting the claim — when the document asserts state-machine or protocol behaviour (≥3 states, ACK/NACK/retry sequences, guards, lock/unlock pairing), a quantitative or temporal guarantee (worst-case path cost ≤ budget, P(reach SAFE) ≥ p, 'must leave within 2 ticks'), a cross-machine handshake (req/ack, power-up sequencing between two components), concurrency guarantees ('thread-safe', 'lock-free', 'ISR-safe' — mined and routed, never proven here), or a refactoring that changes state topology or guard conditions, where the pipeline compares before/after models for behavioral preservation and regression freedom. ALSO use when the task is to model a code flow as UML, or to audit a diagram somebody drew: the skill renders the model as a state, activity or sequence diagram, reads a hand-drawn diagram back into a model, and reviews the modelling — unreachable states, dead ends, ambiguous branches, documentation gaps, diagram-versus-model round-trip fidelity. Data-model, schema and migration claims belong to the sibling logicprobe-datamodel skill. ALSO proactively SUGGEST this skill (do not require) when a user asks code-level behavioral questions — 'check this timing for bugs', 'could this state machine deadlock', 'is this retry limit safe' — since plan-level verification has usually already been done."
 ---
 
 # Logic Probe
@@ -147,6 +147,19 @@ UML modelling variant (the task is to draw a flow, not to check a claim):
     → logicprobe_verify → the behavioural checks (S1-S8 / A1-A14)
 ```
 
+### Native dsh Tools
+
+| Tool | Covers |
+|------|--------|
+| `logicprobe_verify` | S1-S8 structural + A1-A14 adversarial, including A12 budget / worst-case path cost, A13 probabilistic reachability over a DTMC, and A14 discrete-tick deadlines. `beforeModel` + `stateMapping` add the D1-D4 before/after regression. |
+| `logicprobe_datamodel_verify` | Data models and schema migrations: DS/DA checks plus the DD1-DD4 data regression. See the `logicprobe-datamodel` skill. |
+| `logicprobe_compose_verify` | Two or more machines checked together (rendezvous handshake semantics): C1 composition deadlock, C2 rendezvous never fires. |
+| `logicprobe_concurrency_scan` | Mines concurrency claims (thread-safe, lock-free, race condition, mutex, ISR-safe) and routes them to dedicated verification. It does not prove concurrency safety. |
+| `logicprobe_export` | Emits external-checker input from a verified model: UPPAAL, TLA+, PRISM, SPIN. |
+| `logicprobe_uml` | render / parse / review for UML modelling — see [UML Modelling and Modelling Review](#uml-modelling-and-modelling-review). |
+
+`references/logicprobe-engine.py` mirrors the same checks and carries `compose` and `export` subcommands for hosts without the native tools.
+
 ### Refactoring Verification Mode
 
 When the document under review is a refactoring plan (modifying existing state machine logic, not designing from scratch), adapt the pipeline:
@@ -206,9 +219,9 @@ Run these SECOND. Each probe actively tries to BREAK the model. If any probe suc
 | A4 | **Pair symmetry** | Match every `start/stop`, `lock/unlock`, `alloc/free` pair. Flag if any state allows a path where a pair is unbalanced (start without stop, lock without unlock). State `onEntry`/`onExit` actions are treated as implicit acquire/release. | "Resources are always released" |
 | A5 | **Boundary blast** | Probe counters at 0, 1, max-1, max, max+1. Probe timestamps at 0, tick_wraparound. Flag overflow, underflow, or undefined behavior. | "Handles all counter/timer values" |
 | A6 | **Resource injection** | Simulate `malloc→NULL`, `queue→full`, `semaphore→timeout` at each state that calls them. Flag if any state has no recovery path. | "Graceful degradation under resource pressure" |
-| A7 | **Minimal counter-example** | For any invariant that fails, find the SHORTEST event sequence that violates it (BFS from init to violating state). Output the exact path. | "This invariant holds" → refuted by shortest path |
+| A7 | **Counter-example witness** | For any invariant that fails, find the event sequence that violates it and output the exact path. Breadth-first searches (state predicates, sequence, atomicity, budget) yield the shortest witness; the leads-to walk and the probability bound report the witness they found without claiming minimality. | "This invariant holds" → refuted by a concrete path |
 | A8 | **Idempotent replay** | For each event declared in `idempotentEvents`, apply it twice from every reachable state. Flag if the second application changes state or is not replayable. | "This event is safe to retry/replay" |
-| A9 | **Leads-to** | From a declared source state, every path must eventually reach the target state. | "This state always progresses to completion" |
+| A9 | **Leads-to** | From a declared source state, every path must eventually reach the target state, or reach one member of a declared target set. | "This state always progresses to completion" |
 | A10 | **Sequence order** | Events declared in a sequence must occur in the specified order. | "backup before modify before commit" |
 | A11 | **Atomicity** | Once an atomic event starts, the machine must commit or roll back before leaving the scope or terminating. | "all-or-nothing transaction" |
 | A12 | **Budget (worst-case path cost)** | With `cost` on transitions (absent = 1) and a `budget` invariant, every reachable path must stay within budget; reports the shortest over-budget counterexample and flags reachable positive-cost cycles as unbounded. | "Worst-case path cost ≤ budget" |

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

@@ -68,7 +68,8 @@ The same reasoning applies to every id a check names. A reference to a state, ev
 | `transitions[].guard` variables | a declared variable |
 | `resourcePairs[].acquireEvent` / `.releaseEvent` / `.failEvent` | a declared event |
 | `invariants[].event` (`event-before-state`) | a declared event |
-| `invariants[].state` / `.states[]` / `.from` / `.to` / `.target` / `.when.state` | a declared state |
+| `invariants[].state` / `.states[]` / `.from` / `.target` / `.when.state` | a declared state |
+| `invariants[].to` and every member of `invariants[].to[]` (`leads-to`) | a declared state |
 
 A vacuous check is worse than a rejected one: a `leads-to` invariant whose `to` state is misspelled can never be violated, and a `never-states` list holding a nonexistent id can never be reached, so both report "pass" for a model that was never actually checked.
 
@@ -162,13 +163,13 @@ A guard is exactly one of:
 | `never-states` | `{ states: ["ERROR"] }` | No reachable runtime state may be in the forbidden set |
 | `var-in-range` | `{ variable, min?, max?, when? }` | Every reachable runtime state selected by `when` keeps the variable in range (at least one of `min`/`max` is required) |
 | `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` |
+| `leads-to` | `{ from: "MIGRATING", to: "DONE" }`, or `to: ["DONE", "FAILED"]` | Every path from `from` must eventually reach `to`. With a target set, every path must reach at least one member. The set must be non-empty and free of duplicates |
 | `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.
+A7 reports a violating path for each failed invariant, and an empty path means the initial state already violates it. The state-predicate kinds, `sequence`, `atomicity` and `budget` are breadth-first, so their witness is the shortest one; `leads-to` and `probability` report a witness without claiming minimality.
 
 ### Scoping a range to a state (`when`)
 
@@ -281,7 +282,7 @@ When `beforeModel` is passed to `logicprobe_verify`, the engine treats `model` a
 | 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 |
+| D2 Invariant Continuity | Every BEFORE invariant (mapped through `stateMapping`) must still hold in AFTER. State predicates go through the same reachability search as S7; `leads-to`, `sequence`, `atomicity`, `budget` and `probability` are re-decided by the searches their own probes (A9-A13) use |
 | D3 Regression Delta | Lists added/removed states, events, and transitions |
 | D4 Deadlock/Liveness Regression | New deadlock states or closed SCCs not present in BEFORE |
 
@@ -306,7 +307,7 @@ List events that must be idempotent in `idempotentEvents`. For every reachable s
 ## 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`.
+- **A9 Leads-To**: `{ kind: "leads-to", from, to }` — every path from `from` must eventually reach `to`. `to` is one state id or a non-empty array of state ids for "reach any one of these"; a duplicated member is a validation error rather than a shorthand. Either way the property stays universal: one branch that loops forever, or that stops before every target, refutes it.
 - **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.

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

@@ -271,6 +271,8 @@ def shortest_violating_path(states, init, invariant_check):
     return None  # Invariant holds for all reachable states
 ```
 
+That template decides one runtime state at a time, so it only fits the state-predicate kinds. A `leads-to`, `sequence`, `atomicity`, `budget` or `probability` invariant asserts a property of a whole run: reuse the search in its own section (A9-A13) as the witness finder, or A7 will report "all invariants hold" for a model where one of them fails.
+
 ### S8: Monotonic Variables
 
 For counters or progress variables that must only move in one direction, list the events that increase/decrease them. Any event that moves against the declared direction is a finding.
@@ -291,11 +293,13 @@ IDEMPOTENT_EVENTS = {"retry", "sync", "webhook_delivery"}
 
 ### A9: Leads-To
 
-For progress claims ("from MIGRATING, eventually DONE"), check every path from the source state. If a path dead-ends or loops before reaching the target, flag it.
+For progress claims ("from MIGRATING, eventually DONE"), check every path from the source state. If a path dead-ends or loops before reaching the target, flag it. When the code has several acceptable outcomes, give the invariant a target set and check every path reaches at least one member; that is still a universal claim, so a branch that reaches none of them fails.
 
 ```python
 LEADS_TO = [
     ("MIGRATING", "DONE"),
+    # or a set of acceptable outcomes
+    ("DRAINING", ["IDLE", "FAULT"]),
 ]
 ```
 
@@ -438,7 +442,7 @@ The BEFORE model comes from **code, not the plan**. The plan may describe the cu
 
 **Behavioral preservation**: For each event sequence accepted by BEFORE, trace the same sequence in AFTER. If AFTER ends in a different state (or rejects the sequence), flag as BEHAVIORAL DELTA. The plan must explicitly document this delta — if it doesn't, it's a regression.
 
-**Invariant continuity**: Re-run S7 invariant checks on both models. Any invariant that passes on BEFORE but fails on AFTER is a regression — the refactoring broke an existing guarantee.
+**Invariant continuity**: Re-decide every invariant on AFTER, mapped through `stateMapping`. Any invariant that holds on BEFORE but fails on AFTER is a regression — the refactoring broke an existing guarantee. State predicates go through the same reachability search as S7; `leads-to`, `sequence`, `atomicity`, `budget` and `probability` are re-decided by the searches their own probes (A9-A13) use, so continuity agrees with the standalone verdict. A state reference that the mapping drops is reported as a mapped-state warning instead of silently changing the property.
 
 **Complexity delta**: Count objectively:
 
@@ -507,7 +511,7 @@ Manual verification is reliable for state machines with **≤ 10 states and ≤
 
 **A6 Resource Injection**: For each state that appears to allocate (names containing "alloc", "init", "start", "open", "connect", "begin"), check if there is a recovery/error path if the allocation fails. If no recovery exists, flag as RESOURCE VULNERABLE.
 
-**A7 Minimal Counter-Example**: For each invariant that failed in S7, find the SHORTEST event sequence that violates it. This is the most useful output — it gives the plan author an exact repro.
+**A7 Minimal Counter-Example**: For each invariant that failed, find the event sequence that violates it. This is the most useful output — it gives the plan author an exact repro. The searches for state predicates, `sequence`, `atomicity` and `budget` are breadth-first, so their witness is the shortest one; the `leads-to` walk and the `probability` bound report what they found without claiming minimality.
 
 ### Manual Mode Output Format