@astrale-os/kernel-dsl 0.2.0-beta.8 → 1.0.0-beta.1

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

@@ -0,0 +1,110 @@
+import { compareUnicode } from '../../addressing/ordering.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+import { knownDomainClosure } from '../resolution/closure.js';
+import { resolve } from '../resolution/domain.js';
+import { contextOf } from './context.js';
+import { policyReliance, rootReferences, schemaIdentity, usageOf } from './references.js';
+import { capabilityCoordinates, coordinateForKey, resolveSubject } from './subjects.js';
+export function prepare(request) {
+    const { scope, target } = request;
+    if (scope.kind === 'members') {
+        const { source, roots: keys } = scope;
+        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(keys) || keys.length === 0 || new Set(keys).size !== keys.length) {
+            throw new SchemaError([
+                diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', 'Member comparison roots must be one non-empty duplicate-free Key set.'),
+            ]);
+        }
+        return selectMembers(source, target, keys);
+    }
+    const { dependent } = scope;
+    const { source, context: before } = retainedContext(dependent, target.origin, '/target/origin');
+    const keys = scope.capabilities;
+    if (keys !== undefined && !Array.isArray(keys)) {
+        throw new SchemaError([
+            diagnostic('DM_CAPABILITY_INVALID', '/capabilities', 'Declared capabilities must be one Key list.'),
+        ]);
+    }
+    const usage = usageOf(dependent, 'capability');
+    const capabilities = capabilityCoordinates(before, source, keys ?? []).map((coordinate) => ({
+        coordinate,
+        usage,
+    }));
+    return comparisonContext({
+        kind: 'dependency',
+        source,
+        target,
+        dependent,
+        before,
+        roots: [...rootReferences(dependent), ...capabilities],
+        capabilities,
+        reliance: policyReliance(dependent, source.origin),
+    });
+}
+/**
+ * Select distinct Keys of the source against a target the caller checked to be of the same origin.
+ * The selection may be empty, which a public request cannot be: `requiredBump` selects every member
+ * of a version that may declare none.
+ */
+export function selectMembers(source, target, keys) {
+    resolve(source);
+    const before = contextOf(source);
+    return comparisonContext({
+        kind: 'members',
+        source,
+        target,
+        before,
+        roots: keys.map((key, index) => ({
+            coordinate: coordinateForKey(before, source, key, index),
+            usage: usageOf(source, 'selection', key),
+        })),
+        capabilities: [],
+        reliance: [],
+    });
+}
+function comparisonContext({ kind, source, target, dependent, before, roots, capabilities, reliance, }) {
+    resolve(target);
+    const after = contextOf(target);
+    const pairs = new Map();
+    return {
+        source,
+        target,
+        dependent,
+        before,
+        after,
+        roots,
+        capabilities,
+        reliance,
+        scope: Object.freeze({
+            kind,
+            source: schemaIdentity(source),
+            target: schemaIdentity(target),
+            ...(dependent === undefined ? {} : { dependent: schemaIdentity(dependent) }),
+            roots: Object.freeze([...new Set(roots.map(({ coordinate }) => coordinate.key))].sort(compareUnicode)),
+        }),
+        pair(coordinate) {
+            let pair = pairs.get(coordinate.key);
+            if (pair === undefined) {
+                pair = {
+                    coordinate,
+                    source: resolveSubject({ context: before, coordinate }),
+                    target: resolveSubject({ context: after, coordinate }),
+                };
+                pairs.set(coordinate.key, pair);
+            }
+            return pair;
+        },
+    };
+}
+function retainedContext(dependent, origin, path) {
+    resolve(dependent);
+    const source = (knownDomainClosure(dependent) ?? []).find((entry) => entry.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, context: contextOf(dependent) };
+}

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

@@ -0,0 +1,3 @@
+import type { StructureComparison } from '../model.js';
+import type { ComparisonContext } from '../scope.js';
+export declare function analyzeStructure(context: ComparisonContext): StructureComparison;

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

