@istar-ts/core 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -69,7 +69,7 @@ export declare function isContributionLabel(value: string): value is Contributio
 export declare function shortKindName(kind: ElementKind | LinkKind): string;
 //#endregion
 //#region src/constraints.d.ts
-export type ConstraintCode = "unknown-element" | "unknown-link-kind" | "invalid-source" | "invalid-target" | "actor-types-differ" | "self-link" | "duplicate-link" | "dependum-endpoint" | "same-actor" | "different-actors" | "refined-depender" | "contributed-depender" | "depender-target" | "mixed-refinement" | "contribution-and-qualification";
+export type ConstraintCode = "unknown-element" | "unknown-link-kind" | "invalid-source" | "invalid-target" | "actor-types-differ" | "self-link" | "duplicate-link" | "dependum-endpoint" | "same-actor" | "different-actors" | "refined-depender" | "contributed-depender" | "depender-target" | "mixed-refinement" | "contribution-and-qualification" | "hub-target" | "incomplete-hub";
 export type LinkCheck = {
   ok: true;
 } | {
@@ -77,6 +77,11 @@ export type LinkCheck = {
   reason: string;
   code: ConstraintCode;
 };
+/**
+ * True for a link, as opposed to an element: the target of a link kind whose rules target links
+ * (see `LinkRules`) may be either.
+ */
+export declare function isLinkRef<EK extends string, LK extends string>(value: IstarElement<EK> | IstarLink<LK>): value is IstarLink<LK>;
 export interface CanLinkOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
   /** Default: the model's metamodel, or iStar 2.0. */
   readonly metamodel?: Metamodel<EK, LK>;
@@ -89,8 +94,13 @@ export interface CanLinkOptions<EK extends string = ElementKind, LK extends stri
  *
  * Extended kinds (see `extendMetamodel`) are checked with the rules of the kind they behave
  * like, or with their declarative rules, then with their extra predicate.
+ *
+ * `target` may be a link (or a link id) for kinds whose rules target links (`LinkRules`).
+ *
+ * For an n-ary kind (`arity: 'n'`), a `target` that is one of its hubs is checked as a new leg
+ * of that hub; any other target, as a new link from `source` to `target`.
  */
-export declare function canLink<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, source: string | IstarElement<EK>, target: string | IstarElement<EK>, kind: LK, options?: CanLinkOptions<EK, LK>): LinkCheck;
+export declare function canLink<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, source: string | IstarElement<EK>, target: string | IstarElement<EK> | IstarLink<LK>, kind: LK, options?: CanLinkOptions<EK, LK>): LinkCheck;
 /**
  * What an extension's `check` predicate receives: the model, the endpoints, and the graph
  * queries the iStar 2.0 rules use.
@@ -101,9 +111,17 @@ export interface LinkRuleContext {
   /** The link kind being added. */
   readonly kind: string;
   readonly source: IstarElement<string>;
-  readonly target: IstarElement<string>;
-  /** A link (optionally of `kind`, or a kind behaving like it) joins `a` and `b`, either way. */
-  isThereLinkBetween(a: IstarElement<string>, b: IstarElement<string>, kind?: string): boolean;
+  /** An element, or a link for kinds whose rules target links (narrow with `isLinkRef`). */
+  readonly target: IstarElement<string> | IstarLink<string>;
+  /**
+   * A link (optionally of `kind`, or a kind behaving like it) joins `a` and `b`, either way. Both
+   * may be elements or links.
+   */
+  isThereLinkBetween(a: {
+    readonly id: string;
+  }, b: {
+    readonly id: string;
+  }, kind?: string): boolean;
   /** `element` is the source of a link of `kind` (or a kind behaving like it). */
   isSourceOfType(element: IstarElement<string>, kind: string): boolean;
   /** `element` is the target of a link of `kind` (or a kind behaving like it). */
@@ -120,7 +138,9 @@ export interface ModelIssue<LK extends string = LinkKind> {
 /**
  * Re-validates every link of a model, the way piStar does when loading a file: dependencies
  * first (each checked before its own links are added), then the remaining links in file
- * order, each against the graph built so far. Invalid links are reported, not removed.
+ * order, each against the graph built so far, and last the links that target links. Invalid
+ * links are reported, not removed. A hub without an end or legs is reported with code
+ * `incomplete-hub`, the hub's id as `linkId` and the n-ary kind as `kind`.
  */
 export declare function validateModel<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options: CanLinkOptions<EK, LK>): ModelIssue<LK>[];
 export declare function validateModel<EK extends string, LK extends string>(model: IstarModel<EK, LK>): ModelIssue<LK>[];
