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

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

@@ -0,0 +1,37 @@
+import { json } from '@astrale-os/kernel-dsl/value';
+import { isValueObject as isJsonObject } from '../../../language/value/model/object.js';
+import { SCHEMA_ARRAY_KEYWORDS, SCHEMA_MAP_KEYWORDS, SCHEMA_SINGLE_KEYWORDS, } from '../../../language/value/syntax/keywords.js';
+import { digestDomainSchemaBytes } from '../../canonical/domain.digest.js';
+import { ANNOTATION_KEYWORDS } from '../fields.js';
+/** Drop annotation keywords wherever a schema keyword nests a schema; never inside data. */
+export function semanticValueSchema(value) {
+    if (typeof value === 'boolean')
+        return value;
+    const semantic = {};
+    for (const [keyword, entry] of Object.entries(value)) {
+        if (ANNOTATION_KEYWORDS.includes(keyword))
+            continue;
+        if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(entry)) {
+            semantic[keyword] = semanticValueSchema(entry);
+        }
+        else if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(entry)) {
+            semantic[keyword] = entry.map((item) => isJsonSchema(item) ? semanticValueSchema(item) : item);
+        }
+        else if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(entry)) {
+            semantic[keyword] = Object.fromEntries(Object.entries(entry).map(([name, item]) => [
+                name,
+                isJsonSchema(item) ? semanticValueSchema(item) : item,
+            ]));
+        }
+        else {
+            semantic[keyword] = entry;
+        }
+    }
+    return semantic;
+}
+export function fingerprintMeaning(value) {
+    return digestDomainSchemaBytes(json.encode(value));
+}
+function isJsonSchema(value) {
+    return typeof value === 'boolean' || isJsonObject(value);
+}

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

@@ -0,0 +1,5 @@
+import type { Comparison, ComparisonRequest, MeaningComparison, StructureComparison } from './model.js';
+/** Complete facts and independent conclusions, resolved against the same exact contexts. */
+export declare function compare(request: ComparisonRequest): Comparison;
+export declare function compareStructure(request: ComparisonRequest): StructureComparison;
+export declare function compareMeaning(request: ComparisonRequest): MeaningComparison;

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

@@ -0,0 +1,23 @@
+import { analyzeMeaning } from './meaning/index.js';
+import { mergeEntries } from './report.js';
+import { prepare } from './scope.js';
+import { analyzeStructure } from './structure/index.js';
+/** Complete facts and independent conclusions, resolved against the same exact contexts. */
+export function compare(request) {
+    const context = prepare(request);
+    const structure = analyzeStructure(context);
+    const meaning = analyzeMeaning(context);
+    return Object.freeze({
+        scope: context.scope,
+        entries: mergeEntries(structure.entries, meaning.entries),
+        structure,
+        meaning,
+        evidence: Object.freeze({ structure: structure.evidence, meaning: meaning.evidence }),
+    });
+}
+export function compareStructure(request) {
+    return analyzeStructure(prepare(request));
+}
+export function compareMeaning(request) {
+    return analyzeMeaning(prepare(request));
+}

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

@@ -0,0 +1,19 @@
+import type { ClassRef, DefinitionRef, Key as SemanticKey } from '../../addressing/index.js';
+import type { DefinitionAnalysis, EffectiveMethod } from '../analysis/class.js';
+import type { DomainSchema } from '../model/schema.js';
+import { SchemaError } from '../diagnostic.js';
+/** One accepted root with its exact closure and a memoized Definition analysis per owner. */
+export interface Context {
+    readonly schemas: ReadonlyMap<string, DomainSchema>;
+    analysis(owner: DomainSchema): ReadonlyMap<string, DefinitionAnalysis>;
+}
+/**
+ * Every owner passed acceptance against the closure it retains, which is the only way a schema
+ * gets one, so its analysis is derived without validating it again.
+ */
+export declare function contextOf(root: DomainSchema): Context;
+export declare function effectiveDefinition(context: Context, owner: DomainSchema, ref: ClassRef): DefinitionAnalysis | undefined;
+/** Effective Methods are keyed by name; a coordinate names one by its exact Method Key. */
+export declare function effectiveMethod(analysis: DefinitionAnalysis, key: SemanticKey): EffectiveMethod | undefined;
+export declare function requireOwner(context: Context, ref: DefinitionRef, key: SemanticKey): DomainSchema;
+export declare function contextInvalid(message: string, key: SemanticKey): SchemaError;

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

