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

package/dist/src/property-contract/logical-source-graph.js

@@ -0,0 +1,240 @@
+import { contentDigest } from './content-digest.js';
+import { cloneJson, own } from './json-value.js';
+import { sourceDiscriminatedUnion } from './discriminated-union-source.js';
+import { validateSourceGraph, validateSourceValue, } from './property-model.js';
+/** Only own record fields identify a default; an array sample cannot establish item defaults. */
+export function sourceDefaultAtPath(model, path) {
+    if (model.source.default?.state !== 'value' || !own(model.source.default, 'value'))
+        return;
+    let value = model.source.default.value;
+    const nodes = new Map(model.source.graph.nodes.map((node) => [node.id, node]));
+    let node = nodes.get(model.source.graph.rootId);
+    const resolve = () => {
+        const seen = new Set();
+        while (node?.kind === 'reference' && !seen.has(node.id)) {
+            seen.add(node.id);
+            node = nodes.get(node.alternatives?.[0] ?? '');
+        }
+    };
+    for (const segment of path) {
+        resolve();
+        if (segment.kind === 'union' || segment.kind === 'intersection') {
+            const memberId = typeof segment.key === 'number' ? node?.alternatives?.[segment.key] : undefined;
+            if (!memberId ||
+                (segment.kind === 'union' && validateSourceValue(model.source.graph, value, '', memberId).length))
+                return;
+            node = nodes.get(memberId);
+            continue;
+        }
+        if (segment.kind !== 'field' ||
+            typeof segment.key !== 'string' ||
+            !value ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            !own(value, segment.key))
+            return;
+        value = value[segment.key];
+        node = nodes.get(node?.fields?.find((field) => field.key === segment.key)?.nodeId ?? '');
+    }
+    return { action: 'set', value: cloneJson(value) };
+}
+/** Retain shared references while expanding finite occurrences with distinct branch ownership. */
+export function prepareLogicalSourceGraph(model) {
+    const source = model.source.graph;
+    const invalid = validateSourceGraph(source);
+    if (invalid.length)
+        throw new Error(invalid.map((issue) => issue.message).join('; '));
+    if (model.identity.nodeId !== source.rootId ||
+        Object.values(model.identity).some((value) => typeof value !== 'string' || !value))
+        throw new Error('Logical source root owner is incomplete or mismatched');
+    const byId = new Map(source.nodes.map((node) => [node.id, node]));
+    const parents = new Map();
+    for (const node of source.nodes)
+        for (const childId of [
+            ...(node.fields?.map((field) => field.nodeId) ?? []),
+            ...(node.items ?? []),
+            ...(node.alternatives ?? []),
+            ...(node.indexSignatures?.map((signature) => signature.valueNodeId) ?? []),
+        ])
+            parents.set(childId, [...(parents.get(childId) ?? []), node.id]);
+    const branchSensitive = new Set();
+    const pending = source.nodes.filter((node) => sourceDiscriminatedUnion(node, byId)).map((node) => node.id);
+    while (pending.length) {
+        const id = pending.pop();
+        if (branchSensitive.has(id))
+            continue;
+        branchSensitive.add(id);
+        pending.push(...(parents.get(id) ?? []));
+    }
+    const intrinsicReadonly = (id) => {
+        const seen = new Set();
+        let current = byId.get(id);
+        while (current && !seen.has(current.id)) {
+            seen.add(current.id);
+            if (current.readonly === true)
+                return true;
+            if (current.kind === 'reference' && current.alternatives?.length === 1) {
+                current = byId.get(current.alternatives[0]);
+            }
+            else if (current.kind === 'union') {
+                const values = (current.alternatives ?? [])
+                    .map((child) => byId.get(child))
+                    .filter((child) => !['null', 'undefined', 'never'].includes(child.kind));
+                if (values.length !== 1)
+                    return false;
+                current = values[0];
+            }
+            else
+                return false;
+        }
+        return false;
+    };
+    const nodes = [];
+    const canonical = new Map();
+    const activeSources = new Set();
+    let expandedOccurrences = 0;
+    let occurrenceBoundReached = false;
+    const root = byId.get(source.rootId);
+    const rootPath = root.path ?? root.keyPath.map((key) => ({ kind: 'field', key }));
+    const visit = function* (request) {
+        const original = byId.get(request.sourceId);
+        const known = canonical.get(original.id);
+        const sharedReference = known &&
+            ((!request.branchConditions?.length && !branchSensitive.has(original.id)) || activeSources.has(original.id));
+        if (sharedReference && request.target)
+            return known;
+        const boundedOccurrence = known && !sharedReference && expandedOccurrences >= (source.limits.maxEdges ?? 4096);
+        const id = known
+            ? 'occurrence_' +
+                contentDigest({ owner: model.identity, sourceNodeId: original.id, path: request.path }).slice(0, 32)
+            : original.id;
+        const node = {
+            ...cloneJson(original),
+            id,
+            sourceNodeId: original.id,
+            path: cloneJson(request.path),
+            required: request.required,
+            readonly: request.readonly || intrinsicReadonly(original.id),
+            occurrenceReadonly: request.readonly,
+            intrinsicReadonly: intrinsicReadonly(original.id),
+            ...(request.declarations ? { declarations: cloneJson(request.declarations) } : {}),
+            ...(request.branchConditions?.length ? { branchConditions: cloneJson(request.branchConditions) } : {}),
+        };
+        const intent = sourceDefaultAtPath(model, request.path.slice(rootPath.length));
+        if (intent)
+            node.defaultIntent = intent;
+        nodes.push(node);
+        if (sharedReference || boundedOccurrence) {
+            node.kind = 'reference';
+            node.reason = boundedOccurrence ? 'branch-occurrence-expansion-bound' : 'shared-source-occurrence';
+            if (boundedOccurrence) {
+                node.coverage = 'partial';
+                occurrenceBoundReached = true;
+            }
+            node.alternatives = [known];
+            delete node.fields;
+            delete node.items;
+            delete node.indexSignatures;
+            delete node.tupleElements;
+            return id;
+        }
+        if (known)
+            expandedOccurrences += 1;
+        if (!known)
+            canonical.set(original.id, id);
+        activeSources.add(original.id);
+        const child = (sourceId, kind, key, required = request.required, readonly = false, declarations) => ({
+            sourceId,
+            path: [...request.path, { kind, key }],
+            required,
+            readonly,
+            ...(declarations ? { declarations } : {}),
+            ...(request.branchConditions?.length ? { branchConditions: request.branchConditions } : {}),
+        });
+        if (original.fields) {
+            node.fields = [];
+            for (const field of original.fields) {
+                const nodeId = yield child(field.nodeId, 'field', field.key, field.required, field.readonly ?? false, field.declarations);
+                node.fields.push({ ...cloneJson(field), nodeId, path: [...request.path, { kind: 'field', key: field.key }] });
+            }
+        }
+        if (original.items) {
+            node.items = [];
+            node.tupleElements = original.tupleElements ? [] : undefined;
+            if (!original.tupleElements)
+                delete node.tupleElements;
+            for (const [index, sourceId] of original.items.entries()) {
+                const tuple = original.tupleElements?.[index];
+                const nodeId = yield child(sourceId, original.kind === 'tuple' ? 'tuple' : 'item', index, tuple ? !tuple.optional : true);
+                node.items.push(nodeId);
+                if (tuple)
+                    node.tupleElements.push({ ...cloneJson(tuple), nodeId });
+            }
+        }
+        if (original.alternatives) {
+            node.alternatives = [];
+            const union = sourceDiscriminatedUnion(original, byId);
+            if (union)
+                node.unionBranches = { discriminator: union.discriminator, branches: [] };
+            for (const [index, sourceId] of original.alternatives.entries()) {
+                const branch = union?.branches.find((candidate) => candidate.memberIndex === index);
+                const childRequest = child(sourceId, original.kind === 'intersection' ? 'intersection' : 'union', index);
+                if (branch) {
+                    childRequest.required = true;
+                    childRequest.branchConditions = [
+                        ...(request.branchConditions ?? []),
+                        {
+                            unionNodeId: id,
+                            memberIndex: index,
+                            sourceMemberNodeId: sourceId,
+                            discriminator: union.discriminator,
+                            tag: branch.tag,
+                        },
+                    ];
+                }
+                const nodeId = original.kind === 'reference'
+                    ? yield {
+                        sourceId,
+                        path: request.path,
+                        required: request.required,
+                        readonly: request.readonly,
+                        target: true,
+                        ...(request.branchConditions?.length ? { branchConditions: request.branchConditions } : {}),
+                    }
+                    : yield childRequest;
+                node.alternatives.push(nodeId);
+                if (branch)
+                    node.unionBranches.branches.push({ memberIndex: index, nodeId, sourceNodeId: sourceId, tag: branch.tag });
+            }
+        }
+        if (original.indexSignatures) {
+            node.indexSignatures = [];
+            for (const index of original.indexSignatures) {
+                const valueNodeId = yield child(index.valueNodeId, 'index', index.keyType, false);
+                node.indexSignatures.push({ ...cloneJson(index), valueNodeId });
+            }
+        }
+        activeSources.delete(original.id);
+        return id;
+    };
+    const frames = [
+        visit({ sourceId: source.rootId, path: rootPath, required: root.required, readonly: root.readonly ?? false }),
+    ];
+    let returned = '';
+    let rootId = '';
+    while (frames.length) {
+        const step = frames[frames.length - 1].next(returned);
+        returned = '';
+        if (step.done) {
+            frames.pop();
+            returned = step.value;
+            if (!frames.length)
+                rootId = returned;
+        }
+        else
+            frames.push(visit(step.value));
+    }
+    if (canonical.size !== source.nodes.length)
+        throw new Error('Logical compiler accounting is incomplete');
+    return { authority: 'compiler', rootId, nodes, coverage: occurrenceBoundReached ? 'partial' : source.coverage };
+}

