yarramate 1.5.0 → 1.7.0

package/dist/import-command.d.ts

@@ -0,0 +1,16 @@
+import { type CliResult } from './cli-support.js';
+/**
+ * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor, so this is a three-way merge rather
+ * than an overwrite: the author's edits are measured against `~Baseline`, the
+ * repository's drift is measured against the same, and only a field both moved
+ * is refused. Everything the author changed that the repository left alone
+ * merges cleanly, which is what makes a week-long workbook cycle usable.
+ *
+ * Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+ * keeps its comments, key order and formatting, and the whole import passes
+ * the atomic compile gate. A workbook that would produce an uncompilable model
+ * is refused whole rather than half written.
+ */
+export declare function runImportCommand(options: readonly string[], cwd: string): Promise<CliResult>;

package/dist/import-command.js

@@ -0,0 +1,156 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runApplyCommand } from './apply-cli.js';
+import { humanDiagnostics, packageVersion, usage } from './cli-support.js';
+import { compileWorkspaceWithProfileContext } from './compiler.js';
+import { evaluateProjection } from './projection.js';
+import { loadWorkspaceManifest } from './workspace.js';
+import { buildWorkbookSheets } from './workbook.js';
+import { baselineSheets, mergeWorkbook } from './workbook-merge.js';
+import { operationsFrom, operationsDocument } from './workbook-operations.js';
+import { readWorkbook } from './workbook-read.js';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+/**
+ * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor, so this is a three-way merge rather
+ * than an overwrite: the author's edits are measured against `~Baseline`, the
+ * repository's drift is measured against the same, and only a field both moved
+ * is refused. Everything the author changed that the repository left alone
+ * merges cleanly, which is what makes a week-long workbook cycle usable.
+ *
+ * Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+ * keeps its comments, key order and formatting, and the whole import passes
+ * the atomic compile gate. A workbook that would produce an uncompilable model
+ * is refused whole rather than half written.
+ */
+export async function runImportCommand(options, cwd) {
+    const [kind, ...rest] = options;
+    if (kind !== 'xlsx')
+        return { exitCode: 2, stdout: '', stderr: usage };
+    const json = rest.includes('--json');
+    const positionals = rest.filter((option) => option !== '--json');
+    const [workbookPath, workspacePath] = positionals;
+    if (positionals.length !== 2 ||
+        workbookPath === undefined ||
+        workspacePath === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const manifestPath = resolve(cwd, workspacePath);
+    let manifestSource;
+    let workbookBytes;
+    try {
+        manifestSource = readFileSync(manifestPath, 'utf8');
+        workbookBytes = new Uint8Array(readFileSync(resolve(cwd, workbookPath)));
+    }
+    catch (cause) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${cause instanceof Error ? cause.message : String(cause)}\n`,
+        };
+    }
+    const loaded = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+    if (!loaded.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(loaded.diagnostics),
+        };
+    }
+    const workspace = loaded.workspace;
+    const sources = [
+        ...workspace.profiles,
+        ...workspace.patterns,
+        ...workspace.documents,
+    ].map((path) => ({ path, source: readFileSync(resolve(cwd, path), 'utf8') }));
+    const compilation = compileWorkspaceWithProfileContext(sources);
+    if (!compilation.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(compilation.diagnostics),
+        };
+    }
+    const read = await readWorkbook(workbookBytes);
+    if (!read.ok) {
+        return { exitCode: 1, stdout: '', stderr: `${read.reason}\n` };
+    }
+    const baselineRows = read.sheets.get('~Baseline');
+    if (baselineRows === undefined) {
+        // Without the ancestor there is no way to tell the author's edit from the
+        // repository's drift, and guessing would silently discard one of them.
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: 'This workbook carries no ~Baseline sheet, so it was not produced by ' +
+                '`yarramate export xlsx` and there is no ancestor to merge against.\n',
+        };
+    }
+    const projectionId = read.sheets.get('~Meta')?.find((row) => row[0] === 'Projection')?.[1];
+    const result = evaluateProjection(compilation.graph, {
+        format: 'yarramate/projection/v1',
+        id: projectionId ?? 'imported',
+        version: '1.0',
+        query: {},
+    }, compilation.profileContext);
+    const current = buildWorkbookSheets(result, {
+        workspace: workspace.id,
+        yarramateVersion: packageVersion,
+        sourceDigests: {},
+        conceptKinds: [],
+        relationshipKinds: [],
+        statuses: [],
+    });
+    const report = mergeWorkbook(read.sheets, baselineSheets(baselineRows), current);
+    const planned = operationsFrom(report, read.sheets);
+    if (report.conflicts.length > 0) {
+        const lines = report.conflicts.map(({ sheet, id, column, from, to, theirs }) => `  ${sheet} "${id}" ${column}: you wrote ${JSON.stringify(to)}, ` +
+            `the workspace now has ${JSON.stringify(theirs)}, both from ${JSON.stringify(from)}`);
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${report.conflicts.length} field${report.conflicts.length === 1 ? '' : 's'} changed in the workbook and in the workspace since the workbook was made. ` +
+                'Nothing was written.\n' +
+                `${lines.join('\n')}\n`,
+        };
+    }
+    const notes = [
+        ...planned.refusals.map((reason) => `  not imported: ${reason}`),
+        ...report.missing.map(({ sheet, id }) => `  not imported: ${sheet} "${id}" is absent from the workbook; ` +
+            'a missing row is never a deletion'),
+    ];
+    if (planned.operations.length === 0) {
+        const summary = `Nothing to import: the workbook matches the workspace.\n`;
+        return {
+            exitCode: 0,
+            stdout: json
+                ? `${JSON.stringify({ format: 'yarramate/import-result/v1', operations: 0, notes }, null, 2)}\n`
+                : summary + (notes.length > 0 ? `${notes.join('\n')}\n` : ''),
+            stderr: '',
+        };
+    }
+    // Handed to `apply` rather than written directly: one mutation path, one
+    // atomic gate, and the surgical YAML editing that keeps comments.
+    const scratch = mkdtempSync(join(tmpdir(), 'yarramate-import-'));
+    const operationsPath = join(scratch, 'operations.yaml');
+    writeFileSync(operationsPath, stringify(operationsDocument(planned.operations)), 'utf8');
+    const applied = runApplyCommand([operationsPath, workspacePath], cwd);
+    if (applied.exitCode !== 0)
+        return applied;
+    const summary = `Imported ${planned.operations.length} change${planned.operations.length === 1 ? '' : 's'} from ${workbookPath}\n`;
+    return {
+        exitCode: 0,
+        stdout: json
+            ? `${JSON.stringify({
+                format: 'yarramate/import-result/v1',
+                operations: planned.operations.length,
+                notes,
+            }, null, 2)}\n`
+            : summary + (notes.length > 0 ? `${notes.join('\n')}\n` : ''),
+        stderr: '',
+    };
+}