@@ -135,6 +155,10 @@ export type ElementCategory = "actor" | "node";
 export interface KindShape {
   readonly path: string;
   readonly viewBox?: string;
+  /** SVG `stroke-dasharray` of the outline, e.g. `'8,4'` for a dashed shape. */
+  readonly dash?: string;
+  /** Outline width, when it differs from the renderer's default. */
+  readonly strokeWidth?: number;
 }
 export interface KindTextBox {
   readonly top: number;
@@ -167,15 +191,29 @@ export interface ElementKindDefinition<K extends string = string> {
   /** Presentation hints (drawn by `@istar-ts/react`). */
   readonly shape?: KindShape;
   readonly textBox?: KindTextBox;
+  /** `hub` for the kind generated for an n-ary link kind's hubs (see `LinkKindDeclaration.arity`). */
+  readonly role?: "hub";
+  /** For a hub kind: the n-ary link kind it was generated for. */
+  readonly of?: string;
+}
+/** The kinds generated for an n-ary link kind: its hub element kind, leg and end link kinds. */
+export interface HubLinkParts {
+  readonly hub: string;
+  readonly leg: string;
+  readonly end: string;
 }
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
  * which kinds may be the source and target. Entries are kind names (`istar.Goal`,
  * `rationalAgents.Plan`) or categories (`node`, `actor`, `*`). A kind name also matches kinds
  * that behave like it, so `istar.Task` accepts a Planning that behaves like a Task.
+ *
+ * A link may also target another link (NFR's Argument link points at a Contribution): `targets`
+ * then holds `link` (any link) or link kind names. Sources are always elements.
  */
 export interface LinkRules {
   readonly sources: readonly string[];
+  /** Element selectors as for `sources`, plus `link` and link kind names. */
   readonly targets: readonly string[];
   /**
    * Source and target must belong to the same actor (iStar 2.0 Guide, page 14). Default true
@@ -208,13 +246,44 @@ export interface LinkKindDefinition<K extends string = string> {
   readonly extension?: string;
   /** Presentation hint (drawn by `@istar-ts/react`). */
   readonly line?: KindLine;
+  /** `'n'` for an n-ary link kind (several sources joined at a hub); absent means 1. */
+  readonly arity?: 1 | "n";
+  /** For an n-ary kind: the kinds generated for it. */
+  readonly parts?: HubLinkParts;
+  /** For a generated kind: `leg` (a source → the hub) or `end` (the hub → the target). */
+  readonly role?: "leg" | "end";
+  /** For a generated kind: the n-ary link kind it was generated for. */
+  readonly of?: string;
+}
+/**
+ * How a root metamodel's files look, for models that don't come from a file (`createEmptyModel`)
+ * and for writing them (`toPistar`). Files that were read keep their own layout.
+ */
+export interface MetamodelFileHints {
+  /** The `tool` a new model records. Default: piStar's `pistar.2.1.0`. */
+  readonly tool?: string;
+  /** The `istar` version a new model records; only iStar 2.0 sets it (`'2.0'`). */
+  readonly istar?: string;
+  /** Extra top-level keys of a new model (its `extra`), e.g. `{ metamodelVersion: '1.0' }`. */
+  readonly extra?: Readonly<Record<string, unknown>>;
+  /** Top-level key order for models without a source layout. Default: piStar's. */
+  readonly keys?: readonly string[];
 }
 /** A metamodel: the element and link kinds a model may use, and their rules. */
 export interface Metamodel<EK extends string = ElementKind, LK extends string = LinkKind> {
-  /** `istar-2.0`, followed by the names of the extensions applied, e.g. `istar-2.0+rationalAgents`. */
+  /**
+   * The root's name (`istar-2.0`), followed by the names of the extensions applied, e.g.
+   * `istar-2.0+rationalAgents`.
+   */
   readonly name: string;
+  /** The root metamodel's name, e.g. `istar-2.0`; extensions keep it. */
+  readonly framework: string;
+  /** The root's namespace (`istar`). Extensions may not declare kinds in it. */
+  readonly prefix: string;
+  /** How the root's files look (see `MetamodelFileHints`); extensions keep it. */
+  readonly file: MetamodelFileHints;
   readonly extensions: readonly string[];
-  /** In declaration order: iStar 2.0 kinds first, then each extension's. */
+  /** In declaration order: the root's kinds first, then each extension's. */
   readonly elements: ReadonlyMap<EK, ElementKindDefinition<EK>>;
   readonly links: ReadonlyMap<LK, LinkKindDefinition<LK>>;
   /** `type` in piStar files → kind. */
@@ -226,8 +295,6 @@ export type ElementKindOf<M> = M extends Metamodel<infer EK, string> ? EK : neve
 export type LinkKindOf<M> = M extends Metamodel<string, infer LK> ? LK : never;
 /** A metamodel of any dialect, for code that handles every kind generically. */
 export type AnyMetamodel = Metamodel<string, string>;
-/** iStar 2.0, as the piStar tool implements it. The default metamodel everywhere. */
-export declare const ISTAR_2_0: Metamodel;
 export interface ElementKindDeclaration<K extends string = string> {
   /** Namespaced kind name, e.g. `rationalAgents.Planning`. */
   readonly kind: K;
@@ -237,7 +304,10 @@ export interface ElementKindDeclaration<K extends string = string> {
   readonly category?: ElementCategory;
   /** An existing element kind whose link rules this kind follows, e.g. `istar.Task`. */
   readonly behavesLike?: string;
-  /** Containment rules for nodes. Default: those of `behavesLike`, else piStar-ext's (inner, dependum). */
+  /**
+   * Containment rules for nodes. Default: those of `behavesLike`, else piStar-ext's (inner,
+   * dependum) in an extension and DSM3's (inner, dependum, on paper) in a root.
+   */
   readonly info?: Partial<NodeKindInfo>;
   /** Default: that of `behavesLike`, else piStar-ext's 90×55 for nodes and 200×120 for actors. */
   readonly size?: Size;
@@ -257,7 +327,10 @@ export interface LinkKindDeclaration<K extends string = string> {
   readonly category?: LinkCategory;
   /** An existing link kind whose rules this kind takes on, e.g. `istar.OrRefinementLink`. */
   readonly behavesLike?: string;
-  /** Declarative rules; give these or `behavesLike`, not both. */
+  /**
+   * Declarative rules; give these or `behavesLike`, not both. A root's link kind may give
+   * neither when the library has built-in rules for it (iStar 2.0's links).
+   */
   readonly rules?: LinkRules;
   /** An extra predicate, checked after the other rules pass. */
   readonly check?: (context: LinkRuleContext) => LinkCheck;
@@ -266,6 +339,28 @@ export interface LinkKindDeclaration<K extends string = string> {
   readonly pistarType?: string;
   /** Presentation hint, kept as data for renderers (`@istar-ts/react` draws it). */
   readonly line?: KindLine;
+  /**
+   * `'n'` for a link with several sources, like KAOS's AND-refinement: in a model it is a hub
+   * element joined to each source by a leg link and to the target by an end link, as DSM3-goals
+   * draws and saves it. Declaring it generates three kinds, named after this one (`parts`):
+   * `<kind>Hub`, `<kind>Start` and `<kind>End`, written as `<pistarType>Hub` etc. Needs `rules`
+   * and the `node` category.
+   */
+  readonly arity?: "n";
+  /** Names of the generated kinds, when the defaults don't suit. */
+  readonly parts?: Partial<HubLinkParts>;
+  /** The hub's size. Default 20×20, as in DSM3-goals. */
+  readonly hubSize?: Size;
+}
+/** A whole modelling language, turned into a `Metamodel` by `defineMetamodel`. */
+export interface RootMetamodelDeclaration<EK extends string = string, LK extends string = string> {
+  /** Identifies the language; the metamodel's `name` and `framework`, e.g. `istar-2.0`. */
+  readonly name: string;
+  /** The language's namespace, e.g. `istar`. Extensions may not declare kinds in it. */
+  readonly prefix: string;
+  readonly elements: readonly ElementKindDeclaration<EK>[];
+  readonly links: readonly LinkKindDeclaration<LK>[];
+  readonly file?: MetamodelFileHints;
 }
 /** A named set of new kinds, applied to a metamodel with `extendMetamodel`. */
 export interface MetamodelExtension<NEK extends string = string, NLK extends string = string> {
@@ -282,11 +377,27 @@ export declare class MetamodelError extends Error {
  * type the result). Identity at runtime.
  */
 export declare function defineMetamodelExtension<const NEK extends string = never, const NLK extends string = never>(extension: MetamodelExtension<NEK, NLK>): MetamodelExtension<NEK, NLK>;
+/** The `targets` selector for any link (see `LinkRules`). */
+export declare const LINK_SELECTOR = "link";
 /**
- * Returns a new metamodel with the extension's kinds added. `base` is not modified.
+ * Builds a root metamodel: a modelling language of its own, such as iStar 2.0, KAOS or NFR.
+ * Kinds are namespaced (any namespace; usually `prefix`), declared in order: `behavesLike` and
+ * link rules refer to kinds declared before them. Extensions of the result may not use `prefix`.
  *
- * Throws `MetamodelError` when a kind name isn't namespaced, uses the reserved `istar.`
- * prefix, collides with an existing kind or piStar type, or refers to an unknown kind.
+ * Throws `MetamodelError` on the same declaration errors as `extendMetamodel`.
+ */
+export declare function defineMetamodel<const EK extends string, const LK extends string>(declaration: RootMetamodelDeclaration<EK, LK>): Metamodel<EK, LK>;
+/** iStar 2.0's declaration, built from the constants in `metamodel.ts`. */
+export declare const ISTAR_2_0_DECLARATION: RootMetamodelDeclaration<ElementKind, LinkKind>;
+/** iStar 2.0, as the piStar tool implements it. The default metamodel everywhere. */
+export declare const ISTAR_2_0: Metamodel;
+/**
+ * Returns a new metamodel with the extension's kinds added. `base` is not modified. The result
+ * keeps `base`'s `framework`, `prefix` and `file`.
+ *
+ * Throws `MetamodelError` when a kind name isn't namespaced, uses the root's reserved prefix
+ * (`istar.` for iStar 2.0), collides with an existing kind or piStar type, or refers to an
+ * unknown kind.
  */
 export declare function extendMetamodel<EK extends string, LK extends string, const NEK extends string = never, const NLK extends string = never>(base: Metamodel<EK, LK>, extension: MetamodelExtension<NEK, NLK>): Metamodel<EK | NEK, LK | NLK>;
 export declare function elementKindDefinition(metamodel: AnyMetamodel, kind: string): ElementKindDefinition | undefined;
@@ -302,6 +413,10 @@ export declare function isNodeKindIn(metamodel: AnyMetamodel, kind: string): boo
 export declare function effectiveElementKind(metamodel: AnyMetamodel, kind: string): string;
 /** Like `effectiveElementKind`, for link kinds. */
 export declare function effectiveLinkKind(metamodel: AnyMetamodel, kind: string): string;
+/** True when link `kind` is `ancestor` or (transitively) behaves like it. */
+export declare function linkBehavesLike(metamodel: AnyMetamodel, kind: string, ancestor: string): boolean;
+/** True when a link kind's rules let it target links (`link` or a link kind in `targets`). */
+export declare function targetsLinks(metamodel: AnyMetamodel, kind: string): boolean;
 /** True when `kind` is `ancestor` or (transitively) behaves like it. */
 export declare function elementBehavesLike(metamodel: AnyMetamodel, kind: string, ancestor: string): boolean;
 //#endregion
@@ -401,6 +516,13 @@ export interface IstarModel<EK extends string = ElementKind, LK extends string =
 /** Tool identifier written by piStar 2.1.0, whose file format this library emulates. */
 export declare const PISTAR_TOOL = "pistar.2.1.0";
 export declare const ISTAR_VERSION = "2.0";
+/**
+ * DSM3-goals' file conventions, shared by its languages (KAOS, NFR; see `@istar-ts/dsm3-kaos`
+ * and `@istar-ts/dsm3-nfr`): the `tool` its editors write, and the order of their top-level keys
+ * (`fileManager.js`). Use them as a root's `file.tool` and `file.keys`.
+ */
+export declare const DSM3_TOOL = "dsm3-goals";
+export declare const DSM3_FILE_KEYS: readonly string[];
 export declare const DEFAULT_DIAGRAM: Diagram;
 /** A model of any dialect, for code that handles every kind generically. */
 export type AnyIstarModel = IstarModel<string, string>;
@@ -441,13 +563,38 @@ export declare function isActorIn(metamodel: AnyMetamodel): (element: IstarEleme
 export declare function isNodeIn(metamodel: AnyMetamodel): (element: IstarElement<string> | undefined) => boolean;
 /** Inner elements of an actor, in model order. */
 export declare function childrenOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>, actorId: string): IstarElement<EK>[];
-/** Links that have the element as source or target. */
+/**
+ * Links that have the element as source or target. Given a link id, the links that target that
+ * link (see `LinkRules`).
+ */
 export declare function linksOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>, elementId: string): IstarLink<LK>[];
 /** For a dependum, the two halves of its dependency: depender → dependum → dependee. */
 export declare function dependencyLinksOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>, dependumId: string): {
   inbound?: IstarLink<LK>;
   outbound?: IstarLink<LK>;
 };
+/** What a link points at: an element, or a link for kinds whose rules target links. */
+export declare function linkTargetOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>, link: IstarLink<LK>): IstarElement<EK> | IstarLink<LK> | undefined;
+/** An n-ary link as it lives in a model: its hub element, its legs (in link order), its end. */
+export interface HubLink<EK extends string = ElementKind, LK extends string = LinkKind> {
+  readonly hub: IstarElement<EK>;
+  readonly legs: readonly IstarLink<LK>[];
+  /** Absent only in an incomplete model (`validateModel` reports it). */
+  readonly end?: IstarLink<LK>;
+}
+/** True when `element` is the hub of an n-ary link. */
+export declare function isHubElement(metamodel: AnyMetamodel, element: IstarElement<string> | undefined): boolean;
+/** The n-ary link whose hub is `hubId`; `undefined` when it isn't a hub. */
+export declare function hubLinkOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>, hubId: string): HubLink<EK, LK> | undefined;
+/** The hub a leg or end link belongs to. */
+export declare function hubOfLink<EK extends string, LK extends string>(model: IstarModel<EK, LK>, linkId: string): IstarElement<EK> | undefined;
+/** The centre of an element's box: its display size, else its kind's default size. */
+export declare function elementCenter<EK extends string, LK extends string>(model: IstarModel<EK, LK>, element: IstarElement<EK>): Point;
+/**
+ * Where a new hub goes: centred between the source and the target, as DSM3-goals places it.
+ * Returns its top-left corner for a hub of `size`.
+ */
+export declare function defaultHubPosition<EK extends string, LK extends string>(model: IstarModel<EK, LK>, source: IstarElement<EK>, target: IstarElement<EK>, size: Size): Point;
 //#endregion
 //#region src/file-metamodel.d.ts
 /** The top-level key of the block in piStar JSON. */
@@ -508,6 +655,30 @@ export interface PistarLinkJson {
   label?: string;
   [key: string]: unknown;
 }
+/** The hub of an n-ary link, in a hub entry: an element without `text`. */
+export interface PistarHubJson {
+  id: string;
+  type: string;
+  x: number;
+  y: number;
+  customProperties?: Record<string, string>;
+  [key: string]: unknown;
+}
+/**
+ * An n-ary link (see `LinkKindDeclaration.arity`) in `links`, as DSM3-goals writes it: no id of
+ * its own, its hub, its legs (`starts`) and its end.
+ */
+export interface PistarHubLinkJson {
+  hub: PistarHubJson;
+  starts: PistarLinkJson[];
+  end?: PistarLinkJson;
+  [key: string]: unknown;
+}
+/**
+ * Key of a hub element's `extra` that holds its entry's unknown keys (those beside `hub`,
+ * `starts` and `end`), so they are written back on the entry.
+ */
+export declare const HUB_ENTRY_KEY = "__hubEntry";
 export interface PistarDiagramJson {
   width?: number;
   height?: number;
@@ -520,7 +691,7 @@ export interface PistarFile {
   actors: PistarActorJson[];
   orphans?: PistarElementJson[];
   dependencies?: PistarDependencyJson[];
-  links?: PistarLinkJson[];
+  links?: (PistarLinkJson | PistarHubLinkJson)[];
   display?: Record<string, Record<string, unknown>>;
   tool?: string;
   istar?: string;
@@ -579,6 +750,18 @@ export declare function parsePistar<EK extends string, LK extends string>(input:
 }): IstarModel<EK, LK>;
 export declare function parsePistar(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions): IstarModel;
 export declare function parsePistar(input: string | PistarFile | Record<string, unknown>): IstarModel;
+/**
+ * The namespace of the first `type` in a file (`kaos` for `kaos.Softgoal`), looking at actors and
+ * their nodes, orphans, dependencies, then links (hub entries included). `undefined` when no
+ * element or link has a namespaced type. Throws `PistarParseError` for a string that isn't JSON.
+ */
+export declare function detectPrefix(json: string | Record<string, unknown>): string | undefined;
+/**
+ * Which of `roots` a file is written in: the one whose `prefix` is the file's (`detectPrefix`);
+ * for a file without types, the only one whose `file.tool` is the file's `tool`; otherwise
+ * `undefined`. Pass the result to `parsePistar(json, { metamodel })`.
+ */
+export declare function detectFramework(json: string | Record<string, unknown>, roots: readonly AnyMetamodel[]): AnyMetamodel | undefined;
 export interface ToPistarOptions {
   /** Default: the model's metamodel, or iStar 2.0. Decides each kind's `type` and category. */
   metamodel?: AnyMetamodel;
@@ -607,7 +790,7 @@ export declare function fileMetamodelOf<EK extends string, LK extends string>(mo
  */
 export declare function withFileMetamodel<EK extends string, LK extends string>(model: IstarModel<EK, LK>, block: FileMetamodel | null): IstarModel<string, string>;
 declare namespace operations_d_exports {
-  export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, updateDiagram, updateElement, updateLink };
+  export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, addLeg, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, removeLeg, updateDiagram, updateElement, updateLink };
 }
 export declare class ModelOperationError extends Error {
   override name: string;
@@ -657,7 +840,8 @@ export declare function moveElement<EK extends string = ElementKind, LK extends
 export declare function nestElement<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, id: string, parent: string | null): IstarModel<EK, LK>;
 /**
  * Removes elements and everything that depends on them: inner elements of removed actors,
- * links touching removed elements, and the rest of any dependency that loses a part.
+ * links touching removed elements (and links targeting removed links), and the rest of any
+ * dependency that loses a part.
  */
 export declare function removeElements<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, ids: Iterable<string>): IstarModel<EK, LK>;
 export declare function removeElement<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, id: string): IstarModel<EK, LK>;
@@ -665,6 +849,7 @@ export interface NewLink<K extends string = LinkKind> {
   /** Any link kind except dependency kinds (use `addDependency` for those). */
   readonly kind: Exclude<K, DependencyLinkKind>;
   readonly source: string;
+  /** An element id, or a link id for kinds whose rules target links. */
   readonly target: string;
   readonly id?: string;
   /** Contribution value: make, help, hurt or break. */
@@ -684,13 +869,35 @@ export interface ConnectOptions extends OperationContext {
 export type ConnectResult<EK extends string = ElementKind, LK extends string = LinkKind> = {
   ok: true;
   model: IstarModel<EK, LK>;
+  /** The new link; for an n-ary kind, the new leg or (for a new hub) the end. */
   link: IstarLink<LK>;
   reversed: boolean;
+  /** For an n-ary kind: the hub link the new link belongs to, as it now is. */
+  hub?: HubLink<EK, LK>;
 } | Extract<LinkCheck, {
   ok: false;
 }>;
-/** Adds a link between two elements if the iStar constraints allow it. */
+/**
+ * Adds a link between two elements if the iStar constraints allow it.
+ *
+ * With an n-ary kind (`arity: 'n'`), a `target` that is one of the kind's hubs gets a new leg
+ * from `source` (see `addLeg`). Any other target gets a new hub, centred between source and
+ * target, with a leg from `source` and an end to `target`. `input.id` and `customProperties`
+ * then go to the hub, and `label` and `name` to the end.
+ */
 export declare function connect<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, input: NewLink<LK>, options?: ConnectOptions): ConnectResult<EK, LK>;
+/**
+ * Adds a leg from `source` to the hub `hubId` of an n-ary link (one more source for it), if the
+ * kind's rules allow it. `options.id` is the leg's id.
+ */
+export declare function addLeg<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, hubId: string, source: string, options?: ConnectOptions & {
+  readonly id?: string;
+}): ConnectResult<EK, LK>;
+/**
+ * Removes one leg of an n-ary link. Removing its last leg removes the whole link (hub and end),
+ * as `disconnect` does.
+ */
+export declare function removeLeg<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, legId: string): IstarModel<EK, LK>;
 export interface NewDependency<EK extends string = ElementKind, LK extends string = LinkKind> {
   /** The depender: an actor or one of its inner elements. */
   readonly depender: string;
@@ -720,7 +927,10 @@ export type AddDependencyResult<EK extends string = ElementKind, LK extends stri
 }>;
 /** Adds depender → dependum → dependee. */
 export declare function addDependency<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, input: NewDependency<EK, LK>, options?: Omit<ConnectOptions, "tryReversed">): AddDependencyResult<EK, LK>;
