yarramate 1.0.0 → 1.2.0

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

@@ -135,6 +135,23 @@ export type IncrementalCompilationResult = ({
     readonly incremental: boolean;
     readonly cache: CompilationCache;
 };
+/**
+ * A succession entry: a bare predecessor id, or one with the respect in which
+ * it was superseded.
+ *
+ * The scope is load-bearing rather than decorative. A model claimed that Zoekt
+ * superseded the Elasticsearch indexer, unqualified, while the source it was
+ * built from says Zoekt "handles only code search and does not replace
+ * Elasticsearch". The prose carried the qualifier and the field could not, and
+ * `ask --compare` reads the field, so the declared target architecture became
+ * the deletion of a component that is not being deleted (ADR 0109).
+ */
+export type NativeSuccession = string | {
+    readonly subject: string;
+    readonly inRespectOf: string;
+};
+export declare const successionSubject: (entry: NativeSuccession) => string;
+export declare const successionScope: (entry: NativeSuccession) => string | undefined;
 export { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue, parseAttestationClaimValue, parseConstraintExpectsValue, type AttestationClaimParts, type ConstraintExpectsParts, } from './graph-claims.js';
 interface ResolvedPosition {
     readonly line: number;

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

@@ -8,15 +8,39 @@ export interface EvidenceObservedValue {
     readonly key: string;
     readonly value: string;
 }
+/**
+ * One search a provider ran and found nothing at, recorded so a reader can
+ * re-run it. yarramate never executes it: the engine has no access to the
+ * subject tree, and gaining one would be a different decision (ADR 0107).
+ */
+export type SearchProbe = {
+    readonly glob: string;
+} | {
+    readonly grep: string;
+    readonly paths?: readonly string[];
+};
+/**
+ * A figure quoted in an evidence message, with how it was produced, so a
+ * reader can tell a measured number from a remembered one and re-derive it at
+ * a later commit.
+ */
+export interface Measurement {
+    readonly value: string;
+    readonly method: string;
+}
+interface ObservationProvenance {
+    readonly searched?: readonly SearchProbe[];
+    readonly measured?: readonly Measurement[];
+}
 export type EvidenceObservation = ({
     readonly subject: string;
     readonly result: EvidenceResult;
     readonly evidence: EvidenceLocator;
-} & Partial<EvidenceObservedValue>) | ({
+} & ObservationProvenance & Partial<EvidenceObservedValue>) | ({
     readonly claim: string;
     readonly result: EvidenceResult;
     readonly evidence: EvidenceLocator;
-} & Partial<EvidenceObservedValue>);
+} & ObservationProvenance & Partial<EvidenceObservedValue>);
 export interface EvidenceDocument {
     readonly format: 'yarramate/evidence/v1';
     readonly id: string;
@@ -60,3 +84,4 @@ export type EvidenceWorkspaceEvaluationResult = {
 export declare function loadEvidence(source: WorkspaceSource): EvidenceLoadResult;
 export declare function evaluateEvidence(graph: SemanticGraph, evidence: EvidenceDocument): EvidenceEvaluationResult;
 export declare function evaluateEvidenceWorkspace(graph: SemanticGraph, evidenceDocuments: readonly EvidenceDocument[]): EvidenceWorkspaceEvaluationResult;
+export {};

package/docs/CONSUMING-YARRAMATE.md

@@ -232,6 +232,53 @@ the notation module is the rendering vocabulary for that mode; the element
 vocabulary and relationship table themselves are implemented in the core
 profile (ADR 0097).
 
+## Evaluating question catalogues off Node
+
+The interrogation engine is public API. A consumer that compiles a workspace
+itself can load a catalogue and evaluate it without the CLI:
+
+```ts
+import {
+  evaluateCatalogue,
+  loadQuestionCatalogue,
+  INTERROGATION_SEMANTICS_VERSION,
+} from 'yarramate/interrogation'
+```
+
+**Import the subpath, not the package entry, wherever the runtime is not
+Node.** The `.` barrel reaches `node:fs`, `node:path` and `node:child_process`
+through workspace loading, the filesystem source store and git-derived
+attestation staleness, so taking the engine from there drags Node in behind it.
+`yarramate/interrogation` carries the engine alone and is pinned free of Node
+built-ins by the same test that guards `yarramate/adapter/visual-graph`. The
+same names are also exported from `.` for Node consumers.
+
+`evaluateCatalogue` returns the report without its `workspace`, which the
+caller supplies:
+
+```ts
+const report = { workspace: id, ...evaluateCatalogue(catalogue, graph, profileContext) }
+```
+
+The report carries `semantics`, the version of condition evaluation, which
+changes only when an existing question's answer can change for an unchanged
+model ([ADR 0106](adr/0106-a-report-says-which-engine-answered.md)). A consumer
+that **persists** answers should store it beside them: equal means a flipped
+answer is about the model and belongs in front of a user, different means the
+engine moved and the right response is to re-baseline silently rather than
+reopen someone's queue.
+
+Every question also carries `trigger`, the catalogue conditions that opened
+it, verbatim ([ADR 0110](adr/0110-an-open-question-carries-its-answer-shape.md)).
+That is the question's machine-readable answer shape: a host building an
+answering affordance — a concept form with the kind preselected from
+`no-subject-of-kind`, a relationship editor with one endpoint fixed by
+`missing-relationship`'s `direction`, an attestation form on
+`missing-attestation`'s `topic` — maps the conditions directly instead of
+re-deriving the shape from its own catalogue copy. The field is required and
+the published report schema uses `additionalProperties: false`, so upgrade a
+separately pinned schema together with the package.
+
 ### Mount the visual editor
 
 Mount the packaged editor when the consuming product owns the sources and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,10 @@
       "types": "./dist/notation/archimate.d.ts",
       "import": "./dist/notation/archimate.js"
     },
+    "./interrogation": {
+      "types": "./dist/interrogation-entry.d.ts",
+      "import": "./dist/interrogation-entry.js"
+    },
     "./visual-app": {
       "types": "./dist/visual-app-lib/editor.d.ts",
       "import": "./dist/visual-app-lib/editor.js"

package/schema/yarramate-ask-result.schema.json

@@ -522,6 +522,7 @@
             "format",
             "workspace",
             "catalogue",
+            "semantics",
             "summary",
             "waves"
           ],
@@ -535,6 +536,9 @@
             "catalogue": {
               "type": "string"
             },
+            "semantics": {
+              "type": "string"
+            },
             "summary": {
               "type": "object"
             },
@@ -875,6 +879,10 @@
             },
             "notObserved": {
               "type": "integer"
+            },
+            "unsupportedAbsences": {
+              "type": "integer",
+              "minimum": 0
             }
           },
           "additionalProperties": false
