yarramate 1.0.0 → 1.1.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,42 @@ 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.
+
 ### 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.1.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-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"
         },

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

@@ -4,7 +4,7 @@
   "title": "YarraMate interrogation report",
   "type": "object",
   "additionalProperties": false,
-  "required": ["format", "workspace", "catalogue", "summary", "waves"],
+  "required": ["format", "workspace", "catalogue", "semantics", "summary", "waves"],
   "properties": {
     "format": {
       "const": "yarramate/interrogation-report/v1"
@@ -17,6 +17,11 @@
       "type": "string",
       "minLength": 1
     },
+    "semantics": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The version of condition evaluation that produced this report, as distinct from the package version. It changes only when an existing question's answer can change for an unchanged model, so a consumer holding stored answers can tell an engine change from a model change. Absent on reports produced before yarramate 1.1.0."
+    },
     "summary": {
       "type": "object",
       "additionalProperties": false,

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

@@ -104,9 +104,7 @@
       "description": "Which subjects a subject-scope question applies to. Field vocabulary mirrors the projection query selector (ADR 0017).",
       "type": "object",
       "additionalProperties": false,
-      "required": [
-        "kinds"
-      ],
+      
       "properties": {
         "kinds": {
           "type": "array",
@@ -491,6 +489,19 @@
               "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"
+            }
+          }
         }
       ]
     },

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

@@ -30,7 +30,12 @@
         "unknown": { "type": "integer", "minimum": 0 },
         "notObserved": { "type": "integer", "minimum": 0 },
         "subjectsWithoutEvidence": { "type": "integer", "minimum": 0 },
-        "staleAttestations": { "type": "integer", "minimum": 0 },
+        "unsupportedAbsences": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "not-observed observations that name no search. A not-observed asserts a negative about a tree nobody read exhaustively, and is the one result whose message nothing can check; this counts the ones offering a reader nothing to re-run."
+      },
+      "staleAttestations": { "type": "integer", "minimum": 0 },
         "unconfirmedAttestations": { "type": "integer", "minimum": 0 },
         "expectationsCompared": { "type": "integer", "minimum": 0 },
         "expectationsWithoutObservation": { "type": "integer", "minimum": 0 }