@@ -0,0 +1,40 @@
+import { evidenceOf } from '../evidence.js';
+import { createReport } from '../report.js';
+import { compareInheritance } from './inheritance.js';
+import { compareRequirements } from './requirements.js';
+export function analyzeStructure(context) {
+    const report = createReport();
+    compareRequirements({ context, report });
+    compareInheritance({ context, report });
+    const result = { scope: context.scope, ...report.finish() };
+    return Object.freeze({
+        kind: 'structure',
+        ...result,
+        compatible: result.assessments.every(({ satisfied }) => satisfied),
+        // Each version adds one requirement policy and applies only when its fact is present: 3 a
+        // declared capability root, 4 a lost effective Property of a reached Class or a failed Policy
+        // reliance, facts recorded only when they fail. Without one, evidence keeps its version-2 bytes.
+        evidence: evidenceOf({
+            kind: 'structure',
+            version: recordsFailureOnlyFact(result.assessments)
+                ? 4
+                : context.capabilities.length > 0
+                    ? 3
+                    : 2,
+            ...result,
+        }),
+    });
+}
+/**
+ * The facts structure records only when they fail: a referenced or inherited Class that lost an
+ * effective Property, and what a dependent Policy relies on (a Method object, a matched Edge's
+ * endpoints).
+ */
+const FAILURE_ONLY_FACETS = new Set([
+    'class.properties',
+    'method.object',
+    'class.endpoints',
+]);
+function recordsFailureOnlyFact(assessments) {
+    return assessments.some(({ requirement }) => FAILURE_ONLY_FACETS.has(requirement.kind));
+}

package/dist/v1/schema/compatibility/structure/inheritance.d.ts

@@ -0,0 +1,7 @@
+import type { Report } from '../report.js';
+import type { ComparisonContext } from '../scope.js';
+/** Recompose retained descendants using the same obligations as source and compiled admission. */
+export declare function compareInheritance({ context, report, }: {
+    readonly context: ComparisonContext;
+    readonly report: Report;
+}): void;

package/dist/v1/schema/compatibility/structure/inheritance.js

@@ -0,0 +1,68 @@
+import { json } from '@astrale-os/kernel-dsl/value';
+import { compareUnicode, definitionRefIndex } from '../../../addressing/ordering.js';
+import { composeMethods } from '../../../language/callable/composition.js';
+import { sameMethodSignature } from '../../analysis/class.js';
+import { methodInheritance } from '../comparators/callables.js';
+import { effectiveDefinition, requireOwner } from '../context.js';
+import { classCoordinate, keyForDefinitionRef } from '../coordinate.js';
+import { inherits, usageOf } from '../references.js';
+import { resolveSubject } from '../subjects.js';
+/** Recompose retained descendants using the same obligations as source and compiled admission. */
+export function compareInheritance({ context, report, }) {
+    if (context.dependent === undefined)
+        return;
+    const memo = new Map();
+    const visit = (ref) => {
+        const index = definitionRefIndex(ref);
+        const retained = memo.get(index);
+        if (retained !== undefined)
+            return retained;
+        const owner = requireOwner(context.before, ref, keyForDefinitionRef(ref));
+        const original = effectiveDefinition(context.before, owner, ref);
+        if (ref.origin === context.target.origin) {
+            const replacement = effectiveDefinition(context.after, context.target, ref);
+            return { composition: replacement ?? original, affected: replacement !== undefined };
+        }
+        const parents = original.declaration.extends.map(visit);
+        if (!parents.some((parent) => parent.affected)) {
+            const unchanged = { composition: original, affected: false };
+            memo.set(index, unchanged);
+            return unchanged;
+        }
+        const declaration = original.declaration;
+        const own = new Map(Object.keys(declaration.kind === 'node' ? declaration.methods : {}).map((name) => [
+            name,
+            original.methods.get(name),
+        ]));
+        const issues = [];
+        const composition = composeMethods(parents.map((parent) => parent.composition), own, declaration.abstract, (left, right) => sameMethodSignature(left.declaration, right.declaration), (_message, issue) => issues.push(issue));
+        const coordinate = classCoordinate(ref);
+        const subject = resolveSubject({ context: context.before, coordinate });
+        report.note({ coordinate, usage: usageOf(owner, 'extends', coordinate.key) });
+        report.record({
+            pair: { coordinate, source: subject, target: subject },
+            facet: 'class.composition',
+            before: compositionValue(original, []),
+            after: compositionValue(composition, issues),
+            requirement: { kind: 'class.composition', satisfied: issues.length === 0 },
+        });
+        const result = { composition, affected: true };
+        memo.set(index, result);
+        return result;
+    };
+    for (const declaration of Object.values(context.dependent.classes))
+        visit(declaration.ref);
+    for (const root of context.roots) {
+        if (root.coordinate.kind === 'class' && inherits(root.usage))
+            visit(root.coordinate.ref);
+    }
+}
+function compositionValue(composition, issues) {
+    return {
+        requirements: [...composition.requirements.values()]
+            .sort((a, b) => compareUnicode(a.key, b.key))
+            .map(methodInheritance),
+        frontier: [...composition.frontier.keys()].sort(compareUnicode),
+        issues: [...issues].sort((a, b) => compareUnicode(json.serialize(a), json.serialize(b))),
+    };
+}

