dsh-model-everything 0.0.0-stage → 0.2.0

package/lib/baseline.js

@@ -0,0 +1,249 @@
+/**
+ * Report diffing: "did this slice add findings, or remove them?"
+ *
+ * The acceptance criterion of a refactoring slice is usually *not* "zero findings" —
+ * it is "no NEW findings, and none of the old ones got worse". Comparing two JSON
+ * reports by hand is how that gets fudged, so the comparison is code.
+ *
+ * A finding's identity is its machine-readable locator, never its prose:
+ * `check|code|<canonical evidence + path>`. Findings that carry neither evidence nor a
+ * path fall back to their message, because an engine that reports nothing structured
+ * has nothing stabler to match on. Two runs over the same input must produce zero
+ * added and zero removed findings.
+ *
+ * @module dsh-model-everything-baseline
+ */
+import { canonicalJson, REPORT_SCHEMAS, verdictOf } from './engine.js';
+/**
+ * The stable identity of a finding: check + file + code + a canonical locator. Prose is
+ * excluded so a reworded message reads as `changed`, not as a new finding.
+ */
+export function findingIdentity(finding) {
+    const locator = canonicalJson({
+        ...(finding.evidence === undefined ? {} : { evidence: finding.evidence }),
+        ...(finding.path === undefined ? {} : { path: finding.path }),
+    });
+    const where = locator === '{}' ? 'message:' + finding.message : locator;
+    const file = finding.file === undefined ? '' : finding.file + '|';
+    return (finding.check === undefined ? '' : finding.check + '|') + file + finding.code + '|' + where;
+}
+/** Flatten a report of any family into one finding list (`checks[].findings` or `findings[]`). */
+export function flattenReportFindings(report) {
+    if (report === null || typeof report !== 'object')
+        return [];
+    const record = report;
+    const flat = [];
+    if (Array.isArray(record.checks)) {
+        for (const check of record.checks) {
+            const id = typeof check.id === 'string' ? check.id : undefined;
+            for (const finding of (Array.isArray(check.findings) ? check.findings : [])) {
+                flat.push(id === undefined ? finding : { ...finding, check: id });
+            }
+        }
+    }
+    if (Array.isArray(record.findings)) {
+        for (const finding of record.findings)
+            flat.push(finding);
+    }
+    return flat;
+}
+/** The report's own verdict, whatever family it came from. */
+function verdictOfReport(report) {
+    if (report === null || typeof report !== 'object')
+        return 'fail';
+    const value = report.verdict;
+    return value === 'pass' || value === 'pass_with_findings' || value === 'fail' ? value : 'fail';
+}
+/**
+ * The delta's verdict, from the four ways a comparison can get worse or better.
+ *
+ * `escalated` is the one that used to be missing: a finding that keeps its identity and moves from warning to
+ * error lives in `changed`, not in `added`, so folding severities into `addedErrors` only left the comparison
+ * answering `pass` over a change that made the report strictly worse. A de-escalation is not a regression: it is
+ * still a change, so it is named, and the verdict stays `pass`.
+ */
+function diffOf(added, removed, addedErrors, escalated, deescalated, firstCode) {
+    const errors = addedErrors + escalated;
+    if (errors > 0) {
+        const bits = [];
+        if (added > 0)
+            bits.push(String(added) + ' new finding(s)');
+        if (escalated > 0)
+            bits.push(String(escalated) + ' finding(s) escalated to error');
+        return {
+            verdict: 'fail',
+            // The count of errors is the sum: a reader must not have to add "new" and "escalated" in their head.
+            verdictReason: bits.join(', ') + ' (' + String(errors) + ' error)' + (firstCode === undefined ? '' : ' (first error: ' + firstCode + ')'),
+        };
+    }
+    if (added > 0) {
+        return {
+            verdict: 'pass_with_findings',
+            verdictReason: String(added) + ' new warning finding(s), no new errors' + (deescalated > 0 ? '; ' + String(deescalated) + ' finding(s) moved to a lower severity' : ''),
+        };
+    }
+    if (removed > 0) {
+        return { verdict: 'pass', verdictReason: 'no new findings; ' + String(removed) + ' finding(s) resolved' };
+    }
+    if (deescalated > 0) {
+        return { verdict: 'pass', verdictReason: 'no new findings; ' + String(deescalated) + ' finding(s) moved to a lower severity' };
+    }
+    return { verdict: 'pass', verdictReason: 'no new findings, nothing resolved' };
+}
+/**
+ * Compare a baseline report with the current one. The verdict describes the *delta*
+ * (a new error fails it), while `currentVerdict` keeps the absolute result visible.
+ */
+/**
+ * Whether a value is a report this can compare.
+ *
+ * `diffReports(null, null)` answered `verdict: 'pass'`. With no inputs, every comparison found
+ * nothing to compare and the report said the two agree - the worst shape of a false green, because
+ * the absence of an input reads as agreement. A caller who passed the wrong variable would take
+ * that verdict at face value.
+ *
+ * The first fix refused only `null` and `undefined`, on the argument that a present-but-wrong value
+ * still carries `currentVerdict: 'fail'` and the delta is honestly empty. Running the installed
+ * plugin disproved that: `report_diff` with two `'junk'` strings answered `verdict: pass`, and
+ * `verdict` is the field a reader is told to act on. A mitigation in a field the reader is told to
+ * ignore is not a mitigation.
+ *
+ * The second fix required "an object", which moved the hole rather than closing it: `{}` is an object,
+ * has no findings, and two of them compare as agreement. A guard is only as deep as its requirement,
+ * so the requirement is now what the name promises - an object that carries at least one report field.
+ * A partial report still passes, because `findings` alone is one.
+ */
+const REPORT_FIELDS = ['schema', 'verdict', 'ran', 'ok', 'checks', 'findings', 'summary', 'hashes', 'currentVerdict', 'added', 'removed'];
+function requireReport(value, role) {
+    if (value === null || value === undefined) {
+        throw new Error(role + ' is ' + String(value) + '. A diff needs both sides: with no input at all, every comparison finds nothing and the report reads as agreement between two things that were never compared.');
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(role + ' is a ' + typeof value + (Array.isArray(value) ? ' (an array)' : '') + ', not a report. A diff needs two report objects: two values that are not reports flatten to two empty finding lists, and the delta then reads as agreement between things that were never compared.');
+    }
+    const record = value;
+    if (!REPORT_FIELDS.some((field) => field in record)) {
+        const keys = Object.keys(record);
+        throw new Error(role + ' is an object with no report fields' + (keys.length === 0 ? ' at all' : ' (' + keys.slice(0, 6).join(', ') + ')') + ', not a report. Two such values flatten to two empty finding lists, and the delta then reads as agreement between things that were never compared.');
+    }
+    return record;
+}
+/**
+ * Why a report-shaped value still must not be compared, or `undefined` if it can be.
+ *
+ * Two shapes reach here legitimately and neither is a report about a model:
+ *
+ * - a REFUSAL (`ran: false`): the tool did not run, so there is nothing to compare against;
+ * - a report about an INVALID INPUT (`summary.checksRun === 0`): the engine ran, refused the input, and
+ *   examined nothing. Its finding list is not empty because the model is clean, and comparing it against
+ *   a real report would call every finding in that report resolved.
+ *
+ * `checksRun` is read only when the report carries it, because the families that report flat findings
+ * have no check roster and `compose` counts machines rather than checks.
+ */
+function incomparableReason(record, role) {
+    if (record.ran === false) {
+        return role + ' is a refusal: the fields describe why the tool did not run, so there is no report to compare';
+    }
+    const summary = record.summary;
+    if (summary !== null && typeof summary === 'object' && summary.checksRun === 0) {
+        return role + ' examined nothing (its summary says checksRun 0), so its empty finding list is not evidence of anything';
+    }
+    return undefined;
+}
+/** The family a report belongs to, when it says so. Two different schemas cannot be compared. */
+function familyOf(record) {
+    return typeof record.schema === 'string' && record.schema !== '' ? record.schema : undefined;
+}
+export function diffReports(baseline, current) {
+    const beforeRecord = requireReport(baseline, 'baseline');
+    const afterRecord = requireReport(current, 'current');
+    for (const [record, role] of [[beforeRecord, 'baseline'], [afterRecord, 'current']]) {
+        const reason = incomparableReason(record, role);
+        if (reason !== undefined)
+            throw new Error(reason + '. A diff needs two runs that produced reports.');
+    }
+    const beforeFamily = familyOf(beforeRecord);
+    const afterFamily = familyOf(afterRecord);
+    if (beforeFamily !== undefined && afterFamily !== undefined && beforeFamily !== afterFamily) {
+        throw new Error('cannot compare a ' + beforeFamily + ' report with a ' + afterFamily + ' report: they do not share a finding vocabulary, so every finding on one side would read as resolved or added on the other. Compare two runs of the same tool.');
+    }
+    const before = flattenReportFindings(baseline);
+    const after = flattenReportFindings(current);
+    const beforeByIdentity = new Map();
+    for (const finding of before)
+        beforeByIdentity.set(findingIdentity(finding), finding);
+    const seen = new Set();
+    const added = [];
+    const changed = [];
+    for (const finding of after) {
+        const identity = findingIdentity(finding);
+        seen.add(identity);
+        const previous = beforeByIdentity.get(identity);
+        if (previous === undefined) {
+            added.push(finding);
+            continue;
+        }
+        if (previous.severity !== finding.severity || previous.message !== finding.message) {
+            changed.push({
+                identity,
+                code: finding.code,
+                before: { severity: previous.severity, message: previous.message },
+                after: { severity: finding.severity, message: finding.message },
+            });
+        }
+    }
+    const removed = before.filter((finding) => !seen.has(findingIdentity(finding)));
+    const addedErrors = added.filter((finding) => finding.severity === 'error');
+    const addedWarnings = added.filter((finding) => finding.severity === 'warning');
+    // Severity movement lives in `changed`. Counted here, because the verdict is about whether the slice got worse,
+    // and a warning that became an error did - even though nothing was added.
+    const escalated = changed.filter((change) => change.before.severity !== 'error' && change.after.severity === 'error');
+    const deescalated = changed.filter((change) => change.before.severity === 'error' && change.after.severity !== 'error');
+    const delta = diffOf(added.length, removed.length, addedErrors.length, escalated.length, deescalated.length, addedErrors[0]?.code ?? escalated[0]?.code);
+    const nextSteps = [];
+    if (addedErrors.length > 0) {
+        nextSteps.push('Fix or explicitly accept the ' + String(addedErrors.length) + ' new error finding(s) before calling this slice done: the baseline is what "not worse" is measured against.');
+    }
+    else if (escalated.length > 0) {
+        nextSteps.push('A finding moved from warning to error (' + String(escalated.length) + '): the slice added nothing but still made the report worse, so the baseline is less strict than the run.');
+    }
+    else if (added.length > 0) {
+        nextSteps.push('The new warnings are not failures, but they are new: decide per finding whether the change introduced them or the baseline was incomplete.');
+    }
+    else {
+        nextSteps.push('No new findings: re-record the baseline with this report if the slice is accepted, so the next comparison starts from it.');
+    }
+    if (changed.length > 0)
+        nextSteps.push('Review the ' + String(changed.length) + ' changed finding(s): the same locator now reports something different, which usually means the fix moved the problem.');
+    if (removed.length > 0)
+        nextSteps.push(String(removed.length) + ' finding(s) from the baseline are gone — confirm they were fixed rather than renamed out of the report (a renamed check or a reworded message changes the identity).');
+    if (verdictOfReport(current) === 'fail') {
+        // The sentence has to match the delta it sits beside: "the delta being clean" is false when the delta failed,
+        // which is exactly the case an escalation now produces.
+        const deltaClean = delta.verdict === 'pass' || delta.verdict === 'pass_with_findings';
+        nextSteps.push(deltaClean
+            ? 'The current report still fails on its own terms; the delta being clean does not make the run clean.'
+            : 'The current report still fails on its own terms, and the delta already says the slice made it worse: settle both before accepting it.');
+    }
+    return {
+        ok: true,
+        ran: true,
+        ...delta,
+        schema: REPORT_SCHEMAS.baseline,
+        currentVerdict: verdictOfReport(current),
+        added,
+        removed,
+        changed,
+        summary: {
+            baseline: before.length,
+            current: after.length,
+            added: added.length,
+            removed: removed.length,
+            changed: changed.length,
+            addedErrors: addedErrors.length,
+            addedWarnings: addedWarnings.length,
+        },
+        nextSteps,
+    };
+}

