yarramate 1.3.0 → 1.4.0

package/dist/visual-app-lib/types/adapters/visual/workspace-model.d.ts

@@ -49,13 +49,25 @@ export declare const conceptCountOf: (graph: SemanticGraph, query: ProjectionQue
  * Subject ids come from the same compiled graph as `CanvasNode.id`, so the
  * join in the browser is a plain lookup.
  */
+export interface DismissedQuestion {
+    readonly questionId: string;
+    /** Absent dismisses the question wherever it appears. */
+    readonly subject?: string;
+}
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
 }, catalogue: {
     readonly path: string;
     readonly source: string;
-}) => VisualInterrogationOverlay | undefined;
+}, 
+/**
+ * What the host has already dealt with (#328). Evaluation is unchanged and
+ * the model is untouched: this decides only what the pane draws, because a
+ * question set aside in the host's own product should not be asked again by
+ * a pane embedded in it.
+ */
+dismissed?: readonly DismissedQuestion[]) => VisualInterrogationOverlay | undefined;
 /**
  * Rebuilds the shared editor workspace from one successful compile.
  *
@@ -71,7 +83,7 @@ export declare const renderedWorkspaceOf: (compiled: {
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;
-}) => {
+}, dismissed?: readonly DismissedQuestion[]) => {
     readonly model: VisualRenderedModel;
     readonly views: readonly VisualViewSummary[];
 };

package/dist/visual-app-lib/types/compiler.d.ts

@@ -74,6 +74,18 @@ export interface ResolvedProfileContext {
     /** Kind identity -> the core kind it resolves to through lineage. */
     readonly conceptKindCoreAncestors: ReadonlyMap<string, CoreConceptKindId>;
     readonly relationshipKindCoreAncestors: ReadonlyMap<string, RelationshipKind>;
+    /**
+     * The core relationship kinds a pattern PORTS for a concept kind (#268
+     * phase 3, ADR 0124), keyed by kind identity. Only kinds that have a
+     * pattern with ports appear.
+     *
+     * A macro edge needs both ends to port its kind, so a consumer offering a
+     * palette between two instances intersects the two sets. Two raw groupings
+     * permit ten of the eleven kinds, which is no narrowing at all; the ports
+     * are what restore the guidance the relationship table gives everywhere
+     * else.
+     */
+    readonly patternPortKinds: ReadonlyMap<string, readonly RelationshipKind[]>;
     /**
      * The core relationship kinds the ArchiMate table permits between two
      * concept kind identities, resolved through lineage; undefined when either
@@ -104,7 +116,7 @@ export type ContextualCompilationResult = {
  */
 export interface ParsedWorkspaceSource {
     readonly source: string;
-    readonly kind: 'profile' | 'document';
+    readonly kind: 'profile' | 'document' | 'pattern';
     readonly value: unknown;
     readonly schemaDiagnostics: readonly Diagnostic[];
     /**

package/dist/visual-app-lib/types/graph-projection.d.ts

@@ -14,6 +14,16 @@ export interface CanvasNode {
      * profile kind it was authored as.
      */
     readonly coreKindLabel: string;
+    /**
+     * The core relationship kinds this node's PATTERN ports, or `[]` where its
+     * kind has no pattern with ports (#268 phase 3, ADR 0124).
+     *
+     * A macro edge needs both ends to port its kind, so an editor offering a
+     * palette between two instances intersects the two lists. Two raw groupings
+     * permit ten of the eleven kinds, which is no guidance at all; this is what
+     * restores the narrowing the relationship table gives everywhere else.
+     */
+    readonly portKinds: readonly string[];
     readonly layer: Layer | null;
     readonly aspect: Aspect | null;
     readonly name: string;

package/dist/visual-app-lib/types/interrogate-command.d.ts

@@ -87,6 +87,8 @@ export type CatalogueCondition = {
     readonly condition: 'unscoped-succession';
 } | {
     readonly condition: 'unchallenged-evidence';
+} | {
+    readonly condition: 'has-any-subject';
 };
 /**
  * One observation from the workspace's evidence overlay, reduced to what
@@ -131,6 +133,11 @@ export interface QuestionCatalogue {
         readonly id: string;
         readonly name: string;
         readonly description?: string;
+        /**
+         * Conditions that must all hold before this wave opens (#334, ADR 0125).
+         * Absent means always open, which is what every wave did before this.
+         */
+        readonly opensWhen?: readonly CatalogueCondition[];
     }[];
     readonly questions: readonly CatalogueQuestion[];
 }
