typekro 0.28.1 → 0.30.0

package/dist/core/serialization/schema.js

@@ -8,12 +8,16 @@
 import { KUBERNETES_REF_SCHEMA_MARKER_SOURCE } from '../../shared/brands.js';
 import { escapeCelString } from '../../utils/cel-escape.js';
 import { pascalCase } from '../../utils/string.js';
+import { isCelExpression, isKubernetesRef } from '../../utils/type-guards.js';
+import { isValuesMergeExpression } from '../aspects/values-merge.js';
+import { getCompositionAnalysisMetadata } from '../composition/analysis-metadata.js';
 import { createCompositionContext, runWithCompositionContext } from '../composition/context.js';
+import { TypeKroError } from '../errors.js';
 import { getComponentLogger } from '../logging/index.js';
 import { getMetadataField } from '../metadata/index.js';
 import { createSchemaProxy } from '../references/index.js';
 import { separateStatusFields } from '../validation/cel-validator.js';
-import { serializeStatusMappingsToCel } from './cel-references.js';
+import { celLiteralForValueTree, serializeStatusMappingsToCel } from './cel-references.js';
 const logger = getComponentLogger('schema-defaults');
 const SCHEMA_MARKER_PATTERN_SOURCE = KUBERNETES_REF_SCHEMA_MARKER_SOURCE;
 function deriveResourceIdAliases(resourceId) {
@@ -290,7 +294,10 @@ function resolveDefaultsByReExecution(compositionFn, specType, proxyResources) {
         // Build the set of optional top-level field names. Only optional fields
         // can be ternary-controlled (required fields always have a value).
         const optionalFieldNames = new Set((specJson.optional ?? []).map((p) => p.key));
-        const tempCtx = createCompositionContext('defaults-extraction');
+        const optionalFieldPaths = collectSchemaFieldPaths(specJson).optional;
+        const tempCtx = createCompositionContext('defaults-extraction', {
+            suppressResourceDiagnostics: true,
+        });
         // The all-undefined defaults run can throw when a composition dereferences an
         // absent optional parent (`spec.settings.tier` with settings undefined). Contain
         // it: literal-default extraction is then simply empty, but cross-field probing
@@ -330,6 +337,7 @@ function resolveDefaultsByReExecution(compositionFn, specType, proxyResources) {
             });
         }
         const crossFieldOverrides = [];
+        const ambiguousStructuredFallbacks = [];
         for (const [id, proxyRes] of proxyEntries) {
             const defaultsRes = defaultsMap.get(id);
             // Literal-default + ternary extraction need the defaults-run counterpart;
@@ -338,14 +346,23 @@ function resolveDefaultsByReExecution(compositionFn, specType, proxyResources) {
                 extractDefaultsByComparison(proxyRes, defaultsRes, defaults);
                 extractTernaryConditionals(proxyRes, defaultsRes, ternaryConditionals, optionalFieldNames, ternaryConditionFieldHints);
             }
+            // Ambiguity detection cannot depend on the all-defaults resource existing:
+            // an optional guard may remove the entire resource from that execution.
+            // Probe each bare structured schema marker with only that marker absent.
+            // A concrete structured value then proves only that black-box execution is
+            // ambiguous—not that the source was `??`—so compilation fails closed.
+            probeAmbiguousStructuredFallbacks(compositionFn, specJson, proxyRes, id, optionalFieldPaths, ambiguousStructuredFallbacks);
             // Cross-field `??` chain reconstruction is independent of the defaults run —
             // it does its own presence-probing — so it always runs.
             reconstructCrossFieldChains(compositionFn, specJson, id, proxyRes, defaults, crossFieldOverrides);
         }
         const hasResults = Object.keys(defaults).length > 0 ||
             ternaryConditionals.length > 0 ||
