dsh-model-everything 0.0.0-stage → 0.2.0

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 this plugin-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

@@ -0,0 +1,45 @@
+/**
+ * dsh-model-everything — DeepSeek Harness native plugin for models and diagrams.
+ *
+ * It ships a skill set (one entry skill plus a skill per domain) and the tools that do
+ * the work: UML diagrams render, parse and review; state machines, protocols and composed
+ * machines are checked by running them; data models and migrations are checked by the same
+ * doctrine; concurrency claims are mined and routed; a verified model is exported to an
+ * external checker; a structure diagram is audited as a dependency graph; two reports are
+ * diffed against each other.
+ *
+ * Every tool carries its own description and every report says what it proves, so a model
+ * reaches for one the way it reaches for any other tool: by reading what it says it does.
+ * The plugin writes nothing into a session.
+ *
+ * The skills ship in this package's `skills/` directory and are registered at apply time
+ * into dsh's `ctx.skills` registry through the standard filesystem provider, so they appear
+ * in every session catalog without a manual copy step.
+ *
+ * Method, doctrine and per-domain detail live in the skills and their references, not here.
+ *
+ * @module dsh-model-everything
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "dsh-model-everything";
+export declare const inject: string[];
+export type InteractionMode = 'ask' | 'auto' | 'follow-approval';
+export interface Config {
+    /**
+     * How an offer to run a tool resolves: `ask` and `auto` are fixed, while `follow-approval`
+     * reads the session's approval policy per call. `resolveInteraction` is its only reader.
+     *
+     * There is deliberately no on/off key here. A row is switched off by the loader row that
+     * mounts it (`disabled`, or the plugin manager), which removes the tools and the skills
+     * together; a key that turned the tools off while the skills stayed would leave every skill
+     * naming a tool that is not there, which is worse than having no skill at all.
+     */
+    interaction: InteractionMode;
+}
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval", "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval", "defined">;
+}>>, "plain">;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/json-value.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structural mirror of the JSON value union the dsh tool registry accepts.
+ *
+ * `@deepseek-ai/dsh-tools` exported this type through the 0.1.x line and stopped
+ * exporting it in 0.2.x, where the same type now lives in
+ * `@deepseek-ai/dsh-util-values`. This package declares peer support for both
+ * lines, so it cannot import the type from either one without breaking the other
+ * build. Declaring the one-line union here keeps `npm run typecheck` green against
+ * both, and it costs nothing at runtime: every use is a type-only cast on a value
+ * this package already produced.
+ *
+ * Keep it structurally identical to the official type. A cast through `unknown` to
+ * this alias is only a way to satisfy `defineTool`'s return-type constraint; if the
+ * official union ever widens, this alias must widen with it.
+ *
+ * @module this plugin-json-value
+ */
+/** JSON-serializable value: null, boolean, number, string, or an array/object of those. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};

package/lib/types/model-file.d.ts

@@ -0,0 +1,7 @@
+/** Read and parse one JSON file. Formatting is irrelevant: whitespace, BOM and pretty printing all parse. */
+export declare function readJsonFile(path: unknown, option: string, code: string): unknown;
+/**
+ * Exactly one of the inline value and the file path. Both is ambiguous, neither is a missing
+ * argument, and each gets its own sentence so the caller knows which one to drop.
+ */
+export declare function oneOf(value: unknown, path: unknown, inlineName: string, pathName: string, code: string): unknown;

package/lib/types/option-shape.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Option shapes at the tool boundary.
+ *
+ * A tool declares `type: 'json'` for an option, which accepts any JSON value, and the engine then reads
+ * it as the type it needs. A string where an array was expected threw `machinesInput.forEach is not a
+ * function` and `(options.migrationMappings ?? []).map is not a function` - raw TypeErrors with no code,
+ * which a caller cannot route on and which say nothing about which option was wrong.
+ *
+ * The suite pinned those as known gaps. This closes them the way the rest of the plugin reports a
+ * refusal: a code naming the family, and a message naming the option.
+ */
+/** A refusal the caller can route on: the domain's code, and what arrived. */
+export declare class OptionShapeError extends Error {
+    readonly errorCode: string;
+    constructor(errorCode: string, message: string);
+}
+/** An option the engine reads with `.map`: a string or a number is not one. */
+export declare function requireArrayOption(value: unknown, option: string, errorCode: string): void;
+/** An option the engine reads with `Object.entries`: a string has entries, and they are not the ones meant. */
+export declare function requireObjectOption(value: unknown, option: string, errorCode: string): void;
+/** The refusal a tool returns for a shape it could not read. */
+export declare function optionRefusal(error: unknown, errorCode: string): Record<string, unknown>;

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

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