@@ -161,6 +168,16 @@ export interface ReportQuestion {
 export interface ReportWave {
     readonly id: string;
     readonly name: string;
+    /**
+     * Whether the wave's gate is met (#334, ADR 0125). A wave with no
+     * `opensWhen` is always open.
+     *
+     * A wave reported `false` carries NO questions and contributes nothing to
+     * the summary. Its questions are premature rather than answered, and a
+     * progress rail that counted them as answered would flatter itself exactly
+     * where someone is most likely to trust it.
+     */
+    readonly opened: boolean;
     readonly questions: readonly ReportQuestion[];
 }
 export interface InterrogationSummary {

package/dist/visual-app-lib/types/visual-app/local-host.d.ts

@@ -34,5 +34,47 @@ export interface LocalHostOptions {
     readonly description?: string;
     /** Told after every landed commit, so a host can persist what it was given. */
     readonly onCommit?: (documents: readonly string[]) => void;
+    /**
+     * The question catalogue the questions section evaluates, or the shipped
+     * `core-enrichment` one when absent (#328).
+     *
+     * The engine is yarramate's and so is the UI; the QUESTIONS belong to
+     * whoever adopted it. `core-enrichment` is a general modelling interview,
+     * right for this repository's own CLI and for a host with no domain of its
+     * own, and wrong for a product whose interview is about its own subject
+     * matter. Until this existed a host could have the questions UI only by
+     * also running yarramate's catalogue, so a product with its own interview
+     * had to omit the section and show its questions on a separate surface,
+     * away from the model they are about.
+     *
+     * Bytes rather than a parsed catalogue, matching what the seam beneath
+     * already takes: a catalogue that does not load leaves the overlay absent
+     * rather than failing the mount, because the overlay is a garnish on the
+     * model and a model frame must not be blocked by it.
+     */
+    readonly catalogue?: {
+        readonly path: string;
+        readonly source: string;
+    };
+    /**
+     * Questions this host has already dealt with and does not want asked again
+     * (#328).
+     *
+     * A host-supplied catalogue alone does not close this: the editor evaluates
+     * the catalogue itself and cannot know that a reviewer set a question aside,
+     * with a reason, recorded somewhere the editor cannot see. Without this the
+     * pane would go on asking a question its own product had answered.
+     *
+     * `subject` absent dismisses the question wherever it appears - the
+     * workspace-scoped entry and every subject's - which is "stop asking this".
+     * `subject` present dismisses it for that subject alone, which is "not for
+     * this one". Dismissal hides a question from the pane and changes nothing
+     * about the model or about what `ask --open` reports; the interview is not
+     * the editor's to settle.
+     */
+    readonly dismissed?: readonly {
+        readonly questionId: string;
+        readonly subject?: string;
+    }[];
 }
 export declare const createLocalHost: (options: LocalHostOptions) => EditorHost;

package/dist/visual-app-lib/types/workspace.d.ts

@@ -6,6 +6,7 @@ export interface WorkspaceManifest {
     readonly profiles: readonly string[];
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
+    readonly patterns?: readonly string[];
     readonly evidence?: readonly string[];
     readonly contracts?: readonly string[];
 }
@@ -15,6 +16,7 @@ export interface ResolvedWorkspace {
     readonly profiles: readonly string[];
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
+    readonly patterns: readonly string[];
     readonly evidence: readonly string[];
     readonly contracts: readonly string[];
 }

package/dist/workspace.d.ts

@@ -6,6 +6,7 @@ export interface WorkspaceManifest {
     readonly profiles: readonly string[];
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
+    readonly patterns?: readonly string[];
     readonly evidence?: readonly string[];
     readonly contracts?: readonly string[];
 }
@@ -15,6 +16,7 @@ export interface ResolvedWorkspace {
     readonly profiles: readonly string[];
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
+    readonly patterns: readonly string[];
     readonly evidence: readonly string[];
     readonly contracts: readonly string[];
 }

package/dist/workspace.js

@@ -106,6 +106,7 @@ export function loadWorkspaceManifest(source, cwd) {
         profiles: expand('profiles', 'profile', value.profiles),
         projections: expand('projections', 'projection', value.projections),
         adapterMappings: expand('adapterMappings', 'adapter mapping', value.adapterMappings),
+        patterns: expand('patterns', 'pattern', value.patterns ?? []),
         evidence: expand('evidence', 'evidence', value.evidence ?? []),
         contracts: expand('contracts', 'Core contract', value.contracts ?? []),
     };

package/docs/CONSUMING-YARRAMATE.md

@@ -298,6 +298,47 @@ const editor = mountEditor(document.querySelector('#editor')!, {
 editor.unmount()
 ```
 
+### The questions are yours
+
+The questions section evaluates the shipped `core-enrichment` catalogue by
+default. A host with its own interrogation supplies its own instead (#328):
+
+```ts
+const editor = mountEditor(element, {
+  store,
+  workspace,
+  sections: ['palette', 'properties', 'questions', 'changes'],
+  catalogue: { path: 'catalogues/consulting.yaml', source: catalogueText },
+  dismissed: [
+    { questionId: 'register-fidelity', subject: 'crm-integration' },
+    { questionId: 'engagement-framing' },
+  ],
+})
+```
+
+The division this draws is deliberate. **The engine is yarramate's and so is
+the UI; the questions belong to whoever adopted it.** `core-enrichment` is a
+general modelling interview — right for yarramate's own CLI, and right for a
+host with no domain of its own — and wrong for a product whose interview is
+about its own subject matter. Inheriting it would mean asking a consultant
+about modelling hygiene in the pane where they are asking a client about
+sign-off.
+
+`catalogue` takes bytes, and a catalogue that does not load leaves the overlay
+absent rather than failing the mount: the overlay is a garnish on the model,
+and a model frame must not be blocked by it.
+
+`dismissed` is what the host has already dealt with. A supplied catalogue
+alone does not cover this — the editor evaluates the catalogue itself and
+cannot know that a reviewer set a question aside, with a reason, recorded
+somewhere the editor cannot see, so the pane would go on asking a question the
+host's own product had answered. Naming a `subject` dismisses the question for
+that subject alone; omitting it dismisses the question wherever it appears.
+
+Dismissal decides what the **pane draws** and nothing else. The model is
+untouched and `ask --open` still reports the question, because the interview is
+not the editor's to settle.
+
 Pass `readOnly: true` to mount a viewer over the same surface — for a frozen
 published snapshot, say ([ADR 0117](adr/0117-a-mounted-editor-can-refuse-the-pen.md)).
 The reviewer still selects, filters, navigates views and reads questions and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -65,6 +65,7 @@
     "./visual-app/styles.css": "./dist/visual-app-lib/styles.css",
     "./schema/document": "./schema/yarramate-document.schema.json",
     "./schema/profile": "./schema/yarramate-profile.schema.json",
+    "./schema/pattern": "./schema/yarramate-pattern.schema.json",
     "./schema/projection": "./schema/yarramate-projection.schema.json",
     "./schema/projection-result": "./schema/yarramate-projection-result.schema.json",
     "./schema/adapter-mapping": "./schema/yarramate-adapter-mapping.schema.json",

package/schema/yarramate-design-step.schema.json

@@ -534,6 +534,19 @@
             }
           }
         },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The workspace holds at least one concept (#334, ADR 0125). The guard a late wave needs to say \"only once the model has substance\": an empty model is not an architecture at rest, it has not started, and asking it how the planned architecture becomes real greets someone ahead of question one.",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "has-any-subject"
+            }
+          }
+        },
         {
           "type": "object",
           "additionalProperties": false,

package/schema/yarramate-document.schema.json

@@ -151,6 +151,20 @@
             "$ref": "#/$defs/constraint"
           }
         },
+        "parts": {
+          "description": "The subjects that fill this instance's pattern slots, by slot name (ADR 0123). Valid only on a kind that has a pattern; the compiler mints the pattern's wiring between the instance and what these name, and refuses any authored relationship that contradicts it. Binding, not generation: a part keeps its own name, owner, evidence and outside edges.",
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": false,
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "patternProperties": {
+            "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$": {
+              "$ref": "#/$defs/reference"
+            }
+          }
+        },
         "references": {
           "$ref": "#/$defs/identifiedReferences"
         },

package/schema/yarramate-interrogation-report.schema.json

@@ -66,6 +66,7 @@
       "required": [
         "id",
         "name",
+        "opened",
         "questions"
       ],
       "properties": {
@@ -77,6 +78,10 @@
           "type": "string",
           "minLength": 1
         },
+        "opened": {
+          "description": "Whether this wave's gate is met (#334, ADR 0125). A wave with no `opensWhen` is always true. A wave reported false asks nothing and carries no questions: they are premature rather than answered, which is the third state a progress rail needs so a closed wave is not counted as done. Its questions are excluded from `summary` for the same reason.",
+          "type": "boolean"
+        },
         "questions": {
           "type": "array",
           "items": {
@@ -533,6 +538,19 @@
             }
           }
         },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The workspace holds at least one concept (#334, ADR 0125). The guard a late wave needs to say \"only once the model has substance\": an empty model is not an architecture at rest, it has not started, and asking it how the planned architecture becomes real greets someone ahead of question one.",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "has-any-subject"
+            }
+          }
+        },
         {
           "type": "object",
           "additionalProperties": false,

package/schema/yarramate-pattern.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/pattern/v1",
+  "title": "YarraMate structural pattern",
+  "description": "The shape a concept kind promises: the parts an instance binds and the wiring the compiler mints between them (ADR 0123). A pattern declares structure; a profile declares vocabulary. Expansion is compile-time and lands in the semantic graph, never in a document.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "id", "version", "patterns"],
+  "properties": {
+    "format": {
+      "const": "yarramate/pattern/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "patterns": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/pattern"
+      }
+    }
+  },
+  "$defs": {
+    "pattern": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "parts", "wiring"],
+      "properties": {
+        "kind": {
+          "description": "The globally qualified concept kind this pattern shapes. The kind's anchor is whatever the profile says it specializes; a pattern never restates it.",
+          "$ref": "#/$defs/qualifiedKind"
+        },
+        "parts": {
+          "description": "The slots an instance binds, by name. A slot names the kind the bound subject must be, and whether an instance must bind it.",
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": false,
+          "propertyNames": {
+            "$ref": "#/$defs/slotName"
+          },
+          "patternProperties": {
+            "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$": {
+              "$ref": "#/$defs/part"
+            }
+          }
+        },
+        "ports": {
+          "description": "Where a macro-grain edge lands canonically (#268 phase 2, ADR 0124). A relationship authored between two instances whose patterns both declare a port for its kind is expanded: `out` names the slot it leaves from on the source instance, `in` the slot it arrives at on the target. The macro edge itself survives - it is an authored fact, which is what gives a collapsed view edges to draw.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/port"
+          }
+        },
+        "wiring": {
+          "description": "The relationships the compiler mints between an instance and its bound parts. Where an authored relationship already says exactly this, nothing is minted. Any other authored relationship between the same pair contradicts the pattern and fails compilation.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/wire"
+          }
+        }
+      }
+    },
+    "part": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/qualifiedKind"
+        },
+        "required": {
+          "description": "An instance that leaves a required slot unbound fails compilation (YM416). Absent means optional.",
+          "type": "boolean"
+        }
+      }
+    },
+    "port": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "out", "in"],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/qualifiedKind"
+        },
+        "out": {
+          "description": "The slot a macro edge of this kind leaves from, on the SOURCE instance. Never `self`: an edge that left from the instance would be the macro edge again.",
+          "$ref": "#/$defs/slotName"
+        },
+        "in": {
+          "description": "The slot a macro edge of this kind arrives at, on the TARGET instance.",
+          "$ref": "#/$defs/slotName"
+        }
+      }
+    },
+    "wire": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "kind", "to"],
+      "properties": {
+        "from": {
+          "$ref": "#/$defs/endpoint"
+        },
+        "kind": {
+          "$ref": "#/$defs/qualifiedKind"
+        },
+        "to": {
+          "$ref": "#/$defs/endpoint"
+        }
+      }
+    },
+    "endpoint": {
+      "description": "A slot name declared in `parts`, or `self` for the instance itself.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "slotName": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "qualifiedKind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*(?:/[a-z][a-z0-9-]*)+@[0-9]+\\.[0-9]+#[a-z][A-Za-z0-9-]*$"
+    }
+  }
+}

package/schema/yarramate-question-catalogue.schema.json

@@ -63,6 +63,14 @@
           },
           "description": {
             "$ref": "#/$defs/nonEmptyText"
+          },
+          "opensWhen": {
+            "description": "Conditions that must all hold before this wave opens (#334, ADR 0125). A wave that has not opened asks nothing: its questions are premature rather than answered, and the report says so with `opened: false` and no questions rather than reporting them closed. Written in the same condition vocabulary a question's trigger uses, so a reviewer reads a gate the way they already read a trigger. Absent means the wave is always open, which is what every wave did before this existed.",
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "$ref": "#/$defs/condition"
+            }
           }
         }
       }
@@ -503,6 +511,19 @@
             }
           }
         },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The workspace holds at least one concept (#334, ADR 0125). The guard a late wave needs to say \"only once the model has substance\": an empty model is not an architecture at rest, it has not started, and asking it how the planned architecture becomes real greets someone ahead of question one.",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "has-any-subject"
+            }
+          }
+        },
         {
           "type": "object",
           "additionalProperties": false,

package/schema/yarramate-visual-graph.schema.json

@@ -31,6 +31,7 @@
         "kind",
         "kindLabel",
         "coreKindLabel",
+        "portKinds",
         "layer",
         "aspect",
         "name",
@@ -64,6 +65,14 @@
         "kindLabel": {
           "type": "string"
         },
+        "portKinds": {
+          "description": "The core relationship kinds this node's pattern ports, or [] where its kind has no pattern with ports (#268 phase 3, ADR 0124). A macro edge needs both ends to port its kind, so an editor offering a palette between two instances intersects the two lists.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        },
         "coreKindLabel": {
           "type": "string"
         },

package/schema/yarramate-workspace.schema.json

@@ -28,6 +28,10 @@
     "projections": {
       "$ref": "#/$defs/patterns"
     },
+    "patterns": {
+      "description": "yarramate/pattern/v1 documents: the shape a concept kind promises, and the wiring the compiler mints between an instance and the parts it binds (ADR 0123). Structure, where profiles declare vocabulary. Optional, like evidence and contracts.",
+      "$ref": "#/$defs/patterns"
+    },
     "adapterMappings": {
       "$ref": "#/$defs/patterns"
     },