package/dist/index.d.ts

@@ -18,4 +18,4 @@ export { applyOperations, landOperations, posixDirectoryOf, type ApplyInput, typ
 export { connectableKinds, draftRelationship, proposeRelationshipId, stagedSubjectIds, } from './relationship-drafting.js';
 export { draftConcept, proposeConceptId } from './concept-drafting.js';
 export { deletionBlockers, describeDeletion, draftDeletion, type DeletionBlocker, } from './deletion-drafting.js';
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';

package/dist/index.js

@@ -16,4 +16,4 @@ export { applyOperations, landOperations, posixDirectoryOf, } from './apply-comm
 export { connectableKinds, draftRelationship, proposeRelationshipId, stagedSubjectIds, } from './relationship-drafting.js';
 export { draftConcept, proposeConceptId } from './concept-drafting.js';
 export { deletionBlockers, describeDeletion, draftDeletion, } from './deletion-drafting.js';
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/interrogate-command.d.ts

@@ -188,14 +188,29 @@ export interface InterrogationSummary {
 export interface InterrogationReport {
     readonly format: 'yarramate/interrogation-report/v1';
     readonly workspace: string;
+    /** The BASE catalogue, `id@version`. Unchanged in shape by composition. */
     readonly catalogue: string;
+    /**
+     * Every contributing catalogue as `id@version`, base first, when more than
+     * one contributed (#345, ADR 0129). Optional so that adding it breaks no
+     * constructor, and `catalogue` keeps its value shape so it breaks no reader.
+     */
+    readonly catalogues?: readonly string[];
     /** {@link INTERROGATION_SEMANTICS_VERSION} at the time of evaluation. */
     readonly semantics: string;
     readonly summary: InterrogationSummary;
     readonly waves: readonly ReportWave[];
 }
 export declare const renderQuestion: (template: string, subjectId: string, subjectName: string | undefined, counterparts?: readonly string[]) => string;
-export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext, evidence?: readonly CatalogueEvidenceObservation[]): Omit<InterrogationReport, 'workspace'>;
+export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext, evidence?: readonly CatalogueEvidenceObservation[], 
+/**
+ * Contributing catalogues, from {@link composeCatalogues}. Composition
+ * happens BEFORE evaluation and hands this function an ordinary catalogue,
+ * so the only thing evaluation learns about composition is what to name in
+ * the report. A fifth optional parameter rather than an options object,
+ * because this signature is published and a consumer already calls it.
+ */
+catalogues?: readonly string[]): Omit<InterrogationReport, 'workspace'>;
 export type CatalogueLoadResult = {
     readonly ok: true;
     readonly catalogue: QuestionCatalogue;
@@ -203,5 +218,71 @@ export type CatalogueLoadResult = {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
+/**
+ * A catalogue is qualified on the way OUT, never in what an author writes.
+ *
+ * The authored schema keeps ids local (`^[a-z][a-z0-9-]*$`) and that does not
+ * change; a consultant writes `regulator-signoff`, not
+ * `consulting#regulator-signoff`. The engine qualifies when it composes, which
+ * is the only moment two catalogues can be confused for each other.
+ *
+ * NO VERSION, and that is the decision rather than an omission (ADR 0129).
+ * `core-enrichment` went 1.0 to 1.3 in a single day renaming nothing; a
+ * versioned identity would have stranded every stored dismissal in every
+ * adopter's database three times that day, for changes that removed no
+ * question. Versioned identity is safe for things that are AUTHORED - a
+ * document keeps naming the version it was written against and an author
+ * updates it deliberately - and unsafe for things that are STORED, because a
+ * row in someone's database has no author to update it.
+ */
+export declare const qualifiedQuestionId: (catalogueId: string, questionId: string) => string;
+export interface ComposedCatalogue {
+    /**
+     * The composed catalogue, ready for `evaluateCatalogue`. Structurally a
+     * `QuestionCatalogue`, but its question ids are QUALIFIED, so it is a
+     * composition result rather than something an author could have written and
+     * must never be validated against the authored schema again.
+     */
+    readonly catalogue: QuestionCatalogue;
+    /** Every contributing catalogue as `id@version`, base first. */
+    readonly catalogues: readonly string[];
+}
+export type CatalogueCompositionResult = {
+    readonly ok: true;
+    readonly composed: ComposedCatalogue;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/**
+ * Compose a base catalogue with the ones a workspace carries (#345, ADR 0129).
+ *
+ * ADDITIVE. `--catalogue` and `MountOptions.catalogue` replace the base; this
+ * adds to it, which is what lets a consultant author a question at any point
+ * in an engagement with no product release.
+ *
+ * A WAVE IS DECLARED EXACTLY ONCE across the resolved set, and any catalogue
+ * may contribute questions to a wave it did not declare. That one rule settles
+ * three questions composition would otherwise raise. Wave identity: a project
+ * catalogue joins a declared wave rather than colliding with it. Ordering:
+ * only a declaration places a wave, so the base's order is untouched and new
+ * waves append. And the `opensWhen` precedence ADR 0125 made load-bearing does
+ * not arise at all, because there is only ever one declarer to ask.
+ *
+ * QUALIFICATION IS A PROPERTY OF COMPOSITION, NOT OF EVALUATION. A caller
+ * that hands `evaluateCatalogue` a catalogue directly still gets local ids,
+ * exactly as before this existed. Route through here even for ONE catalogue -
+ * which is what every CLI verb does - and ids are qualified from the start, so
+ * they do not change later when a workspace first carries a question of its
+ * own. That transition is the one thing an adopter keying stored judgments on
+ * a question id must not experience, and composing unconditionally is how it
+ * is avoided.
+ *
+ * ID COLLISIONS DISSOLVE rather than being resolved. Two catalogues may both
+ * carry `outcome-missing`; qualified, they are two different questions. There
+ * is no merge rule, no last-wins and no refusal, because there is nothing to
+ * merge.
+ */
+export declare function composeCatalogues(sources: readonly WorkspaceSource[], profileContext?: ResolvedProfileContext): CatalogueCompositionResult;
 export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource, profileContext?: ResolvedProfileContext): CatalogueLoadResult;
 export declare function renderInterrogationReport(report: InterrogationReport): string;

package/dist/interrogate-command.js

@@ -451,7 +451,15 @@ const describeCounterparts = (index, question, subjectId) => {
         return name === undefined ? id : `${name} (${id})`;
     });
 };
