@astrale-os/kernel-dsl 0.2.0-beta.4 → 0.2.0-beta.40

package/dist/v1/schema/compatibility/comparators/callables.js

@@ -0,0 +1,84 @@
+import { isBinaryInput } from '../../../language/callable/model/callable.js';
+import { methodSignature as inheritedSignature } from '../../analysis/class.js';
+import { deepFreeze } from '../../canonical/freeze.js';
+import { keyForDefinitionRef } from '../coordinate.js';
+import { CALLABLE_FIELDS, fieldsOf } from '../fields.js';
+import { fingerprintMeaning, semanticValueSchema } from './values.js';
+export function methodExistence(method) {
+    return deepFreeze({
+        coordinate: 'method',
+        owner: keyForDefinitionRef(method.owner),
+        name: method.name,
+        static: method.declaration.static,
+        abstract: method.declaration.abstract,
+    });
+}
+export function methodSignature(method) {
+    return deepFreeze({
+        coordinate: 'method',
+        owner: keyForDefinitionRef(method.owner),
+        name: method.name,
+        ...callableSignature(method.declaration),
+    });
+}
+export function methodInheritance(method) {
+    return deepFreeze({
+        coordinate: 'method',
+        owner: keyForDefinitionRef(method.owner),
+        name: method.name,
+        abstract: method.declaration.abstract,
+        ...inheritedSignature(method.declaration),
+    });
+}
+export function functionSignature(declaration) {
+    return deepFreeze({
+        coordinate: 'function',
+        ...callableSignature(declaration),
+    });
+}
+export function functionExistence() {
+    return Object.freeze({ coordinate: 'function' });
+}
+/**
+ * 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,
+            ...callableSignature(callable),
+        }
+        : { kind: 'function', key: callable.key, ...callableSignature(callable) });
+}
+/** The `always` fields of CALLABLE_FIELDS: dispatch shape and the semantic input and output. */
+export function callableSignature(declaration) {
+    return {
+        ...fieldsOf({ declaration, roles: CALLABLE_FIELDS }),
+        input: isBinaryInput(declaration.input)
+            ? {
+                mode: 'binary',
+                metadata: semanticValueSchema(declaration.input.metadata),
+                maximumBytes: declaration.input.maximumBytes,
+            }
+            : semanticValueSchema(declaration.input),
+        output: semanticOutput(declaration.output),
+    };
+}
+function semanticOutput(output) {
+    switch (output.mode) {
+        case 'value':
+            return { mode: 'value', schema: semanticValueSchema(output.schema) };
+        case 'stream':
+            return { mode: 'stream', item: semanticValueSchema(output.item) };
+        case 'binary':
+            return { mode: 'binary' };
+    }
+}

package/dist/v1/schema/compatibility/comparators/classes.d.ts

@@ -0,0 +1,28 @@
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { Key as SemanticKey } from '../../../addressing/index.js';
+import type { EffectiveField } from '../../analysis/class.js';
+import type { Context } from '../context.js';
+import type { ClassCoordinate } from '../coordinate.js';
+import type { DependencyMeaningLevel } from '../fields.js';
+import type { Report } from '../report.js';
+import type { ComparisonContext, SubjectPair } from '../scope.js';
+export interface ClassRequirement {
+    readonly ancestors: readonly SemanticKey[];
+}
+/**
+ * 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.
+ */
+export declare function classMeaning(context: Context, coordinate: ClassCoordinate, level: DependencyMeaningLevel, onto?: ClassRequirement): {
+    readonly meaning: JsonValue;
+    readonly requirement: ClassRequirement;
+} | undefined;
+export declare function propertyMeaning(field: EffectiveField): JsonValue;
+/** Newly required data is an obligation even though it was absent from the source footprint. */
+export declare function compareAddedProperties({ context, pair, report, }: {
+    readonly context: ComparisonContext;
+    readonly pair: SubjectPair;
+    readonly report: Report;
+}): void;