-            crossFieldOverrides.length > 0;
-        return hasResults ? { defaults, ternaryConditionals, crossFieldOverrides } : undefined;
+            crossFieldOverrides.length > 0 ||
+            ambiguousStructuredFallbacks.length > 0;
+        return hasResults
+            ? { defaults, ternaryConditionals, crossFieldOverrides, ambiguousStructuredFallbacks }
+            : undefined;
     }
     catch (err) {
         // Best-effort: composition functions with undefined spec fields may throw
@@ -386,6 +403,11 @@ function classifyLeaf(value) {
             return { kind: 'none' };
         return { kind: 'literal', value };
     }
+    if (Array.isArray(value))
+        return { kind: 'structured', value };
+    if (value !== null && typeof value === 'object') {
+        return { kind: 'structured', value: value };
+    }
     return { kind: 'none' };
 }
 /** Read the value at a structural path within a (proxy/probe) resource object. */
@@ -432,6 +454,38 @@ function collectMarkerLeaves(node, path, out) {
         }
     }
 }
+function collectAmbiguityCandidateLeaves(node, path, out, mergeShapes = []) {
+    if (isValuesMergeExpression(node)) {
+        const nestedMergeShapes = [
+            ...mergeShapes,
+            { path: [...path], overlayCount: node.overlays.length },
+        ];
+        collectAmbiguityCandidateLeaves(node.base, [...path, 'base'], out, nestedMergeShapes);
+        node.overlays.forEach((overlay, index) => collectAmbiguityCandidateLeaves(overlay, [...path, 'overlays', String(index)], out, nestedMergeShapes));
+        return;
+    }
+    const classified = classifyLeaf(node);
+    if (classified.kind === 'field') {
+        out.push({
+            path: [...path],
+            field: classified.field,
+            mergeShapes: mergeShapes.map((shape) => ({
+                path: [...shape.path],
+                overlayCount: shape.overlayCount,
+            })),
+        });
+        return;
+    }
+    if (Array.isArray(node)) {
+        node.forEach((value, index) => collectAmbiguityCandidateLeaves(value, [...path, String(index)], out, mergeShapes));
+        return;
+    }
+    if (node && typeof node === 'object') {
+        for (const key of Object.keys(node)) {
+            collectAmbiguityCandidateLeaves(node[key], [...path, key], out, mergeShapes);
+        }
+    }
+}
 /**
  * Build a probe `spec`: the magic schema proxy (so any field access emits its
  * `spec.X` marker) wrapped so the dotted paths in `absent` resolve to `undefined`.
@@ -448,8 +502,8 @@ function buildProbeSpec(specJson, absent) {
             if (absent.has(full))
                 return undefined;
             const v = t[prop];
-            const hasDeeperAbsent = [...absent].some((a) => a.startsWith(`${full}.`));
-            if (hasDeeperAbsent && v && (typeof v === 'object' || typeof v === 'function')) {
+            const hasDeeperMutation = [...absent].some((a) => a.startsWith(`${full}.`));
+            if (hasDeeperMutation && v && (typeof v === 'object' || typeof v === 'function')) {
                 return wrap(v, full);
             }
             return v;
@@ -460,7 +514,9 @@ function buildProbeSpec(specJson, absent) {
 /** Run the composition with a probe spec; return the resource matching `resourceId`. */
 function runProbe(compositionFn, specJson, absent, resourceId) {
     try {
-        const ctx = createCompositionContext('cross-field-probe');
+        const ctx = createCompositionContext('cross-field-probe', {
+            suppressResourceDiagnostics: true,
+        });
         runWithCompositionContext(ctx, () => {
             compositionFn(buildProbeSpec(specJson, absent));
         });
@@ -471,6 +527,249 @@ function runProbe(compositionFn, specJson, absent, resourceId) {
     }
 }
 const celField = (field) => `schema.spec.${field}`;
+/**
+ * Read a probed resource using a path captured from the proxy run. Values-merge
+ * operand segments intentionally are not transparent: if removing a candidate
+ * causes the wrapper to normalize away, the resulting merged object is not
+ * evidence that the original operand contained an implicit fallback.
+ */
+function readRawValueAtPath(obj, path) {
+    let current = obj;
+    for (const key of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function replaceValueAtPath(root, path, value) {
+    const [head, ...tail] = path;
+    if (head === undefined)
+        return value;
+    if (Array.isArray(root)) {
+        const index = Number(head);
+        if (!Number.isInteger(index) || index < 0 || index >= root.length)
+            return root;
+        const copy = [...root];
+        copy[index] = replaceValueAtPath(copy[index], tail, value);
+        return copy;
+    }
+    if (root === null || typeof root !== 'object')
+        return root;
+    const record = root;
+    return {
+        ...record,
+        [head]: replaceValueAtPath(record[head], tail, value),
+    };
+}
+/**
+ * Canonicalize only ordinary value-tree containers. References and CEL nodes
+ * are semantic leaves, while merge expressions retain their explicit operand
+ * ordering. Kubernetes object maps are unordered, so sorting their keys keeps
+ * semantically identical normalization paths from differing solely because a
+ * helper inserted properties in a different order.
+ */
+function canonicalizeValueTree(value) {
+    if (isKubernetesRef(value) || isCelExpression(value))
+        return value;
+    if (isValuesMergeExpression(value)) {
+        let base = canonicalizeValueTree(value.base);
+        let overlays = value.overlays.map(canonicalizeValueTree);
+        while (isValuesMergeExpression(base)) {
+            overlays = [...base.overlays, ...overlays];
+            base = base.base;
+        }
+        overlays = overlays.filter((overlay) => overlay !== undefined &&
+            !(overlay !== null &&
+                typeof overlay === 'object' &&
+                !Array.isArray(overlay) &&
+                Object.getPrototypeOf(overlay) === Object.prototype &&
+                Object.keys(overlay).length === 0));
+        if (overlays.length === 0)
+            return base;
+        return {
+            __typekroValuesMerge: true,
+            base,
+            overlays,
+        };
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalizeValueTree);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    const record = value;
+    return Object.fromEntries(Object.keys(record)
+        .sort()
+        .flatMap((key) => {
+        const canonical = canonicalizeValueTree(record[key]);
+        return canonical === undefined ? [] : [[key, canonical]];
+    }));
+}
+function valueTreeFingerprint(value) {
+    try {
+        return celLiteralForValueTree(canonicalizeValueTree(value), undefined, 'structured-fallback-normalization');
+    }
+    catch {
+        return undefined;
+    }
+}
+function schemaNodeAllowsNull(node) {
+    if (Array.isArray(node))
+        return node.some(schemaNodeAllowsNull);
+    if (node === null || typeof node !== 'object')
+        return false;
+    const record = node;
+    return Object.hasOwn(record, 'unit') && record.unit === null;
+}
+function collectSchemaFieldPaths(node) {
+    const optional = new Set();
+    const nullable = new Set();
+    const walk = (current, prefix) => {
+        if (Array.isArray(current)) {
+            for (const branch of current)
+                walk(branch, prefix);
+            return;
+        }
+        if (current === null || typeof current !== 'object')
+            return;
+        const objectNode = current;
+        const walkCollectionMember = (member, path) => {
+            if (schemaNodeAllowsNull(member))
+                nullable.add(path);
+            walk(member, path);
+        };
+        if (objectNode.proto === 'Array' && objectNode.sequence !== undefined) {
+            const elementPath = `${prefix}[]`;
+            walkCollectionMember(objectNode.sequence, elementPath);
+        }
+        for (const [index, member] of (objectNode.prefix ?? []).entries()) {
+            walkCollectionMember(member, `${prefix}[${index}]`);
+        }
+        for (const [index, member] of (objectNode.optionals ?? []).entries()) {
+            walkCollectionMember(member, `${prefix}[optional:${index}]`);
+        }
+        for (const [index, entry] of (objectNode.defaultables ?? []).entries()) {
+            walkCollectionMember(entry[0], `${prefix}[defaultable:${index}]`);
+        }
+        if (objectNode.variadic !== undefined) {
+            walkCollectionMember(objectNode.variadic, `${prefix}[]`);
+        }
+        for (const [index, member] of (objectNode.postfix ?? []).entries()) {
+            walkCollectionMember(member, `${prefix}[postfix:${index}]`);
+        }
+        for (const entry of objectNode.index ?? []) {
+            const valuePath = prefix ? `${prefix}.*` : '*';
+            walkCollectionMember(entry.value, valuePath);
+        }
+        for (const entry of objectNode.optional ?? []) {
+            const path = prefix ? `${prefix}.${entry.key}` : entry.key;
+            optional.add(path);
+            if (schemaNodeAllowsNull(entry.value))
+                nullable.add(path);
+            walk(entry.value, path);
+        }
+        for (const entry of objectNode.required ?? []) {
+            const path = prefix ? `${prefix}.${entry.key}` : entry.key;
+            if (schemaNodeAllowsNull(entry.value))
+                nullable.add(path);
+            walk(entry.value, path);
+        }
+    };
+    walk(node, '');
+    return { optional, nullable };
+}
+function matchingAncestorPath(field, paths) {
+    let match;
+    for (const path of paths) {
+        if ((field === path || field.startsWith(`${path}.`)) &&
+            (match === undefined || path.length > match.length)) {
+            match = path;
+        }
+    }
+    return match;
+}
+function readProbeValueAtPath(proxyResource, probedResource, candidate) {
+    for (const shape of candidate.mergeShapes) {
+        const probedMerge = readRawValueAtPath(probedResource, shape.path);
+        if (!isValuesMergeExpression(probedMerge) ||
+            probedMerge.overlays.length !== shape.overlayCount) {
+            const originalMerge = readRawValueAtPath(proxyResource, shape.path);
+            if (!isValuesMergeExpression(originalMerge)) {
+                return { value: undefined, ambiguousNormalization: true };
+            }
+            const expectedWithoutCandidate = replaceValueAtPath(originalMerge, candidate.path.slice(shape.path.length), undefined);
+            const actualFingerprint = valueTreeFingerprint(probedMerge);
+            const expectedFingerprint = valueTreeFingerprint(expectedWithoutCandidate);
+            const ambiguousNormalization = actualFingerprint === undefined ||
+                expectedFingerprint === undefined ||
+                actualFingerprint !== expectedFingerprint;
+            return {
+                value: ambiguousNormalization ? probedMerge : undefined,
+                ambiguousNormalization,
+            };
+        }
+    }
+    return {
+        value: readRawValueAtPath(probedResource, candidate.path),
+        ambiguousNormalization: false,
+    };
+}
+/**
+ * Detect a bare structured schema marker that becomes a concrete object/array
+ * when that exact field is absent. This targeted probe does not infer `??`
+ * semantics; it establishes that black-box execution is ambiguous and must
+ * fail closed. Explicit `Cel.default()` values carry CEL provenance and do not
+ * appear as bare schema-marker leaves.
+ */
+function probeAmbiguousStructuredFallbacks(compositionFn, specJson, proxyResource, resourceId, optionalFieldPaths, out) {
+    const markerLeaves = [];
+    collectAmbiguityCandidateLeaves(proxyResource, [], markerLeaves);
+    const candidatesByField = new Map();
+    for (const marker of markerLeaves) {
+        const candidates = candidatesByField.get(marker.field) ?? [];
+        candidates.push(marker);
+        candidatesByField.set(marker.field, candidates);
+    }
+    for (const [field, candidates] of candidatesByField) {
+        // Removing a required leaf is not a realizable KRO instance state. Probe
+        // only a field that is optional itself or descends from an optional parent.
+        // Nullable fields are rejected at the ArkType → KRO schema boundary because
+        // SimpleSchema cannot represent explicit null.
+        const optionalPath = matchingAncestorPath(field, optionalFieldPaths);
+        if (optionalPath === undefined)
+            continue;
+        const probedResource = runProbe(compositionFn, specJson, new Set([optionalPath]), resourceId);
+        for (const candidate of candidates) {
+            const probeRead = readProbeValueAtPath(proxyResource, probedResource, candidate);
+            const fallbackValue = probeRead.value;
+            if (probeRead.ambiguousNormalization ||
+                Array.isArray(fallbackValue) ||
+                (fallbackValue !== null && typeof fallbackValue === 'object')) {
+                out.push({
+                    resourceId,
+                    path: candidate.path,
+                    field,
+                });
+            }
+        }
+    }
+}
+function assertNoAmbiguousStructuredFallbacks(result) {
+    const [ambiguous] = result?.ambiguousStructuredFallbacks ?? [];
+    if (!ambiguous)
+        return;
+    throw new TypeKroError(`Cannot prove structured fallback semantics for schema.spec.${ambiguous.field} at ` +
+        `${ambiguous.resourceId}.${ambiguous.path.join('.')}. ` +
+        'Black-box re-execution cannot distinguish nullish coalescing from value-based control flow. ' +
+        'Use Cel.default(value, fallback) or Cel.coalesce(value, fallback) to make the graph semantics explicit.', 'AMBIGUOUS_STRUCTURED_FALLBACK', {
+        resourceId: ambiguous.resourceId,
+        path: ambiguous.path.join('.'),
+        field: ambiguous.field,
+    });
+}
 /**
  * Presence guard for a (possibly nested) optional field — every ancestor must be
  * present too. `userDeployments.enableSubchart` →
@@ -483,21 +782,33 @@ function presenceGuard(field) {
     return segs.map((_, i) => `has(schema.spec.${segs.slice(0, i + 1).join('.')})`).join(' && ');
 }
 /** Render the chain's CEL: <guard(a)> ? a : (<guard(b)> ? b : <tail>). */
-function buildChainCel(chain, tail) {
-    const tailCel = tail.kind === 'literal'
-        ? typeof tail.value === 'string'
-            ? `"${escapeCelString(tail.value)}"`
-            : String(tail.value)
-        : tail.kind === 'field'
-            ? celField(tail.field)
-            : 'omit()';
-    let expr = tailCel;
-    let nested = false;
-    for (const f of [...chain].reverse()) {
-        expr = `${presenceGuard(f)} ? ${celField(f)} : ${nested ? `(${expr})` : expr}`;
-        nested = true;
+function buildChainCel(chain, tail, resourceId, path) {
+    try {
+        const tailCel = tail.kind === 'literal'
+            ? typeof tail.value === 'string'
+                ? `"${escapeCelString(tail.value)}"`
+                : String(tail.value)
+            : tail.kind === 'field'
+                ? celField(tail.field)
+                : tail.kind === 'structured'
+                    ? `(${celLiteralForValueTree(tail.value, undefined, `structured-coalesce.${resourceId}.${path.join('.')}`)})`
+                    : 'omit()';
+        let expr = tailCel;
+        let nested = false;
+        for (const f of [...chain].reverse()) {
+            expr = `${presenceGuard(f)} ? ${celField(f)} : ${nested ? `(${expr})` : expr}`;
+            nested = true;
+        }
+        return `\${${expr}}`;
+    }
+    catch (error) {
+        logger.debug('Skipping non-serializable structured coalescing fallback', {
+            resourceId,
+            path: path.join('.'),
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
     }
-    return `\${${expr}}`;
 }
 /**
  * For each `spec.X` marker leaf in the proxy-run resource, probe to reconstruct its
@@ -537,8 +848,11 @@ function reconstructCrossFieldChains(compositionFn, specJson, resourceId, proxyR
         // existing default/omit-wrapping mechanisms, so this change can't regress them.
         const [head] = chain;
         if (chain.length >= 2 && head !== undefined) {
-            delete defaults[head];
-            out.push({ resourceId, path, cel: buildChainCel(chain, tail) });
+            const cel = buildChainCel(chain, tail, resourceId, path);
+            if (cel !== undefined) {
+                delete defaults[head];
+                out.push({ resourceId, path, cel });
+            }
         }
     }
 }
@@ -1018,6 +1332,15 @@ function collectOmitFields(specFields, specType) {
  * instead of auto-generated CEL expressions.
  */
 export function arktypeToKroSchema(name, schemaDefinition, resources, statusMappings, nestedStatusCel, schemaFieldValidations) {
+    const nullableField = collectSchemaFieldPaths(schemaDefinition.spec.json).nullable
+        .values()
+        .next().value;
+    if (nullableField !== undefined) {
+        throw new TypeKroError(`KRO SimpleSchema cannot represent nullable field schema.spec.${nullableField}. ` +
+            "TypeKro cannot preserve an ArkType 'T | null' contract by silently converting null " +
+            'to omission or a non-nullable field. Model the KRO input as optional and use ' +
+            'Cel.default(...) for omission, or use direct mode when explicit null is required.', 'KRO_NULLABLE_SCHEMA_UNSUPPORTED', { field: nullableField });
+    }
     const specFields = arktypeJsonToKroFields(schemaDefinition.spec.json);
     if (!specFields.name) {
         specFields.name = `string | default="${name}"`;
@@ -1032,8 +1355,7 @@ export function arktypeToKroSchema(name, schemaDefinition, resources, statusMapp
     //   undefined for optional fields, triggering ?? and resolving imported
     //   constants from the closure. Compares resolved resources with the
     //   proxy-run resources (markers) to extract field → default mappings.
-    const statusMeta = statusMappings;
-    const compositionFn = statusMeta?.__originalCompositionFn;
+    const compositionFn = getCompositionAnalysisMetadata(statusMappings)?.originalCompositionFn;
     // Phase 1a: regex extraction for the outer composition's own defaults.
     if (typeof compositionFn === 'function') {
         const regexDefaults = extractNullishDefaults(compositionFn.toString());
@@ -1093,6 +1415,7 @@ export function arktypeToKroSchema(name, schemaDefinition, resources, statusMapp
             const reExecutionResult = nestedDefinition && nestedResources
                 ? resolveDefaultsByReExecution(fn, nestedDefinition.spec, nestedResources)
                 : undefined;
+            assertNoAmbiguousStructuredFallbacks(reExecutionResult);
             const reExecutionDefaults = reExecutionResult?.defaults ?? {};
             const innerDefaults = remapNullishDefaults({ ...extractedDefaults, ...reExecutionDefaults }, specMappings);
             // Non-destructive: don't overwrite existing outer defaults.
@@ -1112,6 +1435,7 @@ export function arktypeToKroSchema(name, schemaDefinition, resources, statusMapp
     if (typeof compositionFn === 'function' && resources) {
         const reExecutionResult = resolveDefaultsByReExecution(compositionFn, schemaDefinition.spec, resources);
         if (reExecutionResult) {
+            assertNoAmbiguousStructuredFallbacks(reExecutionResult);
             applyNullishDefaults(specFields, reExecutionResult.defaults, true);
             ternaryConditionals.push(...reExecutionResult.ternaryConditionals);
             // Cross-field `??` chains reconstructed by probing: write each CEL conditional
@@ -1127,7 +1451,7 @@ export function arktypeToKroSchema(name, schemaDefinition, resources, statusMapp
     const ternaryFieldNames = new Set(ternaryConditionals.map((t) => t.conditionField));
     const omitFields = collectOmitFields(specFields, schemaDefinition.spec).filter((f) => !ternaryFieldNames.has(f));
     // Filter internal fields (prefixed with __) before classification.
-    // These are TypeKro metadata (e.g., __nestedStatusCel, __originalCompositionFn)
+    // These are TypeKro metadata (for example, __nestedStatusCel).
     // that should never appear in the KRO schema.
     const userStatusMappings = {};
     if (statusMappings) {