dsh-logicprobe 0.8.1 → 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;
@@ -308,10 +453,36 @@ export function validateModel(input) {
                         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();
+                            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)
@@ -432,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);
+                    });
                 }
             }
         }
@@ -724,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));
@@ -1007,6 +1178,103 @@ function shortestViolationForInvariant(model, options, invariant) {
     }
     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) {
+    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, probability) {
+    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, options) {
+    const init = initialState(model);
+    const visited = new Set([runtimeKey(init)]);
+    const reached = [init];
+    const queue = [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, options, invariant) {
+    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, options, invariant) {
     const init = initialState(model);
     const seenInitially = false;
@@ -1038,10 +1306,12 @@ function shortestEventBeforeStateViolation(model, options, invariant) {
     }
     return undefined;
 }
-function runInvariants(model, options) {
+function runInvariants(model, options, includePathProperties = false) {
     const violations = [];
     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);
     }
@@ -1059,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);
@@ -1415,14 +1685,27 @@ function A6_resourceInjection(model) {
     return checkResult('A6', 'Resource Injection', findings, findings.length === 0 ? 'No resource vulnerabilities detected' : 'Resource failure paths missing: ' + findings.length);
 }
 function A7_shortestViolations(model, options) {
-    const violations = runInvariants(model, options);
-    const findings = 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 = 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',
+            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);
 }
 function mapStateId(mapping, state) {
@@ -1500,6 +1783,25 @@ function mapInvariantForComparison(invariant, mapping) {
         }
         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)' };
 }
 function D2_invariantContinuity(before, after, options, mapping) {
@@ -1541,7 +1843,37 @@ function D2_invariantContinuity(before, after, options, mapping) {
                 continue;
             }
         }
-        const violation = shortestViolationForInvariant(after, options, mapped);
+        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 },
+                });
+            }
+        }
+        // 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',
@@ -1722,15 +2054,27 @@ function S8_monotonicVariables(model) {
     return checkResult('S8', 'Monotonic Variables', findings, findings.length === 0 ? 'Monotonic variables are respected' : 'Monotonic findings: ' + findings.length);
 }
 /**
- * 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) {
+    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) {
+    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
@@ -1741,8 +2085,8 @@ function S8_monotonicVariables(model) {
  * 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, start, target) {
-    if (start.state === target)
+function findLeadsToBadPath(model, start, targets, label) {
+    if (targets.has(start.state))
         return undefined;
     const GRAY = 1;
     const BLACK = 2;
@@ -1759,7 +2103,7 @@ function findLeadsToBadPath(model, start, target) {
             }
             frame.nexts = nexts;
             if (nexts.length === 0)
-                return { path: frame.path, reason: 'Dead end before target ' + target };
+                return { path: frame.path, reason: 'Dead end before target ' + label };
         }
         if (frame.index >= frame.nexts.length) {
             color.set(runtimeKey(frame.runtime), BLACK);
@@ -1769,18 +2113,18 @@ function findLeadsToBadPath(model, start, target) {
         const { next, event } = frame.nexts[frame.index];
         frame.index += 1;
         const step = { from: frame.runtime.state, event, to: next.state };
-        if (next.state === target)
+        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 };
+            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;
 }
 function A9_leadsTo(model, exploration) {
@@ -1788,10 +2132,12 @@ function A9_leadsTo(model, exploration) {
     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',
@@ -2199,21 +2545,11 @@ function computeHitProbability(model, options, targetState) {
 }
 function A13_probability(model, options) {
     const findings = [];
-    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',
@@ -2355,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;
@@ -2401,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,
@@ -2420,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;
@@ -2433,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,
@@ -2446,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 }),
@@ -2463,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 = [];
@@ -2473,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 }));
@@ -2483,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 ?? []);
@@ -2548,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();
@@ -2562,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;
         }
@@ -2589,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,
     };
 }