@contentful/experience-design-system-types 2.42.1-dev-build-f69db6bf.0 → 2.43.0-alpha.0

package/dist/src/property-contract/compact-model-components.js

@@ -0,0 +1,113 @@
+import { cloneJson } from './json-value.js';
+/** Compact physical authoring scaffolding while retaining every logical source node. */
+export function compactModelComponents({ nodes, models, mappings, attachment, }) {
+    const wrappers = new Map();
+    for (const model of models.values()) {
+        const node = nodes.get(model.nodeId);
+        const slots = Object.entries(model.entry.$slots ?? {});
+        if (Object.keys(model.entry.$properties).length || slots.length !== 1 || node.branchConditions?.length)
+            continue;
+        const [name, slot] = slots[0];
+        if (slot.$allowedComponents?.length !== 1 || !slot.$cardinality)
+            continue;
+        const childKey = slot.$allowedComponents[0];
+        const childNodeId = slot.$modelBinding?.nodeId;
+        if (!childNodeId)
+            continue;
+        let reconstruction;
+        if (node.kind === 'union' && !node.unionBranches && name === 'value') {
+            const alternatives = node.alternatives ?? [];
+            const values = alternatives.filter((id) => !['null', 'undefined', 'never'].includes(nodes.get(id).kind));
+            if (values.length === 1 && values[0] === childNodeId)
+                reconstruction = { kind: 'optional-value', valueNodeId: childNodeId };
+        }
+        else if (node.kind === 'record' &&
+            node.fields?.length === 1 &&
+            !node.indexSignatures?.length &&
+            !node.callSignatures?.length &&
+            node.fields[0].key === name &&
+            node.fields[0].nodeId === childNodeId)
+            reconstruction = { kind: 'object-envelope', field: name, valueNodeId: childNodeId };
+        else if (node.kind === 'array' && node.items?.length === 1 && name === 'items' && node.items[0] === childNodeId)
+            reconstruction = { kind: 'ordered-array', itemNodeId: childNodeId };
+        if (reconstruction)
+            wrappers.set(model.key, { childKey, slot, reconstruction });
+    }
+    const repeated = new Set();
+    for (const model of models.values())
+        for (const slot of Object.values(model.entry.$slots ?? {}))
+            if (slot.$cardinality?.max !== 1)
+                for (const key of slot.$allowedComponents ?? [])
+                    repeated.add(key);
+    // Transparent envelopes inherit their incoming element boundary; nested collections retain theirs.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [key, wrapper] of wrappers)
+            if (repeated.has(key) && wrapper.reconstruction.kind !== 'ordered-array' && !repeated.has(wrapper.childKey)) {
+                repeated.add(wrapper.childKey);
+                changed = true;
+            }
+    }
+    for (const [key, wrapper] of wrappers)
+        if (repeated.has(key) &&
+            (wrapper.reconstruction.kind !== 'object-envelope' || wrapper.slot.$cardinality.min === 0))
+            wrappers.delete(key);
+    // A recursive chain of envelopes describes actual nesting, so it needs an instance boundary.
+    for (const key of [...wrappers.keys()]) {
+        const visited = new Set();
+        let current = key;
+        while (wrappers.has(current)) {
+            if (visited.has(current)) {
+                for (const member of visited)
+                    wrappers.delete(member);
+                break;
+            }
+            visited.add(current);
+            current = wrappers.get(current).childKey;
+        }
+    }
+    const compactSlot = (slot) => {
+        if (slot.$allowedComponents?.length !== 1 || !slot.$cardinality)
+            return;
+        let key = slot.$allowedComponents[0];
+        let cardinality = cloneJson(slot.$cardinality);
+        while (wrappers.has(key)) {
+            const wrapper = wrappers.get(key);
+            const child = wrapper.slot.$cardinality;
+            if (wrapper.reconstruction.kind === 'ordered-array')
+                cardinality = { min: child.min, max: child.max, ordered: true };
+            else if (!cardinality.ordered)
+                cardinality = { ...cardinality, min: cardinality.min === 0 || child.min === 0 ? 0 : cardinality.min };
+            key = wrapper.childKey;
+        }
+        slot.$allowedComponents = [key];
+        slot.$cardinality = cardinality;
+        slot.$required = cardinality.min > 0;
+    };
+    compactSlot(attachment);
+    for (const model of models.values())
+        if (!wrappers.has(model.key))
+            for (const slot of Object.values(model.entry.$slots ?? {}))
+                compactSlot(slot);
+    for (const [key, wrapper] of wrappers) {
+        const model = models.get(key);
+        const mapping = mappings.get(model.nodeId);
+        delete mapping.componentKey;
+        delete mapping.slot;
+        mapping.disposition = 'reconstruction';
+        mapping.reconstruction = cloneJson(wrapper.reconstruction);
+        if (wrapper.reconstruction.kind === 'optional-value')
+            for (const id of nodes.get(model.nodeId).alternatives ?? []) {
+                const node = nodes.get(id);
+                if (!['null', 'undefined', 'never'].includes(node.kind))
+                    continue;
+                const empty = mappings.get(id);
+                delete empty.componentKey;
+                delete empty.slot;
+                empty.disposition = 'reconstruction';
+                empty.reconstruction = { kind: 'empty-value', state: node.kind };
+            }
+        models.delete(key);
+    }
+}