-/** Removes a link. Removing either half of a dependency removes the whole dependency. */
+/**
+ * Removes a link, and the links that target it. Removing either half of a dependency removes
+ * the whole dependency.
+ */
 export declare function disconnect<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, id: string): IstarModel<EK, LK>;
 export interface LinkPatch {
   /** `null` removes it. */
@@ -763,6 +973,10 @@ export type ModelChange = {
 } | {
   type: "connect";
   id: string;
+  hubId?: string;
+} | {
+  type: "removeLeg";
+  id: string;
 } | {
   type: "addDependency";
   dependumId: string;
@@ -802,7 +1016,7 @@ export interface ModelStore<EK extends string = ElementKind, LK extends string =
   getModel(): IstarModel<EK, LK>;
   /** Returns an unsubscribe function. */
   subscribe(listener: ModelListener<EK, LK>): () => void;
-  canLink(source: string | IstarElement<EK>, target: string | IstarElement<EK>, kind: LK): LinkCheck;
+  canLink(source: string | IstarElement<EK>, target: string | IstarElement<EK> | IstarLink<LK>, kind: LK): LinkCheck;
   addElement(input: NewElement<EK>): IstarElement<EK>;
   updateElement(id: string, patch: ElementPatch): void;
   moveElement(id: string, x: number, y: number): void;
@@ -812,6 +1026,12 @@ export interface ModelStore<EK extends string = ElementKind, LK extends string =
   setCollapsed(actorId: string, collapsed: boolean): void;
   connect(input: NewLink<LK>, options?: Omit<ConnectOptions, "createId">): ConnectResult<EK, LK>;
   addDependency(input: NewDependency<EK, LK>, options?: Omit<ConnectOptions, "createId" | "tryReversed">): AddDependencyResult<EK, LK>;
+  /** Adds a leg from `source` to the hub of an n-ary link (see `ops.addLeg`). */
+  addLeg(hubId: string, source: string, options?: Omit<ConnectOptions, "createId" | "tryReversed"> & {
+    readonly id?: string;
+  }): ConnectResult<EK, LK>;
+  /** Removes a leg; the last one takes its hub and end with it. */
+  removeLeg(id: string): void;
   updateLink(id: string, patch: LinkPatch): void;
   disconnect(id: string): void;
   updateDiagram(patch: Partial<Diagram>): void;
@@ -908,4 +1128,137 @@ export declare function defineProperties<const S extends PropertyShape, const Ki
 }): PropertySchema<S, Kind>;
 export declare function validateModelProperties<EK extends string, LK extends string>(model: IstarModel<EK, LK>, schemas: readonly PropertySchema<PropertyShape, string>[]): ModelPropertyIssue[];
 //#endregion
