dsh-logicprobe 0.8.1 → 1.0.0

package/src/engine.ts

@@ -154,7 +154,7 @@ export type InvariantSpec =
       when?: InvariantWhen
     }
   | { 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: 'leads-to'; from: string; to: string | 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 }
@@ -194,6 +194,8 @@ export interface VerificationOptions {
   maxPermutationEvents?: number
   beforeModel?: unknown
   stateMapping?: Record<string, string>
+  /** Hash specification used for modelHash. Defaults to the current published spec (`v1`). */
+  hashSpec?: HashSpec
 }
 
 export interface PathStep {
@@ -206,6 +208,12 @@ export interface Finding {
   code: string
   severity: 'error' | 'warning'
   message: string
+  /** Longer explanation: the shortest-path note, the per-machine reasons, the quoted source lines. */
+  detail?: string
+  /** The artefact the finding is about (a diagram name, a file path) — set when one report covers several. */
+  file?: string
+  /** 1-based line in that artefact, when the check knows it. */
+  line?: number
   path?: PathStep[]
   evidence?: Record<string, unknown>
 }
@@ -219,9 +227,29 @@ export interface CheckResult {
 }
 
 export interface VerificationReport {
+  /**
+   * The engine ran and the input was well-formed enough to produce this report.
+   * It does NOT mean the review passed — read `verdict` for that.
+   */
   ok: boolean
+  /** The tool executed and produced a report. False only when a tool refused the request before the engine ran. */
+  ran: boolean
+  /** The review outcome. `ok: true` with `verdict: "fail"` is a failing review, not a passing one. */
+  verdict: Verdict
+  /** Why the verdict came out that way, e.g. `2 error finding(s) (first: S2_NO_TRANSITIONS)`. */
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: ReportSchema
   schemaVersion: 1
+  /** Which published specification `modelHash` follows (see references/hash-spec.md). */
+  hashSpec: HashSpec
   modelHash: string
+  /** Every hash this report carries, in one place, for a baseline diff or an archive record. */
+  hashes: { hashSpec: HashSpec; modelHash: string; beforeModelHash?: string; afterModelHash?: string }
+  /** Paths of the `_`-prefixed metadata keys found in the input and ignored by the schema. */
+  metadataKeys?: string[]
+  /** How much of the model the narrative documents; absent when there is no narrative. */
+  narrativeCoverage?: NarrativeCoverage
   /** Echo of the model's natural-language narrative, when present. */
   narrative?: ModelNarrative
   summary: {
@@ -234,11 +262,30 @@ export interface VerificationReport {
   }
   checks: CheckResult[]
   comparison?: ComparisonSummary
+  /** What to do next, derived from the findings — never empty. */
+  nextSteps: string[]
   /** 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[]
 }
 
+/**
+ * The next-steps list every verification report carries. Derived only from the checks
+ * and the narrative coverage, so two runs over the same model produce the same list.
+ */
+function verificationNextSteps(checks: CheckResult[], coverage: NarrativeCoverage | undefined): 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(', ') + '): they are not failures, but they are not silence either.')
+  if (coverage !== undefined && !narrativeComplete(coverage)) {
+    steps.push('Complete the narrative (states ' + coverage.states + ', events ' + coverage.events + ', scenarios ' + coverage.scenarios + ') — a partial narrative is valid, but a reader still has to re-derive the missing symbols.')
+  }
+  steps.push('Re-run with beforeModel/stateMapping after the change to prove the behaviour did not regress (D1-D4).')
+  return steps
+}
+
 export interface ComparisonSummary {
   beforeModelHash: string
   afterModelHash: string
@@ -272,8 +319,177 @@ function stableStringify(value: unknown): string {
   return '{' + Object.keys(record).sort().map((key) => JSON.stringify(key) + ':' + stableStringify(record[key])).join(',') + '}'
 }
 
-export function modelHash(model: LogicModelV1): string {
-  return createHash('sha256').update(stableStringify(model)).digest('hex')
+export function modelHash(model: LogicModelV1, spec: HashSpec = DEFAULT_HASH_SPEC): string {
+  return createHash('sha256').update(stableStringify(hashPayload(model, spec))).digest('hex')
+}
+
+/**
+ * Deterministic JSON (sorted keys, no insignificant whitespace) — the serialization the
+ * hash specification is defined over. Exported so every report hashes inputs the same way.
+ */
+export function canonicalJson(value: unknown): string {
+  return stableStringify(value)
+}
+
+// ---------------------------------------------------------------------------
+// Report contract: ran / verdict (P0-1) and metadata keys + hash specs (P0-3/P0-4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Published model-hash specifications. The full normalization rules, the list of
+ * excluded keys and a one-line recompute command are in `references/hash-spec.md`.
+ *
+ * - `v1` (1.0.0) drops every `_`-prefixed metadata key at every level before hashing,
+ *   so archiving `_source` / `_verified` next to a model cannot change its hash.
+ * - `v0` is the pre-1.0.0 behaviour (no metadata filtering), kept so an archived hash
+ *   can still be checked against the old engine.
+ *
+ * For a model that carries no `_` keys the two specs are byte-identical.
+ */
+export type HashSpec = 'v0' | 'v1'
+
+export const PUBLISHED_HASH_SPECS: readonly HashSpec[] = ['v0', 'v1']
+export const DEFAULT_HASH_SPEC: HashSpec = 'v1'
+
+/**
+ * Versioned report contracts. Every tool result carries `schema`, so a consumer can
+ * branch on the contract instead of sniffing fields, and a change to a report's shape
+ * is a version bump here rather than a silent break. `findings[]` keeps the same
+ * stable core in every family: `{code, severity, message, detail?, evidence?, path?}`.
+ */
+export const REPORT_SCHEMAS = {
+  verify: 'logicprobe/verify/v1',
+  compose: 'logicprobe/compose/v1',
+  datamodel: 'logicprobe/datamodel/v1',
+  concurrency: 'logicprobe/concurrency/v1',
+  export: 'logicprobe/export/v1',
+  umlRender: 'logicprobe/uml/render/v1',
+  umlParse: 'logicprobe/uml/parse/v1',
+  umlReview: 'logicprobe/uml/review/v1',
+  structure: 'logicprobe/structure/v1',
+  granularity: 'logicprobe/granularity/v1',
+  baseline: 'logicprobe/baseline/v1',
+} as const
+
+export type ReportSchema = typeof REPORT_SCHEMAS[keyof typeof REPORT_SCHEMAS]
+
+/**
+ * How much of the model the `narrative` block actually documents, as `covered/total`
+ * per dimension. A partial narrative is valid — writing the states first and the
+ * events later is the natural order — so this is a coverage report, not a gate.
+ * `scenarios` counts distinct modelled (from, event) groups: one scenario per group.
+ */
+export interface NarrativeCoverage {
+  states: string
+  events: string
+  scenarios: string
+}
+
+export function narrativeCoverageOf(model: LogicModelV1): NarrativeCoverage | undefined {
+  const narrative = model.narrative
+  if (narrative === undefined) return undefined
+  const describedStates = narrative.states === undefined ? 0 : Object.keys(narrative.states).length
+  const describedEvents = narrative.events === undefined ? 0 : Object.keys(narrative.events).length
+  const groups = new Set(model.transitions.map((transition) => transition.from + '|' + transition.event))
+  const describedGroups = narrative.scenarios === undefined
+    ? 0
+    : new Set(narrative.scenarios.map((scenario) => scenario.from + '|' + scenario.event)).size
+  const events = new Set(model.transitions.map((transition) => transition.event))
+  return {
+    states: String(describedStates) + '/' + String(model.states.length),
+    events: String(describedEvents) + '/' + String(events.size),
+    scenarios: String(describedGroups) + '/' + String(groups.size),
+  }
+}
+
+/** True when every dimension of the coverage is fully described. */
+export function narrativeComplete(coverage: NarrativeCoverage | undefined): boolean {
+  if (coverage === undefined) return false
+  return coverage.states.split('/')[0] === coverage.states.split('/')[1]
+    && coverage.events.split('/')[0] === coverage.events.split('/')[1]
+    && coverage.scenarios.split('/')[0] === coverage.scenarios.split('/')[1]
+}
+
+/**
+ * The review outcome, kept separate from `ok` (= "the tool ran"). Collapsing the two
+ * is how a failed review gets read as a passing one.
+ */
+export type Verdict = 'pass' | 'pass_with_findings' | 'fail'
+
+export interface VerdictSummary {
+  verdict: Verdict
+  verdictReason: string
+}
+
+/** A tool that refused the request before running anything: it neither passed nor failed a review. */
+export function refusalVerdict(reason: string): VerdictSummary {
+  return { verdict: 'fail', verdictReason: 'the tool did not run: ' + reason }
+}
+
+/**
+ * Decide the verdict from finding counts. Any error-severity finding fails the review
+ * even though the tool ran successfully — that gap is exactly what `verdict` closes.
+ */
+export function verdictOf(errors: number, warnings: number, firstCode?: string): VerdictSummary {
+  if (errors > 0) {
+    return {
+      verdict: 'fail',
+      verdictReason: String(errors) + ' error finding(s)' + (firstCode === undefined ? '' : ' (first: ' + firstCode + ')'),
+    }
+  }
+  if (warnings > 0) {
+    return { verdict: 'pass_with_findings', verdictReason: 'no error findings; ' + String(warnings) + ' warning finding(s)' }
+  }
+  return { verdict: 'pass', verdictReason: 'no error or warning findings' }
+}
+
+export function verdictOfFindings(findings: Array<{ code: string; severity: string }>): VerdictSummary {
+  const errors = findings.filter((finding) => finding.severity === 'error')
+  const warnings = findings.filter((finding) => finding.severity === 'warning')
+  return verdictOf(errors.length, warnings.length, errors[0]?.code)
+}
+
+/**
+ * Paths of every `_`-prefixed key in the input, sorted (`_source`, `_verified`,
+ * `states[0]._note`; a metadata key's own children are not listed, since the subtree is
+ * metadata as a whole). The schema ignores these keys as annotation metadata; echoing
+ * them in the report makes the ignored metadata auditable instead of invisible.
+ */
+export function metadataKeysOf(input: unknown): string[] {
+  const keys: string[] = []
+  const walk = (value: unknown, path: string): void => {
+    if (value === null || typeof value !== 'object') return
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => walk(entry, path + '[' + String(index) + ']'))
+      return
+    }
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      const child = path === '' ? key : path + '.' + key
+      if (key.startsWith('_')) keys.push(child)
+      walk(entry, child)
+    }
+  }
+  walk(input, '')
+  return keys.sort()
+}
+
+function withoutMetadata(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map((entry) => withoutMetadata(entry))
+  const out: Record<string, unknown> = {}
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (key.startsWith('_')) continue
+    out[key] = withoutMetadata(entry)
+  }
+  return out
+}
+
+/**
+ * The exact payload a hash spec hashes. Exported so the specification has one
+ * implementation and the documentation can be checked against it.
+ */
+export function hashPayload(model: unknown, spec: HashSpec = DEFAULT_HASH_SPEC): unknown {
+  return spec === 'v1' ? withoutMetadata(model) : model
 }
 
 export function validateModel(input: unknown): { ok: true; model: LogicModelV1 } | { ok: false; errors: string[] } {
@@ -285,8 +501,12 @@ export function validateModel(input: unknown): { ok: true; model: LogicModelV1 }
     return { ok: false, errors: ['model: must be an object'] }
   }
   const root = input as Record<string, unknown>