@@ -950,6 +958,10 @@
         "notObserved": {
           "type": "integer"
         },
+        "unsupportedAbsences": {
+          "type": "integer",
+          "minimum": 0
+        },
         "subjectsWithoutEvidence": {
           "type": "integer"
         },

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

@@ -83,7 +83,8 @@
             "authority",
             "question",
             "materiality",
-            "resolution"
+            "resolution",
+            "trigger"
           ],
           "properties": {
             "questionId": {
@@ -123,6 +124,14 @@
               "type": "string",
               "minLength": 1
             },
+            "trigger": {
+              "description": "The catalogue trigger, verbatim: the conditions that opened this question, i.e. its machine-readable answer shape.",
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/condition"
+              }
+            },
             "subject": {
               "type": "object",
               "additionalProperties": false,
@@ -163,5 +172,377 @@
       "type": "string",
       "minLength": 1
     }
+  },
+  "$defs": {
+    "condition": {
+      "description": "One deterministic trigger condition. All conditions in a trigger must hold (AND) for the question to be open.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "predicate"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-claim"
+            },
+            "predicate": {
+              "$ref": "#/$defs/claimPredicate"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds",
+            "direction"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-relationship"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "direction": {
+              "enum": [
+                "incoming",
+                "outgoing",
+                "any"
+              ]
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "isolated"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "no-subject-of-kind"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ],
+              "default": "descendants"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "no-state-defined"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds",
+            "direction",
+            "counterpartKinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-linkage"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "direction": {
+              "enum": [
+                "outgoing",
+                "incoming"
+              ]
+            },
+            "counterpartKinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ],
+              "default": "descendants"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds",
+            "direction",
+            "counterpartKinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "has-linkage"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "direction": {
+              "enum": [
+                "outgoing",
+                "incoming",
+                "either"
+              ]
+            },
+            "counterpartKinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ],
+              "default": "descendants"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds",
+            "direction",
+            "counterpartKinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "exists-linkage"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "direction": {
+              "enum": [
+                "outgoing",
+                "incoming",
+                "either"
+              ]
+            },
+            "counterpartKinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ],
+              "default": "descendants"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-constraint"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ],
+              "default": "descendants"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The subject is an endpoint of at least one flow relationship that has no yarramate/flow/content claim.",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-flow-content"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "predicate",
+            "direction"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-reference"
+            },
+            "predicate": {
+              "$ref": "#/$defs/claimPredicate"
+            },
+            "direction": {
+              "enum": [
+                "outgoing",
+                "incoming"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "topic"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-attestation"
+            },
+            "topic": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The subject resembles another subject of the same kind closely enough to be the same thing under two names, and no yarramate/identity/distinct-from claim dismisses the pair. Deterministic and lexical; the algorithm and thresholds are stated in ADR 0077. Questions using it may interpolate {counterparts}.",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "near-duplicate"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The subject's kind is never tested by anything the compiler can check: it participates in no relationship whose kind pins the aspect at the subject's end, so reclassifying it to any other kind of any other aspect would still compile. The kind is a label rather than a constraint (ADR 0083).",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "unconstrained-kind"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The subject supersedes a predecessor that is still current, and does not say in what respect. A succession that replaced its predecessor outright says so by the predecessor being gone; one where both remain is usually partial, and the respect is the part a reader needs (ADR 0109).",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "unscoped-succession"
+            }
+          }
+        }
+      ]
+    },
+    "claimPredicate": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9/@.#-]*$"
+    },
+    "qualifiedKind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9/-]*@[0-9][0-9A-Za-z.-]*#[A-Za-z][A-Za-z0-9-]*$"
+    }
   }
 }

