@astrale-os/kernel-dsl 0.2.0-beta.35 → 0.2.0-beta.36

package/dist/v1/schema/compatibility/meaning.js

@@ -1,375 +1,19 @@
 import { json } from '@astrale-os/kernel-dsl/value';
-import { Key, MethodKey, PropertyKey } from '../../addressing/index.js';
-import { compareUnicode, definitionRefIndex } from '../../addressing/ordering.js';
+import { Key } from '../../addressing/index.js';
+import { compareUnicode } from '../../addressing/ordering.js';
 import { isValueObject as isJsonObject } from '../../language/value/model/object.js';
 import { SCHEMA_ARRAY_KEYWORDS, SCHEMA_MAP_KEYWORDS, SCHEMA_SINGLE_KEYWORDS, } from '../../language/value/syntax/keywords.js';
 import { digestDomainSchemaBytes } from '../canonical/domain.digest.js';
-import { revisionOfDomainSchema } from '../canonical/revision.js';
-import { SchemaError, diagnostic } from '../diagnostic.js';
-import { knownDomainClosure, lookupForDomainClosure } from '../resolution/closure.js';
-import { resolve } from '../resolution/domain.js';
-import { collectCallableContractRefs, collectCallableRefs, collectClassPolicyRefs, collectClassRefs, collectCoreRefs, collectEndpointRefs, collectPolicyDefinitionRefs, collectValueDefinitionRefs, } from '../resolution/origins.js';
-import { validateDomainSchemaSemantics } from '../validation/domain.js';
-const VALUE_SCHEMA_ANNOTATIONS = new Set([
-    '$comment',
-    'contentEncoding',
-    'contentMediaType',
-    'contentSchema',
-    'default',
-    'deprecated',
-    'description',
-    'examples',
-    'format',
-    'readOnly',
-    'title',
-    'writeOnly',
-]);
+import { deepFreeze } from '../canonical/freeze.js';
+import { effectiveDefinition, effectiveMethod } from './context.js';
+import { keyForDefinitionRef } from './coordinate.js';
+import { ANNOTATION_KEYWORDS } from './fields.js';
 /**
- * Compare the exact V1 meaning one accepted Domain used from a retained dependency with a
- * candidate revision of that same dependency origin. This operation is pure and makes no
- * lifecycle-compatibility decision.
+ * The meaning of one coordinate is a portable value built from the fields `fields.ts` classifies
+ * as counting at the coordinate's usage level; `__tests__/fields.test.ts` proves the two agree.
+ * Comparison works on these values, so every difference can name its exact path.
  */