package/dist/v1/schema/compatibility/structure/requirements.d.ts

@@ -0,0 +1,7 @@
+import type { Report } from '../report.js';
+import type { ComparisonContext } from '../scope.js';
+/** Structure follows data and abstract obligations; concrete IO never expands its requirements. */
+export declare function compareRequirements({ context, report, }: {
+    readonly context: ComparisonContext;
+    readonly report: Report;
+}): void;

package/dist/v1/schema/compatibility/structure/requirements.js

@@ -0,0 +1,97 @@
+import { Key } from '../../../addressing/index.js';
+import { compareAddedProperties, compareLostProperties } from '../comparators/classes.js';
+import { compareFacet } from '../comparators/index.js';
+import { fingerprintMeaning } from '../comparators/values.js';
+import { contextInvalid } from '../context.js';
+import { methodCoordinate } from '../coordinate.js';
+import { callableReferences, classReferences, inherits, memberReferences, usageOf, valueReferences, } from '../references.js';
+/** Structure follows data and abstract obligations; concrete IO never expands its requirements. */
+export function compareRequirements({ context, report, }) {
+    const queue = [...context.roots];
+    const visited = new Set();
+    for (const reference of queue) {
+        report.note(reference);
+        const { coordinate, usage } = reference;
+        const visit = `${coordinate.key}:${usage.relation}`;
+        if (visited.has(visit))
+            continue;
+        visited.add(visit);
+        const pair = context.pair(coordinate);
+        const subject = pair.source;
+        if (subject === undefined)
+            throw contextInvalid(`Retained acceptance context has no meaning for ${coordinate.key}.`, coordinate.key);
+        let facet;
+        switch (subject.kind) {
+            case 'class': {
+                facet = inherits(usage) ? 'class.inherit' : 'class.reference';
+                queue.push(...classReferences(subject, false));
+                if (inherits(usage)) {
+                    queue.push(...classReferences(subject, true));
+                    for (const method of subject.analysis.requirements.values())
+                        queue.push({
+                            coordinate: methodCoordinate(method.owner, method.name),
+                            usage: usageOf(subject.schema, 'abstract', coordinate.key),
+                        });
+                }
+                break;
+            }
+            case 'property':
+                facet = 'property';
+                queue.push(...valueReferences(subject));
+                break;
+            case 'method': {
+                facet = usage.relation === 'abstract' ? 'method.inheritance' : 'method.existence';
+                if (facet === 'method.inheritance')
+                    queue.push(...callableReferences(subject));
+                break;
+            }
+            case 'member': {
+                facet =
+                    subject.coordinate.ref.kind === 'function'
+                        ? 'function.existence'
+                        : subject.coordinate.ref.kind;
+                if (facet !== 'function.existence')
+                    queue.push(...memberReferences(subject));
+            }
+        }
+        if (Key.origin(coordinate.key) !== context.source.origin)
+            continue;
+        // Class membership does not establish an invocation dependency. Explicit member selection,
+        // a Method the dependent declares as a capability, and inherited abstract obligations do.
+        const required = facet !== 'method.existence' ||
+            usage.relation === 'selection' ||
+            usage.relation === 'capability';
+        report.record({
+            pair,
+            facet,
+            ...compareFacet({ context, pair, facet }),
+            ...(required ? { requirement: { kind: facet } } : {}),
+        });
+        if (facet === 'class.inherit')
+            compareAddedProperties({ context, pair, report });
+        if (subject.kind === 'class')
+            compareLostProperties({ pair, report });
+    }
+    compareReliance({ context, report });
+}
+/**
+ * What a dependent Policy relies on is recorded only when it fails: a Method it names that is gone
+ * or no longer executable by its owner, or an Edge it matches whose orientation or accepted endpoint
+ * Classes changed. A held reliance adds no fact, so a compatible comparison keeps its evidence bytes
+ * and no coordinate minted from it moves; a failed one is a refusal, from which none is minted.
+ */
+function compareReliance({ context, report, }) {
+    for (const reference of context.reliance) {
+        const pair = context.pair(reference.coordinate);
+        if (pair.source === undefined)
+            throw contextInvalid(`Retained acceptance context has no meaning for ${reference.coordinate.key}.`, reference.coordinate.key);
+        const facet = reference.coordinate.kind === 'method' ? 'method.object' : 'class.endpoints';
+        const { before, after } = compareFacet({ context, pair, facet });
+        if (before !== undefined &&
+            after !== undefined &&
+            fingerprintMeaning(before) === fingerprintMeaning(after))
+            continue;
+        report.note(reference);
+        report.record({ pair, facet, before, after, requirement: { kind: facet } });
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { Key as SemanticKey } from '../../addressing/index.js';
+import type { DefinitionAnalysis, EffectiveField, EffectiveMethod } from '../analysis/class.js';
+import type { DomainSchema } from '../model/schema.js';
+import type { Context } from './context.js';
+import type { ClassCoordinate, Coordinate, MemberCoordinate, MethodCoordinate, PropertyCoordinate } from './coordinate.js';
+import type { Subject } from './model.js';
+export type ResolvedSubject = {
+    readonly kind: 'class';
+    readonly coordinate: ClassCoordinate;
+    readonly schema: DomainSchema;
+    readonly analysis: DefinitionAnalysis;
+} | {
+    readonly kind: 'property';
+    readonly coordinate: PropertyCoordinate;
+    readonly schema: DomainSchema;
+    readonly field: EffectiveField;
+} | {
+    readonly kind: 'method';
+    readonly coordinate: MethodCoordinate;
+    readonly schema: DomainSchema;
+    readonly method: EffectiveMethod;
+} | {
+    readonly kind: 'member';
+    readonly coordinate: MemberCoordinate;
+    readonly schema: DomainSchema;
+};
+/** Resolve a trusted coordinate within one exact accepted closure. */
+export declare function resolveSubject({ context, coordinate, }: {
+    readonly context: Context;
+    readonly coordinate: Coordinate;
+}): ResolvedSubject | undefined;
+export declare function identityOf(coordinate: Coordinate): Subject;
+/** Resolve one caller-supplied Key of the source into an exact coordinate that exists there. */
+export declare function coordinateForKey(context: Context, source: DomainSchema, input: SemanticKey, index: number): Coordinate;
+/**
+ * Resolve the Function, Method and Class Keys a dependent declares as capabilities into exact
+ * coordinates of its retained source. Keys of other origins belong to other comparisons.
+ */
+export declare function capabilityCoordinates(context: Context, source: DomainSchema, capabilities: readonly SemanticKey[]): readonly Coordinate[];

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

@@ -0,0 +1,143 @@
+import { Key } from '../../addressing/index.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+import { effectiveDefinition, effectiveMethod } from './context.js';
+import { classCoordinate, keyReference, memberCoordinate, methodCoordinate, propertyCoordinate, } from './coordinate.js';
+/** Resolve a trusted coordinate within one exact accepted closure. */
+export function resolveSubject({ context, coordinate, }) {
+    const schema = context.schemas.get(Key.origin(coordinate.key));
+    if (schema === undefined)
+        return undefined;
+    if (coordinate.kind === 'member') {
+        const { ref } = coordinate;
+        const declaration = ref.kind === 'function'
+            ? schema.functions[ref.name]
+            : ref.kind === 'policy'
+                ? schema.policies[ref.name]
+                : ref.kind === 'view'
+                    ? schema.views[ref.name]
+                    : schema.core.nodes[ref.name];
+        return declaration === undefined ? undefined : { kind: 'member', coordinate, schema };
+    }
+    const analysis = effectiveDefinition(context, schema, coordinate.kind === 'class' ? coordinate.ref : coordinate.owner);
+    if (analysis === undefined)
+        return undefined;
+    if (coordinate.kind === 'class')
+        return { kind: 'class', coordinate, schema, analysis };
+    if (coordinate.kind === 'property') {
+        const field = analysis.properties.get(coordinate.key);
+        return field === undefined ? undefined : { kind: 'property', coordinate, schema, field };
+    }
+    const method = effectiveMethod(analysis, coordinate.key);
+    return method === undefined ? undefined : { kind: 'method', coordinate, schema, method };
+}
+export function identityOf(coordinate) {
+    return Object.freeze({
+        key: coordinate.key,
+        kind: coordinate.kind === 'member' ? coordinate.ref.kind : coordinate.kind,
+    });
+}
+/** Resolve one caller-supplied Key of the source into an exact coordinate that exists there. */
+export 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 !== undefined && 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');
+        }
+        // Explicit Class selection compares its surface without inferring inheritance.
+        coordinate = classCoordinate({ origin: source.origin, kind: 'class', name: reference.name });
+    }
+    else {
+        coordinate = memberCoordinate({
+            origin: source.origin,
+            kind: reference.kind,
+            name: reference.name,
+        });
+    }
+    if (resolveSubject({ context, coordinate }) === undefined) {
+        return invalidMemberRoot(key, index, 'does not exist in the source');
+    }
+    return coordinate;
+}
+/**
+ * Resolve the Function, Method and Class Keys a dependent declares as capabilities into exact
+ * coordinates of its retained source. Keys of other origins belong to other comparisons.
+ */
+export function capabilityCoordinates(context, source, capabilities) {
+    return capabilities.flatMap((key, index) => {
+        if (!Key.is(key))
+            return invalidCapability(key, index, 'is not a canonical semantic Key');
+        if (Key.origin(key) !== source.origin)
+            return [];
+        const coordinate = capabilityCoordinate(source, key);
+        if (coordinate === undefined) {
+            return invalidCapability(key, index, 'is not a Function, Method or Class');
+        }
+        if (resolveSubject({ context, coordinate }) === undefined) {
+            return invalidCapability(key, index, `does not exist in the retained ${source.origin}`);
+        }
+        return [coordinate];
+    });
+}
+/** A capability names a Function, a Method by its declaring Class, or a Class. */
+function capabilityCoordinate(source, key) {
+    const { kind, name, member, ownerName } = keyReference(key);
+    const { origin } = source;
+    if (member === 'method')
+        return methodCoordinate({ origin, kind: 'class', name: ownerName }, name);
+    if (member !== undefined)
+        return undefined;
+    if (kind === 'class')
+        return classCoordinate({ origin, kind: 'class', name });
+    if (kind === 'function')
+        return memberCoordinate({ origin, kind: 'function', name });
+    return undefined;
+}
+function invalidCapability(key, index, reason) {
+    throw new SchemaError([
+        diagnostic('DM_CAPABILITY_INVALID', `/capabilities/${index}`, `Capability ${shown(key)} ${reason}.`, typeof key === 'string' ? key : undefined),
+    ]);
+}
+function invalidMemberRoot(key, index, reason) {
+    throw new SchemaError([
+        diagnostic('DM_MEMBER_ROOT_INVALID', `/roots/${index}`, `Key ${shown(key)} ${reason}.`, typeof key === 'string' ? key : undefined),
+    ]);
+}
+/**
+ * A caller-supplied item as diagnostic text. Formatting never throws, so the caller always gets the
+ * diagnostic: a bigint is shown as its literal, and another item JSON cannot encode, such as a cyclic
+ * object, is named by its type.
+ */
+function shown(item) {
+    if (typeof item === 'bigint')
+        return `${item}n`;
+    try {
+        const text = JSON.stringify(item);
+        if (text !== undefined)
+            return text;
+    }
+    catch {
+        // Not encodable as JSON: named by its type below.
+    }
+    return `<${typeof item}>`;
+}

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

