dsh-logicprobe 0.3.1 → 0.4.0

package/README.md

@@ -62,11 +62,12 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/l
 
 - 技能遵循 Agent Skills 开放标准，被 dsh 的 `skill-filesystem` provider 原样发现——零代码。
 - bundle 将 claim 验证门禁（1% Rule / Red Flags / 主动建议）注入每个 agent 会话的第一个模型步骤——是 Claude `SessionStart` hook 在 dsh 的原生对应物，并注册模型可见目录条目（`cordis_inspect`）、原生工具 `logicprobe_verify`（`ctx.tools`）以及策略感知上下文 `logicprobe:mode`（`ctx.systemPrompt`）。
+- `logicprobe_verify` 支持 `beforeModel` + `stateMapping` 的 BEFORE/AFTER 对比（D1-D4），可直接验证重构/迁移的行为保持、不变量连续性、回归增量和死锁/活性回归。
 - 与 embedded-workbench bundle 的 Plan Verification Gate 配合，在 dsh 中闭环了 claim 验证链路。
 
 安装：参见 [`.dsh/INSTALL.md`](.dsh/INSTALL.md)（四种方式，从纯技能拷贝到 `dsh plugin add`）。
 
-> DSH 安装注意：包名已使用 scoped 形式 `dsh-logicprobe`。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须写 `dsh-logicprobe`；否则 dsh 加载器会因找不到 `node_modules/dsh-logicprobe` 而启动失败。
+> DSH 安装注意：npm 包名为 `dsh-logicprobe`（无 scope）。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须写 `dsh-logicprobe`；否则 dsh 加载器会因找不到 `node_modules/dsh-logicprobe` 而启动失败。
 
 ## 使用
 

package/lib/engine.js

