yarramate 1.2.0 → 1.4.0

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';
@@ -202,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)) {
@@ -212,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]]));
@@ -267,9 +282,20 @@ export function runDesignCommand(options, cwd) {
             '',
         ];
         if (step === null) {
-            lines.push(subjectFilter === undefined
-                ? 'Interview complete: no open questions. The model answers everything the catalogue asks.'
-                : `Interview complete for ${subjectFilter}: no open questions touch it.`);
+            // "No open questions" has two causes and only one of them is complete
+            // (#334). Every wave gated shut asks NOTHING, so a blank model reaches
+            // zero without a single question having been put - and claiming the
+            // model answers everything the catalogue asks is then flatly false
+            // about a catalogue that asked nothing. Completion inferred from an
+            // empty set is the same fault the wave rail and the report renderer
+            // each carried; this is the sentence an agent reads to decide it is
+            // done, so it is the worst place for it.
+            const asked = report.waves.some((wave) => wave.questions.length > 0);
+            lines.push(!asked
+                ? 'No wave has opened yet: this catalogue asks nothing until the model has substance. Declare a subject and run this again.'
+                : subjectFilter === undefined
+                    ? 'Interview complete: no open questions. The model answers everything the catalogue asks.'
+                    : `Interview complete for ${subjectFilter}: no open questions touch it.`);
         }
         else {
             // --facilitate prefers the workshop phrasing and falls back to the

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

@@ -14,6 +14,16 @@ export interface CanvasNode {
      * profile kind it was authored as.
      */
     readonly coreKindLabel: string;
+    /**
+     * The core relationship kinds this node's PATTERN ports, or `[]` where its
+     * kind has no pattern with ports (#268 phase 3, ADR 0124).
+     *
+     * A macro edge needs both ends to port its kind, so an editor offering a
+     * palette between two instances intersects the two lists. Two raw groupings
+     * permit ten of the eleven kinds, which is no guidance at all; this is what
+     * restores the narrowing the relationship table gives everywhere else.
+     */
+    readonly portKinds: readonly string[];
     readonly layer: Layer | null;
     readonly aspect: Aspect | null;
     readonly name: string;

package/dist/graph-projection.js

@@ -119,6 +119,7 @@ const projectConcept = (subjectId, claims, profileContext) => {
         kind,
         kindLabel: kindLabelOf(kind),
         coreKindLabel: kindLabelOf(profileContext.conceptKindLineages.get(kind)?.[0] ?? kind),
+        portKinds: profileContext.patternPortKinds.get(kind) ?? [],
         layer: profileContext.conceptKindLayers.get(kind) ?? null,
         aspect: profileContext.conceptKindAspects.get(kind) ?? null,
         name: claimValue(nameClaim),

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,28 @@ export type CatalogueCondition = {
     readonly condition: 'unconstrained-kind';
 } | {
     readonly condition: 'unscoped-succession';
+} | {
+    readonly condition: 'unchallenged-evidence';
+} | {
+    readonly condition: 'has-any-subject';
 };
+/**
+ * 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;
@@ -112,6 +133,11 @@ export interface QuestionCatalogue {
         readonly id: string;
         readonly name: string;
         readonly description?: string;
+        /**
+         * Conditions that must all hold before this wave opens (#334, ADR 0125).
+         * Absent means always open, which is what every wave did before this.
+         */
+        readonly opensWhen?: readonly CatalogueCondition[];
     }[];
     readonly questions: readonly CatalogueQuestion[];
 }
@@ -142,6 +168,16 @@ export interface ReportQuestion {
 export interface ReportWave {
     readonly id: string;
     readonly name: string;
+    /**
+     * Whether the wave's gate is met (#334, ADR 0125). A wave with no
+     * `opensWhen` is always open.
+     *
+     * A wave reported `false` carries NO questions and contributes nothing to
+     * the summary. Its questions are premature rather than answered, and a
+     * progress rail that counted them as answered would flatter itself exactly
+     * where someone is most likely to trust it.
+     */
+    readonly opened: boolean;
     readonly questions: readonly ReportQuestion[];
 }
 export interface InterrogationSummary {
@@ -159,7 +195,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,34 @@ 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 'has-any-subject':
+            // The guard a late wave needs to say "only once the model has
+            // substance" (#334). An empty model is not an architecture at rest -
+            // ADR 0120's reading, which stays true for a model that HAS started -
+            // it has not begun, and asking it how the planned architecture becomes
+            // real greets someone ahead of question one.
+            return index.concepts.size > 0;
+        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,61 +451,76 @@ 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;
     const applicableQuestions = catalogue.questions.filter((question) => questionIsApplicable(question, graph.profiles));
+    const waveOpens = (wave) => wave.opensWhen === undefined ||
+        wave.opensWhen.every((condition) => conditionHolds(index, condition, undefined, profileContext, evidence));
     const waves = catalogue.waves.map((wave) => ({
         id: wave.id,
         name: wave.name,
-        questions: applicableQuestions
-            .filter((question) => question.wave === wave.id)
-            .map((question) => {
-            const base = {
-                id: question.id,
-                scope: question.scope,
-                authority: question.authority,
-                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));
-                if (isOpen) {
-                    open += 1;
-                    openQuestions += 1;
+        opened: waveOpens(wave),
+        // A closed wave asks nothing. Its questions are not evaluated at all,
+        // rather than evaluated and reported closed - the latter would say they
+        // had been asked and answered - so they reach neither the report nor the
+        // summary.
+        questions: !waveOpens(wave)
+            ? []
+            : applicableQuestions
+                .filter((question) => question.wave === wave.id)
+                .map((question) => {
+                const base = {
+                    id: question.id,
+                    scope: question.scope,
+                    authority: question.authority,
+                    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, evidence));
+                    if (isOpen) {
+                        open += 1;
+                        openQuestions += 1;
+                    }
+                    return { ...base, open: isOpen };
                 }
-                return { ...base, open: isOpen };
-            }
-            const matches = selectSubjects(index, question.subjects, profileContext).filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext)));
-            if (matches.length === 0) {
-                return { ...base, open: false };
-            }
-            open += matches.length;
-            openQuestions += 1;
-            return {
-                ...base,
-                open: true,
-                subjects: matches.map((id) => {
-                    const name = index.nameOf.get(id);
-                    return {
-                        id,
-                        ...(name === undefined ? {} : { name }),
-                        question: renderQuestion(question.question, id, name, describeCounterparts(index, question, id)),
-                    };
-                }),
-            };
-        }),
+                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 };
+                }
+                open += matches.length;
+                openQuestions += 1;
+                return {
+                    ...base,
+                    open: true,
+                    subjects: matches.map((id) => {
+                        const name = index.nameOf.get(id);
+                        return {
+                            id,
+                            ...(name === undefined ? {} : { name }),
+                            question: renderQuestion(question.question, id, name, describeCounterparts(index, question, id)),
+                        };
+                    }),
+                };
+            }),
     }));
     return {
         format: 'yarramate/interrogation-report/v1',
         catalogue: `${catalogue.id}@${catalogue.version}`,
         semantics: INTERROGATION_SEMANTICS_VERSION,
         summary: {
-            questions: applicableQuestions.length,
+            // Questions in OPENED waves only (#334, ADR 0125). A closed wave's
+            // questions have not been asked, so counting them in the denominator
+            // would report them as answered - "3 of 51" reading as forty-eight
+            // done when forty-eight were never put. The denominator grows as the
+            // model gains substance and waves open, which is the interview
+            // revealing itself rather than a rail filling up.
+            questions: waves.reduce((total, wave) => total + wave.questions.length, 0),
             openQuestions,
             open,
         },
@@ -519,6 +560,16 @@ export function renderInterrogationReport(report) {
     ];
     for (const wave of report.waves) {
         lines.push('', `== ${wave.name} ==`);
+        // A wave that has not opened must not read like one whose questions are
+        // all closed (#334). Both carry no OPEN questions, and a bare heading with
+        // nothing under it is the more flattering of the two readings: "nothing
+        // outstanding here" rather than "nobody has been asked anything here".
+        // The same shape - completion inferred from an empty set - was found in a
+        // consuming product's wave rail on the same day.
+        if (!wave.opened) {
+            lines.push('  not yet — this wave has not opened');
+            continue;
+        }
         for (const question of wave.questions) {
             if (!question.open) {
                 lines.push(`  closed ${question.id}`);

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 &&

package/dist/relationship-drafting.d.ts

@@ -33,8 +33,16 @@ export declare const connectableKinds: (graph: CanvasGraph, fromId: string, toId
  * relationship kind is a single lowercase word. A collision takes a numeric
  * suffix rather than a hash, because the id is authored text a human will read
  * in a diff.
+ *
+ * `reserved` carries ids the graph does not know yet: a staged-but-uncommitted
+ * draft never enters the rendered graph, so without it a second relationship
+ * between the same pair re-proposed the identical id and the editor's
+ * replace-by-target staging silently swallowed the first (#306). The schema
+ * places no uniqueness on the (from, kind, to) triple - parallel relationships
+ * with distinct ids compile cleanly - so the id proposal is the only place the
+ * collision can be stepped past.
  */
-export declare const proposeRelationshipId: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string) => string;
+export declare const proposeRelationshipId: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string, reserved?: Iterable<string>) => string;
 /**
  * The operation that lands a drafted relationship, or `null` when the draft is
  * one the table does not permit.
@@ -47,5 +55,16 @@ export declare const proposeRelationshipId: (graph: CanvasGraph, fromId: string,
  * relationship has to live somewhere, both endpoints are equally defensible,
  * and the source is where a reader looking for what this thing does would go
  * 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 parallel
+ * relationship steps to `-2` instead of colliding with the first (#306).
+ */
+export declare const draftRelationship: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string, reserved?: Iterable<string>) => YarramateOperation | null;
+/**
+ * The ids a pending changeset already claims, for `proposeRelationshipId`'s
+ * `reserved` parameter. Every operation that names a subject id reserves it -
+ * an update's id is already in the graph and reserving it twice is harmless,
+ * while an add's id is exactly the one the graph cannot know yet.
  */
-export declare const draftRelationship: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string) => YarramateOperation | null;
+export declare const stagedSubjectIds: (operations: readonly YarramateOperation[]) => readonly string[];