@@ -0,0 +1,8 @@
+import type { DomainSchema } from '../../model/schema.js';
+import type { RequiredBump } from '../model.js';
+/**
+ * Minimum schema bump: unsatisfied requirements are major, additions minor, other changes patch.
+ * Concrete callable authorization and code behavior are outside this floor; abstract Method auth
+ * belongs to the inherited signature. Version arithmetic stays with the caller.
+ */
+export declare function requiredBump(previous: DomainSchema, next: DomainSchema): RequiredBump;

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

@@ -0,0 +1,50 @@
+import { deepFreeze } from '../../canonical/freeze.js';
+import { SchemaError, diagnostic } from '../../diagnostic.js';
+import { compareFootprint } from '../meaning/footprint.js';
+import { schemaIdentity } from '../references.js';
+import { createReport } from '../report.js';
+import { selectMembers } from '../scope.js';
+import { compareRequirements } from '../structure/requirements.js';
+import { compareAdditions, memberCoordinates } from './members.js';
+import { compareSurface } from './surface.js';
+const LEVELS = ['patch', 'minor', 'major'];
+/**
+ * Minimum schema bump: unsatisfied requirements are major, additions minor, other changes patch.
+ * Concrete callable authorization and code behavior are outside this floor; abstract Method auth
+ * belongs to the inherited signature. Version arithmetic stays with the caller.
+ */
+export function requiredBump(previous, next) {
+    if (previous.origin !== next.origin)
+        throw new SchemaError([
+            diagnostic('DM_MEMBER_ORIGIN_MISMATCH', '/next/origin', `Next version ${next.origin} does not match previous version ${previous.origin}.`),
+        ]);
+    const identities = { previous: schemaIdentity(previous), next: schemaIdentity(next) };
+    if (identities.previous.revision === identities.next.revision)
+        return deepFreeze({ level: 'patch', ...identities, changes: [] });
+    const members = memberCoordinates(previous);
+    const context = selectMembers(previous, next, members.map(({ key }) => key));
+    // Surface observations must win when an existing obligation becomes newly imposed on a Class.
+    const report = createReport();
+    compareSurface({ context, report });
+    compareRequirements({ context, report });
+    compareFootprint({ context, report });
+    compareAdditions({ context, report, previous: members });
+    const { entries, assessments } = report.finish();
+    const unsatisfied = new Set(assessments.filter(({ satisfied }) => !satisfied).map(({ observation }) => observation.id));
+    const changes = entries.flatMap(({ subject, observations }) => observations
+        .filter(({ state }) => state !== 'equal')
+        .map((observation) => ({
+        subject,
+        observation,
+        bump: unsatisfied.has(observation.id)
+            ? 'major'
+            : observation.state === 'added'
+                ? 'minor'
+                : 'patch',
+    })));
+    return deepFreeze({
+        level: changes.reduce((level, { bump }) => (LEVELS.indexOf(bump) > LEVELS.indexOf(level) ? bump : level), 'patch'),
+        ...identities,
+        changes,
+    });
+}

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

