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

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

@@ -0,0 +1,52 @@
+import { CDF_SCHEMA_URL } from '../cdf/schema.js';
+import { validateCDF } from '../cdf/validate.js';
+import { childPath, jsonEqual } from './json-value.js';
+import { componentDefinitionImportIssues } from './definition-import-rules.js';
+export * from './definition-import-rules.js';
+/** Model slots require an exact plan owner even on an otherwise ordinary component. */
+export function componentModelFamilyIssues(components) {
+    if (!components.some(({ entry }) => entry.$model ||
+        entry.$representationPlans ||
+        Object.values(entry.$slots ?? {}).some((slot) => slot.$modelBinding)))
+        return [];
+    if (new Set(components.map(({ key }) => key)).size !== components.length)
+        return [{ path: '/', message: 'Duplicate complete component identity' }];
+    const validation = validateCDF({
+        $schema: CDF_SCHEMA_URL,
+        ...Object.fromEntries(components.map(({ key, entry }) => [key, entry])),
+    });
+    if (!validation.valid)
+        return validation.errors.map(({ path, message }) => ({ path, message }));
+    const expectedSlots = new Map();
+    for (const { key, entry } of components)
+        for (const plan of Object.values(entry.$representationPlans ?? {})) {
+            if (plan.attachment)
+                expectedSlots.set(JSON.stringify([key, plan.attachment.slot]), plan.attachment.definition);
+            for (const generated of plan.models)
+                for (const [name, slot] of Object.entries(generated.entry.$slots ?? {}))
+                    expectedSlots.set(JSON.stringify([generated.key, name]), slot);
+        }
+    const issues = [];
+    for (const { key, entry } of components)
+        for (const [name, slot] of Object.entries(entry.$slots ?? {}))
+            if (slot.$modelBinding && !jsonEqual(slot, expectedSlots.get(JSON.stringify([key, name]))))
+                issues.push({
+                    path: childPath(childPath('', key) + '/$slots', name),
+                    message: 'Model slot has no exact source-plan owner',
+                });
+    return issues;
+}
+/** Data-model relationships do not instantiate a composition tree. Keep ordinary edges intact. */
+export function componentCompositionDefinitions(components) {
+    if (!components.some(({ entry }) => Object.values(entry.$slots ?? {}).some((slot) => slot.$modelBinding)) ||
+        componentModelFamilyIssues(components).length ||
+        components.some(({ entry }) => componentDefinitionImportIssues(entry).length))
+        return [...components];
+    return components.map((component) => ({
+        ...component,
+        entry: {
+            ...component.entry,
+            $slots: Object.fromEntries(Object.entries(component.entry.$slots ?? {}).filter(([, slot]) => !slot.$modelBinding)),
+        },
+    }));
+}

package/dist/src/property-contract/discriminated-union-source.d.ts

@@ -0,0 +1,17 @@
+import { type TargetDefinition } from './target-definition.js';
+import { type PropertyIssue } from './json-value.js';
+import { type PropertySourceGraph, type SourceGraphNode } from './property-model.js';
+export interface SourceUnionBranch {
+    memberIndex: number;
+    nodeId: string;
+    tagNodeId: string;
+    tag: string | number | boolean;
+}
+export interface SourceDiscriminatedUnion {
+    discriminator: string;
+    branches: SourceUnionBranch[];
+}
+/** Complete compiler field edges establish tags independently of observed callers. */
+export declare function sourceDiscriminatedUnion(node: SourceGraphNode, nodes: ReadonlyMap<string, SourceGraphNode>, discriminator?: string): SourceDiscriminatedUnion | undefined;
+/** Match each target branch to the original compiler member through its exact typed tag. */
+export declare function validateDiscriminatedUnionSourceDefinition(definition: TargetDefinition, graph: PropertySourceGraph, nodeId?: string): PropertyIssue[];

package/dist/src/property-contract/discriminated-union-source.js

