dsh-logicprobe 0.5.5 → 0.6.0

package/lib/tool.js

@@ -1,57 +1,58 @@
-import { defineTool } from '@deepseek-ai/dsh-tools';
-import { runVerification } from './engine.js';
-export 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.
- */
-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?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?, narrative?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, event-before-state, leads-to, sequence, and atomicity; 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-A11 adversarial 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.',
-    parameters: {
-        model: {
-            type: 'json',
-            required: true,
-            description: 'LogicModelV1 state machine model to verify.',
-        },
-        maxStates: {
-            type: 'integer',
-            description: 'Maximum runtime states to explore. Default 10000.',
-        },
-        maxPermutationEvents: {
-            type: 'integer',
-            description: 'Maximum event count for A3 order permutation. Default 5.',
-        },
-        beforeModel: {
-            type: 'json',
-            description: 'Optional BEFORE LogicModelV1 state machine model for refactoring/migration regression comparison.',
-        },
-        stateMapping: {
-            type: 'json',
-            description: 'Optional object mapping BEFORE state ids to AFTER state ids. Omit for identity mapping (same state names).',
-        },
-    },
-    output: {
-        schema: {
-            type: 'json',
-            description: 'logicprobe verification report with summary and per-check findings.',
-        },
-        render(_args, value) {
-            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
-        },
-    },
-    timeoutMs: 10_000,
-    isConcurrencySafe: () => true,
-    async execute(args) {
-        return runVerification(args.model, {
-            maxStates: args.maxStates,
-            maxPermutationEvents: args.maxPermutationEvents,
-            beforeModel: args.beforeModel,
-            stateMapping: args.stateMapping,
-        });
-    },
-});
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runVerification } from './engine.js';
+export 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 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 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, 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). 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.',
+    parameters: {
+        model: {
+            type: 'json',
+            required: true,
+            description: 'LogicModelV1 state machine model to verify.',
+        },
+        maxStates: {
+            type: 'integer',
+            description: 'Maximum runtime states to explore. Default 10000.',
+        },
+        maxPermutationEvents: {
+            type: 'integer',
+            description: 'Maximum event count for A3 order permutation. Default 5.',
+        },
+        beforeModel: {
+            type: 'json',
+            description: 'Optional BEFORE LogicModelV1 state machine model for refactoring/migration regression comparison.',
+        },
+        stateMapping: {
+            type: 'json',
+            description: 'Optional object mapping BEFORE state ids to AFTER state ids. Omit for identity mapping (same state names).',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'logicprobe verification report with summary and per-check findings.',
+        },
+        render(_args, value) {
+            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        return runVerification(args.model, {
+            maxStates: args.maxStates,
+            maxPermutationEvents: args.maxPermutationEvents,
+            beforeModel: args.beforeModel,
+            stateMapping: args.stateMapping,
+        });
+    },
+});

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

@@ -0,0 +1,6 @@
+export declare const LOGICPROBE_COMPOSE_TOOL_NAME = "logicprobe_compose_verify";
+/**
+ * DSH tool wrapping multi-machine composition verification:
+ * product-space reachability with rendezvous handshakes (C1 deadlock, C2 sync).
+ */
+export declare const logicProbeComposeTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/concurrency.d.ts