@@ -0,0 +1,49 @@
+import { MethodKey } from '../../addressing/index.js';
+import { definitionRefIndex } from '../../addressing/ordering.js';
+import { analyzeDefinitions } from '../analysis/class.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+import { knownDomainClosure, lookupForDomainClosure } from '../resolution/closure.js';
+import { buildDomainResolutionContext } from '../resolution/context.js';
+/**
+ * Every owner passed acceptance against the closure it retains, which is the only way a schema
+ * gets one, so its analysis is derived without validating it again.
+ */
+export function contextOf(root) {
+    const schemas = new Map([
+        [root.origin, root],
+        ...(knownDomainClosure(root) ?? []).map(({ schema }) => [schema.origin, schema]),
+    ]);
+    const analyses = new Map();
+    return {
+        schemas,
+        analysis(owner) {
+            let definitions = analyses.get(owner);
+            if (definitions === undefined) {
+                definitions = analyzeDefinitions(buildDomainResolutionContext(owner, lookupForDomainClosure(owner))).definitions;
+                analyses.set(owner, definitions);
+            }
+            return definitions;
+        },
+    };
+}
+export function effectiveDefinition(context, owner, ref) {
+    return context.analysis(owner).get(definitionRefIndex(ref));
+}
+/** Effective Methods are keyed by name; a coordinate names one by its exact Method Key. */
+export function effectiveMethod(analysis, key) {
+    for (const method of analysis.methods.values()) {
+        if (MethodKey.of(method.owner, method.name) === key)
+            return method;
+    }
+    return undefined;
+}
+export function requireOwner(context, ref, key) {
+    const owner = context.schemas.get(ref.origin);
+    if (owner === undefined) {
+        throw contextInvalid(`Retained acceptance context cannot resolve ${key}.`, key);
+    }
+    return owner;
+}
+export function contextInvalid(message, key) {
+    return new SchemaError([diagnostic('DM_DEPENDENCY_CONTEXT_INVALID', '', message, key)]);
+}

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

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

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

@@ -0,0 +1,38 @@
+import { Key, MethodKey, PropertyKey } from '../../addressing/index.js';
+import { SchemaError, diagnostic } from '../diagnostic.js';
+export function classCoordinate(ref) {
+    return Object.freeze({ kind: 'class', key: keyForDefinitionRef(ref), ref });
+}
+export function memberCoordinate(ref) {
+    return Object.freeze({ kind: 'member', key: keyForDefinitionRef(ref), ref });
+}
+export function propertyCoordinate(owner, name) {
+    return Object.freeze({ kind: 'property', key: PropertyKey.of(owner, name), owner, name });
+}
+export function methodCoordinate(owner, name) {
+    return Object.freeze({ kind: 'method', key: MethodKey.of(owner, name), owner, name });
+}
+export function keyForDefinitionRef(ref) {
+    return ref.kind === 'core'
+        ? Key.of(ref)
+        : Key.of(ref);
+}
+/** Interpret one canonical V1 Key as a Definition or a Class member location. */
+export function keyReference(key) {
+    const semantic = key.slice(key.indexOf(':') + 1);
+    const parts = semantic.split('.');
+    if (parts[0] === 'core' && parts.length === 2) {
+        return { kind: 'core', name: parts[1] };
+    }
+    if (parts.length === 2) {
+        return { kind: parts[0], name: parts[1] };
+    }
+    if (parts.length === 4 &&
+        parts[0] === 'class' &&
+        (parts[2] === 'property' || parts[2] === 'method')) {
+        return { kind: 'class', name: parts[3], member: parts[2], ownerName: parts[1] };
+    }
+    throw new SchemaError([
+        diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Key ${key} has no supported V1 shape.`, key),
+    ]);
+}

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

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

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

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

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

@@ -0,0 +1,16 @@
+import type { Analysis, ComparisonEvidence } from './model.js';
+/**
+ * Only semantic facts and decisions are durable; provenance and diagnostic prose are not. Each
+ * analysis names the oldest requirement policy that yields its facts: a version applies exactly when
+ * a fact it introduced is recorded, so a comparison without one keeps the earlier version's bytes.
+ */
+export declare function evidenceOf({ kind, version, scope, entries, assessments, }: Omit<Analysis, 'evidence'> & {
+    readonly kind: ComparisonEvidence['kind'];
+    readonly version: ComparisonEvidence['version'];
+}): ComparisonEvidence;
+/**
+ * Whether a referenced or inherited Class lost an effective Property. The fact is recorded only on a
+ * loss, so the evidence version that introduced it applies exactly when it is present
+ * (DM-CLASS-PROPERTIES).
+ */
+export declare function losesProperties({ entries }: Pick<Analysis, 'entries'>): boolean;

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

@@ -0,0 +1,62 @@
+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. Each
+ * analysis names the oldest requirement policy that yields its facts: a version applies exactly when
+ * a fact it introduced is recorded, so a comparison without one keeps the earlier version's bytes.
+ */
+export function evidenceOf({ kind, version, scope, entries, assessments, }) {
+    return Object.freeze({
+        kind,
+        version,
+        fingerprint: fingerprintMeaning({
+            kind,
+            version,
+            scope: {
+                kind: scope.kind,
+                source: [scope.source.origin, scope.source.revision],
+                target: [scope.target.origin, scope.target.revision],
+                dependent: scope.dependent === undefined ? null : [scope.dependent.origin, scope.dependent.revision],
+                roots: scope.roots,
+            },
+            observations: entries.flatMap((entry) => [...entry.observations]
+                .sort((a, b) => compareUnicode(evidenceFacet(a.facet), evidenceFacet(b.facet)))
+                .map((observation) => [
+                entry.subject.key,
+                evidenceFacet(observation.facet),
+                observation.before === undefined ? null : fingerprintMeaning(observation.before),
+                observation.after === undefined ? null : fingerprintMeaning(observation.after),
+            ])),
+            assessments: [...assessments]
+                .sort((a, b) => compareUnicode(`${a.subject.key}#${evidenceFacet(a.observation.facet)}`, `${b.subject.key}#${evidenceFacet(b.observation.facet)}`) ||
+                compareUnicode(evidenceFacet(a.requirement.kind), evidenceFacet(b.requirement.kind)))
+                .map((assessment) => [
+                assessment.subject.key,
+                evidenceFacet(assessment.observation.facet),
+                evidenceFacet(assessment.requirement.kind),
+                assessment.satisfied,
+            ]),
+        }),
+    });
+}
+/**
+ * Whether a referenced or inherited Class lost an effective Property. The fact is recorded only on a
+ * loss, so the evidence version that introduced it applies exactly when it is present
+ * (DM-CLASS-PROPERTIES).
+ */
+export function losesProperties({ entries }) {
+    return entries.some(({ observations }) => observations.some(({ facet }) => facet === 'class.properties'));
+}
+/** Version-1 evidence keeps its original tags independently of public facet names. */
+function evidenceFacet(facet) {
+    switch (facet) {
+        case 'method.signature':
+            return 'method.contract';
+        case 'function.signature':
+            return 'function.contract';
+        case 'method.inheritance':
+            return 'method.signature';
+        default:
+            return facet;
+    }
+}

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