@@ -1042,6 +1042,233 @@ function A7_shortestViolations(model, options) {
     }));
     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) {
+    return mapping[state] ?? state;
+}
+function D1_behavioralPreservation(before, after, mapping) {
+    const findings = [];
+    const afterStates = new Set(after.states.map((state) => state.id));
+    const afterByFromEvent = new Map();
+    for (const transition of after.transitions) {
+        const key = transition.from + '|' + transition.event;
+        const set = afterByFromEvent.get(key) ?? new Set();
+        set.add(transition.to);
+        afterByFromEvent.set(key, set);
+    }
+    const beforeInitMapped = mapStateId(mapping, before.init);
+    if (beforeInitMapped !== after.init) {
+        findings.push({
+            code: 'D1_INIT_MISMATCH',
+            severity: 'warning',
+            message: 'Mapped BEFORE init ' + beforeInitMapped + ' does not match AFTER init ' + after.init + '.',
+            evidence: { beforeInit: before.init, mappedInit: beforeInitMapped, afterInit: after.init },
+        });
+    }
+    for (const state of before.states) {
+        const mapped = mapStateId(mapping, state.id);
+        if (!afterStates.has(mapped)) {
+            findings.push({
+                code: 'D1_MAPPED_STATE_MISSING',
+                severity: 'error',
+                message: 'BEFORE state ' + state.id + ' maps to ' + mapped + ', which is not declared in AFTER.',
+                evidence: { beforeState: state.id, mappedState: mapped },
+            });
+            continue;
+        }
+        for (const transition of before.transitions.filter((entry) => entry.from === state.id)) {
+            const key = mapped + '|' + transition.event;
+            const targets = afterByFromEvent.get(key);
+            if (targets === undefined || targets.size === 0) {
+                findings.push({
+                    code: 'D1_EVENT_DISABLED',
+                    severity: 'error',
+                    message: 'BEFORE can fire event ' + transition.event + ' from ' + state.id + ' (mapped to ' + mapped + '), but AFTER has no transition for that (state, event).',
+                    path: [{ from: state.id, event: transition.event, to: transition.to }],
+                    evidence: { beforeState: state.id, mappedState: mapped, event: transition.event },
+                });
+            }
+        }
+    }
+    return checkResult('D1', 'Behavioral Preservation', findings, findings.length === 0 ? 'BEFORE event behavior is preserved in AFTER' : 'Behavioral preservation findings: ' + findings.length);
+}
+function mapInvariantForComparison(invariant, mapping) {
+    if (invariant.kind === 'never-states') {
+        return {
+            ...invariant,
+            id: invariant.id + ':before',
+            description: invariant.description + ' (from BEFORE)',
+            states: invariant.states.map((state) => mapStateId(mapping, state)),
+        };
+    }
+    if (invariant.kind === 'event-before-state') {
+        return {
+            ...invariant,
+            id: invariant.id + ':before',
+            description: invariant.description + ' (from BEFORE)',
+            state: mapStateId(mapping, invariant.state),
+        };
+    }
+    return { ...invariant, id: invariant.id + ':before', description: invariant.description + ' (from BEFORE)' };
+}
+function D2_invariantContinuity(before, after, options, mapping) {
+    const findings = [];
+    const afterStates = new Set(after.states.map((state) => state.id));
+    const afterVariables = new Set((after.variables ?? []).map((variable) => variable.name));
+    for (const invariant of before.invariants ?? []) {
+        const mapped = mapInvariantForComparison(invariant, mapping);
+        if (mapped.kind === 'never-states') {
+            for (const state of mapped.states) {
+                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 === 'event-before-state') {
+            if (!afterStates.has(mapped.state)) {
+                findings.push({
+                    code: 'D2_MAPPED_STATE_MISSING',
+                    severity: 'warning',
+                    message: 'BEFORE invariant "' + invariant.id + '" maps to state ' + mapped.state + ', which is not declared in AFTER.',
+                    evidence: { invariant: invariant.id, state: mapped.state },
+                });
+            }
+        }
+        else if (mapped.kind === 'var-in-range') {
+            if (!afterVariables.has(mapped.variable)) {
+                findings.push({
+                    code: 'D2_VARIABLE_MISSING',
+                    severity: 'warning',
+                    message: 'BEFORE invariant "' + invariant.id + '" references variable ' + mapped.variable + ', which is not declared in AFTER.',
+                    evidence: { invariant: invariant.id, variable: mapped.variable },
+                });
+                continue;
+            }
+        }
+        const violation = shortestViolationForInvariant(after, options, mapped);
+        if (violation !== undefined) {
+            findings.push({
+                code: 'D2_INVARIANT_REGRESSION',
+                severity: 'error',
+                message: 'BEFORE invariant "' + invariant.id + '" no longer holds in AFTER: ' + violation.reason,
+                path: violation.path,
+                evidence: { beforeInvariant: invariant, afterInvariant: mapped },
+            });
+        }
+    }
+    return checkResult('D2', 'Invariant Continuity', findings, findings.length === 0 ? 'All BEFORE invariants continue to hold' : 'Invariant continuity findings: ' + findings.length);
+}
+function D3_regressionDelta(before, after, mapping) {
+    const afterStateIds = new Set(after.states.map((state) => state.id));
+    const beforeMappedIds = new Set(before.states.map((state) => mapStateId(mapping, state.id)));
+    const addedStates = after.states.filter((state) => !beforeMappedIds.has(state.id)).map((state) => state.id).sort();
+    const removedStates = before.states.filter((state) => !afterStateIds.has(mapStateId(mapping, state.id))).map((state) => state.id).sort();
+    const beforeEvents = new Set(before.transitions.map((transition) => transition.event));
+    const afterEvents = new Set(after.transitions.map((transition) => transition.event));
+    const addedEvents = [...afterEvents].filter((event) => !beforeEvents.has(event)).sort();
+    const removedEvents = [...beforeEvents].filter((event) => !afterEvents.has(event)).sort();
+    const removedTransitions = before.transitions.filter((transition) => !after.transitions.some((candidate) => candidate.from === mapStateId(mapping, transition.from) &&
+        candidate.event === transition.event &&
+        candidate.to === mapStateId(mapping, transition.to)));
+    const addedTransitions = after.transitions.filter((transition) => !before.transitions.some((candidate) => mapStateId(mapping, candidate.from) === transition.from &&
+        candidate.event === transition.event &&
+        mapStateId(mapping, candidate.to) === transition.to));
+    const findings = [];
+    for (const state of removedStates) {
+        findings.push({ code: 'D3_REMOVED_STATE', severity: 'warning', message: 'BEFORE state ' + state + ' is not present in AFTER under the given mapping.', evidence: { state } });
+    }
+    for (const event of removedEvents) {
+        findings.push({ code: 'D3_REMOVED_EVENT', severity: 'warning', message: 'BEFORE event ' + event + ' is not present in AFTER.', evidence: { event } });
+    }
+    for (const transition of removedTransitions) {
+        findings.push({
+            code: 'D3_REMOVED_TRANSITION',
+            severity: 'warning',
+            message: 'BEFORE transition ' + transition.from + ' -' + transition.event + '-> ' + transition.to + ' has no exact AFTER counterpart.',
+            evidence: { transition },
+        });
+    }
+    const detail = 'Delta: +' + addedStates.length + ' states, -' + removedStates.length + ' states, +' + addedEvents.length + ' events, -' + removedEvents.length + ' events, +' + addedTransitions.length + ' transitions, -' + removedTransitions.length + ' transitions';
+    return checkResult('D3', 'Regression Delta', findings, detail);
+}
+function deadlockStateIds(model) {
+    const outgoing = new Set(model.transitions.map((transition) => transition.from));
+    return model.states.filter((state) => state.terminal !== true && !outgoing.has(state.id)).map((state) => state.id);
+}
+function closedSccStateSets(model) {
+    return sccs(model)
+        .filter((component) => {
+        const componentSet = new Set(component);
+        const internalEdges = model.transitions.some((transition) => componentSet.has(transition.from) && componentSet.has(transition.to));
+        const escapingEdges = model.transitions.some((transition) => componentSet.has(transition.from) && !componentSet.has(transition.to));
+        return internalEdges && !escapingEdges && !component.some((state) => isTerminal(model, state));
+    })
+        .map((component) => component.sort());
+}
+function D4_deadlockLivenessRegression(before, after, mapping) {
+    const findings = [];
+    const beforeDeadlock = new Set(deadlockStateIds(before).map((state) => mapStateId(mapping, state)));
+    const afterDeadlock = deadlockStateIds(after);
+    for (const state of afterDeadlock) {
+        if (!beforeDeadlock.has(state)) {
+            findings.push({
+                code: 'D4_DEADLOCK_REGRESSION',
+                severity: 'error',
+                message: 'AFTER introduces deadlock in state ' + state + ' that was not deadlocked in BEFORE.',
+                evidence: { state },
+            });
+        }
+    }
+    const beforeScc = new Set(closedSccStateSets(before).map((component) => component.map((state) => mapStateId(mapping, state)).sort().join(',')));
+    const afterScc = closedSccStateSets(after);
+    for (const component of afterScc) {
+        const key = component.join(',');
+        if (!beforeScc.has(key)) {
+            findings.push({
+                code: 'D4_LIVENESS_REGRESSION',
+                severity: 'error',
+                message: 'AFTER introduces a closed SCC with no exit and no terminal state: ' + key,
+                evidence: { states: component },
+            });
+        }
+    }
+    return checkResult('D4', 'Deadlock/Liveness Regression', findings, findings.length === 0 ? 'No new deadlock or liveness regressions' : 'Regression findings: ' + findings.length);
+}
+function buildComparisonSummary(before, after, mapping) {
+    const afterStateIds = new Set(after.states.map((state) => state.id));
+    const beforeMappedIds = new Set(before.states.map((state) => mapStateId(mapping, state.id)));
+    const addedStates = after.states.filter((state) => !beforeMappedIds.has(state.id)).map((state) => state.id).sort();
+    const removedStates = before.states.filter((state) => !afterStateIds.has(mapStateId(mapping, state.id))).map((state) => state.id).sort();
+    const beforeEvents = new Set(before.transitions.map((transition) => transition.event));
+    const afterEvents = new Set(after.transitions.map((transition) => transition.event));
+    const addedEvents = [...afterEvents].filter((event) => !beforeEvents.has(event)).sort();
+    const removedEvents = [...beforeEvents].filter((event) => !afterEvents.has(event)).sort();
+    const removedTransitions = before.transitions.filter((transition) => !after.transitions.some((candidate) => candidate.from === mapStateId(mapping, transition.from) &&
+        candidate.event === transition.event &&
+        candidate.to === mapStateId(mapping, transition.to)));
+    const addedTransitions = after.transitions.filter((transition) => !before.transitions.some((candidate) => mapStateId(mapping, candidate.from) === transition.from &&
+        candidate.event === transition.event &&
+        mapStateId(mapping, candidate.to) === transition.to));
+    return {
+        beforeModelHash: modelHash(before),
+        afterModelHash: modelHash(after),
+        stateMapping: mapping,
+        beforeStates: before.states.length,
+        beforeTransitions: before.transitions.length,
+        afterStates: after.states.length,
+        afterTransitions: after.transitions.length,
+        addedStates,
+        removedStates,
+        addedEvents,
+        removedEvents,
+        addedTransitions,
+        removedTransitions,
+    };
+}
 // ---------------------------------------------------------------------------
 // main entry
 // ---------------------------------------------------------------------------
@@ -1084,6 +1311,39 @@ export function runVerification(input, options = {}) {
         A6_resourceInjection(model),
         A7_shortestViolations(model, normalized),
     ];
+    let comparison;
+    if (options.beforeModel !== undefined) {
+        const beforeValidation = validateModel(options.beforeModel);
+        if (!beforeValidation.ok) {
+            return {
+                ok: false,
+                schemaVersion: 1,
+                modelHash: modelHash(model),
+                summary: {
+                    states: model.states.length,
+                    transitions: model.transitions.length,
+                    errors: beforeValidation.errors.length,
+                    warnings: 0,
+                    checksRun: checks.length + 1,
+                    truncated: exploration.truncated,
+                },
+                checks: [
+                    ...checks,
+                    {
+                        id: 'BEFORE_MODEL',
+                        name: 'Before Model Validation',
+                        status: 'fail',
+                        detail: 'Before model schema validation failed: ' + beforeValidation.errors.length + ' errors',
+                        findings: beforeValidation.errors.map((message) => ({ code: 'BEFORE_MODEL_INVALID', severity: 'error', message })),
+                    },
+                ],
+            };
+        }
+        const before = beforeValidation.model;
+        const mapping = options.stateMapping ?? {};
+        checks.push(D1_behavioralPreservation(before, model, mapping), D2_invariantContinuity(before, model, normalized, mapping), D3_regressionDelta(before, model, mapping), D4_deadlockLivenessRegression(before, model, mapping));
+        comparison = buildComparisonSummary(before, model, mapping);
+    }
     const errors = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'error').length, 0);
     const warnings = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'warning').length, 0);
     return {
@@ -1099,5 +1359,6 @@ export function runVerification(input, options = {}) {
             truncated: exploration.truncated,
         },
         checks,
+        ...(comparison === undefined ? {} : { comparison }),
     };
 }

