yarramate 0.5.0 → 0.6.0

package/README.md

@@ -119,13 +119,15 @@ node dist/cli.js check .yarramate/workspace.yaml --json
 node dist/cli.js compile .yarramate/workspace.yaml
 node dist/cli.js context .yarramate/projections/context.yaml .yarramate/workspace.yaml
 node dist/cli.js view .yarramate/projections/context.yaml .yarramate/workspace.yaml
+node dist/cli.js next .yarramate/projections/context.yaml .yarramate/workspace.yaml
 node dist/cli.js evidence .yarramate/evidence/repository.yaml .yarramate/workspace.yaml
 node dist/cli.js reconcile .yarramate/workspace.yaml
 ```
 
 `init` creates `.yarramate/architecture/main.yaml` and
 `.yarramate/workspace.yaml`. Commands accept explicit source documents or one
-explicit workspace manifest.
+explicit workspace manifest. `check --strict` additionally fails when any
+evidence observation contradicts the model, for gates that want one knob.
 
 For a local consumer test, create a package artifact:
 

package/dist/adapters/likec4-cli.js

@@ -77,8 +77,8 @@ const usage = 'Usage:\n' +
     '  yarramate-likec4 check <projection.yaml> <mapping.yaml> [--json] [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
     '  yarramate-likec4 check <likec4-project.yaml> [--json] <workspace-or-source...>\n' +
     '  yarramate-likec4 export <projection.yaml> <mapping.yaml> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
-    '  yarramate-likec4 export-project <projection.yaml> <mapping.yaml> <output-dir> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
-    '  yarramate-likec4 export-project <likec4-project.yaml> <output-dir> <workspace-or-source...>\n';
+    '  yarramate-likec4 export-project [--check] <projection.yaml> <mapping.yaml> <output-dir> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
+    '  yarramate-likec4 export-project [--check] <likec4-project.yaml> <output-dir> <workspace-or-source...>\n';
 const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/likec4-diagnostic-result/v1',
     diagnostics,
@@ -89,10 +89,13 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
     diagnostics,
 }, null, 2)}\n`;
 const unmappedSubjectPreviewLength = 3;