package/dist/src/property-contract/mapper-readiness.d.ts

@@ -0,0 +1,6 @@
+import type { CDFComponentEntry, CDFFieldDefinition } from '../cdf/types.js';
+export declare function propertyMapperBlockers(definition: CDFFieldDefinition, path?: string, category?: "content" | "design" | "state" | "unattached" | undefined): string[];
+export declare function mapperApplyBlockers(components: readonly {
+    key: string;
+    entry: CDFComponentEntry;
+}[]): string[];

package/dist/src/property-contract/mapper-readiness.js

@@ -0,0 +1,34 @@
+import { childPath, own } from './json-value.js';
+/** This vocabulary describes the deployed transport, independently of desired file support. */
+const DEPLOYED_CONTENT_TYPES = [
+    'string',
+    'richtext',
+    'number',
+    'media',
+    'link',
+    'token',
+    'boolean',
+    'array',
+    'record',
+];
+const DEPLOYED_DESIGN_TYPES = ['string', 'boolean', 'token'];
+export function propertyMapperBlockers(definition, path = '', category = definition.$category) {
+    if (category !== 'content' && category !== 'design')
+        return [];
+    const types = category === 'design' ? DEPLOYED_DESIGN_TYPES : DEPLOYED_CONTENT_TYPES;
+    const blockers = types.includes(definition.$type) ? [] : [`${path} (${definition.$type} mapper unavailable)`];
+    if (own(definition, '$values'))
+        blockers.push(`${path}/$values (finite-choice mapper unavailable)`);
+    if (definition.$items)
+        blockers.push(...propertyMapperBlockers(definition.$items, `${path}/$items`, category));
+    if (definition.valueType)
+        blockers.push(...propertyMapperBlockers(definition.valueType, `${path}/valueType`, category));
+    for (const [index, member] of (definition.members ?? []).entries())
+        blockers.push(...propertyMapperBlockers(member, `${path}/members/${index}`, category));
+    for (const [key, field] of Object.entries(definition.$fields ?? {}))
+        blockers.push(...propertyMapperBlockers(field, childPath(`${path}/$fields`, key), category));
+    return blockers;
+}
+export function mapperApplyBlockers(components) {
+    return components.flatMap(({ key, entry }) => Object.entries(entry.$properties).flatMap(([name, definition]) => propertyMapperBlockers(definition, childPath(childPath('', key) + '/$properties', name))));
+}

