@astrale-os/kernel-dsl 0.2.0-beta.38 → 0.2.0-beta.39

package/dist/v1/schema/compatibility/compare.d.ts

@@ -1,57 +1,5 @@
-import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
-import type { Definition, Key as SemanticKey, Revision } from '../../addressing/index.js';
-import type { DomainSchema } from '../model/schema.js';
-import type { MeaningDifference } from './diff.js';
-import type { DependencyMeaningLevel } from './fields.js';
-import type { MeaningFingerprint } from './meaning.js';
-export type DependencyMeaningChangeKind = 'missing' | 'changed' | 'added';
-export type DependencyMeaningChange = {
-    readonly key: SemanticKey;
-    readonly kind: 'missing';
-    readonly sourceFingerprint: MeaningFingerprint;
-} | {
-    readonly key: SemanticKey;
-    readonly kind: 'changed';
-    readonly sourceFingerprint: MeaningFingerprint;
-    readonly targetFingerprint: MeaningFingerprint;
-    /** Every exact path of the meaning that differs, in JSON Pointer order. */
-    readonly differences: readonly MeaningDifference[];
-} | {
-    /** A required, non-automatic Property the target adds to an inherited Class. */
-    readonly key: SemanticKey;
-    readonly kind: 'added';
-    readonly targetFingerprint: MeaningFingerprint;
-    readonly meaning: JsonValue;
-};
-export interface DependencyMeaningComparison {
-    readonly version: 3;
-    readonly dependency: SemanticKey.Origin;
-    readonly source: Revision;
-    readonly target: Revision;
-    readonly footprint: readonly SemanticKey[];
-    readonly changes: readonly DependencyMeaningChange[];
-    readonly fingerprint: MeaningFingerprint;
-}
-/** One footprint entry: the Key, what it is, and for a Class how strongly it is used. */
-export interface FootprintEntry {
-    readonly key: SemanticKey;
-    readonly kind: Definition.Kind | 'property' | 'method';
-    readonly level?: DependencyMeaningLevel;
-}
-/**
- * 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.
- */
-export declare function compareDependencyMeaning(dependent: DomainSchema, target: DomainSchema): DependencyMeaningComparison;
-/** Compare one explicit non-empty source member surface and its reachable V1 meaning. */
-export declare function compareMemberMeaning(source: DomainSchema, target: DomainSchema, roots: readonly [SemanticKey, ...SemanticKey[]]): DependencyMeaningComparison;
-/** The footprint one accepted Domain takes from a retained dependency, Key-ordered. */
-export declare function footprintOf(dependent: DomainSchema, origin: SemanticKey.Origin): readonly FootprintEntry[];
-/**
- * The meaning one Domain gives one of its own Keys at a usage level; a Key the Domain does not
- * declare is rejected with DM_MEMBER_ROOT_INVALID.
- */
-export declare function meaningOf(schema: DomainSchema, key: SemanticKey, level?: DependencyMeaningLevel): JsonValue;
-/** One line an operator can act on, naming the exact paths of a changed meaning. */
-export declare function describeMeaningChange(change: DependencyMeaningChange): string;
+import type { Comparison, ComparisonRequest, MeaningComparison, StructureComparison } from './model.js';
+/** Complete facts and independent conclusions, resolved against the same exact contexts. */
+export declare function compare(request: ComparisonRequest): Comparison;
+export declare function compareStructure(request: ComparisonRequest): StructureComparison;
+export declare function compareMeaning(request: ComparisonRequest): MeaningComparison;

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

