@astrale-os/kernel-dsl 0.2.0-beta.34 → 0.2.0-beta.36

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

@@ -0,0 +1,83 @@
+const IDENTITY = Object.freeze({ excluded: 'identity' });
+const ANNOTATION = Object.freeze({ excluded: 'annotation' });
+const AUTHORIZATION = Object.freeze({ excluded: 'authorization' });
+const PRESENTATION = Object.freeze({ excluded: 'presentation' });
+/** The coordinate Key already names the declaration; its `ref` is never repeated in the meaning. */
+export const CLASS_FIELDS = Object.freeze({
+    ref: IDENTITY,
+    kind: 'always',
+    abstract: 'always',
+    orientation: 'always',
+    extends: 'inherit',
+    policies: 'inherit',
+    data: 'inherit',
+    endpoints: 'inherit',
+    constraints: 'inherit',
+    properties: 'members',
+    methods: 'members',
+    description: ANNOTATION,
+    icon: PRESENTATION,
+});
+export const PROPERTY_FIELDS = Object.freeze({
+    schema: 'always',
+    required: 'always',
+    auto: 'always',
+    state: 'always',
+    description: ANNOTATION,
+});
+/** The auth level and Policy check are decided by the Runtime at invocation, never compiled against. */
+export const CALLABLE_FIELDS = Object.freeze({
+    ref: IDENTITY,
+    input: 'always',
+    output: 'always',
+    static: 'always',
+    abstract: 'always',
+    auth: AUTHORIZATION,
+    policy: AUTHORIZATION,
+    description: ANNOTATION,
+});
+export const POLICY_FIELDS = Object.freeze({
+    ref: IDENTITY,
+    expression: 'always',
+    description: ANNOTATION,
+});
+export const VIEW_FIELDS = Object.freeze({
+    ref: IDENTITY,
+    target: 'always',
+    description: ANNOTATION,
+});
+export const CORE_FIELDS = Object.freeze({
+    ref: IDENTITY,
+    class: 'always',
+    properties: 'always',
+    source: 'always',
+    target: 'always',
+});
+/**
+ * JSON Schema keywords that annotate a value schema without constraining its values. Every other
+ * keyword, `x-astrale-path` included, is semantic; arbitrary JSON data is never inspected as schema.
+ * A frozen, Unicode-ordered list like the role tables: printable, and immutable at runtime.
+ */
+export const ANNOTATION_KEYWORDS = Object.freeze([
+    '$comment',
+    'contentEncoding',
+    'contentMediaType',
+    'contentSchema',
+    'default',
+    'deprecated',
+    'description',
+    'examples',
+    'format',
+    'readOnly',
+    'title',
+    'writeOnly',
+]);
+/** The complete classification, one table per declaration kind. */
+export const FIELD_ROLES = Object.freeze({
+    class: CLASS_FIELDS,
+    property: PROPERTY_FIELDS,
+    callable: CALLABLE_FIELDS,
+    policy: POLICY_FIELDS,
+    view: VIEW_FIELDS,
+    core: CORE_FIELDS,
+});

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

