dsh-model-everything 0.0.0-stage → 0.2.0

package/lib/tool.js

@@ -0,0 +1,94 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runVerification } from './engine.js';
+import { renderReportText } from './report-view.js';
+import { OptionShapeError, optionRefusal, requireObjectOption } from './option-shape.js';
+import { oneOf } from './model-file.js';
+export const MODEL_VERIFY_TOOL_NAME = 'model_verify';
+/**
+ * Model-visible DSH tool wrapping the bundled TypeScript verification engine.
+ * The model passes a LogicModelV1 object; the engine validates it and returns
+ * 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 path: the model is built and run here, with no
+ * template to fill in by hand.
+ */
+export const modelVerifyTool = defineTool({
+    name: MODEL_VERIFY_TOOL_NAME,
+    description: 'Verify one state machine: does this LogicModelV1 reach a state it must not, deadlock, livelock, or leave an invariant undecided. Model shape: schemaVersion 1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?, cost?}), plus optional variables, invariants, concurrentPairs, boundaryChecks, resourcePairs, idempotentEvents and narrative. Guards are structured: {variable, op, value}, {all}, {any} or {not}. Invariants cover never-states, var-in-range, event-before-state, leads-to, sequence, atomicity, budget, probability and deadline. `cost` defaults to 1 and drives the path-cost-against-budget check. `weight` defaults to 1 and makes the model a DTMC, which is what the probabilistic-reachability check needs. A state with `maxTicks` needs top-level `tickEvents`, or the deadline check reports it as over-resident. The schema is closed: an undeclared key is a validation error. Keys starting with `_` are metadata: ignored, kept out of `modelHash`, and echoed as `metadataKeys`. Variables support monotonic inc and dec. Pass `beforeModel` and `stateMapping` to compare the two models of a refactor for behaviour preservation, invariant continuity and deadlock regression. For two or more machines interacting, use `model_compose_verify` instead: this tool decides one machine at a time. Read `verdict`, never `ok`. The full schema is in the `model_verify` skill: references/dsh-model-schema.md.',
+    parameters: {
+        model: {
+            type: 'json',
+            description: 'LogicModelV1 state machine model to verify. Pass this, or modelPath, not both.',
+        },
+        modelPath: {
+            type: 'string',
+            description: 'Path to a JSON file holding the model, instead of inlining it. Formatting does not matter: whitespace, a BOM and pretty printing all parse. Relative paths resolve against the process working directory, which is the session workspace.',
+        },
+        maxStates: {
+            type: 'integer',
+            description: 'Maximum runtime states to explore. Default 10000.',
+        },
+        maxPermutationEvents: {
+            type: 'integer',
+            description: 'Maximum event count for A3 order permutation. Default 5.',
+        },
+        beforeModel: {
+            type: 'json',
+            description: 'Optional BEFORE LogicModelV1 state machine model for refactoring/migration regression comparison.',
+        },
+        stateMapping: {
+            type: 'json',
+            description: 'Optional object mapping BEFORE state ids to AFTER state ids. Omit for identity mapping (same state names).',
+        },
+        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: 'this plugin verification report with summary and per-check findings.',
+        },
+        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 {
+            // `stateMapping` is declared `json`, so a string, a list or a map to non-strings all arrive here, and the
+            // engine reads the option with `mapping[state] ?? state`: every one of those quietly became the identity
+            // mapping. A renamed state then read as "A was removed and A2 was added" - a D1 error produced by the shape
+            // of an option rather than by the refactor, which is the one thing a regression comparison must not do.
+            requireObjectOption(args.stateMapping, 'stateMapping', 'VERIFY_OPTION_INVALID');
+            const mapping = args.stateMapping;
+            if (mapping !== undefined) {
+                if (args.beforeModel === undefined) {
+                    throw new OptionShapeError('VERIFY_OPTION_INVALID', 'stateMapping was passed without beforeModel: the mapping says how BEFORE state ids turn into AFTER ones, so there is nothing to map. Pass beforeModel, or omit the mapping.');
+                }
+                const [from, to] = Object.entries(mapping).find(([, value]) => typeof value !== 'string' || value === '') ?? [];
+                if (from !== undefined) {
+                    throw new OptionShapeError('VERIFY_OPTION_INVALID', 'stateMapping.' + from + ' is not a state id (it is ' + (Array.isArray(to) ? 'an array' : to === null ? 'null' : 'a ' + typeof to) + '). Every value is the AFTER state id the BEFORE state maps to, so it has to be a non-empty string.');
+                }
+            }
+            const model = oneOf(args.model, args.modelPath, 'model', 'modelPath', 'VERIFY_OPTION_INVALID');
+            return runVerification(model, {
+                maxStates: args.maxStates,
+                maxPermutationEvents: args.maxPermutationEvents,
+                beforeModel: args.beforeModel,
+                stateMapping: mapping,
+            });
+        }
+        catch (error) {
+            return optionRefusal(error, 'VERIFY_OPTION_INVALID');
+        }
+    },
+});