package/lib/compose-tool.js

@@ -0,0 +1,80 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runCompositionVerification } from './engine.js';
+import { OptionShapeError, optionRefusal, requireArrayOption } from './option-shape.js';
+import { renderReportText } from './report-view.js';
+export const COMPOSE_TOOL_NAME = 'model_compose_verify';
+/**
+ * DSH tool wrapping multi-machine composition verification:
+ * product-space reachability with rendezvous handshakes (C1 deadlock, C2 sync), and the shared
+ * locations the machines both touch (C3 declarations, C4 unordered write, C5 non-atomic update).
+ */
+export const modelComposeTool = defineTool({
+    name: COMPOSE_TOOL_NAME,
+    description: 'Check two or more LogicModelV1 machines together. Pass the models in `machines`. Pass `rendezvous` for handshake events: these fire only when every declaring machine is enabled at once, and a terminal machine stops taking part. Other events advance one machine, so a machine waiting on a handshake can take any number of its own steps first. There is no rate ratio and no fairness bound. Pass `shared` for locations two machines both touch and `accesses` to say which machine event reads or writes one: C3 reports a declaration that names something the composition does not have, C4 an unordered write to one location both machines write, and C5 a read-modify-write pair the model does not make atomic (the lost-update interleaving). Two accesses that name the same `protectedBy` lock are treated as exclusive; that the lock is held across the whole operation is a single-machine question this tool does not answer. Returns C1 deadlocks (no machine can advance, and one is not terminal) and C2 handshakes that never fire. Both name the reason per machine, and C1 gives the shortest counterexample. `maxStates` caps the search; a capped run says so. It decides what no single machine can show: a handshake that never fires, or a node where no machine may advance because of the others. One machine on its own is `model_verify`. Read `verdict` and `verdictReason`.',
+    parameters: {
+        machines: {
+            type: 'json',
+            required: true,
+            description: 'Array of LogicModelV1 state-machine models to compose (two or more).',
+        },
+        rendezvous: {
+            type: 'json',
+            description: 'Optional array of handshake event names shared by the machines.',
+        },
+        shared: {
+            type: 'json',
+            description: 'Optional array of shared locations: { id, initial? }. Without one, nothing is shared between the machines.',
+        },
+        accesses: {
+            type: 'json',
+            description: 'Optional array of { machine, event, location, kind: "read" | "write" | "read-write", protectedBy? }. A read-write is a read-modify-write: two of them that are not mutually exclusive lose an update.',
+        },
+        maxStates: {
+            type: 'integer',
+            description: 'Maximum composite states to explore. Default 10000.',
+        },
+        check: {
+            type: 'string',
+            description: 'Print one check in full when the digest truncated it. Pass the check id the CHECKS line lists (for example A9); the per-check budget no longer applies, and an id this report does not carry is answered with the ids that it does.',
+        },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured report, which report_diff needs.',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'Composition verification report with C1/C2 findings and, when shared locations are declared, C3/C4/C5.',
+        },
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full', check: args.check }) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        try {
+            // `machines` is declared `json`, so a string reached `machinesInput.forEach` as a raw TypeError. The
+            // array-ness is the tool's contract; check it here and refuse with a code that names the option.
+            requireArrayOption(args.machines, 'machines', 'COMPOSE_OPTION_INVALID');
+            if (args.machines !== undefined && args.machines.length === 0) {
+                throw new OptionShapeError('COMPOSE_OPTION_INVALID', 'machines is an empty array. A composition needs at least two machines to compose; with none there is nothing to decide.');
+            }
+            if (args.shared !== undefined)
+                requireArrayOption(args.shared, 'shared', 'COMPOSE_OPTION_INVALID');
+            if (args.accesses !== undefined)
+                requireArrayOption(args.accesses, 'accesses', 'COMPOSE_OPTION_INVALID');
+            return runCompositionVerification(args.machines, {
+                rendezvous: args.rendezvous,
+                shared: args.shared,
+                accesses: args.accesses,
+                maxStates: args.maxStates,
+            });
+        }
+        catch (error) {
+            return optionRefusal(error, 'COMPOSE_OPTION_INVALID');
+        }
+    },
+});

