@astrale-os/kernel-dsl 0.2.0-beta.43 → 0.2.0-beta.45

package/dist/v1/compiled/admission/accept.js

@@ -21,11 +21,10 @@ export function acceptCompiledSchema(input) {
     exact(root, ['format', 'version', 'root', 'closure'], 'CompiledSchema', '');
     if (root.format !== 'astrale.dsl.compiled-schema')
         invalid('format', undefined, '/format');
-    if (root.version !== 1 && root.version !== 2)
+    if (root.version !== 2)
         invalid('version', undefined, '/version');
-    const version = root.version;
     const rootPin = dependency(root.root, 'root', '/root');
-    const closure = array(root.closure, 'closure', '/closure').map((value, index) => entry(value, index, `/closure/${index}`, version));
+    const closure = array(root.closure, 'closure', '/closure').map((value, index) => entry(value, index, `/closure/${index}`));
     if (closure.length > dependencyLimits.closure) {
         invalid('dependency closure limit', 'COMPILED_DEPENDENCY_LIMITS', '/closure');
     }
@@ -75,17 +74,9 @@ export function acceptCompiledSchema(input) {
     validateCompiledSemantics(candidate);
     return deepFreeze(candidate);
 }
-function entry(input, entryIndex, path, version) {
+function entry(input, entryIndex, path) {
     const value = object(input, `closure[${entryIndex}]`, path);
-    exact(value, [
-        'origin',
-        'revision',
-        'dependencies',
-        'definitions',
-        'facts',
-        'values',
-        ...(version === 2 ? ['patterns'] : []),
-    ], 'entry', path);
+    exact(value, ['origin', 'revision', 'dependencies', 'definitions', 'facts', 'values', 'patterns'], 'entry', path);
     const origin = originValue(value.origin, 'entry origin', `${path}/origin`);
     const revision = revisionValue(value.revision, 'entry revision', `${path}/revision`);
     const dependenciesPath = `${path}/dependencies`;
@@ -98,10 +89,8 @@ function entry(input, entryIndex, path, version) {
     }
     const valuesPath = `${path}/values`;
     const patternsPath = `${path}/patterns`;
-    const patterns = version === 2
-        ? array(value.patterns, 'entry patterns', patternsPath).map((item, index) => pattern(item, index, `${patternsPath}/${index}`, true))
-        : [];
-    const values = array(value.values, 'values', valuesPath).map((item, index) => program(item, index, `${valuesPath}/${index}`, patterns, version));
+    const patterns = array(value.patterns, 'entry patterns', patternsPath).map((item, index) => pattern(item, index, `${patternsPath}/${index}`));
+    const values = array(value.values, 'values', valuesPath).map((item, index) => program(item, index, `${valuesPath}/${index}`, patterns));
     const bound = values.map((value) => bindValueProgram(value, patterns));
     const definitionsPath = `${path}/definitions`;
     const definitions = object(value.definitions, 'definitions', definitionsPath);
@@ -803,20 +792,14 @@ function walk(input, path, visit) {
     for (const [key, value] of Object.entries(input))
         walk(value, pointer(path, key), visit);
 }
-function program(input, programIndex, path, table, version) {
+function program(input, programIndex, path, table) {
     const value = object(input, `values[${programIndex}]`, path);
     exact(value, ['root', 'nodes', 'patterns'], 'ValueProgram', path);
     const nodesPath = `${path}/nodes`;
     const nodes = array(value.nodes, 'ValueProgram nodes', nodesPath).map((node, index) => valueNode(node, index, `${nodesPath}/${index}`));
     const root = index(value.root, nodes.length, 'ValueProgram root', `${path}/root`);
     const patternsPath = `${path}/patterns`;
-    const patterns = array(value.patterns, 'ValueProgram patterns', patternsPath).map((item, position) => {
-        const patternPath = `${patternsPath}/${position}`;
-        if (version === 2)
-            return index(item, table.length, 'ValueProgram pattern', patternPath);
-        // Legacy programs can carry different machines with the same source label. Preserve each.
-        return table.push(pattern(item, position, patternPath, false)) - 1;
-    });
+    const patterns = array(value.patterns, 'ValueProgram patterns', patternsPath).map((item, position) => index(item, table.length, 'ValueProgram pattern', `${patternsPath}/${position}`));
     const sources = patterns.map((index) => table[index].source);
     unique(sources, 'patterns', patternsPath);
     const available = new Set(sources);
@@ -855,9 +838,9 @@ function valueNode(input, nodeIndex, path) {
             : { reference: integer(value.reference, 'reference', `${path}/reference`) }),
     };
 }
-function pattern(input, patternIndex, path, counted) {
+function pattern(input, patternIndex, path) {
     const value = object(input, `patterns[${patternIndex}]`, path);
-    if (counted && Object.hasOwn(value, 'runs'))
+    if (Object.hasOwn(value, 'runs'))
         return runPattern(value, path);
     exact(value, ['source', 'start', 'states'], 'Pattern', path);
     if (typeof value.source !== 'string')

package/dist/v1/compiled/loader/load.d.ts

@@ -1,12 +1,4 @@
-import type { ValueProgram } from '../../language/value/compile/model.js';
-import type { CompiledSchema, CompiledSchemaEntry, DomainOfCompiled } from '../model/schema.js';
-type LegacyEntry = Omit<CompiledSchemaEntry, 'values' | 'patterns'> & {
-    readonly values: readonly ValueProgram[];
-};
-type LegacyCompiledSchema = Omit<CompiledSchema, 'version' | 'closure'> & {
-    readonly version: 1;
-    readonly closure: readonly LegacyEntry[];
-};
+import type { CompiledSchema, DomainOfCompiled } from '../model/schema.js';
 /** Load admitted compiled data through the one resolved Domain constructor. */
 export declare function load<const Input extends CompiledSchema>(input: Input): DomainOfCompiled<Input>;
 export declare function load(input: unknown): import('../../domain/model/domain.js').Domain;
@@ -14,5 +6,4 @@ export declare function load(input: unknown): import('../../domain/model/domain.
  * Realize compiled material whose exact embedded bytes were already proven by generated build code.
  * External bytes and caller-provided values must continue through {@link load}.
  */
-export declare function realize(compiled: CompiledSchema | LegacyCompiledSchema): import('../../domain/model/domain.js').Domain;
-export {};
+export declare function realize(compiled: CompiledSchema): import('../../domain/model/domain.js').Domain;

package/dist/v1/compiled/loader/load.js

@@ -69,9 +69,7 @@ function loadEntry(entry) {
             ...entry.definitions.views,
             ...entry.definitions.core,
         ]),
-        validation: programValidation('patterns' in entry
-            ? entry.values.map((value) => bindValueProgram(value, entry.patterns))
-            : entry.values, propertyPrograms, propertyOrdering, callablePrograms),
+        validation: programValidation(entry.values.map((value) => bindValueProgram(value, entry.patterns)), propertyPrograms, propertyOrdering, callablePrograms),
     };
 }
 function loadMethod(entry, value) {

package/dist/v1/language/value/evaluate/evaluator.js

@@ -13,7 +13,7 @@ const MAX_CACHED_PATTERN_RESULTS = 256;
 const MAX_CACHED_PATTERN_INPUT_LENGTH = 128;
 class InstanceEvaluator {
     compiled;
-    active = new Set();
+    resultCache = new Map();
     searchResults = new Map();
     fullMatchResults = new Map();
     patternResultCount = 0;
@@ -21,23 +21,41 @@ class InstanceEvaluator {
         this.compiled = compiled;
     }
     evaluate(location, input, instancePointer) {
-        const activeKey = `${location.key}\u0000${instancePointer}`;
-        if (this.active.has(activeKey)) {
+        const key = `${location.key}\u0000${instancePointer}`;
+        // propertyNames evaluates the name at the property's value pointer. Cache by the actual
+        // input too, retaining one result per repeated sub-problem within this call. A null entry
+        // marks an active evaluation; completed results and their annotations are only read.
+        let byLocation = this.resultCache.get(input);
+        const memoized = byLocation?.get(key);
+        if (memoized === null) {
             throw new TypeError('Admitted value schema entered a non-productive evaluation cycle.');
         }
-        this.active.add(activeKey);
+        if (memoized !== undefined)
+            return memoized;
+        if (byLocation === undefined) {
+            byLocation = new Map();
+            this.resultCache.set(input, byLocation);
+        }
+        byLocation.set(key, null);
         try {
-            if (location.schema === true)
-                return evaluation();
-            if (location.schema === false) {
-                return evaluation([
+            let result;
+            if (location.schema === true) {
+                result = evaluation();
+            }
+            else if (location.schema === false) {
+                result = evaluation([
                     invalid(instancePointer, 'false', 'The false schema rejects every value.'),
                 ]);
             }
-            return this.evaluateObjectSchema(location, location.schema, input, instancePointer);
+            else {
+                result = this.evaluateObjectSchema(location, location.schema, input, instancePointer);
+            }
+            byLocation.set(key, result);
+            return result;
         }
-        finally {
-            this.active.delete(activeKey);
+        catch (error) {
+            byLocation.delete(key);
+            throw error;
         }
     }
     evaluateObjectSchema(location, schema, input, instancePointer) {

package/dist/v1/language/value/profile/rules.js

@@ -3,6 +3,7 @@ import { diagnostic } from '../../validation/diagnostic.js';
 import { blob, BLOB_VALUE_KIND } from '../model/blob.js';
 import { isValueObject as isJsonObject } from '../model/object.js';
 import { VALUE_SCHEMA_DIALECT } from '../model/schema.js';
+import { compilePattern, PatternComplexityError } from '../regexp/compile.js';
 import { isIRegexp } from '../regexp/syntax.js';
 import { walkSchema } from '../syntax/walk.js';
 import { FORBIDDEN_DYNAMIC_KEYWORDS, STANDARD_SCHEMA_KEYWORDS } from './vocabulary.js';
@@ -98,14 +99,38 @@ function validateRegexes(schema, pointer, diagnostics) {
     if (typeof schema.fullMatch === 'string' && !isIRegexp(schema.fullMatch)) {
         diagnostics.push(diagnostic('VS_REGEX_PORTABLE', `${pointer}/fullMatch`, 'fullMatch must satisfy the complete RFC 9485 I-Regexp syntax.'));
     }
+    else if (typeof schema.fullMatch === 'string') {
+        checkPatternComplexity(schema.fullMatch, `${pointer}/fullMatch`, diagnostics);
+    }
     if (typeof schema.pattern === 'string' && !isIRegexp(schema.pattern)) {
         diagnostics.push(diagnostic('VS_REGEX_PORTABLE', `${pointer}/pattern`, 'pattern must satisfy the complete RFC 9485 I-Regexp syntax.'));
     }
+    else if (typeof schema.pattern === 'string') {
+        checkPatternComplexity(schema.pattern, `${pointer}/pattern`, diagnostics);
+    }
     if (isJsonObject(schema.patternProperties)) {
         for (const pattern of Object.keys(schema.patternProperties)) {
             if (!isIRegexp(pattern)) {
                 diagnostics.push(diagnostic('VS_REGEX_PORTABLE', `${pointer}/patternProperties/${escapeToken(pattern)}`, 'patternProperties keys must satisfy RFC 9485 I-Regexp syntax.'));
             }
+            else {
+                checkPatternComplexity(pattern, `${pointer}/patternProperties/${escapeToken(pattern)}`, diagnostics);
+            }
+        }
+    }
+}
+/**
+ * Reject a syntactically valid I-Regexp that compiles to an unbounded NFA (nested counted
+ * repetitions, P1-I-01) at admission, rather than letting it unroll to ~120k states and cost
+ * seconds per validated value. Other compile failures are already reported by the syntax checks.
+ */
+function checkPatternComplexity(source, pointer, diagnostics) {
+    try {
+        compilePattern(source);
+    }
+    catch (error) {
+        if (error instanceof PatternComplexityError) {
+            diagnostics.push(diagnostic('VS_REGEX_PORTABLE', pointer, `${error.message} Simplify nested counted repetitions to stay within the I-Regexp complexity bound.`));
         }
     }
 }

package/dist/v1/language/value/regexp/compile.d.ts

@@ -1,3 +1,9 @@
 import type { Pattern, RunPattern } from '../compile/model.js';
+export declare const MAX_PATTERN_STATES = 10000;
+/** Thrown when an I-Regexp source compiles past `MAX_PATTERN_STATES` NFA states. */
+export declare class PatternComplexityError extends RangeError {
+    readonly limit: number;
+    constructor(limit?: number);
+}
 /** Compile scalar sequences as counted runs; preserve the NFA for branching expressions. */
 export declare function compilePattern(source: string): Pattern | RunPattern;

package/dist/v1/language/value/regexp/compile.js

@@ -1,4 +1,20 @@
 import { parseIRegexp } from './ast.js';
+// A branching I-Regexp compiles to an NFA whose size is the product of its nested counted
+// repetitions, so a short source such as `(a{0,1000}){0,60}b` unrolls to ~120k states and costs
+// seconds per validated value (P1-I-01). Bound the NFA so a pathological source is rejected at
+// schema admission instead. The limit is well above realistic patterns: the RFC 9485 domain-name
+// regex `([a-z0-9-]{1,63}\.){1,32}[a-z]{2,63}` compiles to ~4.3k states. Pure scalar runs
+// (`a{0,1000}`) never reach this path: they compile to counted runs, not NFA states.
+export const MAX_PATTERN_STATES = 10_000;
+/** Thrown when an I-Regexp source compiles past `MAX_PATTERN_STATES` NFA states. */
+export class PatternComplexityError extends RangeError {
+    limit;
+    constructor(limit = MAX_PATTERN_STATES) {
+        super(`I-Regexp compiles to more than ${limit} states.`);
+        this.limit = limit;
+        this.name = 'PatternComplexityError';
+    }
+}
 /** Compile scalar sequences as counted runs; preserve the NFA for branching expressions. */
 export function compilePattern(source) {
     const expression = parseIRegexp(source);
@@ -123,6 +139,8 @@ class Builder {
         return { start: left.start, end: right.end };
     }
     state() {
+        if (this.states.length >= MAX_PATTERN_STATES)
+            throw new PatternComplexityError();
         return this.states.push({ epsilon: [], transitions: [] }) - 1;
     }
     epsilon(from, to) {

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

@@ -1,2 +1,3 @@
 export { compare, compareMeaning, compareStructure } from './compare.js';
-export type { Analysis, Assessment, Comparison, ComparisonEntry, ComparisonEvidence, ComparisonRequest, ComparisonScope, Facet, Fingerprint, MeaningComparison, Observation, SchemaIdentity, StructureComparison, Subject, Usage, } from './model.js';
+export { requiredBump } from './versioning/index.js';
+export type { Analysis, Assessment, Bump, Comparison, ComparisonEntry, ComparisonEvidence, ComparisonRequest, ComparisonScope, Facet, Fingerprint, MeaningComparison, Observation, RequiredBump, SchemaIdentity, StructureComparison, Subject, Usage, VersionChange, } from './model.js';

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

@@ -1 +1,2 @@
 export { compare, compareMeaning, compareStructure } from './compare.js';
+export { requiredBump } from './versioning/index.js';

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

@@ -1,5 +1,9 @@
 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'> & {
+/**
+ * Only semantic facts and decisions are durable; provenance and diagnostic prose are not. Each
+ * analysis names the version of the requirement policy its facts were assessed under.
+ */
+export declare function evidenceOf({ kind, version, scope, entries, assessments, }: Omit<Analysis, 'evidence'> & {
     readonly kind: ComparisonEvidence['kind'];
+    readonly version: ComparisonEvidence['version'];
 }): ComparisonEvidence;

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

@@ -1,8 +1,10 @@
 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;
+/**
+ * Only semantic facts and decisions are durable; provenance and diagnostic prose are not. Each
+ * analysis names the version of the requirement policy its facts were assessed under.
+ */
+export function evidenceOf({ kind, version, scope, entries, assessments, }) {
     return Object.freeze({
         kind,
         version,

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

@@ -1,8 +1,6 @@
 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 type { FieldRole } from './fields.js';
 export { callableFingerprint } from './comparators/callables.js';
 export type { Fingerprint as MeaningFingerprint } from './model.js';

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

@@ -1,4 +1,3 @@
 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 './comparators/callables.js';

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

@@ -9,6 +9,6 @@ export function analyzeMeaning(context) {
         kind: 'meaning',
         ...result,
         equivalent: result.assessments.every(({ satisfied }) => satisfied),
-        evidence: evidenceOf({ kind: 'meaning', ...result }),
+        evidence: evidenceOf({ kind: 'meaning', version: 1, ...result }),
     });
 }

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

@@ -9,6 +9,14 @@ export interface ComparisonRequest {
     readonly scope: {
         readonly kind: 'dependency';
         readonly dependent: DomainSchema;
+        /**
+         * Function, Method and Class Keys the dependent declares as capability requirements outside
+         * its schema. Keys of the target origin become roots with relation `capability`: a Function
+         * or Method requires its existence and dispatch, a Class its reference meaning and effective
+         * Property surface. Keys of other origins are ignored; a value that is not a Key list, or an
+         * unresolvable or unsupported Key of the target origin, is rejected with DM_CAPABILITY_INVALID.
+         */
+        readonly capabilities?: readonly Key[];
     } | {
         readonly kind: 'members';
         readonly source: DomainSchema;
@@ -36,7 +44,7 @@ export interface Subject {
 export interface Usage {
     readonly source: SchemaIdentity;
     readonly key?: Key;
-    readonly relation: ReferenceSite | 'member' | 'abstract' | 'selection';
+    readonly relation: ReferenceSite | 'member' | 'abstract' | 'selection' | 'capability';
 }
 export type Facet = 'class.reference' | 'class.inherit' | 'class.composition' | 'property' | 'property.required' | 'method.existence' | 'method.inheritance' | 'method.signature' | 'function.existence' | 'function.signature' | 'policy' | 'view' | 'core';
 /** A fact about a compared facet, including unchanged facets. No admission decision is implied. */
@@ -64,10 +72,16 @@ export interface Assessment {
     };
     readonly satisfied: boolean;
 }
-/** Evidence is a semantic projection; presentation/provenance never enters its digest. */
+/**
+ * Evidence is a semantic projection; presentation/provenance never enters its digest. Versions are
+ * per kind. Meaning is version 1. Structure is version 2, or version 3 when declared capabilities
+ * are among its roots, so a comparison without them keeps the version-2 bytes. Capability Keys join
+ * the root Key set of both digests: one that is not already a root changes the meaning fingerprint,
+ * never its version, and meaning evidence never records whether capabilities were declared.
+ */
 export interface ComparisonEvidence {
     readonly kind: 'structure' | 'meaning';
-    readonly version: 1 | 2;
+    readonly version: 1 | 2 | 3;
     readonly fingerprint: Fingerprint;
 }
 export interface Analysis {
@@ -94,3 +108,19 @@ export interface Comparison {
         readonly meaning: ComparisonEvidence;
     };
 }
+/** The semantic level a schema change requires at minimum; version numbers stay with the caller. */
+export type Bump = 'patch' | 'minor' | 'major';
+/** One non-equal observation between two versions of one Domain, with the level it alone requires. */
+export interface VersionChange {
+    readonly subject: Subject;
+    readonly observation: Observation;
+    readonly bump: Bump;
+}
+/** The floor `next` sets over `previous`: the highest level among its changes, patch without any. */
+export interface RequiredBump {
+    readonly level: Bump;
+    readonly previous: SchemaIdentity;
+    readonly next: SchemaIdentity;
+    /** Every non-equal observation, ordered by subject Key then observation id; empty for equal revisions. */
+    readonly changes: readonly VersionChange[];
+}

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

@@ -18,9 +18,17 @@ export interface ComparisonContext {
     readonly before: Context;
     readonly after: Context;
     readonly roots: readonly Reference[];
+    /** Roots the dependent declares as capabilities on the compared origin; also in `roots`. */
+    readonly capabilities: readonly Reference[];
     pair(coordinate: Coordinate): SubjectPair;
 }
 export declare function prepare(request: ComparisonRequest): ComparisonContext;
+/**
+ * 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 declare function selectMembers(source: DomainSchema, target: DomainSchema, keys: readonly Key[]): ComparisonContext;
 export declare function retainedContext(dependent: DomainSchema, origin: Key.Origin, path: '/target/origin' | '/origin'): {
     source: DomainSchema;
     context: Context;

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

@@ -4,38 +4,66 @@ import { knownDomainClosure } from '../resolution/closure.js';
 import { resolve } from '../resolution/domain.js';
 import { contextOf } from './context.js';
 import { rootReferences, schemaIdentity, usageOf } from './references.js';
-import { coordinateForKey, resolveSubject } from './subjects.js';
+import { capabilityCoordinates, coordinateForKey, resolveSubject } from './subjects.js';
 export function prepare(request) {
-    const { target } = request;
-    let source;
-    let before;
-    let roots;
-    const dependent = request.scope.kind === 'dependency' ? request.scope.dependent : undefined;
-    if (request.scope.kind === 'dependency') {
-        const retained = retainedContext(request.scope.dependent, target.origin, '/target/origin');
-        source = retained.source;
-        before = retained.context;
-        roots = rootReferences(request.scope.dependent);
-    }
-    else {
-        source = request.scope.source;
+    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}.`),
             ]);
-        const keys = request.scope.roots;
         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.'),
             ]);
         }
-        resolve(source);
-        before = contextOf(source);
-        roots = keys.map((key, index) => ({
+        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,
+    });
+}
+/**
+ * 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: [],
+    });
+}
+function comparisonContext({ kind, source, target, dependent, before, roots, capabilities, }) {
     resolve(target);
     const after = contextOf(target);
     const pairs = new Map();
@@ -46,8 +74,9 @@ export function prepare(request) {
         before,
         after,
         roots,
+        capabilities,
         scope: Object.freeze({
-            kind: request.scope.kind,
+            kind,
             source: schemaIdentity(source),
             target: schemaIdentity(target),
             ...(dependent === undefined ? {} : { dependent: schemaIdentity(dependent) }),

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

@@ -11,6 +11,11 @@ export function analyzeStructure(context) {
         kind: 'structure',
         ...result,
         compatible: result.assessments.every(({ satisfied }) => satisfied),
-        evidence: evidenceOf({ kind: 'structure', ...result }),
+        // Version 3 adds declared capability roots; without one, evidence keeps its version-2 bytes.
+        evidence: evidenceOf({
+            kind: 'structure',
+            version: context.capabilities.length > 0 ? 3 : 2,
+            ...result,
+        }),
     });
 }

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

@@ -55,9 +55,11 @@ export function compareRequirements({ context, report, }) {
         }
         if (Key.origin(coordinate.key) !== context.source.origin)
             continue;
-        // Class membership does not establish an invocation dependency. Explicit member selection
-        // and inherited abstract obligations do establish requirements; call tracking can add others.
-        const required = facet !== 'method.existence' || usage.relation === 'selection';
+        // 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,

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

@@ -32,3 +32,8 @@ export declare function resolveSubject({ context, coordinate, }: {
 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

@@ -79,6 +79,45 @@ export function coordinateForKey(context, source, input, index) {
     }
     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 ${JSON.stringify(key)} ${reason}.`, typeof key === 'string' ? key : undefined),
+    ]);
+}
 function invalidMemberRoot(key, index, reason) {
     throw new SchemaError([
         diagnostic('DM_MEMBER_ROOT_INVALID', `/roots/${index}`, `Key ${JSON.stringify(key)} ${reason}.`, typeof key === 'string' ? key : undefined),

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;

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

@@ -0,0 +1,61 @@
+import { methodInheritance } from '../comparators/callables.js';
+import { compareAddedProperties } from '../comparators/classes.js';
+import { compareFacet } from '../comparators/index.js';
+import { fingerprintMeaning } from '../comparators/values.js';
+import { classCoordinate, methodCoordinate } from '../coordinate.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 function compareSurface({ context, report, }) {
+    const established = new Map();
+    const imposed = new Map();
+    for (const declaration of Object.values(context.source.classes)) {
+        if (context.target.classes[declaration.ref.name] === undefined)
+            continue;
+        const pair = context.pair(classCoordinate(declaration.ref));
+        const { source, target } = pair;
+        if (source?.kind !== 'class' || target?.kind !== 'class')
+            continue;
+        report.record({
+            pair,
+            facet: 'class.inherit',
+            ...compareFacet({ context, pair, facet: 'class.inherit' }),
+            requirement: { kind: 'class.inherit' },
+        });
+        compareAddedProperties({ context, pair, report });
+        for (const [key, method] of source.analysis.requirements)
+            if (!established.has(key))
+                established.set(key, method);
+        for (const [key, method] of target.analysis.requirements)
+            if (!source.analysis.requirements.has(key) && !imposed.has(key))
+                imposed.set(key, method);
+    }
+    for (const key of new Set([...established.keys(), ...imposed.keys()])) {
+        const added = imposed.get(key);
+        const method = established.get(key) ?? added;
+        const pair = context.pair(methodCoordinate(method.owner, method.name));
+        const comparison = established.has(key)
+            ? compareFacet({ context, pair, facet: 'method.inheritance' })
+            : undefined;
+        report.record(comparison !== undefined && (added === undefined || changed(comparison))
+            ? {
+                pair,
+                facet: 'method.inheritance',
+                ...comparison,
+                requirement: { kind: 'method.inheritance' },
+            }
+            : {
+                pair,
+                facet: 'method.inheritance',
+                after: methodInheritance(added),
+                requirement: { kind: 'method.inheritance', satisfied: false },
+            });
+    }
+}
+function changed({ before, after }) {
+    return (before === undefined ||
+        after === undefined ||
+        fingerprintMeaning(before) !== fingerprintMeaning(after));
+}

package/dist/v1/schema/diagnostic.d.ts

@@ -1,4 +1,4 @@
-export type SchemaDiagnosticCode = 'DM_MEMBER_ROOT_INVALID' | 'DM_DEPENDENCY_CONTEXT_INVALID' | 'DM_DEPENDENCY_NOT_RETAINED' | 'DM_MEANING_INCONSISTENT' | 'DM_MEMBER_ORIGIN_MISMATCH' | 'DV_ACCEPTANCE_CONTEXT' | 'DV_CALLABLE_AUTH' | 'DV_CALLABLE_IO' | 'DV_CALLABLE_POLICY_AUTH' | 'DV_CLASS_ABSTRACT' | 'DV_CLASS_ACYCLIC' | 'DV_CLASS_KIND' | 'DV_CORE_EDGE_CLASS' | 'DV_CORE_EDGE_CONSTRAINTS' | 'DV_CORE_EDGE_KEY' | 'DV_CORE_EDGE_PROPERTIES' | 'DV_CORE_NODE_CLASS' | 'DV_CORE_NODE_PROPERTIES' | 'DV_CORE_REF' | 'DV_DATA_COMPOSITION' | 'DV_DEPENDENCY_ACYCLIC' | 'DV_DEPENDENCY_DIRECT' | 'DV_DEPENDENCY_EXACT' | 'DV_DEPENDENCY_LIMITS' | 'DV_DEPENDENCY_REVISION_COHERENCE' | 'DV_DEPENDENCY_UNIQUE' | 'DV_EDGE_ACCEPTS' | 'DV_EDGE_CLASS_COMPOSITION' | 'DV_EDGE_CONSTRAINT' | 'DV_EDGE_ROLE' | 'DV_EDGE_UNDIRECTED' | 'DV_JSON_VALUE' | 'DV_METHOD_ABSTRACT' | 'DV_METHOD_COMPOSITION' | 'DV_PROPERTY_AUTO' | 'DV_PROPERTY_COMPOSITION' | 'DV_PROPERTY_STATE' | 'DV_REF_RESOLVES' | 'DV_VALUE_SCHEMA' | 'DV_VIEW_TARGET' | 'PL_BUDGET' | 'PL_COMPOSITION' | 'PL_CONNECTIVITY' | 'PL_REF' | 'PL_REPEAT' | 'PL_TARGET' | 'PL_TYPING' | 'PL_USE' | 'PL_VARIABLE_SCOPE' | 'STRUCTURE_ABSTRACT_POLICY' | 'STRUCTURE_CALLABLE_POLICY_AUTH' | 'STRUCTURE_DUPLICATE_ITEM' | 'STRUCTURE_EDGE_ORIENTATION' | 'STRUCTURE_FORMAT' | 'STRUCTURE_INVALID' | 'STRUCTURE_KEY' | 'STRUCTURE_MAXIMUM' | 'STRUCTURE_MINIMUM' | 'STRUCTURE_MULTIPLE' | 'STRUCTURE_REQUIRED' | 'STRUCTURE_TYPE' | 'STRUCTURE_UNION' | 'STRUCTURE_UNKNOWN_FIELD' | 'STRUCTURE_VALUE' | 'UNSUPPORTED_DOCUMENT_FORMAT' | 'UNSUPPORTED_DSL_VERSION';
+export type SchemaDiagnosticCode = 'DM_CAPABILITY_INVALID' | 'DM_MEMBER_ROOT_INVALID' | 'DM_DEPENDENCY_CONTEXT_INVALID' | 'DM_DEPENDENCY_NOT_RETAINED' | 'DM_MEANING_INCONSISTENT' | 'DM_MEMBER_ORIGIN_MISMATCH' | 'DV_ACCEPTANCE_CONTEXT' | 'DV_CALLABLE_AUTH' | 'DV_CALLABLE_IO' | 'DV_CALLABLE_POLICY_AUTH' | 'DV_CLASS_ABSTRACT' | 'DV_CLASS_ACYCLIC' | 'DV_CLASS_KIND' | 'DV_CORE_EDGE_CLASS' | 'DV_CORE_EDGE_CONSTRAINTS' | 'DV_CORE_EDGE_KEY' | 'DV_CORE_EDGE_PROPERTIES' | 'DV_CORE_NODE_CLASS' | 'DV_CORE_NODE_PROPERTIES' | 'DV_CORE_REF' | 'DV_DATA_COMPOSITION' | 'DV_DEPENDENCY_ACYCLIC' | 'DV_DEPENDENCY_DIRECT' | 'DV_DEPENDENCY_EXACT' | 'DV_DEPENDENCY_LIMITS' | 'DV_DEPENDENCY_REVISION_COHERENCE' | 'DV_DEPENDENCY_UNIQUE' | 'DV_EDGE_ACCEPTS' | 'DV_EDGE_CLASS_COMPOSITION' | 'DV_EDGE_CONSTRAINT' | 'DV_EDGE_ROLE' | 'DV_EDGE_UNDIRECTED' | 'DV_JSON_VALUE' | 'DV_METHOD_ABSTRACT' | 'DV_METHOD_COMPOSITION' | 'DV_PROPERTY_AUTO' | 'DV_PROPERTY_COMPOSITION' | 'DV_PROPERTY_STATE' | 'DV_REF_RESOLVES' | 'DV_VALUE_SCHEMA' | 'DV_VIEW_TARGET' | 'PL_BUDGET' | 'PL_COMPOSITION' | 'PL_CONNECTIVITY' | 'PL_REF' | 'PL_REPEAT' | 'PL_TARGET' | 'PL_TYPING' | 'PL_USE' | 'PL_VARIABLE_SCOPE' | 'STRUCTURE_ABSTRACT_POLICY' | 'STRUCTURE_CALLABLE_POLICY_AUTH' | 'STRUCTURE_DUPLICATE_ITEM' | 'STRUCTURE_EDGE_ORIENTATION' | 'STRUCTURE_FORMAT' | 'STRUCTURE_INVALID' | 'STRUCTURE_KEY' | 'STRUCTURE_MAXIMUM' | 'STRUCTURE_MINIMUM' | 'STRUCTURE_MULTIPLE' | 'STRUCTURE_REQUIRED' | 'STRUCTURE_TYPE' | 'STRUCTURE_UNION' | 'STRUCTURE_UNKNOWN_FIELD' | 'STRUCTURE_VALUE' | 'UNSUPPORTED_DOCUMENT_FORMAT' | 'UNSUPPORTED_DSL_VERSION';
 export interface SchemaDiagnostic<out Code extends SchemaDiagnosticCode = SchemaDiagnosticCode> {
     readonly code: Code;
     readonly pointer: string;

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

@@ -11,8 +11,8 @@ export type { SchemaDiagnosticCode as DiagnosticCode } from './diagnostic.js';
 export { acceptDomainSchema as accept } from './admission/accept.js';
 export { decodeDomainSchema as decode, encodeDomainSchema as encode, serializeDomainSchema as serialize, } from './codec/schema.js';
 export { revisionOfDomainSchema as revision } from './canonical/revision.js';
-export { ANNOTATION_KEYWORDS, FIELD_ROLES, callableFingerprint, compareDependencyMeaning, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './compatibility/index.js';
-export type { DependencyMeaningChange, DependencyMeaningChangeKind, DependencyMeaningComparison, DependencyMeaningLevel, FieldRole, FootprintEntry, MeaningDifference, MeaningFingerprint, } from './compatibility/index.js';
+export { ANNOTATION_KEYWORDS, FIELD_ROLES, callableFingerprint } from './compatibility/index.js';
+export type { FieldRole, MeaningDifference, MeaningFingerprint } from './compatibility/index.js';
 export * as compatibility from './compatibility/api.js';
 export { header } from './codec/header.js';
 export { DOMAIN_FORMAT as FORMAT, DOMAIN_VERSION as VERSION } from './model/format.js';
@@ -25,5 +25,3 @@ export type { DomainSchemaHeader as Header } from './codec/header.js';
 export type { DomainDependency } from '../addressing/index.js';
 /** The versioned value-schema grammar embedded in declarations. */
 export * as values from './validation/value-api.js';
-export { compareDependencyStructure } from './compatibility/index.js';
-export type { DependencyStructureComparison } from './compatibility/index.js';

package/dist/v1/schema/index.js

@@ -4,7 +4,7 @@ export const resolve = resolveDomainSchema;
 export { acceptDomainSchema as accept } from './admission/accept.js';
 export { decodeDomainSchema as decode, encodeDomainSchema as encode, serializeDomainSchema as serialize, } from './codec/schema.js';
 export { revisionOfDomainSchema as revision } from './canonical/revision.js';
-export { ANNOTATION_KEYWORDS, FIELD_ROLES, callableFingerprint, compareDependencyMeaning, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './compatibility/index.js';
+export { ANNOTATION_KEYWORDS, FIELD_ROLES, callableFingerprint } from './compatibility/index.js';
 export * as compatibility from './compatibility/api.js';
 export { header } from './codec/header.js';
 export { DOMAIN_FORMAT as FORMAT, DOMAIN_VERSION as VERSION } from './model/format.js';
@@ -12,4 +12,3 @@ export { compile, load } from '../compiled/index.js';
 export { SchemaError as Error } from './diagnostic.js';
 /** The versioned value-schema grammar embedded in declarations. */
 export * as values from './validation/value-api.js';
-export { compareDependencyStructure } from './compatibility/index.js';

package/dist/v1/schema/validation/policy/budgets.js

@@ -3,8 +3,14 @@ import { BRANCH_OVERFLOW, MAX_BRANCHES, MAX_CHECK_DEPTH, MAX_CHECK_LEAVES, MAX_D
 import { escapePointer } from './context.js';
 export { BRANCH_OVERFLOW, MAX_BRANCHES, MAX_CHECK_DEPTH, MAX_CHECK_LEAVES, MAX_DOMAINS, MAX_EDGES, MAX_PATTERN_DEPTH, MAX_REPEAT, MAX_VARIABLES, measureChecks, };
 export function validatePolicyBudgets(context) {
+    // Measure every distinct composition node once. A node's expanded measure is independent of the
+    // path that reaches it (the only path-sensitive outcome, the back-edge `undefined`, already holds
+    // for every node on or reaching a composition cycle, regardless of entry), so caching the
+    // completed result by node identity turns path enumeration over the composition DAG into work
+    // linear in the number of nodes while preserving the exact measure and PL_BUDGET decision.
+    const measures = new Map();
     for (const name of Object.keys(context.environment.candidate.policies)) {
-        const measure = measurePolicy(context, name, new Set());
+        const measure = measurePolicy(context, name, new Set(), measures);
         if (measure === undefined)
             continue;
         const pointer = `/policies/${escapePointer(name)}`;
@@ -23,14 +29,21 @@ export function validatePolicyBudgets(context) {
         }
     }
 }
-function measurePolicy(context, name, visiting) {
+function measurePolicy(context, name, visiting, measures) {
     if (visiting.has(name))
         return undefined;
+    if (measures.has(name))
+        return measures.get(name);
     const declaration = context.normalized.get(name);
     if (declaration === undefined)
         return undefined;
     const nested = new Set(visiting);
     nested.add(name);
+    const measure = measureDeclaration(context, declaration, nested, measures);
+    measures.set(name, measure);
+    return measure;
+}
+function measureDeclaration(context, declaration, nested, measures) {
     if ('match' in declaration) {
         return measurePattern(declaration.match, context.environment.candidate.origin);
     }
@@ -38,7 +51,7 @@ function measurePolicy(context, name, visiting) {
     const children = refs.flatMap((ref) => {
         if (!context.isLocalPolicy(ref))
             return [];
-        const value = measurePolicy(context, ref.name, nested);
+        const value = measurePolicy(context, ref.name, nested, measures);
         return value === undefined ? [] : [value];
     });
     if (children.length !== refs.length || children.length === 0)

package/dist/v1/schema/validation/policy/typing.js

@@ -5,6 +5,13 @@ import { escapePointer } from './context.js';
 import { referenceContracts } from './objects.js';
 export class PolicyTyping {
     context;
+    // Expanded branches of each named Policy, cached by node identity. A Policy's expansion is reused
+    // across every composition path that reaches it (and across every use site and object contract,
+    // none of which the expansion depends on), so a shared-child composition DAG is expanded in work
+    // linear in the number of Policies instead of enumerating every path. The expansion result is
+    // independent of the reaching path up to the opaque term-namespace labels, which only ever
+    // disambiguate variables within one branch and leave targetMode and branch typing unchanged.
+    #expansions = new Map();
     constructor(context) {
         this.context = context;
     }
@@ -59,6 +66,14 @@ export class PolicyTyping {
     #expandedBranches(name, visiting, namespace) {
         if (visiting.has(name))
             return undefined;
+        const cached = this.#expansions.get(name);
+        if (cached !== undefined || this.#expansions.has(name))
+            return cached;
+        const expanded = this.#expandDeclaration(name, visiting, namespace);
+        this.#expansions.set(name, expanded);
+        return expanded;
+    }
+    #expandDeclaration(name, visiting, namespace) {
         const declaration = this.context.normalized.get(name);
         if (declaration === undefined)
             return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-dsl",
-  "version": "0.2.0-beta.43",
+  "version": "0.2.0-beta.45",
   "description": "Astrale Kernel DSL - Schema authoring, inference, and IR serialization",
   "license": "Apache-2.0",
   "repository": {
@@ -67,6 +67,10 @@
       "types": "./dist/v1/schema/index.d.ts",
       "import": "./dist/v1/schema/index.js"
     },
+    "./v1/schema/compatibility": {
+      "types": "./dist/v1/schema/compatibility/api.d.ts",
+      "import": "./dist/v1/schema/compatibility/api.js"
+    },
     "./v1/schema/fingerprint": {
       "types": "./dist/v1/schema/fingerprint.d.ts",
       "import": "./dist/v1/schema/fingerprint.js"

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

@@ -1,58 +0,0 @@
-/** 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

@@ -1,145 +0,0 @@
-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}`;
-        }
-    }
-}