@@ -0,0 +1,180 @@
+import { discriminatedUnionTag } from './discriminated-union.js';
+import { validateTargetDefinition } from './target-definition.js';
+import { childPath, jsonEqual, own } from './json-value.js';
+import { validateSourceGraph, validateSourceValue, } from './property-model.js';
+import { finiteSourceValueDomain } from './source-representation.js';
+function referenceValue(node, nodes) {
+    const active = new Set();
+    let current = node;
+    while (current?.kind === 'reference') {
+        if (active.has(current.id) || current.alternatives?.length !== 1)
+            return;
+        active.add(current.id);
+        current = nodes.get(current.alternatives[0]);
+    }
+    return current;
+}
+/** Complete compiler field edges establish tags independently of observed callers. */
+export function sourceDiscriminatedUnion(node, nodes, discriminator) {
+    if (node.kind !== 'union' || node.coverage !== 'complete-within-declared-bound')
+        return;
+    const members = (node.alternatives ?? []).map((id, memberIndex) => ({ node: nodes.get(id), memberIndex }));
+    if (members.length < 2)
+        return;
+    if (members.some((member) => !member.node || ['null', 'undefined', 'never'].includes(member.node.kind)))
+        return;
+    const first = referenceValue(members[0].node, nodes);
+    if (!first)
+        return;
+    const keys = discriminator === undefined ? (first.fields ?? []).map((field) => field.key).sort() : [discriminator];
+    for (const key of keys) {
+        const branches = [];
+        const tags = [];
+        for (const member of members) {
+            const branch = referenceValue(member.node, nodes);
+            if (!branch)
+                break;
+            const field = branch.fields?.find((edge) => edge.key === key);
+            const originalTag = field && nodes.get(field.nodeId);
+            const tag = originalTag && referenceValue(originalTag, nodes);
+            const value = tag?.domain.declaredValues[0];
+            if (!['record', 'intersection'].includes(branch.kind) ||
+                branch.coverage !== 'complete-within-declared-bound' ||
+                !field?.required ||
+                !tag ||
+                tag.domain.provenance !== 'compiler' ||
+                tag.coverage !== 'complete-within-declared-bound' ||
+                tag.kind !== typeof value ||
+                tag.domain.openness !== 'closed' ||
+                tag.domain.unrepresentedValues?.length ||
+                tag.domain.declaredValues.length !== 1 ||
+                !(typeof value === 'string' ||
+                    typeof value === 'boolean' ||
+                    (typeof value === 'number' && Number.isFinite(value))) ||
+                tags.some((other) => jsonEqual(other, value)))
+                break;
+            tags.push(value);
+            branches.push({ memberIndex: member.memberIndex, nodeId: member.node.id, tagNodeId: field.nodeId, tag: value });
+        }
+        if (branches.length === members.length)
+            return { discriminator: key, branches };
+    }
+    return;
+}
+/** Match each target branch to the original compiler member through its exact typed tag. */
+export function validateDiscriminatedUnionSourceDefinition(definition, graph, nodeId = graph.rootId) {
+    const validation = validateTargetDefinition(definition);
+    const issues = [...validation.issues, ...validateSourceGraph(graph)];
+    if (issues.length)
+        return issues;
+    if (graph.coverage !== 'complete-within-declared-bound' || graph.omittedCount)
+        return [{ path: '/source', message: 'Union requires a complete original compiler graph' }];
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const match = (desired, id, path, active, required) => {
+        const node = nodes.get(id);
+        const fail = (message) => {
+            issues.push({ path, message });
+        };
+        if (!node || active.has(id)) {
+            fail('Union source relationship is missing or recursive');
+            return;
+        }
+        if (node.coverage !== 'complete-within-declared-bound' ||
+            node.nullability?.compilerMode !== 'enabled' ||
+            node.nullability.null.state !== 'absent' ||
+            node.nullability.undefined.state !== 'absent' ||
+            node.domain.unrepresentedValues?.length) {
+            fail('Union requires established complete non-nullish compiler value states');
+            return;
+        }
+        const next = new Set(active).add(id);
+        const expectedRequired = required ?? node.required;
+        if (desired.required !== undefined && desired.required !== expectedRequired)
+            fail('Union field requiredness differs from its compiler occurrence');
+        if (desired.values?.length && !['String', 'Number', 'Boolean', 'Literal'].includes(desired.type))
+            fail('Union structure cannot add unproven whole-value constraints');
+        if (own(desired, 'defaultValue'))
+            issues.push(...validateSourceValue(graph, desired.defaultValue, childPath(path, 'defaultValue'), id));
+        if (node.kind === 'reference' && node.alternatives?.length === 1) {
+            match(desired, node.alternatives[0], path, next, expectedRequired);
+            return;
+        }
+        if (desired.type === 'DiscriminatedUnion') {
+            const binding = sourceDiscriminatedUnion(node, nodes, desired.discriminator);
+            if (!binding || binding.branches.length !== desired.members.length) {
+                fail('Union must retain the exact complete compiler discriminator and member set');
+                return;
+            }
+            const selected = new Set();
+            desired.members.forEach((member, index) => {
+                const tag = discriminatedUnionTag(member, desired.discriminator, 'target');
+                const branch = binding.branches.find((candidate) => jsonEqual(candidate.tag, tag.value));
+                if (!branch || selected.has(branch.memberIndex)) {
+                    fail('Union member requires one unique matching compiler tag');
+                    return;
+                }
+                selected.add(branch.memberIndex);
+                match(member, branch.nodeId, childPath(childPath(path, 'members'), index), next, expectedRequired);
+            });
+            return;
+        }
+        if (desired.type === 'Record') {
+            const fields = node.fields;
+            if (!['record', 'intersection'].includes(node.kind) ||
+                node.callSignatures?.length ||
+                node.indexSignatures?.length ||
+                !fields ||
+                fields.length !== Object.keys(desired.fields).length) {
+                fail('Union Record must retain every exact compiler field');
+                return;
+            }
+            for (const field of fields) {
+                const target = desired.fields[field.key];
+                if (!Object.hasOwn(desired.fields, field.key) || target.required !== field.required) {
+                    fail('Union field name and requiredness must match its compiler occurrence');
+                    continue;
+                }
+                match(target, field.nodeId, childPath(childPath(path, 'fields'), field.key), next, field.required);
+            }
+            return;
+        }
+        if (desired.type === 'Array') {
+            if (node.kind !== 'array' || node.items?.length !== 1)
+                fail('Union Array must retain its exact compiler item');
+            else
+                match(desired.items, node.items[0], childPath(path, 'items'), next);
+            return;
+        }
+        if (desired.type === 'Literal') {
+            const type = typeof desired.value;
+            if (node.domain.provenance !== 'compiler' ||
+                node.domain.openness !== 'closed' ||
+                node.domain.declaredValues.length !== 1 ||
+                !jsonEqual(node.domain.declaredValues[0], desired.value) ||
+                node.kind !== type ||
+                !['string', 'number', 'boolean'].includes(type) ||
+                (desired.valueType.type !==
+                    { string: 'String', number: 'Number', boolean: 'Boolean' }[type] &&
+                    !(type === 'number' && desired.valueType.type === 'Integer' && Number.isSafeInteger(desired.value))))
+                fail('Union Literal must retain its exact typed compiler singleton');
+            return;
+        }
+        const type = { String: 'string', Number: 'number', Boolean: 'boolean' }[desired.type];
+        const values = finiteSourceValueDomain(graph, id);
+        const intrinsicBoolean = type === 'boolean' && values?.length === 2 && values.includes(false) && values.includes(true);
+        const finitePrimitive = type && values?.length && values.every((value) => typeof value === type);
+        if (!type || (node.kind !== type && !finitePrimitive))
+            fail('Union branch must preserve its exact compiler type');
+        if (values?.length &&
+            !intrinsicBoolean &&
+            (!desired.values?.length ||
+                values.length !== desired.values.length ||
+                values.some((value) => !desired.values.some((allowed) => jsonEqual(allowed, value)))))
+            fail('Union branch must preserve its complete compiler domain');
+        if (desired.values?.length &&
+            (!values?.length || desired.values.some((allowed) => !values.some((value) => jsonEqual(allowed, value)))))
+            fail('Union branch cannot narrow an unproven or open compiler domain');
+    };
+    match(definition, nodeId, '', new Set());
+    return issues;
+}

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