package/lib/types/baseline.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { 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[];
+export declare function diffReports(baseline: unknown, current: unknown): BaselineReport;
+export type { VerdictSummary };

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

@@ -0,0 +1,7 @@
+export declare 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 declare const modelComposeTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

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

@@ -0,0 +1,8 @@
+export declare 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 declare const modelConcurrencyScanTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/concurrency.d.ts

@@ -0,0 +1,37 @@
+import { type ReportSchema, type Verdict } from './engine.js';
+export interface ConcurrencyFinding {
+    code: 'CONCURRENCY_KEYWORD' | 'CONCURRENCY_ABSOLUTE_CLAIM';
+    severity: 'warning' | 'error';
+    message: string;
+    line?: number;
+    snippet?: string;
+    keyword: string;
+    /** Which execution model the claim belongs to; a reader routes on it, and `nextSteps` reads it. */
+    family: 'threads' | 'synchronization' | 'async' | 'interrupts' | 'shared-state';
+    /** Route to dedicated verification tools when an absolute claim is detected (this plugin does not prove concurrency safety). */
+    suggestions?: string[];
+}
+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;
+        keywords: number;
+        absoluteClaims: number;
+        warnings: number;
+        errors: number;
+    };
+    /** This scan hashes no model; the field is present so every report has the same shape. */
+    hashes: Record<string, string>;
+    /** Present only on a refusal: the code a caller routes on, and the message behind it. */
+    errorCode?: string;
+    error?: string;
+    /** What to do next, derived from the findings — never empty. */
+    nextSteps: string[];
+}
+export declare function runConcurrencyScan(text: unknown): ConcurrencyScanReport;

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