package/lib/concurrency-tool.js

@@ -0,0 +1,40 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runConcurrencyScan } from './concurrency.js';
+import { renderReportText } from './report-view.js';
+export const INTERLEAVING_SCAN_TOOL_NAME = 'model_interleaving_scan';
+/**
+ * Model-visible DSH tool that mines design documents/plans for concurrency-related
+ * claims and risk keywords. It does not prove concurrency safety; it flags terms
+ * such as "thread-safe", "lock-free", "race condition", "atomic", "mutex", etc.,
+ * so the model can either provide dedicated evidence or mark the claim unverified.
+ */
+export const modelConcurrencyScanTool = defineTool({
+    name: INTERLEAVING_SCAN_TOOL_NAME,
+    description: 'Scan a document or plan text for claims about how work is executed: threads, synchronization, async tasks, interrupts, shared state. Use ONLY after confirming the target actually has concurrency requirements or behavior; if the target is purely sequential, do not call this tool. Findings carry a family (threads, synchronization, async, interrupts, shared-state) and an absolute claim is one a plan makes about safety rather than a risk it mentions. Returns keywords like thread-safe, lock-free, wait-free, data race, race condition, atomic, synchronized, mutex, semaphore, spinlock, shared variable, shared memory, reentrant, interrupt-safe, ISR, IRQ, NMI, critical section, disable_irq/enable_irq; async ones such as async, await, promise, event loop, callback, microtask, coroutine, fire-and-forget, backpressure, task queue; and their Chinese counterparts (线程安全, 无数据竞争, 无锁, 互斥, 原子, 并发, 临界区, 异步, 回调, 事件循环, 微任务, 协程, 背压 and so on). Absolute claims (thread-safe, lock-free, no data race, interrupt-safe, ISR-safe, non-blocking, never blocks) are flagged as errors requiring dedicated verification, and each carries suggestions naming the analysis to run instead, chosen by family: TSan/Helgrind/CBMC/TLA+ for threads, RTOS-aware analysis for interrupts, and TLA+/UPPAAL plus a runtime check for async, where a blocking call on the event loop, a missing await and a lock held across an await are invisible to any model. Text with no claim to mine is refused with `CONCURRENCY_NO_CLAIM` rather than reported as clean: a scan of nothing is not a clean bill of health, and that includes text in a vocabulary this scan does not match. This plugin does not prove concurrency safety, and this tool does not check a machine: to decide a protocol it mined, model it and call `model_verify`, or compose two of them with `model_compose_verify`.',
+    parameters: {
+        text: {
+            type: 'string',
+            required: true,
+            description: 'Document or plan text to scan for claims about threads, synchronization, async tasks, interrupts or shared state.',
+        },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured report, which report_diff needs.',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'Concurrency scan report with findings and summary.',
+        },
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        return runConcurrencyScan(args.text);
+    },
+});