package/dist/src/property-contract/content-digest.d.ts

@@ -0,0 +1,2 @@
+/** Stable SHA-256 identity for plain source/plan data in Node and browser runtimes. */
+export declare function contentDigest(value: unknown): string;

package/dist/src/property-contract/content-digest.js

@@ -0,0 +1,69 @@
+import { jsonValueIssue } from './json-value.js';
+/** Stable SHA-256 identity for plain source/plan data in Node and browser runtimes. */
+export function contentDigest(value) {
+    const issue = jsonValueIssue(value);
+    if (issue)
+        throw new Error(issue.message);
+    const canonical = (input) => {
+        if (Array.isArray(input))
+            return '[' + input.map(canonical).join(',') + ']';
+        if (input && typeof input === 'object')
+            return ('{' +
+                Object.keys(input)
+                    .sort()
+                    .map((key) => JSON.stringify(key) + ':' + canonical(input[key]))
+                    .join(',') +
+                '}');
+        return JSON.stringify(input);
+    };
+    const bytes = new TextEncoder().encode(canonical(value));
+    const padded = new Uint8Array(Math.ceil((bytes.length + 9) / 64) * 64);
+    padded.set(bytes);
+    padded[bytes.length] = 128;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bytes.length / 0x20000000));
+    view.setUint32(padded.length - 4, bytes.length * 8);
+    const primes = [];
+    for (let candidate = 2; primes.length < 64; candidate++)
+        if (!primes.some((prime) => prime * prime <= candidate && candidate % prime === 0))
+            primes.push(candidate);
+    const initial = primes.slice(0, 8).map((prime) => ((Math.sqrt(prime) % 1) * 0x100000000) >>> 0);
+    const constants = primes.map((prime) => ((Math.cbrt(prime) % 1) * 0x100000000) >>> 0);
+    const rotate = (word, bits) => (word >>> bits) | (word << (32 - bits));
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        const words = new Uint32Array(64);
+        for (let i = 0; i < 16; i++)
+            words[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const x = words[i - 15], y = words[i - 2];
+            words[i] =
+                (words[i - 16] +
+                    (rotate(x, 7) ^ rotate(x, 18) ^ (x >>> 3)) +
+                    words[i - 7] +
+                    (rotate(y, 17) ^ rotate(y, 19) ^ (y >>> 10))) >>>
+                    0;
+        }
+        let [a, b, c, d, e, f, g, h] = initial;
+        for (let i = 0; i < 64; i++) {
+            const first = (h +
+                (rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25)) +
+                ((e & f) ^ (~e & g)) +
+                constants[i] +
+                words[i]) >>>
+                0;
+            const second = ((rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + first) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (first + second) >>> 0;
+        }
+        [a, b, c, d, e, f, g, h].forEach((word, i) => {
+            initial[i] = (initial[i] + word) >>> 0;
+        });
+    }
+    return initial.map((word) => word.toString(16).padStart(8, '0')).join('');
+}