package/dist/v1/schema/compatibility/comparators/classes.js

@@ -0,0 +1,96 @@
+import { compareUnicode } from '../../../addressing/ordering.js';
+import { deepFreeze } from '../../canonical/freeze.js';
+import { effectiveDefinition } from '../context.js';
+import { propertyCoordinate } from '../coordinate.js';
+import { keyForDefinitionRef } from '../coordinate.js';
+import { CLASS_FIELDS, PROPERTY_FIELDS, fieldsOf } from '../fields.js';
+import { usageOf } from '../references.js';
+import { semanticValueSchema } from './values.js';
+/**
+ * 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.
+ */
+export function classMeaning(context, coordinate, level, 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);
+    if (owner === undefined || declaration === undefined || analysis === undefined)
+        return undefined;
+    const ancestors = ancestorKeys(context, coordinate.ref);
+    const requirement = Object.freeze({
+        ancestors,
+    });
+    const meaning = {
+        coordinate: 'class',
+        level: level,
+        ...fieldsOf({ declaration, roles: CLASS_FIELDS, level }),
+        ...(level === 'inherit'
+            ? {
+                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)])),
+                ...(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: deepFreeze(meaning), requirement };
+}
+export function propertyMeaning(field) {
+    return deepFreeze({
+        coordinate: 'property',
+        owner: keyForDefinitionRef(field.owner),
+        name: field.name,
+        ...fieldsOf({ declaration: field, roles: PROPERTY_FIELDS }),
+        schema: semanticValueSchema(field.schema),
+    });
+}
+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);
+}
+/** Newly required data is an obligation even though it was absent from the source footprint. */
+export function compareAddedProperties({ context, pair, report, }) {
+    if (pair.source?.kind !== 'class' || pair.target?.kind !== 'class')
+        return;
+    for (const field of pair.target.analysis.properties.values()) {
+        if (pair.source.analysis.properties.has(field.identity) ||
+            !field.required ||
+            field.auto !== undefined)
+            continue;
+        const coordinate = propertyCoordinate(field.owner, field.name);
+        report.note({ coordinate, usage: usageOf(pair.source.schema, 'member', pair.coordinate.key) });
+        report.record({
+            pair: context.pair(coordinate),
+            facet: 'property.required',
+            after: propertyMeaning(field),
+            requirement: { kind: 'property.required', satisfied: false },
+        });
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { Facet } from '../model.js';
+import type { ComparisonContext, SubjectPair } from '../scope.js';
+/** Shared facet comparisons know declarations, never installation or an analysis mode. */
+export declare function compareFacet({ context, pair, facet, }: {
+    readonly context: ComparisonContext;
+    readonly pair: SubjectPair;
+    readonly facet: Exclude<Facet, 'class.composition' | 'property.required'>;
+}): {
+    readonly before?: Value;
+    readonly after?: Value;
+};

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

@@ -0,0 +1,41 @@
+import { methodInheritance, functionSignature, functionExistence, methodSignature, methodExistence, } from './callables.js';
+import { classMeaning, propertyMeaning } from './classes.js';
+import { memberMeaning } from './members.js';
+/** Shared facet comparisons know declarations, never installation or an analysis mode. */
+export function compareFacet({ context, pair, facet, }) {
+    if (facet === 'class.reference' || facet === 'class.inherit') {
+        if (pair.coordinate.kind !== 'class')
+            throw new TypeError('Class facet requires a Class coordinate.');
+        const level = facet === 'class.inherit' ? 'inherit' : 'reference';
+        const before = classMeaning(context.before, pair.coordinate, level);
+        const after = classMeaning(context.after, pair.coordinate, level, before?.requirement);
+        return { before: before?.meaning, after: after?.meaning };
+    }
+    const value = (subject) => {
+        if (subject === undefined)
+            return undefined;
+        switch (facet) {
+            case 'property':
+                return subject.kind === 'property' ? propertyMeaning(subject.field) : undefined;
+            case 'method.existence':
+                return subject.kind === 'method' ? methodExistence(subject.method) : undefined;
+            case 'method.signature':
+                return subject.kind === 'method' ? methodSignature(subject.method) : undefined;
+            case 'method.inheritance':
+                return subject.kind === 'method' ? methodInheritance(subject.method) : undefined;
+            case 'function.existence':
+                return functionExistence();
+            case 'function.signature':
+                return subject.kind === 'member'
+                    ? functionSignature(subject.schema.functions[subject.coordinate.ref.name])
+                    : undefined;
+            case 'policy':
+            case 'view':
+            case 'core':
+                return subject.kind === 'member'
+                    ? memberMeaning(subject.schema, subject.coordinate.ref)
+                    : undefined;
+        }
+    };
+    return { before: value(pair.source), after: value(pair.target) };
+}

package/dist/v1/schema/compatibility/comparators/members.d.ts

@@ -0,0 +1,4 @@
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { DomainSchema } from '../../model/schema.js';
+import type { MemberRef } from '../coordinate.js';
+export declare function memberMeaning(owner: DomainSchema, ref: MemberRef): JsonValue | undefined;

package/dist/v1/schema/compatibility/comparators/members.js

@@ -0,0 +1,49 @@
+import { deepFreeze } from '../../canonical/freeze.js';
+import { CORE_FIELDS, POLICY_FIELDS, VIEW_FIELDS, fieldsOf } from '../fields.js';
+import { functionSignature } from './callables.js';
+export function memberMeaning(owner, ref) {
+    const meaning = memberMeaningOf(owner, ref);
+    return meaning === undefined ? undefined : deepFreeze(meaning);
+}
+function memberMeaningOf(owner, ref) {
+    if (ref.origin !== owner.origin)
+        return undefined;
+    switch (ref.kind) {
+        case 'function': {
+            const declaration = owner.functions[ref.name];
+            return declaration === undefined ? undefined : functionSignature(declaration);
+        }
+        case 'policy': {
+            const declaration = owner.policies[ref.name];
+            return declaration === undefined
+                ? undefined
+                : {
+                    coordinate: 'policy',
+                    ...fieldsOf({ declaration, roles: POLICY_FIELDS }),
+                };
+        }
+        case 'view': {
+            const declaration = owner.views[ref.name];
+            return declaration === undefined
+                ? undefined
+                : {
+                    coordinate: 'view',
+                    ...fieldsOf({ declaration, roles: VIEW_FIELDS }),
+                };
+        }
+        case 'core': {
+            const node = owner.core.nodes[ref.name];
+            return node === undefined
+                ? undefined
+                : {
+                    coordinate: 'core',
+                    ...fieldsOf({ declaration: node, roles: CORE_FIELDS }),
+                    edges: incidentCoreEdges(owner, ref.name).map((edge) => fieldsOf({ declaration: edge, roles: CORE_FIELDS })),
+                };
+        }
+    }
+}
+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));
+}

