@astrale-os/kernel-dsl 0.2.0-beta.42 → 0.2.0-beta.44

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/admission/semantics.js

@@ -6,6 +6,7 @@ import { isMethodExecutable } from '../../language/callable/executable.js';
 import { policyObjectKey, policyObjectOrigin, policyVariableClass, projectedMemberClass, } from '../../language/index.js';
 import { branchesOf, branchProduct, capBranches, isConnected, targetMode, termKey, } from '../../language/policy/analysis/branches.js';
 import { BRANCH_OVERFLOW, MAX_BRANCHES, MAX_CHECK_DEPTH, MAX_CHECK_LEAVES, MAX_DOMAINS, MAX_EDGES, MAX_PATTERN_DEPTH, MAX_REPEAT, MAX_VARIABLES, measureChecks, } from '../../language/policy/analysis/budgets.js';
+import { admittedCheckClasses, neverAdmittedClasses, } from '../../language/policy/analysis/checks.js';
 import { normalizePolicyExpression } from '../../language/policy/normalization/normalize.js';
 import { bindValueProgram } from '../../language/value/compile/load.js';
 import { validateValueProgram } from '../../language/value/evaluate/program.js';
@@ -538,6 +539,7 @@ function validateCallablePolicyTyping(context, typing, entry, expression, input,
         measure.leaves > MAX_CHECK_LEAVES) {
         fail(path, 'Callable Policy checks exceed the V1 depth, branch, or leaf budget.');
     }