package/lib/tool.js

@@ -4,12 +4,14 @@ 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. This is the dsh-native replacement for hand-filling the
- * Python template shipped in the skill references.
+ * 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?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, and event-before-state. Returns a report with S1-S7 structural checks and A1-A7 adversarial probes including shortest counterexample paths. 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?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, and event-before-state. Returns a report with S1-S7 structural checks and A1-A7 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',
@@ -24,6 +26,14 @@ export const logicProbeVerifyTool = defineTool({
             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: {
@@ -40,6 +50,8 @@ export const logicProbeVerifyTool = defineTool({
         return runVerification(args.model, {
             maxStates: args.maxStates,
             maxPermutationEvents: args.maxPermutationEvents,
+            beforeModel: args.beforeModel,
+            stateMapping: args.stateMapping,
         });
     },
 });

package/lib/types/engine.d.ts

@@ -83,6 +83,8 @@ export interface LogicModelV1 {
 export interface VerificationOptions {
     maxStates?: number;
     maxPermutationEvents?: number;
+    beforeModel?: unknown;
+    stateMapping?: Record<string, string>;
 }
 export interface PathStep {
     from: string;
@@ -116,6 +118,22 @@ export interface VerificationReport {
         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;

package/lib/types/tool.d.ts

@@ -2,7 +2,9 @@ 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. This is the dsh-native replacement for hand-filling the
- * Python template shipped in the skill references.
+ * 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 declare const logicProbeVerifyTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "dsh-logicprobe",
-    "version": "0.3.1",
+    "version": "0.4.0",
     "description": "Design document & plan claim verification — enumerate claims, verify against codebase facts, then escalate to logic-primitive verification (7 structural checks + 7 adversarial probes) for behavioral claims. Before/after model comparison for refactoring regression detection. 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

@@ -159,6 +159,8 @@ When the document under review is a refactoring plan (modifying existing state m
    | Complexity claim | If plan claims "simpler": count states + transitions + guards. Is AFTER objectively simpler? | Warning — unsubstantiated claim |
    | Unreachable code | New states added in AFTER must be reachable (otherwise they're dead code from the start) | Warning |
 
+   In DSH, pass `beforeModel` and optional `stateMapping` to `logicprobe_verify`; the engine runs D1 Behavioral Preservation, D2 Invariant Continuity, D3 Regression Delta, and D4 Deadlock/Liveness Regression automatically.
+
 6. **Flag any behavioral delta not documented in the plan** — the most common refactoring bug is an unintended side effect that the plan doesn't acknowledge
 
 **Detection step**: Before generating any verification code, run `python3 --version 2>&1` or `python --version 2>&1`. Check the output:

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

@@ -1,6 +1,6 @@
 # DSH Model Schema v1 — logicprobe_verify
 
-The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The engine runs 14 checks (S1-S7 structural, A1-A7 adversarial) and returns a JSON report. Guards and updates are structured data — no code strings, no arbitrary execution.
+The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The engine runs 14 checks (S1-S7 structural, A1-A7 adversarial) and returns a JSON report. When `beforeModel` is supplied, it also runs D1-D4 before/after regression checks. Guards and updates are structured data — no code strings, no arbitrary execution.
 
 ## Top-level model
 
@@ -97,6 +97,31 @@ In `interaction=auto`, do NOT call `ask_user_question` for model confirmation. R
 }
 ```
 
+## Before/after comparison (D1-D4)
+
+When `beforeModel` is passed to `logicprobe_verify`, the engine treats `model` as AFTER and runs four extra checks after S1-A7:
+
+| Check | Purpose |
+|---|---|
+| D1 Behavioral Preservation | Every BEFORE (state, event) that could fire must still be fireable from the mapped AFTER state |
+| D2 Invariant Continuity | Every BEFORE invariant (mapped through `stateMapping`) must still hold in AFTER |
+| D3 Regression Delta | Lists added/removed states, events, and transitions |
+| D4 Deadlock/Liveness Regression | New deadlock states or closed SCCs not present in BEFORE |
+
+`stateMapping` maps BEFORE state ids to AFTER state ids. Omit it when state names are unchanged.
+
+Example tool call shape:
+
+```json
+{
+  "model": { "...": "AFTER LogicModelV1" },
+  "beforeModel": { "...": "BEFORE LogicModelV1" },
+  "stateMapping": { "OLD_INIT": "INIT", "OLD_ACTIVE": "ACTIVE" }
+}
+```
+
+The report's `comparison` object includes both model hashes, state/transition counts, and delta arrays.
+
 ## Limits
 
 - State-space exploration caps at `maxStates` (default 10000); larger guards/domains may report truncation instead of a false pass.

package/src/engine.ts

@@ -86,6 +86,8 @@ export interface LogicModelV1 {
 export interface VerificationOptions {
   maxStates?: number
   maxPermutationEvents?: number
+  beforeModel?: unknown
+  stateMapping?: Record<string, string>
 }
 
 export interface PathStep {
@@ -123,6 +125,23 @@ export interface VerificationReport {
     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 {
@@ -1102,6 +1121,247 @@ function A7_shortestViolations(model: LogicModelV1, options: NormalizedOptions):
   return checkResult('A7', 'Minimal Counter-Example', findings, violations.length === 0 ? 'All invariants hold for all reachable paths' : 'Violated invariants: ' + findings.length)
 }
 
+function mapStateId(mapping: Record<string, string>, state: string): string {
+  return mapping[state] ?? state
+}
+
+function D1_behavioralPreservation(before: LogicModelV1, after: LogicModelV1, mapping: Record<string, string>): CheckResult {
+  const findings: Finding[] = []
+  const afterStates = new Set(after.states.map((state) => state.id))
+  const afterByFromEvent = new Map<string, Set<string>>()
+  for (const transition of after.transitions) {
+    const key = transition.from + '|' + transition.event
+    const set = afterByFromEvent.get(key) ?? new Set<string>()
+    set.add(transition.to)
+    afterByFromEvent.set(key, set)
+  }
+  const beforeInitMapped = mapStateId(mapping, before.init)
+  if (beforeInitMapped !== after.init) {
+    findings.push({
+      code: 'D1_INIT_MISMATCH',
+      severity: 'warning',
+      message: 'Mapped BEFORE init ' + beforeInitMapped + ' does not match AFTER init ' + after.init + '.',
+      evidence: { beforeInit: before.init, mappedInit: beforeInitMapped, afterInit: after.init },
+    })
+  }
+  for (const state of before.states) {
+    const mapped = mapStateId(mapping, state.id)
+    if (!afterStates.has(mapped)) {
+      findings.push({
+        code: 'D1_MAPPED_STATE_MISSING',
+        severity: 'error',
+        message: 'BEFORE state ' + state.id + ' maps to ' + mapped + ', which is not declared in AFTER.',
+        evidence: { beforeState: state.id, mappedState: mapped },
+      })
+      continue
+    }
+    for (const transition of before.transitions.filter((entry) => entry.from === state.id)) {
+      const key = mapped + '|' + transition.event
+      const targets = afterByFromEvent.get(key)
+      if (targets === undefined || targets.size === 0) {
+        findings.push({
+          code: 'D1_EVENT_DISABLED',
+          severity: 'error',
+          message: 'BEFORE can fire event ' + transition.event + ' from ' + state.id + ' (mapped to ' + mapped + '), but AFTER has no transition for that (state, event).',
+          path: [{ from: state.id, event: transition.event, to: transition.to }],
+          evidence: { beforeState: state.id, mappedState: mapped, event: transition.event },
+        })
+      }
+    }
+  }
+  return checkResult('D1', 'Behavioral Preservation', findings, findings.length === 0 ? 'BEFORE event behavior is preserved in AFTER' : 'Behavioral preservation findings: ' + findings.length)
+}
+
+function mapInvariantForComparison(invariant: InvariantSpec, mapping: Record<string, string>): InvariantSpec {
+  if (invariant.kind === 'never-states') {
+    return {
+      ...invariant,
+      id: invariant.id + ':before',
+      description: invariant.description + ' (from BEFORE)',
+      states: invariant.states.map((state) => mapStateId(mapping, state)),
+    }
+  }
+  if (invariant.kind === 'event-before-state') {
+    return {
+      ...invariant,
+      id: invariant.id + ':before',
+      description: invariant.description + ' (from BEFORE)',
+      state: mapStateId(mapping, invariant.state),
+    }
+  }
+  return { ...invariant, id: invariant.id + ':before', description: invariant.description + ' (from BEFORE)' }
+}
+
+function D2_invariantContinuity(before: LogicModelV1, after: LogicModelV1, options: NormalizedOptions, mapping: Record<string, string>): CheckResult {
+  const findings: Finding[] = []
+  const afterStates = new Set(after.states.map((state) => state.id))
+  const afterVariables = new Set((after.variables ?? []).map((variable) => variable.name))
+  for (const invariant of before.invariants ?? []) {
+    const mapped = mapInvariantForComparison(invariant, mapping)
+    if (mapped.kind === 'never-states') {
+      for (const state of mapped.states) {
+        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 === 'event-before-state') {
+      if (!afterStates.has(mapped.state)) {
+        findings.push({
+          code: 'D2_MAPPED_STATE_MISSING',
+          severity: 'warning',
+          message: 'BEFORE invariant "' + invariant.id + '" maps to state ' + mapped.state + ', which is not declared in AFTER.',
+          evidence: { invariant: invariant.id, state: mapped.state },
+        })
+      }
+    } else if (mapped.kind === 'var-in-range') {
+      if (!afterVariables.has(mapped.variable)) {
+        findings.push({
+          code: 'D2_VARIABLE_MISSING',
+          severity: 'warning',
+          message: 'BEFORE invariant "' + invariant.id + '" references variable ' + mapped.variable + ', which is not declared in AFTER.',
+          evidence: { invariant: invariant.id, variable: mapped.variable },
+        })
+        continue
+      }
+    }
+    const violation = shortestViolationForInvariant(after, options, mapped)
+    if (violation !== undefined) {
+      findings.push({
+        code: 'D2_INVARIANT_REGRESSION',
+        severity: 'error',
+        message: 'BEFORE invariant "' + invariant.id + '" no longer holds in AFTER: ' + violation.reason,
+        path: violation.path,
+        evidence: { beforeInvariant: invariant, afterInvariant: mapped },
+      })
+    }
+  }
+  return checkResult('D2', 'Invariant Continuity', findings, findings.length === 0 ? 'All BEFORE invariants continue to hold' : 'Invariant continuity findings: ' + findings.length)
+}
+
+function D3_regressionDelta(before: LogicModelV1, after: LogicModelV1, mapping: Record<string, string>): CheckResult {
+  const afterStateIds = new Set(after.states.map((state) => state.id))
+  const beforeMappedIds = new Set(before.states.map((state) => mapStateId(mapping, state.id)))
+  const addedStates = after.states.filter((state) => !beforeMappedIds.has(state.id)).map((state) => state.id).sort()
+  const removedStates = before.states.filter((state) => !afterStateIds.has(mapStateId(mapping, state.id))).map((state) => state.id).sort()
+  const beforeEvents = new Set(before.transitions.map((transition) => transition.event))
+  const afterEvents = new Set(after.transitions.map((transition) => transition.event))
+  const addedEvents = [...afterEvents].filter((event) => !beforeEvents.has(event)).sort()
+  const removedEvents = [...beforeEvents].filter((event) => !afterEvents.has(event)).sort()
+  const removedTransitions = before.transitions.filter((transition) => !after.transitions.some((candidate) =>
+    candidate.from === mapStateId(mapping, transition.from) &&
+    candidate.event === transition.event &&
+    candidate.to === mapStateId(mapping, transition.to)
+  ))
+  const addedTransitions = after.transitions.filter((transition) => !before.transitions.some((candidate) =>
+    mapStateId(mapping, candidate.from) === transition.from &&
+    candidate.event === transition.event &&
+    mapStateId(mapping, candidate.to) === transition.to
+  ))
+  const findings: Finding[] = []
+  for (const state of removedStates) {
+    findings.push({ code: 'D3_REMOVED_STATE', severity: 'warning', message: 'BEFORE state ' + state + ' is not present in AFTER under the given mapping.', evidence: { state } })
+  }
+  for (const event of removedEvents) {
+    findings.push({ code: 'D3_REMOVED_EVENT', severity: 'warning', message: 'BEFORE event ' + event + ' is not present in AFTER.', evidence: { event } })
+  }
+  for (const transition of removedTransitions) {
+    findings.push({
+      code: 'D3_REMOVED_TRANSITION',
+      severity: 'warning',
+      message: 'BEFORE transition ' + transition.from + ' -' + transition.event + '-> ' + transition.to + ' has no exact AFTER counterpart.',
+      evidence: { transition },
+    })
+  }
+  const detail = 'Delta: +' + addedStates.length + ' states, -' + removedStates.length + ' states, +' + addedEvents.length + ' events, -' + removedEvents.length + ' events, +' + addedTransitions.length + ' transitions, -' + removedTransitions.length + ' transitions'
+  return checkResult('D3', 'Regression Delta', findings, detail)
+}
+
+function deadlockStateIds(model: LogicModelV1): string[] {
+  const outgoing = new Set(model.transitions.map((transition) => transition.from))
+  return model.states.filter((state) => state.terminal !== true && !outgoing.has(state.id)).map((state) => state.id)
+}
+
+function closedSccStateSets(model: LogicModelV1): string[][] {
+  return sccs(model)
+    .filter((component) => {
+      const componentSet = new Set(component)
+      const internalEdges = model.transitions.some((transition) => componentSet.has(transition.from) && componentSet.has(transition.to))
+      const escapingEdges = model.transitions.some((transition) => componentSet.has(transition.from) && !componentSet.has(transition.to))
+      return internalEdges && !escapingEdges && !component.some((state) => isTerminal(model, state))
+    })
+    .map((component) => component.sort())
+}
+
+function D4_deadlockLivenessRegression(before: LogicModelV1, after: LogicModelV1, mapping: Record<string, string>): CheckResult {
+  const findings: Finding[] = []
+  const beforeDeadlock = new Set(deadlockStateIds(before).map((state) => mapStateId(mapping, state)))
+  const afterDeadlock = deadlockStateIds(after)
+  for (const state of afterDeadlock) {
+    if (!beforeDeadlock.has(state)) {
+      findings.push({
+        code: 'D4_DEADLOCK_REGRESSION',
+        severity: 'error',
+        message: 'AFTER introduces deadlock in state ' + state + ' that was not deadlocked in BEFORE.',
+        evidence: { state },
+      })
+    }
+  }
+  const beforeScc = new Set(closedSccStateSets(before).map((component) => component.map((state) => mapStateId(mapping, state)).sort().join(',')))
+  const afterScc = closedSccStateSets(after)
+  for (const component of afterScc) {
+    const key = component.join(',')
+    if (!beforeScc.has(key)) {
+      findings.push({
+        code: 'D4_LIVENESS_REGRESSION',
+        severity: 'error',
+        message: 'AFTER introduces a closed SCC with no exit and no terminal state: ' + key,
+        evidence: { states: component },
+      })
+    }
+  }
+  return checkResult('D4', 'Deadlock/Liveness Regression', findings, findings.length === 0 ? 'No new deadlock or liveness regressions' : 'Regression findings: ' + findings.length)
+}
+
+function buildComparisonSummary(before: LogicModelV1, after: LogicModelV1, mapping: Record<string, string>): ComparisonSummary {
+  const afterStateIds = new Set(after.states.map((state) => state.id))
+  const beforeMappedIds = new Set(before.states.map((state) => mapStateId(mapping, state.id)))
+  const addedStates = after.states.filter((state) => !beforeMappedIds.has(state.id)).map((state) => state.id).sort()
+  const removedStates = before.states.filter((state) => !afterStateIds.has(mapStateId(mapping, state.id))).map((state) => state.id).sort()
+  const beforeEvents = new Set(before.transitions.map((transition) => transition.event))
+  const afterEvents = new Set(after.transitions.map((transition) => transition.event))
+  const addedEvents = [...afterEvents].filter((event) => !beforeEvents.has(event)).sort()
+  const removedEvents = [...beforeEvents].filter((event) => !afterEvents.has(event)).sort()
+  const removedTransitions = before.transitions.filter((transition) => !after.transitions.some((candidate) =>
+    candidate.from === mapStateId(mapping, transition.from) &&
+    candidate.event === transition.event &&
+    candidate.to === mapStateId(mapping, transition.to)
+  ))
+  const addedTransitions = after.transitions.filter((transition) => !before.transitions.some((candidate) =>
+    mapStateId(mapping, candidate.from) === transition.from &&
+    candidate.event === transition.event &&
+    mapStateId(mapping, candidate.to) === transition.to
+  ))
+  return {
+    beforeModelHash: modelHash(before),
+    afterModelHash: modelHash(after),
+    stateMapping: mapping,
+    beforeStates: before.states.length,
+    beforeTransitions: before.transitions.length,
+    afterStates: after.states.length,
+    afterTransitions: after.transitions.length,
+    addedStates,
+    removedStates,
+    addedEvents,
+    removedEvents,
+    addedTransitions,
+    removedTransitions,
+  }
+}
 // ---------------------------------------------------------------------------
 // main entry
 // ---------------------------------------------------------------------------
@@ -1145,6 +1405,44 @@ export function runVerification(input: unknown, options: VerificationOptions = {
     A6_resourceInjection(model),
     A7_shortestViolations(model, normalized),
   ]
+  let comparison: ComparisonSummary | undefined
+  if (options.beforeModel !== undefined) {
+    const beforeValidation = validateModel(options.beforeModel)
+    if (!beforeValidation.ok) {
+      return {
+        ok: false,
+        schemaVersion: 1,
+        modelHash: modelHash(model),
+        summary: {
+          states: model.states.length,
+          transitions: model.transitions.length,
+          errors: beforeValidation.errors.length,
+          warnings: 0,
+          checksRun: checks.length + 1,
+          truncated: exploration.truncated,
+        },
+        checks: [
+          ...checks,
+          {
+            id: 'BEFORE_MODEL',
+            name: 'Before Model Validation',
+            status: 'fail',
+            detail: 'Before model schema validation failed: ' + beforeValidation.errors.length + ' errors',
+            findings: beforeValidation.errors.map((message) => ({ code: 'BEFORE_MODEL_INVALID', severity: 'error', message })),
+          },
+        ],
+      }
+    }
+    const before = beforeValidation.model
+    const mapping = options.stateMapping ?? {}
+    checks.push(
+      D1_behavioralPreservation(before, model, mapping),
+      D2_invariantContinuity(before, model, normalized, mapping),
+      D3_regressionDelta(before, model, mapping),
+      D4_deadlockLivenessRegression(before, model, mapping),
+    )
+    comparison = buildComparisonSummary(before, model, mapping)
+  }
   const errors = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'error').length, 0)
   const warnings = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'warning').length, 0)
   return {
@@ -1160,5 +1458,6 @@ export function runVerification(input: unknown, options: VerificationOptions = {
       truncated: exploration.truncated,
     },
     checks,
+    ...(comparison === undefined ? {} : { comparison }),
   }
 }

package/src/tool.ts

@@ -6,13 +6,15 @@ 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. This is the dsh-native replacement for hand-filling the
- * Python template shipped in the skill references.
+ * 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?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, and event-before-state. Returns a report with S1-S7 structural checks and A1-A7 adversarial probes including shortest counterexample paths. See skills/logicprobe/references/dsh-model-schema.md.',
+    '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?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, and event-before-state. Returns a report with S1-S7 structural checks and A1-A7 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',
@@ -27,6 +29,14 @@ export const logicProbeVerifyTool = defineTool({
       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: {
@@ -43,6 +53,8 @@ export const logicProbeVerifyTool = defineTool({
     return runVerification(args.model, {
       maxStates: args.maxStates,
       maxPermutationEvents: args.maxPermutationEvents,
+      beforeModel: args.beforeModel,
+      stateMapping: args.stateMapping as Record<string, string> | undefined,
     }) as unknown as JsonValue
   },
 })