yarramate 1.6.0 → 1.7.0

package/dist/adapters/visual/session-server.js

@@ -124,6 +124,28 @@ const shippedCatalogue = (() => {
         return undefined;
     }
 })();
+/**
+ * The shipped catalogue plus the ones the workspace carries (#345, ADR 0129).
+ *
+ * A catalogue that cannot be read is SKIPPED rather than failing the session,
+ * which is what the shipped one already did: an interrogation overlay is a
+ * garnish on a model, and losing a session over it would be worse than losing
+ * the questions. `check` is where a broken catalogue is refused.
+ */
+const catalogueSetFor = (workspace) => {
+    if (shippedCatalogue === undefined)
+        return [];
+    const carried = [];
+    for (const path of workspace.questions ?? []) {
+        try {
+            carried.push({ path, source: readFileSync(path, "utf8") });
+        }
+        catch {
+            // Skipped, as above.
+        }
+    }
+    return [shippedCatalogue, ...carried];
+};
 /**
  * Takes one session terminal, whatever caused it: a reviewer's End, a child
  * that failed, a browser that never came back, a cancelling main agent, or a
@@ -612,7 +634,11 @@ export const startVisualServer = async (options) => {
                 // that. A staged view operation pins against these (ADR 0103), and a
                 // projection missing from the map is one the commit will create.
                 projectionDigests: projectionDigestsNow(),
-            }, shippedCatalogue);
+                // The shipped catalogue plus whatever this workspace carries (#345),
+                // so the pane asks the interview `design` asks over the same files.
+                // Read on each recompile rather than once per process, because a
+                // consultant authoring a question mid-session is the whole point.
+            }, catalogueSetFor(resolvedWorkspace));
             // Closures below retain this array, so refresh its contents without
             // replacing the identity the session started with.
             views.splice(0, views.length, ...workspaceModel.views);

package/dist/adapters/visual/workspace-model.d.ts

@@ -57,10 +57,20 @@ export interface DismissedQuestion {
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
-}, catalogue: {
+}, 
+/**
+ * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
+ * A set rather than one document so the pane asks the same interview the
+ * CLI does over the same workspace: an editor showing fewer questions than
+ * `design` does over the same files is a disagreement with no symptom.
+ */
+catalogue: {
     readonly path: string;
     readonly source: string;
-}, 
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], 
 /**
  * What the host has already dealt with (#328). Evaluation is unchanged and
  * the model is untouched: this decides only what the pane draws, because a
@@ -83,7 +93,10 @@ export declare const renderedWorkspaceOf: (compiled: {
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;
-}, dismissed?: readonly DismissedQuestion[]) => {
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], dismissed?: readonly DismissedQuestion[]) => {
     readonly model: VisualRenderedModel;
     readonly views: readonly VisualViewSummary[];
 };

package/dist/adapters/visual/workspace-model.js

@@ -6,7 +6,7 @@ import { projectGraphForCanvas } from "../../graph-projection.js";
 import { DEFAULT_PROJECTION_DIRECTORY } from "./view-identity.js";
 import { evaluateProjection, explainProjection } from "../../projection.js";
 import { kindLabelOf } from "../../kind-label.js";
-import { evaluateCatalogue, loadQuestionCatalogue, } from "../../interrogate-command.js";
+import { evaluateCatalogue, composeCatalogues, } from "../../interrogate-command.js";
 /**
  * What a workspace looks like to the editor, however the editor is being run
  * (#252).
@@ -46,7 +46,14 @@ export const kindOptionsOf = (lineages) => [...lineages.keys()].map((id) => ({
  * them would read as five, and the reviewer counting boxes would find three.
  */
 export const conceptCountOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.filter(({ type }) => type === "concept").length;
