yarramate 1.1.0 → 1.3.0

package/dist/cli-support.d.ts

@@ -7,7 +7,7 @@ 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 design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;

package/dist/cli-support.js

@@ -22,7 +22,7 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { type CliResult } from './cli-support.js';
 export type { CliResult } from './cli-support.js';
+export declare const deriveInitId: (directory: string) => string;
 export declare function runCli(args: readonly string[], cwd?: string): CliResult;

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { dirname, relative, resolve } from 'node:path';
+import { basename, dirname, relative, resolve } from 'node:path';
 import { compileWorkspace } from './compiler.js';
 import { diagnosticJson, isMainModule, usage, versionResult, } from './cli-support.js';
 import { runAskCommand } from './ask-command.js';
@@ -13,8 +13,12 @@ import { deriveAttestationStaleness } from './attestation-staleness.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
 import { loadWorkspaceManifest } from './workspace.js';
 const runReconciliation = (options, cwd) => {
-    const [workspacePath] = options;
-    if (options.length !== 1 ||
+    // Bare reconcile already emits JSON, so --json changes nothing — but a
+    // harness scripting "add --json to every verb" must not hit exit 2 on
+    // the one verb that treats it as unknown (#275). Accepted as a no-op.
+    const positional = options.filter((option) => option !== '--json');
+    const [workspacePath] = positional;
+    if (positional.length !== 1 ||
         workspacePath === undefined ||
         workspacePath.startsWith('-')) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -89,6 +93,22 @@ const runReconciliation = (options, cwd) => {
         return { exitCode: 2, stdout: '', stderr: `${message}\n` };
     }
 };
+// The id grammar the document and workspace schemas share: a lowercase
+// letter first, then lowercase alphanumerics in single-hyphen segments.
+const initIdPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+// The first check output should say the project's own name, not `main`
+// (#275, ADR 0112): the default id is the target directory's basename,
+// slugified to the shared id grammar. `init .` resolves before deriving,
+// so the cwd's basename is what gets named. `main` remains the fallback
+// when the basename yields nothing the schemas accept ('.', '..',
+// all-symbols, a leading digit).
+export const deriveInitId = (directory) => {
+    const slug = basename(directory)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return initIdPattern.test(slug) ? slug : 'main';
+};
 const runInit = (options, cwd) => {
     const positional = options.filter((option) => option !== '--no-pointer');
     const writePointer = positional.length === options.length;
@@ -114,14 +134,15 @@ const runInit = (options, cwd) => {
             stderr: `${existing.join(' and ')} ${existing.length === 1 ? 'already exists' : 'already exist'}; nothing was changed\n`,
         };
     }
+    const workspaceId = deriveInitId(workspaceRoot);
     mkdirSync(dirname(documentPath), { recursive: true });
     writeFileSync(documentPath, 'format: yarramate/v1\n' +
-        'id: main\n' +
+        `id: ${workspaceId}\n` +
         'profile: yarramate/core@0.1\n' +
         'concepts: []\n' +
         'relationships: []\n', 'utf8');
     writeFileSync(manifestPath, 'format: yarramate/workspace/v1\n' +
-        'id: main\n' +
+        `id: ${workspaceId}\n` +
         'documents:\n' +
         '  - architecture/*.yaml\n' +
         'profiles: []\n' +

package/dist/concept-drafting.d.ts

@@ -9,8 +9,14 @@ import type { YarramateOperation } from './operations.js';
  * about a name produces worse ids than a transliteration of the name does.
  * Returning null rather than a placeholder keeps a subject called `"???"` from
  * landing as `subject-1`, which nothing could later be traced back from.
+ *
+ * `reserved` carries ids the graph does not know yet: a staged-but-uncommitted
+ * draft never enters the rendered graph, so without it a second subject whose
+ * name slugs to the same id re-proposed it and the editor's replace-by-target
+ * staging silently swallowed the first (#315) - the identical blind spot
+ * `proposeRelationshipId` had before #306's fix, and the identical way out.
  */
-export declare const proposeConceptId: (graph: CanvasGraph, name: string) => string | null;
+export declare const proposeConceptId: (graph: CanvasGraph, name: string, reserved?: Iterable<string>) => string | null;
 /**
  * The operation that lands a new subject, or `null` when the draft is one no
  * document could accept.
@@ -19,9 +25,14 @@ export declare const proposeConceptId: (graph: CanvasGraph, name: string) => str
  * a kind outside it here, rather than trusting the caller's palette, is the
  * same posture `draftRelationship` takes: the guarantee has to hold for any
  * caller, not only one that filtered first.
+ *
+ * A caller holding drafts the graph has not landed yet - an editor with a
+ * pending changeset - passes their ids as `reserved`, so a second subject
+ * slugging to a taken id steps to `-2` instead of colliding with the first
+ * (#315).
  */
 export declare const draftConcept: (graph: CanvasGraph, input: {
     readonly name: string;
     readonly kind: string;
     readonly document: string;
-}, kinds: readonly string[]) => YarramateOperation | null;
+}, kinds: readonly string[], reserved?: Iterable<string>) => YarramateOperation | null;

package/dist/concept-drafting.js

@@ -17,8 +17,14 @@ const ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
  * about a name produces worse ids than a transliteration of the name does.
  * Returning null rather than a placeholder keeps a subject called `"???"` from
  * landing as `subject-1`, which nothing could later be traced back from.
+ *
+ * `reserved` carries ids the graph does not know yet: a staged-but-uncommitted
+ * draft never enters the rendered graph, so without it a second subject whose
+ * name slugs to the same id re-proposed it and the editor's replace-by-target
+ * staging silently swallowed the first (#315) - the identical blind spot
+ * `proposeRelationshipId` had before #306's fix, and the identical way out.
  */
-export const proposeConceptId = (graph, name) => {
+export const proposeConceptId = (graph, name, reserved = []) => {
     const base = name
         .normalize('NFKD')
         // The marks NFKD split off, dropped rather than treated as boundaries:
@@ -38,6 +44,7 @@ export const proposeConceptId = (graph, name) => {
     const taken = new Set([
         ...graph.nodes.map((node) => node.id),
         ...graph.edges.map((edge) => edge.id),
+        ...reserved,
     ]);
     if (!taken.has(base))
         return base;
@@ -55,8 +62,13 @@ export const proposeConceptId = (graph, name) => {
  * a kind outside it here, rather than trusting the caller's palette, is the
  * same posture `draftRelationship` takes: the guarantee has to hold for any
  * caller, not only one that filtered first.
+ *
+ * A caller holding drafts the graph has not landed yet - an editor with a
+ * pending changeset - passes their ids as `reserved`, so a second subject
+ * slugging to a taken id steps to `-2` instead of colliding with the first
+ * (#315).
  */
-export const draftConcept = (graph, input, kinds) => {
+export const draftConcept = (graph, input, kinds, reserved = []) => {
     if (input.document === '')
         return null;
     if (!kinds.includes(input.kind))
@@ -64,7 +76,7 @@ export const draftConcept = (graph, input, kinds) => {
     const name = input.name.trim();
     if (name === '')
         return null;
-    const id = proposeConceptId(graph, name);
+    const id = proposeConceptId(graph, name, reserved);
     if (id === null)
         return null;
     return {

package/dist/design-command.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 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 { evaluateProjection } from './projection.js';
 import { renderBrief } from './brief.js';
@@ -37,6 +38,7 @@ const selectStep = (report, subjectFilter, askPlainById) => {
                         : { askPlain: askPlainTemplate.trim() }),
                     materiality: question.materiality,
                     resolution: question.resolution,
+                    trigger: question.trigger,
                     ...(question.since === undefined ? {} : { since: question.since }),
                 };
             }
@@ -57,6 +59,7 @@ const selectStep = (report, subjectFilter, askPlainById) => {
                     : { askPlain: renderQuestion(askPlainTemplate, first.id, first.name) }),
                 materiality: question.materiality,
                 resolution: question.resolution,
+                trigger: question.trigger,
                 ...(question.since === undefined ? {} : { since: question.since }),
                 subject: {
                     id: first.id,
@@ -74,6 +77,56 @@ const selectStep = (report, subjectFilter, askPlainById) => {
     }
     return null;
 };
+const localKind = (qualified) => {
+    const hash = qualified.lastIndexOf('#');
+    return hash === -1 ? qualified : qualified.slice(hash + 1);
+};
+const skeletonHeader = (documentAddress, op) => [
+    '',
+    'Prefilled skeleton (edit the <placeholders>, save as operations.yaml):',
+    '  format: yarramate/operations/v1',
+    '  operations:',
+    `    - op: ${op}`,
+    `      document: ${documentAddress}`,
+];
+// The skeleton is a rendering of the step's trigger (#289), printed only
+// when a single condition maps unambiguously onto one operation, so a
+// wrong skeleton is never offered; every other trigger leaves the output
+// exactly as before. Kinds print as local names: that is the form a
+// native document declares.
+const renderSkeleton = (step, documentAddress) => {
+    if (documentAddress === undefined || step.trigger.length !== 1)
+        return [];
+    const condition = step.trigger[0];
+    if (condition.condition === 'no-subject-of-kind') {
+        const kinds = condition.kinds.map(localKind);
+        const alternatives = kinds.length > 1 ? `  # or: ${kinds.slice(1).join(', ')}` : '';
+        return [
+            ...skeletonHeader(documentAddress, 'add-concept'),
+            '      concept:',
+            '        id: <kebab-case-id>',
+            `        kind: ${kinds[0]}${alternatives}`,
+            '        name: <one line>',
+        ];
+    }
+    if (condition.condition === 'missing-relationship' &&
+        step.subject !== undefined) {
+        const kinds = condition.kinds.map(localKind);
+        const alternatives = kinds.length > 1 ? `  # or: ${kinds.slice(1).join(', ')}` : '';
+        const swap = condition.direction === 'any' ? '  # or swap the endpoints' : '';
+        const from = condition.direction === 'incoming' ? '<counterpart-id>' : step.subject.id;
+        const to = condition.direction === 'incoming' ? step.subject.id : '<counterpart-id>';
+        return [
+            ...skeletonHeader(documentAddress, 'add-relationship'),
+            '      relationship:',
+            '        id: <kebab-case-id>',
+            `        kind: ${kinds[0]}${alternatives}`,
+            `        from: ${from}${swap}`,
+            `        to: ${to}`,
+        ];
+    }
+    return [];
+};
 export function runDesignCommand(options, cwd) {
     const json = options.includes('--json');
     // Facilitation is a rendering preference, not an interview mode: the
@@ -150,6 +203,20 @@ export function runDesignCommand(options, cwd) {
         })));
         if (!compilation.ok)
             return failed(compilation.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
+        // condition quiet — rather than an absent one.
+        const evidenceObservations = [];
+        for (const path of workspace.evidence) {
+            const loadedEvidence = loadEvidence({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            });
+            if (!loadedEvidence.ok)
+                return failed(loadedEvidence.diagnostics);
+            evidenceObservations.push(...loadedEvidence.evidence.observations);
+        }
         if (subjectFilter !== undefined) {
             const known = new Set(compilation.graph.subjects.map(({ id }) => id));
             if (!known.has(subjectFilter)) {
@@ -160,7 +227,7 @@ export function runDesignCommand(options, cwd) {
                 };
             }
         }
-        const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext);
+        const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceObservations);
         const askPlainById = new Map(loadedCatalogue.catalogue.questions.flatMap((question) => question.askPlain === undefined
             ? []
             : [[question.id, question.askPlain]]));
@@ -232,7 +299,21 @@ export function runDesignCommand(options, cwd) {
             if (slice !== undefined) {
                 lines.push('', 'Subject slice:', '', slice.trimEnd());
             }
-            lines.push('', 'Answer by updating the model (one atomic batch):', `  yarramate apply <operations.yaml> ${workspacePath}`, `Then re-run: yarramate design ${workspacePath}`);
+            // The skeleton's document address is the manifest-relative form
+            // when the first document sits under the manifest directory - the
+            // address an author naturally writes and apply accepts (#216) -
+            // falling back to the workspace path, which apply also accepts.
+            const manifestDirectory = workspacePath.includes('/')
+                ? workspacePath.slice(0, workspacePath.lastIndexOf('/'))
+                : '';
+            const firstDocument = workspace.documents[0];
+            const documentAddress = firstDocument === undefined
+                ? undefined
+                : manifestDirectory !== '' &&
+                    firstDocument.startsWith(`${manifestDirectory}/`)
+                    ? firstDocument.slice(manifestDirectory.length + 1)
+                    : firstDocument;
+            lines.push('', 'Answer by updating the model (one atomic batch):', `  yarramate apply <operations.yaml> ${workspacePath}`, ...renderSkeleton(step, documentAddress), `Then re-run: yarramate design ${workspacePath}`);
         }
         return { exitCode: 0, stdout: `${lines.join('\n')}\n`, stderr: '' };
     }

package/dist/evidence.js

@@ -27,6 +27,31 @@ export function loadEvidence(source) {
             ...(observation.key === undefined || observation.value === undefined
                 ? {}
                 : { key: observation.key, value: observation.value }),
+            // Provenance survives normalization: reconcile counts a
+            // not-observed naming no search (ADR 0107) and interrogation's
+            // unchallenged-evidence reads recorded searches (ADR 0120), so a
+            // load path that dropped them made both read every overlay as
+            // probe-free however carefully its author recorded one.
+            ...(observation.searched === undefined
+                ? {}
+                : {
+                    searched: observation.searched.map((probe) => 'glob' in probe
+                        ? { glob: probe.glob }
+                        : {
+                            grep: probe.grep,
+                            ...(probe.paths === undefined
+                                ? {}
+                                : { paths: [...probe.paths] }),
+                        }),
+                }),
+            ...(observation.measured === undefined
+                ? {}
+                : {
+                    measured: observation.measured.map(({ value, method }) => ({
+                        value,
+                        method,
+                    })),
+                }),
             evidence: {
                 uri: observation.evidence.uri,
                 ...(observation.evidence.message === undefined

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, ty
 export type { LifecycleStatus, ProjectionDefinition, ProjectionLoadResult, ProjectionResult, } from './projection.js';
 export { createFileSystemStore, type PendingWrite, type SourceStore, type StoredSource, type WriteConflict, type WriteOutcome, } from './source-store.js';
 export { applyOperations, landOperations, posixDirectoryOf, type ApplyInput, type ApplyOutcome, } from './apply-command.js';
-export { connectableKinds, draftRelationship, proposeRelationshipId, } from './relationship-drafting.js';
+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 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, 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

@@ -13,7 +13,7 @@ export { canonicalProjection, evaluateProjection, explainProjection, loadProject
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, } from './adapter-mapping.js';
 export { createFileSystemStore, } from './source-store.js';
 export { applyOperations, landOperations, posixDirectoryOf, } from './apply-command.js';
-export { connectableKinds, draftRelationship, proposeRelationshipId, } from './relationship-drafting.js';
+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';

package/dist/interrogate-command.d.ts

@@ -85,7 +85,26 @@ export type CatalogueCondition = {
     readonly condition: 'unconstrained-kind';
 } | {
     readonly condition: 'unscoped-succession';
+} | {
+    readonly condition: 'unchallenged-evidence';
 };
+/**
+ * One observation from the workspace's evidence overlay, reduced to what
+ * interrogation reads: the result, and whether a search was recorded with
+ * it. The only condition that reads the overlay is `unchallenged-evidence`;
+ * every other condition reads the compiled graph alone, and the overlay
+ * never influences which subjects a selector matches.
+ *
+ * Shaped structurally rather than importing {@link EvidenceObservation} so
+ * the pure engine entry (`./interrogation-entry`) keeps owning its whole
+ * input surface: a caller passes
+ * `evidenceDocuments.flatMap(({ observations }) => observations)` and the
+ * wider evidence shape is never dragged in.
+ */
+export interface CatalogueEvidenceObservation {
+    readonly result: 'confirmed' | 'contradicted' | 'unknown' | 'not-observed';
+    readonly searched?: readonly unknown[];
+}
 export interface CatalogueQuestion {
     readonly id: string;
     readonly wave: string;
@@ -128,6 +147,14 @@ export interface ReportQuestion {
     readonly question: string;
     readonly materiality: string;
     readonly resolution: string;
+    /**
+     * The catalogue trigger, verbatim (#289). The conditions that opened a
+     * question are its machine-readable answer shape: a host builds the
+     * matching affordance (a prefilled form, an operations skeleton) from
+     * them instead of re-deriving the shape from its own catalogue copy and
+     * drifting from engine semantics.
+     */
+    readonly trigger: readonly CatalogueCondition[];
     readonly since?: string;
     readonly subjects?: readonly OpenSubject[];
 }
@@ -151,7 +178,7 @@ export interface InterrogationReport {
     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): Omit<InterrogationReport, 'workspace'>;
+export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext, evidence?: readonly CatalogueEvidenceObservation[]): Omit<InterrogationReport, 'workspace'>;
 export type CatalogueLoadResult = {
     readonly ok: true;
     readonly catalogue: QuestionCatalogue;

package/dist/interrogate-command.js

@@ -236,8 +236,27 @@ const linkageHits = (index, condition, subjectId, profileContext) => {
         return counterparts.some((counterpart) => kindMatches(index.kindOf.get(counterpart), condition.counterpartKinds, matching, profileContext));
     });
 };
-const conditionHolds = (index, condition, subjectId, profileContext) => {
+const conditionHolds = (index, condition, subjectId, profileContext, evidence) => {
     switch (condition.condition) {
+        case 'unchallenged-evidence':
+            // Fires where the overlay records observations and every one is a
+            // frictionless confirmation: no contradicted, unknown, or
+            // not-observed result, and no recorded search. A discovery that
+            // never records anything but success never tested a claim it might
+            // fail — 39 of 39 GitLab observations said confirmed while Praefect
+            // sat declared upstream and absent from the tree (#272). A recorded
+            // search closes it even on a confirmed result, because a
+            // confirmation of a negative claim rests on exactly the empty
+            // search ADR 0107 made auditable; so does any honest non-confirmed
+            // result. An empty overlay stays quiet: with no observations there
+            // is no inspection to interrogate. An absent overlay also stays
+            // quiet — the caller did not supply one, so its diversity is
+            // unknown, not absent, the same rule `unconstrained-kind` applies
+            // to a missing profile context.
+            return (evidence !== undefined &&
+                evidence.length > 0 &&
+                evidence.every(({ result, searched }) => result === 'confirmed' &&
+                    (searched === undefined || searched.length === 0)));
         case 'missing-claim':
             return !(index.claimsBySubject.get(subjectId) ?? []).some(({ predicate }) => predicate === condition.predicate);
         case 'unscoped-succession': {
@@ -425,7 +444,7 @@ const describeCounterparts = (index, question, subjectId) => {
         return name === undefined ? id : `${name} (${id})`;
     });
 };
-export function evaluateCatalogue(catalogue, graph, profileContext) {
+export function evaluateCatalogue(catalogue, graph, profileContext, evidence) {
     const index = indexGraph(graph);
     let open = 0;
     let openQuestions = 0;
@@ -443,17 +462,18 @@ export function evaluateCatalogue(catalogue, graph, profileContext) {
                 question: question.question.trim(),
                 materiality: question.materiality.trim(),
                 resolution: question.resolution.trim(),
+                trigger: question.trigger,
                 ...(question.since === undefined ? {} : { since: question.since }),
             };
             if (question.scope === 'workspace') {
-                const isOpen = question.trigger.every((condition) => conditionHolds(index, condition, undefined, profileContext));
+                const isOpen = question.trigger.every((condition) => conditionHolds(index, condition, undefined, profileContext, evidence));
                 if (isOpen) {
                     open += 1;
                     openQuestions += 1;
                 }
                 return { ...base, open: isOpen };
             }
-            const matches = selectSubjects(index, question.subjects, profileContext).filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext)));
+            const matches = selectSubjects(index, question.subjects, profileContext).filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext, evidence)));
             if (matches.length === 0) {
                 return { ...base, open: false };
             }

package/dist/interrogation-entry.d.ts

@@ -1 +1 @@
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, 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, 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/layout-direction.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which way a view runs its layers, kept in a module that imports nothing.
+ *
+ * Here rather than in `projection.ts` for the reason `./nesting.ts` gives: the
+ * browser needs the value and not only the type, and `projection.ts` drags Ajv
+ * and the projection schema in for one constant. `projection.ts` re-exports
+ * both.
+ */
+export type LayoutDirection = 'top-down' | 'left-right';
+/**
+ * How a view runs when it does not say. Top-down is the behaviour that
+ * shipped, and it is what ArchiMate's layer bands read as (ADR 0121).
+ */
+export declare const DEFAULT_DIRECTION: LayoutDirection;

package/dist/layout-direction.js

@@ -0,0 +1,5 @@
+/**
+ * How a view runs when it does not say. Top-down is the behaviour that
+ * shipped, and it is what ArchiMate's layer bands read as (ADR 0121).
+ */
+export const DEFAULT_DIRECTION = 'top-down';

package/dist/projection.d.ts

@@ -6,6 +6,16 @@ export interface ProjectionDefinition {
     readonly version: string;
     readonly query: {
         readonly subjects?: readonly string[];
+        /**
+         * Subjects this query would otherwise select and the author has taken out
+         * (#267, ADR 0122). A facet view states a rule, and every interesting rule
+         * has an exception someone would rather state than abandon the rule for;
+         * this is where that exception is written down instead of being the silent
+         * absence a hand-enumerated list produces. Applied after every other facet
+         * AND after `relationships: connected` expansion, so an excluded subject is
+         * out whichever way it would have come back in.
+         */
+        readonly exclude?: readonly string[];
         readonly documents?: readonly string[];
         readonly kinds?: readonly string[];
         readonly layers?: readonly string[];
@@ -24,12 +34,12 @@ export interface ProjectionDefinition {
         readonly description?: string;
         readonly layout?: 'layered';
         /**
-         * Read by the LikeC4 export for its `autoLayout`, and by nothing else. The
-         * canvas draws ArchiMate, whose layer bands only read top-down, so it
-         * ignores this rather than offering a control that would tilt the bands
-         * away from what they mean.
+         * Which way this view runs its layers. Read by the LikeC4 export for its
+         * `autoLayout` and by the canvas for ELK's `elk.direction` (ADR 0121); a
+         * view that says nothing runs `top-down`, which is what ArchiMate's layer
+         * bands read as.
          */
-        readonly direction?: 'top-down' | 'left-right';
+        readonly direction?: LayoutDirection;
         /**
          * The relationship kinds that draw as nesting in this view, in precedence
          * order (ADR 0101). Absent means `['composition']`, which is the behaviour
@@ -64,6 +74,12 @@ export interface ProjectionDefinition {
  */
 export { DEFAULT_NESTING, type NestingKind } from './nesting.js';
 import type { NestingKind } from './nesting.js';
+/**
+ * Which way a view runs, and the default. Split out for the same reason as the
+ * nesting vocabulary above, and re-exported here on the same terms (ADR 0121).
+ */
+export { DEFAULT_DIRECTION, type LayoutDirection } from './layout-direction.js';
+import type { LayoutDirection } from './layout-direction.js';
 export type ProjectionQuery = ProjectionDefinition['query'];
 export interface ProjectionResult {
     readonly format: 'yarramate/projection-result/v1';
@@ -86,7 +102,7 @@ export declare function canonicalProjection(projection: ProjectionDefinition): P
  * A facet of a query, named the way the query names it. What
  * {@link explainProjection} reports as the reason a subject is not in a view.
  */
-export type ConceptFacet = 'states' | 'subjects' | 'documents' | 'kinds' | 'layers' | 'statuses' | 'excludeStatuses' | 'owners' | 'constraints';
+export type ConceptFacet = 'exclude' | 'states' | 'subjects' | 'documents' | 'kinds' | 'layers' | 'statuses' | 'excludeStatuses' | 'owners' | 'constraints';
 /** One subject a query dropped, and the facet that dropped it. */
 export interface ProjectionExclusion {
     readonly id: string;

package/dist/projection.js

@@ -14,6 +14,11 @@ const validateProjection = new Ajv2020({ allErrors: true }).compile(projectionSc
  * and a schema, which is a great deal of bundle for one constant (ADR 0101).
  */
 export { DEFAULT_NESTING } from './nesting.js';
+/**
+ * Which way a view runs, and the default. Split out for the same reason as the
+ * nesting vocabulary above, and re-exported here on the same terms (ADR 0121).
+ */
+export { DEFAULT_DIRECTION } from './layout-direction.js';
 export function loadProjection(source) {
     const loaded = loadSourceDocument(source, validateProjection, 'Projection');
     return loaded.ok
@@ -124,7 +129,13 @@ const conceptSelector = (graph, projection, profileContext) => {
                 ? undefined
                 : profileContext?.conceptKindLayers.get(kind);
             // Ordered the way a query declares its facets, so "the first reason" is
-            // the one a reader would reach first themselves.
+            // the one a reader would reach first themselves - except the explicit
+            // exception, which outranks every rule: when someone has written the
+            // subject down as taken out, that IS the first reason, whatever else
+            // would also have dropped it (#267).
+            if (query.exclude?.includes(id) === true) {
+                return 'exclude';
+            }
             if (query.states !== undefined &&
                 (architectureStateIds.has(id) || !participatesInSelectedState(id))) {
                 return 'states';
@@ -201,6 +212,12 @@ export function explainProjection(graph, projection, profileContext) {
 export function evaluateProjection(graph, projection, profileContext) {
     const { droppedBy, architectureStateIds, participatesInSelectedState } = conceptSelector(graph, projection, profileContext);
     const endpointExcluded = (id) => {
+        // An exclusion is final (#267, ADR 0122). Dropping the subject from the
+        // initial selection alone would not be: `relationships: connected` adds
+        // the far end of every relationship it draws, so an excluded subject would
+        // walk back in by the other end of a relationship to one that stayed.
+        if (projection.query.exclude?.includes(id) === true)
+            return true;
         if (!participatesInSelectedState(id))
             return true;
         const status = claimValue(graph.claims, id, 'yarramate/lifecycle/status');
@@ -221,7 +238,11 @@ export function evaluateProjection(graph, projection, profileContext) {
                 continue;
             const relationship = graph.claims.find((claim) => claim.id === subject.id);
             const relationshipStatus = claimValue(graph.claims, subject.id, 'yarramate/lifecycle/status');
-            if (relationship === undefined ||
+            if (
+            // A relationship can be taken out by name too: `exclude` names
+            // subjects, and a relationship is a subject.
+            projection.query.exclude?.includes(subject.id) === true ||
+                relationship === undefined ||
                 !('ref' in relationship.object) ||
                 (projection.query.excludeStatuses !== undefined &&
                     relationshipStatus !== undefined &&