dsh-logicprobe 0.9.0 → 1.0.0

package/src/compose-tool.ts

@@ -1,47 +1,47 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from './json-value.js'
-import { runCompositionVerification } from './engine.js'
-
-export 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 const logicProbeComposeTool = defineTool({
-  name: LOGICPROBE_COMPOSE_TOOL_NAME,
-  description:
-    'Run composition verification over two or more LogicModelV1 state machines (logicprobe). Pass machines as an array of models and optionally rendezvous: a list of handshake events that must fire simultaneously across all machines declaring them (at least two participants, all jointly enabled, guards held; a terminal machine stops participating). Non-rendezvous events advance exactly one firing machine. Returns C1 composition-deadlock findings (a reachable state where no machine can advance while at least one is not terminal) and C2 rendezvous-never-fires findings. Each machine validates against the same schema as logicprobe_verify.',
-  parameters: {
-    machines: {
-      type: 'json',
-      required: true,
-      description: 'Array of LogicModelV1 state-machine models to compose (two or more).',
-    },
-    rendezvous: {
-      type: 'json',
-      description: 'Optional array of handshake event names shared by the machines.',
-    },
-    maxStates: {
-      type: 'integer',
-      description: 'Maximum composite states to explore. Default 10000.',
-    },
-  },
-  output: {
-    schema: {
-      type: 'json',
-      description: 'Composition verification report with C1/C2 findings.',
-    },
-    render(_args, value) {
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
-    },
-  },
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    return runCompositionVerification(args.machines as unknown[], {
-      rendezvous: args.rendezvous as string[] | undefined,
-      maxStates: args.maxStates,
-    }) as unknown as JsonValue
-  },
-})
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { runCompositionVerification } from './engine.js'
+
+export 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 const logicProbeComposeTool = defineTool({
+  name: LOGICPROBE_COMPOSE_TOOL_NAME,
+  description:
+    'Check two or more LogicModelV1 machines together. Pass the models in `machines`. Pass `rendezvous` for handshake events: these fire only when every declaring machine is enabled at once, and a terminal machine stops taking part. Other events advance one machine, so a machine waiting on a handshake can take any number of its own steps first. There is no rate ratio and no fairness bound. Returns C1 deadlocks (no machine can advance, and one is not terminal) and C2 handshakes that never fire. Both name the reason per machine, and C1 gives the shortest counterexample. `maxStates` caps the search; a capped run says so. Read `verdict` and `verdictReason`.',
+  parameters: {
+    machines: {
+      type: 'json',
+      required: true,
+      description: 'Array of LogicModelV1 state-machine models to compose (two or more).',
+    },
+    rendezvous: {
+      type: 'json',
+      description: 'Optional array of handshake event names shared by the machines.',
+    },
+    maxStates: {
+      type: 'integer',
+      description: 'Maximum composite states to explore. Default 10000.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Composition verification report with C1/C2 findings.',
+    },
+    render(_args, value) {
+      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    return runCompositionVerification(args.machines as unknown[], {
+      rendezvous: args.rendezvous as string[] | undefined,
+      maxStates: args.maxStates,
+    }) as unknown as JsonValue
+  },
+})

package/src/concurrency.ts

@@ -1,3 +1,4 @@
+import { REPORT_SCHEMAS, verdictOfFindings, type ReportSchema, type Verdict } from './engine.js'
 export interface ConcurrencyFinding {
   code: 'CONCURRENCY_KEYWORD' | 'CONCURRENCY_ABSOLUTE_CLAIM'
   severity: 'warning' | 'error'
@@ -11,6 +12,11 @@ export interface ConcurrencyFinding {
 
 export interface ConcurrencyScanReport {
   ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: ReportSchema
   findings: ConcurrencyFinding[]
   summary: {
     lines: number
@@ -19,6 +25,10 @@ export interface ConcurrencyScanReport {
     warnings: number
     errors: number
   }
+  /** This scan hashes no model; the field is present so every report has the same shape. */
+  hashes: Record<string, string>
+  /** What to do next, derived from the findings — never empty. */
+  nextSteps: string[]
 }
 
 interface KeywordRule {
@@ -100,8 +110,19 @@ export function runConcurrencyScan(text: string): ConcurrencyScanReport {
   const errors = findings.filter((finding) => finding.severity === 'error').length
   const warnings = findings.filter((finding) => finding.severity === 'warning').length
   const absoluteClaims = findings.filter((finding) => finding.code === 'CONCURRENCY_ABSOLUTE_CLAIM').length
+  const nextSteps: string[] = []
+  if (absoluteClaims > 0) {
+    nextSteps.push('Every absolute claim must either cite dedicated evidence (a TSan/Helgrind run, a CBMC harness, a TLA+ model of the interleaving) or be restated as a bounded, testable property.')
+  }
+  if (findings.length > absoluteClaims) {
+    nextSteps.push('Review each flagged keyword: a plan that names shared state, a mutex or an interrupt without a synchronization argument is incomplete, not merely verbose.')
+  }
+  nextSteps.push('This scan mines claims; it does not prove concurrency safety — route each one to the tool named in its suggestions.')
   return {
     ok: true,
+    ran: true,
+    ...verdictOfFindings(findings),
+    schema: REPORT_SCHEMAS.concurrency,
     findings,
     summary: {
       lines: lines.length,
@@ -110,5 +131,7 @@ export function runConcurrencyScan(text: string): ConcurrencyScanReport {
       warnings,
       errors,
     },
+    hashes: {},
+    nextSteps,
   }
 }

package/src/data-engine.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import type { CheckResult, Finding } from './engine.js'
+import { REPORT_SCHEMAS, verdictOfFindings, type CheckResult, type Finding, type ReportSchema, type Verdict } from './engine.js'
 
 export const DATA_ENGINE_SCHEMA_VERSION = 1
 
@@ -129,9 +129,17 @@ export interface DataComparisonSummary {
 }
 
 export interface DataVerificationReport {
+  /** The engine ran and the input was well-formed enough to produce this report. Read `verdict` for the review outcome. */
   ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: ReportSchema
   schemaVersion: 1
   modelHash: string
+  /** Every hash this report carries, in one place. The data-model hash follows the same normalization as the published spec, but is not covered by it. */
+  hashes: { modelHash: string }
   summary: {
     entities: number
     fields: number
@@ -142,6 +150,8 @@ export interface DataVerificationReport {
   }
   checks: CheckResult[]
   comparison?: DataComparisonSummary
+  /** What to do next, derived from the findings — never empty. */
+  nextSteps: string[]
 }
 
 const KNOWN_TYPES = new Set<string>([
@@ -913,18 +923,25 @@ function buildDataComparisonSummary(before: DataModelV1, after: DataModelV1, opt
 export function runDataVerification(input: unknown, options: DataVerificationOptions = {}): DataVerificationReport {
   const validation = validateDataModel(input)
   if (!validation.ok) {
+    const findings: Finding[] = validation.errors.map((message) => ({ code: 'DATA_MODEL_INVALID', severity: 'error', message }))
+    const modelCheck: CheckResult = {
+      id: 'DATA_MODEL',
+      name: 'Data Model Validation',
+      status: 'fail',
+      detail: 'Data model schema validation failed: ' + validation.errors.length + ' errors',
+      findings,
+    }
     return {
       ok: false,
+      ran: true,
+      ...verdictOfFindings(findings),
+      schema: REPORT_SCHEMAS.datamodel,
       schemaVersion: 1,
       modelHash: '',
+      hashes: { modelHash: '' },
       summary: { entities: 0, fields: 0, errors: validation.errors.length, warnings: 0, checksRun: 0 },
-      checks: [{
-        id: 'DATA_MODEL',
-        name: 'Data Model Validation',
-        status: 'fail',
-        detail: 'Data model schema validation failed: ' + validation.errors.length + ' errors',
-        findings: validation.errors.map((message) => ({ code: 'DATA_MODEL_INVALID', severity: 'error', message })),
-      }],
+      checks: [modelCheck],
+      nextSteps: dataNextSteps([modelCheck]),
     }
   }
   const model = validation.model
@@ -950,10 +967,15 @@ export function runDataVerification(input: unknown, options: DataVerificationOpt
   if (options.beforeModel !== undefined) {
     const beforeValidation = validateDataModel(options.beforeModel)
     if (!beforeValidation.ok) {
+      const beforeFindings: Finding[] = beforeValidation.errors.map((message) => ({ code: 'BEFORE_DATA_MODEL_INVALID', severity: 'error', message }))
       return {
         ok: false,
+        ran: true,
+        ...verdictOfFindings([...checks.flatMap((check) => check.findings), ...beforeFindings]),
+        schema: REPORT_SCHEMAS.datamodel,
         schemaVersion: 1,
         modelHash: dataModelHash(model),
+        hashes: { modelHash: dataModelHash(model) },
         summary: {
           entities: model.entities.length,
           fields: allFieldPaths(model).length,
@@ -968,9 +990,10 @@ export function runDataVerification(input: unknown, options: DataVerificationOpt
             name: 'Before Data Model Validation',
             status: 'fail',
             detail: 'Before data model schema validation failed: ' + beforeValidation.errors.length + ' errors',
-            findings: beforeValidation.errors.map((message) => ({ code: 'BEFORE_DATA_MODEL_INVALID', severity: 'error', message })),
+            findings: beforeFindings,
           },
         ],
+        nextSteps: dataNextSteps(checks),
       }
     }
     const before = beforeValidation.model
@@ -986,8 +1009,12 @@ export function runDataVerification(input: unknown, options: DataVerificationOpt
   const warnings = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'warning').length, 0)
   return {
     ok: true,
+    ran: true,
+    ...verdictOfFindings(checks.flatMap((check) => check.findings)),
+    schema: REPORT_SCHEMAS.datamodel,
     schemaVersion: 1,
     modelHash: dataModelHash(model),
+    hashes: { modelHash: dataModelHash(model) },
     summary: {
       entities: model.entities.length,
       fields: allFieldPaths(model).length,
@@ -996,6 +1023,21 @@ export function runDataVerification(input: unknown, options: DataVerificationOpt
       checksRun: checks.length,
     },
     checks,
+    nextSteps: dataNextSteps(checks),
     ...(comparison === undefined ? {} : { comparison }),
   }
 }
+
+/**
+ * The next-steps list every data report carries, derived only from the checks so two
+ * runs over the same model produce the same list.
+ */
+function dataNextSteps(checks: CheckResult[]): string[] {
+  const steps: string[] = []
+  const failed = checks.filter((check) => check.status === 'fail').map((check) => check.id + ' ' + check.name)
+  const warningCodes = [...new Set(checks.flatMap((check) => check.findings).filter((finding) => finding.severity === 'warning').map((finding) => finding.code))].sort()
+  if (failed.length > 0) steps.push('Resolve the failing checks first: ' + failed.join(', ') + '.')
+  if (warningCodes.length > 0) steps.push('Review the warning findings (' + warningCodes.join(', ') + '): a nullable field or a missing index is a decision, not silence.')
+  steps.push('Re-run with beforeModel plus the mapping/copy/migration options after the change to prove the data behaviour did not regress (DD1-DD4).')
+  return steps
+}