@@ -0,0 +1,70 @@
+import { type CDFComponentEntry, type CDFTokenEntry } from '../cdf/types.js';
+import { type DesignTokenType } from '../dtcg/token-types.js';
+export type ResourceDependencyKey = {
+    kind: 'DesignToken';
+    namespace: 'dtcg-path';
+    value: string;
+} | {
+    kind: 'Component';
+    namespace: 'cdf-key';
+    value: string;
+};
+export interface ImportPrerequisiteManifest {
+    components: readonly {
+        key: string;
+        entry: CDFComponentEntry;
+    }[];
+    tokens: readonly {
+        path: string;
+        entry: CDFTokenEntry;
+    }[];
+}
+export interface ImportPrerequisiteEdge {
+    owner: ResourceDependencyKey;
+    dependency: ResourceDependencyKey;
+}
+export interface ImportPrerequisiteObligation {
+    owner: ResourceDependencyKey;
+    path: string;
+    reference: {
+        namespace: 'dtcg-path';
+        value: string;
+    };
+    expectedKind: DesignTokenType;
+    resolution: 'planned' | 'unknown';
+    definitionIdentity?: string;
+}
+export interface ImportPrerequisitePlan {
+    revision: 1;
+    manifestIdentity: string;
+    tokenManifestIdentity: string;
+    graphIdentity: string;
+    orderedKeys: string[];
+    edges: ImportPrerequisiteEdge[];
+    obligations: ImportPrerequisiteObligation[];
+    capabilityRequirements: Array<{
+        owner: ResourceDependencyKey;
+        path: string;
+        capability: string;
+    }>;
+}
+export interface ImportPrerequisiteIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+export type ImportPrerequisiteValidation = {
+    valid: true;
+    plan: Readonly<ImportPrerequisitePlan>;
+    errors: [];
+} | {
+    valid: false;
+    errors: ImportPrerequisiteIssue[];
+};
+export declare function importTokenDefinitionIdentity(path: string, entry: CDFTokenEntry): string;
+export declare function importTokenManifestIdentity(tokens: ImportPrerequisiteManifest['tokens']): string;
+export declare function importDependencyKey(key: ResourceDependencyKey): string;
+/** Local plans establish dependencies; absent target resources remain unknown. */
+export declare function createImportPrerequisitePlan(input: ImportPrerequisiteManifest): ImportPrerequisiteValidation;
+/** @alias Validation and planning use the same prerequisite checks. */
+export declare const validateImportPrerequisites: typeof createImportPrerequisitePlan;