@@ -1,166 +1,23 @@
-import { compareUnicode } from '../../addressing/ordering.js';
-import { revisionOfDomainSchema } from '../canonical/revision.js';
-import { SchemaError, diagnostic } from '../diagnostic.js';
-import { knownDomainClosure } from '../resolution/closure.js';
-import { resolve } from '../resolution/domain.js';
-import { contextOf, effectiveDefinition } from './context.js';
-import { differences } from './diff.js';
-import { collectReachableMeanings, collectSchemaRoots, coordinateForKey } from './footprint.js';
-import { fingerprintMeaning, meaningForCoordinate, propertyMeaning } from './meaning.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.
- */
-export function compareDependencyMeaning(dependent, target) {
-    const { source, meanings } = retainedMeanings(dependent, target.origin, '/target/origin');
-    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);
-}
-/** The footprint one accepted Domain takes from a retained dependency, Key-ordered. */
-export function footprintOf(dependent, origin) {
-    const { meanings } = retainedMeanings(dependent, origin, '/origin');
-    return Object.freeze([...meanings.values()]
-        .map(({ coordinate }) => Object.freeze({
-        key: coordinate.key,
-        kind: coordinate.kind === 'member' ? coordinate.ref.kind : coordinate.kind,
-        ...(coordinate.kind === 'class' ? { level: coordinate.level } : {}),
-    }))
-        .sort((left, right) => compareUnicode(left.key, right.key)));
-}
-/**
- * The meaning one Domain gives one of its own Keys at a usage level; a Key the Domain does not
- * declare is rejected with DM_MEMBER_ROOT_INVALID.
- */
-export function meaningOf(schema, key, level = 'reference') {
-    resolve(schema);
-    const context = contextOf(schema);
-    const coordinate = coordinateForKey(context, schema, key, 0, level);
-    return meaningForCoordinate(context, coordinate);
-}
-/** One line an operator can act on, naming the exact paths of a changed meaning. */
-export function describeMeaningChange(change) {
-    switch (change.kind) {
-        case 'missing':
-            return `${change.key} missing`;
-        case 'added':
-            return `${change.key} added as an obligation`;
-        case 'changed': {
-            const paths = change.differences.map(({ path }) => path);
-            const shown = paths.slice(0, 3).join(', ');
-            return `${change.key} changed at ${paths.length > 3 ? `${shown} and ${paths.length - 3} more` : shown}`;
-        }
-    }
-}
-/** The retained dependency at one origin and every meaning the dependent reaches in it. */
-function retainedMeanings(dependent, origin, path) {
-    resolve(dependent);
-    const context = contextOf(dependent);
-    const source = (knownDomainClosure(dependent) ?? []).find((candidate) => candidate.schema.origin === origin)?.schema;
-    if (source === undefined) {
-        throw new SchemaError([
-            diagnostic('DM_DEPENDENCY_NOT_RETAINED', path, `Domain ${dependent.origin} was not admitted with a dependency at ${origin}.`),
-        ]);
-    }
-    return {
-        source,
-        meanings: collectReachableMeanings(collectSchemaRoots(dependent), source.origin, context),
-    };
-}
-/**
- * A footprint coordinate is unchanged only when the same Key exists in the target with the same
- * meaning projected onto the source requirement of its usage level. Additions outside the
- * footprint are free; a required non-automatic Property the target adds to an inherited Class is
- * the one addition reported, as an obligation.
- */
-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 (targetMeaning === undefined || 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,
-                differences: differences(sourceMeaning.meaning, targetMeaning),
-            }));
-        }
-    }
-    const additions = addedObligations(context, sourceMeanings);
-    const sourceRevision = revisionOfDomainSchema(source);
-    const targetRevision = revisionOfDomainSchema(target);
-    const fingerprint = fingerprintMeaning({
-        version: 3,
-        dependency: source.origin,
-        source: sourceRevision,
-        target: targetRevision,
-        coordinates: comparisonCoordinates,
-        additions: additions.map(({ key, targetFingerprint }) => [key, targetFingerprint]),
-    });
+import { analyzeMeaning } from './meaning/index.js';
+import { mergeEntries } from './report.js';
+import { prepare } from './scope.js';
+import { analyzeStructure } from './structure/index.js';
+/** Complete facts and independent conclusions, resolved against the same exact contexts. */
+export function compare(request) {
+    const context = prepare(request);
+    const structure = analyzeStructure(context);
+    const meaning = analyzeMeaning(context);
     return Object.freeze({
-        version: 3,
-        dependency: source.origin,
-        source: sourceRevision,
-        target: targetRevision,
-        footprint,
-        changes: Object.freeze([...changes, ...additions]),
-        fingerprint,
+        scope: context.scope,
+        entries: mergeEntries(structure.entries, meaning.entries),
+        structure,
+        meaning,
+        evidence: Object.freeze({ structure: structure.evidence, meaning: meaning.evidence }),
     });
 }
