dsh-model-everything 0.0.0-stage → 0.2.0

package/src/gate.ts

@@ -0,0 +1,330 @@
+/**
+ * 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 type { Context, Volatile } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { ContextFormed } from '@deepseek-ai/dsh-llm'
+import type { HostCordisInspectProviderRegistration } from '@deepseek-ai/dsh-cordis-host-runner'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
+
+// DSH 0.1.7-alpha.1 (session format v4) retires the shared `{ kind: 'plugin', plugin }`
+// wrapper, so the producer-owned kind is declared here. The history guard below matches on
+// it, which is what keeps the gate to one copy per session.
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'plugin:dsh-model-everything-gate': { kind: 'plugin:dsh-model-everything-gate' } & ContextFormed
+  }
+}
+
+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' = '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: Record<string, string> = {
+  '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(): string[] {
+  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: string[] = shippedSkills(), extraGuidance = ''): string {
+  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()
+
+/**
+ * A live switch, when this host's schemastery supports one.
+ *
+ * The settings service projects ONLY fields under a `.volatile()` node, so a plain boolean
+ * cannot be flipped from the Web Plugins page without remounting the row. The returned
+ * schema keeps the field's static type; {@link Config} carries the union the host actually
+ * hands over, and {@link injectionEnabled} accepts both shapes - a host that predates
+ * `.volatile()` simply gets a switch that needs a restart.
+ */
+interface LiveField {
+  volatile?: () => unknown
+}
+function live<T>(field: T): T {
+  const probe = field as T & LiveField
+  return typeof probe.volatile === 'function' ? (probe.volatile() as T) : field
+}
+
+export interface Config {
+  /** Whether the gate is injected. Read through {@link injectionEnabled}. On unless a deployment says otherwise. */
+  enabled: Volatile<boolean> | boolean
+  /** The text to inject. Override in the profile's `cordis.patch.yml` row, not in a GUI form. */
+  gateContent: string
+  /** A deployment's own sentence, appended to whatever text is injected. */
+  extraGuidance: string
+}
+
+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: Config): boolean {
+  const value = config.enabled
+  return typeof value === 'boolean' ? value : value.get()
+}
+
+function gateText(config: Config): string {
+  const extra = typeof config.extraGuidance === 'string' ? config.extraGuidance.trim() : ''
+  return extra === '' ? config.gateContent : config.gateContent + '\n\n' + extra
+}
+
+function gateMessage(text: string): UserMessage {
+  return createUserMessage({
+    content: [{ type: 'text', text }],
+    source: { kind: GATE_SOURCE_KIND },
+  })
+}
+
+interface SessionEventLike {
+  type: string
+  data?: Record<string, unknown>
+}
+
+/**
+ * Minimum session-store surface this plugin reads. DSH 0.1.2-alpha.4 replaced the
+ * `Session.events` getter with on-demand reads; releases up to 0.1.2-alpha.3 expose the log
+ * as a snapshot. Read through a structural union so one build serves every declared release.
+ */
+interface SessionEventSource {
+  events?: readonly SessionEventLike[]
+  snapshotEvents?: () => readonly SessionEventLike[]
+}
+
+function readSessionEvents(session: Session): readonly SessionEventLike[] {
+  const source = session as unknown as SessionEventSource
+  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: Session): boolean {
+  return readSessionEvents(session).some((event) => {
+    if (event.type !== 'user/message') return false
+    const source = event.data?.source as { kind?: string } | undefined
+    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: Config): HostCordisInspectProviderRegistration {
+  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: string) => {
+      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: Context, config: Config): void {
+  // 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 = (): void => {
+    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/src/granularity.ts

@@ -0,0 +1,312 @@
+/**
+ * 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, type Finding, type ReportSchema, type Verdict, type VerdictSummary } from './engine.js'
+import { parseStructure, reviewStructure, type StructureGraph, type StructureNotation } from './structure.js'
+
+export interface GranularityDiagram {
+  /** Name of this level, e.g. `L2/motion` or `repo`. Referenced by a child's `parent`. */
+  name: string
+  /** Diagram source text. */
+  diagram: string
+  /** Name of the diagram this one refines; absent for a root. */
+  parent?: string
+}
+
+export interface GranularityOptions {
+  diagrams: GranularityDiagram[]
+  notation?: 'auto' | StructureNotation
+  /** Optional dependency matrix, applied to every diagram. */
+  matrix?: unknown
+}
+
+export interface GranularityEdgeRef {
+  from: string
+  to: string
+  line?: number
+}
+
+export interface GranularityPairSummary {
+  parent: string
+  child: string
+  parentNodes: number
+  childNodes: number
+  parentEdges: number
+  childEdges: number
+  /** Child edges whose endpoints both exist in the parent and which the parent also draws. */
+  inheritedEdges: number
+  /** Child edges with at least one endpoint the parent does not have (the refinement's own detail). */
+  newEdges: number
+  /** Parent edges with no direct child counterpart, but a child path connects the same ends. */
+  expandedEdges: GranularityEdgeRef[]
+  /** Parent edges with no direct counterpart and no connecting path — the refinement lost them. */
+  missingEdges: GranularityEdgeRef[]
+  /** Child edges between two parent nodes that the parent does not draw — invented dependencies. */
+  inventedEdges: GranularityEdgeRef[]
+}
+
+export interface GranularityDiagramSummary {
+  name: string
+  parent?: string
+  notation: StructureNotation
+  nodes: number
+  edges: number
+  verdict: Verdict
+  findings: number
+}
+
+export interface GranularityReport {
+  ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  schema: ReportSchema
+  diagrams: GranularityDiagramSummary[]
+  pairs: GranularityPairSummary[]
+  findings: Finding[]
+  summary: {
+    diagrams: number
+    roots: number
+    pairs: number
+    nodes: number
+    edges: number
+    inventedEdges: number
+    missingEdges: number
+    expandedEdges: number
+    errors: number
+    warnings: number
+  }
+  hashes: { diagrams: Array<{ name: string; hash: string }> }
+  warnings: string[]
+  nextSteps: string[]
+}
+
+/** Reachability in one diagram, ignoring edge direction? No: a dependency path is directed. */
+function reaches(graph: StructureGraph, from: string, to: string): boolean {
+  const adjacency = new Map<string, string[]>()
+  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<string>([from])
+  const queue: string[] = [from]
+  while (queue.length > 0) {
+    const current = queue.shift() as string
+    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: GranularityDiagram[]): string[] | undefined {
+  const byName = new Map(diagrams.map((entry) => [entry.name, entry]))
+  for (const start of diagrams) {
+    const path: string[] = [start.name]
+    const seen = new Set<string>([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: GranularityOptions): GranularityReport {
+  const diagrams = options.diagrams
+  const findings: Finding[] = []
+  const warnings: string[] = []
+  const diagramSummaries: GranularityDiagramSummary[] = []
+  const graphs = new Map<string, StructureGraph>()
+
+  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: GranularityPairSummary[] = []
+  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: GranularityEdgeRef[] = []
+    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: GranularityEdgeRef[] = []
+    const missingEdges: GranularityEdgeRef[] = []
+    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: string[] = []
+  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: GranularityPairSummary[]): string {
+  return canonicalJson(pairs)
+}
+
+export type { VerdictSummary }