yarramate 0.4.0 → 0.6.0

package/dist/next-command.js

@@ -0,0 +1,272 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseDocument } from 'yaml';
+import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
+import { compileWorkspaceWithProfileContext, } from './compiler.js';
+import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
+import { evaluateProjection, loadProjection } from './projection.js';
+import { loadWorkspaceManifest } from './workspace.js';
+// Which endpoint of a declared relationship must exist before the other,
+// read off each core kind's declared intent (ADR 0048). Kinds without a
+// build-order reading (association, assignment, influence) contribute no
+// ordering edge rather than a guessed one.
+const corePrerequisiteEndpoints = new Map([
+    ['realization', 'source'],
+    ['serving', 'source'],
+    ['triggering', 'source'],
+    ['flow', 'source'],
+    ['composition', 'target'],
+    ['aggregation', 'target'],
+    ['access', 'target'],
+    ['specialization', 'target'],
+]);
+const prerequisiteEndpoint = (kind, profileContext) => {
+    const candidates = [
+        kind,
+        ...(profileContext?.relationshipKindLineages.get(kind) ?? []),
+    ];
+    for (const candidate of candidates) {
+        const separator = candidate.indexOf('#');
+        if (separator === -1 || !candidate.startsWith('yarramate/core@')) {
+            continue;
+        }
+        const orientation = corePrerequisiteEndpoints.get(candidate.slice(separator + 1));
+        if (orientation !== undefined)
+            return orientation;
+    }
+    return undefined;
+};
+const claimValue = (claims, subject, predicate) => {
+    const object = claims.find((claim) => claim.subject === subject && claim.predicate === predicate)?.object;
+    return object !== undefined && 'value' in object ? object.value : undefined;
+};
+const plural = (count, singular) => `${count} ${count === 1 ? singular : `${singular}s`}`;
+const coverageClause = (coverage) => {
+    if (coverage.observations === 0)
+        return 'no evidence';
+    const parts = [
+        ...(coverage.confirmed > 0 ? [`${coverage.confirmed} confirmed`] : []),
+        ...(coverage.contradicted > 0
+            ? [`${coverage.contradicted} contradicted`]
+            : []),
+        ...(coverage.unknown > 0 ? [`${coverage.unknown} unknown`] : []),
+        ...(coverage.notObserved > 0
+            ? [`${coverage.notObserved} not observed`]
+            : []),
+    ];
+    return `${plural(coverage.observations, 'observation')} (${parts.join(', ')})`;
+};
+export function runNextCommand(options, cwd) {
+    const json = options.includes('--json');
+    const rest = options.filter((option) => option !== '--json');
+    const [projectionPath, workspacePath] = rest;
+    if (rest.length !== 2 ||
+        projectionPath === undefined ||
+        workspacePath === undefined ||
+        rest.some((option) => option.startsWith('-'))) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
+        if (parseDocument(manifestSource).get('format') !== 'yarramate/workspace/v1') {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: 'next requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
+        }
+        const failed = (diagnostics) => ({
+            exitCode: 1,
+            stdout: json ? diagnosticJson(diagnostics) : humanDiagnostics(diagnostics),
+            stderr: '',
+        });
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok)
+            return failed(loadedWorkspace.diagnostics);
+        const workspace = loadedWorkspace.workspace;
+        const loadedProjection = loadProjection({
+            path: projectionPath,
+            source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
+        });
+        if (!loadedProjection.ok)
+            return failed(loadedProjection.diagnostics);
+        const compilation = compileWorkspaceWithProfileContext([...workspace.profiles, ...workspace.documents].map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        })));
+        if (!compilation.ok)
+            return failed(compilation.diagnostics);
+        const graph = compilation.graph;
+        const evidenceDocuments = [];
+        for (const path of workspace.evidence) {
+            const loaded = loadEvidence({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            });
+            if (!loaded.ok)
+                return failed(loaded.diagnostics);
+            evidenceDocuments.push(loaded.evidence);
+        }
+        const evaluation = evaluateEvidenceWorkspace(graph, evidenceDocuments);
+        if (!evaluation.ok)
+            return failed(evaluation.diagnostics);
+        const result = evaluateProjection(graph, loadedProjection.projection, compilation.profileContext);
+        const planned = result.subjects
+            .filter(({ id, type }) => type === 'concept' &&
+            claimValue(result.claims, id, 'yarramate/lifecycle/status') ===
+                'planned')
+            .map(({ id }) => id);
+        const plannedIds = new Set(planned);
+        const dependsOn = new Map();
+        const requiredBy = new Map();
+        for (const subject of result.subjects) {
+            if (subject.type !== 'relationship')
+                continue;
+            const claim = result.claims.find(({ id, object }) => id === subject.id && 'ref' in object);
+            if (claim === undefined || !('ref' in claim.object))
+                continue;
+            const orientation = prerequisiteEndpoint(claim.predicate, compilation.profileContext);
+            if (orientation === undefined)
+                continue;
+            const prerequisite = orientation === 'source' ? claim.subject : claim.object.ref;
+            const dependent = orientation === 'source' ? claim.object.ref : claim.subject;
+            if (prerequisite === dependent ||
+                !plannedIds.has(prerequisite) ||
+                !plannedIds.has(dependent)) {
+                continue;
+            }
+            dependsOn.set(dependent, (dependsOn.get(dependent) ?? new Set()).add(prerequisite));
+            requiredBy.set(prerequisite, (requiredBy.get(prerequisite) ?? new Set()).add(dependent));
+        }
+        // Deterministic Kahn ordering: everything whose prerequisites are
+        // already emitted goes next, lexicographic within a round; a cycle
+        // cannot be ordered, so its members are appended sorted and marked.
+        const ordered = [];
+        const cycles = new Set();
+        const emitted = new Set();
+        const remaining = new Set([...planned].sort());
+        while (remaining.size > 0) {
+            const ready = [...remaining]
+                .filter((id) => [...(dependsOn.get(id) ?? [])].every((dependency) => emitted.has(dependency)))
+                .sort();
+            if (ready.length === 0) {
+                for (const id of [...remaining].sort()) {
+                    ordered.push(id);
+                    cycles.add(id);
+                }
+                break;
+            }
+            for (const id of ready) {
+                ordered.push(id);
+                emitted.add(id);
+                remaining.delete(id);
+            }
+        }
+        const relationshipIds = new Set(graph.subjects
+            .filter(({ type }) => type === 'relationship')
+            .map(({ id }) => id));
+        const relationshipEndpoints = new Map();
+        const claimOwners = new Map();
+        for (const claim of graph.claims) {
+            claimOwners.set(claim.id, claim.subject);
+            if (relationshipIds.has(claim.id) && 'ref' in claim.object) {
+                relationshipEndpoints.set(claim.id, [claim.subject, claim.object.ref]);
+            }
+        }
+        const coverageTargets = (observation) => {
+            const target = 'subject' in observation ? observation.subject : observation.claim;
+            const endpoints = relationshipEndpoints.get(target);
+            if (endpoints !== undefined)
+                return endpoints;
+            if ('claim' in observation) {
+                const owner = claimOwners.get(target);
+                if (owner === undefined)
+                    return [];
+                return relationshipEndpoints.get(owner) ?? [owner];
+            }
+            return [target];
+        };
+        const coverage = new Map();
+        for (const id of planned) {
+            coverage.set(id, {
+                observations: 0,
+                confirmed: 0,
+                contradicted: 0,
+                unknown: 0,
+                notObserved: 0,
+            });
+        }
+        for (const report of evaluation.reports) {
+            for (const observation of report.observations) {
+                for (const target of coverageTargets(observation)) {
+                    const tally = coverage.get(target);
+                    if (tally === undefined)
+                        continue;
+                    tally.observations += 1;
+                    if (observation.result === 'not-observed') {
+                        tally.notObserved += 1;
+                    }
+                    else {
+                        tally[observation.result] += 1;
+                    }
+                }
+            }
+        }
+        const subjects = ordered.map((id) => {
+            const name = claimValue(result.claims, id, 'yarramate/concept/name');
+            return {
+                id,
+                kind: claimValue(result.claims, id, 'yarramate/concept/kind') ?? 'unknown',
+                ...(name === undefined ? {} : { name }),
+                dependsOn: [...(dependsOn.get(id) ?? [])].sort(),
+                requiredBy: [...(requiredBy.get(id) ?? [])].sort(),
+                evidence: coverage.get(id),
+                ...(cycles.has(id) ? { cycle: true } : {}),
+            };
+        });
+        const projectionLabel = `${loadedProjection.projection.id}@${loadedProjection.projection.version}`;
+        if (json) {
+            const payload = {
+                format: 'yarramate/next-result/v1',
+                workspace: workspace.id,
+                projection: projectionLabel,
+                subjects,
+            };
+            return {
+                exitCode: 0,
+                stdout: `${JSON.stringify(payload, null, 2)}\n`,
+                stderr: '',
+            };
+        }
+        if (subjects.length === 0) {
+            return {
+                exitCode: 0,
+                stdout: `No planned subjects in projection ${projectionLabel}.\n`,
+                stderr: '',
+            };
+        }
+        const width = Math.max(...subjects.map(({ id }) => id.length));
+        const lines = [
+            `Planned subjects in projection ${projectionLabel} (dependency order):`,
+            ...subjects.map((subject) => {
+                const clauses = [
+                    ...(subject.requiredBy.length > 0
+                        ? [`<- required by ${subject.requiredBy.join(', ')}`]
+                        : []),
+                    coverageClause(subject.evidence),
+                    ...(subject.cycle === true ? ['dependency cycle'] : []),
+                ];
+                return `  ${subject.id.padEnd(width)}  ${clauses.join('; ')}`;
+            }),
+        ];
+        return {
+            exitCode: 0,
+            stdout: `${lines.join('\n')}\n`,
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/dist/profile.d.ts

@@ -21,6 +21,11 @@ export interface RelationshipPolicy {
     readonly intent: string;
     readonly sourceAspects?: readonly Aspect[];
     readonly targetAspects?: readonly Aspect[];
+    /**
+     * Repair hint appended to endpoint-aspect diagnostics (YM404). A remedy,
+     * never a correction: the compiler still rejects the input.
+     */
+    readonly repair?: string;
 }
 /**
  * Safe, intentionally broad semantic constraints. A future licensed

package/dist/profile.js

@@ -137,6 +137,7 @@ export const relationshipPolicies = [
         id: 'assignment',
         intent: 'Allocate an active structure to behavior or responsibility',
         sourceAspects: ['active-structure'],
+        repair: 'assign from an active-structure element (an actor, component, or node), or use "association"',
     },
     { id: 'realization', intent: 'Fulfil a more abstract concept' },
     { id: 'serving', intent: 'Make behavior or an interface available' },
@@ -144,11 +145,13 @@ export const relationshipPolicies = [
         id: 'access',
         intent: 'Read, write, create, or use passive structure',
         targetAspects: ['passive-structure'],
+        repair: 'point "access" at passive structure (a business object, data object, or artifact), or use "association"',
     },
     {
         id: 'influence',
         intent: 'Affect a motivation concept',
         targetAspects: ['motivation'],
+        repair: 'point "influence" at a motivation concept (a goal, requirement, or principle), or use "association"',
     },
     { id: 'association', intent: 'Relevant connection with no stronger meaning' },
     {
@@ -156,6 +159,7 @@ export const relationshipPolicies = [
         intent: 'Express temporal or causal precedence',
         sourceAspects: ['behavior'],
         targetAspects: ['behavior'],
+        repair: 'use "flow" between active-structure elements, or introduce a behavior concept and "assignment"',
     },
     { id: 'flow', intent: 'Transfer information, value, goods, or material' },
     { id: 'specialization', intent: 'Express a more specific form' },

package/dist/reconciliation.d.ts

@@ -1,9 +1,17 @@
+import type { SemanticGraph } from './compiler.js';
 import type { EvidenceLocator, EvidenceReport, EvidenceResult } from './evidence.js';
+export interface AssertedRelationship {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: string;
+    readonly name?: string;
+}
 export interface ReconciliationFinding {
     readonly target: {
         readonly type: 'subject' | 'claim';
         readonly id: string;
     };
+    readonly asserted?: AssertedRelationship;
     readonly result: Exclude<EvidenceResult, 'confirmed'>;
     readonly provider: string;
     readonly evidenceDocument: string;
@@ -20,7 +28,9 @@ export interface ReconciliationReport {
         readonly contradicted: number;
         readonly unknown: number;
         readonly notObserved: number;
+        readonly subjectsWithoutEvidence: number;
     };
     readonly findings: readonly ReconciliationFinding[];
+    readonly unobservedSubjects?: readonly string[];
 }
-export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[]): ReconciliationReport;
+export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[], graph?: SemanticGraph): ReconciliationReport;

package/dist/reconciliation.js

@@ -1,4 +1,68 @@
-export function reconcileEvidenceReports(workspace, reports) {
+const assertedRelationshipsByClaim = (graph) => {
+    const asserted = new Map();
+    if (graph === undefined)
+        return asserted;
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const names = new Map();
+    for (const claim of graph.claims) {
+        if (claim.predicate === 'yarramate/relationship/name' &&
+            'value' in claim.object) {
+            names.set(claim.subject, claim.object.value);
+        }
+    }
+    for (const claim of graph.claims) {
+        if (!relationshipIds.has(claim.id) || !('ref' in claim.object))
+            continue;
+        const name = names.get(claim.id);
+        asserted.set(claim.id, {
+            from: claim.subject,
+            to: claim.object.ref,
+            kind: claim.predicate,
+            ...(name === undefined ? {} : { name }),
+        });
+    }
+    return asserted;
+};
+const unobservedCurrentConcepts = (graph, reports) => {
+    if (graph === undefined)
+        return [];
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const claimsById = new Map(graph.claims.map((claim) => [claim.id, claim]));
+    const observed = new Set();
+    for (const report of reports) {
+        for (const observation of report.observations) {
+            if ('subject' in observation) {
+                observed.add(observation.subject);
+                continue;
+            }
+            const claim = claimsById.get(observation.claim);
+            if (claim === undefined)
+                continue;
+            observed.add(claim.subject);
+            if (relationshipIds.has(claim.id) && 'ref' in claim.object) {
+                observed.add(claim.object.ref);
+            }
+        }
+    }
+    const conceptIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'concept')
+        .map(({ id }) => id));
+    return graph.claims
+        .filter((claim) => claim.predicate === 'yarramate/lifecycle/status' &&
+        'value' in claim.object &&
+        claim.object.value === 'current' &&
+        conceptIds.has(claim.subject) &&
+        !observed.has(claim.subject))
+        .map(({ subject }) => subject)
+        .sort((left, right) => left.localeCompare(right));
+};
+export function reconcileEvidenceReports(workspace, reports, graph) {
+    const assertedByClaim = assertedRelationshipsByClaim(graph);
+    const unobservedSubjects = unobservedCurrentConcepts(graph, reports);
     const summary = {
         evidenceDocuments: reports.length,
         observations: 0,
@@ -7,6 +71,7 @@ export function reconcileEvidenceReports(workspace, reports) {
         contradicted: 0,
         unknown: 0,
         notObserved: 0,
+        subjectsWithoutEvidence: unobservedSubjects.length,
     };
     const findings = [];
     for (const report of reports) {
@@ -22,10 +87,13 @@ export function reconcileEvidenceReports(workspace, reports) {
             else {
                 summary[observation.result] += 1;
             }
+            const target = 'subject' in observation
+                ? { type: 'subject', id: observation.subject }
+                : { type: 'claim', id: observation.claim };
+            const asserted = target.type === 'claim' ? assertedByClaim.get(target.id) : undefined;
             findings.push({
-                target: 'subject' in observation
-                    ? { type: 'subject', id: observation.subject }
-                    : { type: 'claim', id: observation.claim },
+                target,
+                ...(asserted === undefined ? {} : { asserted }),
                 result: observation.result,
                 provider: report.provider,
                 evidenceDocument: report.evidence,
@@ -43,5 +111,6 @@ export function reconcileEvidenceReports(workspace, reports) {
         workspace,
         summary,
         findings,
+        ...(unobservedSubjects.length === 0 ? {} : { unobservedSubjects }),
     };
 }

package/dist/status-command.js

@@ -91,7 +91,7 @@ export function runStatusCommand(options, cwd) {
                     });
                     const evaluation = evaluateEvidenceWorkspace(compilation.graph, evidenceDocuments);
                     if (evaluation.ok) {
-                        reconciliation = reconcileEvidenceReports(workspace.id, evaluation.reports).summary;
+                        reconciliation = reconcileEvidenceReports(workspace.id, evaluation.reports, compilation.graph).summary;
                     }
                 }
             }
@@ -145,6 +145,9 @@ export function runStatusCommand(options, cwd) {
                     ? ` (${result.reconciliation.contradicted} contradicted, ` +
                         `${result.reconciliation.unknown} unknown, ` +
                         `${result.reconciliation.notObserved} not observed)`
+                    : '') +
+                (result.reconciliation.subjectsWithoutEvidence > 0
+                    ? `, ${plural(result.reconciliation.subjectsWithoutEvidence, 'current subject')} without evidence`
                     : ''));
         }
         lines.push(`Documents: ${documents.map(({ id }) => id).join(', ') || 'none'}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -59,6 +59,7 @@
     "./schema/likec4-check-result": "./schema/yarramate-likec4-check-result.schema.json",
     "./schema/state-comparison": "./schema/yarramate-state-comparison.schema.json",
     "./schema/status-result": "./schema/yarramate-status-result.schema.json",
+    "./schema/next-result": "./schema/yarramate-next-result.schema.json",
     "./schema/graph-v2": "./schema/yarramate-graph-v2.schema.json",
     "./schema/workspace": "./schema/yarramate-workspace.schema.json",
     "./schema/evidence": "./schema/yarramate-evidence.schema.json",
@@ -92,11 +93,11 @@
     "self:contract": "pnpm build && node dist/cli.js context .yarramate/projections/core-contract-foundation.yaml .yarramate/workspace.yaml",
     "self:evidence": "pnpm build && node dist/cli.js evidence .yarramate/evidence/repository.yaml .yarramate/workspace.yaml",
     "self:reconcile": "pnpm build && node dist/cli.js reconcile .yarramate/workspace.yaml",
-    "self:check:likec4": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/integrations/likec4/project.yaml .yarramate/workspace.yaml",
-    "self:check:likec4:json": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml",
-    "self:export:likec4": "pnpm build && node dist/adapters/likec4-cli.js export-project .yarramate/integrations/likec4/project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml",
+    "self:check:likec4": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/likec4-project.yaml .yarramate/workspace.yaml",
+    "self:check:likec4:json": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml",
+    "self:export:likec4": "pnpm build && node dist/adapters/likec4-cli.js export-project .yarramate/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml",
     "validate": "pnpm self:export:likec4 && likec4 validate --no-layout .yarramate-out/likec4",
-    "verify": "pnpm typecheck && pnpm test && pnpm self:check && pnpm validate",
+    "verify": "pnpm typecheck && pnpm build && pnpm test && pnpm self:check && pnpm validate",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },

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

@@ -20,6 +20,9 @@
     },
     "counted": {
       "$ref": "#/$defs/counted"
+    },
+    "strict": {
+      "$ref": "#/$defs/strict"
     }
   },
   "allOf": [
@@ -50,6 +53,15 @@
     }
   ],
   "$defs": {
+    "strict": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["observations", "contradicted"],
+      "properties": {
+        "observations": { "type": "integer", "minimum": 0 },
+        "contradicted": { "type": "integer", "minimum": 0 }
+      }
+    },
     "counted": {
       "type": "object",
       "additionalProperties": false,

package/schema/yarramate-core-contract.schema.json

@@ -70,6 +70,7 @@
               "add",
               "connect",
               "new",
+              "next",
               "check",
               "status",
               "compile",

package/schema/yarramate-likec4-generated-project-v2.schema.json

@@ -45,6 +45,12 @@
         }
       }
     },
+    "inputDigests": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/sha256"
+      }
+    },
     "files": {
       "const": [
         "likec4.config.json",

package/schema/yarramate-likec4-generated-project.schema.json

@@ -51,6 +51,12 @@
         }
       }
     },
+    "inputDigests": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/sha256"
+      }
+    },
     "files": {
       "const": [
         "likec4.config.json",

package/schema/yarramate-likec4-project.schema.json

@@ -41,7 +41,7 @@
     },
     "path": {
       "type": "string",
-      "description": "Repository-relative path resolved from the CLI working directory. Parent traversal, absolute paths, and backslashes are rejected.",
+      "description": "Path resolved from the project-definition document's directory, matching workspace-manifest semantics. Parent traversal, absolute paths, and backslashes are rejected, so references stay beneath the project document.",
       "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
     },
     "subjectIdentity": {

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

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/next-result/v1",
+  "title": "YarraMate next result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "workspace", "projection", "subjects"],
+  "properties": {
+    "format": {
+      "const": "yarramate/next-result/v1"
+    },
+    "workspace": {
+      "type": "string",
+      "minLength": 1
+    },
+    "projection": {
+      "type": "string",
+      "minLength": 1
+    },
+    "subjects": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/subject"
+      }
+    }
+  },
+  "$defs": {
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "dependsOn", "requiredBy", "evidence"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "dependsOn": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "requiredBy": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "evidence": {
+          "$ref": "#/$defs/coverage"
+        },
+        "cycle": {
+          "const": true
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "observations",
+        "confirmed",
+        "contradicted",
+        "unknown",
+        "notObserved"
+      ],
+      "properties": {
+        "observations": { "type": "integer", "minimum": 0 },
+        "confirmed": { "type": "integer", "minimum": 0 },
+        "contradicted": { "type": "integer", "minimum": 0 },
+        "unknown": { "type": "integer", "minimum": 0 },
+        "notObserved": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}