package/dist/src/property-contract/decision-protocol.d.ts

@@ -0,0 +1,45 @@
+import { type ClassifiedPropertyCall } from './classification.js';
+export interface ComponentClassificationCall {
+    tool: 'classify_component';
+    description?: string;
+    rationale?: {
+        description?: string;
+        props?: string;
+        slots?: string;
+    };
+}
+export interface SlotClassificationCall {
+    tool: 'classify_slot';
+    slot: string;
+    required?: boolean;
+    allowed_components?: string[];
+    description?: string;
+    rationale?: string;
+}
+export interface PropertyExclusionCall {
+    tool: 'exclude_prop';
+    prop: string;
+    reason: string;
+}
+export type ClassificationToolCall = ClassifiedPropertyCall | ComponentClassificationCall | SlotClassificationCall | PropertyExclusionCall;
+export interface NormalizedClassificationCalls {
+    calls: ClassificationToolCall[];
+    warnings: string[];
+}
+/** Wire and direct calls use the same descriptor-checked normalization. */
+export declare function normalizeClassificationCalls(values: readonly unknown[]): NormalizedClassificationCalls;
+export declare function parseClassificationToolLines(stdout: string): NormalizedClassificationCalls;
+export interface DecisionInventory {
+    properties: readonly string[];
+    slots: readonly {
+        name: string;
+        sourceInput?: string;
+    }[];
+}
+export interface DecisionAccounting {
+    complete: boolean;
+    accepted: ClassificationToolCall[];
+    missing: string[];
+    issues: string[];
+}
+export declare function accountClassificationCalls(inventory: DecisionInventory, calls: readonly ClassificationToolCall[]): DecisionAccounting;

package/dist/src/property-contract/decision-protocol.js