@@ -0,0 +1,25 @@
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { Key as SemanticKey } from '../../addressing/index.js';
+import type { DomainSchema } from '../model/schema.js';
+import type { Context } from './context.js';
+import type { Coordinate } from './coordinate.js';
+import type { DependencyMeaningLevel } from './fields.js';
+import type { ClassRequirement, MeaningFingerprint } from './meaning.js';
+/** One footprint coordinate with the meaning the dependent was authored against. */
+export interface SourceMeaning {
+    readonly coordinate: Coordinate;
+    readonly meaning: JsonValue;
+    readonly fingerprint: MeaningFingerprint;
+    readonly requirement?: ClassRequirement;
+}
+/** Every dependency Definition the dependent's own declarations name, at its strongest usage. */
+export declare function collectSchemaRoots(owner: DomainSchema): readonly Coordinate[];
+/**
+ * The transitive footprint: from the roots, every Class, Property, Method, Function, Policy, View
+ * and Core coordinate of the selected origin that the dependent's meaning reaches. A Class carries
+ * its strongest usage level; only inheritance traverses ancestors and Edge endpoint contracts, and
+ * a reached callable contributes its contract references but never its Policy check.
+ */
+export declare function collectReachableMeanings(roots: readonly Coordinate[], selectedOrigin: string, context: Context): ReadonlyMap<SemanticKey, SourceMeaning>;
+/** 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, level?: DependencyMeaningLevel): Coordinate;

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

@@ -0,0 +1,263 @@
+import { Key } from '../../addressing/index.js';
+import { compareUnicode, definitionRefIndex } from '../../addressing/ordering.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+import { collectCallableContractRefs, collectCallableRefs, collectClassPolicyRefs, collectClassRefs, collectCoreRefs, collectEndpointRefs, collectPolicyDefinitionRefs, collectValueDefinitionRefs, } from '../resolution/origins.js';
+import { contextInvalid, effectiveDefinition, effectiveMethod, requireOwner } from './context.js';
+import { classCoordinate, keyReference, levelOf, memberCoordinate, methodCoordinate, propertyCoordinate, } from './coordinate.js';
+import { classMeaning, fingerprintMeaning, meaningForCoordinate, memberMeaning, methodMeaning, propertyMeaning, } from './meaning.js';
+/** Every dependency Definition the dependent's own declarations name, at its strongest usage. */
+export function collectSchemaRoots(owner) {
+    const classes = new Map();
+    const members = new Map();
+    const add = (ref, site) => {
+        if (ref.kind === 'class') {
+            const index = definitionRefIndex(ref);
+            const level = levelOf(site);
+            const previous = classes.get(index);
+            if (previous === undefined || (previous.level === 'reference' && level === 'inherit')) {
+                classes.set(index, classCoordinate(ref, level));
+            }
+            return;
+        }
+        members.set(definitionRefIndex(ref), memberCoordinate(ref));
+    };
+    for (const declaration of Object.values(owner.classes))
+        collectClassRefs(declaration, add);
+    for (const declaration of Object.values(owner.functions))
+        collectCallableRefs(declaration, add);
+    for (const declaration of Object.values(owner.policies)) {
+        collectPolicyDefinitionRefs(declaration, add);
+    }
+    for (const declaration of Object.values(owner.views)) {
+        if (declaration.target.kind === 'definition') {
+            declaration.target.definitions.forEach((ref) => add(ref, 'view'));
+        }
+    }
+    collectCoreRefs(owner, add);
+    return [...classes.values(), ...members.values()].sort((left, right) => compareUnicode(left.key, right.key));
+}
+/**
+ * The transitive footprint: from the roots, every Class, Property, Method, Function, Policy, View
+ * and Core coordinate of the selected origin that the dependent's meaning reaches. A Class carries
+ * its strongest usage level; only inheritance traverses ancestors and Edge endpoint contracts, and
+ * a reached callable contributes its contract references but never its Policy check.
+ */
+export function collectReachableMeanings(roots, selectedOrigin, context) {
+    const meanings = new Map();
+    const classLevels = new Map();
+    const visitedMembers = new Set();
+    const pendingClasses = [];
+    const pendingMembers = [];
+    const push = (ref, site) => {
+        if (ref.kind === 'class')
+            pendingClasses.push(classCoordinate(ref, levelOf(site)));
+        else
+            pendingMembers.push(memberCoordinate(ref));
+    };
+    for (const coordinate of roots) {
+        if (coordinate.kind === 'class') {
+            pendingClasses.push(coordinate);
+            continue;
+        }
+        if (coordinate.kind === 'member') {
+            pendingMembers.push(coordinate);
+            continue;
+        }
+        const meaning = meaningForCoordinate(context, coordinate);
+        if (meaning === undefined) {
+            throw new SchemaError([
+                diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Member comparison root ${coordinate.key} does not exist in its source context.`, coordinate.key),
+            ]);
+        }
+        retainMeaning(meanings, selectedOrigin, coordinate, meaning);
+        collectCoordinateSemanticRefs(context, coordinate, push);
+    }
+    const visitClass = (coordinate) => {
+        const index = definitionRefIndex(coordinate.ref);
+        const previous = classLevels.get(index);
+        if (previous === 'inherit' || previous === coordinate.level)
+            return;
+        classLevels.set(index, coordinate.level);
+        const owner = requireOwner(context, coordinate.ref, coordinate.key);
+        const declaration = owner.classes[coordinate.ref.name];
+        const analysis = effectiveDefinition(context, owner, coordinate.ref);
+        const resolved = classMeaning(context, coordinate);
+        if (declaration === undefined || analysis === undefined || resolved === undefined) {
+            throw contextInvalid(`Retained acceptance context has no meaning for ${coordinate.key}.`, coordinate.key);
+        }
+        retainMeaning(meanings, selectedOrigin, coordinate, resolved.meaning, resolved.requirement);
+        if (previous === undefined) {
+            // The surface is level-independent: every effective Property and Method the dependent may
+            // read or call, with the Definitions their contracts and policies name.
+            for (const field of analysis.properties.values()) {
+                retainMeaning(meanings, selectedOrigin, propertyCoordinate(field.owner, field.name), propertyMeaning(field));
+                collectValueDefinitionRefs(field.schema, push);
+            }
+            for (const method of analysis.methods.values()) {
+                retainMeaning(meanings, selectedOrigin, methodCoordinate(method.owner, method.name), methodMeaning(method));
+                collectCallableContractRefs(method.declaration, push);
+            }
+            collectClassPolicyRefs(declaration, push);
+        }
+        if (coordinate.level === 'inherit') {
+            // Only inheritance takes on the ancestry and, for an Edge, the endpoint contract.
+            declaration.extends.forEach((parent) => push(parent, 'extends'));
+            if (declaration.kind === 'edge')
+                collectEndpointRefs(declaration, push);
+        }
+    };
+    const visitMember = (coordinate) => {
+        const index = definitionRefIndex(coordinate.ref);
+        if (visitedMembers.has(index))
+            return;
+        visitedMembers.add(index);
+        const owner = requireOwner(context, coordinate.ref, coordinate.key);
+        const meaning = memberMeaning(owner, coordinate.ref);
+        if (meaning === undefined) {
+            throw contextInvalid(`Retained acceptance context has no meaning for ${coordinate.key}.`, coordinate.key);
+        }
+        retainMeaning(meanings, selectedOrigin, coordinate, meaning);
+        collectMemberSemanticRefs(owner, coordinate.ref, push);
+    };
+    let classIndex = 0;
+    let memberIndex = 0;
+    while (classIndex < pendingClasses.length || memberIndex < pendingMembers.length) {
+        if (classIndex < pendingClasses.length)
+            visitClass(pendingClasses[classIndex++]);
+        else
+            visitMember(pendingMembers[memberIndex++]);
+    }
+    return meanings;
+}
+/** Resolve one caller-supplied Key of the source into an exact coordinate that exists there. */
+export function coordinateForKey(context, source, input, index, level = 'reference') {
+    let key;
+    try {
+        key = Key(input);
+    }
+    catch {
+        return invalidMemberRoot(input, index, 'is not a canonical semantic Key');
+    }
+    if (Key.origin(key) !== source.origin) {
+        return invalidMemberRoot(key, index, `belongs to ${Key.origin(key)}, not source ${source.origin}`);
+    }
+    const reference = keyReference(key);
+    let coordinate;
+    if (reference.member !== undefined && reference.ownerName !== undefined) {
+        if (source.classes[reference.ownerName] === undefined) {
+            return invalidMemberRoot(key, index, 'has no exact owning Definition');
+        }
+        const owner = { origin: source.origin, kind: 'class', name: reference.ownerName };
+        coordinate =
+            reference.member === 'property'
+                ? propertyCoordinate(owner, reference.name)
+                : methodCoordinate(owner, reference.name);
+    }
+    else if (reference.kind === 'class') {
+        if (source.classes[reference.name] === undefined) {
+            return invalidMemberRoot(key, index, 'does not exist in the source');
+        }
+        // A Class root takes the caller's level; compareMemberMeaning passes none and compares the
+        // surface at reference level without inferring an inheritance contract.
+        coordinate = classCoordinate({ origin: source.origin, kind: 'class', name: reference.name }, level);
+    }
+    else {
+        coordinate = memberCoordinate({
+            origin: source.origin,
+            kind: reference.kind,
+            name: reference.name,
+        });
+    }
+    if (meaningForCoordinate(context, coordinate) === undefined) {
+        return invalidMemberRoot(key, index, 'does not exist in the source');
+    }
+    return coordinate;
+}
+function collectCoordinateSemanticRefs(context, coordinate, add) {
+    const owner = context.schemas.get(coordinate.owner.origin);
+    const analysis = owner === undefined ? undefined : effectiveDefinition(context, owner, coordinate.owner);
+    if (analysis === undefined)
+        return;
+    if (coordinate.kind === 'property') {
+        const field = analysis.properties.get(coordinate.key);
+        if (field !== undefined)
+            collectValueDefinitionRefs(field.schema, add);
+        return;
+    }
+    const method = effectiveMethod(analysis, coordinate.key);
+    if (method !== undefined)
+        collectCallableContractRefs(method.declaration, add);
+}
+function collectMemberSemanticRefs(owner, ref, add) {
+    switch (ref.kind) {
+        case 'function': {
+            const declaration = owner.functions[ref.name];
+            if (declaration !== undefined)
+                collectCallableRefs(declaration, add);
+            return;
+        }
+        case 'policy': {
+            const declaration = owner.policies[ref.name];
+            if (declaration !== undefined)
+                collectPolicyDefinitionRefs(declaration, add);
+            return;
+        }
+        case 'view': {
+            const declaration = owner.views[ref.name];
+            if (declaration?.target.kind === 'definition') {
+                declaration.target.definitions.forEach((definition) => add(definition, 'view'));
+            }
+            return;
+        }
+        case 'core': {
+            // The dependency instantiates its own Core; the dependent only refers to it.
+            const node = owner.core.nodes[ref.name];
+            if (node === undefined)
+                return;
+            add(node.class);
+            for (const edge of owner.core.edges) {
+                const incident = (edge.source.kind === 'core' && edge.source.name === ref.name) ||
+                    (edge.target.kind === 'core' && edge.target.name === ref.name);
+                if (!incident)
+                    continue;
+                add(edge.class);
+                if (edge.source.kind !== 'domain')
+                    add(edge.source);
+                if (edge.target.kind !== 'domain')
+                    add(edge.target);
+            }
+        }
+    }
+}
+function retainMeaning(meanings, selectedOrigin, coordinate, meaning, requirement) {
+    if (Key.origin(coordinate.key) !== selectedOrigin)
+        return;
+    const fingerprint = fingerprintMeaning(meaning);
+    const previous = meanings.get(coordinate.key);
+    if (previous !== undefined) {
+        const upgraded = previous.coordinate.kind === 'class' &&
+            coordinate.kind === 'class' &&
+            previous.coordinate.level !== coordinate.level;
+        if (upgraded) {
+            // A stronger requirement replaces the weaker one for the same Class.
+            if (coordinate.level === 'reference')
+                return;
+        }
+        else if (previous.fingerprint !== fingerprint) {
+            throw new SchemaError([
+                diagnostic('DM_MEANING_INCONSISTENT', '', `Semantic coordinate ${coordinate.key} produced inconsistent effective meaning.`, coordinate.key),
+            ]);
+        }
+    }
+    meanings.set(coordinate.key, Object.freeze({
+        coordinate,
+        meaning,
+        fingerprint,
+        ...(requirement === undefined ? {} : { requirement }),
+    }));
+}
+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/index.d.ts

@@ -0,0 +1,7 @@
+export { compareDependencyMeaning, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './compare.js';
+export type { DependencyMeaningChange, DependencyMeaningChangeKind, DependencyMeaningComparison, FootprintEntry, } from './compare.js';
+export type { MeaningDifference } from './diff.js';
+export { ANNOTATION_KEYWORDS, FIELD_ROLES } from './fields.js';
+export type { DependencyMeaningLevel, FieldRole } from './fields.js';
+export { callableFingerprint } from './meaning.js';
+export type { MeaningFingerprint } from './meaning.js';

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

@@ -0,0 +1,3 @@
+export { compareDependencyMeaning, compareMemberMeaning, describeMeaningChange, footprintOf, meaningOf, } from './compare.js';
+export { ANNOTATION_KEYWORDS, FIELD_ROLES } from './fields.js';
+export { callableFingerprint } from './meaning.js';

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

@@ -1,44 +1,44 @@
-import type { Key as SemanticKey } from '../../addressing/index.js';
-import type { Revision } from '../../addressing/index.js';
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { Key as SemanticKey, PropertyKey as SemanticPropertyKey } from '../../addressing/index.js';
+import type { ResolvedFunction, ResolvedMethod } from '../../language/callable/resolved.js';
+import type { JsonSchema } from '../../language/value/model/schema.js';
+import type { EffectiveField, EffectiveMethod } from '../analysis/class.js';
 import type { DomainSchema } from '../model/schema.js';
-import { Key } from '../../addressing/index.js';
-/**
- * How strongly a dependent relies on a dependency Class. `inherit` covers `extends` and Core
- * instantiation, which take on the Class creation contract; `reference` covers every other site,
- * which only names the Class and reads its surface.
- */
-export type DependencyMeaningLevel = 'reference' | 'inherit';
-export type DependencyMeaningChangeKind = 'missing' | 'changed' | 'added';
+import type { Context } from './context.js';
+import type { ClassCoordinate, Coordinate, MemberRef } from './coordinate.js';
 export type MeaningFingerprint = `sha256:${string}`;
-export type DependencyMeaningChange = {
-    readonly key: SemanticKey;
-    readonly kind: 'missing';
-    readonly sourceFingerprint: MeaningFingerprint;
-} | {
-    readonly key: SemanticKey;
-    readonly kind: 'changed';
-    readonly sourceFingerprint: MeaningFingerprint;
-    readonly targetFingerprint: MeaningFingerprint;
-} | {
-    /** A required, non-automatic Property the target adds to an inherited Class. */
-    readonly key: SemanticKey;
-    readonly kind: 'added';
-    readonly targetFingerprint: MeaningFingerprint;
-};
-export interface DependencyMeaningComparison {
-    readonly version: 2;
-    readonly dependency: Key.Origin;
-    readonly source: Revision;
-    readonly target: Revision;
-    readonly footprint: readonly SemanticKey[];
-    readonly changes: readonly DependencyMeaningChange[];
-    readonly fingerprint: MeaningFingerprint;
+/** What the source Class projects onto the target before comparing an inherited Class. */
+export interface ClassRequirement {
+    readonly ancestors: readonly SemanticKey[];
+    readonly properties: ReadonlySet<SemanticPropertyKey>;
 }
 /**
- * Compare the exact V1 meaning one accepted Domain used from a retained dependency with a
- * candidate revision of that same dependency origin. This operation is pure and makes no
- * lifecycle-compatibility decision.
+ * The meaning of one coordinate is a portable value built from the fields `fields.ts` classifies
+ * as counting at the coordinate's usage level; `__tests__/fields.test.ts` proves the two agree.
+ * Comparison works on these values, so every difference can name its exact path.
+ */
+export declare function meaningForCoordinate(context: Context, coordinate: Coordinate, requirement?: ClassRequirement): JsonValue | undefined;
+/**
+ * A reference needs the Class to exist with its kind, abstractness and orientation; inheritance
+ * additionally takes on the source ancestors, class policies, data contract and, for an Edge, the
+ * endpoint and constraint contracts. A target projected onto a source requirement keeps only the
+ * ancestors the source named, so a superset satisfies it while a removal changes it.
+ */
+export declare function classMeaning(context: Context, coordinate: ClassCoordinate, onto?: ClassRequirement): {
+    readonly meaning: JsonValue;
+    readonly requirement: ClassRequirement;
+} | undefined;
+export declare function memberMeaning(owner: DomainSchema, ref: MemberRef): JsonValue | undefined;
+export declare function propertyMeaning(field: EffectiveField): JsonValue;
+export declare function methodMeaning(method: EffectiveMethod): JsonValue;
+/**
+ * Fingerprint the contract a caller compiles against, independently of its Domain revision: the
+ * exact key, the owner, dispatch and abstractness of a Method, and the semantic input and output
+ * contracts; authorization is excluded (DM-CALLABLE-FINGERPRINT). A static consumer pins this
+ * instead of a Domain revision, so a dependency release that leaves the callable contract untouched
+ * keeps every bound invocation valid.
  */
-export declare function compareDependencyMeaning(dependent: DomainSchema, target: DomainSchema): DependencyMeaningComparison;
-/** Compare one explicit non-empty source member surface and its reachable V1 meaning. */
-export declare function compareMemberMeaning(source: DomainSchema, target: DomainSchema, roots: readonly [SemanticKey, ...SemanticKey[]]): DependencyMeaningComparison;
+export declare function callableFingerprint(callable: ResolvedFunction | ResolvedMethod): MeaningFingerprint;
+/** Drop annotation keywords wherever a schema keyword nests a schema; never inside data. */
+export declare function semanticValueSchema(value: JsonSchema): JsonSchema;
+export declare function fingerprintMeaning(value: unknown): MeaningFingerprint;