dsh-logicprobe 0.9.0 → 1.0.0

package/lib/types/baseline.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 logicprobe-baseline
+ */
+import { type Finding, type Verdict, type VerdictSummary } from './engine.js';
+/** A finding as it appears in any report family, after flattening. */
+export interface ReportFinding extends Finding {
+    /** The check that emitted it (verify/datamodel: `S2`, `C1`, …); absent for flat families. */
+    check?: string;
+}
+export interface BaselineChange {
+    identity: string;
+    code: string;
+    before: {
+        severity: string;
+        message: string;
+    };
+    after: {
+        severity: string;
+        message: string;
+    };
+}
+export interface BaselineReport {
+    ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: string;
+    /** The current report's own verdict, echoed so "no new findings" cannot hide a failing run. */
+    currentVerdict: Verdict;
+    added: ReportFinding[];
+    removed: ReportFinding[];
+    changed: BaselineChange[];
+    summary: {
+        baseline: number;
+        current: number;
+        added: number;
+        removed: number;
+        changed: number;
+        addedErrors: number;
+        addedWarnings: number;
+    };
+    nextSteps: string[];
+}
+/**
+ * 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 declare function findingIdentity(finding: ReportFinding): string;
+/** Flatten a report of any family into one finding list (`checks[].findings` or `findings[]`). */
+export declare function flattenReportFindings(report: unknown): ReportFinding[];
+/**
+ * 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.
+ */
+export declare function diffReports(baseline: unknown, current: unknown): BaselineReport;
+export type { VerdictSummary };

package/lib/types/concurrency.d.ts

