dsh-logicprobe 0.9.0 → 1.1.0

package/src/baseline.ts

@@ -0,0 +1,180 @@
+/**
+ * Report diffing: "did this slice add findings, or remove them?"
+ *
+ * The acceptance criterion of a refactoring slice is usually *not* "zero findings" —
+ * it is "no NEW findings, and none of the old ones got worse". Comparing two JSON
+ * reports by hand is how that gets fudged, so the comparison is code.
+ *
+ * A finding's identity is its machine-readable locator, never its prose:
+ * `check|code|<canonical evidence + path>`. Findings that carry neither evidence nor a
+ * path fall back to their message, because an engine that reports nothing structured
+ * has nothing stabler to match on. Two runs over the same input must produce zero
+ * added and zero removed findings.
+ *
+ * @module logicprobe-baseline
+ */
+
+import { canonicalJson, REPORT_SCHEMAS, verdictOf, type Finding, type Verdict, type VerdictSummary } from './engine.js'
+
+/** A finding as it appears in any report family, after flattening. */
+export interface ReportFinding extends Finding {
+  /** The check that emitted it (verify/datamodel: `S2`, `C1`, …); absent for flat families. */
+  check?: string
+}
+
+export interface BaselineChange {
+  identity: string
+  code: string
+  before: { severity: string; message: string }
+  after: { severity: string; message: string }
+}
+
+export interface BaselineReport {
+  ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: string
+  /** The current report's own verdict, echoed so "no new findings" cannot hide a failing run. */
+  currentVerdict: Verdict
+  added: ReportFinding[]
+  removed: ReportFinding[]
+  changed: BaselineChange[]
+  summary: {
+    baseline: number
+    current: number
+    added: number
+    removed: number
+    changed: number
+    addedErrors: number
+    addedWarnings: number
+  }
+  nextSteps: string[]
+}
+
+/**
+ * The stable identity of a finding: check + file + code + a canonical locator. Prose is
+ * excluded so a reworded message reads as `changed`, not as a new finding.
+ */
+export function findingIdentity(finding: ReportFinding): string {
+  const locator = canonicalJson({
+    ...(finding.evidence === undefined ? {} : { evidence: finding.evidence }),
+    ...(finding.path === undefined ? {} : { path: finding.path }),
+  })
+  const where = locator === '{}' ? 'message:' + finding.message : locator
+  const file = finding.file === undefined ? '' : finding.file + '|'
+  return (finding.check === undefined ? '' : finding.check + '|') + file + finding.code + '|' + where
+}
+
+/** Flatten a report of any family into one finding list (`checks[].findings` or `findings[]`). */
+export function flattenReportFindings(report: unknown): ReportFinding[] {
+  if (report === null || typeof report !== 'object') return []
+  const record = report as Record<string, unknown>
+  const flat: ReportFinding[] = []
+  if (Array.isArray(record.checks)) {
+    for (const check of record.checks as Array<Record<string, unknown>>) {
+      const id = typeof check.id === 'string' ? check.id : undefined
+      for (const finding of (Array.isArray(check.findings) ? check.findings : []) as Finding[]) {
+        flat.push(id === undefined ? finding : { ...finding, check: id })
+      }
+    }
+  }
+  if (Array.isArray(record.findings)) {
+    for (const finding of record.findings as Finding[]) flat.push(finding)
+  }
+  return flat
+}
+
+/** The report's own verdict, whatever family it came from. */
+function verdictOfReport(report: unknown): Verdict {
+  if (report === null || typeof report !== 'object') return 'fail'
+  const value = (report as Record<string, unknown>).verdict
+  return value === 'pass' || value === 'pass_with_findings' || value === 'fail' ? value : 'fail'
+}
+
+function diffOf(added: number, removed: number, addedErrors: number, firstCode?: string): VerdictSummary {
+  if (addedErrors > 0) {
+    return {
+      verdict: 'fail',
+      verdictReason: String(added) + ' new finding(s) (' + String(addedErrors) + ' error)' + (firstCode === undefined ? '' : ' (first: ' + firstCode + ')'),
+    }
+  }
+  if (added > 0) {
+    return { verdict: 'pass_with_findings', verdictReason: String(added) + ' new warning finding(s), no new errors' }
+  }
+  if (removed > 0) {
+    return { verdict: 'pass', verdictReason: 'no new findings; ' + String(removed) + ' finding(s) resolved' }
+  }
+  return { verdict: 'pass', verdictReason: 'no new findings, nothing resolved' }
+}
+
+/**
+ * Compare a baseline report with the current one. The verdict describes the *delta*
+ * (a new error fails it), while `currentVerdict` keeps the absolute result visible.
+ */
+export function diffReports(baseline: unknown, current: unknown): BaselineReport {
+  const before = flattenReportFindings(baseline)
+  const after = flattenReportFindings(current)
+  const beforeByIdentity = new Map<string, ReportFinding>()
+  for (const finding of before) beforeByIdentity.set(findingIdentity(finding), finding)
+  const seen = new Set<string>()
+  const added: ReportFinding[] = []
+  const changed: BaselineChange[] = []
+  for (const finding of after) {
+    const identity = findingIdentity(finding)
+    seen.add(identity)
+    const previous = beforeByIdentity.get(identity)
+    if (previous === undefined) {
+      added.push(finding)
+      continue
+    }
+    if (previous.severity !== finding.severity || previous.message !== finding.message) {
+      changed.push({
+        identity,
+        code: finding.code,
+        before: { severity: previous.severity, message: previous.message },
+        after: { severity: finding.severity, message: finding.message },
+      })
+    }
+  }
+  const removed = before.filter((finding) => !seen.has(findingIdentity(finding)))
+  const addedErrors = added.filter((finding) => finding.severity === 'error')
+  const addedWarnings = added.filter((finding) => finding.severity === 'warning')
+  const delta = diffOf(added.length, removed.length, addedErrors.length, addedErrors[0]?.code)
+
+  const nextSteps: string[] = []
+  if (addedErrors.length > 0) {
+    nextSteps.push('Fix or explicitly accept the ' + String(addedErrors.length) + ' new error finding(s) before calling this slice done: the baseline is what "not worse" is measured against.')
+  } else if (added.length > 0) {
+    nextSteps.push('The new warnings are not failures, but they are new: decide per finding whether the change introduced them or the baseline was incomplete.')
+  } else {
+    nextSteps.push('No new findings: re-record the baseline with this report if the slice is accepted, so the next comparison starts from it.')
+  }
+  if (changed.length > 0) nextSteps.push('Review the ' + String(changed.length) + ' changed finding(s): the same locator now reports something different, which usually means the fix moved the problem.')
+  if (removed.length > 0) nextSteps.push(String(removed.length) + ' finding(s) from the baseline are gone — confirm they were fixed rather than renamed out of the report (a renamed check or a reworded message changes the identity).')
+  if (verdictOfReport(current) === 'fail') nextSteps.push('The current report still fails on its own terms; the delta being clean does not make the run clean.')
+
+  return {
+    ok: true,
+    ran: true,
+    ...delta,
+    schema: REPORT_SCHEMAS.baseline,
+    currentVerdict: verdictOfReport(current),
+    added,
+    removed,
+    changed,
+    summary: {
+      baseline: before.length,
+      current: after.length,
+      added: added.length,
+      removed: removed.length,
+      changed: changed.length,
+      addedErrors: addedErrors.length,
+      addedWarnings: addedWarnings.length,
+    },
+    nextSteps,
+  }
+}
+
+export type { VerdictSummary }