package/dist/src/property-contract/import-prerequisites.js

@@ -0,0 +1,208 @@
+import { CDFComponentSchema, CDFTokenSchema, } from '../cdf/types.js';
+import { DESIGN_TOKEN_TYPES } from '../dtcg/token-types.js';
+import { contentDigest } from './content-digest.js';
+import { validateRepresentationClosure } from '../cdf/representation-validation.js';
+import { childPath, freezeJson, cloneJson, jsonValueIssue } from './json-value.js';
+import { componentDefinitionImportIssues } from './definition-import-rules.js';
+export function importTokenDefinitionIdentity(path, entry) {
+    return contentDigest({ path, entry });
+}
+export function importTokenManifestIdentity(tokens) {
+    return contentDigest([...tokens].sort((left, right) => left.path.localeCompare(right.path)));
+}
+export function importDependencyKey(key) {
+    return `${key.kind}:${JSON.stringify([key.namespace, key.value])}`;
+}
+/** Local plans establish dependencies; absent target resources remain unknown. */
+export function createImportPrerequisitePlan(input) {
+    const errors = [];
+    const components = new Map();
+    const tokens = new Map();
+    const edges = new Map();
+    const obligations = [];
+    const capabilityRequirements = [];
+    const nodes = new Set();
+    const issue = (code, path, message) => {
+        errors.push({ code, path, message });
+    };
+    const componentKey = (value) => ({ kind: 'Component', namespace: 'cdf-key', value });
+    const tokenKey = (value) => ({ kind: 'DesignToken', namespace: 'dtcg-path', value });
+    const addEdge = (owner, dependency) => {
+        edges.set(JSON.stringify([importDependencyKey(owner), importDependencyKey(dependency)]), { owner, dependency });
+    };
+    for (const [index, component] of input.components.entries()) {
+        if (!component.key || components.has(component.key)) {
+            issue('component-owner-duplicate', `/components/${index}/key`, 'Duplicate or empty Component key');
+            continue;
+        }
+        if (!CDFComponentSchema.safeParse(component.entry).success) {
+            issue('component-definition-invalid', `/components/${index}`, 'Invalid Component definition');
+            continue;
+        }
+        for (const finding of componentDefinitionImportIssues(component.entry))
+            issue('component-import-invalid', `/components/${index}${finding.path}`, finding.message);
+        components.set(component.key, component.entry);
+        nodes.add(importDependencyKey(componentKey(component.key)));
+    }
+    for (const [index, token] of input.tokens.entries()) {
+        if (!token.path || tokens.has(token.path)) {
+            issue('token-definition-duplicate', `/tokens/${index}/path`, 'Duplicate or empty DesignToken path');
+            continue;
+        }
+        if (jsonValueIssue(token.entry) || !CDFTokenSchema.safeParse(token.entry).success) {
+            issue('token-definition-invalid', `/tokens/${index}`, 'Invalid DesignToken definition');
+            continue;
+        }
+        tokens.set(token.path, token.entry);
+        nodes.add(importDependencyKey(tokenKey(token.path)));
+    }
+    if (errors.length)
+        return { valid: false, errors };
+    const visit = (owner, definition, path, category) => {
+        if (category === 'design' && definition.$type === 'token') {
+            const kind = definition['$token.kind'];
+            if (!DESIGN_TOKEN_TYPES.includes(kind)) {
+                issue('token-kind-invalid', `${path}/$token.kind`, 'Token properties require a recognized token kind');
+            }
+            else {
+                const references = (definition['$token.allowed'] ?? []).map((value, index) => ({
+                    value,
+                    path: `${path}/$token.allowed/${index}`,
+                }));
+                if (typeof definition.$default === 'string')
+                    references.push({ value: definition.$default, path: `${path}/$default` });
+                for (const reference of references) {
+                    if (!reference.value.trim()) {
+                        issue('token-reference-invalid', reference.path, 'Token reference must not be empty');
+                        continue;
+                    }
+                    const planned = tokens.get(reference.value);
+                    if (planned && planned.$type !== kind) {
+                        issue('token-kind-mismatch', reference.path, 'Planned token kind differs from the property kind');
+                        continue;
+                    }
+                    obligations.push({
+                        owner,
+                        path: reference.path,
+                        reference: { namespace: 'dtcg-path', value: reference.value },
+                        expectedKind: kind,
+                        resolution: planned ? 'planned' : 'unknown',
+                        ...(planned ? { definitionIdentity: importTokenDefinitionIdentity(reference.value, planned) } : {}),
+                    });
+                    if (planned)
+                        addEdge(owner, tokenKey(reference.value));
+                }
+            }
+        }
+        if (definition.$items)
+            visit(owner, definition.$items, `${path}/$items`, category);
+        if (definition.valueType)
+            visit(owner, definition.valueType, `${path}/valueType`, category);
+        for (const [index, member] of (definition.members ?? []).entries())
+            visit(owner, member, `${path}/members/${index}`, category);
+        for (const [key, field] of Object.entries(definition.$fields ?? {}))
+            visit(owner, field, childPath(`${path}/$fields`, key), category);
+    };
+    for (const [key, component] of components) {
+        const owner = componentKey(key);
+        for (const [name, definition] of Object.entries(component.$properties))
+            visit(owner, definition, childPath(`${childPath('', key)}/$properties`, name), definition.$category);
+        for (const [name, slot] of Object.entries(component.$slots ?? {})) {
+            for (const allowed of slot.$allowedComponents ?? []) {
+                if (components.has(allowed))
+                    addEdge(owner, componentKey(allowed));
+                else if (slot.$modelBinding)
+                    issue('prerequisite-node-missing', childPath(`${childPath('', key)}/$slots`, name), 'Generated model dependency is missing');
+            }
+        }
+        for (const [name, plan] of Object.entries(component.$representationPlans ?? {})) {
+            if (!Array.isArray(plan.requirements)) {
+                issue('import-model-invalid', childPath(`${childPath('', key)}/$representationPlans`, name), 'Representation requirements are missing');
+                continue;
+            }
+            for (const requirement of plan.requirements)
+                capabilityRequirements.push({ owner, path: requirement.path, capability: requirement.capability });
+            for (const allowed of plan.attachment?.definition.$allowedComponents ?? []) {
+                if (!components.has(allowed))
+                    issue('prerequisite-node-missing', childPath(`${childPath('', key)}/$representationPlans`, name), 'Representation model dependency is missing');
+                else
+                    addEdge(owner, componentKey(allowed));
+            }
+        }
+    }
+    const orderedEdges = [...edges.values()].sort((a, b) => importDependencyKey(a.owner).localeCompare(importDependencyKey(b.owner)) ||
+        importDependencyKey(a.dependency).localeCompare(importDependencyKey(b.dependency)));
+    const remaining = new Map([...nodes].map((node) => [node, new Set()]));
+    for (const edge of orderedEdges)
+        remaining.get(importDependencyKey(edge.owner)).add(importDependencyKey(edge.dependency));
+    const orderedKeys = [];
+    while (remaining.size) {
+        let ready = [...remaining]
+            .filter(([, dependencies]) => dependencies.size === 0)
+            .map(([key]) => key)
+            .sort();
+        if (!ready.length) {
+            const groups = new Map();
+            for (const [key, component] of components) {
+                if (!component.$model)
+                    continue;
+                const identity = component.$model;
+                const groupId = JSON.stringify([identity.planId, identity.componentId, identity.propertyId]);
+                const node = importDependencyKey(componentKey(key));
+                if (!remaining.has(node))
+                    continue;
+                const group = groups.get(groupId) ?? new Set();
+                group.add(node);
+                groups.set(groupId, group);
+            }
+            // Recursive definitions form a finite model group; instances remain ordinary finite trees.
+            // Such a group requires staged downstream creation rather than dependency-first creation.
+            const group = [...groups.values()].find((members) => [...members].every((node) => [...remaining.get(node)].every((dependency) => members.has(dependency))));
+            if (group && !validateRepresentationClosure(input.components.map((component) => ({ ...component }))).length)
+                ready = [...group].sort();
+        }
+        if (!ready.length) {
+            issue('prerequisite-cycle', '', 'Import prerequisite graph contains a cycle');
+            break;
+        }
+        for (const key of ready) {
+            orderedKeys.push(key);
+            remaining.delete(key);
+        }
+        for (const dependencies of remaining.values())
+            for (const key of ready)
+                dependencies.delete(key);
+    }
+    if (errors.length)
+        return { valid: false, errors };
+    const manifestIdentity = contentDigest({
+        components: [...input.components].sort((a, b) => a.key.localeCompare(b.key)),
+        tokens: [...input.tokens].sort((a, b) => a.path.localeCompare(b.path)),
+    });
+    obligations.sort((a, b) => a.path.localeCompare(b.path));
+    capabilityRequirements.sort((a, b) => importDependencyKey(a.owner).localeCompare(importDependencyKey(b.owner)) ||
+        a.path.localeCompare(b.path) ||
+        a.capability.localeCompare(b.capability));
+    return {
+        valid: true,
+        errors: [],
+        plan: freezeJson(cloneJson({
+            revision: 1,
+            manifestIdentity,
+            tokenManifestIdentity: importTokenManifestIdentity(input.tokens),
+            graphIdentity: contentDigest({
+                manifestIdentity,
+                orderedKeys,
+                edges: orderedEdges,
+                obligations,
+                capabilityRequirements,
+            }),
+            orderedKeys,
+            edges: orderedEdges,
+            obligations,
+            capabilityRequirements,
+        })),
+    };
+}
+/** @alias Validation and planning use the same prerequisite checks. */
+export const validateImportPrerequisites = createImportPrerequisitePlan;