-export const interrogationOverlayOf = (compiled, catalogue, 
+export const interrogationOverlayOf = (compiled, 
+/**
+ * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
+ * A set rather than one document so the pane asks the same interview the
+ * CLI does over the same workspace: an editor showing fewer questions than
+ * `design` does over the same files is a disagreement with no symptom.
+ */
+catalogue, 
 /**
  * What the host has already dealt with (#328). Evaluation is unchanged and
  * the model is untouched: this decides only what the pane draws, because a
@@ -54,10 +61,10 @@ export const interrogationOverlayOf = (compiled, catalogue,
  * a pane embedded in it.
  */
 dismissed = []) => {
-    const loaded = loadQuestionCatalogue(catalogue);
-    if (!loaded.ok)
+    const composed = composeCatalogues(Array.isArray(catalogue) ? catalogue : [catalogue]);
+    if (!composed.ok)
         return undefined;
-    const report = evaluateCatalogue(loaded.catalogue, compiled.graph, compiled.profileContext);
+    const report = evaluateCatalogue(composed.composed.catalogue, compiled.graph, compiled.profileContext, undefined, composed.composed.catalogues);
     const dismissedEverywhere = new Set(dismissed
         .filter(({ subject }) => subject === undefined)
         .map(({ questionId }) => questionId));

package/dist/ask-command.js

@@ -9,7 +9,8 @@ import { runCheckCommand } from './check-command.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
-import { evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, } from './interrogate-command.js';
+import { catalogueSources } from './catalogue-sources.js';
+import { evaluateCatalogue, composeCatalogues, renderInterrogationReport, } from './interrogate-command.js';
 import { buildNextSubjects, coverageClause, } from './next-command.js';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
 import { ARCHIMATE_RELATIONSHIPS_VERSION, CORE_CONCEPT_KIND_ORDER, PERMITTED_RELATIONSHIP_LETTERS, RELATIONSHIP_LETTERS, } from './archimate-relationships.generated.js';
@@ -468,13 +469,13 @@ export function runAskCommand(options, cwd) {
             const planned = buildNextSubjects(wholeWorkspace, compilation.graph, compilation.profileContext, evaluation.reports);
             const current = entries.filter(({ status }) => status === 'current');
             const retired = entries.filter(({ status }) => status === 'retired');
-            const loadedCatalogue = loadQuestionCatalogue({
+            const composed = composeCatalogues(catalogueSources({
                 path: shippedCataloguePath,
                 source: readFileSync(shippedCataloguePath, 'utf8'),
-            }, compilation.profileContext);
-            if (!loadedCatalogue.ok)
-                return failed(loadedCatalogue.diagnostics);
-            const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
+            }, workspace, cwd), compilation.profileContext);
+            if (!composed.ok)
+                return failed(composed.diagnostics);
+            const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues);
             const result = {
                 format: 'yarramate/ask-result/v1',
                 workspace: workspace.id,
@@ -698,12 +699,12 @@ export function runAskCommand(options, cwd) {
             const resolvedCataloguePath = cataloguePath === undefined
                 ? shippedCataloguePath
                 : resolve(cwd, cataloguePath);
-            const loadedCatalogue = loadQuestionCatalogue({
+            const composed = composeCatalogues(catalogueSources({
                 path: cataloguePath ?? resolvedCataloguePath,
                 source: readFileSync(resolvedCataloguePath, 'utf8'),
-            }, compilation.profileContext);
-            if (!loadedCatalogue.ok)
-                return failed(loadedCatalogue.diagnostics);
+            }, workspace, cwd), compilation.profileContext);
+            if (!composed.ok)
+                return failed(composed.diagnostics);
             // The evidence overlay rides along for the one condition that
             // reads it (unchallenged-evidence); a workspace declaring no
             // evidence passes an overlay known to be empty.
@@ -718,13 +719,21 @@ export function runAskCommand(options, cwd) {
                 evidenceObservations.push(...loaded.evidence.observations);
             }
             const report = {
-                ...evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext, evidenceObservations),
+                ...evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues),
                 workspace: workspace.id,
             };
+            // Field by field, to fix key ORDER in the emitted JSON. Every optional
+            // field has to be threaded through explicitly, which is why `catalogues`
+            // is here: a copier like this drops a new field silently and the only
+            // symptom is an absent one, which reads as "did not apply" rather than
+            // as "was lost".
             const ordered = {
                 format: report.format,
                 workspace: report.workspace,
                 catalogue: report.catalogue,
+                ...(report.catalogues === undefined
+                    ? {}
+                    : { catalogues: report.catalogues }),
                 semantics: report.semantics,
                 summary: report.summary,
                 waves: report.waves,
@@ -993,12 +1002,12 @@ export function runAskCommand(options, cwd) {
         const resolvedCataloguePath = cataloguePath === undefined
             ? shippedCataloguePath
             : resolve(cwd, cataloguePath);
-        const loadedCatalogue = loadQuestionCatalogue({
+        const composed = composeCatalogues(catalogueSources({
             path: cataloguePath ?? resolvedCataloguePath,
             source: readFileSync(resolvedCataloguePath, 'utf8'),
-        }, compilation.profileContext);
-        if (!loadedCatalogue.ok)
-            return failed(loadedCatalogue.diagnostics);
+        }, workspace, cwd), compilation.profileContext);
+        if (!composed.ok)
+            return failed(composed.diagnostics);
         // Loaded ahead of evaluation so the overlay feeds the one condition
         // that reads it (unchallenged-evidence), then reused for the
         // reconciliation summary below.
@@ -1012,7 +1021,7 @@ export function runAskCommand(options, cwd) {
                 return failed(loaded.diagnostics);
             evidenceDocuments.push(loaded.evidence);
         }
-        const report = evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
+        const report = evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues);
         const openQuestions = [];
         for (const wave of report.waves) {
             for (const question of wave.questions) {

package/dist/catalogue-sources.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceSource } from './compiler.js';
+import type { ResolvedWorkspace } from './workspace.js';
+export declare const shippedCataloguePath: string;
+/** The base catalogue as a source, read from disk. */
+export declare const shippedCatalogueSource: () => WorkspaceSource;
+/**
+ * The catalogues a verb should compose: the base, then whatever the workspace
+ * carries (#345, ADR 0129).
+ *
+ * Built in ONE place because every verb that interviews has to make the same
+ * choice, and a verb that forgot the workspace half would silently ask fewer
+ * questions than the workspace declares - a failure with no symptom, which is
+ * the shape this repository keeps being bitten by.
+ *
+ * The base is REPLACED by `--catalogue` and ADDED TO by `questions:`. Those
+ * are different powers on purpose: a host controls the catalogue that is not
+ * in the workspace (#328), and a consultant adds to it mid-engagement without
+ * a product release.
+ */
+export declare const catalogueSources: (base: WorkspaceSource, workspace: Pick<ResolvedWorkspace, 'questions'>, cwd: string) => readonly WorkspaceSource[];

package/dist/catalogue-sources.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The catalogue ships inside the package, versioned with it, and harnesses
+// never pass catalogue paths. The relative hop works from both src/ (dev) and
+// dist/ (shipped). Defined ONCE: `design`, `ask` and `check` all need it, and
+// three copies of a path constant is three chances for them to disagree about
+// which catalogue is the base.
+const here = dirname(fileURLToPath(import.meta.url));
+export const shippedCataloguePath = join(here, '..', 'catalogues', 'core-enrichment.yaml');
+/** The base catalogue as a source, read from disk. */
+export const shippedCatalogueSource = () => ({
+    path: shippedCataloguePath,
+    source: readFileSync(shippedCataloguePath, 'utf8'),
+});
+/**
+ * The catalogues a verb should compose: the base, then whatever the workspace
+ * carries (#345, ADR 0129).
+ *
+ * Built in ONE place because every verb that interviews has to make the same
+ * choice, and a verb that forgot the workspace half would silently ask fewer
+ * questions than the workspace declares - a failure with no symptom, which is
+ * the shape this repository keeps being bitten by.
+ *
+ * The base is REPLACED by `--catalogue` and ADDED TO by `questions:`. Those
+ * are different powers on purpose: a host controls the catalogue that is not
+ * in the workspace (#328), and a consultant adds to it mid-engagement without
+ * a product release.
+ */
+export const catalogueSources = (base, workspace, cwd) => [
+    base,
+    // `?? []` because `questions` is optional on the published type: adding a
+    // required field to `ResolvedWorkspace` broke a consumer's production module
+    // once already.
+    ...(workspace.questions ?? []).map((path) => ({
+        path,
+        source: readFileSync(resolve(cwd, path), 'utf8'),
+    })),
+];

package/dist/check-command.js

@@ -1,13 +1,15 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { catalogueSources, shippedCatalogueSource, } from './catalogue-sources.js';
+import { composeCatalogues } from './interrogate-command.js';
 import { resolve } from 'node:path';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { parseDocument } from 'yaml';
 import { loadAdapterMapping, validateAdapterMappings, } from './adapter-mapping.js';
 import { checkResultJson, humanDiagnostics, resolveCliWorkspaceSources, sortDiagnostics, usage, } from './cli-support.js';
-import { compileWorkspace, withDiagnosticSubjects } from './compiler.js';
+import { compileWorkspaceWithProfileContext, withDiagnosticSubjects, } from './compiler.js';
 import { checkCoreContract, loadCoreContract, } from './core-contract.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
-import { loadProjection } from './projection.js';
+import { loadProjection, projectionReferenceDiagnostics, } from './projection.js';
 import { reconcileEvidenceReports, } from './reconciliation.js';
 // `.default ?? module`, not a bare `.default`: NodeNext sees the raw CJS
 // `module.exports` and a bundler the unwrapped class. One shape for all of
@@ -138,13 +140,15 @@ export function runCheckCommand(options, cwd) {
                 : humanDiagnostics(contractDiagnostics);
             return { exitCode: 1, stdout: output, stderr: '' };
         }
-        const projectionDiagnostics = sortDiagnostics(resolved.projections.flatMap((path) => {
-            const loaded = loadProjection({
-                path,
-                source: readFileSync(resolve(cwd, path), 'utf8'),
-            });
-            return loaded.ok ? [] : loaded.diagnostics;
+        const projectionSources = resolved.projections.map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        }));
+        const loadedProjections = projectionSources.map((source) => ({
+            source,
+            loaded: loadProjection(source),
         }));
+        const projectionDiagnostics = sortDiagnostics(loadedProjections.flatMap(({ loaded }) => loaded.ok ? [] : loaded.diagnostics));
         if (projectionDiagnostics.length > 0) {
             const output = json
                 ? checkResultJson(false, projectionDiagnostics)
@@ -177,7 +181,7 @@ export function runCheckCommand(options, cwd) {
                 : humanDiagnostics(mappingLoadDiagnostics);
             return { exitCode: 1, stdout: output, stderr: '' };
         }
-        const result = compileWorkspace(coreSources);
+        const result = compileWorkspaceWithProfileContext(coreSources);
         const mappingValidation = result.ok
             ? validateAdapterMappings(result.graph, loadedMappings.flatMap((loaded) => loaded.ok ? [loaded.mapping] : []))
             : undefined;
@@ -190,9 +194,34 @@ export function runCheckCommand(options, cwd) {
         const evidenceDiagnostics = evidenceEvaluation === undefined || evidenceEvaluation.ok
             ? []
             : evidenceEvaluation.diagnostics;
+        // A catalogue the manifest declares is workspace content, so `check`
+        // refuses a broken one (#345, ADR 0129). Composed rather than checked one
+        // by one, because the refusals that matter are CROSS-catalogue: a wave
+        // declared twice, and a question naming a wave nothing in the set
+        // declares. Checking each file alone would miss both and would refuse the
+        // one thing the feature exists to allow, a question joining a wave another
+        // catalogue declared.
+        const catalogueDiagnostics = result.ok && resolved.questions.length > 0
+            ? (() => {
+                const composed = composeCatalogues(catalogueSources(shippedCatalogueSource(), resolved, cwd), result.profileContext);
+                return composed.ok ? [] : composed.diagnostics;
+            })()
+            : [];
+        // A projection is a document, and a query holds references the same way a
+        // relationship does. Checked HERE rather than with the projection's own
+        // schema load above, because a reference can only be resolved against a
+        // model that compiled: reporting dangling names out of a workspace that
+        // does not build would bury the real failure under its consequences.
+        const referenceDiagnostics = result.ok
+            ? loadedProjections.flatMap(({ source, loaded }) => loaded.ok
+                ? projectionReferenceDiagnostics(source, loaded.projection, result.graph, result.profileContext)
+                : [])
+            : [];
         const optionalDiagnostics = sortDiagnostics([
             ...mappingDiagnostics,
             ...evidenceDiagnostics,
+            ...referenceDiagnostics,
+            ...catalogueDiagnostics,
         ]);
         const ok = result.ok && optionalDiagnostics.length === 0;
         // Published results name the subject a diagnostic is about wherever its

package/dist/cli-support.d.ts

@@ -30,6 +30,13 @@ export declare const resolveCliWorkspaceSources: (paths: readonly string[], cwd:
     readonly contracts: readonly string[];
     /** Pattern documents, which ride in `paths` and are not documents. */
     readonly patterns: readonly string[];
+    /**
+     * Question catalogues the workspace carries (#345). Handed over rather
+     * than resolved-and-dropped, which is the #268 failure recorded below:
+     * a category a manifest declares and no verb receives is ignored with
+     * no symptom.
+     */
+    readonly questions: readonly string[];
 } | {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];

package/dist/cli-support.js

@@ -51,6 +51,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: [],
             contracts: [],
             patterns: [],
+            questions: [],
         };
     }
     const manifestPath = paths[0];
@@ -62,6 +63,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: [],
             contracts: [],
             patterns: [],
+            questions: [],
         };
     }
     const source = readFileSync(resolve(cwd, manifestPath), 'utf8');
@@ -73,6 +75,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: [],
             contracts: [],
             patterns: [],
+            questions: [],
         };
     }
     const loaded = loadWorkspaceManifest({ path: manifestPath, source }, cwd);
