dsh-model-everything 0.0.0-stage → 0.2.0

package/lib/gate.js

@@ -0,0 +1,274 @@
+/**
+ * The gate: one optional routing message, injected once per session.
+ *
+ * Why it exists. Routing works through text: the measured result is that a session asked
+ * to check something loads the skill whose catalog line matches. What that measurement
+ * also showed is the limit - a session that never decides to load anything is never routed,
+ * and the catalog line is cut at 500 characters, so the tail of a long line is invisible at
+ * the moment of choosing. This component carries the routing in a message instead of in the
+ * line, for a deployment that wants the decision made for it.
+ *
+ * Why it is a separate row. The plugin's doctrine is that a capability is discoverable
+ * through its own tool description or skill text. Injection departs from that, so it is
+ * opt-in and mounted as its own component: install it, disable it, or never enable it,
+ * without touching the tools or the skills. `enabled` is a live switch, so the Web Plugins
+ * page flips it inside a running host.
+ *
+ * Why it is off by default. It costs tokens in every session that turns it on, to fix a
+ * problem text-only routing was measured not to have once the session engages. A deployment
+ * that wants it says so; the default pays nothing.
+ *
+ * What it does not do. It routes; it checks nothing. It cannot make a skill load, and it
+ * does not restate the doctrine - the skill bodies carry that, and duplicating them here
+ * would spend the session's context on a second copy.
+ *
+ * @module dsh-model-everything-gate
+ */
+import { readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import z from '@deepseek-ai/schemastery';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+export const name = 'dsh-model-everything-gate';
+/** Producer-owned message source kind declared in `MessageSourceMap` above. */
+const GATE_SOURCE_KIND = 'plugin:dsh-model-everything-gate';
+/**
+ * The default text. It names every skill the package ships, because its job is the routing
+ * the catalog line cannot carry once the line is long; `tests/gate` fails when a skill is
+ * added and this list is not, which is the only thing keeping the two in step.
+ *
+ * The rule is stated at both ends, in different words. That is a measured change, not a
+ * stylistic one: the single-statement version left the one case that needed the plugin - a
+ * migration question the session believed it could answer from memory - with no skill loaded
+ * and no tool run. Stating it at the start and restating it at the end fixed that case and
+ * added no load on a control that must load nothing. Two sentences cost 403 characters; the
+ * comparison is in the routing measurement under "第三臂".
+ */
+/** One row per skill: the request it answers, in the words a user would use. */
+const SKILL_ROWS = {
+    'model-everything': 'claims against code, state machines, protocols',
+    'model-everything-uml': 'drawing a diagram, or reading one someone drew',
+    'model-everything-structure': 'an architecture or dependency drawing',
+    'model-everything-design': 'layering, responsibilities, substitutability, interface width',
+    'model-everything-datamodel': 'a schema, a migration, a data guarantee',
+    'model-everything-interleaving': 'thread-safe, lock-free, ISR, async interleaving; a shared location is decided, the rest is routed',
+    'model-everything-report-reading': 'reading a report this plugin returned',
+};
+/**
+ * The skills this package actually ships, read from disk when the module loads.
+ *
+ * The table below advertises only these. A row for a skill that is not in the package sends the
+ * model to a name that resolves to nothing, which is the one failure a routing message must not
+ * have; a skill added without a row still gets an entry, reading "see its catalog line", so the
+ * table can be incomplete but never wrong.
+ */
+export function shippedSkills() {
+    try {
+        return readdirSync(fileURLToPath(new URL('../skills/', import.meta.url)), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The text, rendered from the skills that ship.
+ *
+ * The rule is stated at both ends, in different words. That is a measured change, not a stylistic
+ * one: with a single statement, the one case that needed the plugin - a migration question the
+ * session believed it could answer from memory - loaded no skill and ran no tool. Stated at the
+ * start and restated at the end, it did both, and a control task was not over-triggered.
+ *
+ * The shape follows a neighbouring plugin's injected section: a table that chooses between near-equals,
+ * rows only for what is installed, and a rule against degrading silently when a tool refuses.
+ *
+ * @param skills - the skills to advertise; defaults to the ones on disk.
+ * @param extraGuidance - a deployment's own sentence, appended last.
+ */
+export function renderGateText(skills = shippedSkills(), extraGuidance = '') {
+    const rows = skills.map((skill) => '| ' + (SKILL_ROWS[skill] ?? 'see its catalog line') + ' | `' + skill + '` |');
+    const extra = extraGuidance.trim();
+    return `<EXTREMELY_IMPORTANT>
+Before answering anything about code, a design or a diagram: load the skill whose row matches, and let its tool decide. Do not answer from memory first.
+
+Plugin dsh-model-everything is active. It checks claims about designs and code: facts against the source, behaviour as an executable model, structure as a graph.
+
+**Unsure which row applies?** Load \`model-everything\` first: it owns the doctrine, the model schema and the routing to its siblings.
+
+| The request | The skill |
+| --- | --- |
+${rows.join('\n')}
+
+**Tools** (dsh):
+
+- \`model_verify\` — one state machine: structural checks, adversarial probes, budgets, deadlines, before/after regression.
+- \`model_compose_verify\` — two or more machines: deadlock, a rendezvous that never fires, and - with \`shared\` + \`accesses\` - an unordered write (C4) or a non-atomic update (C5).
+- \`model_datamodel_verify\` — a data model and its migration: keys, domains, migration coverage, copy consistency, rollback symmetry.
+- \`model_design_review\` — a design against its own declarations: layering, boundaries, substitutability, interface width. The graph's shape is reported, not judged.
+- \`model_interleaving_scan\` — finds claims about threads, synchronization, async and interrupts, names the family, and routes each to the tool that decides it. It proves nothing about any of them.
+- \`model_export\` — UPPAAL, TLA+, PRISM or SPIN input from a verified model. It exports; it does not check the target tool.
+- \`uml_render\`, \`uml_parse\`, \`uml_review\` — draw a model, read a diagram into one, audit one. Round-trip fidelity is measured, never assumed.
+- \`uml_explain_labels\` — the accepted label and comment forms for one notation.
+- \`uml_structure_verify\` — dependency review of a structure drawing, one level or several. It audits the drawing, not the code.
+- \`report_diff\` — baseline against current: what a change added, removed or changed.
+
+**Read a report**: gate on \`verdict\` (\`pass\`, \`pass_with_findings\`, \`fail\`), never on \`ok\`. \`verdictReason\` says why and \`nextSteps\` says what to do. \`ran\` says whether it executed, \`checksRun\` how much it examined: a \`skip\` is not a \`pass\`, and a code ending \`_UNDECIDED\` means the search hit its limit and decided nothing. Keys starting with \`_\` are notes: ignored, and left out of the model hash.
+
+**When a tool refuses, or is not there.** Read its \`errorCode\` and fix the input before retrying; if the tool is not registered in this deployment, say so and use the general method. A check that nothing ran is not a passing check.${extra === '' ? '' : '\n\n' + extra}
+
+The rule again, because it is the one that gets skipped: before answering anything about code, a design or a diagram, load the skill whose routing applies and let its tool decide - a claim you can check is not a claim you may answer from memory.
+</EXTREMELY_IMPORTANT>`;
+}
+/** The shipped default: every row the package can advertise, no deployment guidance. */
+export const DEFAULT_GATE_TEXT = renderGateText();
+function live(field) {
+    const probe = field;
+    return typeof probe.volatile === 'function' ? probe.volatile() : field;
+}
+export const Config = z.object({
+    // On by default, and live so a deployment can turn it off without a restart. The comparison that
+    // decided this is in the routing measurement: at 2933 characters it fixed the one request class
+    // the plugin otherwise never reached, and a control task was not over-triggered.
+    enabled: live(z.boolean().default(true)),
+    // Not volatile on purpose: the settings projection feeds a GUI form, and a kilobyte of
+    // prose does not belong in one.
+    gateContent: z.string().default(DEFAULT_GATE_TEXT),
+    // A neighbour's technique, adopted: a short free-text slot a deployment can use for its own
+    // rule without forking the package. Appended last, so it is read after the routing.
+    extraGuidance: z.string().default(''),
+});
+/**
+ * Read the switch as a boolean, whichever shape this host produced.
+ * @param config - the resolved plugin configuration.
+ * @returns whether the gate may be injected.
+ */
+function injectionEnabled(config) {
+    const value = config.enabled;
+    return typeof value === 'boolean' ? value : value.get();
+}
+function gateText(config) {
+    const extra = typeof config.extraGuidance === 'string' ? config.extraGuidance.trim() : '';
+    return extra === '' ? config.gateContent : config.gateContent + '\n\n' + extra;
+}
+function gateMessage(text) {
+    return createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: GATE_SOURCE_KIND },
+    });
+}
+function readSessionEvents(session) {
+    const source = session;
+    if (typeof source.snapshotEvents === 'function') {
+        const snapshot = source.snapshotEvents();
+        if (Array.isArray(snapshot))
+            return snapshot;
+    }
+    if (Array.isArray(source.events))
+        return source.events;
+    return [];
+}
+/**
+ * Whether the gate already entered this session's durable history. The pre-step listener
+ * re-appends the gate until it does; once a step committed it, every later step - and a
+ * resume of a session that kept it - skips the injection. A gate dropped before any step
+ * ran simply re-injects on the first step that does.
+ * @param session - the agent's session.
+ * @returns whether a gate message is already in the log.
+ */
+function gateInHistory(session) {
+    return readSessionEvents(session).some((event) => {
+        if (event.type !== 'user/message')
+            return false;
+        const source = event.data?.source;
+        return source?.kind === GATE_SOURCE_KIND;
+    });
+}
+/**
+ * Model-visible status, so "is the gate on" is answered by inspection rather than by reading
+ * a session transcript. A separate provider id from the main row: these are two components,
+ * and one of them being mounted says nothing about the other.
+ * @param config - the resolved plugin configuration.
+ * @returns the inspect provider registration.
+ */
+function inspectProvider(config) {
+    return {
+        manifest: {
+            id: 'dsh-model-everything-gate',
+            description: 'The optional session-start routing message of dsh-model-everything: whether it is injected, and how much text it costs. It routes a request to a skill; it checks nothing.',
+            methods: [
+                {
+                    name: 'status',
+                    description: 'Read the gate status: whether injection is enabled and how long the injected text is.',
+                    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+                    outputSchema: {
+                        type: 'object',
+                        description: 'Gate status.',
+                        properties: {
+                            enabled: { type: 'boolean', description: 'Whether the gate is injected into new sessions.' },
+                            gateContentLength: { type: 'integer', description: 'Length in characters of the injected text.' },
+                        },
+                        additionalProperties: false,
+                    },
+                },
+            ],
+        },
+        query: async (method) => {
+            if (method === 'status') {
+                return {
+                    enabled: injectionEnabled(config),
+                    gateContentLength: config.gateContent.length,
+                };
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Mount the gate.
+ *
+ * The listener is registered whether or not the switch is on: the switch is volatile, so
+ * `apply` runs once and the value behind it can turn on later from the Plugins page.
+ * Returning early here would freeze the decision for the lifetime of the mount.
+ *
+ * @param ctx - the plugin context.
+ * @param config - the resolved plugin configuration.
+ */
+export function apply(ctx, config) {
+    // Catalog visibility is optional and the registry may be mounted after this row applies,
+    // so registration is retried on each step until it lands.
+    let providerRegistered = false;
+    const registerProvider = () => {
+        if (providerRegistered)
+            return;
+        const inspect = ctx.get('cordisInspect');
+        if (inspect === undefined)
+            return;
+        try {
+            ctx.effect(() => inspect.register(inspectProvider(config)), 'dsh-model-everything-gate: inspect provider');
+            providerRegistered = true;
+        }
+        catch (error) {
+            console.warn('[dsh-model-everything-gate] inspect provider registration failed', error);
+        }
+    };
+    registerProvider();
+    // Inject on the FIRST model step that runs, instead of at session start: a session-start
+    // message lands in the inbox, which a blank-session preset switch can clear before the
+    // first step. The pre-step decision is durable - the message enters history with the step,
+    // and the guard below stops it from being added a second time.
+    ctx.on('agent/pre-step', async ({ agent }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject')
+            return decision;
+        registerProvider();
+        if (!injectionEnabled(config))
+            return decision;
+        if (gateInHistory(agent.session))
+            return decision;
+        return {
+            kind: 'enter',
+            messages: [...decision.messages, gateMessage(gateText(config))],
+        };
+    });
+}

package/lib/granularity.js

@@ -0,0 +1,237 @@
+/**
+ * Multi-granularity structure review: one architecture, several levels of detail.
+ *
+ * A module diagram and the repository-wide diagram it belongs to are two views of one
+ * fact, and nothing keeps them in step — the child grows a dependency the parent never
+ * had, or the parent keeps an arrow the child quietly stopped drawing. This module
+ * checks that a child diagram is a **refinement** of its declared parent:
+ *
+ * - every dependency the child draws between two nodes the parent also has must exist in
+ *   the parent (nothing appears out of nowhere);
+ * - an edge the parent draws and the child does not must be *expanded* in the child, i.e.
+ *   a child path must connect the same two ends;
+ * - the declared parent relation must be a forest, not a cycle.
+ *
+ * Every per-diagram structural check still runs, and its findings are tagged with the
+ * diagram they came from (`file`), so one report can carry several diagrams without the
+ * findings becoming anonymous.
+ *
+ * @module this plugin-granularity
+ */
+import { createHash } from 'node:crypto';
+import { REPORT_SCHEMAS, canonicalJson, verdictOfFindings } from './engine.js';
+import { parseStructure, reviewStructure } from './structure.js';
+/** Reachability in one diagram, ignoring edge direction? No: a dependency path is directed. */
+function reaches(graph, from, to) {
+    const adjacency = new Map();
+    for (const node of graph.nodes)
+        adjacency.set(node.id, []);
+    for (const edge of graph.edges)
+        adjacency.get(edge.from)?.push(edge.to);
+    const seen = new Set([from]);
+    const queue = [from];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const next of adjacency.get(current) ?? []) {
+            if (next === to)
+                return true;
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            queue.push(next);
+        }
+    }
+    return false;
+}
+/** The parent relation must be a forest: report the first cycle it contains, if any. */
+function parentCycle(diagrams) {
+    const byName = new Map(diagrams.map((entry) => [entry.name, entry]));
+    for (const start of diagrams) {
+        const path = [start.name];
+        const seen = new Set([start.name]);
+        let cursor = start.parent;
+        while (cursor !== undefined) {
+            if (seen.has(cursor)) {
+                path.push(cursor);
+                return path;
+            }
+            seen.add(cursor);
+            path.push(cursor);
+            cursor = byName.get(cursor)?.parent;
+        }
+    }
+    return undefined;
+}
+/**
+ * Review a set of structure diagrams with declared parent relations. Per-diagram
+ * structural checks run first; the cross-diagram refinement checks follow.
+ */
+export function reviewGranularity(options) {
+    const diagrams = options.diagrams;
+    const findings = [];
+    const warnings = [];
+    const diagramSummaries = [];
+    const graphs = new Map();
+    if (diagrams.length === 0) {
+        findings.push({ code: 'UML031_NO_DIAGRAMS', severity: 'error', message: 'no diagram was supplied, so there are no granularity levels to compare.' });
+    }
+    const cycle = parentCycle(diagrams);
+    if (cycle !== undefined) {
+        findings.push({
+            code: 'UML030_PARENT_CYCLE',
+            severity: 'error',
+            message: 'the declared parent relation has a cycle: ' + cycle.join(' → ') + '. A refinement hierarchy must be a forest, or "which level owns this dependency" has no answer.',
+            evidence: { cycle },
+        });
+    }
+    const knownNames = new Set(diagrams.map((entry) => entry.name));
+    for (const entry of diagrams) {
+        if (entry.parent !== undefined && !knownNames.has(entry.parent)) {
+            findings.push({
+                code: 'UML028_UNKNOWN_PARENT',
+                severity: 'error',
+                message: 'diagram "' + entry.name + '" declares parent "' + entry.parent + '", which is not part of this set.',
+                file: entry.name,
+                evidence: { diagram: entry.name, parent: entry.parent, known: [...knownNames].sort() },
+            });
+        }
+        const report = reviewStructure({
+            diagram: entry.diagram,
+            notation: options.notation ?? 'auto',
+            ...(options.matrix === undefined ? {} : { matrix: options.matrix }),
+        });
+        graphs.set(entry.name, report.graph);
+        // Tag every finding with the diagram it came from: with several diagrams in one
+        // report, an untagged finding is unactionable.
+        for (const finding of report.findings) {
+            findings.push({ ...finding, file: entry.name, ...(finding.evidence === undefined ? {} : {}) });
+        }
+        warnings.push(...report.warnings.map((warning) => entry.name + ': ' + warning));
+        diagramSummaries.push({
+            name: entry.name,
+            ...(entry.parent === undefined ? {} : { parent: entry.parent }),
+            notation: report.notation,
+            nodes: report.summary.nodes,
+            edges: report.summary.edges,
+            verdict: report.verdict,
+            findings: report.findings.length,
+        });
+    }
+    const pairs = [];
+    for (const child of diagrams) {
+        if (child.parent === undefined)
+            continue;
+        const parent = diagrams.find((entry) => entry.name === child.parent);
+        const parentGraph = graphs.get(child.parent);
+        const childGraph = graphs.get(child.name);
+        if (parent === undefined || parentGraph === undefined || childGraph === undefined)
+            continue;
+        const parentNodes = new Set(parentGraph.nodes.map((node) => node.id));
+        const childNodes = new Set(childGraph.nodes.map((node) => node.id));
+        const parentEdges = new Set(parentGraph.edges.map((edge) => edge.from + '\u0000' + edge.to));
+        const childEdges = new Set(childGraph.edges.map((edge) => edge.from + '\u0000' + edge.to));
+        let inheritedEdges = 0;
+        let newEdges = 0;
+        const inventedEdges = [];
+        for (const edge of childGraph.edges) {
+            const hasFrom = parentNodes.has(edge.from);
+            const hasTo = parentNodes.has(edge.to);
+            if (!hasFrom || !hasTo) {
+                newEdges += 1;
+                continue;
+            }
+            if (parentEdges.has(edge.from + '\u0000' + edge.to)) {
+                inheritedEdges += 1;
+                continue;
+            }
+            inventedEdges.push({ from: edge.from, to: edge.to, line: edge.line });
+        }
+        const expandedEdges = [];
+        const missingEdges = [];
+        for (const edge of parentGraph.edges) {
+            const key = edge.from + '\u0000' + edge.to;
+            if (childEdges.has(key))
+                continue;
+            // The child only has to answer for a parent edge whose ends it also carries; a child
+            // may legitimately cover a subtree of the parent.
+            if (!childNodes.has(edge.from) || !childNodes.has(edge.to))
+                continue;
+            if (reaches(childGraph, edge.from, edge.to))
+                expandedEdges.push({ from: edge.from, to: edge.to, line: edge.line });
+            else
+                missingEdges.push({ from: edge.from, to: edge.to, line: edge.line });
+        }
+        if (inventedEdges.length > 0) {
+            findings.push({
+                code: 'UML029_REFINEMENT_VIOLATION',
+                severity: 'error',
+                message: 'diagram "' + child.name + '" draws ' + String(inventedEdges.length) + ' dependency(ies) between nodes its parent "' + parent.name + '" also has, but the parent does not: ' + inventedEdges.map((edge) => edge.from + ' → ' + edge.to).join(', ') + '. A refinement may add detail below the parent level, never a dependency at the parent level.',
+                file: child.name,
+                evidence: { kind: 'invented-edge', parent: parent.name, edges: inventedEdges },
+            });
+        }
+        if (missingEdges.length > 0) {
+            findings.push({
+                code: 'UML029_REFINEMENT_VIOLATION',
+                severity: 'error',
+                message: 'diagram "' + child.name + '" drops ' + String(missingEdges.length) + ' dependency(ies) its parent "' + parent.name + '" draws, without expanding them into a path: ' + missingEdges.map((edge) => edge.from + ' → ' + edge.to).join(', ') + '.',
+                file: child.name,
+                evidence: { kind: 'unexpanded-edge', parent: parent.name, edges: missingEdges },
+            });
+        }
+        pairs.push({
+            parent: parent.name,
+            child: child.name,
+            parentNodes: parentNodes.size,
+            childNodes: childNodes.size,
+            parentEdges: parentGraph.edges.length,
+            childEdges: childGraph.edges.length,
+            inheritedEdges,
+            newEdges,
+            expandedEdges,
+            missingEdges,
+            inventedEdges,
+        });
+    }
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
+    const invented = pairs.reduce((sum, pair) => sum + pair.inventedEdges.length, 0);
+    const missing = pairs.reduce((sum, pair) => sum + pair.missingEdges.length, 0);
+    const expanded = pairs.reduce((sum, pair) => sum + pair.expandedEdges.length, 0);
+    const nextSteps = [];
+    if (errors > 0)
+        nextSteps.push('Fix the refinement violations first: a level that invents or drops a parent-level dependency makes the hierarchy unusable as a rule source.');
+    if (pairs.length === 0 && diagrams.length > 0)
+        nextSteps.push('Give the levels a `parent` so the refinement can be checked; a set of unrelated diagrams has no consistency property to verify.');
+    if (expanded > 0)
+        nextSteps.push(String(expanded) + ' parent edge(s) are drawn as a path in the child — that is a legitimate expansion, and it is listed per pair so a reviewer can confirm each one.');
+    nextSteps.push('Reconcile the levels with the source-side scan: the diagram pair is consistent or not, and neither says anything about the code until it is scanned.');
+    return {
+        ok: true,
+        ran: true,
+        ...verdictOfFindings(findings),
+        schema: REPORT_SCHEMAS.granularity,
+        diagrams: diagramSummaries,
+        pairs,
+        findings,
+        summary: {
+            diagrams: diagrams.length,
+            roots: diagrams.filter((entry) => entry.parent === undefined).length,
+            pairs: pairs.length,
+            nodes: diagrams.reduce((sum, entry) => sum + (graphs.get(entry.name)?.nodes.length ?? 0), 0),
+            edges: diagrams.reduce((sum, entry) => sum + (graphs.get(entry.name)?.edges.length ?? 0), 0),
+            inventedEdges: invented,
+            missingEdges: missing,
+            expandedEdges: expanded,
+            errors,
+            warnings: warningCount,
+        },
+        hashes: { diagrams: diagrams.map((entry) => ({ name: entry.name, hash: createHash('sha256').update(entry.diagram).digest('hex') })) },
+        warnings,
+        nextSteps,
+    };
+}
+/** Deterministic JSON of a granularity report's pair table, for a stable summary line. */
+export function granularityDigest(pairs) {
+    return canonicalJson(pairs);
+}