-const summarizeUnmappedConcepts = (diagnostics) => {
-    const unmapped = diagnostics.filter((diagnostic) => diagnostic.code === 'YMLC102');
+const summarizeUnmappedSubjects = (diagnostics) => [
+    ['YMLC102', 'concepts'],
+    ['YMLC111', 'relationships'],
+].reduce((current, [code, noun]) => {
+    const unmapped = current.filter((diagnostic) => diagnostic.code === code);
     if (unmapped.length <= unmappedSubjectPreviewLength)
-        return diagnostics;
+        return current;
     const preview = unmapped
         .slice(0, unmappedSubjectPreviewLength)
         .map((diagnostic) => 'subject' in diagnostic && diagnostic.subject !== undefined
@@ -101,21 +104,20 @@ const summarizeUnmappedConcepts = (diagnostics) => {
         .join(', ');
     const summary = {
         ...unmapped[0],
-        message: `${unmapped.length} projected concepts have no LikeC4 mapping ` +
+        message: `${unmapped.length} projected ${noun} have no LikeC4 mapping ` +
             `(first: ${preview}); run "yarramate-likec4 map --sync" to add ` +
             'the missing mappings',
     };
     let summarized = false;
-    return diagnostics.flatMap((diagnostic) => {
-        if (diagnostic.code !== 'YMLC102')
+    return current.flatMap((diagnostic) => {
+        if (diagnostic.code !== code)
             return [diagnostic];
         if (summarized)
             return [];
         summarized = true;
         return [summary];
     });
-};
-const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+}, diagnostics);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
     const sync = args[0];
@@ -290,6 +292,33 @@ const runLikeC4MapSync = (args, cwd) => {
         return { exitCode: 2, stdout: '', stderr: `${message}\n` };
     }
 };
+// Ownership fields never gate updates: a marker of either format version
+// plus intact output digests proves the directory is entirely
+// machine-generated, so regenerating after the inputs changed loses nothing.
+const readGeneratedProjectMarker = (markerPath) => {
+    let marker;
+    try {
+        marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return validateGeneratedProjectMarker(marker) ||
+        validateGeneratedProjectV2Marker(marker)
+        ? marker
+        : undefined;
+};
+const changedGeneratedFile = (projectPath, marker) => {
+    // Markers written before output digests existed are accepted once and
+    // upgraded on regeneration.
+    if (marker['digests'] === undefined)
+        return undefined;
+    const digests = marker['digests'];
+    return generatedFileNames.find((file) => {
+        const path = resolve(projectPath, file);
+        return (!existsSync(path) || sha256(readFileSync(path)) !== digests[file]);
+    });
+};
 const publishGeneratedProject = (cwd, outputDirectory, input) => {
     const projectPath = resolve(cwd, outputDirectory);
     const markerPath = resolve(projectPath, 'yarramate.generated.json');
@@ -319,37 +348,21 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
                 stderr: `Generated project contains an unsafe file: ${unsafeFile}\n`,
             };
         }
-        let marker;
-        try {
-            marker = JSON.parse(readFileSync(markerPath, 'utf8'));
-        }
-        catch {
-            marker = undefined;
-        }
-        if (!input.validateMarker(marker) ||
-            typeof marker !== 'object' ||
-            marker === null ||
-            Object.entries(input.ownership).some(([key, value]) => !sameJson(marker[key], value))) {
+        const marker = readGeneratedProjectMarker(markerPath);
+        if (marker === undefined) {
             return {
                 exitCode: 2,
                 stdout: '',
-                stderr: `Output directory already exists: ${projectPath}\n`,
+                stderr: `Output directory exists but is not a YarraMate-generated project: ${projectPath}\n`,
             };
         }
-        if ('digests' in marker && marker.digests !== undefined) {
-            const digests = marker.digests;
-            const changedFile = generatedFileNames.find((file) => {
-                const path = resolve(projectPath, file);
-                return (!existsSync(path) ||
-                    sha256(readFileSync(path)) !== digests[file]);
-            });
-            if (changedFile !== undefined) {
-                return {
-                    exitCode: 2,
-                    stdout: '',
-                    stderr: `Generated project file has changed: ${resolve(projectPath, changedFile)}\n`,
-                };
-            }
+        const changedFile = changedGeneratedFile(projectPath, marker);
+        if (changedFile !== undefined) {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: `Generated project file has changed: ${resolve(projectPath, changedFile)}\n`,
+            };
         }
     }
     else {
@@ -373,6 +386,7 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
             'model.likec4': sha256(input.modelSource),
             'specification.likec4': sha256(specificationSource),
         },
+        inputDigests: input.inputDigests,
     }, null, 2)}\n`;
     publishFiles([
         {
@@ -397,6 +411,85 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
         stderr: '',
     };
 };
+// Freshness is a pure digest comparison between the marker and the would-be
+// export; nothing on disk is written or semantically judged.
+const checkGeneratedProject = (cwd, outputDirectory, input) => {
+    const projectPath = resolve(cwd, outputDirectory);
+    if (!existsSync(projectPath)) {
+        return {
+            exitCode: 1,
+            stdout: 'Generated LikeC4 output: absent\n',
+            stderr: '',
+        };
+    }
+    const marker = readGeneratedProjectMarker(resolve(projectPath, 'yarramate.generated.json'));
+    if (marker === undefined) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: `Output directory exists but is not a YarraMate-generated project: ${projectPath}\n`,
+        };
+    }
+    const changedFile = changedGeneratedFile(projectPath, marker);
+    if (changedFile !== undefined) {
+        return {
+            exitCode: 1,
+            stdout: 'Generated LikeC4 output: modified\n' +
+                'Reason:\n' +
+                `- generated file changed: ${resolve(projectPath, changedFile)}\n` +
+                'Safe to regenerate: no\n',
+            stderr: '',
+        };
+    }
+    const recordedInputs = marker['inputDigests'];
+    const reasons = [];
+    if (recordedInputs === undefined) {
+        reasons.push('marker predates input digests');
+    }
+    else {
+        const inputPaths = [
+            ...new Set([
+                ...Object.keys(recordedInputs),
+                ...Object.keys(input.inputDigests),
+            ]),
+        ].sort();
+        for (const path of inputPaths) {
+            const recorded = recordedInputs[path];
+            const current = input.inputDigests[path];
+            if (recorded === undefined)
+                reasons.push(`input added: ${path}`);
+            else if (current === undefined) {
+                reasons.push(`input removed: ${path}`);
+            }
+            else if (recorded !== current) {
+                reasons.push(`input changed: ${path}`);
+            }
+        }
+    }
+    const digests = marker['digests'];
+    if (digests !== undefined &&
+        sha256(input.modelSource) !== digests['model.likec4']) {
+        reasons.push('model source changed');
+    }
+    if (reasons.length === 0) {
+        return {
+            exitCode: 0,
+            stdout: 'Generated LikeC4 output: fresh\n',
+            stderr: '',
+        };
+    }
+    return {
+        exitCode: 1,
+        stdout: 'Generated LikeC4 output: stale\n' +
+            'Reason:\n' +
+            reasons.map((reason) => `- ${reason}\n`).join('') +
+            'Safe to regenerate: yes\n',
+        stderr: '',
+    };
+};
+const inputDigestsOf = (inputs) => Object.fromEntries(inputs
+    .map(({ path, source }) => [path, sha256(source)])
+    .sort(([left], [right]) => left.localeCompare(right)));
 export function runLikeC4Cli(args, cwd = process.cwd()) {
     if (args[0] === '--version') {
         return versionResult('yarramate-likec4');
@@ -404,7 +497,10 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
     if (args[0] === 'map') {
         return runLikeC4MapSync(args.slice(1), cwd);
     }
-    const [command, projectionPath, mappingPath, ...options] = args;
+    const checkFreshness = args[0] === 'export-project' && args.includes('--check');
+    const [command, projectionPath, mappingPath, ...options] = checkFreshness
+        ? args.filter((argument) => argument !== '--check')
+        : args;
     let projectDefinitionMode = false;
     if ((command === 'check' || command === 'export-project') &&
         projectionPath !== undefined) {
@@ -493,7 +589,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
     const diagnosticOutput = (diagnostics) => json
         ? checkJson(false, diagnostics)
         : diagnosticJson(command === 'check'
-            ? summarizeUnmappedConcepts(diagnostics)
+            ? summarizeUnmappedSubjects(diagnostics)
             : diagnostics);
     try {
         const resolved = resolveCliWorkspaceSources(sourcePaths, cwd);
@@ -584,6 +680,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                         ? {}
                         : { comparison: view.compare }),
                     vocabulary: 'bundled',
+                    requireMappedRelationships: command === 'check',
                 }),
             }));
             const failed = preparedViews.find(({ prepared }) => !prepared.ok);
@@ -813,6 +910,17 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 ? undefined
                 : `${first.prepared.kindMapping.id}@${first.prepared.kindMapping.version}`;
             const projectIdentity = `${loadedProject.document.value.id}@${loadedProject.document.value.version}`;
+            const inputDigests = inputDigestsOf([
+                projectSource,
+                ...sources,
+                ...referencedSources.values(),
+            ]);
+            if (checkFreshness) {
+                return checkGeneratedProject(cwd, outputDirectory, {
+                    modelSource: exported.source,
+                    inputDigests,
+                });
+            }
             return publishGeneratedProject(cwd, outputDirectory, {
                 projectName: `yarramate-${projectIdentity}`.replaceAll(/[^A-Za-z0-9_-]/g, '-'),
                 title: loadedProject.document.value.title,
@@ -832,29 +940,33 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                             : { comparison }),
                     })),
                 },
-                validateMarker: (value) => validateGeneratedProjectV2Marker(value),
+                inputDigests,
             });
         }
+        const projectionSource = {
+            path: projectionPath,
+            source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
+        };
+        const mappingSource = {
+            path: mappingPath,
+            source: readFileSync(resolve(cwd, mappingPath), 'utf8'),
+        };
+        const kindMappingSource = kindMappingPath === undefined
+            ? undefined
+            : {
+                path: kindMappingPath,
+                source: readFileSync(resolve(cwd, kindMappingPath), 'utf8'),
+            };
         const prepared = prepareLikeC4Export({
             sources,
-            projection: {
-                path: projectionPath,
-                source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
-            },
-            subjectMapping: {
-                path: mappingPath,
-                source: readFileSync(resolve(cwd, mappingPath), 'utf8'),
-            },
-            ...(kindMappingPath === undefined
+            projection: projectionSource,
+            subjectMapping: mappingSource,
+            ...(kindMappingSource === undefined
                 ? {}
-                : {
-                    kindMapping: {
-                        path: kindMappingPath,
-                        source: readFileSync(resolve(cwd, kindMappingPath), 'utf8'),
-                    },
-                }),
+                : { kindMapping: kindMappingSource }),
             ...(comparison === undefined ? {} : { comparison }),
             vocabulary: command === 'export' ? 'consumer' : 'bundled',
+            requireMappedRelationships: command === 'check',
         });
         if (!prepared.ok) {
             return {
@@ -881,6 +993,18 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
             ? undefined
             : `${prepared.kindMapping.id}@${prepared.kindMapping.version}`;
         const comparisonIdentity = comparison;
+        const inputDigests = inputDigestsOf([
+            projectionSource,
+            mappingSource,
+            ...(kindMappingSource === undefined ? [] : [kindMappingSource]),
+            ...sources,
+        ]);
+        if (checkFreshness) {
+            return checkGeneratedProject(cwd, outputDirectory, {
+                modelSource: prepared.source,
+                inputDigests,
+            });
+        }
         return publishGeneratedProject(cwd, outputDirectory, {
             projectName: ['yarramate', projectionIdentity]
                 .join('-')
@@ -899,7 +1023,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                     ? {}
                     : { comparison: comparisonIdentity }),
             },
-            validateMarker: (value) => validateGeneratedProjectMarker(value),
+            inputDigests,
         });
     }
     catch (error) {

package/dist/adapters/likec4-export.d.ts

@@ -4,7 +4,7 @@ import type { ProjectionResult } from '../projection.js';
 import type { LikeC4KindMapping } from './likec4-kind-mapping.js';
 export interface LikeC4ExportDiagnostic {
     readonly severity: 'error';
-    readonly code: 'YMLC101' | 'YMLC102' | 'YMLC103' | 'YMLC104' | 'YMLC105' | 'YMLC106' | 'YMLC107' | 'YMLC108' | 'YMLC109';
+    readonly code: 'YMLC101' | 'YMLC102' | 'YMLC103' | 'YMLC104' | 'YMLC105' | 'YMLC106' | 'YMLC107' | 'YMLC108' | 'YMLC109' | 'YMLC111';
     readonly message: string;
     readonly subject?: string;
     readonly path: string;

package/dist/adapters/likec4-prepare.d.ts

@@ -13,6 +13,12 @@ export interface LikeC4PreparationInput {
         readonly to: string;
     };
     readonly vocabulary: 'bundled' | 'consumer';
+    /**
+     * Gate mode. Rendering a relationship needs no external identity — views
+     * select it by metadata — but `map --sync` still writes one, so only a
+     * check answering "would sync change anything" requires the entry.
+     */
+    readonly requireMappedRelationships?: boolean;
 }
 export type LikeC4PreparationDiagnostic = Diagnostic | LikeC4ExportDiagnostic;
 export type LikeC4PreparationResult = {

package/dist/adapters/likec4-prepare.js

@@ -70,6 +70,31 @@ const unsupportedBundledKinds = (projection, kindMapping) => {
     }
     return diagnostics.sort(diagnosticOrder);
 };
+const unmappedProjectedRelationships = (projection, mapping) => {
+    const mapped = new Set(mapping.mappings
+        .filter(({ type }) => type === 'relationship')
+        .map(({ native }) => native));
+    return projection.subjects
+        .filter(({ type, id }) => type === 'relationship' && !mapped.has(id))
+        .flatMap(({ id }) => {
+        const source = projection.claims.find((claim) => claim.id === id)?.source;
+        return source === undefined
+            ? []
+            : [
+                {
+                    severity: 'error',
+                    code: 'YMLC111',
+                    message: `Projected relationship "${id}" has no LikeC4 mapping`,
+                    subject: id,
+                    path: source.path,
+                    pointer: source.pointer,
+                    line: source.line,
+                    column: source.column,
+                },
+            ];
+    })
+        .sort(diagnosticOrder);
+};
 export function prepareLikeC4Export(input) {
     const compilation = compileWorkspaceWithProfileContext(input.sources);
     if (!compilation.ok)
@@ -137,11 +162,24 @@ export function prepareLikeC4Export(input) {
         if (diagnostics.length > 0)
             return { ok: false, diagnostics };
     }
+    const unmappedRelationships = input.requireMappedRelationships === true
+        ? unmappedProjectedRelationships(projectionResult, subjectMapping.mapping)
+        : [];
     const exported = exportLikeC4(projectionResult, subjectMapping.mapping, kindMapping?.mapping, comparison === undefined
         ? undefined
         : { comparison: comparison.comparison });
-    if (!exported.ok)
-        return exported;
+    if (!exported.ok) {
+        return {
+            ok: false,
+            diagnostics: [
+                ...exported.diagnostics,
+                ...unmappedRelationships,
+            ].sort(diagnosticOrder),
+        };
+    }
+    if (unmappedRelationships.length > 0) {
+        return { ok: false, diagnostics: unmappedRelationships };
+    }
     return {
         ok: true,
         source: exported.source,

package/dist/check-command.js

@@ -8,10 +8,23 @@ import { compileWorkspace } from './compiler.js';
 import { checkCoreContract, loadCoreContract, } from './core-contract.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { loadProjection } from './projection.js';
+import { reconcileEvidenceReports, } from './reconciliation.js';
 const Ajv2020 = Ajv2020Module.default;
+const strictFindingMessage = (finding) => {
+    const observed = finding.evidence.message === undefined
+        ? finding.evidence.uri
+        : `${finding.evidence.uri}: ${finding.evidence.message}`;
+    const assertion = finding.asserted === undefined
+        ? `Evidence contradicts ${finding.target.type} "${finding.target.id}"`
+        : `Evidence contradicts claim "${finding.target.id}": the model asserts ` +
+            `${finding.asserted.from} -> ${finding.asserted.to} (${finding.asserted.kind})`;
+    return (`${assertion}, but provider "${finding.provider}" observed otherwise ` +
+        `(${observed}); align the model or the evidence to pass --strict`);
+};
 export function runCheckCommand(options, cwd) {
     const json = options.includes('--json');
-    const paths = options.filter((option) => option !== '--json');
+    const strict = options.includes('--strict');
+    const paths = options.filter((option) => option !== '--json' && option !== '--strict');
     const unknownOption = paths.find((path) => path.startsWith('-'));
     if (unknownOption !== undefined || paths.length === 0) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -171,6 +184,46 @@ export function runCheckCommand(options, cwd) {
         const diagnostics = result.ok
             ? optionalDiagnostics
             : result.diagnostics;
+        // Strict only tightens a passing check: base diagnostics already fail
+        // the gate, so contradictions are folded in only once everything else
+        // holds, and each one is anchored at the claim the model declares.
+        const strictEvaluation = strict && result.ok && ok
+            ? (() => {
+                const reports = evidenceEvaluation !== undefined && evidenceEvaluation.ok
+                    ? evidenceEvaluation.reports
+                    : [];
+                const graph = result.graph;
+                const contradicted = reconcileEvidenceReports('strict', reports, graph).findings.filter(({ result: outcome }) => outcome === 'contradicted');
+                return {
+                    observations: reports.reduce((total, report) => total + report.observations.length, 0),
+                    diagnostics: sortDiagnostics(contradicted.map((finding) => {
+                        const anchor = graph.claims.find(({ id }) => id === finding.target.id) ??
+                            graph.claims.find(({ subject, predicate }) => subject === finding.target.id &&
+                                predicate === 'yarramate/concept/kind') ??
+                            graph.claims.find(({ subject }) => subject === finding.target.id);
+                        return {
+                            severity: 'error',
+                            code: 'YM901',
+                            message: strictFindingMessage(finding),
+                            path: anchor?.source.path ?? finding.evidenceDocument,
+                            pointer: anchor?.source.pointer ?? '/',
+                            line: anchor?.source.line ?? 1,
+                            column: anchor?.source.column ?? 1,
+                        };
+                    })),
+                };
+            })()
+            : undefined;
+        const strictSummary = strictEvaluation === undefined
+            ? undefined
+            : {
+                observations: strictEvaluation.observations,
+                contradicted: strictEvaluation.diagnostics.length,
+            };
+        const strictOk = strictEvaluation === undefined
+            ? true
+            : strictEvaluation.diagnostics.length === 0;
+        const finalOk = ok && strictOk;
         const counted = result.ok
             ? (() => {
                 const states = new Set(result.graph.claims
@@ -186,8 +239,15 @@ export function runCheckCommand(options, cwd) {
             : undefined;
         if (json) {
             return {
-                exitCode: ok ? 0 : 1,
-                stdout: checkResultJson(ok, ok ? [] : diagnostics, ok ? counted : undefined),
+                exitCode: finalOk ? 0 : 1,
+                stdout: checkResultJson(finalOk, finalOk ? [] : ok ? strictEvaluation.diagnostics : diagnostics, finalOk ? counted : undefined, strictSummary),
+                stderr: '',
+            };
+        }
+        if (ok && !strictOk) {
+            return {
+                exitCode: 1,
+                stdout: humanDiagnostics(strictEvaluation.diagnostics),
                 stderr: '',
             };
         }
@@ -227,13 +287,19 @@ export function runCheckCommand(options, cwd) {
                     ]
                     : []),
             ].join(' and ');
+            const strictLine = strictSummary === undefined
+                ? ''
+                : strictSummary.observations === 0
+                    ? 'Strict: no evidence observations to evaluate\n'
+                    : `Strict: ${strictSummary.observations} ${strictSummary.observations === 1 ? 'observation' : 'observations'}, 0 contradicted\n`;
             return {
                 exitCode: 0,
                 stdout: `Checked ${checked} (` +
                     `${successfulCounts.concepts} ${successfulCounts.concepts === 1 ? 'concept' : 'concepts'}, ` +
                     `${successfulCounts.relationships} ${successfulCounts.relationships === 1 ? 'relationship' : 'relationships'}, ` +
                     `${successfulCounts.states} ${successfulCounts.states === 1 ? 'state' : 'states'}` +
-                    '): no errors\n',
+                    '): no errors\n' +
+                    strictLine,
                 stderr: '',
             };
         }

package/dist/cli-support.d.ts

@@ -7,13 +7,16 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const packageVersion: string;
 export declare const versionResult: (binary: string) => CliResult;
-export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate next <projection.yaml> <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;
     readonly concepts: number;
     readonly relationships: number;
     readonly states: number;
+}, strict?: {
+    readonly observations: number;
+    readonly contradicted: number;
 }) => string;
 export declare const humanDiagnostics: (diagnostics: readonly Pick<Diagnostic, "path" | "line" | "column" | "code" | "message">[]) => string;
 export declare const sortDiagnostics: <T extends Diagnostic>(diagnostics: readonly T[]) => T[];

package/dist/cli-support.js

@@ -23,16 +23,17 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate next <projection.yaml> <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,
 }, null, 2)}\n`;
-export const checkResultJson = (ok, diagnostics, counted) => `${JSON.stringify({
+export const checkResultJson = (ok, diagnostics, counted, strict) => `${JSON.stringify({
     format: 'yarramate/check-result/v1',
     ok,
     diagnostics,
     ...(counted === undefined ? {} : { counted }),
+    ...(strict === undefined ? {} : { strict }),
 }, null, 2)}\n`;
 export const humanDiagnostics = (diagnostics) => diagnostics
     .map((diagnostic) => `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} error ${diagnostic.code} ${diagnostic.message}\n`)

package/dist/cli.js

@@ -8,6 +8,7 @@ import { serializeSemanticGraph } from './graph.js';
 import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, versionResult, } from './cli-support.js';
 import { runCheckCommand } from './check-command.js';
 import { runNewCommand } from './new-command.js';
+import { runNextCommand } from './next-command.js';
 import { runStatusCommand } from './status-command.js';
 import { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
@@ -757,6 +758,9 @@ export function runCli(args, cwd = process.cwd()) {
     if (command === 'new') {
         return runNewCommand(options, cwd);
     }
+    if (command === 'next') {
+        return runNextCommand(options, cwd);
+    }
     return { exitCode: 2, stdout: '', stderr: usage };
 }
 if (isMainModule(import.meta.url, process.argv[1])) {

package/dist/compiler.js

@@ -14,6 +14,23 @@ const validateDocument = new Ajv2020({ allErrors: true }).compile(documentSchema
 const validateProfile = new Ajv2020({ allErrors: true }).compile(profileSchema);
 const compareById = (left, right) => left.id.localeCompare(right.id);
 const presenceClaimId = (subject, state) => `${subject}~present-in-${Buffer.from(state, 'utf8').toString('hex')}`;
+const describeAspect = (aspect) => aspect.replace('-', ' ');
+// Candidate order is the policy-matrix declaration order: the resolved kind
+// map inserts core policies first, then extension kinds as declared.
+const candidateKindHint = (kinds, rejected, sourceAspect, targetAspect) => {
+    const candidates = [...kinds]
+        .filter(([id, kind]) => id !== rejected &&
+        (kind.sourceAspects?.includes(sourceAspect) ?? true) &&
+        (kind.targetAspects?.includes(targetAspect) ?? true))
+        .map(([id]) => id);
+    if (candidates.length === 0) {
+        return '';
+    }
+    const observed = sourceAspect === targetAspect
+        ? `both endpoints are ${describeAspect(sourceAspect)}`
+        : `source is ${describeAspect(sourceAspect)} and target is ${describeAspect(targetAspect)}`;
+    return `; ${observed}; valid candidates: ${candidates.join(', ')}`;
+};
 const diagnosticFailure = (diagnostics) => ({
     ok: false,
     diagnostics: [...diagnostics].sort((left, right) => left.path.localeCompare(right.path) ||
@@ -779,27 +796,35 @@ function compileWorkspaceResolved(sources) {
             }
             const policy = selectedProfile.relationshipKinds.get(relationship.kind);
             if (policy !== undefined) {
-                for (const endpoint of ['source', 'target']) {
-                    const reference = endpoint === 'source' ? relationship.from : relationship.to;
+                const aspectOf = (reference) => {
                     const resolvedConcept = conceptByQualifiedId.get(qualifyReference(value.id, reference));
-                    const kind = resolvedConcept === undefined
+                    return resolvedConcept === undefined
                         ? undefined
                         : profiles
                             .get(resolvedConcept.profile)
-                            ?.conceptKinds.get(resolvedConcept.concept.kind);
+                            ?.conceptKinds.get(resolvedConcept.concept.kind)?.aspect;
+                };
+                const sourceAspect = aspectOf(relationship.from);
+                const targetAspect = aspectOf(relationship.to);
+                const candidates = sourceAspect === undefined || targetAspect === undefined
+                    ? ''
+                    : candidateKindHint(selectedProfile.relationshipKinds, relationship.kind, sourceAspect, targetAspect);
+                for (const endpoint of ['source', 'target']) {
+                    const reference = endpoint === 'source' ? relationship.from : relationship.to;
+                    const aspect = endpoint === 'source' ? sourceAspect : targetAspect;
                     const allowed = endpoint === 'source'
                         ? policy.sourceAspects
                         : policy.targetAspects;
-                    if (kind !== undefined &&
+                    if (aspect !== undefined &&
                         allowed !== undefined &&
-                        !allowed.includes(kind.aspect)) {
+                        !allowed.includes(aspect)) {
                         const field = endpoint === 'source' ? 'from' : 'to';
                         const pointer = `/relationships/${index}/${field}`;
                         const source = location(['relationships', index, field], pointer);
                         diagnostics.push({
                             severity: 'error',
                             code: 'YM404',
-                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((aspect) => `"${aspect}"`).join(' or ')}; "${reference}" has aspect "${kind.aspect}"${policy.repair === undefined ? '' : `; ${policy.repair}`}`,
+                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((entry) => `"${entry}"`).join(' or ')}; "${reference}" has aspect "${aspect}"${policy.repair === undefined ? '' : `; ${policy.repair}`}${candidates}`,
                             path: input.path,
                             pointer,
                             line: source.line,

package/dist/next-command.d.ts

@@ -0,0 +1,25 @@
+import { type CliResult } from './cli-support.js';
+interface EvidenceCoverage {
+    readonly observations: number;
+    readonly confirmed: number;
+    readonly contradicted: number;
+    readonly unknown: number;
+    readonly notObserved: number;
+}
+export interface NextSubject {
+    readonly id: string;
+    readonly kind: string;
+    readonly name?: string;
+    readonly dependsOn: readonly string[];
+    readonly requiredBy: readonly string[];
+    readonly evidence: EvidenceCoverage;
+    readonly cycle?: true;
+}
+export interface NextResult {
+    readonly format: 'yarramate/next-result/v1';
+    readonly workspace: string;
+    readonly projection: string;
+    readonly subjects: readonly NextSubject[];
+}
+export declare function runNextCommand(options: readonly string[], cwd: string): CliResult;
+export {};

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/reconciliation.d.ts

@@ -28,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[], graph?: SemanticGraph): ReconciliationReport;

package/dist/reconciliation.js

@@ -25,8 +25,44 @@ const assertedRelationshipsByClaim = (graph) => {
     }
     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,
@@ -35,6 +71,7 @@ export function reconcileEvidenceReports(workspace, reports, graph) {
         contradicted: 0,
         unknown: 0,
         notObserved: 0,
+        subjectsWithoutEvidence: unobservedSubjects.length,
     };
     const findings = [];
     for (const report of reports) {
@@ -74,5 +111,6 @@ export function reconcileEvidenceReports(workspace, reports, graph) {
         workspace,
         summary,
         findings,
+        ...(unobservedSubjects.length === 0 ? {} : { unobservedSubjects }),
     };
 }

package/dist/status-command.js

@@ -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.5.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",

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-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 }
+      }
+    }
+  }
+}

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

@@ -18,7 +18,8 @@
         "findings",
         "contradicted",
         "unknown",
-        "notObserved"
+        "notObserved",
+        "subjectsWithoutEvidence"
       ],
       "properties": {
         "evidenceDocuments": { "type": "integer", "minimum": 0 },
@@ -27,12 +28,17 @@
         "findings": { "type": "integer", "minimum": 0 },
         "contradicted": { "type": "integer", "minimum": 0 },
         "unknown": { "type": "integer", "minimum": 0 },
-        "notObserved": { "type": "integer", "minimum": 0 }
+        "notObserved": { "type": "integer", "minimum": 0 },
+        "subjectsWithoutEvidence": { "type": "integer", "minimum": 0 }
       }
     },
     "findings": {
       "type": "array",
       "items": { "$ref": "#/$defs/finding" }
+    },
+    "unobservedSubjects": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/subjectIdentity" }
     }
   },
   "$defs": {

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

@@ -79,7 +79,8 @@
         "findings",
         "contradicted",
         "unknown",
-        "notObserved"
+        "notObserved",
+        "subjectsWithoutEvidence"
       ],
       "properties": {
         "evidenceDocuments": {
@@ -109,6 +110,10 @@
         "notObserved": {
           "type": "integer",
           "minimum": 0
+        },
+        "subjectsWithoutEvidence": {
+          "type": "integer",
+          "minimum": 0
         }
       }
     },