package/lib/types/report-view.d.ts

@@ -0,0 +1,50 @@
+/** Rendering limits. Defaults are the shipped behaviour; tests pin them. */
+export interface ReportViewOptions {
+    /** Maximum finding lines per check. Error findings are never dropped, only warnings are capped. */
+    maxFindingsPerCheck?: number;
+    /** Evidence is inlined for `error` findings only, truncated to this many characters. */
+    maxEvidenceChars?: number;
+    /** Include passing checks' bodies (default false: a passing check carries no actionable finding). */
+    includePassing?: boolean;
+    /**
+     * Print the whole structured report instead of the body. This is the escape hatch for a
+     * caller that must hand the report to another tool verbatim — `report_diff`
+     * matches on check + code + evidence, so a body cannot stand in for the object.
+     */
+    full?: boolean;
+    /**
+     * Print one check in full: every finding, evidence included, without the per-check budget the
+     * digest applies. The digest truncates a check's warnings and tells the reader to ask for it by
+     * id; before this option existed that sentence named something the tools could not do, and the
+     * only way to see the lines was `full`, which returns the whole structured report.
+     */
+    check?: string | undefined;
+}
+type Record_ = Record<string, unknown>;
+/** One normalized finding. `evidence` is kept because a finding's identity depends on it. */
+export interface ViewFinding {
+    code: string;
+    severity: string;
+    message: string;
+    evidence?: Record_;
+    file?: string;
+    line?: number;
+    check?: string | undefined;
+}
+/** Normalize one raw finding. Unknown fields are ignored; a missing message renders as the code. */
+export declare function toViewFinding(value: unknown, check?: string): ViewFinding;
+/**
+ * The fact a finding states, as a comparable key. The verify/datamodel families report the
+ * same (state, event) fact from more than one check, so the key ignores which check said it;
+ * anything else falls back to code + message.
+ */
+export declare function factKey(finding: ViewFinding): string;
+/**
+ * Render any this plugin result as the text a model reads.
+ *
+ * Order of recognition: a `checks[]` report, a flat `findings[]` report, a baseline delta,
+ * a payload result (`diagram`/`primary`), and finally compact JSON so an unrecognized shape
+ * is still readable rather than silently empty.
+ */
+export declare function renderReportText(value: unknown, options?: ReportViewOptions): string;
+export {};

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

@@ -0,0 +1,10 @@
+export declare const STRUCTURE_TOOL_NAME = "uml_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
+ * `uml action=parse` does) or pretending the arrows are state transitions
+ * (which is what a false `ok` used to hide).
+ */
+export declare const umlStructureTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/structure.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 model-everything-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;
+}
+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

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

