yarramate 1.9.0 → 1.11.0

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

@@ -6,7 +6,7 @@ import { basename, extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import Ajv2020Module from "ajv/dist/2020.js";
 import { WebSocketServer } from "ws";
-import { parse, stringify } from "yaml";
+import { parse } from "yaml";
 import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, digestOf, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, toWireFileUri, visualBrowserInputType, } from "./protocol.js";
 import { appendTerminalEvent, appendVisualEvent, appendVisualResponse, createVisualSession, isActionableVisualEvent, recoverVisualSession, removeVisualSession, writeVisualSessionDescriptor, } from "./session-store.js";
 import { loadProjection, } from "../../projection.js";
@@ -15,6 +15,7 @@ import { adoptLandedViews, exclusionsOf, matchedIdsOf, planViewWrites, published
 import { compileWorkspaceWithProfileContext, } from "../../compiler.js";
 import { planOperations, posixDirectoryOf, writeConflictDiagnostics, } from "../../apply-command.js";
 import { createFileSystemStore } from "../../source-store.js";
+import { emitYaml } from "../../yaml-emission.js";
 import { loadWorkspaceManifest, } from "../../workspace.js";
 import visualLayoutSchema from "../../../schema/yarramate-visual-layout.schema.json" with { type: "json" };
 import visualProjectionSchema from "../../../schema/yarramate-projection.schema.json" with { type: "json" };
@@ -1306,7 +1307,7 @@ export const startVisualServer = async (options) => {
                     }
                     return;
                 }