@@ -0,0 +1,211 @@
+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';
+export interface FieldSpec {
+    name: string;
+    type: DataType | string;
+    required?: boolean;
+    unique?: boolean;
+    nullable?: boolean;
+    default?: DataValue;
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    enum?: DataValue[];
+    ref?: string;
+    items?: FieldSpec;
+    monotonic?: 'inc' | 'dec';
+}
+export interface EntitySpec {
+    name: string;
+    fields: FieldSpec[];
+    primaryKey?: string[];
+    uniqueKeys?: string[][];
+    indexes?: string[][];
+}
+export interface RelationshipSpec {
+    name?: string;
+    fromEntity: string;
+    fromField: string;
+    toEntity: string;
+    toField?: string;
+    onDelete?: 'cascade' | 'restrict' | 'set-null' | 'no-action';
+}
+export type DataInvariantSpec = {
+    id: string;
+    description: string;
+    kind: 'field-required';
+    entity: string;
+    field: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'unique';
+    entity: string;
+    fields: string[];
+} | {
+    id: string;
+    description: string;
+    kind: 'referential-integrity';
+    entity: string;
+    field: string;
+    refEntity: string;
+    refField?: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'range';
+    entity: string;
+    field: string;
+    min?: number;
+    max?: number;
+} | {
+    id: string;
+    description: string;
+    kind: 'count-equal';
+    sourceEntity: string;
+    targetEntity: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'field-equal';
+    sourceEntity: string;
+    sourceField: string;
+    targetEntity: string;
+    targetField: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'no-orphan';
+    entity: string;
+    field: string;
+    refEntity: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'idempotent-copy';
+    sourceEntity: string;
+    targetEntity: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'idempotent-migration';
+    from: string;
+    to: string;
+} | {
+    id: string;
+    description: string;
+    kind: 'monotonic';
+    entity: string;
+    field: string;
+    direction: 'inc' | 'dec';
+} | {
+    id: string;
+    description: string;
+    kind: 'sequence';
+    steps: string[];
+} | {
+    id: string;
+    description: string;
+    kind: 'leads-to';
+    entity: string;
+    field: string;
+    from: DataValue;
+    to: DataValue;
+} | {
+    id: string;
+    description: string;
+    kind: 'atomicity';
+    steps: string[];
+};
+export interface DataModelV1 {
+    schemaVersion: 1;
+    entities: EntitySpec[];
+    relationships?: RelationshipSpec[];
+    invariants?: DataInvariantSpec[];
+    boundaryChecks?: Array<{
+        entity: string;
+        field: string;
+        values?: DataValue[];
+    }>;
+}
+export interface CopyPairSpec {
+    id: string;
+    sourceEntity: string;
+    targetEntity: string;
+    mapping: Record<string, string>;
+}
+export interface BackupPairSpec {
+    id: string;
+    sourceEntity: string;
+    targetEntity: string;
+    mapping: Record<string, string>;
+}
+export interface MigrationMappingSpec {
+    id?: string;
+    from: string;
+    to: string;
+    transform?: 'copy' | 'rename' | 'split' | 'merge' | 'drop' | 'manual';
+    note?: string;
+}
+export interface DataVerificationOptions {
+    beforeModel?: unknown;
+    fieldMapping?: Record<string, string>;
+    copyPairs?: CopyPairSpec[];
+    migrationMappings?: MigrationMappingSpec[];
+    backupPairs?: BackupPairSpec[];
+}
+export interface DataComparisonSummary {
+    beforeModelHash: string;
+    afterModelHash: string;
+    fieldMapping: Record<string, string>;
+    beforeEntities: number;
+    beforeFields: number;
+    afterEntities: number;
+    afterFields: number;
+    addedEntities: string[];
+    removedEntities: string[];
+    addedFields: string[];
+    removedFields: string[];
+    addedRelationships: string[];
+    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;
+        errors: number;
+        warnings: number;
+        checksRun: number;
+        truncated?: boolean;
+    };
+    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): {
+    ok: true;
+    model: DataModelV1;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function runDataVerification(input: unknown, options?: DataVerificationOptions): DataVerificationReport;

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

@@ -0,0 +1,10 @@
+import { DATA_ENGINE_SCHEMA_VERSION } from './data-engine.js';
+export declare const DATAMODEL_VERIFY_TOOL_NAME = "model_datamodel_verify";
+/**
+ * Model-visible DSH tool wrapping the bundled data-model verification engine.
+ * The model passes a DataModelV1 object; the engine validates it and returns
+ * DS/DA/DD checks. Optional beforeModel/fieldMapping/copyPairs/migrationMappings
+ * enable before/after data-model regression and migration coverage checks.
+ */
+export declare const modelDataModelVerifyTool: import("@deepseek-ai/dsh-tools").ToolDefinition;
+export { DATA_ENGINE_SCHEMA_VERSION };

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

@@ -0,0 +1,215 @@
+/**
+ * The design-review engine: shape, and the declared design principles.
+ *
+ * This is not the verification engine. That one decides whether a machine can misbehave;
+ * this one decides whether a design keeps the contracts it declares about *itself* - which
+ * layers may depend on which, which responsibility owns which dependency, which subtype may
+ * refuse which event. The two answer different questions and their verdicts mean different
+ * things, which is why they are two engines and two tools.
+ *
+ * Three levels, kept apart in the report because they are not the same claim:
+ *
+ * - **violations** - the design contradicts something it declared. These decide `verdict`.
+ * - **signals** - a structural fact worth a reader's attention, reported without claiming it
+ *   is wrong. A hub with high fan-in is a fact about a graph; whether it is a design defect
+ *   depends on the design, and nothing here knows that.
+ * - **facts** - counts and computed structure, for a reader or another tool.
+ *
+ * What this engine does *not* do is judge a design. It never says a decomposition is good,
+ * a responsibility name is meaningful, or an abstraction is the right one. It compares a
+ * design against its own declarations and computes features of its graph, and the wording of
+ * every finding says which of those it is.
+ *
+ * @module model-everything-design-engine
+ */
+import { REPORT_SCHEMAS, type Finding, type Verdict } from './engine.js';
+export { REPORT_SCHEMAS };
+/** How a type is drawn and what it promises. */
+export type DesignStereotype = 'class' | 'interface' | 'abstract-class' | 'enum' | 'component' | 'abstract-component';
+export interface DesignOperation {
+    name: string;
+    /** Parameter type names, positional: `['Money']`. */
+    parameters?: string[];
+    returns?: string;
+}
+/** A declared state change, used only where behaviour is part of the contract. */
+export interface DesignEvent {
+    event: string;
+    /** A guard the model states in words; compared as text, never parsed. */
+    guard?: string;
+}
+export interface DesignResponsibility {
+    name: string;
+    /** The dependencies this responsibility owns. */
+    uses: string[];
+}
+/** A type, with whatever the model chose to say about it. */
+export interface DesignType {
+    name: string;
+    stereotype: DesignStereotype;
+    /** The type this one specialises, when the model declares one. */
+    extends?: string;
+    implements?: string[];
+    /** Operations the type exposes, for signature and interface checks. */
+    operations?: DesignOperation[];
+    /** Events the type handles. Its presence is what makes behaviour checkable. */
+    transitions?: DesignEvent[];
+    /** Events the type refuses. A refusal its supertype does not also declare is a violation. */
+    forbids?: DesignEvent[];
+    /** Declared responsibilities, each owning a subset of the dependencies. */
+    responsibilities?: DesignResponsibility[];
+    /** Types this one depends on, by name. */
+    dependsOn?: string[];
+    /** What this type calls on another, operation by operation: the interface-segregation input. */
+    uses?: Array<{
+        type: string;
+        operations: string[];
+    }>;
+    /** The layer the model places this type in, when it places it. */
+    layer?: string;
+}
+/** A declared layer: an ordered band of the design. */
+export interface DesignLayer {
+    name: string;
+    members: string[];
+}
+/** A declared boundary of responsibility; not ordered, unlike a layer. */
+export interface DesignBoundary {
+    name: string;
+    members: string[];
+}
+/** One rule about which edges may exist. Deny beats allow. */
+export interface DesignEdgeRule {
+    id: string;
+    source: string;
+    allow?: string[];
+    deny?: string[];
+}
+/** A dependency the design says must exist. */
+export interface DesignRequirement {
+    id: string;
+    from: string;
+    to: string;
+}
+/**
+ * A design as a model.
+ *
+ * `architecture` is the dependency graph every shape feature is computed from. `types` is the
+ * vocabulary that makes the principle checks possible at all: with no `extends` there is no
+ * substitutability to check, with no `uses` no interface can be called fat. An empty
+ * vocabulary is not a pass - it is a design that declared nothing for those checks to hold
+ * it to, and the report says so.
+ */
+export interface DesignModelV1 {
+    schemaVersion: 1;
+    /** What this design is, for a reader; carried into the report unchanged. */
+    artifact?: string;
+    architecture: {
+        nodes: string[];
+        edges: Array<[string, string]>;
+    };
+    types?: DesignType[];
+    declare?: {
+        layers?: DesignLayer[];
+        boundaries?: DesignBoundary[];
+        allowedEdges?: DesignEdgeRule[];
+        requiredEdges?: DesignRequirement[];
+    };
+    narrative?: {
+        types?: Record<string, string>;
+    };
+}
+export interface DesignValidation {
+    ok: boolean;
+    errors: string[];
+    model?: DesignModelV1;
+}
+/**
+ * Validate a candidate design.
+ *
+ * The schema is closed, for the reason the verification engine gives: a mistyped field is not
+ * a missing feature, it is a different design, and reviewing the wrong one silently is worse
+ * than refusing.
+ */
+export declare function validateDesignModel(input: unknown): DesignValidation;
+export interface GraphFeatures {
+    nodes: number;
+    edges: number;
+    components: number;
+    /** McCabe's cyclomatic complexity over the dependency graph: E - V + 2P. */
+    cyclomatic: number;
+    density: number;
+    /** The largest strongly connected component, and its members when it has more than one. */
+    largestCycle: string[];
+    /** One canonical peeling: remove these and the graph is acyclic. */
+    /** The edges whose removal makes the graph acyclic, and whether that count is a proven minimum. */
+    feedbackArcs: {
+        edges: Array<[string, string]>;
+        exact: boolean;
+        note: string;
+    };
+    /** Removing one of these disconnects the graph. */
+    articulationPoints: string[];
+    /** Removing one of these disconnects the graph. */
+    bridges: Array<[string, string]>;
+    /** Longest-path rank over the condensation; one band per layer the design actually has. */
+    ranks: Record<string, number>;
+    /** Fan-out per node: how many distinct dependencies it has. */
+    fanOut: Record<string, number>;
+    /** Fan-in per node: how many distinct dependents it has. */
+    fanIn: Record<string, number>;
+    /** Pairs that depend on each other. */
+    mutualPairs: Array<[string, string]>;
+}
+/** Every shape feature, computed once so every check reads the same numbers. */
+export declare function designFeatures(model: DesignModelV1): GraphFeatures;
+interface CheckResult {
+    id: string;
+    name: string;
+    status: 'pass' | 'fail' | 'skip';
+    detail: string;
+    findings: Finding[];
+}
+export type DesignPrincipleLevel = 'violation' | 'signal' | 'fact';
+/** Which level each code belongs to, so a reader never has to guess. */
+export declare const DESIGN_CODE_LEVEL: Record<string, DesignPrincipleLevel>;
+export interface DesignReport {
+    ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    schema: typeof REPORT_SCHEMAS.design;
+    artifact?: string;
+    /** The check-by-check results, in a fixed order. */
+    checks: CheckResult[];
+    /** Violations of something the design declared. These decide `verdict`. */
+    violations: Finding[];
+    /** Structural facts a reader should see, reported without claiming they are wrong. */
+    signals: Finding[];
+    /** Counts and computed structure. */
+    facts: Record<string, unknown>;
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+        checksRun: number;
+        nodes: number;
+        edges: number;
+    };
+    hashes: {
+        modelHash: string;
+    };
+    modelHash: string;
+    nextSteps: string[];
+}
+/**
+ * Review a design: its graph, and the contracts it declares about itself.
+ *
+ * Read `verdict`, never `ok`. A design that declares nothing gets `pass` with an empty
+ * vocabulary only for the checks that had something to hold it to - which is why the report
+ * carries each check's `status` and `detail`, and why `facts.declared` says how much the
+ * model actually declared.
+ */
+export declare function runDesignReview(input: unknown): DesignReport;
+/** A stable hash of the design, for a baseline diff or an archive record. */
+export declare function designHash(model: DesignModelV1): string;

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

@@ -0,0 +1,11 @@
+export declare const DESIGN_TOOL_NAME = "model_design_review";
+/**
+ * Model-visible DSH tool that reviews a *design*: the shape of its dependency graph, and the
+ * contracts the design states about itself.
+ *
+ * This is not `model_verify`. That one asks whether a machine can misbehave; this one asks
+ * whether a design keeps its own declarations - which layer may depend on which, which
+ * responsibility owns which dependency, which subtype may refuse which event. Two engines,
+ * two questions, two verdicts that mean different things.
+ */
+export declare const designTool: import("@deepseek-ai/dsh-tools").ToolDefinition;