@@ -0,0 +1,251 @@
+import { CDF_PROPERTY_TYPES } from '../cdf/vocabularies.js';
+import { parseClassificationMetadata, parseClassificationDefaultMetadata, } from './classification.js';
+import { cloneJson, jsonValueIssue, parseStrictJson, own } from './json-value.js';
+import { validateProposalDraft } from './representation-proposal.js';
+import { isSourceBoundRepresentation } from './source-representation.js';
+import { validateNullHandling } from './null-handling.js';
+const fields = {
+    classify_component: ['description', 'rationale'],
+    classify_slot: ['slot', 'required', 'allowed_components', 'description', 'rationale'],
+    exclude_prop: ['prop', 'reason'],
+    classify_prop: [
+        'prop',
+        'cdf_type',
+        'cdf_category',
+        'values',
+        'token_kind',
+        'required',
+        'description',
+        'default',
+        'default_intent',
+        'items',
+        'fields',
+        'source_revision',
+        'source_node_id',
+        'reason',
+        'value',
+        'valueType',
+        'discriminator',
+        'members',
+        'allowedResources',
+        'representation_proposal',
+        'representation_selection',
+        'null_handling',
+    ],
+};
+/** Wire and direct calls use the same descriptor-checked normalization. */
+export function normalizeClassificationCalls(values) {
+    const outerIssue = jsonValueIssue(values);
+    if (outerIssue)
+        return { calls: [], warnings: [`${outerIssue.path}: ${outerIssue.message}`] };
+    const calls = [];
+    const warnings = [];
+    for (const [index, value] of values.entries()) {
+        let subject = '';
+        try {
+            const unsafe = jsonValueIssue(value);
+            if (unsafe)
+                throw new Error(`${unsafe.path}: ${unsafe.message}`);
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                throw new Error('Expected tool object');
+            const rec = value;
+            if (typeof rec.tool !== 'string' || !own(fields, rec.tool))
+                throw new Error('Unknown tool');
+            const tool = rec.tool;
+            if ((tool === 'classify_prop' || tool === 'exclude_prop') && typeof rec.prop === 'string')
+                subject = ` property:${rec.prop}:`;
+            else if (tool === 'classify_slot' && typeof rec.slot === 'string')
+                subject = ` slot:${rec.slot}:`;
+            const allowed = fields[tool];
+            if (Object.keys(rec).some((key) => key !== 'tool' && !allowed.includes(key)))
+                throw new Error('Unknown decision field');
+            for (const key of ['prop', 'slot', 'description', 'reason', 'token_kind', 'source_revision', 'source_node_id'])
+                if (own(rec, key) && typeof rec[key] !== 'string')
+                    throw new Error(`${key} must be a string`);
+            if (own(rec, 'required') && typeof rec.required !== 'boolean')
+                throw new Error('required must be Boolean');
+            if (tool === 'classify_prop' || tool === 'exclude_prop')
+                if (typeof rec.prop !== 'string' || !rec.prop)
+                    throw new Error('Missing exact property name');
+            if (tool === 'exclude_prop' && (typeof rec.reason !== 'string' || !rec.reason.trim()))
+                throw new Error('Exclusion requires nonblank reason');
+            if (tool === 'classify_slot') {
+                if (typeof rec.slot !== 'string' || !rec.slot)
+                    throw new Error('Missing exact slot name');
+                if (own(rec, 'rationale') && typeof rec.rationale !== 'string')
+                    throw new Error('rationale must be a string');
+                if (own(rec, 'allowed_components') &&
+                    (!Array.isArray(rec.allowed_components) ||
+                        !rec.allowed_components.every((entry) => typeof entry === 'string') ||
+                        new Set(rec.allowed_components).size !== rec.allowed_components.length))
+                    throw new Error('Invalid allowed components');
+            }
+            if (tool === 'classify_component' && own(rec, 'rationale')) {
+                const rationale = rec.rationale;
+                if (!rationale ||
+                    typeof rationale !== 'object' ||
+                    Array.isArray(rationale) ||
+                    Object.entries(rationale).some(([key, entry]) => !['description', 'props', 'slots'].includes(key) || typeof entry !== 'string'))
+                    throw new Error('Invalid component rationale');
+            }
+            const call = cloneJson(rec);
+            if (call.tool === 'classify_prop') {
+                if (!['content', 'design', 'state'].includes(call.cdf_category))
+                    throw new Error('Invalid semantic category');
+                if (own(rec, 'null_handling')) {
+                    const issues = validateNullHandling(rec.null_handling);
+                    if (issues.length)
+                        throw new Error(issues.map((issue) => `${issue.path}: ${issue.message}`).join('; '));
+                    if (!call.source_revision?.trim() || !call.source_node_id?.trim())
+                        throw new Error('Null handling requires the current source revision and property root node');
+                }
+                if (own(rec, 'representation_selection')) {
+                    const selection = call.representation_selection;
+                    if (!selection ||
+                        typeof selection !== 'object' ||
+                        Array.isArray(selection) ||
+                        selection.strategy !== 'component-model' ||
+                        typeof selection.candidateId !== 'string' ||
+                        !selection.candidateId.trim() ||
+                        Object.keys(selection).some((key) => !['strategy', 'candidateId'].includes(key)))
+                        throw new Error('Invalid model representation selection');
+                    if (!call.source_revision?.trim() || !call.source_node_id?.trim())
+                        throw new Error('Model selection requires the current source revision and property root node');
+                    if (!call.reason?.trim())
+                        throw new Error('Model selection requires a source-grounded reason');
+                    if ([
+                        'cdf_type',
+                        'values',
+                        'token_kind',
+                        'items',
+                        'fields',
+                        'value',
+                        'valueType',
+                        'discriminator',
+                        'members',
+                        'allowedResources',
+                        'representation_proposal',
+                    ].some((key) => own(rec, key)))
+                        throw new Error('Model selection cannot also select a native property definition');
+                    const issues = parseClassificationDefaultMetadata(rec, call);
+                    if (issues.length)
+                        throw new Error(issues.join('; '));
+                }
+                else if (own(rec, 'cdf_type')) {
+                    if (typeof rec.cdf_type !== 'string' || !CDF_PROPERTY_TYPES.includes(rec.cdf_type))
+                        throw new Error('Invalid representation type');
+                    if (own(rec, 'token_kind') && rec.cdf_type !== 'token')
+                        throw new Error('Token kind requires token representation');
+                    if (own(rec, 'values') && rec.cdf_type === 'token')
+                        throw new Error('Token options require a token mapping decision');
+                    const issues = parseClassificationMetadata(rec, call);
+                    if (issues.length)
+                        throw new Error(issues.join('; '));
+                    if (own(rec, 'representation_proposal')) {
+                        const issues = validateProposalDraft(call.representation_proposal);
+                        if (issues.length)
+                            throw new Error(`property:${call.prop}: ` +
+                                issues.map((issue) => `/representation_proposal${issue.path}: ${issue.message}`).join('; '));
+                        if (!call.representation_proposal ||
+                            call.representation_proposal.desiredType !== call.cdf_type ||
+                            call.cdf_category !== 'content' ||
+                            call.representation_proposal.key !== call.prop ||
+                            call.representation_proposal.name !== call.prop)
+                            throw new Error('Representation proposal and property decision disagree');
+                    }
+                    if (isSourceBoundRepresentation(call.cdf_type) && !call.representation_proposal)
+                        throw new Error('Source-bound representation requires a complete proposal');
+                }
+                else {
+                    if (typeof call.reason !== 'string' || !call.reason.trim())
+                        throw new Error('Absent representation requires nonblank reason');
+                    const companions = [
+                        'values',
+                        'token_kind',
+                        'default',
+                        'default_intent',
+                        'items',
+                        'fields',
+                        'required',
+                        'value',
+                        'valueType',
+                        'discriminator',
+                        'members',
+                        'allowedResources',
+                        'representation_proposal',
+                        'null_handling',
+                    ].filter((key) => own(rec, key));
+                    if (companions.length)
+                        throw new Error(`Representation companions require a representation: ${companions.join(', ')} require cdf_type or representation_selection; omit these fields while unresolved`);
+                }
+            }
+            calls.push(call);
+        }
+        catch (error) {
+            warnings.push(`decision ${index + 1}:${subject} ${error instanceof Error ? error.message : 'Invalid decision'}`);
+        }
+    }
+    const keys = calls.map((call) => call.tool === 'classify_component'
+        ? 'component'
+        : call.tool === 'classify_slot'
+            ? `slot:${call.slot}`
+            : `property:${call.prop}`);
+    const duplicates = new Set(keys.filter((key, index) => keys.indexOf(key) !== index));
+    for (const key of duplicates)
+        warnings.push(`Duplicate or conflicting subject ${key}`);
+    return { calls: calls.filter((_, index) => !duplicates.has(keys[index])), warnings };
+}
+export function parseClassificationToolLines(stdout) {
+    const values = [];
+    const warnings = [];
+    for (const [index, raw] of stdout.split('\n').entries()) {
+        const line = raw.trim();
+        if (!line.startsWith('{'))
+            continue;
+        try {
+            values.push(parseStrictJson(line));
+        }
+        catch {
+            warnings.push(`line ${index + 1}: malformed JSON or trailing content`);
+        }
+    }
+    const normalized = normalizeClassificationCalls(values);
+    return { calls: normalized.calls, warnings: [...warnings, ...normalized.warnings] };
+}
+export function accountClassificationCalls(inventory, calls) {
+    const issues = [];
+    const subjects = [
+        'component',
+        ...inventory.properties.map((key) => `property:${key}`),
+        ...inventory.slots.map((slot) => `slot:${slot.name}`),
+    ];
+    if (new Set(subjects).size !== subjects.length)
+        issues.push('Duplicate retained source subject');
+    const owners = inventory.slots.flatMap((slot) => (slot.sourceInput === undefined ? [] : [slot.sourceInput]));
+    if (new Set(owners).size !== owners.length)
+        issues.push('Competing accepted slot owners');
+    if (owners.some((key) => inventory.properties.includes(key)))
+        issues.push('Property and slot compete for source owner');
+    const grouped = new Map();
+    for (const call of calls) {
+        const key = call.tool === 'classify_component'
+            ? 'component'
+            : call.tool === 'classify_slot'
+                ? `slot:${call.slot}`
+                : `property:${call.prop}`;
+        const entries = grouped.get(key) ?? [];
+        entries.push(call);
+        grouped.set(key, entries);
+    }
+    const accepted = [];
+    for (const [key, entries] of grouped) {
+        if (!subjects.includes(key))
+            issues.push(`Unknown subject ${key}`);
+        else if (entries.length !== 1)
+            issues.push(`Duplicate or conflicting subject ${key}`);
+        else
+            accepted.push(entries[0]);
+    }
+    const missing = subjects.filter((key) => grouped.get(key)?.length !== 1);
+    return { complete: !issues.length && !missing.length, accepted, missing, issues };
+}