-export function evaluateCatalogue(catalogue, graph, profileContext, evidence) {
+export function evaluateCatalogue(catalogue, graph, profileContext, evidence, 
+/**
+ * Contributing catalogues, from {@link composeCatalogues}. Composition
+ * happens BEFORE evaluation and hands this function an ordinary catalogue,
+ * so the only thing evaluation learns about composition is what to name in
+ * the report. A fifth optional parameter rather than an options object,
+ * because this signature is published and a consumer already calls it.
+ */
+catalogues) {
     const index = indexGraph(graph);
     let open = 0;
     let openQuestions = 0;
@@ -512,6 +520,11 @@ export function evaluateCatalogue(catalogue, graph, profileContext, evidence) {
     return {
         format: 'yarramate/interrogation-report/v1',
         catalogue: `${catalogue.id}@${catalogue.version}`,
+        // Only when composition actually happened. A single-catalogue report is
+        // byte-identical to what it was before this existed.
+        ...(catalogues === undefined || catalogues.length < 2
+            ? {}
+            : { catalogues }),
         semantics: INTERROGATION_SEMANTICS_VERSION,
         summary: {
             // Questions in OPENED waves only (#334, ADR 0125). A closed wave's
@@ -615,43 +628,196 @@ const unresolvableKinds = (catalogue, profileContext) => {
         return hash > 0 && loadedProfiles.has(kind.slice(0, hash));
     });
 };
-// Shared by interrogate and design: schema validation plus the YM911
-// undeclared-wave check, both source-located against the catalogue file.
-export function loadQuestionCatalogue(catalogueSource, profileContext) {
-    const loadedCatalogue = loadSourceDocument(catalogueSource, validateCatalogue, 'Question catalogue');
-    if (!loadedCatalogue.ok) {
-        return { ok: false, diagnostics: loadedCatalogue.diagnostics };
+const loadCatalogueDocument = (catalogueSource) => {
+    const loaded = loadSourceDocument(catalogueSource, validateCatalogue, 'Question catalogue');
+    if (!loaded.ok)
+        return { ok: false, diagnostics: loaded.diagnostics };
+    return {
+        ok: true,
+        document: {
+            source: catalogueSource,
+            catalogue: loaded.document.value,
+            locate: (path) => locateSourcePath(catalogueSource.path, loaded.document.yaml, loaded.document.lineCounter, path, `/${path.join('/')}`),
+        },
+    };
+};
+/**
+ * The YM911 undeclared-wave check, against a set of wave ids that may be
+ * WIDER than the catalogue's own.
+ *
+ * That width is the whole of #345. A project catalogue's reason to exist is
+ * adding "one more Assurance question for this client" to a wave the domain
+ * catalogue declared, so checking each file against only its own waves would
+ * refuse precisely the case the feature enables. Composed, the set is the
+ * union; alone, it is the catalogue's own and the check is what it always was.
+ */
+const undeclaredWaveDiagnostics = ({ catalogue, locate }, declaredWaves) => catalogue.questions.flatMap((question, questionIndex) => declaredWaves.has(question.wave)
+    ? []
+    : [
+        {
+            severity: 'error',
+            code: 'YM911',
+            message: `Question "${question.id}" references undeclared wave "${question.wave}"`,
+            ...locate(['questions', questionIndex, 'wave']),
+        },
+    ]);
+const unresolvableKindDiagnostics = ({ catalogue, locate }, profileContext) => 
+// Only when a caller has a compiled workspace to check against. Without one
+// there is no way to tell a typo from a kind whose profile simply is not
+// here, and guessing would be the false positive this check exists to avoid.
+profileContext === undefined
+    ? []
+    : unresolvableKinds(catalogue, profileContext).map((reference) => ({
+        severity: 'error',
+        code: 'YM914',
+        message: `Kind "${reference.kind}" is not declared by profile "${reference.kind.slice(0, reference.kind.indexOf('#'))}", which this workspace loads, so the question can never fire`,
+        ...locate(reference.path),
+    }));
+/**
+ * A catalogue is qualified on the way OUT, never in what an author writes.
+ *
+ * The authored schema keeps ids local (`^[a-z][a-z0-9-]*$`) and that does not
+ * change; a consultant writes `regulator-signoff`, not
+ * `consulting#regulator-signoff`. The engine qualifies when it composes, which
+ * is the only moment two catalogues can be confused for each other.
+ *
+ * NO VERSION, and that is the decision rather than an omission (ADR 0129).
+ * `core-enrichment` went 1.0 to 1.3 in a single day renaming nothing; a
+ * versioned identity would have stranded every stored dismissal in every
+ * adopter's database three times that day, for changes that removed no
+ * question. Versioned identity is safe for things that are AUTHORED - a
+ * document keeps naming the version it was written against and an author
+ * updates it deliberately - and unsafe for things that are STORED, because a
+ * row in someone's database has no author to update it.
+ */
+export const qualifiedQuestionId = (catalogueId, questionId) => `${catalogueId}#${questionId}`;
+/**
+ * Compose a base catalogue with the ones a workspace carries (#345, ADR 0129).
+ *
+ * ADDITIVE. `--catalogue` and `MountOptions.catalogue` replace the base; this
+ * adds to it, which is what lets a consultant author a question at any point
+ * in an engagement with no product release.
+ *
+ * A WAVE IS DECLARED EXACTLY ONCE across the resolved set, and any catalogue
+ * may contribute questions to a wave it did not declare. That one rule settles
+ * three questions composition would otherwise raise. Wave identity: a project
+ * catalogue joins a declared wave rather than colliding with it. Ordering:
+ * only a declaration places a wave, so the base's order is untouched and new
+ * waves append. And the `opensWhen` precedence ADR 0125 made load-bearing does
+ * not arise at all, because there is only ever one declarer to ask.
+ *
+ * QUALIFICATION IS A PROPERTY OF COMPOSITION, NOT OF EVALUATION. A caller
+ * that hands `evaluateCatalogue` a catalogue directly still gets local ids,
+ * exactly as before this existed. Route through here even for ONE catalogue -
+ * which is what every CLI verb does - and ids are qualified from the start, so
+ * they do not change later when a workspace first carries a question of its
+ * own. That transition is the one thing an adopter keying stored judgments on
+ * a question id must not experience, and composing unconditionally is how it
+ * is avoided.
+ *
+ * ID COLLISIONS DISSOLVE rather than being resolved. Two catalogues may both
+ * carry `outcome-missing`; qualified, they are two different questions. There
+ * is no merge rule, no last-wins and no refusal, because there is nothing to
+ * merge.
+ */
+export function composeCatalogues(sources, profileContext) {
+    const documents = [];
+    const loadDiagnostics = [];
+    for (const source of sources) {
+        const loaded = loadCatalogueDocument(source);
+        if (loaded.ok)
+            documents.push(loaded.document);
+        else
+            loadDiagnostics.push(...loaded.diagnostics);
+    }
+    if (loadDiagnostics.length > 0) {
+        return { ok: false, diagnostics: loadDiagnostics };
     }
-    const catalogue = loadedCatalogue.document.value;
-    const waveIds = new Set(catalogue.waves.map(({ id }) => id));
-    const waveDiagnostics = catalogue.questions.flatMap((question, questionIndex) => waveIds.has(question.wave)
-        ? []
-        : [
-            {
+    const base = documents[0];
+    if (base === undefined) {
+        // Never reached through the CLI, which always has the shipped catalogue,
+        // but an empty set must not compose into an empty catalogue that reports
+        // a finished interview.
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    code: 'YM915',
+                    message: 'No question catalogue to compose',
+                    path: '',
+                    pointer: '',
+                    line: 1,
+                    column: 1,
+                },
+            ],
+        };
+    }
+    // Declared exactly once. A second declaration is refused rather than merged,
+    // because the two carry independent `opensWhen` gates and silently picking
+    // one would decide when a wave opens by file order.
+    const declaredBy = new Map();
+    const duplicates = [];
+    for (const document of documents) {
+        document.catalogue.waves.forEach((wave, waveIndex) => {
+            const first = declaredBy.get(wave.id);
+            if (first === undefined) {
+                declaredBy.set(wave.id, document);
+                return;
+            }
+            duplicates.push({
                 severity: 'error',
-                code: 'YM911',
-                message: `Question "${question.id}" references undeclared wave "${question.wave}"`,
-                ...locateSourcePath(catalogueSource.path, loadedCatalogue.document.yaml, loadedCatalogue.document.lineCounter, ['questions', questionIndex, 'wave'], `/questions/${questionIndex}/wave`),
+                code: 'YM915',
+                message: `Wave "${wave.id}" is already declared by catalogue "${first.catalogue.id}" ` +
+                    `(${first.source.path}). A wave is declared once and contributed to freely: ` +
+                    'drop the declaration here and questions in this catalogue will join it.',
+                ...document.locate(['waves', waveIndex, 'id']),
+            });
+        });
+    }
+    if (duplicates.length > 0)
+        return { ok: false, diagnostics: duplicates };
+    const declaredWaves = new Set(declaredBy.keys());
+    const crossDiagnostics = documents.flatMap((document) => [
+        ...undeclaredWaveDiagnostics(document, declaredWaves),
+        ...unresolvableKindDiagnostics(document, profileContext),
+    ]);
+    if (crossDiagnostics.length > 0) {
+        return { ok: false, diagnostics: crossDiagnostics };
+    }
+    return {
+        ok: true,
+        composed: {
+            catalogue: {
+                ...base.catalogue,
+                // The base names the composition, which is why the report's
+                // `catalogue` field keeps its value shape while `catalogues` lists
+                // every contributor.
+                waves: documents.flatMap(({ catalogue }) => catalogue.waves),
+                questions: documents.flatMap(({ catalogue }) => catalogue.questions.map((question) => ({
+                    ...question,
+                    id: qualifiedQuestionId(catalogue.id, question.id),
+                }))),
             },
-        ]);
+            catalogues: documents.map(({ catalogue }) => `${catalogue.id}@${catalogue.version}`),
+        },
+    };
+}
+// Shared by interrogate and design: schema validation plus the YM911
+// undeclared-wave check, both source-located against the catalogue file.
+export function loadQuestionCatalogue(catalogueSource, profileContext) {
+    const loaded = loadCatalogueDocument(catalogueSource);
+    if (!loaded.ok)
+        return { ok: false, diagnostics: loaded.diagnostics };
+    const waveDiagnostics = undeclaredWaveDiagnostics(loaded.document, new Set(loaded.document.catalogue.waves.map(({ id }) => id)));
     if (waveDiagnostics.length > 0) {
         return { ok: false, diagnostics: waveDiagnostics };
     }
-    // Only when a caller has a compiled workspace to check against. Without one
-    // there is no way to tell a typo from a kind whose profile simply is not
-    // here, and guessing would be the false positive this check exists to avoid.
-    const kindDiagnostics = profileContext === undefined
-        ? []
-        : unresolvableKinds(catalogue, profileContext).map(({ kind, path }) => ({
-            severity: 'error',
-            code: 'YM914',
-            message: `Kind "${kind}" is not declared by profile "${kind.slice(0, kind.indexOf('#'))}", which this workspace loads, so the question can never fire`,
-            ...locateSourcePath(catalogueSource.path, loadedCatalogue.document.yaml, loadedCatalogue.document.lineCounter, path, `/${path.join('/')}`),
-        }));
+    const kindDiagnostics = unresolvableKindDiagnostics(loaded.document, profileContext);
     if (kindDiagnostics.length > 0) {
         return { ok: false, diagnostics: kindDiagnostics };
     }
-    return { ok: true, catalogue };
+    return { ok: true, catalogue: loaded.document.catalogue };
 }
 // Shared by interrogate and `ask --open`: the wave-by-wave human report.
 export function renderInterrogationReport(report) {

package/dist/interrogation-entry.d.ts

@@ -1 +1 @@
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCompositionResult, type ComposedCatalogue, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';

package/dist/interrogation-entry.js

@@ -7,4 +7,4 @@
 // alone: catalogue loading takes a WorkspaceSource, evaluation takes an
 // in-memory graph, and a test pins the import graph free of Node builtins.
 // The same shape the visual-graph projector uses (`./adapter/visual-graph`).
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/projection.d.ts

@@ -108,6 +108,53 @@ export interface ProjectionExclusion {
     readonly id: string;
     readonly facet: ConceptFacet;
 }
+/** A query facet naming something the model does not have. */
+export interface UnmatchedSelector {
+    readonly facet: string;
+    readonly value: string;
+    /** The closest name the facet does offer, when one is close enough to be a likely typo. */
+    readonly nearest?: string;
+}
+/**
+ * Every value in a projection query that names nothing.
+ *
+ * A projection is a DOCUMENT, and a query holds references the same way a
+ * relationship does. YarraMate refuses a relationship pointing at a concept
+ * that does not exist; it did not refuse a query naming a state that does not
+ * exist, and the symptom is silent. `states: [target-stat]` selects no state,
+ * which selects no subject, which exports a clean empty artifact with exit 0.
+ * Someone hands that to a client.
+ *
+ * Checked at `check`, not at `export`, because the typo is in a file rather
+ * than in an invocation: CI catches it, and every verb over the same
+ * projection inherits the guard instead of each growing its own.
+ *
+ * ONLY FACETS WITH A CLOSED NAMESPACE ARE CHECKED. `statuses` and
+ * `excludeStatuses` are schema enums, refused upstream before this runs.
+ * Everything else names something: `owners` and `constraints` are REFS to
+ * concepts, which the compiler itself proves by refusing an unresolved owner
+ * with YM304, so their namespace is the subject list like `subjects`.
+ *
+ * Each namespace is derived the way the FILTER derives it, so the check cannot
+ * drift from what it guards: `documents` reads the same provenance the
+ * `documents` facet compares against, and `states` is the same
+ * `yarramate/state/type` scan `conceptSelector` runs.
+ *
+ * A kind whose profile is not loaded is DORMANT rather than wrong, the same
+ * distinction #351 drew for question catalogues, so the kind facets are
+ * checked only when a profile context is present.
+ *
+ * An empty RESULT is not reported here and must not be. A query whose every
+ * name resolves and which selects nothing is a real answer to a real question:
+ * a target state nobody has populated yet is empty, correctly.
+ */
+export declare function unmatchedSelectors(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): readonly UnmatchedSelector[];
+/**
+ * {@link unmatchedSelectors} as diagnostics, built HERE rather than at each
+ * caller so `check`, and anything that adopts this later, refuse in identical
+ * words with an identical code.
+ */
+export declare function projectionReferenceDiagnostics(source: WorkspaceSource, projection: ProjectionDefinition, graph: SemanticGraph, profileContext?: ResolvedProfileContext): readonly Diagnostic[];
 /**
  * Every concept a query leaves out, and the facet that left it out.
  *