yarramate 1.2.0 → 1.4.0

package/dist/compiler.js

@@ -7,6 +7,8 @@ import documentSchema from '../schema/yarramate-document.schema.json' with { typ
 };
 import profileSchema from '../schema/yarramate-profile.schema.json' with { type: 'json'
 };
+import patternSchema from '../schema/yarramate-pattern.schema.json' with { type: 'json'
+};
 import { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue } from './graph-claims.js';
 import { shippedPolicyIdentity, shippedPolicySource, } from './shipped-profile.js';
 const coreProfile = 'yarramate/core@0.1';
@@ -14,6 +16,7 @@ const ajv2020Module = Ajv2020Import;
 const Ajv2020 = ajv2020Module.default ?? ajv2020Module;
 const validateDocument = new Ajv2020({ allErrors: true }).compile(documentSchema);
 const validateProfile = new Ajv2020({ allErrors: true }).compile(profileSchema);
+const validatePattern = new Ajv2020({ allErrors: true }).compile(patternSchema);
 const immutableMap = (entries) => {
     const backing = new Map(entries);
     const facade = {
@@ -133,6 +136,18 @@ const parseWorkspaceSource = (input) => {
     // Classification reads the composed mapping through the YAML document, which
     // types the lookup as `unknown` - the same key the old probe pass read.
     const fresh = { yaml, lineCounter };
+    if (yaml.get('format') === 'yarramate/pattern/v1') {
+        return {
+            entry: {
+                source: input.source,
+                kind: 'pattern',
+                value,
+                schemaDiagnostics: parseDiagnostics,
+                positions: new Map(),
+            },
+            fresh,
+        };
+    }
     if (yaml.get('format') === 'yarramate/profile/v1') {
         return {
             entry: {
@@ -260,11 +275,15 @@ export const withDiagnosticSubjects = (diagnostics, sources) => {
 };
 function compileWorkspaceResolved(parsed) {
     const profileInputs = [];
+    const patternInputs = [];
     const documentInputs = [];
     for (const source of parsed) {
         if (source.entry.kind === 'profile') {
             profileInputs.push(source);
         }
+        else if (source.entry.kind === 'pattern') {
+            patternInputs.push(source);
+        }
         else {
             documentInputs.push(source);
         }
@@ -563,6 +582,268 @@ function compileWorkspaceResolved(parsed) {
     if (profileDiagnostics.length > 0) {
         return diagnosticFailure(profileDiagnostics);
     }
+    /**
+     * Which core relationship kinds the vendored 3.2 table permits between two
+     * resolved concept kinds, or `undefined` where either side is an extension
+     * whose core ancestor is not a core kind. The same rule `profileContext`
+     * publishes below; needed here because a pattern's legality is decided
+     * before any document is read.
+     */
+    const permittedBetween = (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)
+            ? new Set(tablePermittedKinds(fromCore, toCore))
+            : undefined;
+    };
+    // ---- structural patterns (#268, ADR 0123) --------------------------------
+    //
+    // Resolved here, after the profiles they name and before the documents that
+    // instantiate them. A pattern declares the shape a kind promises: the slots
+    // an instance binds and the wiring the compiler mints between them. Faults
+    // in the pattern itself are reported ONCE, against the pattern, rather than
+    // once per instance - including whether the wiring it describes is legal
+    // ArchiMate at all, which is a property of the slot kinds and so knowable
+    // without any instance.
+    const patternDiagnostics = [];
+    const patternsByKind = new Map();
+    for (const { input, entry, fresh } of patternInputs) {
+        const value = entry.value;
+        const positionFor = positionReader(input.source, entry.positions, fresh);
+        const at = (yamlPath, pointer) => {
+            const position = positionFor(yamlPath);
+            return {
+                path: input.path,
+                pointer,
+                line: position.line,
+                column: position.col,
+            };
+        };
+        if (entry.schemaDiagnostics.length > 0) {
+            patternDiagnostics.push(...entry.schemaDiagnostics);
+            continue;
+        }
+        if (!validatePattern(value)) {
+            for (const error of validatePattern.errors ?? []) {
+                const property = error.keyword === 'additionalProperties'
+                    ? String(error.params.additionalProperty)
+                    : undefined;
+                const pointer = property
+                    ? `${error.instancePath}/${property}`
+                    : error.instancePath || '/';
+                const yamlPath = pointer
+                    .split('/')
+                    .slice(1)
+                    .map((segment) => (/^\d+$/.test(segment) ? Number(segment) : segment));
+                patternDiagnostics.push({
+                    severity: 'error',
+                    code: 'YM201',
+                    message: describeSchemaViolation(error),
+                    ...at(yamlPath, pointer),
+                });
+            }
+            continue;
+        }
+        for (const [index, pattern] of value.patterns.entries()) {
+            const anchor = conceptKindByIdentity.get(pattern.kind);
+            if (anchor === undefined) {
+                patternDiagnostics.push({
+                    severity: 'error',
+                    code: 'YM401',
+                    message: `Concept kind "${pattern.kind}" is not available to this pattern`,
+                    ...at(['patterns', index, 'kind'], `/patterns/${index}/kind`),
+                });
+                continue;
+            }
+            const existing = patternsByKind.get(pattern.kind);
+            if (existing !== undefined) {
+                patternDiagnostics.push({
+                    severity: 'error',
+                    code: 'YM411',
+                    message: `Concept kind "${pattern.kind}" already has a pattern, declared by "${existing.declaredBy}"; a kind has at most one shape`,
+                    ...at(['patterns', index, 'kind'], `/patterns/${index}/kind`),
+                });
+                continue;
+            }
+            const slots = new Map();
+            let slotsOk = true;
+            for (const [slot, part] of Object.entries(pattern.parts)) {
+                const kind = conceptKindByIdentity.get(part.kind);
+                if (kind === undefined) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM401',
+                        message: `Concept kind "${part.kind}" is not available to the "${slot}" part`,
+                        ...at(['patterns', index, 'parts', slot, 'kind'], `/patterns/${index}/parts/${slot}/kind`),
+                    });
+                    slotsOk = false;
+                    continue;
+                }
+                slots.set(slot, {
+                    name: slot,
+                    kindIdentity: kind.identity,
+                    required: part.required === true,
+                });
+            }
+            if (!slotsOk)
+                continue;
+            // `self` is the instance, so it is spelled apart from the slots and can
+            // never be one: a slot named `self` would make the wiring ambiguous
+            // about which end it meant.
+            if (slots.has('self')) {
+                patternDiagnostics.push({
+                    severity: 'error',
+                    code: 'YM201',
+                    message: `A part cannot be named "self"; "self" names the instance itself in wiring`,
+                    ...at(['patterns', index, 'parts'], `/patterns/${index}/parts`),
+                });
+                continue;
+            }
+            const kindOfEndpoint = (endpoint) => endpoint === 'self' ? anchor.identity : slots.get(endpoint)?.kindIdentity;
+            const wiring = [];
+            let wiringOk = true;
+            const seenWires = new Set();
+            for (const [wireIndex, wire] of pattern.wiring.entries()) {
+                const wireAt = at(['patterns', index, 'wiring', wireIndex], `/patterns/${index}/wiring/${wireIndex}`);
+                const fromKind = kindOfEndpoint(wire.from);
+                const toKind = kindOfEndpoint(wire.to);
+                for (const [end, endpoint, kind] of [
+                    ['from', wire.from, fromKind],
+                    ['to', wire.to, toKind],
+                ]) {
+                    if (kind !== undefined)
+                        continue;
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM302',
+                        message: `Wiring names "${endpoint}" as its ${end}, which is neither "self" nor a declared part`,
+                        ...wireAt,
+                    });
+                    wiringOk = false;
+                }
+                if (wire.from === wire.to) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM201',
+                        message: `Wiring joins "${wire.from}" to itself`,
+                        ...wireAt,
+                    });
+                    wiringOk = false;
+                }
+                const policy = relationshipKindByIdentity.get(wire.kind);
+                if (policy === undefined) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM402',
+                        message: `Relationship kind "${wire.kind}" is not available to this pattern`,
+                        ...wireAt,
+                    });
+                    wiringOk = false;
+                }
+                if (fromKind === undefined || toKind === undefined || policy === undefined) {
+                    continue;
+                }
+                const duplicate = `${wire.from}\u0000${wire.kind}\u0000${wire.to}`;
+                if (seenWires.has(duplicate)) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM201',
+                        message: `Wiring repeats "${wire.from}" ${policy.coreKind} "${wire.to}"`,
+                        ...wireAt,
+                    });
+                    wiringOk = false;
+                    continue;
+                }
+                seenWires.add(duplicate);
+                // Legality is a property of the PATTERN, because the slot kinds fix
+                // both endpoint kinds: a pattern whose wiring the relationship table
+                // forbids can never expand legally, and saying so once here beats
+                // saying it against every instance that was authored correctly.
+                const permitted = permittedBetween(fromKind, toKind);
+                if (permitted !== undefined && !permitted.has(policy.coreKind)) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM404',
+                        message: `Wiring "${wire.from}" ${policy.coreKind} "${wire.to}" is not permitted between ` +
+                            `"${fromKind}" and "${toKind}"`,
+                        ...wireAt,
+                    });
+                    wiringOk = false;
+                    continue;
+                }
+                wiring.push({
+                    from: wire.from,
+                    to: wire.to,
+                    kindIdentity: policy.identity,
+                    coreKind: policy.coreKind,
+                });
+            }
+            if (!wiringOk)
+                continue;
+            const ports = new Map();
+            let portsOk = true;
+            for (const [portIndex, port] of (pattern.ports ?? []).entries()) {
+                const portAt = at(['patterns', index, 'ports', portIndex], `/patterns/${index}/ports/${portIndex}`);
+                const policy = relationshipKindByIdentity.get(port.kind);
+                if (policy === undefined) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM402',
+                        message: `Relationship kind "${port.kind}" is not available to this pattern`,
+                        ...portAt,
+                    });
+                    portsOk = false;
+                    continue;
+                }
+                for (const [end, slot] of [
+                    ['out', port.out],
+                    ['in', port.in],
+                ]) {
+                    if (slots.has(slot))
+                        continue;
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM302',
+                        message: `Port "${policy.coreKind}" names "${slot}" as its ${end}, which is not a declared part`,
+                        ...portAt,
+                    });
+                    portsOk = false;
+                }
+                if (ports.has(port.kind)) {
+                    patternDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM201',
+                        message: `Port "${policy.coreKind}" is declared twice; a kind lands one way`,
+                        ...portAt,
+                    });
+                    portsOk = false;
+                    continue;
+                }
+                ports.set(port.kind, {
+                    out: port.out,
+                    in: port.in,
+                    coreKind: policy.coreKind,
+                });
+            }
+            if (!portsOk)
+                continue;
+            patternsByKind.set(pattern.kind, {
+                kindIdentity: pattern.kind,
+                declaredBy: input.path,
+                slots,
+                wiring,
+                ports,
+            });
+        }
+    }
+    if (patternDiagnostics.length > 0) {
+        return diagnosticFailure(patternDiagnostics);
+    }
+    const patternInstances = [];
     const documents = documentInputs.map(({ input, entry, fresh }) => {
         // Schema-checked by `parseWorkspaceSource`; the faults it found are the
         // `schemaDiagnostics` returned below, and they gate every later phase.
@@ -1276,6 +1557,55 @@ function compileWorkspaceResolved(parsed) {
         for (const [index, concept] of value.concepts.entries()) {
             const subject = concept.id;
             subjects.push({ id: subject, type: 'concept' });
+            // A pattern instance is only COLLECTED here. What its slots bind may be
+            // declared in any document, so the bindings cannot be checked until
+            // every document has been read (#268, ADR 0123).
+            if (concept.parts !== undefined) {
+                const kindIdentity = selectedProfile.conceptKinds.get(concept.kind)?.identity ??
+                    concept.kind;
+                const pattern = patternsByKind.get(kindIdentity);
+                if (pattern === undefined) {
+                    const where = location(['concepts', index, 'parts'], `/concepts/${index}/parts`);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM419',
+                        message: `Concept "${subject}" declares parts, but kind "${kindIdentity}" has no pattern to bind them to`,
+                        path: where.path,
+                        pointer: where.pointer,
+                        line: where.line,
+                        column: where.column,
+                    });
+                }
+                else {
+                    const bindings = new Map();
+                    const sourceOf = new Map();
+                    for (const [slot, target] of Object.entries(concept.parts)) {
+                        const where = location(['concepts', index, 'parts', slot], `/concepts/${index}/parts/${slot}`);
+                        if (!pattern.slots.has(slot)) {
+                            diagnostics.push({
+                                severity: 'error',
+                                code: 'YM419',
+                                message: `Concept "${subject}" binds "${slot}", which the pattern for ` +
+                                    `"${kindIdentity}" does not declare; its parts are ` +
+                                    `${[...pattern.slots.keys()].map((name) => `"${name}"`).join(', ')}`,
+                                path: where.path,
+                                pointer: where.pointer,
+                                line: where.line,
+                                column: where.column,
+                            });
+                            continue;
+                        }
+                        bindings.set(slot, qualifyReference(value.id, target));
+                        sourceOf.set(slot, where);
+                    }
+                    patternInstances.push({
+                        instance: subject,
+                        pattern,
+                        bindings,
+                        sourceOf,
+                    });
+                }
+            }
             claims.push({
                 id: `${subject}~kind`,
                 subject,
@@ -1695,6 +2025,310 @@ function compileWorkspaceResolved(parsed) {
             });
         }
     }
+    // ---- pattern expansion (#268, ADR 0123) ----------------------------------
+    //
+    // Every document has been read, so this can see the whole workspace: what a
+    // slot binds, what kind that subject is, and whether an authored
+    // relationship already says what a wiring edge says. Minted claims are
+    // `declared` and sourced to the binding line that produced them, because
+    // that is where the author said it - the pattern only says which KIND of
+    // edge a bound pair gets.
+    if (patternInstances.length > 0) {
+        const kindOfSubject = new Map();
+        for (const claim of claims) {
+            if (claim.predicate === 'yarramate/concept/kind' &&
+                'value' in claim.object) {
+                kindOfSubject.set(claim.subject, claim.object.value);
+            }
+        }
+        const declaredIds = new Set(subjects.map(({ id }) => id));
+        // Authored relationships indexed by the UNORDERED pair they join, which is
+        // the granularity the ownership rule is stated at: the pattern speaks for
+        // a pair, so a reversed edge is a contradiction rather than a new fact.
+        const pairKey = (left, right) => left < right ? `${left}\u0000${right}` : `${right}\u0000${left}`;
+        const authoredByPair = new Map();
+        const relationshipIds = new Set(subjects.filter(({ type }) => type === 'relationship').map(({ id }) => id));
+        for (const claim of claims) {
+            if (!relationshipIds.has(claim.id) || !('ref' in claim.object))
+                continue;
+            const entry = {
+                id: claim.id,
+                from: claim.subject,
+                to: claim.object.ref,
+                predicate: claim.predicate,
+                source: claim.source,
+            };
+            const key = pairKey(entry.from, entry.to);
+            const group = authoredByPair.get(key);
+            if (group === undefined)
+                authoredByPair.set(key, [entry]);
+            else
+                group.push(entry);
+        }
+        for (const { instance, pattern, bindings, sourceOf } of patternInstances) {
+            const boundTo = new Map();
+            for (const [slot, target] of bindings) {
+                const where = sourceOf.get(slot);
+                if (where === undefined)
+                    continue;
+                const slotShape = pattern.slots.get(slot);
+                if (slotShape === undefined)
+                    continue;
+                if (!declaredIds.has(target)) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM315',
+                        message: `Part "${slot}" of "${instance}" names "${target}", which is not a declared subject`,
+                        path: where.path,
+                        pointer: where.pointer,
+                        line: where.line,
+                        column: where.column,
+                    });
+                    continue;
+                }
+                const already = boundTo.get(target);
+                if (already !== undefined) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM315',
+                        message: `"${instance}" binds "${target}" as both "${already}" and "${slot}"; one subject fills one slot`,
+                        path: where.path,
+                        pointer: where.pointer,
+                        line: where.line,
+                        column: where.column,
+                    });
+                    continue;
+                }
+                boundTo.set(target, slot);
+                const actual = kindOfSubject.get(target);
+                if (actual !== slotShape.kindIdentity) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM417',
+                        message: `Part "${slot}" of "${instance}" binds "${target}", which is ` +
+                            `"${actual ?? 'not a concept'}"; the pattern declares this part ` +
+                            `"${slotShape.kindIdentity}"`,
+                        path: where.path,
+                        pointer: where.pointer,
+                        line: where.line,
+                        column: where.column,
+                    });
+                }
+            }
+            const instanceSource = [...sourceOf.values()][0];
+            for (const slot of pattern.slots.values()) {
+                if (!slot.required || bindings.has(slot.name))
+                    continue;
+                if (instanceSource === undefined)
+                    continue;
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'YM416',
+                    message: `"${instance}" leaves the required part "${slot.name}" unbound`,
+                    path: instanceSource.path,
+                    pointer: instanceSource.pointer,
+                    line: instanceSource.line,
+                    column: instanceSource.column,
+                });
+            }
+            const subjectOf = (endpoint) => endpoint === 'self' ? instance : bindings.get(endpoint);
+            for (const wire of pattern.wiring) {
+                const from = subjectOf(wire.from);
+                const to = subjectOf(wire.to);
+                // An optional part nobody bound wires nothing. The required ones have
+                // already been reported above, so this is silence by design.
+                if (from === undefined || to === undefined)
+                    continue;
+                if (!declaredIds.has(from) || !declaredIds.has(to))
+                    continue;
+                const where = sourceOf.get(wire.to === 'self' ? wire.from : wire.to) ??
+                    instanceSource;
+                if (where === undefined)
+                    continue;
+                const authored = authoredByPair.get(pairKey(from, to)) ?? [];
+                let satisfied = false;
+                for (const edge of authored) {
+                    if (edge.from === from &&
+                        edge.to === to &&
+                        edge.predicate === wire.kindIdentity) {
+                        // Exactly what the wiring says. The authored relationship IS the
+                        // wiring, so nothing is minted and nothing is reported: adoption
+                        // costs no edit, and the redundant lines can go later.
+                        satisfied = true;
+                        continue;
+                    }
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM418',
+                        message: `Relationship "${edge.id}" joins "${edge.from}" to "${edge.to}", a pair ` +
+                            `the pattern for "${pattern.kindIdentity}" wires as "${from}" ` +
+                            `${wire.coreKind} "${to}"`,
+                        path: edge.source.path,
+                        pointer: edge.source.pointer,
+                        line: edge.source.line,
+                        column: edge.source.column,
+                    });
+                }
+                if (satisfied)
+                    continue;
+                const wireId = [
+                    instance,
+                    ...(wire.from === 'self' ? [] : [wire.from]),
+                    wire.coreKind,
+                    wire.to,
+                ].join('-');
+                if (declaredIds.has(wireId)) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM420',
+                        message: `The pattern for "${pattern.kindIdentity}" derives the wiring id ` +
+                            `"${wireId}" for "${instance}", which is already a declared subject`,
+                        path: where.path,
+                        pointer: where.pointer,
+                        line: where.line,
+                        column: where.column,
+                    });
+                    continue;
+                }
+                declaredIds.add(wireId);
+                subjects.push({ id: wireId, type: 'relationship' });
+                claims.push({
+                    id: wireId,
+                    subject: from,
+                    predicate: wire.kindIdentity,
+                    object: { ref: to },
+                    origin: 'declared',
+                    source: where,
+                });
+            }
+        }
+    }
+    // ---- macro edges through ports (#268 phase 2, ADR 0124) ------------------
+    //
+    // A relationship authored BETWEEN two pattern instances is a macro-grain
+    // fact: "System API serves Process API", one line. Where both patterns
+    // declare a port for its kind, it is expanded to the canonical pair the
+    // ports name - the source's `out` slot to the target's `in` slot - and the
+    // macro edge itself SURVIVES, because it is what a collapsed view has to
+    // draw. That is the whole inversion: the simple picture is authored and the
+    // detailed one derived, rather than the other way about.
+    if (patternInstances.length > 0) {
+        const instanceByIdForPorts = new Map(patternInstances.map((entry) => [entry.instance, entry]));
+        const kindOfSubjectForPorts = new Map();
+        for (const claim of claims) {
+            if (claim.predicate === 'yarramate/concept/kind' &&
+                'value' in claim.object) {
+                kindOfSubjectForPorts.set(claim.subject, claim.object.value);
+            }
+        }
+        const declaredIdsForPorts = new Set(subjects.map(({ id }) => id));
+        const relationshipIdsForPorts = new Set(subjects.filter(({ type }) => type === 'relationship').map(({ id }) => id));
+        const authoredPairs = new Set();
+        const macroEdges = [];
+        for (const claim of claims) {
+            if (!relationshipIdsForPorts.has(claim.id) || !('ref' in claim.object)) {
+                continue;
+            }
+            authoredPairs.add(`${claim.subject}\u0000${claim.predicate}\u0000${claim.object.ref}`);
+            if (instanceByIdForPorts.has(claim.subject) &&
+                instanceByIdForPorts.has(claim.object.ref)) {
+                macroEdges.push(claim);
+            }
+        }
+        for (const edge of macroEdges) {
+            if (!('ref' in edge.object))
+                continue;
+            const source = instanceByIdForPorts.get(edge.subject);
+            const target = instanceByIdForPorts.get(edge.object.ref);
+            if (source === undefined || target === undefined)
+                continue;
+            const outPort = source.pattern.ports.get(edge.predicate);
+            const inPort = target.pattern.ports.get(edge.predicate);
+            // Only a kind BOTH patterns give a port is a macro edge. Anything else
+            // between two instances is an ordinary relationship and is left alone:
+            // groupings may legally relate, and a pattern that says nothing about a
+            // kind has not claimed it.
+            if (outPort === undefined || inPort === undefined)
+                continue;
+            const from = source.bindings.get(outPort.out);
+            const to = target.bindings.get(inPort.in);
+            if (from === undefined || to === undefined) {
+                // The macro edge is a promise the expansion keeps, so an unbound
+                // landing slot is a promise the model cannot cash. Reported against
+                // the macro edge, which is the line someone would have to change.
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'YM421',
+                    message: `"${edge.id}" is a ${outPort.coreKind} between pattern instances, but ` +
+                        `${from === undefined ? `"${edge.subject}" binds no "${outPort.out}"` : `"${'ref' in edge.object ? edge.object.ref : ''}" binds no "${inPort.in}"`}` +
+                        `, so it has nowhere to land`,
+                    path: edge.source.path,
+                    pointer: edge.source.pointer,
+                    line: edge.source.line,
+                    column: edge.source.column,
+                });
+                continue;
+            }
+            // Legality cannot be settled when the pattern resolves, the way wiring's
+            // is: the two ends belong to DIFFERENT patterns, and neither knows the
+            // other's slot kinds. So the pair the ports actually name is judged here,
+            // against the macro edge that asked for it. Without this the compiler
+            // would emit a relationship the table forbids - the one thing `check`
+            // exists to make impossible.
+            const expandedKind = relationshipKindByIdentity.get(edge.predicate);
+            const fromKind = kindOfSubjectForPorts.get(from);
+            const toKind = kindOfSubjectForPorts.get(to);
+            if (expandedKind !== undefined &&
+                fromKind !== undefined &&
+                toKind !== undefined) {
+                const permitted = permittedBetween(fromKind, toKind);
+                if (permitted !== undefined && !permitted.has(expandedKind.coreKind)) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM404',
+                        message: `Expanding "${edge.id}" through the ports lands ` +
+                            `"${expandedKind.coreKind}" from "${from}" to "${to}", which is ` +
+                            `not permitted between "${fromKind}" and "${toKind}"`,
+                        path: edge.source.path,
+                        pointer: edge.source.pointer,
+                        line: edge.source.line,
+                        column: edge.source.column,
+                    });
+                    continue;
+                }
+            }
+            if (authoredPairs.has(`${from}\u0000${edge.predicate}\u0000${to}`)) {
+                // Already said at the member grain. The macro edge and the authored
+                // pair agree, which is exactly the correspondence a description used
+                // to assert; nothing is minted and nothing is reported.
+                continue;
+            }
+            const expandedId = `${edge.id}-expansion`;
+            if (declaredIdsForPorts.has(expandedId)) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'YM420',
+                    message: `Expanding "${edge.id}" derives the id "${expandedId}", which is ` +
+                        `already a declared subject`,
+                    path: edge.source.path,
+                    pointer: edge.source.pointer,
+                    line: edge.source.line,
+                    column: edge.source.column,
+                });
+                continue;
+            }
+            declaredIdsForPorts.add(expandedId);
+            subjects.push({ id: expandedId, type: 'relationship' });
+            claims.push({
+                id: expandedId,
+                subject: from,
+                predicate: edge.predicate,
+                object: { ref: to },
+                origin: 'declared',
+                source: edge.source,
+            });
+        }
+    }
     if (diagnostics.length > 0) {
         return diagnosticFailure(diagnostics);
     }
@@ -1745,6 +2379,18 @@ function compileWorkspaceResolved(parsed) {
             relationshipKindCoreAncestors: immutableMap([...relationshipKindByIdentity]
                 .sort(([left], [right]) => left.localeCompare(right))
                 .map(([identity, kind]) => [identity, kind.coreKind])),
+            patternPortKinds: immutableMap([...patternsByKind]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .flatMap(([identity, pattern]) => pattern.ports.size === 0
+                ? []
+                : [
+                    [
+                        identity,
+                        Object.freeze([...pattern.ports.values()]
+                            .map(({ coreKind }) => coreKind)
+                            .sort()),
+                    ],
+                ])),
             permittedRelationshipKinds: (fromKindIdentity, toKindIdentity) => {
                 const from = conceptKindByIdentity.get(fromKindIdentity);
                 const to = conceptKindByIdentity.get(toKindIdentity);