dsh-logicprobe 0.9.0 → 1.1.0

package/src/engine.ts

@@ -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 {
@@ -204,8 +206,18 @@ export interface PathStep {
 
 export interface Finding {
   code: string
-  severity: 'error' | 'warning'
+  /**
+   * `info` is a note, not a defect: it is reported so a machine-readable reader can see it,
+   * and it never contributes to `verdict`, `summary.errors` or `summary.warnings`.
+   */
+  severity: 'error' | 'warning' | 'info'
   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 +231,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 +266,44 @@ 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
+}
+
+/**
+ * Repair guidance for a rejected model. A refusal reports the offending path and the rule
+ * it broke, but not what to write instead; for fields whose absence is a documented trap,
+ * that is the difference between "fix it" and "guess again". Derived only from the
+ * validation messages, so the list stays deterministic.
+ */
+function refusalGuidance(errors: string[]): string[] {
+  const steps: string[] = []
+  if (errors.some((message) => message.includes('.description'))) {
+    steps.push('Add the required "description" string to every invariant (for example "description": "what this invariant guarantees"); a `_`-prefixed key is not a substitute, and the value takes part in `modelHash`.')
+  }
+  return steps
+}
+
 export interface ComparisonSummary {
   beforeModelHash: string
   afterModelHash: string
@@ -272,8 +337,178 @@ 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',
+  umlExplainLabels: 'logicprobe/uml/explain-labels/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 +520,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 +661,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 +684,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')
@@ -574,57 +813,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.
@@ -838,14 +1079,16 @@ function checkResult(id: string, name: string, findings: Finding[], detail: stri
   return {
     id,
     name,
-    status: findings.length === 0 ? 'pass' : 'fail',
+    // An info finding is a note, not a defect: it must not flip a check to `fail`, or the
+    // check would be dragged into the "resolve the failing checks" list for a remark.
+    status: errors + warnings === 0 ? 'pass' : 'fail',
     detail: detail + (errors > 0 ? ' (' + errors + ' errors' + (warnings > 0 ? ', ' + warnings + ' warnings' : '') + ')' : warnings > 0 ? ' (' + warnings + ' warnings)' : ''),
     findings,
   }
 }
 
 // ---------------------------------------------------------------------------
-// S1-S7
+// S1-S8
 // ---------------------------------------------------------------------------
 
 function S1_reachability(model: LogicModelV1, exploration: Exploration): CheckResult {
@@ -1271,7 +1514,7 @@ function S7_invariants(model: LogicModelV1, options: NormalizedOptions): CheckRe
 }
 
 // ---------------------------------------------------------------------------
-// A1-A7
+// A1-A14
 // ---------------------------------------------------------------------------
 
 function A1_unexpectedEvents(model: LogicModelV1): CheckResult {
@@ -2646,20 +2889,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: [...refusalGuidance(validation.errors), ...verificationNextSteps([modelCheck], undefined)],
     }
   }
   const model = validation.model
@@ -2692,10 +2947,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,
@@ -2711,9 +2974,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
@@ -2729,10 +2993,32 @@ 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)
+  // R3: a partial narrative is valid, but the gap must be machine-readable instead of only a
+  // sentence in `nextSteps`. It rides on S5 — the check that already reports undocumented
+  // (state, event) combinations — so the documented check count stays 22.
+  if (narrativeCoverage !== undefined && !narrativeComplete(narrativeCoverage)) {
+    checks.find((check) => check.id === 'S5')?.findings.push({
+      code: 'NARRATIVE_PARTIAL',
+      severity: 'info',
+      message: 'Narrative coverage is partial (states ' + narrativeCoverage.states + ', events ' + narrativeCoverage.events + ', scenarios ' + narrativeCoverage.scenarios + '): the checks still run over the whole model, but the undocumented symbols have to be re-derived by the reader.',
+    })
+  }
   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,
@@ -2742,6 +3028,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 }),
@@ -2762,6 +3049,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 {
@@ -2774,9 +3063,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 {
@@ -2802,6 +3103,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[] = []
@@ -2811,7 +3113,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 }))
@@ -2821,8 +3123,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 ?? [])
@@ -2881,6 +3189,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()!
@@ -2894,12 +3213,63 @@ 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(', ')))
+      // A non-terminal state with no outgoing transition anywhere in its own model is a
+      // modelling gap, not a design defect: without this note the census reads as
+      // "the architecture deadlocks" when the model was simply left unfinished.
+      const gaps = node.runtimes
+        .map((runtime, index) => ({ index, state: runtime.state }))
+        .filter((entry) => !isTerminal(models[entry.index], entry.state)
+          && !models[entry.index].transitions.some((transition) => transition.from === entry.state))
+      const gapNote = gaps.length === 0
+        ? ''
+        : ' Modelling note: ' + gaps.map((gap) => 'machine ' + String(gap.index) + ' state ' + gap.state).join(', ') + ' has no outgoing transition in its own model, so this deadlock may be a modelling gap rather than a design defect.'
       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(' | ') + gapNote,
+        evidence: { steps: node.path, states: node.runtimes.map((runtime) => runtime.state), depth: node.path.length, perMachine, reasons },
       })
       continue
     }
@@ -2916,22 +3286,83 @@ 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.',
+        severity: 'error',
+        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
+  // C2 is an error, not a warning: a rendezvous that can never fire means the composition
+  // cannot advance through that handshake — the same "stuck forever" outcome C1 reports,
+  // so a gate that only reads `verdict` must be able to stop on it.
+  const errors = c1Findings.length + c2Findings.length
+  const warnings = 0
+  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 errors: ' + 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) {
+    const why = c1Findings.length > 0
+      ? 'the composition deadlocks at a reachable state, so at least one machine is missing an exit or a handshake partner'
+      : 'a rendezvous event can never fire, so the composition cannot advance through that handshake'
+    nextSteps.push('Resolve the error findings first: ' + why + '.')
+  }
+  // Composition couples machines only through rendezvous: each machine's `variables` are
+  // private to it, so two machines cannot share one predicate. Name them when the input
+  // looks like it is trying to (two or more machines each declare variables).
+  const owners = models
+    .map((entry, index) => ({ index, names: (entry.variables ?? []).map((variable) => variable.name) }))
+    .filter((entry) => entry.names.length > 0)
+  if (owners.length >= 2) {
+    nextSteps.push('Each machine\'s variables are private to it (' + owners.map((entry) => 'machine ' + String(entry.index) + ': ' + entry.names.join(', ')).join('; ') + '): composition couples machines only through rendezvous, so a value two machines must agree on has to be modelled as a handshake, or inside a single machine.')
+  }
+  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,
   }
 }