package/lib/concurrency.js

@@ -0,0 +1,206 @@
+import { REPORT_SCHEMAS, refusalVerdict, verdictOfFindings } from './engine.js';
+/** How a finding names its family in prose. */
+const FAMILY_WORD = {
+    threads: 'Concurrency',
+    synchronization: 'Synchronization',
+    async: 'Async',
+    interrupts: 'Interrupt',
+    'shared-state': 'Shared-state',
+};
+const KEYWORD_RULES = [
+    // Threads: the vocabulary the scan started with.
+    { pattern: /\bthread\s*-?\s*safe\b/i, label: 'thread-safe', absolute: true, family: 'threads' },
+    { pattern: /\block\s*-?\s*free\b/i, label: 'lock-free', absolute: true, family: 'threads' },
+    { pattern: /\bwait\s*-?\s*free\b/i, label: 'wait-free', absolute: true, family: 'threads' },
+    { pattern: /\bno\s+data\s+race\b/i, label: 'no data race', absolute: true, family: 'threads' },
+    { pattern: /\brace\s*-?\s*free\b/i, label: 'race-free', absolute: true, family: 'threads' },
+    { pattern: /\bdata\s+race\b/i, label: 'data race', absolute: false, family: 'threads' },
+    { pattern: /\brace\s+condition\b/i, label: 'race condition', absolute: false, family: 'threads' },
+    { pattern: /\bthread\s*-?\s*safety\b/i, label: 'thread safety', absolute: false, family: 'threads' },
+    { pattern: /\bconcurrent\b/i, label: 'concurrent', absolute: false, family: 'threads' },
+    { pattern: /\bparallel\b/i, label: 'parallel', absolute: false, family: 'threads' },
+    { pattern: /\bmulti-?threaded\b/i, label: 'multi-threaded', absolute: false, family: 'threads' },
+    { pattern: /\bmultithreaded\b/i, label: 'multithreaded', absolute: false, family: 'threads' },
+    // Synchronization primitives: a claim that names one is a claim about what it protects.
+    { pattern: /\batomic\b/i, label: 'atomic', absolute: false, family: 'synchronization' },
+    { pattern: /\bsynchronized\b/i, label: 'synchronized', absolute: false, family: 'synchronization' },
+    { pattern: /\bmutex\b/i, label: 'mutex', absolute: false, family: 'synchronization' },
+    { pattern: /\bsemaphore\b/i, label: 'semaphore', absolute: false, family: 'synchronization' },
+    { pattern: /\bspinlock\b/i, label: 'spinlock', absolute: false, family: 'synchronization' },
+    { pattern: /\breentrant\b/i, label: 'reentrant', absolute: false, family: 'synchronization' },
+    // Shared state: no primitive named, so the review asks what guards it.
+    { pattern: /\bshared\s+variable\b/i, label: 'shared variable', absolute: false, family: 'shared-state' },
+    { pattern: /\bshared\s+memory\b/i, label: 'shared memory', absolute: false, family: 'shared-state' },
+    { pattern: /\bglobal\s+state\b/i, label: 'global state', absolute: false, family: 'shared-state' },
+    // Interrupts.
+    { pattern: /\binterrupt\s*-?\s*safe\b/i, label: 'interrupt-safe', absolute: true, family: 'interrupts' },
+    { pattern: /\bISR\s*-?\s*safe\b/i, label: 'ISR-safe', absolute: true, family: 'interrupts' },
+    { pattern: /\binterrupt\s+safety\b/i, label: 'interrupt safety', absolute: false, family: 'interrupts' },
+    { pattern: /\binterrupt\s+context\b/i, label: 'interrupt context', absolute: false, family: 'interrupts' },
+    { pattern: /\bISR\b/i, label: 'ISR', absolute: false, family: 'interrupts' },
+    { pattern: /\bIRQ\b/i, label: 'IRQ', absolute: false, family: 'interrupts' },
+    { pattern: /\bNMI\b/i, label: 'NMI', absolute: false, family: 'interrupts' },
+    { pattern: /\bcritical\s+section\b/i, label: 'critical section', absolute: false, family: 'interrupts' },
+    { pattern: /\bdisable_irq\b/i, label: 'disable_irq', absolute: false, family: 'interrupts' },
+    { pattern: /\benable_irq\b/i, label: 'enable_irq', absolute: false, family: 'interrupts' },
+    { pattern: /\bspin_lock_irqsave\b/i, label: 'spin_lock_irqsave', absolute: false, family: 'interrupts' },
+    // Async: a second execution model, with its own failure modes and its own verifiers. These terms were
+    // absent, so an async design mined nothing and was refused as "no claim" - a blind spot that reads as a
+    // clean scan, the same defect the Chinese vocabulary had.
+    { pattern: /\bnon-?\s*blocking\b/i, label: 'non-blocking', absolute: true, family: 'async' },
+    { pattern: /\bnever\s+blocks?\b/i, label: 'never blocks', absolute: true, family: 'async' },
+    { pattern: /\bno\s+blocking\b/i, label: 'no blocking', absolute: true, family: 'async' },
+    { pattern: /\basync\b/i, label: 'async', absolute: false, family: 'async' },
+    { pattern: /\bawait(?:s|ing)?\b/i, label: 'await', absolute: false, family: 'async' },
+    { pattern: /\bpromises?\b/i, label: 'promise', absolute: false, family: 'async' },
+    { pattern: /\bevent\s+loop\b/i, label: 'event loop', absolute: false, family: 'async' },
+    { pattern: /\bcallbacks?\b/i, label: 'callback', absolute: false, family: 'async' },
+    { pattern: /\bmicrotasks?\b/i, label: 'microtask', absolute: false, family: 'async' },
+    { pattern: /\bcoroutines?\b/i, label: 'coroutine', absolute: false, family: 'async' },
+    { pattern: /\bfire\s*-?\s*and\s*-?\s*forget\b/i, label: 'fire-and-forget', absolute: false, family: 'async' },
+    { pattern: /\bbackpressure\b/i, label: 'backpressure', absolute: false, family: 'async' },
+    { pattern: /\btask\s+queue\b/i, label: 'task queue', absolute: false, family: 'async' },
+    // Chinese terms. The vocabulary was English-only, so a Chinese document about the same subject mined
+    // nothing and landed in the no-claim path - a blind spot that read as a clean scan. A negated form is an
+    // absolute claim, and the lookbehind keeps the bare term from firing on the same line as well.
+    { pattern: /线程安全/, label: '线程安全 (thread-safe)', absolute: true, family: 'threads' },
+    { pattern: /无数据竞争/, label: '无数据竞争 (no data race)', absolute: true, family: 'threads' },
+    { pattern: /(?<!无)数据竞争/, label: '数据竞争 (data race)', absolute: false, family: 'threads' },
+    { pattern: /无竞态/, label: '无竞态 (race-free)', absolute: true, family: 'threads' },
+    { pattern: /(?:无锁|免锁)/, label: '无锁 (lock-free)', absolute: true, family: 'threads' },
+    { pattern: /(?:中断安全|ISR安全)/, label: '中断安全 (interrupt-safe)', absolute: true, family: 'interrupts' },
+    { pattern: /竞态条件/, label: '竞态条件 (race condition)', absolute: false, family: 'threads' },
+    { pattern: /并发/, label: '并发 (concurrent)', absolute: false, family: 'threads' },
+    { pattern: /并行/, label: '并行 (parallel)', absolute: false, family: 'threads' },
+    { pattern: /多线程/, label: '多线程 (multi-threaded)', absolute: false, family: 'threads' },
+    { pattern: /原子/, label: '原子 (atomic)', absolute: false, family: 'synchronization' },
+    { pattern: /互斥/, label: '互斥 (mutex)', absolute: false, family: 'synchronization' },
+    { pattern: /信号量/, label: '信号量 (semaphore)', absolute: false, family: 'synchronization' },
+    { pattern: /自旋锁/, label: '自旋锁 (spinlock)', absolute: false, family: 'synchronization' },
+    { pattern: /共享变量/, label: '共享变量 (shared variable)', absolute: false, family: 'shared-state' },
+    { pattern: /共享内存/, label: '共享内存 (shared memory)', absolute: false, family: 'shared-state' },
+    { pattern: /全局状态/, label: '全局状态 (global state)', absolute: false, family: 'shared-state' },
+    { pattern: /可重入/, label: '可重入 (reentrant)', absolute: false, family: 'synchronization' },
+    { pattern: /临界区/, label: '临界区 (critical section)', absolute: false, family: 'interrupts' },
+    { pattern: /关中断/, label: '关中断 (disable interrupt)', absolute: false, family: 'interrupts' },
+    { pattern: /(?:非阻塞|不阻塞|无阻塞|零阻塞)/, label: '非阻塞 (non-blocking)', absolute: true, family: 'async' },
+    { pattern: /异步/, label: '异步 (async)', absolute: false, family: 'async' },
+    { pattern: /回调/, label: '回调 (callback)', absolute: false, family: 'async' },
+    { pattern: /事件循环/, label: '事件循环 (event loop)', absolute: false, family: 'async' },
+    { pattern: /微任务/, label: '微任务 (microtask)', absolute: false, family: 'async' },
+    { pattern: /协程/, label: '协程 (coroutine)', absolute: false, family: 'async' },
+    { pattern: /背压/, label: '背压 (backpressure)', absolute: false, family: 'async' },
+];
+/**
+ * The text to scan, or a refusal naming what arrived instead.
+ *
+ * `runConcurrencyScan(undefined)` threw a read of `split` on undefined. The scan proves nothing
+ * either way, so a caller who passed the wrong variable must be told which one was wrong rather
+ * than left with a crash.
+ */
+function requireScanText(value) {
+    if (typeof value !== 'string') {
+        const arrived = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+        throw new Error('text must be a string to scan, got ' + arrived + '. Pass the source or the notes to scan for concurrency claims.');
+    }
+    return value;
+}
+export function runConcurrencyScan(text) {
+    const source = requireScanText(text);
+    const lines = source.split(/\r?\n/);
+    const findings = [];
+    const seen = new Set();
+    const suggestionsFor = (family) => {
+        if (family === 'async') {
+            return [
+                'TLA+ (exhaustive interleaving), or model_compose_verify for a handshake between two tasks',
+                'model_verify with maxTicks + tickEvents (a timeout is a deadline), or model_export -> UPPAAL for clocks',
+                'A runtime or static check for the three things a model cannot see: a blocking call on the event loop, a missing await (fire-and-forget), a lock held across an await',
+            ];
+        }
+        if (family === 'threads') {
+            return ['TSan / Helgrind (runtime data-race detection)', 'CBMC / static analysis (proof-oriented)', 'TLA+ (exhaustive interleaving model)'];
+        }
+        if (family === 'interrupts') {
+            return ['RTOS-aware analysis (interrupt latency, priority inversion)', 'CBMC (state-machine + ISR interleaving proof)', 'TLA+ (preemption/exclusion model)'];
+        }
+        return ['Dedicated concurrency verification (TSan, CBMC, TLA+, or RTOS-specific analysis)'];
+    };
+    lines.forEach((line, index) => {
+        const lineNumber = index + 1;
+        const lower = line.toLowerCase();
+        for (const rule of KEYWORD_RULES) {
+            if (!rule.pattern.test(line))
+                continue;
+            const key = rule.label + ':' + lineNumber;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const finding = {
+                code: rule.absolute ? 'CONCURRENCY_ABSOLUTE_CLAIM' : 'CONCURRENCY_KEYWORD',
+                severity: rule.absolute ? 'error' : 'warning',
+                message: rule.absolute
+                    ? FAMILY_WORD[rule.family] + ' safety claim "' + rule.label + '" detected; this plugin does not verify it — it needs dedicated verification.'
+                    : FAMILY_WORD[rule.family] + '-related term "' + rule.label + '" detected; review whether the plan addresses this risk.',
+                line: lineNumber,
+                snippet: line.trim().slice(0, 200),
+                keyword: rule.label,
+                family: rule.family,
+                ...(rule.absolute ? { suggestions: suggestionsFor(rule.family) } : {}),
+            };
+            findings.push(finding);
+        }
+    });
+    const families = new Set(findings.map((finding) => finding.family));
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warnings = findings.filter((finding) => finding.severity === 'warning').length;
+    const absoluteClaims = findings.filter((finding) => finding.code === 'CONCURRENCY_ABSOLUTE_CLAIM').length;
+    const nextSteps = [];
+    if (absoluteClaims > 0) {
+        nextSteps.push('Every absolute claim must either cite dedicated evidence (a TSan/Helgrind run, a CBMC harness, a TLA+ model of the interleaving) or be restated as a bounded, testable property.');
+    }
+    if (findings.length > absoluteClaims) {
+        nextSteps.push('Review each flagged keyword: a plan that names shared state, a mutex or an interrupt without a synchronization argument is incomplete, not merely verbose.');
+    }
+    if (families.has('async')) {
+        nextSteps.push('For an async design, three defects are invisible to this scan and to any model: a blocking call on the event loop, an await that never happens (fire-and-forget), and a lock held across an await. Name them in the model, or check them at runtime.');
+    }
+    nextSteps.push('This scan mines claims; it does not prove concurrency safety — route each one to the tool named in its suggestions.');
+    if (findings.length === 0) {
+        // Nothing was mined, so nothing was examined. Reporting `pass` here said "no concurrency problem"
+        // about a text this scan could not see: the same false green as a check that examined nothing, and the
+        // common case, because a plan that is not about concurrency at all lands here too.
+        const reason = 'the text contains no concurrency claim this scan can mine, so there is nothing to scan. It is either not about concurrency, or it is written in a vocabulary this scan does not match: it reads English terms such as mutex, atomic, thread-safe, async, await and event loop, and Chinese ones such as 互斥, 原子, 线程安全 and 事件循环';
+        return {
+            ok: false,
+            ran: false,
+            ...refusalVerdict(reason),
+            schema: REPORT_SCHEMAS.concurrency,
+            errorCode: 'CONCURRENCY_NO_CLAIM',
+            error: reason,
+            findings: [],
+            summary: { lines: lines.length, keywords: 0, absoluteClaims: 0, warnings: 0, errors: 0 },
+            hashes: {},
+            nextSteps: [
+                'If the text does discuss concurrency, name the claim explicitly — the resource, the guard, and what it protects — and scan it again.',
+                'This scan mines claims; it does not prove concurrency safety — route each one to the tool named in its suggestions.',
+            ],
+        };
+    }
+    return {
+        ok: true,
+        ran: true,
+        ...verdictOfFindings(findings),
+        schema: REPORT_SCHEMAS.concurrency,
+        findings,
+        summary: {
+            lines: lines.length,
+            keywords: findings.length,
+            absoluteClaims,
+            warnings,
+            errors,
+        },
+        hashes: {},
+        nextSteps,
+    };
+}