@@ -0,0 +1,12 @@
+import type { DomainSchema } from '../../model/schema.js';
+import type { Coordinate } from '../coordinate.js';
+import type { Report } from '../report.js';
+import type { ComparisonContext } from '../scope.js';
+/** Inherited members count once, at their declaring Class. */
+export declare function memberCoordinates(schema: DomainSchema): readonly Coordinate[];
+/** New declarations impose no requirements here; the surface pass checks obligations on existing Classes. */
+export declare function compareAdditions({ context, report, previous, }: {
+    readonly context: ComparisonContext;
+    readonly report: Report;
+    readonly previous: readonly Coordinate[];
+}): void;

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

@@ -0,0 +1,47 @@
+import { compareFacet } from '../comparators/index.js';
+import { classCoordinate, memberCoordinate, methodCoordinate, propertyCoordinate, } from '../coordinate.js';
+/** Inherited members count once, at their declaring Class. */
+export function memberCoordinates(schema) {
+    const result = [];
+    for (const declaration of Object.values(schema.classes)) {
+        result.push(classCoordinate(declaration.ref));
+        for (const name of Object.keys(declaration.properties))
+            result.push(propertyCoordinate(declaration.ref, name));
+        if (declaration.kind === 'node')
+            for (const name of Object.keys(declaration.methods))
+                result.push(methodCoordinate(declaration.ref, name));
+    }
+    for (const { ref } of [
+        ...Object.values(schema.functions),
+        ...Object.values(schema.policies),
+        ...Object.values(schema.views),
+        ...Object.values(schema.core.nodes),
+    ])
+        result.push(memberCoordinate(ref));
+    return result;
+}
+/** New declarations impose no requirements here; the surface pass checks obligations on existing Classes. */
+export function compareAdditions({ context, report, previous, }) {
+    const known = new Set(previous.map(({ key }) => key));
+    for (const coordinate of memberCoordinates(context.target)) {
+        if (known.has(coordinate.key))
+            continue;
+        const pair = context.pair(coordinate);
+        for (const facet of selectedFacets(coordinate))
+            report.record({ pair, facet, ...compareFacet({ context, pair, facet }) });
+    }
+}
+function selectedFacets(coordinate) {
+    switch (coordinate.kind) {
+        case 'class':
+            return ['class.reference'];
+        case 'property':
+            return ['property'];
+        case 'method':
+            return ['method.existence', 'method.signature'];
+        case 'member':
+            return coordinate.ref.kind === 'function'
+                ? ['function.existence', 'function.signature']
+                : [coordinate.ref.kind];
+    }
+}

package/dist/v1/schema/compatibility/versioning/surface.d.ts

@@ -0,0 +1,11 @@
+import type { Report } from '../report.js';
+import type { ComparisonContext } from '../scope.js';
+/**
+ * Compare inherited contracts and newly imposed obligations on existing Classes.
+ * Obligations are reported at their declaring Method: changed signatures retain their comparison;
+ * an unchanged obligation newly inherited by a Class is added and unsatisfied.
+ */
+export declare function compareSurface({ context, report, }: {
+    readonly context: ComparisonContext;
+    readonly report: Report;
+}): void;