package/lib/types/uml-communication.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The communication diagram module.
+ *
+ * A communication diagram is a set of lifelines joined by links, with numbered messages
+ * travelling along the links. PlantUML has no communication-diagram type - the page is a
+ * 404 and the navigation lists none - but the drawing is expressible with the object
+ * diagram's vocabulary: objects for the lifelines, arrows for the links, and the sequence
+ * number in the arrow's label.
+ *
+ * That last point is why this family is *not* refused. An earlier version of the family
+ * table said neither notation spells the numbering or the link roles, so a parse would
+ * invent an order. The numbering is spelled - `C --> O : 1: create` carries both the link
+ * and the order - and the renderer writes it back the same way. What the notation cannot
+ * say is the *nesting* that a number like `1.1` implies (which message is a nested call of
+ * which), so the model keeps the number as the string the diagram wrote and makes no claim
+ * about the tree it suggests.
+ *
+ * @module model-everything-uml-communication
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+/**
+ * A message number as the diagram wrote it: `1`, `2`, `1.1`, `3a`.
+ *
+ * It is a string, not a number, and the module does not parse its structure. `1.1` reads as
+ * a nested call in UML, but that is a claim about the design; the diagram only draws a
+ * label, and inventing the call tree from a dotted string would be the sort of guess this
+ * plugin refuses to make elsewhere.
+ */
+export type CommunicationSequence = string;
+export interface CommunicationLifeline {
+    id: string;
+    label?: string;
+    /** `:Name` in the drawing is a classifier, `Name` alone is an instance. */
+    classifier?: string;
+}
+export interface CommunicationLink {
+    from: string;
+    to: string;
+    label?: string;
+}
+export interface CommunicationMessage {
+    sequence: CommunicationSequence;
+    from: string;
+    to: string;
+    /** The message name and arguments, without the number. */
+    label?: string;
+}
+/**
+ * A communication diagram as a model.
+ *
+ * `links` is what the diagram draws between lifelines; a message travels along one. The two
+ * are kept apart because a link with no message is a real thing to notice, and so is a
+ * message with no link to carry it.
+ */
+export interface CommunicationModelV1 {
+    schemaVersion: 1;
+    lifelines: CommunicationLifeline[];
+    links: CommunicationLink[];
+    messages: CommunicationMessage[];
+    /** Ids a message or link named that no declaration introduced. */
+    undeclared?: string[];
+    narrative?: {
+        lifelines?: Record<string, string>;
+    };
+}
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * A sequence number must be unique: two messages with the same number is not a style
+ * question, it is a diagram whose order has two answers.
+ */
+export declare function validateCommunicationModel(input: unknown): CommunicationModelV1;
+/**
+ * Render a communication diagram as PlantUML.
+ *
+ * Objects for the lifelines, arrows for the links, and one arrow per message with its
+ * number in the label. A message whose lifelines have no declared link is still drawn -
+ * the notation allows it - and the review reports it rather than the renderer hiding it.
+ *
+ * @param input - candidate `CommunicationModelV1`.
+ * @param notation - only `plantuml` draws this family.
+ */
+export declare function renderCommunication(input: unknown, notation: UmlNotation): UmlFamilyRender;
+/**
+ * Read a communication diagram back into a model.
+ *
+ * Hand-written text is read the same way the renderer writes it: `object` declarations are
+ * the lifelines, `--` arrows are the links, and an arrow whose label starts with a number
+ * and a colon is a message. A line that is neither is reported in `discardedConstructs`.
+ */
+export declare function parseCommunication(text: string, notation: UmlNotation): UmlFamilyParse<CommunicationModelV1>;
+export type CommunicationFindingCode = 'UML063_COMMUNICATION_NO_LIFELINES' | 'UML064_COMMUNICATION_LIFELINE_UNLINKED' | 'UML065_COMMUNICATION_MESSAGE_WITHOUT_LINK' | 'UML066_COMMUNICATION_UNDECLARED_ENDPOINT' | 'UML067_COMMUNICATION_SEQUENCE_DUPLICATE' | 'UML068_COMMUNICATION_UNDOCUMENTED';
+export declare const COMMUNICATION_FINDING_CODES: readonly CommunicationFindingCode[];
+/** Sequence numbers as they sort: `2` before `10`, `1.1` before `1.2`. */
+declare function sequenceOrder(left: string, right: string): number;
+/**
+ * What a reader would get wrong about a communication diagram.
+ *
+ * The checks are the ones the diagram exists to answer: is every lifeline reachable, does
+ * every message travel a link that was drawn, does any number appear twice, and is each
+ * participant named after something in the design. The order the numbers imply is *not*
+ * checked against the drawing order - the numbers are the order, and the drawing order is
+ * not a claim.
+ */
+export declare function reviewCommunicationModel(model: CommunicationModelV1, labels: Record<string, string>): UmlFamilyFinding[];
+/** The communication family, as the engine's registry expects it. */
+export declare const communicationModule: UmlFamilyModule<CommunicationModelV1>;
+/** Sort two sequence numbers the way a reader reads them: `2` before `10`, `1.1` before `1.2`. */
+export { sequenceOrder as communicationSequenceOrder };