package/dist/src/property-contract/index.d.ts

@@ -1,4 +1,21 @@
 export * from './json-value.js';
+export * from './target-definition.js';
 export * from './date-time-value.js';
+export * from './source-representation.js';
+export * from './mapper-readiness.js';
+export * from './definition-import.js';
+export * from './property-model.js';
+export * from './representation-proposal.js';
+export * from './classification.js';
+export * from './null-handling.js';
+export * from './decision-protocol.js';
+export * from './property-decision.js';
+export * from './representation-plan.js';
+export * from './model-exploration.js';
+export { contentDigest } from './content-digest.js';
+export * from './import-prerequisites.js';
+export * from './logical-source-graph.js';
+export * from './analysis-representation-candidates.js';
+export { nativeSourceRegion } from './native-source-region.js';
 export * from './discriminated-union.js';
-export * from './target-definition.js';
+export * from './discriminated-union-source.js';

package/dist/src/property-contract/index.js

@@ -1,9 +1,21 @@
-// Pillar #4 foundation — property-contract target types + validators.
-// Dormant on `development` until downstream consumers (new extractors,
-// generation, review UI) activate them. Shape is deliberately verbatim
-// with the upstream work on feat/import-pipeline-evidence-and-reasoning
-// so the two merge without drift. See INTEG-5147 (spike) / INTEG-4927.
 export * from './json-value.js';