+//#region src/diagnostics.d.ts
+/**
+ * The Goal Model Diagnostics Protocol: findings about a model's elements and links, published by
+ * any analyser (a language server, a validator, a simulation…) and anchored by element id rather
+ * than by text position. Data only: diagnostics are never part of the model and are never
+ * written to disk.
+ *
+ * See goal-controller issue #24 (option D). Producers publish per source; consumers see the
+ * union of every source, deduplicated by `(elementId, key, message)`.
+ */
+export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+/** Most severe first. */
+export declare const DIAGNOSTIC_SEVERITIES: readonly DiagnosticSeverity[];
+/** A zero-based position in the producer's document (as in LSP). */
+export interface DiagnosticPosition {
+  readonly line: number;
+  readonly character: number;
+}
+export interface DiagnosticRange {
+  readonly start: DiagnosticPosition;
+  readonly end: DiagnosticPosition;
+}
+export interface GoalDiagnostic {
+  /** Id of the element or link the diagnostic is about. */
+  readonly elementId: string;
+  /** The custom property it is about; absent for the element as a whole. */
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+  /** Who published it (e.g. `mutrose`, `goal-language`). */
+  readonly source?: string;
+  /** Where it was found in the producer's document, if it has one. */
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+  /** Producer data, passed through untouched. */
+  readonly data?: unknown;
+}
+/** Negative when `a` is more severe than `b`. */
+export declare function compareSeverity(a: DiagnosticSeverity, b: DiagnosticSeverity): number;
+/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
+export declare function worstDiagnosticSeverity(diagnostics: readonly {
+  readonly severity: DiagnosticSeverity;
+}[] | undefined): DiagnosticSeverity | undefined;
+/**
+ * The union of several lists, in order, without duplicates: diagnostics with the same
+ * `(elementId, key, message)` count once, keeping the first one's position and the most severe
+ * severity among them.
+ */
+export declare function mergeDiagnostics(lists: Iterable<readonly GoalDiagnostic[] | undefined>): GoalDiagnostic[];
+/** Diagnostics by element (or link) id, each list in the input order. */
+export declare function groupDiagnostics(diagnostics: readonly GoalDiagnostic[] | undefined): ReadonlyMap<string, readonly GoalDiagnostic[]>;
+/**
+ * Holds the diagnostics of several sources. Each `publish` replaces that source's set, so a
+ * producer re-publishes everything it currently reports, as an LSP server does.
+ */
+export interface DiagnosticsStore {
+  /**
+   * Replaces `source`'s diagnostics (an empty list clears them). Entries without a `source` get
+   * this one.
+   */
+  publish(source: string, diagnostics: readonly GoalDiagnostic[]): void;
+  /** Removes one source's diagnostics, or every source's. */
+  clear(source?: string): void;
+  /** Sources with diagnostics, in the order they first published. */
+  sources(): readonly string[];
+  /** One source's diagnostics. */
+  get(source: string): readonly GoalDiagnostic[];
+  /**
+   * Every source's diagnostics, merged (see `mergeDiagnostics`). The same array until the next
+   * change, so it can back `useSyncExternalStore`.
+   */
+  getAll(): readonly GoalDiagnostic[];
+  subscribe(listener: () => void): () => void;
+}
+export declare function createDiagnosticsStore(): DiagnosticsStore;
+/**
+ * The parts of an LSP `Diagnostic` the adapter reads (structurally typed, so no LSP library is
+ * needed). The element is taken from `data.elementId`, or MutRoSe's `data.nodeId`; the property
+ * from `data.key`.
+ */
+export interface LspDiagnosticLike {
+  readonly range?: DiagnosticRange;
+  /** LSP numbering: 1 error, 2 warning, 3 information, 4 hint. */
+  readonly severity?: number;
+  readonly message: string | {
+    readonly value: string;
+  };
+  readonly source?: string;
+  readonly code?: string | number | {
+    readonly value: string | number;
+  };
+  readonly data?: unknown;
+}
+export interface FromLspOptions<D extends LspDiagnosticLike = LspDiagnosticLike> {
+  /**
+   * The element of a diagnostic whose `data` names none, e.g. by looking its range up in the
+   * document. Return `undefined` to drop it.
+   */
+  readonly elementIdFor?: (diagnostic: D) => string | undefined;
+  /**
+   * `'vscode'` for `vscode.Diagnostic` objects, whose severity counts from 0 (error) to 3
+   * (hint). Default `'lsp'`, the protocol's 1 to 4.
+   */
+  readonly severityNumbering?: "lsp" | "vscode";
+}
+/**
+ * One LSP diagnostic anchored by `data.elementId` (or `data.nodeId`), or `undefined` when it
+ * names no element. For range-anchored diagnostics use `fromLspDiagnostics` with `elementIdFor`.
+ */
+export declare function fromLspDiagnostic(diagnostic: LspDiagnosticLike): GoalDiagnostic | undefined;
+/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
+export declare function fromLspDiagnostics<D extends LspDiagnosticLike>(diagnostics: readonly D[], options?: FromLspOptions<D>): GoalDiagnostic[];
+/**
+ * The shape MutRoSe's VS Code extension posts to its webview: `{ nodeId, severity, message }`
+ * (plus `range` and `source`). `nodeId` is missing when no node could be found.
+ */
+export interface NodeIdDiagnostic {
+  readonly nodeId?: string;
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity | string;
+  readonly message: string;
+  readonly source?: string;
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+}
+/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
+export declare function fromNodeIdDiagnostic(diagnostic: NodeIdDiagnostic): GoalDiagnostic | undefined;
+/**
+ * `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
+ * without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+ */
+export declare function fromNodeIdDiagnostics(diagnostics: readonly NodeIdDiagnostic[]): GoalDiagnostic[];
+//#endregion
 //# sourceMappingURL=index.d.cts.map