package/dist/v1/schema/compatibility/comparators/values.d.ts

@@ -0,0 +1,5 @@
+import type { JsonSchema } from '../../../language/value/model/schema.js';
+import type { Fingerprint } from '../model.js';
+/** Drop annotation keywords wherever a schema keyword nests a schema; never inside data. */
+export declare function semanticValueSchema(value: JsonSchema): JsonSchema;
+export declare function fingerprintMeaning(value: unknown): Fingerprint;

package/dist/v1/schema/compatibility/comparators/values.js

@@ -0,0 +1,37 @@
+import { json } from '@astrale-os/kernel-dsl/value';
+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 { ANNOTATION_KEYWORDS } from '../fields.js';
+/** 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 (ANNOTATION_KEYWORDS.includes(keyword))
+            continue;
+        if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(entry)) {
+            semantic[keyword] = semanticValueSchema(entry);
+        }
+        else if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(entry)) {
+            semantic[keyword] = entry.map((item) => isJsonSchema(item) ? semanticValueSchema(item) : item);
+        }
+        else if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(entry)) {
+            semantic[keyword] = Object.fromEntries(Object.entries(entry).map(([name, item]) => [
+                name,
+                isJsonSchema(item) ? semanticValueSchema(item) : item,
+            ]));
+        }
+        else {
+            semantic[keyword] = entry;
+        }
+    }
+    return semantic;
+}
+export function fingerprintMeaning(value) {
+    return digestDomainSchemaBytes(json.encode(value));
+}
+function isJsonSchema(value) {
+    return typeof value === 'boolean' || isJsonObject(value);
+}

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,23 @@
+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({
+        scope: context.scope,
+        entries: mergeEntries(structure.entries, meaning.entries),
+        structure,
+        meaning,
+        evidence: Object.freeze({ structure: structure.evidence, meaning: meaning.evidence }),
+    });
+}
+export function compareStructure(request) {
+    return analyzeStructure(prepare(request));
+}
+export function compareMeaning(request) {
+    return analyzeMeaning(prepare(request));
+}

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

@@ -0,0 +1,15 @@
+import type { ClassRef, DefinitionRef, Key as SemanticKey } from '../../addressing/index.js';
+import type { DefinitionAnalysis, EffectiveMethod } from '../analysis/class.js';
+import type { DomainSchema } from '../model/schema.js';
+import { SchemaError } from '../diagnostic.js';
+/** One accepted root with its exact closure and a memoized semantic analysis per owner. */
+export interface Context {
+    readonly schemas: ReadonlyMap<string, DomainSchema>;
+    analysis(owner: DomainSchema): ReadonlyMap<string, DefinitionAnalysis> | undefined;
+}
+export declare function contextOf(root: DomainSchema): Context;
+export declare function effectiveDefinition(context: Context, owner: DomainSchema, ref: ClassRef): DefinitionAnalysis | undefined;
+/** Effective Methods are keyed by name; a coordinate names one by its exact Method Key. */
+export declare function effectiveMethod(analysis: DefinitionAnalysis, key: SemanticKey): EffectiveMethod | undefined;
+export declare function requireOwner(context: Context, ref: DefinitionRef, key: SemanticKey): DomainSchema;
+export declare function contextInvalid(message: string, key: SemanticKey): SchemaError;

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