@@ -0,0 +1,194 @@
+/**
+ * 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';
+/**
+ * Where one declaration field counts for a dependent:
+ * - `always`: at every usage level;
+ * - `inherit`: only when the dependent inherits or instantiates the Class;
+ * - `members`: as separate Property and Method coordinates with their own meaning;
+ * - `excluded`: never, for the stated reason.
+ *
+ * Every field of every declaration kind is classified below. A field added to the DSL does not
+ * compile until it is classified, so meaning can only be narrowed by an explicit decision.
+ */
+export type FieldRole = 'always' | 'inherit' | 'members' | {
+    readonly excluded: 'identity' | 'annotation' | 'authorization' | 'presentation';
+};
+/** The coordinate Key already names the declaration; its `ref` is never repeated in the meaning. */
+export declare const CLASS_FIELDS: Readonly<{
+    ref: Readonly<{
+        excluded: 'identity';
+    }>;
+    kind: "always";
+    abstract: "always";
+    orientation: "always";
+    extends: "inherit";
+    policies: "inherit";
+    data: "inherit";
+    endpoints: "inherit";
+    constraints: "inherit";
+    properties: "members";
+    methods: "members";
+    description: Readonly<{
+        excluded: 'annotation';
+    }>;
+    icon: Readonly<{
+        excluded: 'presentation';
+    }>;
+}>;
+export declare const PROPERTY_FIELDS: Readonly<{
+    schema: "always";
+    required: "always";
+    auto: "always";
+    immutable: "always";
+    state: "always";
+    description: Readonly<{
+        excluded: 'annotation';
+    }>;
+}>;
+/**
+ * The auth level and Policy check are decided by the Runtime at invocation, never compiled against.
+ * The execution modifier decides what an invocation returns; an accepted Schema carries it only
+ * when durable, so ordinary callables keep their meaning unchanged.
+ */
+export declare const CALLABLE_FIELDS: Readonly<{
+    ref: Readonly<{
+        excluded: 'identity';
+    }>;
+    input: "always";
+    output: "always";
+    static: "always";
+    abstract: "always";
+    execution: "always";
+    auth: Readonly<{
+        excluded: 'authorization';
+    }>;
+    policy: Readonly<{
+        excluded: 'authorization';
+    }>;
+    description: Readonly<{
+        excluded: 'annotation';
+    }>;
+}>;
+export declare const POLICY_FIELDS: Readonly<{
+    ref: Readonly<{
+        excluded: 'identity';
+    }>;
+    expression: "always";
+    description: Readonly<{
+        excluded: 'annotation';
+    }>;
+}>;
+export declare const VIEW_FIELDS: Readonly<{
+    ref: Readonly<{
+        excluded: 'identity';
+    }>;
+    target: "always";
+    description: Readonly<{
+        excluded: 'annotation';
+    }>;
+}>;
+export declare const CORE_FIELDS: Readonly<{
+    ref: Readonly<{
+        excluded: '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 declare const ANNOTATION_KEYWORDS: readonly string[];
+/** The complete classification, one table per declaration kind. */
+export declare const FIELD_ROLES: Readonly<{
+    class: Readonly<{
+        ref: Readonly<{
+            excluded: 'identity';
+        }>;
+        kind: "always";
+        abstract: "always";
+        orientation: "always";
+        extends: "inherit";
+        policies: "inherit";
+        data: "inherit";
+        endpoints: "inherit";
+        constraints: "inherit";
+        properties: "members";
+        methods: "members";
+        description: Readonly<{
+            excluded: 'annotation';
+        }>;
+        icon: Readonly<{
+            excluded: 'presentation';
+        }>;
+    }>;
+    property: Readonly<{
+        schema: "always";
+        required: "always";
+        auto: "always";
+        immutable: "always";
+        state: "always";
+        description: Readonly<{
+            excluded: 'annotation';
+        }>;
+    }>;
+    callable: Readonly<{
+        ref: Readonly<{
+            excluded: 'identity';
+        }>;
+        input: "always";
+        output: "always";
+        static: "always";
+        abstract: "always";
+        execution: "always";
+        auth: Readonly<{
+            excluded: 'authorization';
+        }>;
+        policy: Readonly<{
+            excluded: 'authorization';
+        }>;
+        description: Readonly<{
+            excluded: 'annotation';
+        }>;
+    }>;
+    policy: Readonly<{
+        ref: Readonly<{
+            excluded: 'identity';
+        }>;
+        expression: "always";
+        description: Readonly<{
+            excluded: 'annotation';
+        }>;
+    }>;
+    view: Readonly<{
+        ref: Readonly<{
+            excluded: 'identity';
+        }>;
+        target: "always";
+        description: Readonly<{
+            excluded: 'annotation';
+        }>;
+    }>;
+    core: Readonly<{
+        ref: Readonly<{
+            excluded: 'identity';
+        }>;
+        class: "always";
+        properties: "always";
+        source: "always";
+        target: "always";
+    }>;
+}>;
+/** Classification drives projection; special semantic normalization stays with each comparator. */
+export declare function fieldsOf({ declaration, roles, level, }: {
+    readonly declaration: object;
+    readonly roles: Readonly<Record<string, FieldRole>>;
+    readonly level?: DependencyMeaningLevel;
+}): Readonly<Record<string, unknown>>;

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

@@ -0,0 +1,94 @@
+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',
+    immutable: 'always',
+    state: 'always',
+    description: ANNOTATION,
+});
+/**
+ * The auth level and Policy check are decided by the Runtime at invocation, never compiled against.
+ * The execution modifier decides what an invocation returns; an accepted Schema carries it only
+ * when durable, so ordinary callables keep their meaning unchanged.
+ */
+export const CALLABLE_FIELDS = Object.freeze({
+    ref: IDENTITY,
+    input: 'always',
+    output: 'always',
+    static: 'always',
+    abstract: 'always',
+    execution: '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,
+});
+/** Classification drives projection; special semantic normalization stays with each comparator. */
+export function fieldsOf({ declaration, roles, level = 'reference', }) {
+    return Object.fromEntries(Object.entries(declaration).filter(([name, value]) => value !== undefined &&
+        (roles[name] === 'always' || (level === 'inherit' && roles[name] === 'inherit'))));
+}

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

@@ -0,0 +1,6 @@
+export * from './api.js';
+export type { MeaningDifference } from './diff.js';
+export { ANNOTATION_KEYWORDS, FIELD_ROLES } 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

@@ -0,0 +1,3 @@
+export * from './api.js';
+export { ANNOTATION_KEYWORDS, FIELD_ROLES } from './fields.js';
+export { callableFingerprint } from './comparators/callables.js';

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

@@ -0,0 +1,7 @@
+import type { Report } from '../report.js';
+import type { ComparisonContext } from '../scope.js';
+/** Meaning follows complete callable contracts through the exact authored reference closure. */
+export declare function compareFootprint({ context, report, }: {
+    readonly context: ComparisonContext;
+    readonly report: Report;
+}): void;