dsh-logicprobe 0.9.0 → 1.0.0

package/lib/engine.js

@@ -35,6 +35,24 @@ const MODEL_KEYS = {
     narrative: new Set(['states', 'events', 'scenarios']),
     scenario: new Set(['from', 'event', 'scenario']),
 };
+/**
+ * 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, coverage) {
+    const steps = [];
+    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;
+}
 const DEFAULT_MAX_STATES = 10_000;
 const DEFAULT_MAX_PERMUTATION_EVENTS = 5;
 function stableStringify(value) {
@@ -45,8 +63,131 @@ function stableStringify(value) {
     const record = value;
     return '{' + Object.keys(record).sort().map((key) => JSON.stringify(key) + ':' + stableStringify(record[key])).join(',') + '}';
 }
-export function modelHash(model) {
-    return createHash('sha256').update(stableStringify(model)).digest('hex');
+export function modelHash(model, spec = DEFAULT_HASH_SPEC) {
+    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) {
+    return stableStringify(value);
+}
+export const PUBLISHED_HASH_SPECS = ['v0', 'v1'];
+export const DEFAULT_HASH_SPEC = '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',
+};
+export function narrativeCoverageOf(model) {
+    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) {
+    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];
+}
+/** A tool that refused the request before running anything: it neither passed nor failed a review. */
+export function refusalVerdict(reason) {
+    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, warnings, firstCode) {
+    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) {
+    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) {
+    const keys = [];
+    const walk = (value, path) => {
+        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)) {
+            const child = path === '' ? key : path + '.' + key;
+            if (key.startsWith('_'))
+                keys.push(child);
+            walk(entry, child);
+        }
+    };
+    walk(input, '');
+    return keys.sort();
+}
+function withoutMetadata(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((entry) => withoutMetadata(entry));
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        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, spec = DEFAULT_HASH_SPEC) {
+    return spec === 'v1' ? withoutMetadata(model) : model;
 }
 export function validateModel(input) {
     const errors = [];
@@ -57,8 +198,12 @@ export function validateModel(input) {
         return { ok: false, errors: ['model: must be an object'] };
     }
     const root = input;
+    // `_`-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, allowed, path) => {
-        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(', ') + ')');
         }
@@ -239,7 +384,7 @@ export function validateModel(input) {
                 // older reader may not know are skipped so they still fail on `.kind` alone.
                 if (KNOWN_INVARIANT_KINDS.has(invariant.kind)) {
                     const allowed = INVARIANT_KEYS[invariant.kind];
-                    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(', ') + ')');
                     }