+export * from './target-definition.js';
 export * from './date-time-value.js';
+export * from './source-representation.js';
+export * from './mapper-readiness.js';
+export * from './definition-import.js';
+export * from './property-model.js';
+export * from './representation-proposal.js';
+export * from './classification.js';
+export * from './null-handling.js';
+export * from './decision-protocol.js';
+export * from './property-decision.js';
+export * from './representation-plan.js';
+export * from './model-exploration.js';
+export { contentDigest } from './content-digest.js';
+export * from './import-prerequisites.js';
+export * from './logical-source-graph.js';
+export * from './analysis-representation-candidates.js';
+export { nativeSourceRegion } from './native-source-region.js';
 export * from './discriminated-union.js';
-export * from './target-definition.js';
+export * from './discriminated-union-source.js';

package/dist/src/property-contract/logical-source-graph.d.ts

@@ -0,0 +1,36 @@
+import { type DefaultIntent, type PropertyModel, type SourceGraphNode } from './property-model.js';
+export interface LogicalBranchCondition {
+    unionNodeId: string;
+    memberIndex: number;
+    sourceMemberNodeId: string;
+    discriminator: string;
+    tag: string | number | boolean;
+}
+export interface LogicalSourceNode extends SourceGraphNode {
+    sourceNodeId: string;
+    path: NonNullable<SourceGraphNode['path']>;
+    readonly: boolean;
+    occurrenceReadonly: boolean;
+    intrinsicReadonly: boolean;
+    defaultIntent?: DefaultIntent;
+    branchConditions?: LogicalBranchCondition[];
+    unionBranches?: {
+        discriminator: string;
+        branches: Array<{
+            memberIndex: number;
+            nodeId: string;
+            sourceNodeId: string;
+            tag: string | number | boolean;
+        }>;
+    };
+}
+export interface LogicalSourceGraph {
+    authority: 'compiler';
+    rootId: string;
+    nodes: LogicalSourceNode[];
+    coverage: PropertyModel['source']['graph']['coverage'];
+}
+/** Only own record fields identify a default; an array sample cannot establish item defaults. */
+export declare function sourceDefaultAtPath(model: Pick<PropertyModel, 'source'>, path: LogicalSourceNode['path']): DefaultIntent | undefined;
+/** Retain shared references while expanding finite occurrences with distinct branch ownership. */
+export declare function prepareLogicalSourceGraph(model: Pick<PropertyModel, 'identity' | 'source'>): LogicalSourceGraph;