+    const leaves = new Map();
     const visit = (value, pointer) => {
         if ('sameNode' in value)
             return;
@@ -547,12 +549,23 @@ function validateCallablePolicyTyping(context, typing, entry, expression, input,
             return;
         }
         const contracts = callableObjectContracts(context, entry, input, receiver, value.object);
-        if (contracts !== undefined &&
-            contracts.some((contract) => !typing.policyAccepts(value.check.name, contract))) {
+        if (contracts === undefined)
+            return;
+        const typings = new Map(contracts.map((contract) => [
+            contract.kind === 'exact' ? Key.of(contract.ref) : 'default',
+            typing.policyBranchTyping(value.check.name, contract),
+        ]));
+        const admitted = admittedCheckClasses(typings);
+        if (admitted === undefined) {
             fail(pointer, 'Named Policy is incompatible with the callable object contract.');
         }
+        leaves.set(value, { accepted: [...typings.keys()], admitted });
     };
     visit(expression, path);
+    const [never] = neverAdmittedClasses(expression, leaves);
+    if (never !== undefined) {
+        fail(path, `Callable Policy checks can never admit ${never[0]} of Class ${never[1]}.`);
+    }
 }
 function callableObjectContracts(context, entry, input, receiver, object) {
     if (object.kind === 'self') {
@@ -629,9 +642,11 @@ class CompiledPolicyTyping {
         return 'allOf' in declaration ? branchProduct(children) : capBranches(children.flat());
     }
     policyAccepts(name, object) {
+        return this.policyBranchTyping(name, object)?.every(Boolean) ?? false;
+    }
+    policyBranchTyping(name, object) {
         const branches = this.expandedBranches(name, new Set(), `$use:${name}`);
-        return (branches !== undefined &&
-            branches.every((branch) => this.branchIsTyped(branch, { kind: 'object', object })));
+        return branches?.map((branch) => this.branchIsTyped(branch, { kind: 'object', object }));
     }
     policyAcceptsEdge(name, source, target) {
         const branches = this.expandedBranches(name, new Set(), `$edge-use:${name}`);

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/policy/analysis/checks.d.ts

@@ -0,0 +1,28 @@
+import type { PolicyCheckExpression } from '../model/policy.js';
+export type PolicyCheckLeaf = Extract<PolicyCheckExpression, {
+    readonly check: unknown;
+}>;
+/** How one check leaf types against the Classes its object accepts. */
+export interface CheckLeafClasses {
+    /** Every Class the leaf's object accepts. */
+    readonly accepted: readonly string[];
+    /** The accepted Classes at least one normalized branch of the leaf's Policy is typed for. */
+    readonly admitted: ReadonlySet<string>;
+}
+/**
+ * The Classes a leaf admits, from the typing of each normalized branch of its Policy for each
+ * accepted Class of its object. `undefined` when the Policy does not expand, or when one branch is
+ * typed for no accepted Class: that branch can never match this object, so it is refused rather
+ * than silently erased.
+ */
+export declare function admittedCheckClasses(typing: ReadonlyMap<string, readonly boolean[] | undefined>): ReadonlySet<string> | undefined;
+/**
+ * The accepted Classes of each object that the whole check tree can never admit.
+ *
+ * The tree is read in disjunctive normal form. A conjunction admits Class C of object O when every
+ * leaf over O in it admits C and every other object it checks keeps a Class that all of its leaves
+ * over that object admit; an object the conjunction does not check keeps every accepted Class.
+ * `sameNode` compares identities, not Classes, so it never removes a Class here. A tree over the
+ * check budget is already refused, so it is not expanded.
+ */
+export declare function neverAdmittedClasses(expression: PolicyCheckExpression, leaves: ReadonlyMap<PolicyCheckLeaf, CheckLeafClasses>): readonly (readonly [object: string, className: string])[];

package/dist/v1/language/policy/analysis/checks.js

@@ -0,0 +1,80 @@
+import { policyObjectKey } from '../model/policy.js';
+import { MAX_BRANCHES, measureChecks } from './budgets.js';
+/** Names a callable check object. Every leaf over one object sees the same Node at runtime. */
+function checkObjectName(object) {
+    if (object.kind === 'self')
+        return 'self';
+    if (object.kind === 'input')
+        return `input.${object.field}`;
+    return policyObjectKey(object.ref);
+}
+/**
+ * The Classes a leaf admits, from the typing of each normalized branch of its Policy for each
+ * accepted Class of its object. `undefined` when the Policy does not expand, or when one branch is
+ * typed for no accepted Class: that branch can never match this object, so it is refused rather
+ * than silently erased.
+ */
+export function admittedCheckClasses(typing) {
+    const rows = [...typing];
+    if (!rows.every((row) => row[1] !== undefined)) {
+        return undefined;
+    }
+    const branches = Math.max(0, ...rows.map(([, row]) => row.length));
+    for (let index = 0; index < branches; index++) {
+        if (!rows.some(([, row]) => row[index] === true))
+            return undefined;
+    }
+    return new Set(rows.filter(([, row]) => row.some(Boolean)).map(([name]) => name));
+}
+/**
+ * The accepted Classes of each object that the whole check tree can never admit.
+ *
+ * The tree is read in disjunctive normal form. A conjunction admits Class C of object O when every
+ * leaf over O in it admits C and every other object it checks keeps a Class that all of its leaves
+ * over that object admit; an object the conjunction does not check keeps every accepted Class.
+ * `sameNode` compares identities, not Classes, so it never removes a Class here. A tree over the
+ * check budget is already refused, so it is not expanded.
+ */
+export function neverAdmittedClasses(expression, leaves) {
+    if (measureChecks(expression).branches > MAX_BRANCHES)
+        return [];
+    const accepted = new Map();
+    for (const [leaf, classes] of leaves)
+        accepted.set(checkObjectName(leaf.object), classes.accepted);
+    const admitted = new Map();
+    for (const conjunction of disjunctiveForm(expression)) {
+        const constrained = new Map();
+        for (const leaf of conjunction) {
+            if (!('check' in leaf))
+                continue;
+            const classes = leaves.get(leaf);
+            if (classes === undefined)
+                continue;
+            const object = checkObjectName(leaf.object);
+            const previous = constrained.get(object);
+            constrained.set(object, previous === undefined
+                ? classes.admitted
+                : new Set([...previous].filter((name) => classes.admitted.has(name))));
+        }
+        if ([...constrained.values()].some((classes) => classes.size === 0))
+            continue;
+        for (const [object, all] of accepted) {
+            const reached = admitted.get(object) ?? new Set();
+            for (const name of constrained.get(object) ?? all)
+                reached.add(name);
+            admitted.set(object, reached);
+        }
+    }
+    return [...accepted].flatMap(([object, all]) => all
+        .filter((name) => admitted.get(object)?.has(name) !== true)
+        .map((name) => [object, name]));
+}
+function disjunctiveForm(expression) {
+    if ('check' in expression || 'sameNode' in expression)
+        return [[expression]];
+    if ('anyOf' in expression)
+        return expression.anyOf.flatMap(disjunctiveForm);
+    return expression.allOf
+        .map(disjunctiveForm)
+        .reduce((left, right) => left.flatMap((prefix) => right.map((suffix) => [...prefix, ...suffix])), [[]]);
+}

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;