package/dist/src/property-contract/model-exploration.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import type { CDFComponentEntry } from '../cdf/types.js';
+import type { LogicalSourceNode } from './logical-source-graph.js';
+import type { LogicalPhysicalMapping, RepresentationPlan } from './representation-plan.js';
+export declare const ModelComponentExplorationSchema: z.ZodObject<{
+    modelKey: z.ZodString;
+    nodeId: z.ZodString;
+    sourceRevision: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    properties: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            content: "content";
+            design: "design";
+        }>;
+        authorability: z.ZodEnum<{
+            editable: "editable";
+            fixed: "fixed";
+            uncertain: "uncertain";
+        }>;
+        name: z.ZodString;
+        description: z.ZodString;
+        reasoning: z.ZodString;
+        sourceNodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    slots: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        reasoning: z.ZodString;
+        sourceNodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    modelingNotes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ModelComponentExploration = z.infer<typeof ModelComponentExplorationSchema>;
+export declare const modelComponentExplorationJsonSchema: ReturnType<typeof z.toJSONSchema>;
+/** Apply source-bound authoring judgments before model definitions receive their signed identities. */
+export declare function applyModelComponentExploration(input: ModelComponentExploration, model: {
+    key: string;
+    nodeId: string;
+    entry: CDFComponentEntry;
+}, nodes: ReadonlyMap<string, LogicalSourceNode>, mappings: Map<string, LogicalPhysicalMapping>, sourceRevision: string): void;
+export declare function modelExplorationComplete(plan: RepresentationPlan): boolean;