-/** 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;
-            const meaning = propertyMeaning(field);
-            additions.set(field.identity, Object.freeze({
-                key: field.identity,
-                kind: 'added',
-                targetFingerprint: fingerprintMeaning(meaning),
-                meaning,
-            }));
-        }
-    }
-    return [...additions.values()].sort((left, right) => compareUnicode(left.key, right.key));
+export function compareStructure(request) {
+    return analyzeStructure(prepare(request));
+}
+export function compareMeaning(request) {
+    return analyzeMeaning(prepare(request));
 }

package/dist/v1/schema/compatibility/coordinate.d.ts

@@ -1,12 +1,9 @@
 import type { ClassRef, Definition, DefinitionRef, Key as SemanticKey, PropertyKey as SemanticPropertyKey } from '../../addressing/index.js';
-import type { ReferenceSite } from '../resolution/origins.js';
-import type { DependencyMeaningLevel } from './fields.js';
 export type MemberRef = DefinitionRef<Exclude<Definition.Kind, 'class'>>;
 export type ClassCoordinate = Readonly<{
     kind: 'class';
     key: SemanticKey;
     ref: ClassRef;
-    level: DependencyMeaningLevel;
 }>;
 export type MemberCoordinate = Readonly<{
     kind: 'member';
@@ -25,11 +22,9 @@ export type MethodCoordinate = Readonly<{
     owner: ClassRef;
     name: string;
 }>;
-/** One exact semantic location of a dependency, as the dependent reaches it. */
+/** One exact semantic location, independent of how a dependent uses it. */
 export type Coordinate = ClassCoordinate | MemberCoordinate | PropertyCoordinate | MethodCoordinate;
-/** `extends` and Core instantiation take on the creation contract; every other site only refers. */
-export declare function levelOf(site: ReferenceSite | undefined): DependencyMeaningLevel;
-export declare function classCoordinate(ref: ClassRef, level: DependencyMeaningLevel): ClassCoordinate;
+export declare function classCoordinate(ref: ClassRef): ClassCoordinate;
 export declare function memberCoordinate(ref: MemberRef): MemberCoordinate;
 export declare function propertyCoordinate(owner: ClassRef, name: string): PropertyCoordinate;
 export declare function methodCoordinate(owner: ClassRef, name: string): MethodCoordinate;

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

@@ -1,11 +1,7 @@
 import { Key, MethodKey, PropertyKey } from '../../addressing/index.js';
 import { SchemaError, diagnostic } from '../diagnostic.js';