@@ -0,0 +1,43 @@
+import { MethodKey } from '../../addressing/index.js';
+import { definitionRefIndex } from '../../addressing/ordering.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+import { knownDomainClosure, lookupForDomainClosure } from '../resolution/closure.js';
+import { validateDomainSchemaSemantics } from '../validation/domain.js';
+export 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);
+        },
+    };
+}
+export function effectiveDefinition(context, owner, ref) {
+    return context.analysis(owner)?.get(definitionRefIndex(ref));
+}
+/** Effective Methods are keyed by name; a coordinate names one by its exact Method Key. */
+export function effectiveMethod(analysis, key) {
+    for (const method of analysis.methods.values()) {
+        if (MethodKey.of(method.owner, method.name) === key)
+            return method;
+    }
+    return undefined;
+}
+export 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;
+}
+export function contextInvalid(message, key) {
+    return new SchemaError([diagnostic('DM_DEPENDENCY_CONTEXT_INVALID', '', message, key)]);
+}

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

@@ -0,0 +1,39 @@
+import type { ClassRef, Definition, DefinitionRef, Key as SemanticKey, PropertyKey as SemanticPropertyKey } from '../../addressing/index.js';
+export type MemberRef = DefinitionRef<Exclude<Definition.Kind, 'class'>>;
+export type ClassCoordinate = Readonly<{
+    kind: 'class';
+    key: SemanticKey;
+    ref: ClassRef;
+}>;
+export type MemberCoordinate = Readonly<{
+    kind: 'member';
+    key: SemanticKey;
+    ref: MemberRef;
+}>;
+export type PropertyCoordinate = Readonly<{
+    kind: 'property';
+    key: SemanticPropertyKey;
+    owner: ClassRef;
+    name: string;
+}>;
+export type MethodCoordinate = Readonly<{
+    kind: 'method';
+    key: SemanticKey;
+    owner: ClassRef;
+    name: string;
+}>;
+/** One exact semantic location, independent of how a dependent uses it. */
+export type Coordinate = ClassCoordinate | MemberCoordinate | PropertyCoordinate | MethodCoordinate;
+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;
+export declare function keyForDefinitionRef(ref: DefinitionRef): SemanticKey;
+export interface ParsedKeyReference {
+    readonly kind: Definition.Kind;
+    readonly name: string;
+    readonly member?: 'property' | 'method';
+    readonly ownerName?: string;
+}
+/** Interpret one canonical V1 Key as a Definition or a Class member location. */
+export declare function keyReference(key: SemanticKey): ParsedKeyReference;

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