+  // `_`-prefixed keys are annotation metadata (provenance, verification snapshots,
+  // extraction caveats). They are ignored here and excluded from the hash, so a model
+  // can carry its own archive record without a sidecar that drifts away from it.
+  // Everything else stays closed: a mistyped `sttes` must still be an error.
   const rejectUnknownKeys = (value: Record<string, unknown>, allowed: Set<string>, path: string): void => {
-    const unexpected = Object.keys(value).filter((key) => !allowed.has(key))
+    const unexpected = Object.keys(value).filter((key) => !allowed.has(key) && !key.startsWith('_'))
     if (unexpected.length > 0) {
       bad(path + '.' + unexpected[0], 'unknown field (allowed: ' + [...allowed].join(', ') + ')')
     }
@@ -422,7 +642,7 @@ export function validateModel(input: unknown): { ok: true; model: LogicModelV1 }
       // older reader may not know are skipped so they still fail on `.kind` alone.
       if (KNOWN_INVARIANT_KINDS.has(invariant.kind as string)) {
         const allowed = INVARIANT_KEYS[invariant.kind as string]
-        const unexpected = Object.keys(invariant).filter((key) => !allowed.has(key))
+        const unexpected = Object.keys(invariant).filter((key) => !allowed.has(key) && !key.startsWith('_'))
         if (unexpected.length > 0) {
           bad(path + '.' + unexpected[0], 'unknown field for kind ' + String(invariant.kind) + ' (allowed: ' + [...allowed].join(', ') + ')')
         }
@@ -445,7 +665,7 @@ export function validateModel(input: unknown): { ok: true; model: LogicModelV1 }
           } else if ('state' in when) {
             const scope = when as Record<string, unknown>
             for (const key of Object.keys(scope)) {
-              if (key !== 'state') bad(path + '.when.' + key, 'unknown field for a state scope (allowed: state)')
+              if (key !== 'state' && !key.startsWith('_')) bad(path + '.when.' + key, 'unknown field for a state scope (allowed: state)')
             }
             const state = scope.state
             if (typeof state !== 'string' || state.length === 0) bad(path + '.when.state', 'must be a non-empty string')
@@ -469,8 +689,27 @@ export function validateModel(input: unknown): { ok: true; model: LogicModelV1 }
       } else if (invariant.kind === 'leads-to') {
         if (typeof invariant.from !== 'string' || invariant.from.length === 0) bad(path + '.from', 'must be a non-empty string')
         else if (!invariantStateIds.has(invariant.from)) bad(path + '.from', 'references unknown state ' + invariant.from)
-        if (typeof invariant.to !== 'string' || invariant.to.length === 0) bad(path + '.to', 'must be a non-empty string')
-        else if (!invariantStateIds.has(invariant.to)) bad(path + '.to', 'references unknown state ' + invariant.to)
+        // `to` is one state id or a target set. A set with a duplicate member is a
+        // model-authoring slip that would otherwise give one meaning two hashes, so it
+        // is rejected rather than silently deduplicated.
+        if (typeof invariant.to === 'string') {
+          if (invariant.to.length === 0) bad(path + '.to', 'must be a non-empty string')
+          else if (!invariantStateIds.has(invariant.to)) bad(path + '.to', 'references unknown state ' + invariant.to)
+        } else if (Array.isArray(invariant.to)) {
+          if (invariant.to.length === 0) bad(path + '.to', 'must be a non-empty array of state ids')
+          else {
+            const targets = new Set<string>()
+            invariant.to.forEach((target, targetIndex) => {
+              const at = path + '.to[' + targetIndex + ']'
+              if (typeof target !== 'string' || target.length === 0) bad(at, 'must be a non-empty string')
+              else if (!invariantStateIds.has(target)) bad(at, 'references unknown state ' + target)
+              else if (targets.has(target)) bad(at, 'duplicates state ' + target + ' in the target set')
+              else targets.add(target)
+            })
+          }
+        } else {
+          bad(path + '.to', 'must be a state id or a non-empty array of state ids')
+        }
       } else if (invariant.kind === 'sequence') {
         if (!Array.isArray(invariant.events) || invariant.events.length === 0) bad(path + '.events', 'must be a non-empty array')
         else invariant.events.forEach((event, eventIndex) => {
@@ -555,57 +794,59 @@ export function validateModel(input: unknown): { ok: true; model: LogicModelV1 }
       rejectUnknownKeys(narrative, MODEL_KEYS.narrative, narrativePath)
       const stateIds = new Set<string>(Array.isArray(root.states) ? (root.states as StateSpec[]).map((state) => state.id) : [])
       const eventIds = new Set<string>(Array.isArray(root.transitions) ? (root.transitions as TransitionSpec[]).map((transition) => transition.event) : [])
-      const fromEventGroups = new Set<string>(Array.isArray(root.transitions) ? (root.transitions as TransitionSpec[]).map((transition) => transition.from + '|' + transition.event) : [])
-      if (typeof narrative.states !== 'object' || narrative.states === null || Array.isArray(narrative.states)) {
-        bad(narrativePath + '.states', 'must be an object mapping state id -> natural-language description')
-      } else {
-        for (const [id, description] of Object.entries(narrative.states as Record<string, unknown>)) {
-          if (!stateIds.has(id)) bad(narrativePath + '.states', 'references unknown state ' + id)
-          if (typeof description !== 'string' || description.length === 0) bad(narrativePath + '.states.' + id, 'must be a non-empty string')
-        }
-        for (const id of stateIds) {
-          if (typeof (narrative.states as Record<string, unknown>)[id] !== 'string') bad(narrativePath + '.states', 'missing description for state ' + id)
-        }
+      // A narrative is allowed to cover part of the model: states first, events and
+      // scenarios later is the natural authoring order, and `narrativeCoverage` reports
+      // what is still missing instead of rejecting the file. What stays an error is a
+      // narrative that is *wrong* (unknown id, empty description, duplicate scenario) or
+      // empty — an empty block claims documentation that does not exist.
+      const declaredDimensions = (['states', 'events', 'scenarios'] as const).filter((key) => narrative[key] !== undefined)
+      if (declaredDimensions.length === 0) {
+        bad(narrativePath, 'declares no dimension: give at least one of states, events or scenarios (a partial narrative is fine)')
       }
-      if (typeof narrative.events !== 'object' || narrative.events === null || Array.isArray(narrative.events)) {
-        bad(narrativePath + '.events', 'must be an object mapping event id -> natural-language description')
-      } else {
-        for (const [id, description] of Object.entries(narrative.events as Record<string, unknown>)) {
-          if (!eventIds.has(id)) bad(narrativePath + '.events', 'references unknown event ' + id)
-          if (typeof description !== 'string' || description.length === 0) bad(narrativePath + '.events.' + id, 'must be a non-empty string')
-        }
-        for (const id of eventIds) {
-          if (typeof (narrative.events as Record<string, unknown>)[id] !== 'string') bad(narrativePath + '.events', 'missing description for event ' + id)
+      if (narrative.states !== undefined) {
+        if (typeof narrative.states !== 'object' || narrative.states === null || Array.isArray(narrative.states)) {
+          bad(narrativePath + '.states', 'must be an object mapping state id -> natural-language description')
+        } else {
+          for (const [id, description] of Object.entries(narrative.states as Record<string, unknown>)) {
+            if (!stateIds.has(id)) bad(narrativePath + '.states', 'references unknown state ' + id)
+            if (typeof description !== 'string' || description.length === 0) bad(narrativePath + '.states.' + id, 'must be a non-empty string')
+          }
         }
       }
-      if (!Array.isArray(narrative.scenarios)) {
-        bad(narrativePath + '.scenarios', 'must be an array of { from, event, scenario }')
-      } else {
-        const seen = new Set<string>()
-        narrative.scenarios.forEach((entry, index) => {
-          const scenarioPath = narrativePath + '.scenarios[' + index + ']'
-          if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-            bad(scenarioPath, 'must be an object')
-            return
-          }
-          const scenario = entry as Record<string, unknown>
-          rejectUnknownKeys(scenario, MODEL_KEYS.scenario, scenarioPath)
-          if (typeof scenario.from !== 'string' || scenario.from.length === 0) bad(scenarioPath + '.from', 'must be a non-empty string')
-          else if (!stateIds.has(scenario.from)) bad(scenarioPath + '.from', 'unknown state ' + scenario.from)
-          if (typeof scenario.event !== 'string' || scenario.event.length === 0) bad(scenarioPath + '.event', 'must be a non-empty string')
-          else if (!eventIds.has(scenario.event)) bad(scenarioPath + '.event', 'unknown event ' + scenario.event)
-          if (typeof scenario.scenario !== 'string' || scenario.scenario.length === 0) bad(scenarioPath + '.scenario', 'must be a non-empty string')
-          const key = String(scenario.from) + '|' + String(scenario.event)
-          if (seen.has(key)) bad(scenarioPath, 'duplicate scenario for (' + scenario.from + ', ' + scenario.event + ')')
-          seen.add(key)
-        })
-        for (const key of fromEventGroups) {
-          if (!seen.has(key)) {
-            const sep = key.indexOf('|')
-            bad(narrativePath + '.scenarios', 'missing scenario for (' + key.slice(0, sep) + ', ' + key.slice(sep + 1) + ')')
+      if (narrative.events !== undefined) {
+        if (typeof narrative.events !== 'object' || narrative.events === null || Array.isArray(narrative.events)) {
+          bad(narrativePath + '.events', 'must be an object mapping event id -> natural-language description')
+        } else {
+          for (const [id, description] of Object.entries(narrative.events as Record<string, unknown>)) {
+            if (!eventIds.has(id)) bad(narrativePath + '.events', 'references unknown event ' + id)
+            if (typeof description !== 'string' || description.length === 0) bad(narrativePath + '.events.' + id, 'must be a non-empty string')
           }
         }
       }
+      if (narrative.scenarios !== undefined) {
+        if (!Array.isArray(narrative.scenarios)) {
+          bad(narrativePath + '.scenarios', 'must be an array of { from, event, scenario }')
+        } else {
+          const seen = new Set<string>()
+          narrative.scenarios.forEach((entry, index) => {
+            const scenarioPath = narrativePath + '.scenarios[' + index + ']'
+            if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+              bad(scenarioPath, 'must be an object')
+              return
+            }
+            const scenario = entry as Record<string, unknown>
+            rejectUnknownKeys(scenario, MODEL_KEYS.scenario, scenarioPath)
+            if (typeof scenario.from !== 'string' || scenario.from.length === 0) bad(scenarioPath + '.from', 'must be a non-empty string')
+            else if (!stateIds.has(scenario.from)) bad(scenarioPath + '.from', 'unknown state ' + scenario.from)
+            if (typeof scenario.event !== 'string' || scenario.event.length === 0) bad(scenarioPath + '.event', 'must be a non-empty string')
+            else if (!eventIds.has(scenario.event)) bad(scenarioPath + '.event', 'unknown event ' + scenario.event)
+            if (typeof scenario.scenario !== 'string' || scenario.scenario.length === 0) bad(scenarioPath + '.scenario', 'must be a non-empty string')
+            const key = String(scenario.from) + '|' + String(scenario.event)
+            if (seen.has(key)) bad(scenarioPath, 'duplicate scenario for (' + scenario.from + ', ' + scenario.event + ')')
+            seen.add(key)
+          })
+        }
+      }
     }
   }
   // Guard/update variable references were validated structurally; re-walk for references.
@@ -826,7 +1067,7 @@ function checkResult(id: string, name: string, findings: Finding[], detail: stri
 }
 
 // ---------------------------------------------------------------------------
-// S1-S7
+// S1-S8
 // ---------------------------------------------------------------------------
 
 function S1_reachability(model: LogicModelV1, exploration: Exploration): CheckResult {
@@ -1108,6 +1349,96 @@ function shortestViolationForInvariant(model: LogicModelV1, options: NormalizedO
   return undefined
 }
 
+/**
+ * Whether an invariant asserts a property of whole runs rather than of a single
+ * runtime state. These kinds cannot be decided by a state predicate, so they are not
+ * part of `shortestViolationForInvariant` (and therefore not of S7), which owns the
+ * states; A9-A13 own the verdicts, and `pathPropertyViolation` below makes the same
+ * verdicts available to A7 and D2.
+ */
+function isPathPropertyInvariant(invariant: InvariantSpec): boolean {
+  return invariant.kind === 'leads-to'
+    || invariant.kind === 'sequence'
+    || invariant.kind === 'atomicity'
+    || invariant.kind === 'budget'
+    || invariant.kind === 'probability'
+}
+
+/** Whether a probability invariant's bound fails for the computed hit probability. */
+function probabilityViolated(invariant: Extract<InvariantSpec, { kind: 'probability' }>, probability: number): boolean {
+  const eps = 1e-9
+  if (invariant.op === '>=') return probability < invariant.p - eps
+  if (invariant.op === '>') return probability <= invariant.p + eps
+  if (invariant.op === '<=') return probability > invariant.p + eps
+  return probability >= invariant.p - eps
+}
+
+/** Every runtime state reachable from init, capped like the other searches. */
+function reachableRuntimeStates(model: LogicModelV1, options: NormalizedOptions): RuntimeState[] {
+  const init = initialState(model)
+  const visited = new Set<string>([runtimeKey(init)])
+  const reached: RuntimeState[] = [init]
+  const queue: RuntimeState[] = [init]
+  let steps = 0
+  while (queue.length > 0) {
+    if (++steps > options.maxStates) break
+    const current = queue.shift()!
+    for (const event of allEvents(model)) {
+      for (const next of stepRuntime(model, current, event)) {
+        const key = runtimeKey(next)
+        if (visited.has(key)) continue
+        visited.add(key)
+        reached.push(next)
+        queue.push(next)
+      }
+    }
+  }
+  return reached
+}
+
+/**
+ * Violation of a path-property invariant, or undefined when it holds. Each kind
+ * delegates to the search its dedicated probe uses (A9 leads-to, A10 sequence, A11
+ * atomicity, A12 budget, A13 probability), so a verdict reported here can never
+ * disagree with the probe that owns the kind.
+ */
+function pathPropertyViolation(model: LogicModelV1, options: NormalizedOptions, invariant: InvariantSpec): InvariantViolation | undefined {
+  if (invariant.kind === 'leads-to') {
+    const targets = new Set(leadsToTargets(invariant))
+    const label = leadsToTargetLabel(invariant)
+    for (const runtime of reachableRuntimeStates(model, options)) {
+      if (runtime.state !== invariant.from) continue
+      const bad = findLeadsToBadPath(model, runtime, targets, label)
+      if (bad !== undefined) return { invariant, path: bad.path, reason: bad.reason }
+    }
+    return undefined
+  }
+  if (invariant.kind === 'sequence') return findSequenceViolation(model, options, invariant)
+  if (invariant.kind === 'atomicity') return findAtomicityViolation(model, options, invariant)
+  if (invariant.kind === 'budget') {
+    const violation = findBudgetViolation(model, options, invariant)
+    if (violation === undefined) return undefined
+    return {
+      invariant,
+      path: violation.path,
+      reason: violation.unbounded
+        ? 'a reachable cycle keeps accumulating cost, so no finite budget holds'
+        : 'a run accumulates cost ' + String(violation.cost) + ', above the declared budget ' + String(invariant.budget),
+    }
+  }
+  if (invariant.kind === 'probability') {
+    const { probability, converged } = computeHitProbability(model, options, invariant.target)
+    if (!probabilityViolated(invariant, probability)) return undefined
+    return {
+      invariant,
+      path: [],
+      reason: 'P(hit ' + invariant.target + ') = ' + probability.toFixed(6) + ' does not satisfy ' + invariant.op + ' ' + String(invariant.p)
+        + (converged ? '' : ' (value iteration did not converge)'),
+    }
+  }
+  return undefined
+}
+
 function shortestEventBeforeStateViolation(model: LogicModelV1, options: NormalizedOptions, invariant: Extract<InvariantSpec, { kind: 'event-before-state' }>): InvariantViolation | undefined {
   const init = initialState(model)
   const seenInitially = false
@@ -1138,10 +1469,12 @@ function shortestEventBeforeStateViolation(model: LogicModelV1, options: Normali
   return undefined
 }
 
-function runInvariants(model: LogicModelV1, options: NormalizedOptions): InvariantViolation[] {
+function runInvariants(model: LogicModelV1, options: NormalizedOptions, includePathProperties = false): InvariantViolation[] {
   const violations: InvariantViolation[] = []
   for (const invariant of model.invariants ?? []) {
-    const violation = shortestViolationForInvariant(model, options, invariant)
+    const violation = includePathProperties && isPathPropertyInvariant(invariant)
+      ? pathPropertyViolation(model, options, invariant)
+      : shortestViolationForInvariant(model, options, invariant)
     if (violation !== undefined) violations.push(violation)
   }
   return violations
@@ -1160,7 +1493,7 @@ function S7_invariants(model: LogicModelV1, options: NormalizedOptions): CheckRe
 }
 
 // ---------------------------------------------------------------------------
-// A1-A7
+// A1-A14
 // ---------------------------------------------------------------------------
 
 function A1_unexpectedEvents(model: LogicModelV1): CheckResult {
@@ -1507,14 +1840,27 @@ function A6_resourceInjection(model: LogicModelV1): CheckResult {
 }
 
 function A7_shortestViolations(model: LogicModelV1, options: NormalizedOptions): CheckResult {
-  const violations = runInvariants(model, options)
-  const findings: Finding[] = violations.map((violation) => ({
-    code: 'A7_SHORTEST_COUNTEREXAMPLE',
-    severity: 'warning',
-    message: 'Invariant "' + violation.invariant.id + '" shortest violating path length: ' + violation.path.length + (violation.path.length === 0 ? ' (initial state)' : ''),
-    path: violation.path,
-    evidence: { invariant: violation.invariant.id },
-  }))
+  // Path-property invariants are included: "for any invariant that fails" is this
+  // check's contract, and a check that silently skips five of the eight kinds cannot
+  // honour it. The searches for the state kinds, for sequence, atomicity and budget
+  // are breadth-first, so their first witness is the shortest one; the leads-to walk
+  // and the probability bound have no such guarantee, and their message says what it
+  // found instead of claiming minimality.
+  const violations = runInvariants(model, options, true)
+  const findings: Finding[] = violations.map((violation) => {
+    const pathLength = violation.path.length
+    const message = isPathPropertyInvariant(violation.invariant)
+      ? 'Invariant "' + violation.invariant.id + '" violated: ' + violation.reason
+        + (pathLength === 0 ? '' : ' (witness path length: ' + pathLength + ')')
+      : 'Invariant "' + violation.invariant.id + '" shortest violating path length: ' + pathLength + (pathLength === 0 ? ' (initial state)' : '')
+    return {
+      code: 'A7_SHORTEST_COUNTEREXAMPLE',
+      severity: 'warning' as const,
+      message,
+      path: violation.path,
+      evidence: { invariant: violation.invariant.id },
+    }
+  })
   return checkResult('A7', 'Minimal Counter-Example', findings, violations.length === 0 ? 'All invariants hold for all reachable paths' : 'Violated invariants: ' + findings.length)
 }
 
@@ -1595,6 +1941,25 @@ function mapInvariantForComparison(invariant: InvariantSpec, mapping: Record<str
     }
     return mapped
   }
+  if (invariant.kind === 'leads-to') {
+    // A target set maps member by member; a rename that drops a state is reported by
+    // D2's own mapped-state check rather than silently changing the property.
+    return {
+      ...invariant,
+      id: invariant.id + ':before',
+      description: invariant.description + ' (from BEFORE)',
+      from: mapStateId(mapping, invariant.from),
+      to: typeof invariant.to === 'string' ? mapStateId(mapping, invariant.to) : invariant.to.map((state) => mapStateId(mapping, state)),
+    }
+  }
+  if (invariant.kind === 'probability') {
+    return {
+      ...invariant,
+      id: invariant.id + ':before',
+      description: invariant.description + ' (from BEFORE)',
+      target: mapStateId(mapping, invariant.target),
+    }
+  }
   return { ...invariant, id: invariant.id + ':before', description: invariant.description + ' (from BEFORE)' }
 }
 
@@ -1634,8 +1999,36 @@ function D2_invariantContinuity(before: LogicModelV1, after: LogicModelV1, optio
         })
         continue
       }
+    } else if (mapped.kind === 'leads-to') {
+      // The state references of a path-property invariant must follow stateMapping too,
+      // otherwise a pure rename searches for a state AFTER does not declare.
+      for (const state of [mapped.from, ...leadsToTargets(mapped)]) {
+        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 === 'probability') {
+      if (!afterStates.has(mapped.target)) {
+        findings.push({
+          code: 'D2_MAPPED_STATE_MISSING',
+          severity: 'warning',
+          message: 'BEFORE invariant "' + invariant.id + '" maps to state ' + mapped.target + ', which is not declared in AFTER.',
+          evidence: { invariant: invariant.id, state: mapped.target },
+        })
+      }
     }
-    const violation = shortestViolationForInvariant(after, options, mapped)
+    // Every invariant the engine can decide is re-decided against AFTER. Path-property
+    // kinds go through the same searches their dedicated probes use, so D2 can no
+    // longer report "all BEFORE invariants continue to hold" while A9-A13 fail on the
+    // very same model.
+    const violation = isPathPropertyInvariant(mapped)
+      ? pathPropertyViolation(after, options, mapped)
+      : shortestViolationForInvariant(after, options, mapped)
     if (violation !== undefined) {
       findings.push({
         code: 'D2_INVARIANT_REGRESSION',
@@ -1825,15 +2218,29 @@ function S8_monotonicVariables(model: LogicModelV1): CheckResult {
 }
 
 /**
- * Find a run from `start` that never reaches `target`, or return undefined when
- * every run does. The property is universal (see the A9 row in `SKILL.md`): one
- * branch that loops forever, or that stops before the target, refutes it.
+ * Target states of a `leads-to` invariant. The schema accepts one state id or a
+ * non-empty array of them, so "reach any of these" needs no separate invariant kind.
+ */
+function leadsToTargets(invariant: Extract<InvariantSpec, { kind: 'leads-to' }>): string[] {
+  return typeof invariant.to === 'string' ? [invariant.to] : invariant.to
+}
+
+/** Target list as findings print it. A single target renders as its bare id, so existing messages stay byte-identical. */
+function leadsToTargetLabel(invariant: Extract<InvariantSpec, { kind: 'leads-to' }>): string {
+  return leadsToTargets(invariant).join(', ')
+}
+
+/**
+ * Find a run from `start` that reaches none of `targets`, or return undefined when
+ * every run reaches at least one of them. The property is universal (see the A9 row
+ * in `SKILL.md`): one branch that loops forever, or that stops before any target,
+ * refutes it.
  *
- * The search is a depth-first walk of the run graph with three colours, and target
- * runs are success leaves that are never expanded:
+ * The search is a depth-first walk of the run graph with three colours, and runs at a
+ * target are success leaves that are never expanded:
  *
  * - a node reached while it is on the current walk (GRAY) closes a cycle that avoids
- *   the target, so some run never reaches it;
+ *   every target, so some run never reaches one;
  * - a node with no outgoing step at all stops the machine where it stands, which is
  *   the same violation for a different reason;
  * - a node whose walk completed without a violation is BLACK, and reaching it again
@@ -1844,8 +2251,8 @@ function S8_monotonicVariables(model: LogicModelV1): CheckResult {
  * A run is identified by its state plus its variable values, so the same state id
  * with different values is a different node.
  */
-function findLeadsToBadPath(model: LogicModelV1, start: RuntimeState, target: string): { path: PathStep[]; reason: string } | undefined {
-  if (start.state === target) return undefined
+function findLeadsToBadPath(model: LogicModelV1, start: RuntimeState, targets: Set<string>, label: string): { path: PathStep[]; reason: string } | undefined {
+  if (targets.has(start.state)) return undefined
   const GRAY = 1
   const BLACK = 2
   interface LeadFrame {
@@ -1866,7 +2273,7 @@ function findLeadsToBadPath(model: LogicModelV1, start: RuntimeState, target: st
         for (const next of stepRuntime(model, frame.runtime, event)) nexts.push({ next, event })
       }
       frame.nexts = nexts
-      if (nexts.length === 0) return { path: frame.path, reason: 'Dead end before target ' + target }
+      if (nexts.length === 0) return { path: frame.path, reason: 'Dead end before target ' + label }
     }
     if (frame.index >= frame.nexts.length) {
       color.set(runtimeKey(frame.runtime), BLACK)
@@ -1876,15 +2283,15 @@ function findLeadsToBadPath(model: LogicModelV1, start: RuntimeState, target: st
     const { next, event } = frame.nexts[frame.index]
     frame.index += 1
     const step: PathStep = { from: frame.runtime.state, event, to: next.state }
-    if (next.state === target) continue
+    if (targets.has(next.state)) continue
     const key = runtimeKey(next)
     const seen = color.get(key)
-    if (seen === GRAY) return { path: [...frame.path, step], reason: 'Cycle avoids target ' + target }
+    if (seen === GRAY) return { path: [...frame.path, step], reason: 'Cycle avoids target ' + label }
     if (seen === BLACK) continue
     color.set(key, GRAY)
     stack.push({ runtime: next, path: [...frame.path, step], nexts: undefined, index: 0 })
   }
-  // Every branch either reached the target or rejoined a branch that did.
+  // Every branch either reached a target or rejoined a branch that did.
   return undefined
 }
 
@@ -1892,9 +2299,11 @@ function A9_leadsTo(model: LogicModelV1, exploration: Exploration): CheckResult
   const findings: Finding[] = []
   for (const invariant of model.invariants ?? []) {
     if (invariant.kind !== 'leads-to') continue
+    const targets = new Set(leadsToTargets(invariant))
+    const label = leadsToTargetLabel(invariant)
     for (const runtime of exploration.reachable) {
       if (runtime.state !== invariant.from) continue
-      const bad = findLeadsToBadPath(model, runtime, invariant.to)
+      const bad = findLeadsToBadPath(model, runtime, targets, label)
       if (bad !== undefined) {
         findings.push({
           code: 'A9_LEADS_TO_VIOLATION',
@@ -2318,16 +2727,10 @@ function computeHitProbability(model: LogicModelV1, options: NormalizedOptions,
 
 function A13_probability(model: LogicModelV1, options: NormalizedOptions): CheckResult {
   const findings: Finding[] = []
-  const eps = 1e-9
   for (const invariant of model.invariants ?? []) {
     if (invariant.kind !== 'probability') continue
     const { probability, converged } = computeHitProbability(model, options, invariant.target)
-    let violated = false
-    if (invariant.op === '>=') violated = probability < invariant.p - eps
-    else if (invariant.op === '>') violated = probability <= invariant.p + eps
-    else if (invariant.op === '<=') violated = probability > invariant.p + eps
-    else violated = probability >= invariant.p - eps
-    if (violated) {
+    if (probabilityViolated(invariant, probability)) {
       findings.push({
         code: 'A13_PROBABILITY_VIOLATION',
         severity: 'error',
@@ -2465,20 +2868,32 @@ export function runVerification(input: unknown, options: VerificationOptions = {
     maxStates: options.maxStates ?? DEFAULT_MAX_STATES,
     maxPermutationEvents: options.maxPermutationEvents ?? DEFAULT_MAX_PERMUTATION_EVENTS,
   }
+  const hashSpec = options.hashSpec ?? DEFAULT_HASH_SPEC
+  const metadataKeys = metadataKeysOf(input)
+  const metadata = metadataKeys.length === 0 ? {} : { metadataKeys }
   const validation = validateModel(input)
   if (!validation.ok) {
+    const findings: Finding[] = validation.errors.map((message) => ({ code: 'MODEL_INVALID', severity: 'error', message }))
+    const modelCheck: CheckResult = {
+      id: 'MODEL',
+      name: 'Model Validation',
+      status: 'fail',
+      detail: 'Model schema validation failed: ' + validation.errors.length + ' errors',
+      findings,
+    }
     return {
       ok: false,
+      ran: true,
+      ...verdictOfFindings(findings),
+      schema: REPORT_SCHEMAS.verify,
       schemaVersion: 1,
+      hashSpec,
       modelHash: '',
+      hashes: { hashSpec, modelHash: '' },
+      ...metadata,
       summary: { states: 0, transitions: 0, errors: validation.errors.length, warnings: 0, checksRun: 0 },
-      checks: [{
-        id: 'MODEL',
-        name: 'Model Validation',
-        status: 'fail',
-        detail: 'Model schema validation failed: ' + validation.errors.length + ' errors',
-        findings: validation.errors.map((message) => ({ code: 'MODEL_INVALID', severity: 'error', message })),
-      }],
+      checks: [modelCheck],
+      nextSteps: verificationNextSteps([modelCheck], undefined),
     }
   }
   const model = validation.model
@@ -2511,10 +2926,18 @@ export function runVerification(input: unknown, options: VerificationOptions = {
   if (options.beforeModel !== undefined) {
     const beforeValidation = validateModel(options.beforeModel)
     if (!beforeValidation.ok) {
+      const beforeFindings: Finding[] = beforeValidation.errors.map((message) => ({ code: 'BEFORE_MODEL_INVALID', severity: 'error', message }))
+      const allFindings: Finding[] = [...checks.flatMap((check) => check.findings), ...beforeFindings]
       return {
         ok: false,
+        ran: true,
+        ...verdictOfFindings(allFindings),
+        schema: REPORT_SCHEMAS.verify,
         schemaVersion: 1,
-        modelHash: modelHash(model),
+        hashSpec,
+        modelHash: modelHash(model, hashSpec),
+        hashes: { hashSpec, modelHash: modelHash(model, hashSpec), afterModelHash: modelHash(model, hashSpec) },
+        ...metadata,
         summary: {
           states: model.states.length,
           transitions: model.transitions.length,
@@ -2530,9 +2953,10 @@ export function runVerification(input: unknown, options: VerificationOptions = {
             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 })),
+            findings: beforeFindings,
           },
         ],
+        nextSteps: verificationNextSteps(checks, narrativeCoverageOf(model)),
       }
     }
     const before = beforeValidation.model
@@ -2548,10 +2972,22 @@ export function runVerification(input: unknown, options: VerificationOptions = {
   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)
   const coverageNotes = computeCoverageNotes(model)
+  const narrativeCoverage = narrativeCoverageOf(model)
   return {
     ok: true,
+    ran: true,
+    ...verdictOfFindings(checks.flatMap((check) => check.findings)),
+    schema: REPORT_SCHEMAS.verify,
     schemaVersion: 1,
-    modelHash: modelHash(model),
+    hashSpec,
+    modelHash: modelHash(model, hashSpec),
+    hashes: {
+      hashSpec,
+      modelHash: modelHash(model, hashSpec),
+      ...(comparison === undefined ? {} : { beforeModelHash: comparison.beforeModelHash, afterModelHash: comparison.afterModelHash }),
+    },
+    ...metadata,
+    ...(narrativeCoverage === undefined ? {} : { narrativeCoverage }),
     summary: {
       states: model.states.length,
       transitions: model.transitions.length,
@@ -2561,6 +2997,7 @@ export function runVerification(input: unknown, options: VerificationOptions = {
       truncated: exploration.truncated,
     },
     checks,
+    nextSteps: verificationNextSteps(checks, narrativeCoverage),
     ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
     ...(comparison === undefined ? {} : { comparison }),
     ...(coverageNotes.length === 0 ? {} : { coverageNotes }),
@@ -2581,6 +3018,8 @@ export interface CompositionOptions {
   /** Events that require a synchronized multi-machine step (handshake). */
   rendezvous?: string[]
   maxStates?: number
+  /** Hash specification used for the per-machine modelHash. Defaults to the current published spec (`v1`). */
+  hashSpec?: HashSpec
 }
 
 export interface CompositionSummary {
@@ -2593,9 +3032,21 @@ export interface CompositionSummary {
 }
 
 export interface CompositionReport {
+  /** Historical meaning: the composition has no error-severity finding. Read `verdict` for the review outcome. */
   ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: ReportSchema
+  /** Which published specification the per-machine `modelHash` values follow. */
+  hashSpec: HashSpec
+  /** Every hash this report carries, in one place. */
+  hashes: { hashSpec: HashSpec; machines: string[] }
   summary: CompositionSummary
   checks: CheckResult[]
+  /** What to do next, derived from the findings — never empty. */
+  nextSteps: string[]
 }
 
 interface CompositionNode {
@@ -2621,6 +3072,7 @@ interface CompositionMove {
  * least one is not terminal) and C2 rendezvous that can never fire.
  */
 export function runCompositionVerification(machinesInput: unknown[], options: CompositionOptions = {}): CompositionReport {
+  const hashSpec = options.hashSpec ?? DEFAULT_HASH_SPEC
   const models: LogicModelV1[] = []
   const hashes: string[] = []
   const modelFindings: Finding[] = []
@@ -2630,7 +3082,7 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
       modelFindings.push({ code: 'MODEL_INVALID', severity: 'error', message: 'machine ' + index + ' invalid: ' + validation.errors.join('; ') })
     } else {
       models.push(validation.model)
-      hashes.push(modelHash(validation.model))
+      hashes.push(modelHash(validation.model, hashSpec))
     }
   })
   const machineSummary = models.map((m, i) => ({ modelHash: hashes[i] ?? '', states: m.states.length, transitions: m.transitions.length }))
@@ -2640,8 +3092,14 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
     }
     return {
       ok: false,
+      ran: true,
+      ...verdictOfFindings(modelFindings),
+      schema: REPORT_SCHEMAS.compose,
+      hashSpec,
+      hashes: { hashSpec, machines: hashes },
       summary: { machineCount: models.length, machines: machineSummary, compositeStates: 0, errors: modelFindings.length, warnings: 0, truncated: false },
       checks: [{ id: 'MODEL', name: 'Machine Validation', status: 'fail', detail: 'composition input validation failed', findings: modelFindings }],
+      nextSteps: ['Fix the machine that failed validation, then re-run the composition.'],
     }
   }
   const rendezvous = new Set(options.rendezvous ?? [])
@@ -2700,6 +3158,17 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
   let truncated = false
   const firedCount = new Map<string, number>()
   for (const event of rendezvous) firedCount.set(event, 0)
+  // Per-machine enablement, collected while the state space is explored: a rendezvous
+  // that never fires needs to say *which* machine never had it enabled, not just that
+  // the handshake did not happen.
+  const everEnabled = new Map<string, Set<number>>()
+  const enabledStates = new Map<string, string[][]>()
+  const coEnabledNodes = new Map<string, number>()
+  for (const event of rendezvous) {
+    everEnabled.set(event, new Set<number>())
+    enabledStates.set(event, models.map(() => []))
+    coEnabledNodes.set(event, 0)
+  }
   const c1Findings: Finding[] = []
   while (queue.length > 0) {
     const node = queue.shift()!
@@ -2713,12 +3182,53 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
     }
     const moves = compositionMoves(node)
     const allTerminal = node.runtimes.every((runtime, i) => isTerminal(models[i], runtime.state))
+    // Enablement census for C2: which machines could fire each rendezvous here.
+    for (const event of rendezvous) {
+      const declaring: number[] = []
+      for (let i = 0; i < models.length; i++) if (machineEventSets[i].has(event)) declaring.push(i)
+      if (declaring.length === 0) continue
+      let allEnabled = declaring.length >= 2
+      for (const i of declaring) {
+        const enabled = !isTerminal(models[i], node.runtimes[i].state) && stepRuntime(models[i], node.runtimes[i], event).length > 0
+        if (!enabled) { allEnabled = false; continue }
+        everEnabled.get(event)?.add(i)
+        const states = enabledStates.get(event)?.[i]
+        if (states !== undefined && !states.includes(node.runtimes[i].state) && states.length < 8) states.push(node.runtimes[i].state)
+      }
+      if (allEnabled) coEnabledNodes.set(event, (coEnabledNodes.get(event) ?? 0) + 1)
+    }
     if (moves.length === 0 && !allTerminal) {
+      // Why nobody can advance, per machine: its state, its alphabet, and for every event
+      // either the rendezvous partner that is not ready or the transition that does not fire.
+      const perMachine = node.runtimes.map((runtime, i) => {
+        const terminal = isTerminal(models[i], runtime.state)
+        const blocked = terminal ? [] : allEvents(models[i]).map((event) => {
+          const enabled = stepRuntime(models[i], runtime, event).length > 0
+          // A rendezvous event is not fireable just because this machine has a transition:
+          // it needs every declaring machine enabled at the same time. Check that first, or
+          // the deadlock census would report "enabled" for a handshake nobody can complete.
+          if (!rendezvous.has(event)) return { event, reason: enabled ? 'enabled' : 'no-enabled-transition' }
+          const declaring: number[] = []
+          for (let j = 0; j < models.length; j++) if (machineEventSets[j].has(event)) declaring.push(j)
+          if (declaring.length < 2) return { event, reason: 'rendezvous-needs-partner' }
+          const partnersReady = declaring.every((j) => !isTerminal(models[j], node.runtimes[j].state)
+            && stepRuntime(models[j], node.runtimes[j], event).length > 0)
+          if (!partnersReady) return { event, reason: 'rendezvous-partner-not-ready' }
+          return { event, reason: enabled ? 'enabled' : 'no-enabled-transition' }
+        })
+        return { index: i, state: runtime.state, terminal, blocked }
+      })
+      const reasons = perMachine
+        .filter((machine) => !machine.terminal)
+        .map((machine) => 'machine ' + String(machine.index) + ' at ' + machine.state + ': ' + (machine.blocked.length === 0
+          ? 'empty event alphabet'
+          : machine.blocked.map((entry) => entry.event + ' (' + entry.reason + ')').join(', ')))
       c1Findings.push({
         code: 'C1_COMPOSITION_DEADLOCK',
         severity: 'error',
         message: 'Composition deadlock: no machine can advance from (' + node.runtimes.map((runtime) => runtime.state).join(', ') + ') while at least one is not terminal.',
-        evidence: { steps: node.path, states: node.runtimes.map((runtime) => runtime.state) },
+        detail: 'Shortest counterexample (breadth-first): ' + String(node.path.length) + ' step(s) to reach it. ' + reasons.join(' | '),
+        evidence: { steps: node.path, states: node.runtimes.map((runtime) => runtime.state), depth: node.path.length, perMachine, reasons },
       })
       continue
     }
@@ -2735,22 +3245,67 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
   for (const event of rendezvous) {
     if (!allEventsSet.has(event)) continue
     if ((firedCount.get(event) ?? 0) === 0) {
+      // Why the handshake never happens: who declares it, who ever had it enabled, and
+      // whether the enabling states could ever coincide.
+      const machines = models.map((model, index) => ({
+        index,
+        declares: machineEventSets[index].has(event),
+        everEnabled: everEnabled.get(event)?.has(index) === true,
+        enabledAt: enabledStates.get(event)?.[index] ?? [],
+      }))
+      const declaring = machines.filter((machine) => machine.declares)
+      const neverEnabled = declaring.filter((machine) => !machine.everEnabled)
+      const coEnabled = coEnabledNodes.get(event) ?? 0
+      let reason: string
+      if (declaring.length < 2) {
+        reason = 'only ' + String(declaring.length) + ' machine(s) declare it (machine ' + declaring.map((machine) => machine.index).join(', ') + '); a handshake needs at least two'
+      } else if (neverEnabled.length > 0) {
+        reason = 'machine ' + neverEnabled.map((machine) => machine.index).join(', ') + ' declares it but never has it enabled (no transition, or the guard never holds)'
+      } else {
+        reason = 'every declaring machine enables it somewhere, but never at the same time (' + String(coEnabled) + ' composite state(s) had all of them ready)'
+      }
+      // A truncated exploration cannot prove that a handshake never happens: it may simply
+      // not have reached the composite state where both machines are ready.
+      const caveat = truncated ? ' The search was truncated at ' + String(maxStates) + ' composite states, so this may be an artefact of the cap rather than a property of the model.' : ''
       c2Findings.push({
         code: 'C2_RENDEZVOUS_NEVER_FIRES',
         severity: 'warning',
-        message: 'Rendezvous event ' + event + ' can never fire: fewer than two machines ever jointly enable it.',
+        message: 'Rendezvous event ' + event + ' can never fire: ' + reason + '.' + caveat,
+        detail: machines.map((machine) => 'machine ' + String(machine.index) + (machine.declares ? ' declares' : ' does not declare')
+          + (machine.everEnabled ? ', enabled at ' + (machine.enabledAt.length === 0 ? 'no visited state' : machine.enabledAt.join('/')) : ', never enabled')).join(' | '),
+        evidence: { event, machines, declaring: declaring.map((machine) => machine.index), coEnabledNodes: coEnabled, reason, truncated },
       })
     }
   }
   const errors = c1Findings.length
   const warnings = c2Findings.length
+  const c1Detail = c1Findings.length > 0
+    ? 'Composition deadlocks: ' + String(c1Findings.length)
+    : truncated
+      ? 'No composition deadlock found, but the search was truncated at ' + String(maxStates) + ' composite states: absence is not proven'
+      : 'No composition deadlock reachable'
+  const c2Detail = c2Findings.length > 0
+    ? 'Rendezvous warnings: ' + String(c2Findings.length)
+    : truncated
+      ? 'All rendezvous events fired, but the search was truncated at ' + String(maxStates) + ' composite states'
+      : 'All rendezvous events can fire'
   const checks: CheckResult[] = [
-    checkResult('C1', 'Composition Deadlock', c1Findings, c1Findings.length === 0 ? 'No composition deadlock reachable' : 'Composition deadlocks: ' + c1Findings.length),
-    checkResult('C2', 'Rendezvous Sync', c2Findings, c2Findings.length === 0 ? 'All rendezvous events can fire' : 'Rendezvous warnings: ' + c2Findings.length),
+    checkResult('C1', 'Composition Deadlock', c1Findings, c1Detail),
+    checkResult('C2', 'Rendezvous Sync', c2Findings, c2Detail),
   ]
+  const nextSteps: string[] = []
+  if (errors > 0) nextSteps.push('Resolve the error findings first: the composition deadlocks at a reachable state, so at least one machine is missing an exit or a handshake partner.')
+  if (warnings > 0) nextSteps.push('Review the warning findings: a rendezvous event that can never fire means the handshake is declared but unreachable.')
+  nextSteps.push('Re-run the composition after the change; every machine must be able to advance, or explain why it is terminal.')
   return {
     ok: errors === 0,
+    ran: true,
+    ...verdictOf(errors, warnings, c1Findings[0]?.code ?? c2Findings[0]?.code),
+    schema: REPORT_SCHEMAS.compose,
+    hashSpec,
+    hashes: { hashSpec, machines: hashes },
     summary: { machineCount: models.length, machines: machineSummary, compositeStates, errors, warnings, truncated },
     checks,
+    nextSteps,
   }
 }