-/** `extends` and Core instantiation take on the creation contract; every other site only refers. */
-export function levelOf(site) {
-    return site === 'extends' || site === 'core' ? 'inherit' : 'reference';
-}
-export function classCoordinate(ref, level) {
-    return Object.freeze({ kind: 'class', key: keyForDefinitionRef(ref), ref, level });
+export function classCoordinate(ref) {
+    return Object.freeze({ kind: 'class', key: keyForDefinitionRef(ref), ref });
 }
 export function memberCoordinate(ref) {
     return Object.freeze({ kind: 'member', key: keyForDefinitionRef(ref), ref });

package/dist/v1/schema/compatibility/evidence.d.ts

@@ -0,0 +1,5 @@
+import type { Analysis, ComparisonEvidence } from './model.js';
+/** Only semantic facts and decisions are durable; provenance and diagnostic prose are not. */
+export declare function evidenceOf({ kind, scope, entries, assessments, }: Omit<Analysis, 'evidence'> & {
+    readonly kind: ComparisonEvidence['kind'];
+}): ComparisonEvidence;

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

@@ -0,0 +1,51 @@
+import { compareUnicode } from '../../addressing/ordering.js';
+import { fingerprintMeaning } from './comparators/values.js';
+/** Only semantic facts and decisions are durable; provenance and diagnostic prose are not. */
+export function evidenceOf({ kind, scope, entries, assessments, }) {
+    const version = kind === 'structure' ? 2 : 1;
+    return Object.freeze({
+        kind,
+        version,
+        fingerprint: fingerprintMeaning({
+            kind,
+            version,
+            scope: {
+                kind: scope.kind,
+                source: [scope.source.origin, scope.source.revision],
+                target: [scope.target.origin, scope.target.revision],
+                dependent: scope.dependent === undefined ? null : [scope.dependent.origin, scope.dependent.revision],
+                roots: scope.roots,
+            },
+            observations: entries.flatMap((entry) => [...entry.observations]
+                .sort((a, b) => compareUnicode(evidenceFacet(a.facet), evidenceFacet(b.facet)))
+                .map((observation) => [
+                entry.subject.key,
+                evidenceFacet(observation.facet),
+                observation.before === undefined ? null : fingerprintMeaning(observation.before),
+                observation.after === undefined ? null : fingerprintMeaning(observation.after),
+            ])),
+            assessments: [...assessments]
+                .sort((a, b) => compareUnicode(`${a.subject.key}#${evidenceFacet(a.observation.facet)}`, `${b.subject.key}#${evidenceFacet(b.observation.facet)}`) ||
+                compareUnicode(evidenceFacet(a.requirement.kind), evidenceFacet(b.requirement.kind)))
+                .map((assessment) => [
+                assessment.subject.key,
+                evidenceFacet(assessment.observation.facet),
+                evidenceFacet(assessment.requirement.kind),
+                assessment.satisfied,
+            ]),
+        }),
+    });
+}
+/** Version-1 evidence keeps its original tags independently of public facet names. */
+function evidenceFacet(facet) {
+    switch (facet) {
+        case 'method.signature':
+            return 'method.contract';
+        case 'function.signature':
+            return 'function.contract';
+        case 'method.inheritance':
+            return 'method.signature';
+        default:
+            return facet;
+    }
+}

package/dist/v1/schema/compatibility/fields.d.ts

@@ -178,3 +178,9 @@ export declare const FIELD_ROLES: Readonly<{
         target: "always";
     }>;
 }>;
+/** Classification drives projection; special semantic normalization stays with each comparator. */
+export declare function fieldsOf({ declaration, roles, level, }: {
+    readonly declaration: object;
+    readonly roles: Readonly<Record<string, FieldRole>>;
+    readonly level?: DependencyMeaningLevel;
+}): Readonly<Record<string, unknown>>;

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

@@ -81,3 +81,8 @@ export const FIELD_ROLES = Object.freeze({
     view: VIEW_FIELDS,
     core: CORE_FIELDS,
 });
+/** Classification drives projection; special semantic normalization stays with each comparator. */
+export function fieldsOf({ declaration, roles, level = 'reference', }) {
+    return Object.fromEntries(Object.entries(declaration).filter(([name, value]) => value !== undefined &&
+        (roles[name] === 'always' || (level === 'inherit' && roles[name] === 'inherit'))));
+}

package/dist/v1/schema/compatibility/index.d.ts

@@ -1,7 +1,8 @@
-export { compareDependencyMeaning, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './compare.js';
-export type { DependencyMeaningChange, DependencyMeaningChangeKind, DependencyMeaningComparison, FootprintEntry, } from './compare.js';
+export * from './api.js';
+export { compareDependencyMeaning, compareDependencyStructure, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './legacy/index.js';
+export type { DependencyMeaningChange, DependencyMeaningChangeKind, DependencyMeaningComparison, DependencyStructureComparison, FootprintEntry, } from './legacy/index.js';
 export type { MeaningDifference } from './diff.js';
 export { ANNOTATION_KEYWORDS, FIELD_ROLES } from './fields.js';
 export type { DependencyMeaningLevel, FieldRole } from './fields.js';
-export { callableFingerprint } from './meaning.js';
-export type { MeaningFingerprint } from './meaning.js';
+export { callableFingerprint } from './comparators/callables.js';
+export type { Fingerprint as MeaningFingerprint } from './model.js';

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

@@ -1,3 +1,4 @@
-export { compareDependencyMeaning, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './compare.js';
+export * from './api.js';
+export { compareDependencyMeaning, compareDependencyStructure, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './legacy/index.js';
 export { ANNOTATION_KEYWORDS, FIELD_ROLES } from './fields.js';
-export { callableFingerprint } from './meaning.js';
+export { callableFingerprint } from './comparators/callables.js';

package/dist/v1/schema/compatibility/legacy/index.d.ts

@@ -0,0 +1,58 @@
+/** Historical positional APIs and version-3 wire evidence. New analyses never depend on this adapter. */
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { Definition, Key as SemanticKey, Revision } from '../../../addressing/index.js';
+import type { DomainSchema } from '../../model/schema.js';
+import type { MeaningDifference } from '../diff.js';
+import type { DependencyMeaningLevel } from '../fields.js';
+import type { Fingerprint as MeaningFingerprint } from '../model.js';
+export type DependencyMeaningChangeKind = 'missing' | 'changed' | 'added';
+export type DependencyMeaningChange = {
+    readonly key: SemanticKey;
+    readonly kind: 'missing';
+    readonly sourceFingerprint: MeaningFingerprint;
+} | {
+    readonly key: SemanticKey;
+    readonly kind: 'changed';
+    readonly sourceFingerprint: MeaningFingerprint;
+    readonly targetFingerprint: MeaningFingerprint;
+    /** Every exact path of the meaning that differs, in JSON Pointer order. */
+    readonly differences: readonly MeaningDifference[];
+} | {
+    /** A required, non-automatic Property the target adds to an inherited Class. */
+    readonly key: SemanticKey;
+    readonly kind: 'added';
+    readonly targetFingerprint: MeaningFingerprint;
+    readonly meaning: JsonValue;
+};
+export interface DependencyMeaningComparison {
+    readonly version: 3;
+    readonly dependency: SemanticKey.Origin;
+    readonly source: Revision;
+    readonly target: Revision;
+    readonly footprint: readonly SemanticKey[];
+    readonly changes: readonly DependencyMeaningChange[];
+    readonly fingerprint: MeaningFingerprint;
+}
+/** One footprint entry: the Key, what it is, and for a Class how strongly it is used. */
+export interface FootprintEntry {
+    readonly key: SemanticKey;
+    readonly kind: Definition.Kind | 'property' | 'method';
+    readonly level?: DependencyMeaningLevel;
+}
+export interface DependencyStructureComparison {
+    readonly kind: 'structure';
+    readonly version: 1;
+    readonly dependency: SemanticKey.Origin;
+    readonly source: Revision;
+    readonly target: Revision;
+    readonly footprint: readonly SemanticKey[];
+    readonly changes: readonly DependencyMeaningChange[];
+    readonly fingerprint: MeaningFingerprint;
+}
+export declare function compareDependencyMeaning(dependent: DomainSchema, target: DomainSchema): DependencyMeaningComparison;
+export declare function compareMemberMeaning(source: DomainSchema, target: DomainSchema, roots: readonly [SemanticKey, ...SemanticKey[]]): DependencyMeaningComparison;
+export declare function compareDependencyStructure(dependent: DomainSchema, target: DomainSchema): DependencyStructureComparison;
+export declare function footprintOf(dependent: DomainSchema, origin: SemanticKey.Origin): readonly FootprintEntry[];
+export declare function meaningOf(schema: DomainSchema, key: SemanticKey, level?: DependencyMeaningLevel): JsonValue;
+/** One line an operator can act on, naming the exact paths of a changed meaning. */
+export declare function describeMeaningChange(change: DependencyMeaningChange): string;

package/dist/v1/schema/compatibility/legacy/index.js

@@ -0,0 +1,145 @@
+import { Key } from '../../../addressing/index.js';
+import { compareUnicode } from '../../../addressing/ordering.js';
+import { compareFacet } from '../comparators/index.js';
+import { fingerprintMeaning } from '../comparators/values.js';
+import { compareMeaning, compareStructure } from '../compare.js';
+import { prepare, retainedContext } from '../scope.js';
+export function compareDependencyMeaning(dependent, target) {
+    return legacyMeaning(compareMeaning({ scope: { kind: 'dependency', dependent }, target }));
+}
+export function compareMemberMeaning(source, target, roots) {
+    return legacyMeaning(compareMeaning({ scope: { kind: 'members', source, roots }, target }));
+}
+export function compareDependencyStructure(dependent, target) {
+    const report = compareStructure({ scope: { kind: 'dependency', dependent }, target });
+    const failed = new Set(report.assessments.filter((item) => !item.satisfied).map((item) => item.observation.id));
+    const changes = report.entries.flatMap((entry) => entry.observations.filter((item) => failed.has(item.id)).map((item) => changeOf(entry, item)));
+    return Object.freeze({
+        kind: 'structure',
+        version: 1,
+        dependency: report.scope.source.origin,
+        source: report.scope.source.revision,
+        target: report.scope.target.revision,
+        footprint: Object.freeze(report.entries
+            .filter((entry) => Key.origin(entry.subject.key) === report.scope.source.origin &&
+            entry.observations.some((item) => item.before !== undefined))
+            .map((entry) => entry.subject.key)),
+        changes: Object.freeze(changes),
+        fingerprint: report.evidence.fingerprint,
+    });
+}
+export function footprintOf(dependent, origin) {
+    const { source } = retainedContext(dependent, origin, '/origin');
+    const report = compareMeaning({ scope: { kind: 'dependency', dependent }, target: source });
+    return Object.freeze(report.entries.map((entry) => Object.freeze({
+        ...entry.subject,
+        ...(entry.subject.kind === 'class'
+            ? {
+                level: strongest(entry).facet === 'class.inherit'
+                    ? 'inherit'
+                    : 'reference',
+            }
+            : {}),
+    })));
+}
+export function meaningOf(schema, key, level = 'reference') {
+    const context = prepare({
+        scope: { kind: 'members', source: schema, roots: [key] },
+        target: schema,
+    });
+    const coordinate = context.roots[0].coordinate;
+    const facet = coordinate.kind === 'class'
+        ? level === 'inherit'
+            ? 'class.inherit'
+            : 'class.reference'
+        : coordinate.kind === 'method'
+            ? 'method.signature'
+            : coordinate.kind === 'property'
+                ? 'property'
+                : coordinate.ref.kind === 'function'
+                    ? 'function.signature'
+                    : coordinate.ref.kind;
+    return compareFacet({ context, pair: context.pair(coordinate), facet }).before;
+}
+function strongest(entry) {
+    return (entry.observations.find((item) => item.facet === 'class.inherit') ??
+        entry.observations.find((item) => item.facet !== 'property.required') ??
+        entry.observations[0]);
+}
+function legacyMeaning(report) {
+    const coordinates = [];
+    const footprint = [];
+    const changes = [];
+    const additions = [];
+    for (const entry of report.entries) {
+        const added = entry.observations.find((item) => item.facet === 'property.required');
+        if (added !== undefined)
+            additions.push(changeOf(entry, added));
+        const observation = strongest(entry);
+        const change = changeOf(entry, observation);
+        if (observation.before === undefined) {
+            continue;
+        }
+        footprint.push(entry.subject.key);
+        coordinates.push([
+            entry.subject.key,
+            fingerprintMeaning(observation.before),
+            observation.after === undefined ? null : fingerprintMeaning(observation.after),
+        ]);
+        if (change !== undefined)
+            changes.push(change);
+    }
+    additions.sort((a, b) => compareUnicode(a.key, b.key));
+    const identity = {
+        version: 3,
+        dependency: report.scope.source.origin,
+        source: report.scope.source.revision,
+        target: report.scope.target.revision,
+    };
+    return Object.freeze({
+        ...identity,
+        footprint: Object.freeze(footprint),
+        changes: Object.freeze([...changes, ...additions]),
+        fingerprint: fingerprintMeaning({
+            ...identity,
+            coordinates,
+            additions: additions.map(({ key, targetFingerprint }) => [key, targetFingerprint]),
+        }),
+    });
+}
+function changeOf(entry, observation) {
+    const key = entry.subject.key;
+    if (observation.state === 'equal')
+        return undefined;
+    if (observation.before === undefined)
+        return Object.freeze({
+            key,
+            kind: 'added',
+            targetFingerprint: fingerprintMeaning(observation.after),
+            meaning: observation.after,
+        });
+    const sourceFingerprint = fingerprintMeaning(observation.before);
+    if (observation.after === undefined)
+        return Object.freeze({ key, kind: 'missing', sourceFingerprint });
+    return Object.freeze({
+        key,
+        kind: 'changed',
+        sourceFingerprint,
+        targetFingerprint: fingerprintMeaning(observation.after),
+        differences: observation.differences,
+    });
+}
+/** One line an operator can act on, naming the exact paths of a changed meaning. */
+export function describeMeaningChange(change) {
+    switch (change.kind) {
+        case 'missing':
+            return `${change.key} missing`;
+        case 'added':
+            return `${change.key} added as an obligation`;
+        case 'changed': {
+            const paths = change.differences.map(({ path }) => path);
+            const shown = paths.slice(0, 3).join(', ');
+            return `${change.key} changed at ${paths.length > 3 ? `${shown} and ${paths.length - 3} more` : shown}`;
+        }
+    }
+}

package/dist/v1/schema/compatibility/meaning/footprint.d.ts

@@ -0,0 +1,7 @@
+import type { Report } from '../report.js';
+import type { ComparisonContext } from '../scope.js';
+/** Meaning follows complete callable contracts through the exact authored reference closure. */
+export declare function compareFootprint({ context, report, }: {
+    readonly context: ComparisonContext;
+    readonly report: Report;
+}): void;