@@ -1,3 +1,4 @@
+import { type ReportSchema, type Verdict } from './engine.js';
 export interface ConcurrencyFinding {
     code: 'CONCURRENCY_KEYWORD' | 'CONCURRENCY_ABSOLUTE_CLAIM';
     severity: 'warning' | 'error';
@@ -10,6 +11,11 @@ export interface ConcurrencyFinding {
 }
 export interface ConcurrencyScanReport {
     ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
     findings: ConcurrencyFinding[];
     summary: {
         lines: number;
@@ -18,5 +24,9 @@ export interface ConcurrencyScanReport {
         warnings: number;
         errors: number;
     };
+    /** This scan hashes no model; the field is present so every report has the same shape. */
+    hashes: Record<string, string>;
+    /** What to do next, derived from the findings — never empty. */
+    nextSteps: string[];
 }
 export declare function runConcurrencyScan(text: string): ConcurrencyScanReport;

package/lib/types/data-engine.d.ts

@@ -1,4 +1,4 @@
-import type { CheckResult } from './engine.js';
+import { type CheckResult, type ReportSchema, type Verdict } from './engine.js';
 export declare const DATA_ENGINE_SCHEMA_VERSION = 1;
 export type DataValue = number | string | boolean | null;
 export type DataType = 'string' | 'integer' | 'number' | 'boolean' | 'uuid' | 'date' | 'datetime' | 'timestamp' | 'json' | 'enum' | 'array' | 'object' | 'binary';
@@ -174,9 +174,19 @@ export interface DataComparisonSummary {
     removedRelationships: string[];
 }
 export interface DataVerificationReport {
+    /** The engine ran and the input was well-formed enough to produce this report. Read `verdict` for the review outcome. */
     ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
     schemaVersion: 1;
     modelHash: string;
+    /** Every hash this report carries, in one place. The data-model hash follows the same normalization as the published spec, but is not covered by it. */
+    hashes: {
+        modelHash: string;
+    };
     summary: {
         entities: number;
         fields: number;
@@ -187,6 +197,8 @@ export interface DataVerificationReport {
     };
     checks: CheckResult[];
     comparison?: DataComparisonSummary;
+    /** What to do next, derived from the findings — never empty. */
+    nextSteps: string[];
 }
 export declare function dataModelHash(model: DataModelV1): string;
 export declare function validateDataModel(input: unknown): {

package/lib/types/engine.d.ts

@@ -167,6 +167,8 @@ export interface VerificationOptions {
     maxPermutationEvents?: number;
     beforeModel?: unknown;
     stateMapping?: Record<string, string>;
+    /** Hash specification used for modelHash. Defaults to the current published spec (`v1`). */
+    hashSpec?: HashSpec;
 }
 export interface PathStep {
     from: string;
@@ -177,6 +179,12 @@ export interface Finding {
     code: string;
     severity: 'error' | 'warning';
     message: string;
+    /** Longer explanation: the shortest-path note, the per-machine reasons, the quoted source lines. */
+    detail?: string;
+    /** The artefact the finding is about (a diagram name, a file path) — set when one report covers several. */
+    file?: string;
+    /** 1-based line in that artefact, when the check knows it. */
+    line?: number;
     path?: PathStep[];
     evidence?: Record<string, unknown>;
 }
@@ -188,9 +196,34 @@ export interface CheckResult {
     findings: Finding[];
 }
 export interface VerificationReport {
+    /**
+     * The engine ran and the input was well-formed enough to produce this report.
+     * It does NOT mean the review passed — read `verdict` for that.
+     */
     ok: boolean;
+    /** The tool executed and produced a report. False only when a tool refused the request before the engine ran. */
+    ran: boolean;
+    /** The review outcome. `ok: true` with `verdict: "fail"` is a failing review, not a passing one. */
+    verdict: Verdict;
+    /** Why the verdict came out that way, e.g. `2 error finding(s) (first: S2_NO_TRANSITIONS)`. */
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
     schemaVersion: 1;
+    /** Which published specification `modelHash` follows (see references/hash-spec.md). */
+    hashSpec: HashSpec;
     modelHash: string;
+    /** Every hash this report carries, in one place, for a baseline diff or an archive record. */
+    hashes: {
+        hashSpec: HashSpec;
+        modelHash: string;
+        beforeModelHash?: string;
+        afterModelHash?: string;
+    };
+    /** Paths of the `_`-prefixed metadata keys found in the input and ignored by the schema. */
+    metadataKeys?: string[];
+    /** How much of the model the narrative documents; absent when there is no narrative. */
+    narrativeCoverage?: NarrativeCoverage;
     /** Echo of the model's natural-language narrative, when present. */
     narrative?: ModelNarrative;
     summary: {
@@ -203,6 +236,8 @@ export interface VerificationReport {
     };
     checks: CheckResult[];
     comparison?: ComparisonSummary;
+    /** What to do next, derived from the findings — never empty. */
+    nextSteps: string[];
     /** Informational notes about semantic dimensions this model references (timing, preemption)
      * that this engine does not verify. Heuristic, vocabulary-based — never a substitute for the checks. */
     coverageNotes?: string[];
@@ -226,7 +261,92 @@ export interface RuntimeState {
     state: string;
     vars: Record<string, VarValue>;
 }
-export declare function modelHash(model: LogicModelV1): string;
+export declare function modelHash(model: LogicModelV1, spec?: HashSpec): string;
+/**
+ * Deterministic JSON (sorted keys, no insignificant whitespace) — the serialization the
+ * hash specification is defined over. Exported so every report hashes inputs the same way.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Published model-hash specifications. The full normalization rules, the list of
+ * excluded keys and a one-line recompute command are in `references/hash-spec.md`.
+ *
+ * - `v1` (1.0.0) drops every `_`-prefixed metadata key at every level before hashing,
+ *   so archiving `_source` / `_verified` next to a model cannot change its hash.
+ * - `v0` is the pre-1.0.0 behaviour (no metadata filtering), kept so an archived hash
+ *   can still be checked against the old engine.
+ *
+ * For a model that carries no `_` keys the two specs are byte-identical.
+ */
+export type HashSpec = 'v0' | 'v1';
+export declare const PUBLISHED_HASH_SPECS: readonly HashSpec[];
+export declare const DEFAULT_HASH_SPEC: HashSpec;
+/**
+ * Versioned report contracts. Every tool result carries `schema`, so a consumer can
+ * branch on the contract instead of sniffing fields, and a change to a report's shape
+ * is a version bump here rather than a silent break. `findings[]` keeps the same
+ * stable core in every family: `{code, severity, message, detail?, evidence?, path?}`.
+ */
+export declare const REPORT_SCHEMAS: {
+    readonly verify: 'logicprobe/verify/v1';
+    readonly compose: 'logicprobe/compose/v1';
+    readonly datamodel: 'logicprobe/datamodel/v1';
+    readonly concurrency: 'logicprobe/concurrency/v1';
+    readonly export: 'logicprobe/export/v1';
+    readonly umlRender: 'logicprobe/uml/render/v1';
+    readonly umlParse: 'logicprobe/uml/parse/v1';
+    readonly umlReview: 'logicprobe/uml/review/v1';
+    readonly structure: 'logicprobe/structure/v1';
+    readonly granularity: 'logicprobe/granularity/v1';
+    readonly baseline: 'logicprobe/baseline/v1';
+};
+export type ReportSchema = typeof REPORT_SCHEMAS[keyof typeof REPORT_SCHEMAS];
+/**
+ * How much of the model the `narrative` block actually documents, as `covered/total`
+ * per dimension. A partial narrative is valid — writing the states first and the
+ * events later is the natural order — so this is a coverage report, not a gate.
+ * `scenarios` counts distinct modelled (from, event) groups: one scenario per group.
+ */
+export interface NarrativeCoverage {
+    states: string;
+    events: string;
+    scenarios: string;
+}
+export declare function narrativeCoverageOf(model: LogicModelV1): NarrativeCoverage | undefined;
+/** True when every dimension of the coverage is fully described. */
+export declare function narrativeComplete(coverage: NarrativeCoverage | undefined): boolean;
+/**
+ * The review outcome, kept separate from `ok` (= "the tool ran"). Collapsing the two
+ * is how a failed review gets read as a passing one.
+ */
+export type Verdict = 'pass' | 'pass_with_findings' | 'fail';
+export interface VerdictSummary {
+    verdict: Verdict;
+    verdictReason: string;
+}
+/** A tool that refused the request before running anything: it neither passed nor failed a review. */
+export declare function refusalVerdict(reason: string): VerdictSummary;
+/**
+ * Decide the verdict from finding counts. Any error-severity finding fails the review
+ * even though the tool ran successfully — that gap is exactly what `verdict` closes.
+ */
+export declare function verdictOf(errors: number, warnings: number, firstCode?: string): VerdictSummary;
+export declare function verdictOfFindings(findings: Array<{
+    code: string;
+    severity: string;
+}>): VerdictSummary;
+/**
+ * Paths of every `_`-prefixed key in the input, sorted (`_source`, `_verified`,
+ * `states[0]._note`; a metadata key's own children are not listed, since the subtree is
+ * metadata as a whole). The schema ignores these keys as annotation metadata; echoing
+ * them in the report makes the ignored metadata auditable instead of invisible.
+ */
+export declare function metadataKeysOf(input: unknown): string[];
+/**
+ * The exact payload a hash spec hashes. Exported so the specification has one
+ * implementation and the documentation can be checked against it.
+ */
+export declare function hashPayload(model: unknown, spec?: HashSpec): unknown;
 export declare function validateModel(input: unknown): {
     ok: true;
     model: LogicModelV1;
@@ -245,6 +365,8 @@ export interface CompositionOptions {
     /** Events that require a synchronized multi-machine step (handshake). */
     rendezvous?: string[];
     maxStates?: number;
+    /** Hash specification used for the per-machine modelHash. Defaults to the current published spec (`v1`). */
+    hashSpec?: HashSpec;
 }
 export interface CompositionSummary {
     machineCount: number;
@@ -259,9 +381,24 @@ export interface CompositionSummary {
     truncated: boolean;
 }
 export interface CompositionReport {
+    /** Historical meaning: the composition has no error-severity finding. Read `verdict` for the review outcome. */
     ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
+    /** Which published specification the per-machine `modelHash` values follow. */
+    hashSpec: HashSpec;
+    /** Every hash this report carries, in one place. */
+    hashes: {
+        hashSpec: HashSpec;
+        machines: string[];
+    };
     summary: CompositionSummary;
     checks: CheckResult[];
+    /** What to do next, derived from the findings — never empty. */
+    nextSteps: string[];
 }
 /**
  * N-machine composition semantics (documented in dsh-model-schema.md):

package/lib/types/granularity.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 logicprobe-granularity
+ */
+import { type Finding, type ReportSchema, type Verdict, type VerdictSummary } from './engine.js';
+import { 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[];
+}
+/**
+ * Review a set of structure diagrams with declared parent relations. Per-diagram
+ * structural checks run first; the cross-diagram refinement checks follow.
+ */
+export declare function reviewGranularity(options: GranularityOptions): GranularityReport;
+/** Deterministic JSON of a granularity report's pair table, for a stable summary line. */
+export declare function granularityDigest(pairs: GranularityPairSummary[]): string;
+export type { VerdictSummary };

package/lib/types/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
- * Injects the session-start gate text (claim-verification doctrine, 1% Rule,
- * Red Flags, proactive suggestion) into the first model step of every agent
- * session, mirroring the SessionStart hook the Claude Code plugin installs.
+ * Injects the session-start gate text (what this plugin checks, the 1% Rule,
+ * the Red Flags, the routing to the skills, the tool list, how to read a report)
+ * into the first model step of every agent session, mirroring the SessionStart
+ * hook the Claude Code plugin installs.
  * The skill ships in this package's `skills/` directory and is registered at
  * apply time into dsh's `ctx.skills` registry through the standard filesystem
  * provider, so it appears in every session catalog without a manual copy step.
@@ -16,11 +17,11 @@
  * reminders (skill catalog, AGENTS.md, gate plugins) simply defer this message
  * to the first step after their promotion, and the history guard re-injects it
  * there. The default gate text is the dsh-native adaptation of
- * `hooks/session-start-content.md`: behavior rules
- * (1% Rule / Red Flags / proactive suggestion) stay in sync, while
- * presentation is adapted to dsh's native skill catalog — the trigger list
- * lives in the skill description, not duplicated in the gate. Deployments
- * override via Config.
+ * `hooks/session-start-content.md`. Both are a guide to calling the tools: what
+ * this plugin checks, the 1% Rule and the Red Flags that raise the chance of a
+ * call, the routing to the five skills, the tool list, and how to read a report.
+ * They stay in sync. Method, doctrine and per-domain detail live in the skills
+ * and their references, not here. Deployments override via Config.
  *
  * @module logicprobe-dsh
  */

package/lib/types/report-diff-tool.d.ts

@@ -0,0 +1,8 @@
+export declare const LOGICPROBE_REPORT_DIFF_TOOL_NAME = "logicprobe_report_diff";
+/**
+ * Model-visible DSH tool that compares two reports of the same family — the accepted
+ * "violations must not increase" acceptance criterion, computed instead of eyeballed.
+ * A finding's identity is its check + code + machine-readable locator, so a reworded
+ * message reads as `changed`, and two runs over the same input add nothing.
+ */
+export declare const logicProbeReportDiffTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/structure-tool.d.ts

@@ -0,0 +1,10 @@
+export declare const LOGICPROBE_STRUCTURE_TOOL_NAME = "logicprobe_structure_verify";
+/**
+ * Model-visible DSH tool that audits a *structure* diagram — components, packages,
+ * classes, deployment nodes and the dependency arrows between them — against an
+ * optional dependency matrix. A structure diagram is not a state machine: this tool
+ * reads the graph the diagram actually draws, instead of refusing it (which is what
+ * `logicprobe_uml action=parse` does) or pretending the arrows are state transitions
+ * (which is what a false `ok` used to hide).
+ */
+export declare const logicProbeStructureTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/structure.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Structure-diagram review: a dependency graph is not a state machine.
+ *
+ * The state-machine front end (`uml.ts`) reads a component, package, class or
+ * deployment diagram as a *by-product* and says so (`UML_NOT_A_STATE_DIAGRAM`).
+ * This module reads the same text as what it actually is — a directed graph of
+ * nodes and dependency edges — and audits it against a declared dependency matrix.
+ *
+ * The checks are the structural ones a reader performs by eye and gets wrong:
+ * an isolated node nobody notices, an arrow whose endpoint was never declared, a
+ * dependency cycle, an edge that violates the allowed-dependency matrix, a child
+ * depending on its parent, and an edge the matrix says must exist but the diagram
+ * does not draw. Every finding names the rule id it hit, so the diagram and the
+ * source-side checker can be reconciled rule by rule.
+ *
+ * @module logicprobe-structure
+ */
+import { type Finding, type ReportSchema, type Verdict, type VerdictSummary } from './engine.js';
+export type StructureNotation = 'plantuml' | 'mermaid';
+/** What a node declares itself to be. Containers hold other nodes; they are not dependencies. */
+export type StructureNodeKind = 'component' | 'class' | 'interface' | 'actor' | 'database' | 'node' | 'package' | 'rectangle' | 'cloud' | 'queue' | 'unknown';
+export interface StructureNode {
+    id: string;
+    /** Display label when the declaration carried one (`component "Order Service" as SVC`). */
+    label?: string;
+    kind: StructureNodeKind;
+    /** True when the node is a container (package/rectangle/frame): it owns members and carries no dependency of its own. */
+    container: boolean;
+    /** 1-based line of the declaration. Absent when the node was only ever named by an edge. */
+    line?: number;
+    declared: boolean;
+    /** Container id this node was declared inside, if any. */
+    parent?: string;
+}
+export interface StructureEdge {
+    from: string;
+    to: string;
+    /** Arrow label, e.g. `read` in `PAY --> DRV : read`. */
+    label?: string;
+    line: number;
+}
+export interface StructureGraph {
+    notation: StructureNotation;
+    nodes: StructureNode[];
+    edges: StructureEdge[];
+    warnings: string[];
+}
+/** One dependency rule from the matrix document. */
+export interface StructureRule {
+    id: string;
+    /** Node id or glob the rule applies to; absent = applies to every source. */
+    source?: string;
+    /** Permitted targets (glob or node id). Winning an allow match permits the edge. */
+    allow?: string[];
+    /** Forbidden targets. Deny always wins over allow. */
+    deny?: string[];
+    /** When true, at least one edge matching source→targets must exist (UML025). */
+    require?: boolean;
+}
+export interface StructureLayer {
+    name: string;
+    /** Node ids or globs that belong to this layer. */
+    members: string[];
+}
+/**
+ * The dependency matrix: the single source of truth a diagram is checked against.
+ * `default` decides the fate of an edge no rule mentions (`allow` = only explicit
+ * rules judge, `deny` = anything unlisted is a violation).
+ */
+export interface DependencyMatrix {
+    rules?: StructureRule[];
+    layers?: StructureLayer[];
+    default?: 'allow' | 'deny';
+}
+export interface StructureEdgeVerdict {
+    from: string;
+    to: string;
+    line: number;
+    /** Rule ids whose `source` matched this edge, whether they allowed or denied it. */
+    matchedRules: string[];
+    allowed: boolean;
+    /** `allow` (a rule permitted it), `default` (nothing judged it), `deny` (a rule forbade it), `unlisted` (default=deny and no rule matched). */
+    basis: 'allow' | 'default' | 'deny' | 'unlisted';
+}
+export interface StructureSummary {
+    nodes: number;
+    edges: number;
+    containers: number;
+    isolated: number;
+    dangling: number;
+    cycles: number;
+    disallowedEdges: number;
+    layerViolations: number;
+    missingExpectedEdges: number;
+    errors: number;
+    warnings: number;
+    rules: number;
+}
+export interface StructureReport {
+    /** The tool ran and produced this report; read `verdict` for the outcome. */
+    ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
+    notation: StructureNotation;
+    graph: StructureGraph;
+    /** Per-edge matrix verdict, present only when a matrix was supplied. */
+    edgeVerdicts?: StructureEdgeVerdict[];
+    findings: Finding[];
+    summary: StructureSummary;
+    /** Hashes of the inputs this report is about: the diagram text, and the matrix when one was supplied. */
+    hashes: {
+        diagram: string;
+        matrix?: string;
+    };
+    warnings: string[];
+    nextSteps: string[];
+}
+/** A finding code in the structure family; the numbers continue the UML0xx series after UML019. */
+export type StructureFindingCode = 'UML020_ISOLATED_NODE' | 'UML021_DANGLING_REFERENCE' | 'UML022_CYCLE' | 'UML023_DISALLOWED_EDGE' | 'UML024_LAYER_VIOLATION' | 'UML025_MISSING_EXPECTED_EDGE' | 'UML026_NO_NODES';
+/**
+ * Parse a structure diagram (PlantUML component/package/class/deployment, Mermaid
+ * class diagram) into nodes and dependency edges.
+ *
+ * A structure diagram is *not* refused here: refusing is the state-machine front
+ * end's job (`parseUml`). This parser is the honest reading of the same text.
+ */
+export declare function parseStructure(text: string, notation?: 'auto' | StructureNotation): StructureGraph;
+/** `*` matches any run of characters, `?` exactly one. Ids keep their own punctuation. */
+export declare function globMatches(pattern: string, value: string): boolean;
+export declare function validateMatrix(input: unknown): {
+    ok: true;
+    matrix: DependencyMatrix;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Shortest directed cycle through the graph, as a node path with the start repeated. */
+export declare function shortestCycle(nodes: string[], edges: StructureEdge[]): string[] | undefined;
+export interface StructureReviewOptions {
+    /** Diagram text to review. */
+    diagram: string;
+    notation?: 'auto' | StructureNotation;
+    /** Dependency matrix: allowed/denied edges, layers, required edges. */
+    matrix?: unknown;
+}
+/**
+ * Audit a structure diagram. Every check is structural: it reads the drawn graph and
+ * the declared matrix, and never claims anything about the code behind them.
+ */
+export declare function reviewStructure(options: StructureReviewOptions): StructureReport;
+/** The finding codes this module can emit, for documentation and tests. */
+export declare const STRUCTURE_FINDING_CODES: readonly StructureFindingCode[];
+export type { VerdictSummary };

package/lib/types/tool.d.ts

@@ -5,7 +5,7 @@ export declare const LOGICPROBE_VERIFY_TOOL_NAME = "logicprobe_verify";
  * the 22-check report (S1-S8 structural, A1-A14), or a 26-check
  * report when beforeModel is supplied (D1 behavioral preservation, D2
  * invariant continuity, D3 regression delta, D4 deadlock/liveness regression).
- * This is the dsh-native replacement for hand-filling the Python template
- * shipped in the skill references.
+ * This is the dsh-native path: the model is built and run here, with no
+ * template to fill in by hand.
  */
 export declare const logicProbeVerifyTool: import("@deepseek-ai/dsh-tools").ToolDefinition;