yarramate 0.23.0 → 1.0.0

package/dist/compiler.js

@@ -1,6 +1,7 @@
-import { createRequire } from 'node:module';
-import { LineCounter, parseDocument } from 'yaml';
+import Ajv2020Import from 'ajv/dist/2020.js';
+import { LineCounter, parse, parseDocument } from 'yaml';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
+import { isCoreConceptKindId, matrixEndpointAspects, permittedRelationshipKinds as tablePermittedKinds, } from './relationship-matrix.js';
 import { closestCandidate, describeSchemaViolation, } from './source-document.js';
 import documentSchema from '../schema/yarramate-document.schema.json' with { type: 'json'
 };
@@ -9,8 +10,7 @@ import profileSchema from '../schema/yarramate-profile.schema.json' with { type:
 import { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue } from './graph-claims.js';
 import { shippedPolicyIdentity, shippedPolicySource, } from './shipped-profile.js';
 const coreProfile = 'yarramate/core@0.1';
-const require = createRequire(import.meta.url);
-const ajv2020Module = require('ajv/dist/2020.js');
+const ajv2020Module = Ajv2020Import;
 const Ajv2020 = ajv2020Module.default ?? ajv2020Module;
 const validateDocument = new Ajv2020({ allErrors: true }).compile(documentSchema);
 const validateProfile = new Ajv2020({ allErrors: true }).compile(profileSchema);
@@ -33,32 +33,35 @@ const immutableMap = (entries) => {
     return Object.freeze(facade);
 };
 const compareById = (left, right) => left.id.localeCompare(right.id);
-const presenceClaimId = (subject, state) => `${subject}~present-in-${Buffer.from(state, 'utf8').toString('hex')}`;
+const utf8Encoder = new TextEncoder();
+const utf8Hex = (value) => {
+    let hex = '';
+    for (const byte of utf8Encoder.encode(value)) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+};
+const presenceClaimId = (subject, state) => `${subject}~present-in-${utf8Hex(state)}`;
 // Alternative labels and distinctness records are unordered sets, not
 // authored lists with ids. Hex-encoding the value the way presence
 // encodes its state keeps the claim id derived from content rather than
 // position, so reordering the YAML leaves the graph byte-identical.
-const aliasClaimId = (subject, alias) => `${subject}~alias-${Buffer.from(alias, 'utf8').toString('hex')}`;
-const distinctFromClaimId = (subject, other) => `${subject}~distinct-from-${Buffer.from(other, 'utf8').toString('hex')}`;
-const supersedesClaimId = (subject, predecessor) => `${subject}~supersedes-${Buffer.from(predecessor, 'utf8').toString('hex')}`;
+const aliasClaimId = (subject, alias) => `${subject}~alias-${utf8Hex(alias)}`;
+const distinctFromClaimId = (subject, other) => `${subject}~distinct-from-${utf8Hex(other)}`;
+const supersedesClaimId = (subject, predecessor) => `${subject}~supersedes-${utf8Hex(predecessor)}`;
 export { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue, parseAttestationClaimValue, parseConstraintExpectsValue, } from './graph-claims.js';
-const describeAspect = (aspect) => aspect.replace('-', ' ');
-// Candidate order is the policy-matrix declaration order: the resolved kind
-// map inserts core policies first, then extension kinds as declared.
-const candidateKindHint = (kinds, rejected, sourceAspect, targetAspect) => {
-    const candidates = [...kinds]
-        .filter(([id, kind]) => id !== rejected &&
-        (kind.sourceAspects?.includes(sourceAspect) ?? true) &&
-        (kind.targetAspects?.includes(targetAspect) ?? true))
-        .map(([id]) => id);
-    if (candidates.length === 0) {
-        return '';
-    }
-    const observed = sourceAspect === targetAspect
-        ? `both endpoints are ${describeAspect(sourceAspect)}`
-        : `source is ${describeAspect(sourceAspect)} and target is ${describeAspect(targetAspect)}`;
-    return `; ${observed}; valid candidates: ${candidates.join(', ')}`;
-};
+const localKindId = (identity) => identity.slice(identity.indexOf('#') + 1);
+// Candidate order is the resolved kind map's insertion order: core kinds
+// first, then extension kinds as declared. Scoped to the selected profile
+// (ADR 0079), so a profile nobody selected never surfaces here. A candidate
+// has to clear both the table and any narrowing the kind declares, or the
+// suggestion would be the next rejection.
+const permittedCandidates = (kinds, rejected, permitted, sourceAspect, targetAspect) => [...kinds]
+    .filter(([id, kind]) => id !== rejected &&
+    permitted.has(kind.coreKind) &&
+    (kind.sourceAspects?.includes(sourceAspect) ?? true) &&
+    (kind.targetAspects?.includes(targetAspect) ?? true))
+    .map(([id]) => id);
 const diagnosticFailure = (diagnostics) => ({
     ok: false,
     diagnostics: [...diagnostics].sort((left, right) => left.path.localeCompare(right.path) ||
@@ -199,6 +202,60 @@ const parseSources = (sources, previous) => {
     });
     return { parsed, cache: { sources: entries }, reused };
 };
+// Resolves each diagnostic's subject from the pointer it already carries, so
+// the rules themselves stay unchanged and no construction site has to remember
+// to name what it refused.
+//
+// A pointer into a document reads `/concepts/<n>/...` or
+// `/relationships/<n>/...`, and `<n>` indexes the authored array, so the id is
+// one lookup away in the same parsed value the diagnostic was located against.
+// Pointers are positional - inserting a concept shifts every index below it -
+// which is exactly why this is done here, against the parse that produced the
+// diagnostic, rather than by a consumer against whatever it holds later.
+//
+// Anything else keeps no subjects: a parse failure, a whole-document schema
+// violation, a manifest, a projection's own definition. That absence is the
+// signal a consumer needs, so it is left empty rather than guessed at.
+const subjectsForPointer = (pointer, documentValue) => {
+    const match = /^\/(concepts|relationships)\/(\d+)(?:\/|$)/.exec(pointer);
+    if (match === null)
+        return [];
+    const value = documentValue;
+    const documentId = typeof value?.id === 'string' ? value.id : undefined;
+    if (documentId === undefined)
+        return [];
+    const items = value?.[match[1]];
+    if (!Array.isArray(items))
+        return [];
+    const item = items[Number(match[2])];
+    return typeof item?.id === 'string' ? [item.id] : [];
+};
+export const withDiagnosticSubjects = (diagnostics, sources) => {
+    if (diagnostics.length === 0)
+        return diagnostics;
+    // Only the documents something was actually said about are parsed, and each
+    // at most once: a clean workspace pays nothing, and a workspace refused on
+    // one document does not pay for the rest.
+    const wanted = new Set(diagnostics.map((diagnostic) => diagnostic.path));
+    const valueByPath = new Map();
+    for (const source of sources) {
+        if (!wanted.has(source.path))
+            continue;
+        try {
+            valueByPath.set(source.path, parse(source.source));
+        }
+        catch {
+            // A source that will not parse is exactly one whose diagnostics belong
+            // to no subject, so failing to read it here is the right answer.
+        }
+    }
+    return diagnostics.map((diagnostic) => {
+        if (diagnostic.subjects !== undefined)
+            return diagnostic;
+        const subjects = subjectsForPointer(diagnostic.pointer, valueByPath.get(diagnostic.path));
+        return subjects.length === 0 ? diagnostic : { ...diagnostic, subjects };
+    });
+};
 function compileWorkspaceResolved(parsed) {
     const profileInputs = [];
     const documentInputs = [];
@@ -230,9 +287,7 @@ function compileWorkspaceResolved(parsed) {
         const resolved = {
             identity: `${coreProfile}#${policy.id}`,
             lineage: [`${coreProfile}#${policy.id}`],
-            sourceAspects: policy.sourceAspects,
-            targetAspects: policy.targetAspects,
-            repair: policy.repair,
+            coreKind: policy.id,
         };
         coreRelationshipKinds.set(policy.id, resolved);
         relationshipKindByIdentity.set(resolved.identity, resolved);
@@ -441,9 +496,12 @@ function compileWorkspaceResolved(parsed) {
                 for (const endpoint of ['source', 'target']) {
                     const field = `${endpoint}Aspects`;
                     const declared = kind[field];
-                    const inherited = parent[field];
+                    // A parent that declares no narrowing is bounded by the table:
+                    // an extension may not admit an aspect its core ancestor can never
+                    // carry at that end.
+                    const inherited = parent[field] ??
+                        [...matrixEndpointAspects(parent.coreKind, endpoint)];
                     if (declared !== undefined &&
-                        inherited !== undefined &&
                         declared.some((aspect) => !inherited.includes(aspect))) {
                         const position = positionFor([
                             'relationshipKinds',
@@ -468,6 +526,7 @@ function compileWorkspaceResolved(parsed) {
                 const resolved = {
                     identity: `${identity}#${kind.id}`,
                     lineage: [...parent.lineage, `${identity}#${kind.id}`],
+                    coreKind: parent.coreKind,
                     sourceAspects: kind.sourceAspects ?? parent.sourceAspects,
                     targetAspects: kind.targetAspects ?? parent.targetAspects,
                 };
@@ -547,25 +606,29 @@ function compileWorkspaceResolved(parsed) {
         seenDocumentIds.add(value.id);
     }
     const conceptByQualifiedId = new Map(documents.flatMap(({ value }) => value.concepts.map((concept) => [
-        `${value.id}#${concept.id}`,
+        concept.id,
         {
             concept,
             profile: value.profile,
             document: value.id,
         },
     ])));
-    const qualifyReference = (documentId, reference) => reference.includes('#') ? reference : `${documentId}#${reference}`;
-    const architectureStateIds = new Set(documents.flatMap(({ value }) => (value.states ?? []).map((state) => `${value.id}#${state.id}`)));
+    // Subject identity is the authored id, unique across the workspace, so a
+    // reference resolves as written. Kept as a named step rather than inlined
+    // because every reference in the model passes through here, and that is
+    // where a future scheme would hook.
+    const qualifyReference = (_documentId, reference) => reference;
+    const architectureStateIds = new Set(documents.flatMap(({ value }) => (value.states ?? []).map((state) => state.id)));
     const subjectIds = new Set(documents.flatMap(({ value }) => [
-        ...(value.states ?? []).map((state) => `${value.id}#${state.id}`),
-        ...value.concepts.map((concept) => `${value.id}#${concept.id}`),
-        ...value.relationships.map((relationship) => `${value.id}#${relationship.id}`),
+        ...(value.states ?? []).map((state) => state.id),
+        ...value.concepts.map((concept) => concept.id),
+        ...value.relationships.map((relationship) => relationship.id),
     ]));
     const architectureStateAfter = new Map(documents.flatMap(({ value }) => (value.states ?? []).flatMap((state) => state.after === undefined
         ? []
         : [
             [
-                `${value.id}#${state.id}`,
+                state.id,
                 qualifyReference(value.id, state.after),
             ],
         ])));
@@ -589,7 +652,7 @@ function compileWorkspaceResolved(parsed) {
         ? []
         : [
             [
-                `${value.id}#${concept.id}`,
+                concept.id,
                 concept.supersedes.map((predecessor) => qualifyReference(value.id, predecessor)),
             ],
         ])));
@@ -612,6 +675,14 @@ function compileWorkspaceResolved(parsed) {
         }
         return false;
     };
+    // Subject identity is the authored id and carries no document prefix, so an
+    // id declared twice anywhere in the workspace names one subject twice. The
+    // walk below therefore remembers across documents, not just within one.
+    const declaringDocument = new Map();
+    // A document whose own id is a duplicate (YM303) would collide on every
+    // subject it declares, burying the one fault worth acting on under a
+    // diagnostic per concept. It is walked for nothing else here.
+    const documentIdsSeen = new Set();
     for (const { input, value, location } of documents) {
         const selectedProfile = profiles.get(value.profile);
         if (selectedProfile === undefined) {
@@ -627,7 +698,6 @@ function compileWorkspaceResolved(parsed) {
             });
             continue;
         }
-        const seenIds = new Set();
         const declarations = [
             ...(value.states ?? []).map((state, index) => ({
                 id: state.id,
@@ -645,23 +715,36 @@ function compileWorkspaceResolved(parsed) {
                 pointer: `/relationships/${index}/id`,
             })),
         ];
+        const duplicateDocumentId = documentIdsSeen.has(value.id);
+        documentIdsSeen.add(value.id);
         for (const declaration of declarations) {
-            if (seenIds.has(declaration.id)) {
+            if (duplicateDocumentId)
+                break;
+            const firstDeclarer = declaringDocument.get(declaration.id);
+            if (firstDeclarer !== undefined) {
                 const source = location(declaration.yamlPath, declaration.pointer);
+                // Two documents claiming one id is a different fault from one document
+                // repeating itself, and it reads differently to whoever has to fix it:
+                // the second names a file they may not have open.
+                const sameDocument = firstDeclarer === input.path;
                 diagnostics.push({
                     severity: 'error',
-                    code: 'YM301',
-                    message: `Duplicate local ID "${declaration.id}"`,
+                    code: sameDocument ? 'YM301' : 'YM314',
+                    message: sameDocument
+                        ? `Duplicate ID "${declaration.id}"`
+                        : `ID "${declaration.id}" is already declared by "${firstDeclarer}"; a subject id is unique across the workspace`,
                     path: input.path,
                     pointer: declaration.pointer,
                     line: source.line,
                     column: source.column,
                 });
             }
-            seenIds.add(declaration.id);
+            else {
+                declaringDocument.set(declaration.id, input.path);
+            }
         }
         for (const [index, state] of (value.states ?? []).entries()) {
-            const stateIdentity = `${value.id}#${state.id}`;
+            const stateIdentity = state.id;
             if (state.after !== undefined &&
                 !architectureStateIds.has(qualifyReference(value.id, state.after))) {
                 const pointer = `/states/${index}/after`;
@@ -692,7 +775,7 @@ function compileWorkspaceResolved(parsed) {
             }
         }
         for (const [index, state] of (value.states ?? []).entries()) {
-            const subject = `${value.id}#${state.id}`;
+            const subject = state.id;
             subjects.push({ id: subject, type: 'concept' });
             claims.push({
                 id: `${subject}~kind`,
@@ -787,7 +870,7 @@ function compileWorkspaceResolved(parsed) {
                         column: source.column,
                     });
                 }
-                else if (otherIdentity === `${value.id}#${concept.id}`) {
+                else if (otherIdentity === concept.id) {
                     const source = location(['concepts', index, 'distinctFrom', distinctIndex], pointer);
                     diagnostics.push({
                         severity: 'error',
@@ -803,7 +886,7 @@ function compileWorkspaceResolved(parsed) {
             for (const [supersedesIndex, predecessor] of (concept.supersedes ?? []).entries()) {
                 const pointer = `/concepts/${index}/supersedes/${supersedesIndex}`;
                 const predecessorIdentity = qualifyReference(value.id, predecessor);
-                const subjectIdentity = `${value.id}#${concept.id}`;
+                const subjectIdentity = concept.id;
                 if (!conceptByQualifiedId.has(predecessorIdentity)) {
                     const source = location(['concepts', index, 'supersedes', supersedesIndex], pointer);
                     diagnostics.push({
@@ -1046,7 +1129,24 @@ function compileWorkspaceResolved(parsed) {
                     diagnostics.push({
                         severity: 'error',
                         code: 'YM302',
-                        message: `Unresolved concept reference "${reference}"`,
+                        message: `Unresolved concept reference "${reference}"${(() => {
+                            // A reference written the way ids read before 1.0 flattened them
+                            // (ADR 0099) is not a typo, and the edit distance from
+                            // `<document>#<local>` to `<local>` is usually past the
+                            // suggestion threshold, so it would otherwise get no hint at all
+                            // on the one change most likely to produce it.
+                            const hash = reference.lastIndexOf('#');
+                            if (hash !== -1) {
+                                const local = reference.slice(hash + 1);
+                                if (conceptByQualifiedId.has(qualifyReference(value.id, local))) {
+                                    return `; a subject id carries no document prefix since 1.0, and "${local}" exists`;
+                                }
+                            }
+                            const suggestion = closestCandidate(reference, [...conceptByQualifiedId.keys()]);
+                            return suggestion === undefined
+                                ? ''
+                                : `; did you mean "${suggestion}"?`;
+                        })()}`,
                         path: input.path,
                         pointer,
                         line: source.line,
@@ -1056,46 +1156,82 @@ function compileWorkspaceResolved(parsed) {
             }
             const policy = selectedProfile.relationshipKinds.get(relationship.kind);
             if (policy !== undefined) {
-                const aspectOf = (reference) => {
+                // Each endpoint resolves to the core kind its declared kind descends
+                // from: the ArchiMate relationship table is defined over core kinds,
+                // and an extension inherits its parent's row and column (ADR 0097).
+                const endpointKind = (reference) => {
                     const resolvedConcept = conceptByQualifiedId.get(qualifyReference(value.id, reference));
-                    return resolvedConcept === undefined
-                        ? undefined
-                        : profiles
-                            .get(resolvedConcept.profile)
-                            ?.conceptKinds.get(resolvedConcept.concept.kind)?.aspect;
+                    if (resolvedConcept === undefined)
+                        return undefined;
+                    const resolvedKind = profiles
+                        .get(resolvedConcept.profile)
+                        ?.conceptKinds.get(resolvedConcept.concept.kind);
+                    if (resolvedKind === undefined)
+                        return undefined;
+                    const core = localKindId(resolvedKind.lineage[0] ?? resolvedKind.identity);
+                    return isCoreConceptKindId(core)
+                        ? { declared: resolvedConcept.concept.kind, core, aspect: resolvedKind.aspect }
+                        : undefined;
                 };
-                const sourceAspect = aspectOf(relationship.from);
-                const targetAspect = aspectOf(relationship.to);
-                const candidates = sourceAspect === undefined || targetAspect === undefined
-                    ? ''
-                    : candidateKindHint(selectedProfile.relationshipKinds, relationship.kind, sourceAspect, targetAspect);
-                for (const endpoint of ['source', 'target']) {
-                    const reference = endpoint === 'source' ? relationship.from : relationship.to;
-                    const aspect = endpoint === 'source' ? sourceAspect : targetAspect;
-                    const allowed = endpoint === 'source'
-                        ? policy.sourceAspects
-                        : policy.targetAspects;
-                    if (aspect !== undefined &&
-                        allowed !== undefined &&
-                        !allowed.includes(aspect)) {
-                        const field = endpoint === 'source' ? 'from' : 'to';
-                        const pointer = `/relationships/${index}/${field}`;
-                        const source = location(['relationships', index, field], pointer);
+                const from = endpointKind(relationship.from);
+                const to = endpointKind(relationship.to);
+                // An unresolved endpoint was already reported as YM302; nothing more
+                // can be said about a pair that does not exist.
+                if (from !== undefined && to !== undefined) {
+                    const permitted = tablePermittedKinds(from.core, to.core);
+                    const describe = (endpoint) => endpoint.declared === endpoint.core
+                        ? endpoint.core
+                        : `${endpoint.declared}, a ${endpoint.core}`;
+                    const candidates = permittedCandidates(selectedProfile.relationshipKinds, relationship.kind, permitted, from.aspect, to.aspect);
+                    const tail = candidates.length === 0
+                        ? ''
+                        : `; ArchiMate 3.2 permits: ${candidates.join(', ')}`;
+                    if (!permitted.has(policy.coreKind)) {
+                        const pointer = `/relationships/${index}/kind`;
+                        const source = location(['relationships', index, 'kind'], pointer);
+                        const kindLabel = relationship.kind === policy.coreKind
+                            ? `"${relationship.kind}"`
+                            : `"${relationship.kind}" (${policy.coreKind})`;
                         diagnostics.push({
                             severity: 'error',
                             code: 'YM404',
-                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((entry) => `"${entry}"`).join(' or ')}; "${reference}" has aspect "${aspect}"${policy.repair === undefined ? '' : `; ${policy.repair}`}${candidates}`,
+                            message: `Relationship ${kindLabel} is not permitted from "${relationship.from}" (${describe(from)}) to "${relationship.to}" (${describe(to)})${tail}`,
                             path: input.path,
                             pointer,
                             line: source.line,
                             column: source.column,
                         });
                     }
+                    else {
+                        // The table permits the pair; an extension kind may still
+                        // narrow it by aspect, and that narrowing is reported per end.
+                        for (const endpoint of ['source', 'target']) {
+                            const reference = endpoint === 'source' ? relationship.from : relationship.to;
+                            const aspect = endpoint === 'source' ? from.aspect : to.aspect;
+                            const allowed = endpoint === 'source'
+                                ? policy.sourceAspects
+                                : policy.targetAspects;
+                            if (allowed !== undefined && !allowed.includes(aspect)) {
+                                const field = endpoint === 'source' ? 'from' : 'to';
+                                const pointer = `/relationships/${index}/${field}`;
+                                const source = location(['relationships', index, field], pointer);
+                                diagnostics.push({
+                                    severity: 'error',
+                                    code: 'YM404',
+                                    message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((entry) => `"${entry}"`).join(' or ')}; "${reference}" has aspect "${aspect}"${tail}`,
+                                    path: input.path,
+                                    pointer,
+                                    line: source.line,
+                                    column: source.column,
+                                });
+                            }
+                        }
+                    }
                 }
             }
         }
         for (const [index, concept] of value.concepts.entries()) {
-            const subject = `${value.id}#${concept.id}`;
+            const subject = concept.id;
             subjects.push({ id: subject, type: 'concept' });
             claims.push({
                 id: `${subject}~kind`,
@@ -1190,6 +1326,20 @@ function compileWorkspaceResolved(parsed) {
                     source: location(['concepts', index, 'owner'], `/concepts/${index}/owner`),
                 });
             }
+            if (concept.folder !== undefined) {
+                claims.push({
+                    id: `${subject}~folder`,
+                    subject,
+                    predicate: 'yarramate/organisation/folder',
+                    // A VALUE, not a ref. A folder is a label the author writes, not a
+                    // subject the workspace declares: nothing can be said about it, it
+                    // resolves to nothing, and two documents writing the same label mean
+                    // the same folder without either naming the other (ADR 0104).
+                    object: { value: concept.folder },
+                    origin: 'declared',
+                    source: location(['concepts', index, 'folder'], `/concepts/${index}/folder`),
+                });
+            }
             for (const [constraintIndex, constraint] of (concept.constraints ?? []).entries()) {
                 claims.push({
                     id: `${subject}~constraint-${constraint.id}`,
@@ -1289,7 +1439,7 @@ function compileWorkspaceResolved(parsed) {
             }
         }
         for (const [index, relationship] of value.relationships.entries()) {
-            const id = `${value.id}#${relationship.id}`;
+            const id = relationship.id;
             subjects.push({ id, type: 'relationship' });
             claims.push({
                 id,
@@ -1381,7 +1531,7 @@ function compileWorkspaceResolved(parsed) {
         relationship.kind === 'aggregation'
         ? [
             {
-                id: `${value.id}#${relationship.id}`,
+                id: relationship.id,
                 localId: relationship.id,
                 document: value.id,
                 kind: relationship.kind,
@@ -1420,6 +1570,72 @@ function compileWorkspaceResolved(parsed) {
         previousRelationships.push(relationship);
         wholePartByEndpoints.set(endpointKey, previousRelationships);
     }
+    // A junction takes the kind of the relationships that pass through it, so
+    // every relationship on one junction must be the same kind (ArchiMate 3.2,
+    // junctions). The table cannot say this: it rules on one pair at a time,
+    // and this is a property of the set. Sorted by id, so the first-listed
+    // relationship's kind is the one the others are measured against and the
+    // diagnostic lands on the later ones.
+    const junctionKinds = new Set([
+        'andJunction',
+        'orJunction',
+    ]);
+    const junctionRelationships = documents
+        .flatMap(({ value, location }) => value.relationships.flatMap((relationship, index) => {
+        const policy = profiles
+            .get(value.profile)
+            ?.relationshipKinds.get(relationship.kind);
+        if (policy === undefined)
+            return [];
+        return ['from', 'to'].flatMap((endpoint) => {
+            const junction = qualifyReference(value.id, relationship[endpoint]);
+            const resolvedConcept = conceptByQualifiedId.get(junction);
+            const resolvedKind = resolvedConcept === undefined
+                ? undefined
+                : profiles
+                    .get(resolvedConcept.profile)
+                    ?.conceptKinds.get(resolvedConcept.concept.kind);
+            if (resolvedKind === undefined ||
+                !junctionKinds.has(localKindId(resolvedKind.lineage[0] ?? resolvedKind.identity))) {
+                return [];
+            }
+            return [
+                {
+                    id: relationship.id,
+                    localId: relationship.id,
+                    junction,
+                    kind: relationship.kind,
+                    coreKind: policy.coreKind,
+                    source: location(['relationships', index, 'kind'], `/relationships/${index}/kind`),
+                },
+            ];
+        });
+    }))
+        .sort(compareById);
+    const relationshipsByJunction = new Map();
+    for (const entry of junctionRelationships) {
+        const group = relationshipsByJunction.get(entry.junction) ?? [];
+        group.push(entry);
+        relationshipsByJunction.set(entry.junction, group);
+    }
+    for (const [junction, group] of relationshipsByJunction) {
+        const expected = group[0]?.coreKind;
+        if (expected === undefined)
+            continue;
+        for (const entry of group) {
+            if (entry.coreKind === expected)
+                continue;
+            diagnostics.push({
+                severity: 'error',
+                code: 'YM414',
+                message: `Relationship "${entry.localId}" (${entry.kind}) joins junction "${junction}" whose relationships are "${expected}"; every relationship on one junction must be the same kind`,
+                path: entry.source.path,
+                pointer: entry.source.pointer,
+                line: entry.source.line,
+                column: entry.source.column,
+            });
+        }
+    }
     if (diagnostics.length > 0) {
         return diagnosticFailure(diagnostics);
     }
@@ -1449,14 +1665,38 @@ function compileWorkspaceResolved(parsed) {
                 .map(([identity, kind]) => [
                 identity,
                 Object.freeze({
-                    ...(kind.sourceAspects === undefined
-                        ? {}
-                        : { source: Object.freeze([...kind.sourceAspects]) }),
-                    ...(kind.targetAspects === undefined
-                        ? {}
-                        : { target: Object.freeze([...kind.targetAspects]) }),
+                    source: Object.freeze([
+                        ...(kind.sourceAspects ??
+                            matrixEndpointAspects(kind.coreKind, 'source')),
+                    ]),
+                    target: Object.freeze([
+                        ...(kind.targetAspects ??
+                            matrixEndpointAspects(kind.coreKind, 'target')),
+                    ]),
                 }),
             ])),
+            conceptKindCoreAncestors: immutableMap([...conceptKindByIdentity]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .flatMap(([identity, kind]) => {
+                const core = localKindId(kind.lineage[0] ?? identity);
+                return isCoreConceptKindId(core)
+                    ? [[identity, core]]
+                    : [];
+            })),
+            relationshipKindCoreAncestors: immutableMap([...relationshipKindByIdentity]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([identity, kind]) => [identity, kind.coreKind])),
+            permittedRelationshipKinds: (fromKindIdentity, toKindIdentity) => {
+                const from = conceptKindByIdentity.get(fromKindIdentity);
+                const to = conceptKindByIdentity.get(toKindIdentity);
+                if (from === undefined || to === undefined)
+                    return undefined;
+                const fromCore = localKindId(from.lineage[0] ?? from.identity);
+                const toCore = localKindId(to.lineage[0] ?? to.identity);
+                return isCoreConceptKindId(fromCore) && isCoreConceptKindId(toCore)
+                    ? tablePermittedKinds(fromCore, toCore)
+                    : undefined;
+            },
         },
         graph: {
             format: 'yarramate/graph/v2',

package/dist/concept-drafting.d.ts

@@ -0,0 +1,27 @@
+import type { CanvasGraph } from './graph-projection.js';
+import type { YarramateOperation } from './operations.js';
+/**
+ * A kebab-case id derived from a name, unique across the graph, or `null` when
+ * the name yields nothing an id may be made of.
+ *
+ * Deriving rather than asking is the point: an id is a stable address a human
+ * reads in a diff, and asking a reviewer to invent one while they are thinking
+ * 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.
+ */
+export declare const proposeConceptId: (graph: CanvasGraph, name: string) => string | null;
+/**
+ * The operation that lands a new subject, or `null` when the draft is one no
+ * document could accept.
+ *
+ * `kinds` is the vocabulary the workspace's profile actually offers. Refusing
+ * 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.
+ */
+export declare const draftConcept: (graph: CanvasGraph, input: {
+    readonly name: string;
+    readonly kind: string;
+    readonly document: string;
+}, kinds: readonly string[]) => YarramateOperation | null;