@@ -0,0 +1,38 @@
+import { Key, MethodKey, PropertyKey } from '../../addressing/index.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+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 });
+}
+export function propertyCoordinate(owner, name) {
+    return Object.freeze({ kind: 'property', key: PropertyKey.of(owner, name), owner, name });
+}
+export function methodCoordinate(owner, name) {
+    return Object.freeze({ kind: 'method', key: MethodKey.of(owner, name), owner, name });
+}
+export function keyForDefinitionRef(ref) {
+    return ref.kind === 'core'
+        ? Key.of(ref)
+        : Key.of(ref);
+}
+/** Interpret one canonical V1 Key as a Definition or a Class member location. */
+export 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], ownerName: parts[1] };
+    }
+    throw new SchemaError([
+        diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Key ${key} has no supported V1 shape.`, key),
+    ]);
+}

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

@@ -0,0 +1,12 @@
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+/**
+ * One exact place where two meanings differ, addressed by JSON Pointer into the meaning value.
+ * An absent side is omitted: `before` only means removed, `after` only means added.
+ */
+export interface MeaningDifference {
+    readonly path: string;
+    readonly before?: JsonValue;
+    readonly after?: JsonValue;
+}
+/** Structural differences between two portable values, leaf by leaf, in JSON Pointer order. */
+export declare function differences(before: JsonValue, after: JsonValue): readonly MeaningDifference[];

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

@@ -0,0 +1,39 @@
+import { compareUnicode } from '../../addressing/ordering.js';
+import { isValueObject as isJsonObject } from '../../language/value/model/object.js';
+/** Structural differences between two portable values, leaf by leaf, in JSON Pointer order. */
+export function differences(before, after) {
+    const found = [];
+    collect(before, after, '', found);
+    return Object.freeze(found.sort((left, right) => compareUnicode(left.path, right.path)));
+}
+function collect(before, after, path, found) {
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const length = Math.max(before.length, after.length);
+        for (let index = 0; index < length; index += 1) {
+            collect(before[index], after[index], `${path}/${index}`, found);
+        }
+        return;
+    }
+    if (isJsonObject(before) && isJsonObject(after)) {
+        const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort(compareUnicode);
+        for (const key of keys) {
+            collect(before[key], after[key], `${path}/${escape(key)}`, found);
+        }
+        return;
+    }
+    if (before === undefined && after === undefined)
+        return;
+    if (before !== undefined &&
+        after !== undefined &&
+        JSON.stringify(before) === JSON.stringify(after)) {
+        return;
+    }
+    found.push(Object.freeze({
+        path,
+        ...(before === undefined ? {} : { before }),
+        ...(after === undefined ? {} : { after }),
+    }));
+}
+function escape(segment) {
+    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}

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;
+    }
+}