package/src/client.js

@@ -30,7 +30,61 @@ window.__ModuleLoader__.load({
   id: 'dsh-logicprobe',
   factory: (require) => {
     const React = require('react')
-    const { Button, Switch } = require('@deepseek-ai/dsh-client-ui-primitives')
+    // The host's Switch and Button, vendored. A plain-JS client bundle must not
+    // require a Harness Client package: it changes without notice, we get no type
+    // check, and a throw blanks this slot entry. Markup, classes, token usage and
+    // the aria behaviour follow the host primitive; classes carry our own prefix.
+    const CONTROLS_CSS = [
+      '.lp-switch { box-sizing: border-box; position: relative; flex: 0 0 auto; width: 36px; height: 20px; padding: 2px; border: 0; border-radius: 999px; corner-shape: round; background: var(--dsw-alias-border-l3); cursor: pointer; }',
+      ".lp-switch[aria-checked='true'] { background: var(--dsw-alias-brand-primary); }",
+      '.lp-switch:disabled { cursor: default; opacity: 0.5; }',
+      '.lp-switch:focus-visible { outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); outline-offset: 2px; }',
+      '.lp-switch-thumb { display: block; width: 16px; height: 16px; border-radius: 50%; corner-shape: round; background: var(--dsw-alias-label-primary-foreground); transition: transform 120ms ease; }',
+      ".lp-switch[aria-checked='false'] .lp-switch-thumb { background: var(--dsw-alias-switch-thumb); }",
+      ".lp-switch[aria-checked='true'] .lp-switch-thumb { transform: translateX(16px); }",
+      '.lp-btn { box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 4px; border: none; border-radius: var(--dsw-radius-md); cursor: pointer; font-size: 14px; line-height: 22px; color: var(--dsw-alias-label-primary); background: transparent; padding: 0 14px; }',
+      '.lp-btn:disabled { cursor: not-allowed; opacity: 0.4; }',
+      '.lp-btn-sm { height: 28px; font-size: 12px; line-height: 18px; padding: 0 10px; border-radius: var(--dsw-radius-sm); }',
+      '.lp-btn-outline { border: 0.5px solid var(--dsw-alias-border-l3); background: transparent; }',
+      '.lp-btn-outline:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); }',
+    ].join('\n')
+
+    /** Rendered inside the component tree, so unmounting removes the styles. */
+    function Controls() {
+      return React.createElement('style', null, CONTROLS_CSS)
+    }
+
+    function Switch(props) {
+      return React.createElement(
+        'button',
+        {
+          type: 'button',
+          role: 'switch',
+          'aria-checked': props.checked === true,
+          'aria-label': props.label,
+          className: 'lp-switch',
+          disabled: props.disabled === true,
+          onClick: () => {
+            if (props.disabled !== true) props.onChange(!(props.checked === true))
+          },
+        },
+        React.createElement('span', { className: 'lp-switch-thumb' }),
+      )
+    }
+
+    Switch.displayName = 'dsh-logicprobe:Switch'
+    Button.displayName = 'dsh-logicprobe:Button'
+
+    function Button(props) {
+      const classes = ['lp-btn']
+      if (props.size === 'sm') classes.push('lp-btn-sm')
+      if (props.variant === 'outline') classes.push('lp-btn-outline')
+      return React.createElement(
+        'button',
+        { type: 'button', className: classes.join(' '), disabled: props.disabled === true, onClick: props.onClick },
+        props.children,
+      )
+    }
 
     /** Settings namespace: the Loader entry id this bundle's patch declares. */
     const NS = 'logicprobe'
@@ -122,6 +176,7 @@ window.__ModuleLoader__.load({
       const locked = state.writable !== true || pending
 
       const children = [
+        React.createElement(Controls, { key: 'styles' }),
         React.createElement('h4', { key: 'title', style: TITLE }, t('title')),
         React.createElement('div', { key: 'row', style: ROW }, [
           React.createElement('span', { key: 'label', style: LABEL }, t('label')),

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
+}