dsh-logicprobe 0.5.6 → 0.6.0

package/lib/types/engine.d.ts

@@ -19,6 +19,12 @@ export type GuardNode = LeafGuard | AllGuard | AnyGuard | NotGuard;
 export interface StateSpec {
     id: string;
     terminal?: boolean;
+    /** Actions fired automatically when the state is entered. They do not change state or variables; checks such as A4 Pair Symmetry treat them as implicit acquire/release events so lock/unlock hidden inside entry actions is verified. */
+    onEntry?: string[];
+    /** Actions fired automatically when the state is left. Same semantics as onEntry. */
+    onExit?: string[];
+    /** Deadline (A14): the state must be left within this many declared tick events of entering it. */
+    maxTicks?: number;
 }
 export interface UpdateSpec {
     variable: string;
@@ -32,6 +38,10 @@ export interface TransitionSpec {
     /** Absent guard is the else/default branch for the same (from, event) group. */
     guard?: GuardNode;
     updates?: UpdateSpec[];
+    /** Execution cost of firing this transition (e.g. cycles, microseconds). Absent cost defaults to 1, so an unannotated machine keeps step-count semantics. Checked by A12 against budget invariants. */
+    cost?: number;
+    /** Relative probability weight when a probability invariant is declared (DTMC interpretation). Absent weight = 1; weight 0 means the branch never fires probabilistically. */
+    weight?: number;
 }
 export interface TransitionScenarioSpec {
     from: string;
@@ -91,6 +101,18 @@ export type InvariantSpec = {
     events: string[];
     commit: string;
     rollback?: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'budget';
+    budget: number;
+} | {
+    id: string;
+    description: string;
+    kind: 'probability';
+    target: string;
+    op: '>=' | '<=' | '>' | '<';
+    p: number;
 };
 export interface ResourcePairSpec {
     resource: string;
@@ -113,6 +135,8 @@ export interface LogicModelV1 {
     boundaryChecks?: BoundaryCheckSpec[];
     resourcePairs?: ResourcePairSpec[];
     idempotentEvents?: string[];
+    /** Events that advance the discrete clock by one tick; used by A14 deadline checks. */
+    tickEvents?: string[];
     /** Natural-language descriptions of states, events, and (state, event) scenarios. */
     narrative?: ModelNarrative;
 }
@@ -157,6 +181,9 @@ export interface VerificationReport {
     };
     checks: CheckResult[];
     comparison?: ComparisonSummary;
+    /** Informational notes about semantic dimensions this model references (timing, preemption)
+     * that this engine does not verify. Heuristic, vocabulary-based — never a substitute for the checks. */
+    coverageNotes?: string[];
 }
 export interface ComparisonSummary {
     beforeModelHash: string;
@@ -187,3 +214,42 @@ export declare function validateModel(input: unknown): {
 };
 export declare function guardVariables(guard: GuardNode | undefined): string[];
 export declare function runVerification(input: unknown, options?: VerificationOptions): VerificationReport;
+export interface CompositionStep {
+    event: string;
+    /** Indices of the machines that advanced together on this step. */
+    machines: number[];
+}
+export interface CompositionOptions {
+    /** Events that require a synchronized multi-machine step (handshake). */
+    rendezvous?: string[];
+    maxStates?: number;
+}
+export interface CompositionSummary {
+    machineCount: number;
+    machines: Array<{
+        modelHash: string;
+        states: number;
+        transitions: number;
+    }>;
+    compositeStates: number;
+    errors: number;
+    warnings: number;
+    truncated: boolean;
+}
+export interface CompositionReport {
+    ok: boolean;
+    summary: CompositionSummary;
+    checks: CheckResult[];
+}
+/**
+ * N-machine composition semantics (documented in dsh-model-schema.md):
+ * - a non-rendezvous event advances exactly ONE non-terminal machine that fires it;
+ * - a rendezvous event (handshake) fires only when AT LEAST TWO machines declare it in
+ *   their alphabet and EVERY such non-terminal machine has it enabled (guards held);
+ *   all participants then advance simultaneously. A machine that is terminal, or whose
+ *   alphabet does not include the event, does not participate;
+ * - a terminal machine is stopped and takes no further part.
+ * Checks: C1 composition deadlock (reachable node where no machine can advance while at
+ * least one is not terminal) and C2 rendezvous that can never fire.
+ */
+export declare function runCompositionVerification(machinesInput: unknown[], options?: CompositionOptions): CompositionReport;

package/lib/types/export-tool.d.ts

@@ -0,0 +1,7 @@
+export declare const LOGICPROBE_EXPORT_TOOL_NAME = "logicprobe_export";
+/**
+ * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
+ * native input for the tool logicprobe routes to (UPPAAL / TLA+ / PRISM / SPIN).
+ * v1 translates the core machine; unrepresentable invariants become warnings.
+ */
+export declare const logicProbeExportTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/exporters.d.ts

@@ -0,0 +1,17 @@
+import { type LogicModelV1 } from './engine.js';
+export type ExportFormat = 'uppaal' | 'tla' | 'prism' | 'spin';
+export interface ExportResult {
+    format: ExportFormat;
+    primary: string;
+    extras?: Record<string, string>;
+    warnings: string[];
+}
+export interface ExportedModel {
+    model: LogicModelV1;
+    stateIds: string[];
+    indexOf: Map<string, number>;
+    initId: string;
+    stateIdOf: Map<string, string>;
+}
+export declare function prepareModel(input: unknown): ExportedModel;
+export declare function exportModel(input: unknown, format: ExportFormat): ExportResult;

package/lib/types/tool.d.ts

@@ -2,9 +2,10 @@ export declare const LOGICPROBE_VERIFY_TOOL_NAME = "logicprobe_verify";
 /**
  * Model-visible DSH tool wrapping the bundled TypeScript verification engine.
  * The model passes a LogicModelV1 object; the engine validates it and returns
- * the 14-check report, or an 18-check report when beforeModel is supplied
- * (D1 behavioral preservation, D2 invariant continuity, D3 regression delta,
- * D4 deadlock/liveness regression). This is the dsh-native replacement for
- * hand-filling the Python template shipped in the skill references.
+ * the 22-check report (S1-S8 structural, A1-A14), or a 26-check
+ * report when beforeModel is supplied (D1 behavioral preservation, D2
+ * invariant continuity, D3 regression delta, D4 deadlock/liveness regression).
+ * This is the dsh-native replacement for hand-filling the Python template
+ * shipped in the skill references.
  */
 export declare const logicProbeVerifyTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/package.json

@@ -1,103 +1,106 @@
-{
-  "name": "dsh-logicprobe",
-  "version": "0.5.6",
-  "description": "Design document & plan claim verification — enumerate claims, verify against codebase facts, then escalate to state-machine verification (S1-S8/A1-A11) 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",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "src",
-    "skills",
-    "cordis.patch.yml"
-  ],
-  "dsh": {
-    "engines": {
-      "dsh": ">=0.1.0-rc.7"
-    },
-    "category": "skill",
-    "displayName": "逻辑探针",
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "compatibility": {
-      "dsh": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.2-alpha.3 || ^0.1.2-alpha.4",
-      "dshReleases": {
-        "0.1.0-rc.7": "compatible",
-        "0.1.0-rc.8": "compatible",
-        "0.1.1-rc.1": "compatible",
-        "0.1.1-rc.2": "compatible",
-        "0.1.2-alpha.2": "compatible",
-        "0.1.2-alpha.3": "compatible",
-        "0.1.2-alpha.4": "compatible"
-      },
-      "profiles": [
-        "headless"
-      ]
-    }
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "bump": "node scripts/bump-version.mjs",
-    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/apply-smoke.mjs",
-    "test:full": "npm run build && node tests/full-suite.mjs"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-cordis-host-runner": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@types/node": "^26.3.0",
-    "typescript": "^7.0.2"
-  },
-  "author": {
-    "name": "Amethyst Luna",
-    "url": "https://github.com/AmethystLuna"
-  },
-  "license": "MIT",
-  "repository": "https://github.com/AmethystLuna/logicprobe",
-  "keywords": [
-    "verification",
-    "fact-check",
-    "design-review",
-    "plan-review",
-    "state-machine",
-    "logic-verification",
-    "adversarial",
-    "refactoring",
-    "model-checking",
-    "agentskills",
-    "plugin",
-    "dsh"
-  ],
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "dsh-logicprobe",
+  "version": "0.6.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",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "skills",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.1.0-rc.7"
+    },
+    "category": "skill",
+    "displayName": "逻辑探针",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.2-alpha.3 || ^0.1.2-alpha.4 || ^0.1.2-alpha.5 || ^0.1.2-rc.1",
+      "dshReleases": {
+        "0.1.0-rc.7": "compatible",
+        "0.1.0-rc.8": "compatible",
+        "0.1.1-rc.1": "compatible",
+        "0.1.1-rc.2": "compatible",
+        "0.1.2-alpha.2": "compatible",
+        "0.1.2-alpha.3": "compatible",
+        "0.1.2-alpha.4": "compatible",
+        "0.1.2-alpha.5": "compatible",
+        "0.1.2-rc.1": "compatible"
+      },
+      "profiles": [
+        "headless"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "bump": "node scripts/bump-version.mjs",
+    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/apply-smoke.mjs && node tests/exporters/run.mjs && node tests/external/run.mjs && node tests/python/run.mjs",
+    "test:full": "npm run build && node tests/full-suite.mjs",
+    "test:python": "npm run build && node tests/python/run.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-cordis-host-runner": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2"
+  },
+  "author": {
+    "name": "Amethyst Luna",
+    "url": "https://github.com/AmethystLuna"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/AmethystLuna/logicprobe",
+  "keywords": [
+    "verification",
+    "fact-check",
+    "design-review",
+    "plan-review",
+    "state-machine",
+    "logic-verification",
+    "adversarial",
+    "refactoring",
+    "model-checking",
+    "agentskills",
+    "plugin",
+    "dsh"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/logicprobe/SKILL.md

@@ -44,7 +44,7 @@ This step is NOT skippable — it creates an explicit, auditable record of what
 |-------|----------|
 | LIGHTWEIGHT | All 5 checklist items (file paths, API/type names, line numbers, behavioral claims, mechanism feasibility) answered in context with explicit results per item |
 | STANDARD | Phase 1-2: enumerate every verifiable claim → verify each against codebase with evidence |
-| ESCALATED | Full pipeline: Phase 1-5 including Logic Primitive Verification (Phase 2a + 2b, 14 checks) |
+| ESCALATED | Full pipeline: Phase 1-5 including Logic Primitive Verification (Phase 2a + 2b, 22 checks) |
 
 ### Plan Verification Block
 
@@ -131,12 +131,13 @@ When Phase 2 triggers escalation, do NOT proceed to Phase 3 until the verificati
 ```text
 Document claims → Extract model → Runtime check:
   ├── DSH + `logicprobe_verify` tool available → build Model schema v1 (references/dsh-model-schema.md) → call the tool → structured report
-  ├── Python available → fill in references/verification-harness.py → run → report
+  ├── Python available + LogicModelV1 JSON at hand → references/logicprobe-engine.py verify model.json (S1-S8/A1-A14/D1-D4; subcommands compose / export add C1-C2 and UPPAAL/TLA+/PRISM/SPIN output)
+  ├── Python available + model only as extracted dicts → fill in references/verification-harness.py → run → report
   └── No Python → Manual Verification Mode (see references/logic-verification-guide.md#manual-verification-mode)
 
 Refactoring variant:
   Old code + Refactoring plan → Extract BEFORE model + AFTER model
-    → Run pipeline on AFTER model (14 checks)
+    → Run pipeline on AFTER model (22 checks)
     → Compare BEFORE vs AFTER: behavioral preservation, regression, complexity delta
     → Flag any invariant that held in BEFORE but fails in AFTER
 ```
@@ -148,7 +149,7 @@ When the document under review is a refactoring plan (modifying existing state m
 1. **Extract the BEFORE model** from the existing codebase (not the plan — verify what the code actually does, not what the plan claims it does)
 2. **Extract the AFTER model** from the refactoring plan
 3. **Show both tables AND their model narratives** to the user side by side and confirm the delta is intentional
-4. **Run Phase 2a + 2b on the AFTER model** — same 14 checks as new design
+4. **Run Phase 2a + 2b on the AFTER model** — same 22 checks as new design
 5. **Compare BEFORE vs AFTER**:
 
    | Check | Method | Severity if Violated |
@@ -171,9 +172,9 @@ When the document under review is a refactoring plan (modifying existing state m
 
 Do NOT attempt to install Python — the user's embedded development machine may be air-gapped or locked down.
 
-In DSH, prefer the native `logicprobe_verify` tool (model JSON, structured guard DSL, path-aware invariants) — see `references/dsh-model-schema.md`. For non-DSH hosts, the reusable Python harness is `references/verification-harness.py`. For detailed probe patterns, model extraction methodology, and manual verification procedures, load `references/logic-verification-guide.md`.
+In DSH, prefer the native `logicprobe_verify` tool (model JSON, structured guard DSL, path-aware invariants) — see `references/dsh-model-schema.md`. For non-DSH hosts: when the model is already a LogicModelV1 JSON, run the standalone JSON engine `references/logicprobe-engine.py` (verify | compose | export — an exact Python mirror of the DSH tools, cross-checked byte-for-byte by tests/python/run.mjs); when the model exists only as extracted dicts, fill in the reusable template `references/verification-harness.py`. For detailed probe patterns, model extraction methodology, and manual verification procedures, load `references/logic-verification-guide.md`.
 
-### Phase 2a: Structural Primitives (7 Checks)
+### Phase 2a: Structural Primitives (8 Checks)
 
 Run these FIRST. They establish basic well-formedness before adversarial probing.
 
@@ -188,7 +189,7 @@ Run these FIRST. They establish basic well-formedness before adversarial probing
 | S7 | **Invariant validity** | Does every reachable state satisfy the plan's stated "always/never/guaranteed" assertions? | Error — plan claim is false |
 | S8 | **Monotonic variables** | If a variable is declared `monotonic: inc/dec`, do all updates respect that direction? | Error — counter can move backwards |
 
-### Phase 2b: Adversarial Probes (7 Attacks)
+### Phase 2b: Adversarial Probes (14 Attacks)
 
 Run these SECOND. Each probe actively tries to BREAK the model. If any probe succeeds (finds a violation), the plan has a behavior gap.
 
@@ -197,7 +198,7 @@ Run these SECOND. Each probe actively tries to BREAK the model. If any probe suc
 | A1 | **Unexpected event** | For each state S, inject every event E where no transition is defined for (S, E). Log whether the model silently ignores or crashes. | "All events are handled in all states" |
 | A2 | **Race interleaving** | For every pair of concurrent events (E1, E2), simulate arrival in both orders: E1-then-E2 vs E2-then-E1. Flag if terminal state differs. | "Behavior is independent of event ordering" |
 | A3 | **Order permutation** | For N independent events, permute arrival order. Flag if different permutations produce different final states or violate invariants. | "Outcome is order-independent" |
-| 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). | "Resources are always released" |
+| 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 |
@@ -205,6 +206,9 @@ Run these SECOND. Each probe actively tries to BREAK the model. If any probe suc
 | A9 | **Leads-to** | From a declared source state, every path must eventually reach the target state. | "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" |
+| A13 | **Probability reachability (DTMC)** | With `weight` on transitions (absent = 1) and a `probability` invariant, P(ever hitting the target) must satisfy the bound; solved by value iteration over the absorbing chain. | "≥ 90% of runs reach SAFE" |
+| A14 | **Deadline (discrete tick clock)** | State `maxTicks` plus top-level `tickEvents`: a tick step may not keep a state resident past its deadline; reports the over-residency path. | "must leave within 2 ticks" |
 
 ### Integration Back to Phase 3
 
@@ -323,6 +327,8 @@ logicprobe does **not** prove concurrency safety. It mines documents and plans f
 
 In DSH, use the `logicprobe_concurrency_scan` tool. For manual review, follow `references/concurrency-risk-guide.md`.
 
+For routing claims in dimensions logicprobe does not verify — hard real time (deadlines/periods), preemptive concurrency, hybrid control stability, probabilistic reliability, and execution-cost budgets — to dedicated tools, see `references/gap-routing-guide.md`. In `logicprobe_verify` reports, matching models carry informational `coverageNotes` with the same routing.
+
 ---
 
 ## Rules

package/skills/logicprobe/references/concurrency-risk-guide.md

@@ -52,3 +52,5 @@ Manual checklist:
 - Java: JCStress, Java PathFinder
 - General: TLA+, SPIN, Alloy
 - Rust: loom, Shuttle
+
+Other semantic dimensions (hard real time, hybrid control, probability/reliability, execution cost) route through the same pattern — see `references/gap-routing-guide.md`.