package/dist/src/property-contract/model-exploration.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { cloneJson, jsonEqual, own } from './json-value.js';
+const text = z.string().trim().min(1);
+const judgment = {
+    name: text,
+    description: text,
+    reasoning: text,
+    sourceNodeIds: z.array(text).min(1),
+};
+export const ModelComponentExplorationSchema = z
+    .object({
+    modelKey: text,
+    nodeId: text,
+    sourceRevision: text,
+    name: text,
+    description: text,
+    properties: z.array(z
+        .object({
+        ...judgment,
+        category: z.enum(['content', 'design']),
+        authorability: z.enum(['editable', 'fixed', 'uncertain']),
+    })
+        .strict()),
+    slots: z.array(z.object(judgment).strict()),
+    modelingNotes: z.array(text),
+})
+    .strict();
+// Generated descriptors carry non-enumerable standard-schema helpers; publish plain JSON.
+export const modelComponentExplorationJsonSchema = JSON.parse(JSON.stringify(z.toJSONSchema(ModelComponentExplorationSchema, { target: 'draft-7' })));
+/** Apply source-bound authoring judgments before model definitions receive their signed identities. */
+export function applyModelComponentExploration(input, model, nodes, mappings, sourceRevision) {
+    const report = ModelComponentExplorationSchema.parse(input);
+    if (report.modelKey !== model.key || report.nodeId !== model.nodeId || report.sourceRevision !== sourceRevision)
+        throw new Error('Model exploration has a stale or different source owner');
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(report.name) || /^Model_[a-f0-9]{32}$/.test(report.name))
+        throw new Error('Model exploration name must be a readable component identifier');
+    const exact = (names, expected, subject) => {
+        if (new Set(names).size !== names.length || !jsonEqual([...names].sort(), [...expected].sort()))
+            throw new Error(`Model exploration must account for every ${subject} exactly once`);
+    };
+    exact(report.properties.map((field) => field.name), Object.keys(model.entry.$properties), 'property');
+    exact(report.slots.map((slot) => slot.name), Object.keys(model.entry.$slots ?? {}), 'slot');
+    const checkNodes = (ids, expected) => {
+        if (new Set(ids).size !== ids.length || ids.some((id) => !expected.includes(id)))
+            throw new Error('Model exploration refers to evidence outside its exact field or slot');
+    };
+    model.entry.$description = report.description;
+    for (const field of report.properties) {
+        const mapped = [...mappings.values()].filter((item) => item.componentKey === model.key && item.field === field.name);
+        checkNodes(field.sourceNodeIds, mapped.map((item) => item.nodeId));
+        const property = model.entry.$properties[field.name];
+        if (field.authorability === 'fixed') {
+            // A source default or a caller sample does not make a value invariant.
+            const value = property.$type === 'Literal' && own(property, 'value')
+                ? property.value
+                : property.$values?.length === 1
+                    ? property.$values[0]
+                    : undefined;
+            if (!property.$required || value === undefined)
+                throw new Error(`Cannot hide ${field.name}: no required intrinsic literal proves a reconstruction value`);
+            const root = mapped.find((item) => item.withinValue?.path.length === 0);
+            const node = root && nodes.get(root.nodeId);
+            if (!node ||
+                !node.required ||
+                node.domain.provenance !== 'compiler' ||
+                node.domain.openness !== 'closed' ||
+                node.domain.declaredValues.length !== 1 ||
+                !jsonEqual(node.domain.declaredValues[0], value) ||
+                node.nullable !== false ||
+                node.undefinable !== false)
+                throw new Error(`Cannot hide ${field.name}: source presence or literal identity remains uncertain`);
+            for (const item of mapped) {
+                item.disposition = 'reconstruction';
+                item.reconstruction = { kind: 'fixed-value', value: cloneJson(value) };
+                item.reason = field.reasoning;
+            }
+            delete model.entry.$properties[field.name];
+        }
+        else {
+            property.$category = field.category;
+            property.$description = field.description;
+        }
+    }
+    for (const slot of report.slots) {
+        const definition = model.entry.$slots[slot.name];
+        checkNodes(slot.sourceNodeIds, definition.$modelBinding ? [definition.$modelBinding.nodeId] : []);
+        definition.$description = slot.description;
+    }
+}
+export function modelExplorationComplete(plan) {
+    return plan.models.every((model) => plan.modelExplorations?.some((report) => report.modelKey === model.originalKey &&
+        report.nodeId === model.nodeId &&
+        report.sourceRevision === plan.identity.sourceRevision));
+}