-export function compareDependencyMeaning(dependent, target) {
-    resolve(dependent);
-    const context = contextOf(dependent);
-    const source = (knownDomainClosure(dependent) ?? []).find((candidate) => candidate.schema.origin === target.origin)?.schema;
-    if (source === undefined) {
-        throw new SchemaError([
-            diagnostic('DM_DEPENDENCY_NOT_RETAINED', '/target/origin', `Domain ${dependent.origin} was not admitted with a dependency at ${target.origin}.`),
-        ]);
-    }
-    const meanings = collectReachableMeanings(collectSchemaRoots(dependent), source.origin, context);
-    return compareSourceMeanings(source, target, meanings);
-}
-/** Compare one explicit non-empty source member surface and its reachable V1 meaning. */
-export function compareMemberMeaning(source, target, roots) {
-    if (source.origin !== target.origin) {
-        throw new SchemaError([
-            diagnostic('DM_MEMBER_ORIGIN_MISMATCH', '/target/origin', `Member comparison target ${target.origin} does not match source ${source.origin}.`),
-        ]);
-    }
-    if (!Array.isArray(roots) || roots.length === 0 || new Set(roots).size !== roots.length) {
-        throw new SchemaError([
-            diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', 'Member comparison roots must be one non-empty duplicate-free Key set.'),
-        ]);
-    }
-    resolve(source);
-    const context = contextOf(source);
-    const coordinates = roots.map((key, index) => coordinateForKey(context, source, key, index));
-    const meanings = collectReachableMeanings(coordinates, source.origin, context);
-    return compareSourceMeanings(source, target, meanings);
-}
-/**
- * Fingerprint the contract a caller compiles against, independently of its Domain revision: the
- * exact key, the owner, dispatch and abstractness of a Method, and the semantic input and output
- * contracts; authorization is excluded (DM-CALLABLE-FINGERPRINT). A static consumer pins this
- * instead of a Domain revision, so a dependency release that leaves the callable contract untouched
- * keeps every bound invocation valid.
- */
-export function callableFingerprint(callable) {
-    return fingerprintMeaning('owner' in callable
-        ? {
-            kind: 'method',
-            key: callable.key,
-            owner: callable.owner.key,
-            ...semanticMethod(callable),
-        }
-        : { kind: 'function', key: callable.key, ...semanticFunction(callable) });
-}
-function contextOf(root) {
-    const schemas = new Map([
-        [root.origin, root],
-        ...(knownDomainClosure(root) ?? []).map(({ schema }) => [schema.origin, schema]),
-    ]);
-    const analyses = new Map();
-    return {
-        schemas,
-        analysis(owner) {
-            if (!analyses.has(owner)) {
-                const validation = validateDomainSchemaSemantics(owner, lookupForDomainClosure(owner));
-                analyses.set(owner, validation.diagnostics.length > 0 ? undefined : validation.analysis.definitions);
-            }
-            return analyses.get(owner);
-        },
-    };
-}
-function compareSourceMeanings(source, target, sourceMeanings) {
-    // Prove the candidate still has an exact accepted semantic context before comparing it.
-    resolve(target);
-    const context = contextOf(target);
-    const footprint = Object.freeze([...sourceMeanings.keys()].sort(compareUnicode));
-    const changes = [];
-    const comparisonCoordinates = [];
-    for (const key of footprint) {
-        const sourceMeaning = sourceMeanings.get(key);
-        const targetMeaning = meaningForCoordinate(context, sourceMeaning.coordinate, sourceMeaning.requirement);
-        const targetFingerprint = targetMeaning === undefined ? undefined : fingerprintMeaning(targetMeaning);
-        comparisonCoordinates.push([
-            key,
-            sourceMeaning.fingerprint,
-            targetFingerprint ?? null,
-        ]);
-        if (targetFingerprint === undefined) {
-            changes.push(Object.freeze({ key, kind: 'missing', sourceFingerprint: sourceMeaning.fingerprint }));
-        }
-        else if (targetFingerprint !== sourceMeaning.fingerprint) {
-            changes.push(Object.freeze({
-                key,
-                kind: 'changed',
-                sourceFingerprint: sourceMeaning.fingerprint,
-                targetFingerprint,
-            }));
-        }
-    }
-    const additions = addedObligations(context, sourceMeanings);
-    const sourceRevision = revisionOfDomainSchema(source);
-    const targetRevision = revisionOfDomainSchema(target);
-    const fingerprint = fingerprintMeaning({
-        version: 2,
-        dependency: source.origin,
-        source: sourceRevision,
-        target: targetRevision,
-        coordinates: comparisonCoordinates,
-        additions: additions.map(({ key, targetFingerprint }) => [key, targetFingerprint]),
-    });
-    return Object.freeze({
-        version: 2,
-        dependency: source.origin,
-        source: sourceRevision,
-        target: targetRevision,
-        footprint,
-        changes: Object.freeze([...changes, ...additions]),
-        fingerprint,
-    });
-}
-/** A target may extend an inherited Class only with optional or automatic Properties. */
-function addedObligations(context, sourceMeanings) {
-    const additions = new Map();
-    for (const { coordinate, requirement } of sourceMeanings.values()) {
-        if (coordinate.kind !== 'class' || coordinate.level !== 'inherit' || requirement === undefined)
-            continue;
-        const owner = context.schemas.get(coordinate.ref.origin);
-        const analysis = owner === undefined ? undefined : effectiveDefinition(context, owner, coordinate.ref);
-        if (analysis === undefined)
-            continue;
-        for (const field of analysis.properties.values()) {
-            if (requirement.properties.has(field.identity) || !field.required || field.auto !== undefined)
-                continue;
-            additions.set(field.identity, Object.freeze({
-                key: field.identity,
-                kind: 'added',
-                targetFingerprint: fingerprintMeaning(propertyMeaning(field)),
-            }));
-        }
-    }
-    return [...additions.values()].sort((left, right) => compareUnicode(left.key, right.key));
-}
-function collectSchemaRoots(owner) {
-    const classes = new Map();
-    const members = new Map();
-    const add = (ref, site) => {
-        if (ref.kind === 'class') {
-            const index = definitionRefIndex(ref);
-            const level = levelOf(site);
-            const previous = classes.get(index);
-            if (previous === undefined || (previous.level === 'reference' && level === 'inherit')) {
-                classes.set(index, classCoordinate(ref, level));
-            }
-            return;
-        }
-        members.set(definitionRefIndex(ref), memberCoordinate(ref));
-    };
-    for (const declaration of Object.values(owner.classes))
-        collectClassRefs(declaration, add);
-    for (const declaration of Object.values(owner.functions))
-        collectCallableRefs(declaration, add);
-    for (const declaration of Object.values(owner.policies)) {
-        collectPolicyDefinitionRefs(declaration, add);
-    }
-    for (const declaration of Object.values(owner.views)) {
-        if (declaration.target.kind === 'definition') {
-            declaration.target.definitions.forEach((ref) => add(ref, 'view'));
-        }
-    }
-    collectCoreRefs(owner, add);
-    return [...classes.values(), ...members.values()].sort((left, right) => compareUnicode(left.key, right.key));
-}
-function collectReachableMeanings(roots, selectedOrigin, context) {
-    const meanings = new Map();
-    const classLevels = new Map();
-    const visitedMembers = new Set();
-    const pendingClasses = [];
-    const pendingMembers = [];
-    const push = (ref, site) => {
-        if (ref.kind === 'class')
-            pendingClasses.push(classCoordinate(ref, levelOf(site)));
-        else
-            pendingMembers.push(memberCoordinate(ref));
-    };
-    for (const coordinate of roots) {
-        if (coordinate.kind === 'class') {
-            pendingClasses.push(coordinate);
-            continue;
-        }
-        if (coordinate.kind === 'member') {
-            pendingMembers.push(coordinate);
-            continue;
-        }
-        const meaning = meaningForCoordinate(context, coordinate);
-        if (meaning === undefined) {
-            throw new SchemaError([
-                diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Member comparison root ${coordinate.key} does not exist in its source context.`, coordinate.key),
-            ]);
-        }
-        retainMeaning(meanings, selectedOrigin, coordinate, meaning);
-        collectCoordinateSemanticRefs(context, coordinate, push);
-    }
-    const visitClass = (coordinate) => {
-        const index = definitionRefIndex(coordinate.ref);
-        const previous = classLevels.get(index);
-        if (previous === 'inherit' || previous === coordinate.level)
-            return;
-        classLevels.set(index, coordinate.level);
-        const owner = requireOwner(context, coordinate.ref, coordinate.key);
-        const declaration = owner.classes[coordinate.ref.name];
-        const analysis = effectiveDefinition(context, owner, coordinate.ref);
-        const resolved = classMeaning(context, coordinate);
-        if (declaration === undefined || analysis === undefined || resolved === undefined) {
-            throw contextInvalid(`Retained acceptance context has no meaning for ${coordinate.key}.`, coordinate.key);
-        }
-        retainMeaning(meanings, selectedOrigin, coordinate, resolved.meaning, resolved.requirement);
-        if (previous === undefined) {
-            // The surface is level-independent: every effective Property and Method the dependent may
-            // read or call, with the Definitions their contracts and policies name.
-            for (const field of analysis.properties.values()) {
-                retainMeaning(meanings, selectedOrigin, propertyCoordinate(field.owner, field.name), propertyMeaning(field));
-                collectValueDefinitionRefs(field.schema, push);
-            }
-            for (const method of analysis.methods.values()) {
-                retainMeaning(meanings, selectedOrigin, methodCoordinate(method.owner, method.name), methodMeaning(method));
-                collectCallableContractRefs(method.declaration, push);
-            }
-            collectClassPolicyRefs(declaration, push);
-        }
-        if (coordinate.level === 'inherit') {
-            // Only inheritance takes on the ancestry and, for an Edge, the endpoint contract.
-            declaration.extends.forEach((parent) => push(parent, 'extends'));
-            if (declaration.kind === 'edge')
-                collectEndpointRefs(declaration, push);
-        }
-    };
-    const visitMember = (coordinate) => {
-        const index = definitionRefIndex(coordinate.ref);
-        if (visitedMembers.has(index))
-            return;
-        visitedMembers.add(index);
-        const owner = requireOwner(context, coordinate.ref, coordinate.key);
-        const meaning = memberMeaning(owner, coordinate.ref);
-        if (meaning === undefined) {
-            throw contextInvalid(`Retained acceptance context has no meaning for ${coordinate.key}.`, coordinate.key);
-        }
-        retainMeaning(meanings, selectedOrigin, coordinate, meaning);
-        collectMemberSemanticRefs(owner, coordinate.ref, push);
-    };
-    let classIndex = 0;
-    let memberIndex = 0;
-    while (classIndex < pendingClasses.length || memberIndex < pendingMembers.length) {
-        if (classIndex < pendingClasses.length)
-            visitClass(pendingClasses[classIndex++]);
-        else
-            visitMember(pendingMembers[memberIndex++]);
-    }
-    return meanings;
-}
-function requireOwner(context, ref, key) {
-    const owner = context.schemas.get(ref.origin);
-    if (owner === undefined) {
-        throw contextInvalid(`Retained acceptance context cannot resolve ${key}.`, key);
-    }
-    return owner;
-}
-function contextInvalid(message, key) {
-    return new SchemaError([diagnostic('DM_DEPENDENCY_CONTEXT_INVALID', '', message, key)]);
-}
-function collectCoordinateSemanticRefs(context, coordinate, add) {
-    const owner = context.schemas.get(coordinate.owner.origin);
-    const analysis = owner === undefined ? undefined : effectiveDefinition(context, owner, coordinate.owner);
-    if (analysis === undefined)
-        return;
-    if (coordinate.kind === 'property') {
-        const field = analysis.properties.get(coordinate.key);
-        if (field !== undefined)
-            collectValueDefinitionRefs(field.schema, add);
-        return;
-    }
-    const method = [...analysis.methods.values()].find((candidate) => MethodKey.of(candidate.owner, candidate.name) === coordinate.key);
-    if (method !== undefined)
-        collectCallableContractRefs(method.declaration, add);
-}
-function collectMemberSemanticRefs(owner, ref, add) {
-    switch (ref.kind) {
-        case 'function': {
-            const declaration = owner.functions[ref.name];
-            if (declaration !== undefined)
-                collectCallableRefs(declaration, add);
-            return;
-        }
-        case 'policy': {
-            const declaration = owner.policies[ref.name];
-            if (declaration !== undefined)
-                collectPolicyDefinitionRefs(declaration, add);
-            return;
-        }
-        case 'view': {
-            const declaration = owner.views[ref.name];
-            if (declaration?.target.kind === 'definition') {
-                declaration.target.definitions.forEach((definition) => add(definition, 'view'));
-            }
-            return;
-        }
-        case 'core': {
-            // The dependency instantiates its own Core; the dependent only refers to it.
-            const node = owner.core.nodes[ref.name];
-            if (node === undefined)
-                return;
-            add(node.class);
-            for (const edge of incidentCoreEdges(owner, ref.name)) {
-                add(edge.class);
-                if (edge.source.kind !== 'domain')
-                    add(edge.source);
-                if (edge.target.kind !== 'domain')
-                    add(edge.target);
-            }
-        }
-    }
-}
-function retainMeaning(meanings, selectedOrigin, coordinate, meaning, requirement) {
-    if (Key.origin(coordinate.key) !== selectedOrigin)
-        return;
-    const fingerprint = fingerprintMeaning(meaning);
-    const previous = meanings.get(coordinate.key);
-    if (previous !== undefined) {
-        const upgraded = previous.coordinate.kind === 'class' &&
-            coordinate.kind === 'class' &&
-            previous.coordinate.level !== coordinate.level;
-        if (upgraded) {
-            // A stronger requirement replaces the weaker one for the same Class.
-            if (coordinate.level === 'reference')
-                return;
-        }
-        else if (previous.fingerprint !== fingerprint) {
-            throw new SchemaError([
-                diagnostic('DM_MEANING_INCONSISTENT', '', `Semantic coordinate ${coordinate.key} produced inconsistent effective meaning.`, coordinate.key),
-            ]);
-        }
-    }
-    meanings.set(coordinate.key, Object.freeze({
-        coordinate,
-        fingerprint,
-        ...(requirement === undefined ? {} : { requirement }),
-    }));
-}
-function meaningForCoordinate(context, coordinate, requirement) {
+export function meaningForCoordinate(context, coordinate, requirement) {
     const owner = context.schemas.get(Key.origin(coordinate.key));
     if (owner === undefined)
         return undefined;
@@ -384,16 +28,16 @@ function meaningForCoordinate(context, coordinate, requirement) {
         const field = analysis.properties.get(coordinate.key);
         return field === undefined ? undefined : propertyMeaning(field);
     }
-    const method = [...analysis.methods.values()].find((candidate) => MethodKey.of(candidate.owner, candidate.name) === coordinate.key);
+    const method = effectiveMethod(analysis, coordinate.key);
     return method === undefined ? undefined : methodMeaning(method);
 }
 /**
- * The requirement one usage level places on a Class. A reference needs the Class to exist with
- * its kind; inheritance additionally needs the source ancestors, class policies, data contract
- * and, for an Edge, the endpoint contract. A target projected onto a source requirement keeps only
- * the ancestors the source named, so a superset satisfies it while a removal changes it.
+ * A reference needs the Class to exist with its kind, abstractness and orientation; inheritance
+ * additionally takes on the source ancestors, class policies, data contract and, for an Edge, the
+ * endpoint and constraint contracts. A target projected onto a source requirement keeps only the
+ * ancestors the source named, so a superset satisfies it while a removal changes it.
  */
-function classMeaning(context, coordinate, onto) {
+export function classMeaning(context, coordinate, onto) {
     const owner = context.schemas.get(coordinate.ref.origin);
     const declaration = owner?.classes[coordinate.ref.name];
     const analysis = owner === undefined ? undefined : effectiveDefinition(context, owner, coordinate.ref);
@@ -405,48 +49,39 @@ function classMeaning(context, coordinate, onto) {
         properties: new Set(analysis.properties.keys()),
     });
     const meaning = {
-        kind: 'class',
+        coordinate: 'class',
         level: coordinate.level,
-        classKind: declaration.kind,
+        kind: declaration.kind,
+        abstract: declaration.abstract,
         ...(declaration.kind === 'edge' ? { orientation: declaration.orientation } : {}),
         ...(coordinate.level === 'inherit'
             ? {
-                ancestors: onto === undefined
+                extends: onto === undefined
                     ? ancestors
                     : onto.ancestors.filter((ancestor) => ancestors.includes(ancestor)),
                 policies: Object.fromEntries(Object.entries(declaration.policies)
                     .filter(([, ref]) => ref !== undefined)
                     .map(([role, ref]) => [role, keyForDefinitionRef(ref)])),
-                data: analysis.data === undefined
-                    ? null
-                    : {
-                        owner: keyForDefinitionRef(analysis.data.owner),
-                        declaration: analysis.data.declaration,
-                    },
-                ...(declaration.kind === 'edge' ? { endpoints: declaration.endpoints } : {}),
+                ...(declaration.kind === 'node'
+                    ? {
+                        data: analysis.data === undefined
+                            ? null
+                            : {
+                                owner: keyForDefinitionRef(analysis.data.owner),
+                                declaration: analysis.data.declaration,
+                            },
+                    }
+                    : { endpoints: declaration.endpoints, constraints: declaration.constraints }),
             }
             : {}),
     };
-    return { meaning, requirement };
+    return { meaning: deepFreeze(meaning), requirement };
 }
-function ancestorKeys(context, ref) {
-    const seen = new Set();
-    const visit = (current) => {
-        const declaration = context.schemas.get(current.origin)?.classes[current.name];
-        if (declaration === undefined)
-            return;
-        for (const parent of declaration.extends) {
-            const key = keyForDefinitionRef(parent);
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            visit(parent);
-        }
-    };
-    visit(ref);
-    return [...seen].sort(compareUnicode);
+export function memberMeaning(owner, ref) {
+    const meaning = memberMeaningOf(owner, ref);
+    return meaning === undefined ? undefined : deepFreeze(meaning);
 }
-function memberMeaning(owner, ref) {
+function memberMeaningOf(owner, ref) {
     if (ref.origin !== owner.origin)
         return undefined;
     switch (ref.kind) {
@@ -454,66 +89,86 @@ function memberMeaning(owner, ref) {
             const declaration = owner.functions[ref.name];
             return declaration === undefined
                 ? undefined
-                : { kind: ref.kind, declaration: semanticFunction(declaration) };
+                : { coordinate: 'function', ...callableContract(declaration) };
         }
         case 'policy': {
             const declaration = owner.policies[ref.name];
             return declaration === undefined
                 ? undefined
-                : { kind: ref.kind, declaration: semanticPolicy(declaration) };
+                : { coordinate: 'policy', expression: declaration.expression };
         }
         case 'view': {
             const declaration = owner.views[ref.name];
             return declaration === undefined
                 ? undefined
-                : { kind: ref.kind, declaration: semanticView(declaration) };
+                : { coordinate: 'view', target: declaration.target };
         }
         case 'core': {
             const node = owner.core.nodes[ref.name];
             return node === undefined
                 ? undefined
                 : {
-                    kind: ref.kind,
-                    node,
-                    edges: incidentCoreEdges(owner, ref.name),
+                    coordinate: 'core',
+                    class: node.class,
+                    properties: node.properties,
+                    edges: incidentCoreEdges(owner, ref.name).map((edge) => ({
+                        class: edge.class,
+                        source: edge.source,
+                        target: edge.target,
+                        properties: edge.properties,
+                    })),
                 };
         }
     }
 }
-function effectiveDefinition(context, owner, ref) {
-    return context.analysis(owner)?.get(definitionRefIndex(ref));
-}
-function propertyMeaning(field) {
-    return {
-        kind: 'property',
+export function propertyMeaning(field) {
+    return deepFreeze({
+        coordinate: 'property',
         owner: keyForDefinitionRef(field.owner),
         name: field.name,
         schema: semanticValueSchema(field.schema),
         required: field.required,
+        ...(field.auto === undefined ? {} : { auto: field.auto }),
         ...(field.state === undefined ? {} : { state: field.state }),
-    };
+    });
 }
-function methodMeaning(method) {
-    return {
-        kind: 'method',
+export function methodMeaning(method) {
+    return deepFreeze({
+        coordinate: 'method',
         owner: keyForDefinitionRef(method.owner),
         name: method.name,
-        declaration: semanticMethod(method.declaration),
-    };
+        ...callableContract(method.declaration),
+    });
+}
+/**
+ * Fingerprint the contract a caller compiles against, independently of its Domain revision: the
+ * exact key, the owner, dispatch and abstractness of a Method, and the semantic input and output
+ * contracts; authorization is excluded (DM-CALLABLE-FINGERPRINT). A static consumer pins this
+ * instead of a Domain revision, so a dependency release that leaves the callable contract untouched
+ * keeps every bound invocation valid.
+ */
+export function callableFingerprint(callable) {
+    // This digest input travels in every bound invocation and is recomputed by the Kernel; its
+    // shape is frozen, `kind` included, so a Kernel upgrade never invalidates an unchanged pin.
+    return fingerprintMeaning('owner' in callable
+        ? {
+            kind: 'method',
+            key: callable.key,
+            owner: callable.owner.key,
+            ...callableContract(callable),
+        }
+        : { kind: 'function', key: callable.key, ...callableContract(callable) });
 }
-function semanticFunction(declaration) {
+/** The `always` fields of CALLABLE_FIELDS: dispatch shape and the semantic input and output. */
+function callableContract(declaration) {
     return {
+        ...('static' in declaration
+            ? { static: declaration.static, abstract: declaration.abstract }
+            : {}),
         input: semanticValueSchema(declaration.input),
         output: semanticOutput(declaration.output),
     };
 }
-function semanticMethod(declaration) {
-    return {
-        static: declaration.static,
-        abstract: declaration.abstract,
-        ...semanticFunction(declaration),
-    };
-}
 function semanticOutput(output) {
     switch (output.mode) {
         case 'value':
@@ -524,20 +179,13 @@ function semanticOutput(output) {
             return { mode: 'binary' };
     }
 }
-function semanticPolicy(declaration) {
-    const { description: _description, ...semantic } = declaration;
-    return semantic;
-}
-function semanticView(declaration) {
-    const { description: _description, ...semantic } = declaration;
-    return semantic;
-}
-function semanticValueSchema(value) {
+/** Drop annotation keywords wherever a schema keyword nests a schema; never inside data. */
+export function semanticValueSchema(value) {
     if (typeof value === 'boolean')
         return value;
     const semantic = {};
     for (const [keyword, entry] of Object.entries(value)) {
-        if (VALUE_SCHEMA_ANNOTATIONS.has(keyword))
+        if (ANNOTATION_KEYWORDS.includes(keyword))
             continue;
         if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(entry)) {
             semantic[keyword] = semanticValueSchema(entry);
@@ -557,106 +205,30 @@ function semanticValueSchema(value) {
     }
     return semantic;
 }
-function coordinateForKey(context, source, input, index) {
-    let key;
-    try {
-        key = Key(input);
-    }
-    catch {
-        return invalidMemberRoot(input, index, 'is not a canonical semantic Key');
-    }
-    if (Key.origin(key) !== source.origin) {
-        return invalidMemberRoot(key, index, `belongs to ${Key.origin(key)}, not source ${source.origin}`);
-    }
-    const reference = keyReference(key);
-    let coordinate;
-    if ((reference.member === 'property' || reference.member === 'method') &&
-        reference.ownerKind === 'class' &&
-        reference.ownerName !== undefined) {
-        if (source.classes[reference.ownerName] === undefined) {
-            return invalidMemberRoot(key, index, 'has no exact owning Definition');
-        }
-        const owner = { origin: source.origin, kind: 'class', name: reference.ownerName };
-        coordinate =
-            reference.member === 'property'
-                ? propertyCoordinate(owner, reference.name)
-                : methodCoordinate(owner, reference.name);
-    }
-    else if (reference.kind === 'class') {
-        if (source.classes[reference.name] === undefined) {
-            return invalidMemberRoot(key, index, 'does not exist in the source');
-        }
-        // An explicit Class root compares its surface; it never infers an inheritance contract.
-        coordinate = classCoordinate({ origin: source.origin, kind: 'class', name: reference.name }, 'reference');
-    }
-    else {
-        coordinate = memberCoordinate({
-            origin: source.origin,
-            kind: reference.kind,
-            name: reference.name,
-        });
-    }
-    if (meaningForCoordinate(context, coordinate) === undefined) {
-        return invalidMemberRoot(key, index, 'does not exist in the source');
-    }
-    return coordinate;
-}
-function invalidMemberRoot(key, index, reason) {
-    throw new SchemaError([
-        diagnostic('DM_MEMBER_ROOT_INVALID', `/roots/${index}`, `Member comparison root ${JSON.stringify(key)} ${reason}.`, typeof key === 'string' ? key : undefined),
-    ]);
-}
-function levelOf(site) {
-    return site === 'extends' || site === 'core' ? 'inherit' : 'reference';
-}
-function classCoordinate(ref, level) {
-    return Object.freeze({ kind: 'class', key: keyForDefinitionRef(ref), ref, level });
-}
-function memberCoordinate(ref) {
-    return Object.freeze({ kind: 'member', key: keyForDefinitionRef(ref), ref });
-}
-function propertyCoordinate(owner, name) {
-    return Object.freeze({ kind: 'property', key: PropertyKey.of(owner, name), owner, name });
-}
-function methodCoordinate(owner, name) {
-    return Object.freeze({ kind: 'method', key: MethodKey.of(owner, name), owner, name });
-}
-function keyForDefinitionRef(ref) {
-    return ref.kind === 'core'
-        ? Key.of(ref)
-        : Key.of(ref);
+export function fingerprintMeaning(value) {
+    return digestDomainSchemaBytes(json.encode(value));
 }
-function keyReference(key) {
-    const semantic = key.slice(key.indexOf(':') + 1);
-    const parts = semantic.split('.');
-    if (parts[0] === 'core' && parts.length === 2) {
-        return { kind: 'core', name: parts[1] };
-    }
-    if (parts.length === 2) {
-        return { kind: parts[0], name: parts[1] };
-    }
-    if (parts.length === 4 &&
-        parts[0] === 'class' &&
-        (parts[2] === 'property' || parts[2] === 'method')) {
-        return {
-            kind: 'class',
-            name: parts[3],
-            member: parts[2],
-            ownerKind: 'class',
-            ownerName: parts[1],
-        };
-    }
-    throw new SchemaError([
-        diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Key ${key} has no supported V1 shape.`, key),
-    ]);
+function ancestorKeys(context, ref) {
+    const seen = new Set();
+    const visit = (current) => {
+        const declaration = context.schemas.get(current.origin)?.classes[current.name];
+        if (declaration === undefined)
+            return;
+        for (const parent of declaration.extends) {
+            const key = keyForDefinitionRef(parent);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            visit(parent);
+        }
+    };
+    visit(ref);
+    return [...seen].sort(compareUnicode);
 }
 function incidentCoreEdges(owner, name) {
     return owner.core.edges.filter((edge) => (edge.source.kind === 'core' && edge.source.name === name) ||
         (edge.target.kind === 'core' && edge.target.name === name));
 }
-function fingerprintMeaning(value) {
-    return digestDomainSchemaBytes(json.encode(value));
-}
 function isJsonSchema(value) {
     return typeof value === 'boolean' || isJsonObject(value);
 }