@@ -5,6 +5,8 @@ export interface ConcurrencyFinding {
     line?: number;
     snippet?: string;
     keyword: string;
+    /** Route to dedicated verification tools when an absolute claim is detected (logicprobe does not prove concurrency safety). */
+    suggestions?: string[];
 }
 export interface ConcurrencyScanReport {
     ok: boolean;

package/lib/types/engine.d.ts

@@ -1,189 +1,255 @@
-export declare const ENGINE_SCHEMA_VERSION = 1;
-export type VarValue = number | boolean;
-export type GuardOp = '==' | '!=' | '<' | '<=' | '>' | '>=';
-export interface LeafGuard {
-    variable: string;
-    op: GuardOp;
-    value: VarValue;
-}
-export interface AllGuard {
-    all: GuardNode[];
-}
-export interface AnyGuard {
-    any: GuardNode[];
-}
-export interface NotGuard {
-    not: GuardNode;
-}
-export type GuardNode = LeafGuard | AllGuard | AnyGuard | NotGuard;
-export interface StateSpec {
-    id: string;
-    terminal?: boolean;
-}
-export interface UpdateSpec {
-    variable: string;
-    op: 'set' | 'inc' | 'dec';
-    value?: number;
-}
-export interface TransitionSpec {
-    from: string;
-    event: string;
-    to: string;
-    /** Absent guard is the else/default branch for the same (from, event) group. */
-    guard?: GuardNode;
-    updates?: UpdateSpec[];
-}
-export interface TransitionScenarioSpec {
-    from: string;
-    event: string;
-    /** Natural language: what this (state, event) combination represents in the real scenario. */
-    scenario: string;
-}
-export interface ModelNarrative {
-    /** Natural-language meaning of each state id. */
-    states?: Record<string, string>;
-    /** Natural-language meaning of each event id. */
-    events?: Record<string, string>;
-    /** Natural-language scenario for each distinct (from, event) combination. */
-    scenarios?: TransitionScenarioSpec[];
-}
-export interface VariableSpec {
-    name: string;
-    kind: 'integer' | 'boolean';
-    init: number | boolean;
-    min?: number;
-    max?: number;
-    monotonic?: 'inc' | 'dec';
-}
-export type InvariantSpec = {
-    id: string;
-    description: string;
-    kind: 'never-states';
-    states: string[];
-} | {
-    id: string;
-    description: string;
-    kind: 'var-in-range';
-    variable: string;
-    min?: number;
-    max?: number;
-} | {
-    id: string;
-    description: string;
-    kind: 'event-before-state';
-    event: string;
-    state: string;
-} | {
-    id: string;
-    description: string;
-    kind: 'leads-to';
-    from: string;
-    to: string;
-} | {
-    id: string;
-    description: string;
-    kind: 'sequence';
-    events: string[];
-} | {
-    id: string;
-    description: string;
-    kind: 'atomicity';
-    events: string[];
-    commit: string;
-    rollback?: string;
-};
-export interface ResourcePairSpec {
-    resource: string;
-    acquireEvent: string;
-    releaseEvent: string;
-    failEvent?: string;
-}
-export interface BoundaryCheckSpec {
-    variable: string;
-    values: number[];
-}
-export interface LogicModelV1 {
-    schemaVersion: 1;
-    init: string;
-    states: StateSpec[];
-    transitions: TransitionSpec[];
-    variables?: VariableSpec[];
-    invariants?: InvariantSpec[];
-    concurrentPairs?: [string, string][];
-    boundaryChecks?: BoundaryCheckSpec[];
-    resourcePairs?: ResourcePairSpec[];
-    idempotentEvents?: string[];
-    /** Natural-language descriptions of states, events, and (state, event) scenarios. */
-    narrative?: ModelNarrative;
-}
-export interface VerificationOptions {
-    maxStates?: number;
-    maxPermutationEvents?: number;
-    beforeModel?: unknown;
-    stateMapping?: Record<string, string>;
-}
-export interface PathStep {
-    from: string;
-    event: string;
-    to: string;
-}
-export interface Finding {
-    code: string;
-    severity: 'error' | 'warning';
-    message: string;
-    path?: PathStep[];
-    evidence?: Record<string, unknown>;
-}
-export interface CheckResult {
-    id: string;
-    name: string;
-    status: 'pass' | 'fail' | 'skip';
-    detail: string;
-    findings: Finding[];
-}
-export interface VerificationReport {
-    ok: boolean;
-    schemaVersion: 1;
-    modelHash: string;
-    /** Echo of the model's natural-language narrative, when present. */
-    narrative?: ModelNarrative;
-    summary: {
-        states: number;
-        transitions: number;
-        errors: number;
-        warnings: number;
-        checksRun: number;
-        truncated?: boolean;
-    };
-    checks: CheckResult[];
-    comparison?: ComparisonSummary;
-}
-export interface ComparisonSummary {
-    beforeModelHash: string;
-    afterModelHash: string;
-    stateMapping: Record<string, string>;
-    beforeStates: number;
-    beforeTransitions: number;
-    afterStates: number;
-    afterTransitions: number;
-    addedStates: string[];
-    removedStates: string[];
-    addedEvents: string[];
-    removedEvents: string[];
-    addedTransitions: TransitionSpec[];
-    removedTransitions: TransitionSpec[];
-}
-export interface RuntimeState {
-    state: string;
-    vars: Record<string, VarValue>;
-}
-export declare function modelHash(model: LogicModelV1): string;
-export declare function validateModel(input: unknown): {
-    ok: true;
-    model: LogicModelV1;
-} | {
-    ok: false;
-    errors: string[];
-};
-export declare function guardVariables(guard: GuardNode | undefined): string[];
-export declare function runVerification(input: unknown, options?: VerificationOptions): VerificationReport;
+export declare const ENGINE_SCHEMA_VERSION = 1;
+export type VarValue = number | boolean;
+export type GuardOp = '==' | '!=' | '<' | '<=' | '>' | '>=';
+export interface LeafGuard {
+    variable: string;
+    op: GuardOp;
+    value: VarValue;
+}
+export interface AllGuard {
+    all: GuardNode[];
+}
+export interface AnyGuard {
+    any: GuardNode[];
+}
+export interface NotGuard {
+    not: GuardNode;
+}
+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;
+    op: 'set' | 'inc' | 'dec';
+    value?: number;
+}
+export interface TransitionSpec {
+    from: string;
+    event: string;
+    to: string;
+    /** 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;
+    event: string;
+    /** Natural language: what this (state, event) combination represents in the real scenario. */
+    scenario: string;
+}
+export interface ModelNarrative {
+    /** Natural-language meaning of each state id. */
+    states?: Record<string, string>;
+    /** Natural-language meaning of each event id. */
+    events?: Record<string, string>;
+    /** Natural-language scenario for each distinct (from, event) combination. */
+    scenarios?: TransitionScenarioSpec[];
+}
+export interface VariableSpec {
+    name: string;
+    kind: 'integer' | 'boolean';
+    init: number | boolean;
+    min?: number;
+    max?: number;
+    monotonic?: 'inc' | 'dec';
+}
+export type InvariantSpec = {
+    id: string;
+    description: string;
+    kind: 'never-states';
+    states: string[];
+} | {
+    id: string;
+    description: string;
+    kind: 'var-in-range';
+    variable: string;
+    min?: number;
+    max?: number;
+} | {
+    id: string;
+    description: string;
+    kind: 'event-before-state';
+    event: string;
+    state: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'leads-to';
+    from: string;
+    to: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'sequence';
+    events: string[];
+} | {
+    id: string;
+    description: string;
+    kind: 'atomicity';
+    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;
+    acquireEvent: string;
+    releaseEvent: string;
+    failEvent?: string;
+}
+export interface BoundaryCheckSpec {
+    variable: string;
+    values: number[];
+}
+export interface LogicModelV1 {
+    schemaVersion: 1;
+    init: string;
+    states: StateSpec[];
+    transitions: TransitionSpec[];
+    variables?: VariableSpec[];
+    invariants?: InvariantSpec[];
+    concurrentPairs?: [string, string][];
+    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;
+}
+export interface VerificationOptions {
+    maxStates?: number;
+    maxPermutationEvents?: number;
+    beforeModel?: unknown;
+    stateMapping?: Record<string, string>;
+}
+export interface PathStep {
+    from: string;
+    event: string;
+    to: string;
+}
+export interface Finding {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    path?: PathStep[];
+    evidence?: Record<string, unknown>;
+}
+export interface CheckResult {
+    id: string;
+    name: string;
+    status: 'pass' | 'fail' | 'skip';
+    detail: string;
+    findings: Finding[];
+}
+export interface VerificationReport {
+    ok: boolean;
+    schemaVersion: 1;
+    modelHash: string;
+    /** Echo of the model's natural-language narrative, when present. */
+    narrative?: ModelNarrative;
+    summary: {
+        states: number;
+        transitions: number;
+        errors: number;
+        warnings: number;
+        checksRun: number;
+        truncated?: boolean;
+    };
+    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;
+    afterModelHash: string;
+    stateMapping: Record<string, string>;
+    beforeStates: number;
+    beforeTransitions: number;
+    afterStates: number;
+    afterTransitions: number;
+    addedStates: string[];
+    removedStates: string[];
+    addedEvents: string[];
+    removedEvents: string[];
+    addedTransitions: TransitionSpec[];
+    removedTransitions: TransitionSpec[];
+}
+export interface RuntimeState {
+    state: string;
+    vars: Record<string, VarValue>;
+}
+export declare function modelHash(model: LogicModelV1): string;
+export declare function validateModel(input: unknown): {
+    ok: true;
+    model: LogicModelV1;
+} | {
+    ok: false;
+    errors: string[];
+};
+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;