package/dist/src/property-contract/native-source-region.d.ts

@@ -0,0 +1,5 @@
+import type { CDFFieldDefinition } from '../cdf/types.js';
+import type { LogicalSourceNode } from './logical-source-graph.js';
+/** Derive only structures available at the target position, retaining nullish evidence separately. */
+export declare function nativeSourceRegion(nodeId: string, nodes: ReadonlyMap<string, LogicalSourceNode>, position?: 'root' | 'item' | 'field', active?: Set<string>, required?: boolean, region?: 'ordinary' | 'union-branch'): CDFFieldDefinition | undefined;
+export declare function sourceRecordFields(node: LogicalSourceNode, nodes: ReadonlyMap<string, LogicalSourceNode>): LogicalSourceNode['fields'];

package/dist/src/property-contract/native-source-region.js

@@ -0,0 +1,125 @@
+import { cloneJson } from './json-value.js';
+import { sourceDiscriminatedUnion } from './discriminated-union-source.js';
+/** Derive only structures available at the target position, retaining nullish evidence separately. */
+export function nativeSourceRegion(nodeId, nodes, position = 'root', active = new Set(), required, region = 'ordinary') {
+    const node = nodes.get(nodeId);
+    if (!node ||
+        active.has(nodeId) ||
+        node.coverage !== 'complete-within-declared-bound' ||
+        node.domain.unrepresentedValues?.length)
+        return;
+    const next = new Set(active).add(nodeId);
+    const presence = required ?? node.required;
+    const currentRegion = node.branchConditions?.length ? 'union-branch' : region;
+    if (node.kind === 'reference' && node.alternatives?.length === 1)
+        return nativeSourceRegion(node.alternatives[0], nodes, position, next, presence, currentRegion);
+    if (node.kind === 'union') {
+        const members = (node.alternatives ?? []).map((id) => nodes.get(id));
+        const values = members.filter((member) => !['null', 'undefined', 'never'].includes(member.kind));
+        if (values.length === 1)
+            return nativeSourceRegion(values[0].id, nodes, position, next, presence, currentRegion);
+        const union = sourceDiscriminatedUnion(node, nodes);
+        if (union) {
+            const members = [];
+            for (const branch of union.branches) {
+                const member = nativeSourceRegion(branch.nodeId, nodes, 'item', next, presence, 'union-branch');
+                if (!member?.$fields || member.$type !== 'record')
+                    return;
+                member.$fields[union.discriminator] = {
+                    $type: 'Literal',
+                    $required: true,
+                    value: branch.tag,
+                    valueType: { $type: typeof branch.tag },
+                };
+                members.push(member);
+            }
+            return { $type: 'DiscriminatedUnion', $required: presence, discriminator: union.discriminator, members };
+        }
+        const scalar = values[0]?.kind;
+        if (!values.length ||
+            !['string', 'number', 'boolean'].includes(scalar ?? '') ||
+            values.some((member) => member.kind !== scalar))
+            return;
+        const field = { $type: scalar, $required: presence };
+        applyChoices(field, node);
+        return branchSingleton(field, currentRegion);
+    }
+    if (['string', 'number', 'boolean'].includes(node.kind)) {
+        const field = { $type: node.kind, $required: presence };
+        applyChoices(field, node);
+        return branchSingleton(field, currentRegion);
+    }
+    if (node.kind === 'array') {
+        if (position !== 'root' || node.items?.length !== 1)
+            return;
+        const items = nativeSourceRegion(node.items[0], nodes, 'item', next, true, currentRegion);
+        return items ? { $type: 'array', $required: presence, $items: items } : undefined;
+    }
+    if ((node.kind === 'record' || node.kind === 'intersection') &&
+        position !== 'field' &&
+        !node.indexSignatures?.length &&
+        !node.callSignatures?.length) {
+        const fields = Object.create(null);
+        if (!node.fields || (node.kind === 'intersection' && !disjointRecordIntersection(node, nodes)))
+            return;
+        for (const field of node.fields) {
+            const child = nativeSourceRegion(field.nodeId, nodes, 'field', next, field.required, currentRegion);
+            if (!child)
+                return;
+            if (field.description)
+                child.$description = field.description;
+            fields[field.key] = child;
+        }
+        return { $type: 'record', $required: presence, $fields: fields };
+    }
+    return;
+}
+function branchSingleton(field, region) {
+    if (region !== 'union-branch' || field.$values?.length !== 1)
+        return field;
+    return {
+        $type: 'Literal',
+        $required: field.$required,
+        value: field.$values[0],
+        valueType: { $type: field.$type },
+    };
+}
+function applyChoices(field, node) {
+    const values = node.domain.declaredValues;
+    if (node.domain.provenance === 'compiler' &&
+        node.domain.openness === 'closed' &&
+        values.length &&
+        values.every((value) => typeof value === field.$type) &&
+        !(field.$type === 'boolean' && values.length === 2 && values.includes(true) && values.includes(false)))
+        field.$values = cloneJson(values);
+}
+function disjointRecordIntersection(node, nodes) {
+    const keys = new Set();
+    const seen = new Set();
+    const pending = [...(node.alternatives ?? [])];
+    if (!pending.length)
+        return false;
+    while (pending.length) {
+        const member = nodes.get(pending.pop());
+        if (seen.has(member.id))
+            return false;
+        seen.add(member.id);
+        if (member.kind === 'reference' || member.kind === 'intersection')
+            pending.push(...(member.alternatives ?? []));
+        else {
+            if (member.kind !== 'record' || member.indexSignatures?.length || member.callSignatures?.length)
+                return false;
+            for (const field of member.fields ?? []) {
+                if (keys.has(field.key))
+                    return false;
+                keys.add(field.key);
+            }
+        }
+    }
+    return node.fields?.length === keys.size && node.fields.every((field) => keys.has(field.key));
+}
+export function sourceRecordFields(node, nodes) {
+    return node.kind === 'record' || (node.kind === 'intersection' && disjointRecordIntersection(node, nodes))
+        ? node.fields
+        : undefined;
+}

