@astrale-os/kernel-dsl 0.2.0-beta.4 → 0.2.0-beta.40

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

@@ -0,0 +1,186 @@
+/**
+ * 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";
+    state: "always";
+    description: Readonly<{
+        excluded: 'annotation';
+    }>;
+}>;
+/** The auth level and Policy check are decided by the Runtime at invocation, never compiled against. */
+export declare const CALLABLE_FIELDS: Readonly<{
+    ref: Readonly<{
+        excluded: 'identity';
+    }>;
+    input: "always";
+    output: "always";
+    static: "always";
+    abstract: "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";
+        state: "always";
+        description: Readonly<{
+            excluded: 'annotation';
+        }>;
+    }>;
+    callable: Readonly<{
+        ref: Readonly<{
+            excluded: 'identity';
+        }>;
+        input: "always";
+        output: "always";
+        static: "always";
+        abstract: "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,88 @@
+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,
+});
+/** 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,8 @@
+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 { callableFingerprint } from './comparators/callables.js';
+export type { Fingerprint as MeaningFingerprint } from './model.js';

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

@@ -0,0 +1,4 @@
+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/legacy/index.d.ts

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

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

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;

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

@@ -0,0 +1,57 @@
+import { Key } from '../../../addressing/index.js';
+import { compareAddedProperties } from '../comparators/classes.js';
+import { compareFacet } from '../comparators/index.js';
+import { contextInvalid } from '../context.js';
+import { callableReferences, classReferences, inherits, memberReferences, valueReferences, } from '../references.js';
+/** Meaning follows complete callable contracts through the exact authored reference closure. */
+export function compareFootprint({ context, report, }) {
+    const queue = [...context.roots];
+    const visited = new Set();
+    for (const reference of queue) {
+        report.note(reference);
+        const { coordinate, usage } = reference;
+        const visit = `${coordinate.key}:${usage.relation}`;
+        if (visited.has(visit))
+            continue;
+        visited.add(visit);
+        const pair = context.pair(coordinate);
+        const subject = pair.source;
+        if (subject === undefined)
+            throw contextInvalid(`Retained acceptance context has no meaning for ${coordinate.key}.`, coordinate.key);
+        let facet;
+        switch (subject.kind) {
+            case 'class': {
+                facet = inherits(usage) ? 'class.inherit' : 'class.reference';
+                queue.push(...classReferences(subject, false));
+                if (inherits(usage))
+                    queue.push(...classReferences(subject, true));
+                break;
+            }
+            case 'property':
+                facet = 'property';
+                queue.push(...valueReferences(subject));
+                break;
+            case 'method':
+                facet = 'method.signature';
+                queue.push(...callableReferences(subject));
+                break;
+            case 'member': {
+                facet =
+                    subject.coordinate.ref.kind === 'function'
+                        ? 'function.signature'
+                        : subject.coordinate.ref.kind;
+                queue.push(...memberReferences(subject));
+            }
+        }
+        if (Key.origin(coordinate.key) !== context.source.origin)
+            continue;
+        report.record({
+            pair,
+            facet,
+            ...compareFacet({ context, pair, facet }),
+            requirement: { kind: facet },
+        });
+        if (facet === 'class.inherit')
+            compareAddedProperties({ context, pair, report });
+    }
+}

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

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

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

@@ -0,0 +1,14 @@
+import { evidenceOf } from '../evidence.js';
+import { createReport } from '../report.js';
+import { compareFootprint } from './footprint.js';
+export function analyzeMeaning(context) {
+    const report = createReport();
+    compareFootprint({ context, report });
+    const result = { scope: context.scope, ...report.finish() };
+    return Object.freeze({
+        kind: 'meaning',
+        ...result,
+        equivalent: result.assessments.every(({ satisfied }) => satisfied),
+        evidence: evidenceOf({ kind: 'meaning', ...result }),
+    });
+}

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

@@ -0,0 +1,96 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { Definition, Key, Revision } from '../../addressing/index.js';
+import type { DomainSchema } from '../model/schema.js';
+import type { ReferenceSite } from '../resolution/origins.js';
+import type { MeaningDifference } from './diff.js';
+export type Fingerprint = `sha256:${string}`;
+/** Inputs carry accepted schemas; a dependency's source is always its retained exact context. */
+export interface ComparisonRequest {
+    readonly scope: {
+        readonly kind: 'dependency';
+        readonly dependent: DomainSchema;
+    } | {
+        readonly kind: 'members';
+        readonly source: DomainSchema;
+        readonly roots: readonly [Key, ...Key[]];
+    };
+    readonly target: DomainSchema;
+}
+export interface SchemaIdentity {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+}
+export interface ComparisonScope {
+    readonly kind: ComparisonRequest['scope']['kind'];
+    readonly source: SchemaIdentity;
+    readonly target: SchemaIdentity;
+    readonly dependent?: SchemaIdentity;
+    readonly roots: readonly Key[];
+}
+/** Identity contains no requirement or usage level. */
+export interface Subject {
+    readonly key: Key;
+    readonly kind: Definition.Kind | 'property' | 'method';
+}
+/** Immediate provenance, retained even when several paths impose the same requirement. */
+export interface Usage {
+    readonly source: SchemaIdentity;
+    readonly key?: Key;
+    readonly relation: ReferenceSite | 'member' | 'abstract' | 'selection';
+}
+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. */
+export interface Observation {
+    readonly id: string;
+    readonly facet: Facet;
+    readonly state: 'equal' | 'changed' | 'missing' | 'added';
+    readonly before?: Value;
+    readonly after?: Value;
+    readonly differences: readonly MeaningDifference[];
+}
+export interface ComparisonEntry {
+    readonly subject: Subject;
+    readonly source?: SchemaIdentity;
+    readonly target?: SchemaIdentity;
+    readonly usages: readonly Usage[];
+    readonly observations: readonly Observation[];
+}
+/** An established requirement; observations without one remain visible but do not affect the conclusion. */
+export interface Assessment {
+    readonly subject: Subject;
+    readonly observation: Observation;
+    readonly requirement: {
+        readonly kind: Facet;
+    };
+    readonly satisfied: boolean;
+}
+/** Evidence is a semantic projection; presentation/provenance never enters its digest. */
+export interface ComparisonEvidence {
+    readonly kind: 'structure' | 'meaning';
+    readonly version: 1 | 2;
+    readonly fingerprint: Fingerprint;
+}
+export interface Analysis {
+    readonly scope: ComparisonScope;
+    readonly entries: readonly ComparisonEntry[];
+    readonly assessments: readonly Assessment[];
+    readonly evidence: ComparisonEvidence;
+}
+export interface StructureComparison extends Analysis {
+    readonly kind: 'structure';
+    readonly compatible: boolean;
+}
+export interface MeaningComparison extends Analysis {
+    readonly kind: 'meaning';
+    readonly equivalent: boolean;
+}
+export interface Comparison {
+    readonly scope: ComparisonScope;
+    readonly entries: readonly ComparisonEntry[];
+    readonly structure: StructureComparison;
+    readonly meaning: MeaningComparison;
+    readonly evidence: {
+        readonly structure: ComparisonEvidence;
+        readonly meaning: ComparisonEvidence;
+    };
+}

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

@@ -0,0 +1 @@
+export {};