package/lib/types/uml-composite.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The composite structure diagram module.
+ *
+ * A composite structure diagram is a structured classifier seen from the inside: the parts
+ * it is made of, the ports on its boundary, and the connectors between them. That reads
+ * back out of the text, which is what separates this family from the profile.
+ *
+ * PlantUML has no composite-structure page, so the view is an approximation built from the
+ * deployment diagram's vocabulary: a nested element for the classifier, the nestable
+ * elements for its parts, `port`/`portin`/`portout` for the boundary, and the arrows for
+ * connectors. Nesting is spelled, port direction is spelled, and both connector ends are
+ * spelled - so the model survives the round trip. What the notation cannot say (a part's
+ * type, a port's required interface, a connector's name) stays out of the model rather
+ * than being invented on the way back.
+ *
+ * @module model-everything-uml-composite
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+/** One end of a connector: the classifier itself, one of its ports, or one of its parts. */
+export type CompositeEndpoint = string;
+/** The structured classifier being opened up. */
+export interface CompositeSpec {
+    id: string;
+    label?: string;
+    /** The keyword it is drawn with; `component` is the deployment diagram's default. */
+    kind: string;
+}
+export interface CompositePart {
+    id: string;
+    label?: string;
+}
+export type CompositePortDirection = 'in' | 'out' | 'inout';
+export interface CompositePort {
+    id: string;
+    /** `in` is `portin`, `out` is `portout`, `inout` is the bare `port`. */
+    direction: CompositePortDirection;
+}
+export interface CompositeConnector {
+    from: CompositeEndpoint;
+    to: CompositeEndpoint;
+    label?: string;
+}
+/**
+ * A composite structure diagram as a model.
+ *
+ * `self` is the classifier. Ports and parts belong to it, and a connector endpoint names
+ * one of the three - the classifier itself, a port, or a part. The model has no nesting:
+ * a part of a part is a second diagram, which is how a reader keeps each view readable.
+ */
+export interface CompositeModelV1 {
+    schemaVersion: 1;
+    self: CompositeSpec;
+    parts: CompositePart[];
+    ports: CompositePort[];
+    connectors: CompositeConnector[];
+    /** Ids a connector named that no declaration introduced; the review reports them. */
+    undeclared?: string[];
+    narrative?: {
+        self?: string;
+        parts?: Record<string, string>;
+        ports?: Record<string, string>;
+    };
+}
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * A port id and a part id may not collide: a connector endpoint is a bare name, so two
+ * declarations sharing one would make the drawing say two things at once.
+ */
+export declare function validateCompositeModel(input: unknown): CompositeModelV1;
+/**
+ * Render a composite structure diagram as PlantUML.
+ *
+ * The classifier is drawn as a nested element, its parts inside it, its ports on its
+ * boundary, and the connectors after the block. The `self` directive carries the
+ * classifier's own id, because a nested element's closing brace is the only thing that
+ * says where its inside ends.
+ *
+ * @param input - candidate `CompositeModelV1`.
+ * @param notation - only `plantuml` draws this family; mermaid has no ports or connectors.
+ */
+export declare function renderComposite(input: unknown, notation: UmlNotation): UmlFamilyRender;
+/**
+ * Read a composite structure diagram back into a model.
+ *
+ * Faithful to this module's renderer and tolerant of hand-written text: the classifier is
+ * the outermost block (named by the `compositeSelf` directive when the renderer wrote it),
+ * `port`/`portin`/`portout` lines are its ports, nestable declarations inside the block are
+ * its parts, and every arrow between two names is a connector. A construct the notation
+ * carries but this model does not - a nested block inside a part, a stereotype, a note - is
+ * reported in `discardedConstructs`, never dropped in silence.
+ */
+export declare function parseComposite(text: string, notation: UmlNotation): UmlFamilyParse<CompositeModelV1>;
+export type CompositeFindingCode = 'UML057_COMPOSITE_NO_PARTS' | 'UML058_COMPOSITE_PORT_UNCONNECTED' | 'UML059_COMPOSITE_CONNECTOR_ENDPOINT_MISSING' | 'UML060_COMPOSITE_DUPLICATE_PART' | 'UML061_COMPOSITE_PORT_COLLISION' | 'UML062_COMPOSITE_UNDOCUMENTED';
+export declare const COMPOSITE_FINDING_CODES: readonly CompositeFindingCode[];
+/**
+ * What a reader would get wrong about a composite structure.
+ *
+ * The questions are the ones the diagram exists to answer: is anything inside, does every
+ * port lead somewhere, does every connector join two things that exist, and is each part
+ * and port named after something in the system rather than after its drawing position.
+ * Whether the decomposition is *right* is a question about the design, and this does not
+ * answer it.
+ */
+export declare function reviewCompositeModel(model: CompositeModelV1, labels: Record<string, string>): UmlFamilyFinding[];
+/** The composite structure family, as the engine's registry expects it. */
+export declare const compositeModule: UmlFamilyModule<CompositeModelV1>;