package/dist/src/property-contract/null-handling.d.ts

@@ -0,0 +1,10 @@
+import { type PropertyIssue } from './json-value.js';
+import type { PropertySourceGraph } from './property-model.js';
+/** A source-bound behavioral judgment, separate from compiler nullability facts. */
+export interface NullHandlingJudgment {
+    sourceNodeId: string;
+    handling: 'omit-equivalent' | 'distinct' | 'unknown';
+    reason: string;
+}
+export declare function validateNullHandling(input: unknown): PropertyIssue[];
+export declare function validateNullHandlingSource(input: unknown, graph: PropertySourceGraph): PropertyIssue[];

package/dist/src/property-contract/null-handling.js

@@ -0,0 +1,45 @@
+import { jsonValueIssue } from './json-value.js';
+export function validateNullHandling(input) {
+    const unsafe = jsonValueIssue(input);
+    if (unsafe)
+        return [unsafe];
+    if (!Array.isArray(input) || !input.length)
+        return [{ path: '/null_handling', message: 'Null handling requires a nonempty judgment array' }];
+    const issues = [];
+    const seen = new Set();
+    for (const [index, value] of input.entries()) {
+        const path = `/null_handling/${index}`;
+        if (!value ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            Object.keys(value).some((key) => !['sourceNodeId', 'handling', 'reason'].includes(key)) ||
+            typeof value.sourceNodeId !== 'string' ||
+            !value.sourceNodeId.trim() ||
+            !['omit-equivalent', 'distinct', 'unknown'].includes(value.handling) ||
+            typeof value.reason !== 'string' ||
+            !value.reason.trim()) {
+            issues.push({ path, message: 'Invalid source-bound null-handling judgment' });
+            continue;
+        }
+        if (seen.has(value.sourceNodeId))
+            issues.push({ path, message: 'Duplicate null-handling source node' });
+        seen.add(value.sourceNodeId);
+    }
+    return issues;
+}
+export function validateNullHandlingSource(input, graph) {
+    const issues = validateNullHandling(input);
+    if (issues.length)
+        return issues;
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    for (const judgment of input) {
+        const node = nodes.get(judgment.sourceNodeId);
+        const members = (node?.alternatives ?? []).map((id) => nodes.get(id));
+        if (node?.kind !== 'union' || !members.some((member) => member?.kind === 'null'))
+            issues.push({ path: '/null_handling', message: 'Null judgment must reference a current nullable source union' });
+        else if (judgment.handling === 'omit-equivalent' &&
+            !members.some((member) => member && !['null', 'undefined', 'never'].includes(member.kind)))
+            issues.push({ path: '/null_handling', message: 'Null omission requires a non-null source alternative' });
+    }
+    return issues;
+}

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

@@ -0,0 +1,6 @@
+import type { CDFFieldDefinition } from '../cdf/types.js';
+import { type PropertyIssue } from './json-value.js';
+/** Finite choices stay in the source; target mapping owns enforcement and loss reporting. */
+export declare function propertyDefinitionImportBlockers(definition: CDFFieldDefinition, path?: string): string[];
+/** Physical restrictions apply to emitted fields, never to retained source evidence. */
+export declare function propertyDefinitionImportIssues(definition: CDFFieldDefinition): PropertyIssue[];