@@ -99,6 +102,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: loaded.workspace.evidence,
             contracts: loaded.workspace.contracts,
             patterns: loaded.workspace.patterns,
+            questions: loaded.workspace.questions ?? [],
         }
         : { ok: false, diagnostics: loaded.diagnostics };
 };

package/dist/design-command.js

@@ -5,7 +5,7 @@ import { parseDocument } from 'yaml';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { loadEvidence } from './evidence.js';
-import { evaluateCatalogue, loadQuestionCatalogue, renderQuestion, } from './interrogate-command.js';
+import { composeCatalogues, evaluateCatalogue, renderQuestion, } from './interrogate-command.js';
 import { evaluateProjection } from './projection.js';
 import { renderBrief } from './brief.js';
 import { loadWorkspaceManifest } from './workspace.js';
@@ -205,12 +205,23 @@ export function runDesignCommand(options, cwd) {
         })));
         if (!compilation.ok)
             return failed(compilation.diagnostics);
-        const loadedCatalogue = loadQuestionCatalogue({
-            path: cataloguePath ?? resolvedCataloguePath,
-            source: readFileSync(resolvedCataloguePath, 'utf8'),
-        }, compilation.profileContext);
-        if (!loadedCatalogue.ok)
-            return failed(loadedCatalogue.diagnostics);
+        // The base, then whatever the workspace carries (#345, ADR 0129). The
+        // base is REPLACED by `--catalogue` and ADDED TO by `questions:`, which is
+        // what lets a consultant author a question mid-engagement with no product
+        // release while a host still controls the catalogue that is not in the
+        // workspace.
+        const composed = composeCatalogues([
+            {
+                path: cataloguePath ?? resolvedCataloguePath,
+                source: readFileSync(resolvedCataloguePath, 'utf8'),
+            },
+            ...(workspace.questions ?? []).map((path) => ({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            })),
+        ], compilation.profileContext);
+        if (!composed.ok)
+            return failed(composed.diagnostics);
         // The evidence overlay rides along for the one condition that reads
         // it (unchallenged-evidence). A workspace declaring no evidence
         // passes an empty overlay — known to be empty, which keeps that
@@ -235,8 +246,9 @@ export function runDesignCommand(options, cwd) {
                 };
             }
         }
-        const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceObservations);
-        const askPlainById = new Map(loadedCatalogue.catalogue.questions.flatMap((question) => question.askPlain === undefined
+        const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues);
+        // Keyed by the QUALIFIED id, matching what the report now carries.
+        const askPlainById = new Map(composed.composed.catalogue.questions.flatMap((question) => question.askPlain === undefined
             ? []
             : [[question.id, question.askPlain]]));
         const step = selectStep(report, subjectFilter, askPlainById);

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;