package/schema/yarramate-document.schema.json

@@ -127,6 +127,24 @@
         "supersedes": {
           "$ref": "#/$defs/successionReferences"
         },
+        "forbids": {
+          "description": "Relationship shapes this subject rules out, checked against the graph. A constraint nothing tests is a comment. Deliberately narrow: forbid a relationship kind between named endpoints, with exceptions, which covers \"everything goes through X\" and needs no traversal.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["relationship"],
+            "anyOf": [{ "required": ["from"] }, { "required": ["to"] }],
+            "properties": {
+              "relationship": { "type": "string", "minLength": 1 },
+              "from": { "type": "string", "minLength": 1 },
+              "to": { "type": "string", "minLength": 1 },
+              "exceptFrom": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+              "exceptTo": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+            }
+          }
+        },
         "constraints": {
           "type": "array",
           "items": {
@@ -237,7 +255,18 @@
       "minItems": 1,
       "uniqueItems": true,
       "items": {
-        "$ref": "#/$defs/reference"
+        "oneOf": [
+          { "$ref": "#/$defs/reference" },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["subject", "inRespectOf"],
+            "properties": {
+              "subject": { "$ref": "#/$defs/reference" },
+              "inRespectOf": { "$ref": "#/$defs/nonEmptyText" }
+            }
+          }
+        ]
       }
     },
     "relationship": {

package/schema/yarramate-evidence.schema.json

@@ -27,6 +27,44 @@
     }
   },
   "$defs": {
+    "searchProbe": {
+      "description": "One search a provider performed and found nothing at. Recorded so a reader can re-run it; yarramate does not execute it.",
+      "type": "object",
+      "additionalProperties": false,
+      "oneOf": [{ "required": ["glob"] }, { "required": ["grep"] }],
+      "properties": {
+        "glob": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A path glob that matched nothing, e.g. PRAEFECT_*"
+        },
+        "grep": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A pattern that matched nothing."
+        },
+        "paths": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Paths the search covered. Absent means the whole tree."
+        }
+      }
+    },
+    "measurement": {
+      "description": "A figure quoted in an evidence message, with how it was produced. Recorded so a reader can re-derive it rather than trust it; yarramate does not execute the method.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "method"],
+      "properties": {
+        "value": { "type": "string", "minLength": 1 },
+        "method": {
+          "type": "string",
+          "minLength": 1,
+          "description": "How the value was obtained, precisely enough to reproduce."
+        }
+      }
+    },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
@@ -77,6 +115,18 @@
             "not-observed"
           ]
         },
+        "searched": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/searchProbe" },
+          "description": "What was searched and found empty. Meaningful on a not-observed result, which is the one result that asserts a negative about a tree nobody read exhaustively."
+        },
+        "measured": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/measurement" },
+          "description": "Figures quoted in the message, with how each was produced."
+        },
         "key": {
           "$ref": "#/$defs/observationKey"
         },