-                const operationsSource = stringify({
+                const operationsSource = emitYaml({
                     format: "yarramate/operations/v1",
                     operations: event.payload.operations,
                 });
@@ -1417,7 +1418,7 @@ export const startVisualServer = async (options) => {
                 }
                 const path = `.yarramate/visual-layout/${projectionId}.yaml`;
                 mkdirSync(layoutDir, { recursive: true });
-                writeFileSync(resolve(options.cwd, path), stringify({
+                writeFileSync(resolve(options.cwd, path), emitYaml({
                     format: "yarramate/visual-layout/v1",
                     projectionId,
                     positions,

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

@@ -1,5 +1,5 @@
-import { stringify } from "yaml";
 import { loadProjection } from "../../projection.js";
+import { emitYaml } from "../../yaml-emission.js";
 import { withDiagnosticSubjects } from "../../compiler.js";
 import { posixDirectoryOf } from "../../apply-command.js";
 import { projectGraphForCanvas } from "../../graph-projection.js";
@@ -259,7 +259,7 @@ export const planViewWrites = (operations, workspace, store) => {
             diagnostics.push(serverDiagnostic("YMVS315", `The workspace manifest covers no projection in "${posixDirectoryOf(operation.path)}", so a view saved there would never load`));
             continue;
         }
-        const source = stringify(operation.projection);
+        const source = emitYaml(operation.projection);
         const loaded = loadProjection({ path: operation.path, source });
         if (!loaded.ok) {
             // The composed document is the only source these are about, so they are

package/dist/apply-command.js

@@ -1,8 +1,9 @@
-import { isMap, isScalar, isSeq, parseDocument, stringify, } from 'yaml';
+import { isMap, isScalar, isSeq, parseDocument, } from 'yaml';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { loadAdapterMapping } from './adapter-mapping.js';
 import { compileWorkspace, withDiagnosticSubjects, } from './compiler.js';
 import { evaluateEvidence, loadEvidence } from './evidence.js';
+import { emitYaml } from './yaml-emission.js';
 import { loadProjection } from './projection.js';
 import { loadSourceDocument, locateSourcePath, } from './source-document.js';
 import { declaredStateIds, rewriteSubjectReferences, scanSubjectReferences, } from './subject-references.js';
@@ -61,7 +62,7 @@ const reindent = (text, indent) => text.split('\n').join(`\n${' '.repeat(indent)
 // A plain value as YAML source. lineWidth 0 keeps strings we author on one
 // line; genuinely multi-line strings become block scalars and are re-indented
 // by the caller.
-const valueText = (value) => stringify(value, { lineWidth: 0 }).trimEnd();
+const valueText = (value) => emitYaml(value, { lineWidth: 0 }).trimEnd();
 const pairFor = (map, key) => map.items.find((pair) => isScalar(pair.key) && pair.key.value === key);
 const nodeRange = (node) => {
     const range = node.range;
@@ -72,7 +73,7 @@ const nodeRange = (node) => {
 };
 // Renders `items` as block sequence entries at the given marker indent.
 const sequenceEntries = (items, markerIndent) => {
-    const rendered = stringify(items, { lineWidth: 0 }).trimEnd();
+    const rendered = emitYaml(items, { lineWidth: 0 }).trimEnd();
     return `${' '.repeat(markerIndent)}${reindent(rendered, markerIndent)}`;
 };
 const splice = (source, start, end, text) => source.slice(0, start) + text + source.slice(end);
@@ -186,7 +187,7 @@ const rewriteFlowItem = (source, map, mutate) => {
     const mutated = mutate(map.toJSON());
     const [start, valueEnd] = nodeRange(map);
     const fieldIndent = indentAt(source, start);
-    const rendered = reindent(stringify(mutated, { lineWidth: 0 }).trimEnd(), fieldIndent);
+    const rendered = reindent(emitYaml(mutated, { lineWidth: 0 }).trimEnd(), fieldIndent);
     return splice(source, start, valueEnd, rendered);
 };
 const setScalarField = (source, map, key, value) => {
@@ -235,7 +236,7 @@ const appendListField = (source, map, key, additions) => {
         ? nodeRange(sequence)
         : nodeRange(pair.value);
     if (isSeq(sequence) && sequence.flow) {
-        const flow = stringify(merged, {
+        const flow = emitYaml(merged, {
             collectionStyle: 'flow',
             lineWidth: 0,
         }).trimEnd();
@@ -278,7 +279,7 @@ const removeCollectionItem = (source, collection, matches) => {
         const [start, valueEnd] = nodeRange(sequence);
         return splice(source, start, valueEnd, remaining.length === 0
             ? '[]'
-            : stringify(remaining, {
+            : emitYaml(remaining, {
                 collectionStyle: 'flow',
                 lineWidth: 0,
             }).trimEnd());

package/dist/import-command.js

@@ -9,10 +9,10 @@ import { buildWorkbookSheets } from './workbook.js';
 import { baselineSheets, mergeWorkbook } from './workbook-merge.js';
 import { operationsFrom, operationsDocument } from './workbook-operations.js';
 import { readWorkbook } from './workbook-read.js';
+import { emitYaml } from './yaml-emission.js';
 import { writeFileSync, mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { stringify } from 'yaml';
 /**
  * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
  *
@@ -137,7 +137,7 @@ export async function runImportCommand(options, cwd) {
     // atomic gate, and the surgical YAML editing that keeps comments.
     const scratch = mkdtempSync(join(tmpdir(), 'yarramate-import-'));
     const operationsPath = join(scratch, 'operations.yaml');
-    writeFileSync(operationsPath, stringify(operationsDocument(planned.operations)), 'utf8');
+    writeFileSync(operationsPath, emitYaml(operationsDocument(planned.operations)), 'utf8');
     const applied = runApplyCommand([operationsPath, workspacePath], cwd);
     if (applied.exitCode !== 0)
         return applied;

package/dist/interrogate-command.d.ts

@@ -178,6 +178,16 @@ export interface ReportQuestion {
     readonly scope: 'workspace' | 'subject';
     readonly authority: 'human' | 'agent' | 'either';
     readonly open: boolean;
+    /**
+     * Whether the question was asked at all (#375, ADR 0132). Absent means
+     * true; only a subject-scoped question whose selector matched NO subject
+     * carries `asked: false`. Without it, never-asked and answered were
+     * byte-identical (`open: false`), and a host summing closed questions
+     * read an empty model as a satisfied interview — completion inferred
+     * from an empty set, the exact reading ADR 0125 refuses one level up by
+     * not evaluating a closed wave's questions at all.
+     */
+    readonly asked?: boolean;
     readonly question: string;
     readonly materiality: string;
     readonly resolution: string;

package/dist/interrogate-command.js

@@ -1,6 +1,7 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { loadSourceDocument, locateSourcePath, } from './source-document.js';
 import { nearDuplicateIndex } from './subject-identity.js';
+import { sourceKindsPermitting, tableKnowsConceptKind, tableKnowsRelationshipKind, targetKindsPermitting, } from './relationship-matrix.js';
 import catalogueSchema from '../schema/yarramate-question-catalogue.schema.json' with { type: 'json'
 };
 // `.default ?? module`, not a bare `.default`: NodeNext sees the raw CJS
@@ -517,7 +518,16 @@ patternMemberships) {
                     }
                     return { ...base, open: isOpen };
                 }
-                const matches = selectSubjects(index, question.subjects, profileContext).filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext, evidence, patternMemberships)));
+                // Selection and trigger filtering are separate reads on purpose
+                // (#375, ADR 0132): a selector matching nobody means the question
+                // was never asked, and reporting that as a closed question said it
+                // had been asked and answered — completion inferred from an empty
+                // set, the reading ADR 0125 refuses one level up.
+                const selected = selectSubjects(index, question.subjects, profileContext);
+                if (selected.length === 0) {
+                    return { ...base, open: false, asked: false };
+                }
+                const matches = selected.filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext, evidence, patternMemberships)));
                 if (matches.length === 0) {
                     return { ...base, open: false };
                 }
@@ -648,6 +658,128 @@ const unresolvableKinds = (catalogue, profileContext) => {
         return hash > 0 && loadedProfiles.has(kind.slice(0, hash));
     });
 };
+// The core kind an authored kind resolves to, or undefined when this workspace
+// cannot resolve it at all. Lineage is ancestor-first, so `lineage[0]` is the
+// core identity and an extension inherits its parent's row in the table
+// (ADR 0097); a core kind is its own lineage head. This is also why
+// `kindMatching: descendants` needs no special handling: a descendant shares
+// its ancestor's row and column, so checking the named kind covers them all.
+// A kind the table has no row for answers every query with an empty set,
+// which reads exactly like "forbidden". The guards keep the two apart, so a
+// vocabulary the table cannot judge is passed over in silence rather than
+// accused - the direction every ambiguity here resolves in. They are the
+// reason nothing below casts: the typed queries are reached through the
+// check rather than around it.
+const localKindOf = (kind, lineages) => {
+    const lineage = lineages.get(kind);
+    if (lineage === undefined)
+        return undefined;
+    const identity = lineage[0] ?? kind;
+    return identity.slice(identity.indexOf('#') + 1);
+};
+const coreConceptKindOf = (kind, lineages) => {
+    const local = localKindOf(kind, lineages);
+    return local !== undefined && tableKnowsConceptKind(local) ? local : undefined;
+};
+const coreRelationshipKindOf = (kind, lineages) => {
+    const local = localKindOf(kind, lineages);
+    return local !== undefined && tableKnowsRelationshipKind(local)
+        ? local
+        : undefined;
+};
+/**
+ * Remedies a trigger offers that no model could author.
+ *
+ * A trigger names the ways its question can be satisfied, and each one is an
+ * OFFER: add this relationship, in this direction, from one of these kinds.
+ * The ArchiMate table the compiler admits relationships against decides which
+ * of those are authorable. An offer it forbids is a lie the catalogue tells,
+ * and the unit is the offer rather than the question, because a question with
+ * three offers and one dead one still reads as answerable: a reader takes the
+ * dead option, authors it, and the compiler refuses the write (ADR 0133).
+ *
+ * Both conditions naming a relationship are checked, and `missing-linkage` is
+ * the MORE checkable of the two. `missing-relationship` asks whether any of
+ * the 62 core kinds may stand opposite, which only the seven kinds nothing may
+ * realize can fail. `missing-linkage` names its own counterpart kinds, so the
+ * question narrows to those, a dead offer is far likelier, and the diagnostic
+ * can point at the exact list that admits nothing. Both of the defects that
+ * prompted this check in the reporting consumer's catalogue were linkage
+ * offers, not relationship ones.
+ *
+ * `missing-attestation` and `missing-claim` are not checked: they name no
+ * relationship, so there is no table to consult, and inventing one for them
+ * would be the second encoding of ArchiMate's rules this check exists to
+ * prevent.
+ *
+ * Narrow in the same two ways `unresolvableKinds` is narrow. Without a profile
+ * context there is no lineage to resolve an extension kind through, so nothing
+ * is reported rather than guessed; and a kind that resolves nowhere is
+ * `YM914`'s business, not this one. A trigger with any unresolvable counterpart
+ * is skipped whole, because a partial reading could accuse a question that a
+ * dormant cross-profile kind would have answered.
+ */
+const unauthorableOffers = (catalogue, profileContext) => {
+    const found = [];
+    const conceptCore = (kind) => coreConceptKindOf(kind, profileContext.conceptKindLineages);
+    for (const [questionIndex, question] of catalogue.questions.entries()) {
+        const subjectKinds = question.subjects?.kinds ?? [];
+        if (subjectKinds.length === 0)
+            continue;
+        for (const [conditionIndex, condition] of question.trigger.entries()) {
+            const trigger = condition;
+            if (trigger.condition !== 'missing-relationship' &&
+                trigger.condition !== 'missing-linkage') {
+                continue;
+            }
+            // `any` and `either` are satisfied by a relationship in either
+            // direction, so an offer is dead only when both directions are.
+            const directions = trigger.direction === 'any' || trigger.direction === 'either'
+                ? ['incoming', 'outgoing']
+                : [trigger.direction ?? 'any'];
+            const named = trigger.counterpartKinds;
+            const counterparts = named?.map(conceptCore);
+            if (counterparts?.some((kind) => kind === undefined) === true)
+                continue;
+            for (const subjectKind of subjectKinds) {
+                const subject = conceptCore(subjectKind);
+                if (subject === undefined)
+                    continue;
+                for (const [kindIndex, relationshipKind] of (trigger.kinds ?? []).entries()) {
+                    const relationship = coreRelationshipKindOf(relationshipKind, profileContext.relationshipKindLineages);
+                    if (relationship === undefined)
+                        continue;
+                    const authorable = directions.some((direction) => {
+                        const opposite = direction === 'incoming'
+                            ? sourceKindsPermitting(relationship, subject)
+                            : targetKindsPermitting(relationship, subject);
+                        return counterparts === undefined
+                            ? opposite.size > 0
+                            : counterparts.some((kind) => kind !== undefined && opposite.has(kind));
+                    });
+                    if (authorable)
+                        continue;
+                    found.push({
+                        questionId: question.id,
+                        subjectKind,
+                        relationshipKind,
+                        direction: trigger.direction ?? 'any',
+                        counterpartKinds: named,
+                        path: [
+                            'questions',
+                            questionIndex,
+                            'trigger',
+                            conditionIndex,
+                            'kinds',
+                            kindIndex,
+                        ],
+                    });
+                }
+            }
+        }
+    }
+    return found;
+};
 const loadCatalogueDocument = (catalogueSource) => {
     const loaded = loadSourceDocument(catalogueSource, validateCatalogue, 'Question catalogue');
     if (!loaded.ok)
@@ -693,6 +825,25 @@ profileContext === undefined
         message: `Kind "${reference.kind}" is not declared by profile "${reference.kind.slice(0, reference.kind.indexOf('#'))}", which this workspace loads, so the question can never fire`,
         ...locate(reference.path),
     }));
+// YM916, the sibling of YM914. YM914 refuses a question that can never FIRE;
+// this refuses one that offers a remedy nobody could author. Both failures are
+// invisible, and this one twice over: the question reads as ordinary
+// unfinished work, and a reader who takes the dead offer learns only when the
+// compiler refuses the write it led them to (ADR 0133).
+const unauthorableOfferDiagnostics = ({ catalogue, locate }, profileContext) => profileContext === undefined
+    ? []
+    : unauthorableOffers(catalogue, profileContext).map((offer) => ({
+        severity: 'error',
+        code: 'YM916',
+        message: `Question "${offer.questionId}" offers "${offer.relationshipKind}" ` +
+            `${offer.direction} on "${offer.subjectKind}", which the ` +
+            'ArchiMate relationship table permits from ' +
+            (offer.counterpartKinds === undefined
+                ? 'no kind at all'
+                : `none of the counterpart kinds it names (${offer.counterpartKinds.join(', ')})`) +
+            ', so no model could author it',
+        ...locate(offer.path),
+    }));
 /**
  * A catalogue is qualified on the way OUT, never in what an author writes.
  *
@@ -801,6 +952,7 @@ export function composeCatalogues(sources, profileContext) {
     const crossDiagnostics = documents.flatMap((document) => [
         ...undeclaredWaveDiagnostics(document, declaredWaves),
         ...unresolvableKindDiagnostics(document, profileContext),
+        ...unauthorableOfferDiagnostics(document, profileContext),
     ]);
     if (crossDiagnostics.length > 0) {
         return { ok: false, diagnostics: crossDiagnostics };
@@ -837,6 +989,10 @@ export function loadQuestionCatalogue(catalogueSource, profileContext) {
     if (kindDiagnostics.length > 0) {
         return { ok: false, diagnostics: kindDiagnostics };
     }
+    const offerDiagnostics = unauthorableOfferDiagnostics(loaded.document, profileContext);
+    if (offerDiagnostics.length > 0) {
+        return { ok: false, diagnostics: offerDiagnostics };
+    }
     return { ok: true, catalogue: loaded.document.catalogue };
 }
 // Shared by interrogate and `ask --open`: the wave-by-wave human report.
@@ -859,6 +1015,13 @@ export function renderInterrogationReport(report) {
             continue;
         }
         for (const question of wave.questions) {
+            if (question.asked === false) {
+                // Never asked is not closed (#375): `closed` says answered, and a
+                // selector that matched nobody asked nothing — the question-level
+                // twin of the wave's own "not yet" line above.
+                lines.push(`  unasked ${question.id} — nothing it selects exists yet`);
+                continue;
+            }
             if (!question.open) {
                 lines.push(`  closed ${question.id}`);
                 continue;

package/dist/relationship-matrix.d.ts

@@ -6,6 +6,8 @@ export declare const isCoreConceptKindId: (id: string) => id is CoreConceptKindI
 export declare const permittedRelationshipKinds: (from: CoreConceptKindId, to: CoreConceptKindId) => ReadonlySet<RelationshipKind>;
 export declare const relationshipPermitted: (from: CoreConceptKindId, kind: RelationshipKind, to: CoreConceptKindId) => boolean;
 export declare const matrixEndpointAspects: (kind: RelationshipKind, endpoint: 'source' | 'target') => ReadonlySet<Aspect>;
+export declare const tableKnowsConceptKind: (kind: string) => kind is CoreConceptKindId;
+export declare const tableKnowsRelationshipKind: (kind: string) => kind is RelationshipKind;
 /** Kinds that may stand as the source of `kind` into `to`. */
 export declare const sourceKindsPermitting: (kind: RelationshipKind, to: CoreConceptKindId) => ReadonlySet<CoreConceptKindId>;
 /** Kinds that may stand as the target of `kind` from `from`. */

package/dist/relationship-matrix.js

@@ -66,6 +66,30 @@ export const matrixEndpointAspects = (kind, endpoint) => {
     endpointAspectCache.set(key, aspects);
     return aspects;
 };
+/**
+ * Whether the table has a row and column for this kind at all.
+ *
+ * Every query below answers an ABSENT kind with an empty set, which reads
+ * identically to "the table forbids this" - the empty-set conflation, in the
+ * one place where mistaking it turns a gate into a false accuser. A caller
+ * deciding whether something is forbidden must therefore ask this first, so
+ * that "not in the table" resolves toward silence rather than toward blame.
+ *
+ * Nothing reachable through a profile should fail it: `parent` is required on
+ * every declared kind and resolves to a core ancestor, so a lineage head is
+ * always a table kind. The predicates exist because that guarantee is another
+ * module's to keep, and a gate should not rest on one silently.
+ *
+ * They are type guards rather than booleans so that a caller holding a bare
+ * string reaches the typed queries through the check instead of around it by
+ * a cast. The cast is where the hole actually opens: the signatures already
+ * refuse an unknown kind, and asserting past them is what lets an absent kind
+ * arrive and be read as a forbidden one.
+ */
+const CORE_CONCEPT_KINDS = new Set(CORE_CONCEPT_KIND_ORDER);
+const CORE_RELATIONSHIP_KIND_SET = new Set(relationshipKinds);
+export const tableKnowsConceptKind = (kind) => CORE_CONCEPT_KINDS.has(kind);
+export const tableKnowsRelationshipKind = (kind) => CORE_RELATIONSHIP_KIND_SET.has(kind);
 /** Kinds that may stand as the source of `kind` into `to`. */
 export const sourceKindsPermitting = (kind, to) => new Set(CORE_CONCEPT_KIND_ORDER.filter((from) => relationshipPermitted(from, kind, to)));
 /** Kinds that may stand as the target of `kind` from `from`. */