package/dist/src/property-contract/definition-import-rules.d.ts

@@ -0,0 +1,10 @@
+import { type CDFComponentEntry, type CDFSlotDefinition } from '../cdf/types.js';
+export * from './physical-property-import.js';
+import { type PropertyIssue } from './json-value.js';
+import { type ModelBinding, type RepresentationPlan } from './representation-plan.js';
+/** Importing a definition does not establish delivery or rendering readiness. */
+export declare function definitionImportCapabilityStatus(capability: string): 'supported' | 'deferred' | 'unavailable';
+export declare function slotDefinitionImportIssues(slot: CDFSlotDefinition, modelOwner?: ModelBinding): string[];
+export declare function representationDefinitionImportIssues(plan: RepresentationPlan): string[];
+/** Check source ownership and physical import constraints before mapping. */
+export declare function componentDefinitionImportIssues(component: CDFComponentEntry): PropertyIssue[];

package/dist/src/property-contract/definition-import-rules.js

@@ -0,0 +1,105 @@
+import { CDFComponentSchema } from '../cdf/types.js';
+import { propertyDefinitionImportIssues } from './physical-property-import.js';
+export * from './physical-property-import.js';
+import { childPath, jsonEqual } from './json-value.js';
+import { validateRepresentationPlan } from './representation-plan.js';
+const DEFINITION_CAPABILITIES = new Set([
+    'deployed-mapper',
+    'component-model-mapper',
+    'singleton-slot-cardinality',
+    'ordered-slot-cardinality',
+    'cyclic-model-dependencies',
+]);
+const DEFERRED_RUNTIME_CAPABILITIES = new Set([
+    'source-reconstruction',
+    'source-default-evaluation',
+    'source-structural-default-materialization',
+    'empty-source-value-materialization',
+    'presence-null-state',
+    'exclusive-union-branch-selection',
+    'intrinsic-field-reconstruction',
+    'index-key-preservation:string',
+    'index-key-preservation:number',
+]);
+/** Importing a definition does not establish delivery or rendering readiness. */
+export function definitionImportCapabilityStatus(capability) {
+    if (DEFINITION_CAPABILITIES.has(capability))
+        return 'supported';
+    return DEFERRED_RUNTIME_CAPABILITIES.has(capability) ? 'deferred' : 'unavailable';
+}
+export function slotDefinitionImportIssues(slot, modelOwner) {
+    const cardinality = slot.$cardinality;
+    if (!cardinality)
+        return [];
+    const binding = slot.$modelBinding;
+    const ownedModelSlot = modelOwner !== undefined &&
+        binding !== undefined &&
+        binding.planId === modelOwner.planId &&
+        binding.componentId === modelOwner.componentId &&
+        binding.propertyId === modelOwner.propertyId;
+    // A source-owned model uses one typed slot per position; its family is checked separately.
+    if ((cardinality.tuplePosition !== undefined || cardinality.rest !== undefined) && !ownedModelSlot)
+        return ['Slot cardinality mapping is not available for positional model semantics'];
+    if (cardinality.max === 0)
+        return ['Slot cardinality mapping is not available for empty-only slots'];
+    if (!Number.isSafeInteger(cardinality.min) || (cardinality.max !== null && !Number.isSafeInteger(cardinality.max)))
+        return ['Slot cardinality bounds must be safe integers'];
+    return [];
+}
+export function representationDefinitionImportIssues(plan) {
+    if (!['native', 'component-model'].includes(plan.kind) || !plan.sdkValid || !Array.isArray(plan.requirements))
+        return ['Representation mapping prerequisites are not available'];
+    const issues = plan.requirements.flatMap((requirement) => {
+        const allowed = plan.kind === 'native'
+            ? requirement.capability === 'deployed-mapper'
+            : definitionImportCapabilityStatus(requirement.capability) !== 'unavailable';
+        return allowed ? [] : [`Required capability ${requirement.capability} remains unverified at ${requirement.path}`];
+    });
+    if (plan.kind === 'native' && plan.nativeDefinition)
+        issues.push(...propertyDefinitionImportIssues(plan.nativeDefinition).map(({ path, message }) => `${path}: ${message}`));
+    for (const model of plan.models)
+        issues.push(...componentDefinitionImportIssues(model.entry).map(({ path, message }) => `${model.key}${path}: ${message}`));
+    return issues;
+}
+/** Check source ownership and physical import constraints before mapping. */
+export function componentDefinitionImportIssues(component) {
+    const issues = [];
+    if (component.$model &&
+        !CDFComponentSchema.safeParse(Object.fromEntries(Object.entries(component).filter(([key]) => key !== 'key')))
+            .success)
+        issues.push({ path: '/$model', message: 'Invalid model component source binding' });
+    for (const [id, slot] of Object.entries(component.$slots ?? {})) {
+        if (!id.trim() || !(id.split('.').at(-1) ?? id).split(/[-_]/g).filter(Boolean).join(' ').length)
+            issues.push({ path: childPath('/$slots', id), message: 'Slot id must produce a non-empty display name' });
+        for (const message of slotDefinitionImportIssues(slot, component.$model))
+            issues.push({ path: childPath('/$slots', id) + '/$cardinality', message });
+    }
+    for (const [id, definition] of Object.entries(component.$properties))
+        for (const issue of propertyDefinitionImportIssues(definition))
+            issues.push({ path: childPath('/$properties', id) + issue.path, message: issue.message });
+    for (const [id, plan] of Object.entries(component.$representationPlans ?? {})) {
+        const path = childPath('/$representationPlans', id);
+        const prerequisites = representationDefinitionImportIssues(plan);
+        if (prerequisites.length) {
+            issues.push(...prerequisites.map((message) => ({ path, message })));
+            continue;
+        }
+        try {
+            issues.push(...validateRepresentationPlan(plan, plan.sourceModel, plan.contextSnapshot).map(({ message }) => ({
+                path,
+                message,
+            })));
+            if (plan.identity.key !== id ||
+                (plan.kind === 'native'
+                    ? !Object.hasOwn(component.$properties, id) || !jsonEqual(plan.nativeDefinition, component.$properties[id])
+                    : !plan.attachment ||
+                        Object.hasOwn(component.$properties, id) ||
+                        !jsonEqual(component.$slots?.[plan.attachment.slot], plan.attachment.definition)))
+                issues.push({ path, message: 'Representation does not match its physical definition' });
+        }
+        catch {
+            issues.push({ path, message: 'Invalid representation plan' });
+        }
+    }
+    return issues;
+}

package/dist/src/property-contract/definition-import.d.ts

@@ -0,0 +1,13 @@
+import type { CDFComponentEntry } from '../cdf/types.js';
+import { type PropertyIssue } from './json-value.js';
+export * from './definition-import-rules.js';
+/** Model slots require an exact plan owner even on an otherwise ordinary component. */
+export declare function componentModelFamilyIssues(components: readonly {
+    key: string;
+    entry: CDFComponentEntry;
+}[]): PropertyIssue[];
+/** Data-model relationships do not instantiate a composition tree. Keep ordinary edges intact. */
+export declare function componentCompositionDefinitions<T extends {
+    key: string;
+    entry: CDFComponentEntry;
+}>(components: readonly T[]): T[];