@@ -271,7 +416,7 @@ export function validateModel(input) {
                         else if ('state' in when) {
                             const scope = when;
                             for (const key of Object.keys(scope)) {
-                                if (key !== 'state')
+                                if (key !== 'state' && !key.startsWith('_'))
                                     bad(path + '.when.' + key, 'unknown field for a state scope (allowed: state)');
                             }
                             const state = scope.state;
@@ -458,70 +603,70 @@ export function validateModel(input) {
             rejectUnknownKeys(narrative, MODEL_KEYS.narrative, narrativePath);
             const stateIds = new Set(Array.isArray(root.states) ? root.states.map((state) => state.id) : []);
             const eventIds = new Set(Array.isArray(root.transitions) ? root.transitions.map((transition) => transition.event) : []);
-            const fromEventGroups = new Set(Array.isArray(root.transitions) ? root.transitions.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');
+            // 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'].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)');
             }
-            else {
-                for (const [id, description] of Object.entries(narrative.states)) {
-                    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 (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');
                 }
-                for (const id of stateIds) {
-                    if (typeof narrative.states[id] !== 'string')
-                        bad(narrativePath + '.states', 'missing description for state ' + id);
+                else {
+                    for (const [id, description] of Object.entries(narrative.states)) {
+                        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 (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)) {
-                    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.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');
                 }
-                for (const id of eventIds) {
-                    if (typeof narrative.events[id] !== 'string')
-                        bad(narrativePath + '.events', 'missing description for event ' + id);
+                else {
+                    for (const [id, description] of Object.entries(narrative.events)) {
+                        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 (!Array.isArray(narrative.scenarios)) {
-                bad(narrativePath + '.scenarios', 'must be an array of { from, event, scenario }');
-            }
-            else {
-                const seen = new Set();
-                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;
-                    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.scenarios !== undefined) {
+                if (!Array.isArray(narrative.scenarios)) {
+                    bad(narrativePath + '.scenarios', 'must be an array of { from, event, scenario }');
+                }
+                else {
+                    const seen = new Set();
+                    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;
+                        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);
+                    });
                 }
             }
         }
@@ -750,7 +895,7 @@ function checkResult(id, name, findings, detail) {
     };
 }
 // ---------------------------------------------------------------------------
-// S1-S7
+// S1-S8
 // ---------------------------------------------------------------------------
 function S1_reachability(model, exploration) {
     const reached = new Set(exploration.reachable.map((runtime) => runtime.state));
@@ -1184,7 +1329,7 @@ function S7_invariants(model, options) {
     return checkResult('S7', 'Invariant Validity', findings, violations.length === 0 ? 'All invariants hold' : 'Invariant violations: ' + violations.length);
 }
 // ---------------------------------------------------------------------------
-// A1-A7
+// A1-A14
 // ---------------------------------------------------------------------------
 function A1_unexpectedEvents(model) {
     const events = allEvents(model);
@@ -2546,20 +2691,32 @@ export function runVerification(input, options = {}) {
         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 = validation.errors.map((message) => ({ code: 'MODEL_INVALID', severity: 'error', message }));
+        const modelCheck = {
+            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;
@@ -2592,10 +2749,18 @@ export function runVerification(input, options = {}) {
     if (options.beforeModel !== undefined) {
         const beforeValidation = validateModel(options.beforeModel);
         if (!beforeValidation.ok) {
+            const beforeFindings = beforeValidation.errors.map((message) => ({ code: 'BEFORE_MODEL_INVALID', severity: 'error', message }));
+            const allFindings = [...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,
@@ -2611,9 +2776,10 @@ export function runVerification(input, options = {}) {
                         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;
@@ -2624,10 +2790,22 @@ export function runVerification(input, options = {}) {
     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,
@@ -2637,6 +2815,7 @@ export function runVerification(input, options = {}) {
             truncated: exploration.truncated,
         },
         checks,
+        nextSteps: verificationNextSteps(checks, narrativeCoverage),
         ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
         ...(comparison === undefined ? {} : { comparison }),
         ...(coverageNotes.length === 0 ? {} : { coverageNotes }),
@@ -2654,6 +2833,7 @@ export function runVerification(input, options = {}) {
  * least one is not terminal) and C2 rendezvous that can never fire.
  */
 export function runCompositionVerification(machinesInput, options = {}) {
+    const hashSpec = options.hashSpec ?? DEFAULT_HASH_SPEC;
     const models = [];
     const hashes = [];
     const modelFindings = [];
@@ -2664,7 +2844,7 @@ export function runCompositionVerification(machinesInput, options = {}) {
         }
         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 }));
@@ -2674,8 +2854,14 @@ export function runCompositionVerification(machinesInput, options = {}) {
         }
         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 ?? []);
@@ -2739,6 +2925,17 @@ export function runCompositionVerification(machinesInput, options = {}) {
     const firedCount = new Map();
     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();
+    const enabledStates = new Map();
+    const coEnabledNodes = new Map();
+    for (const event of rendezvous) {
+        everEnabled.set(event, new Set());
+        enabledStates.set(event, models.map(() => []));
+        coEnabledNodes.set(event, 0);
+    }
     const c1Findings = [];
     while (queue.length > 0) {
         const node = queue.shift();
@@ -2753,12 +2950,66 @@ export function runCompositionVerification(machinesInput, options = {}) {
         }
         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 = [];
+            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 = [];
+                    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;
         }
@@ -2780,22 +3031,71 @@ export function runCompositionVerification(machinesInput, options = {}) {
         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;
+            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('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 = [];
+    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,
     };
 }