typekro 0.7.0 → 0.9.0

package/dist/core/serialization/schema.js

@@ -5,9 +5,26 @@
  * simple schemas, and provides utility functions for generating schemas
  * from resource maps.
  */
+import { escapeCelString } from '../../utils/cel-escape.js';
+import { KUBERNETES_REF_SCHEMA_MARKER_SOURCE } from '../../shared/brands.js';
+import { createCompositionContext, runWithCompositionContext } from '../composition/context.js';
+import { getComponentLogger } from '../logging/index.js';
+import { getMetadataField } from '../metadata/index.js';
 import { pascalCase } from '../../utils/string.js';
 import { separateStatusFields } from '../validation/cel-validator.js';
 import { serializeStatusMappingsToCel } from './cel-references.js';
+const logger = getComponentLogger('schema-defaults');
+const SCHEMA_MARKER_PATTERN_SOURCE = KUBERNETES_REF_SCHEMA_MARKER_SOURCE;
+function deriveResourceIdAliases(resourceId) {
+    const aliases = [];
+    for (const match of resourceId.matchAll(/\d+/g)) {
+        const suffix = resourceId.slice((match.index ?? 0) + match[0].length);
+        if (suffix && /^[A-Z]/.test(suffix)) {
+            aliases.push(suffix.charAt(0).toLowerCase() + suffix.slice(1));
+        }
+    }
+    return aliases;
+}
 // ---------------------------------------------------------------------------
 // Arktype JSON AST → Kro type helpers (private)
 // ---------------------------------------------------------------------------
@@ -27,6 +44,20 @@ function getKroTypeFromJson(node) {
         if (nodeObj.domain === 'number' && nodeObj.divisor === 1) {
             return 'integer';
         }
+        // Map / Record types — arktype represents `Record<string, V>` as
+        // `{ domain: "object", index: [{ signature: "string", value: V }] }`.
+        // KRO SimpleSchema uses `map[string]<value-type>` notation for these.
+        if (nodeObj.domain === 'object' &&
+            Array.isArray(nodeObj.index) &&
+            nodeObj.index.length === 1) {
+            const indexEntry = nodeObj.index[0];
+            if (indexEntry.signature === 'string') {
+                return `map[string]${getKroTypeFromJson(indexEntry.value)}`;
+            }
+        }
+        if (nodeObj.domain === 'object' || nodeObj.required || nodeObj.optional) {
+            return 'object';
+        }
     }
     // Case 2: Array → union of literals
     if (Array.isArray(node)) {
@@ -35,6 +66,9 @@ function getKroTypeFromJson(node) {
             node.some((branch) => branch.unit === false)) {
             return 'boolean';
         }
+        if (node.some((branch) => !branch || typeof branch !== 'object' || !('unit' in branch))) {
+            return 'object';
+        }
         const enumValues = node.map((branch) => {
             if (typeof branch.unit === 'string') {
                 return branch.unit;
@@ -85,7 +119,6 @@ function arktypeJsonToKroFields(node) {
         if (typeof childNode === 'object' &&
             childNode !== null &&
             (childNode.required || childNode.optional)) {
-            // Nested object — recurse to produce a nested schema
             fields[prop.key] = arktypeJsonToKroFields(childNode);
         }
         else {
@@ -95,6 +128,643 @@ function arktypeJsonToKroFields(node) {
     return fields;
 }
 // ---------------------------------------------------------------------------
+// Nullish coalescing default extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract literal default values from `spec.field ?? literalValue` patterns
+ * in a composition function's source code.
+ *
+ * **FAST PATH — NOT AUTHORITATIVE.** This regex-based extraction runs first
+ * to catch the common case where a composition uses `spec.X ?? 'literal'`
+ * with a literal right-hand side. It is intentionally conservative:
+ *
+ * - Both `??` and the literal must be on the same source line.
+ * - The literal must be a string, number, boolean, or minified !0/!1 form.
+ * - The right-hand side cannot be a constant, variable, template literal,
+ *   function call, or expression involving other spec fields.
+ *
+ * Anything this regex misses is caught by {@link resolveDefaultsByReExecution}
+ * (Phase 2), which actually executes the composition function with optional
+ * fields set to `undefined` and observes the concrete resolved values. Phase 2
+ * is the authoritative source; this function only exists to short-circuit
+ * the common case so the heavy re-execution doesn't need to compare every
+ * field for every composition.
+ *
+ * In KRO mode, `??` doesn't trigger for proxy objects (they're truthy).
+ * Instead, we detect these patterns via fn.toString() and add
+ * `| default=<value>` annotations to the KRO SimpleSchema so that KRO
+ * uses the intended default when the field isn't provided in the CR.
+ *
+ * NOTE: `.orValue()` is NOT supported in KRO resource templates (only in
+ * status CEL). Schema `| default=` is the correct mechanism for resource
+ * template defaults.
+ *
+ * Handles:
+ * - `spec.field ?? 'string'` or `spec.field ?? "string"`
+ * - `spec.field ?? 123` (numbers)
+ * - `spec.field ?? true/false` (booleans, including minified !0/!1)
+ * - `spec.parent?.child ?? value` (optional chaining)
+ */
+export function extractNullishDefaults(fnSource) {
+    const defaults = {};
+    const pattern = /spec\.([\w]+(?:\??\.\w+)*)\s*\?\?\s*(?:(['"])([^'"]*)\2|(-?\d+(?:\.\d+)?)|true|false|!0|!1)(?=\s*[;,)}\n])/g;
+    let match = pattern.exec(fnSource);
+    while (match !== null) {
+        const fieldPath = match[1]?.replace(/\?\./g, '.');
+        if (!fieldPath) {
+            match = pattern.exec(fnSource);
+            continue;
+        }
+        const stringValue = match[3];
+        const numericValue = match[4];
+        if (stringValue !== undefined) {
+            defaults[fieldPath] = stringValue;
+        }
+        else if (numericValue !== undefined) {
+            defaults[fieldPath] = Number(numericValue);
+        }
+        else {
+            const fullMatch = match[0];
+            if (fullMatch.endsWith('true') || fullMatch.endsWith('!0'))
+                defaults[fieldPath] = true;
+            else if (fullMatch.endsWith('false') || fullMatch.endsWith('!1'))
+                defaults[fieldPath] = false;
+        }
+        match = pattern.exec(fnSource);
+    }
+    return defaults;
+}
+/**
+ * Placeholder value passed in place of required spec fields during the
+ * defaults-extraction re-execution. Any captured leaf value that IS this
+ * string, CONTAINS this string as a substring (from template-literal
+ * interpolation), or is NaN (from arithmetic coercion of the string) is
+ * filtered out by the sentinel-detection logic in `extractDefaultsByComparison`
+ * so it never gets recorded as a real schema default.
+ *
+ * The choice of a string (rather than a Symbol or object) is deliberate:
+ *   - String concatenation preserves the token so template-literal usage
+ *     produces a clearly-identifiable captured value (e.g. `"__typekro_default__-cfg"`).
+ *   - Truthiness matches the real proxy behavior (proxies are truthy), so
+ *     `if (spec.requiredField)` takes the same branch in both runs.
+ *   - Numeric contexts coerce to NaN in both runs (proxies also coerce to
+ *     NaN because functions have no numeric value), so arithmetic-derived
+ *     NaN values are symmetric across runs and don't produce spurious defaults.
+ *
+ * If the propagation ever drifts out of this sentinel's shape (e.g. someone
+ * introduces a Symbol-based sentinel), update `isSentinelDerivedValue` below
+ * to match.
+ */
+export const REQUIRED_FIELD_SENTINEL = '__typekro_default__';
+/**
+ * Check whether a captured value is derived from the required-field sentinel
+ * and therefore should NOT be recorded as a real schema default. Handles:
+ *   - Direct sentinel or substring (template-literal propagation)
+ *   - NaN (numeric-coercion propagation — both runs produce NaN symmetrically,
+ *     but the defaults run's NaN must be filtered out of the defaults map)
+ */
+function isSentinelDerivedValue(v) {
+    if (typeof v === 'string')
+        return v.includes(REQUIRED_FIELD_SENTINEL);
+    if (typeof v === 'number')
+        return Number.isNaN(v);
+    return false;
+}
+/**
+ * Resolve ?? defaults by re-executing the composition function with undefined
+ * for optional spec fields. This triggers ?? fallbacks naturally, resolving
+ * imported constants from the closure (e.g., DEFAULT_SEARXNG_IMAGE).
+ *
+ * Also detects ternary conditional sections (spec.field ? section : '') by
+ * comparing resource strings between proxy-run and defaults-run.
+ *
+ * Runs in a temporary, isolated composition context. Resource registrations
+ * are contained within the temp context. However, composition functions with
+ * external side effects (API calls, logging, metrics) will fire during this
+ * re-execution. Composition functions should be side-effect-free beyond
+ * resource creation for this mechanism to work safely.
+ */
+function resolveDefaultsByReExecution(compositionFn, specType, proxyResources) {
+    try {
+        const specJson = specType.json;
+        if (!specJson)
+            return undefined;
+        const defaultsSpec = {};
+        for (const p of specJson.required ?? [])
+            defaultsSpec[p.key] = REQUIRED_FIELD_SENTINEL;
+        for (const p of specJson.optional ?? [])
+            defaultsSpec[p.key] = undefined;
+        // 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');
+        runWithCompositionContext(tempCtx, () => {
+            compositionFn(defaultsSpec);
+        });
+        const defaults = {};
+        const ternaryConditionals = [];
+        const ternaryConditionFieldHints = extractTernaryConditionFieldHints(compositionFn.toString());
+        // Match resources by RESOURCE ID rather than by insertion order. Compositions
+        // that use `if (!spec.optional) { createResource(...) }` produce different
+        // resource counts between runs — positional matching silently pairs
+        // unrelated resources (e.g., the defaults run's auto-Secret against the
+        // proxy run's Deployment) and corrupts both default extraction and
+        // ternary detection. Key-based matching is robust against conditional
+        // resource creation: resources present in only one run are simply skipped
+        // for comparison.
+        const proxyEntries = Object.entries(proxyResources);
+        const defaultsEntries = Object.entries(tempCtx.resources);
+        const defaultsMap = new Map(defaultsEntries);
+        if (proxyEntries.length !== defaultsEntries.length) {
+            // Different resource counts between runs are expected when the
+            // composition uses conditional `createResource` patterns — the
+            // defaults run takes different branches than the proxy run.
+            // Key-based matching handles this correctly, so downgrade to debug.
+            logger.debug('Re-execution produced a different number of resources than the proxy run — matching by resource ID', {
+                proxyResourceCount: proxyEntries.length,
+                defaultsResourceCount: defaultsEntries.length,
+            });
+        }
+        for (const [id, proxyRes] of proxyEntries) {
+            const defaultsRes = defaultsMap.get(id);
+            if (!defaultsRes)
+                continue; // resource only in proxy run — skip
+            extractDefaultsByComparison(proxyRes, defaultsRes, defaults);
+            extractTernaryConditionals(proxyRes, defaultsRes, ternaryConditionals, optionalFieldNames, ternaryConditionFieldHints);
+        }
+        const hasResults = Object.keys(defaults).length > 0 || ternaryConditionals.length > 0;
+        return hasResults ? { defaults, ternaryConditionals } : undefined;
+    }
+    catch (err) {
+        // Best-effort: composition functions with undefined spec fields may throw
+        // (e.g., accessing spec.nested.field without optional chaining). Log at
+        // debug level for troubleshooting but don't fail schema generation.
+        logger.debug('Defaults re-execution failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * Recursively compare proxy-run resource values (with __KUBERNETES_REF__ markers)
+ * against defaults-run values (with resolved constants) to find field defaults.
+ *
+ * When a proxy value is `__KUBERNETES_REF___schema___spec.FIELD__` and the
+ * corresponding defaults value is a concrete scalar, we record FIELD → value.
+ */
+function extractDefaultsByComparison(proxyVal, defaultsVal, result) {
+    // KubernetesRef proxies are functions whose toString() returns a marker string.
+    // Coerce to string to check for __KUBERNETES_REF__ markers.
+    const proxyStr = typeof proxyVal === 'function' || typeof proxyVal === 'string'
+        ? String(proxyVal) : null;
+    // Only match when the proxy value IS the marker (exact, single reference).
+    // If the marker is embedded inside a larger string (template literal), the
+    // value is a transformation, not a default — e.g., `\`has-${spec.extra}\``
+    // produces `"has-<marker>"` which is NOT a default for `extra`.
+    const exactMarkerMatch = proxyStr?.match(new RegExp(`^${SCHEMA_MARKER_PATTERN_SOURCE}$`));
+    const exactFieldPath = exactMarkerMatch?.[1];
+    if (exactFieldPath?.startsWith('spec.')) {
+        if (typeof defaultsVal === 'string' ||
+            typeof defaultsVal === 'number' ||
+            typeof defaultsVal === 'boolean') {
+            // Skip values derived from the required-field sentinel — these aren't
+            // real defaults. Covers: string containing the sentinel token
+            // (template-literal propagation), NaN (arithmetic-coercion
+            // propagation), and the sentinel itself.
+            if (isSentinelDerivedValue(defaultsVal))
+                return;
+            const fieldKey = exactFieldPath.slice('spec.'.length);
+            if (fieldKey) {
+                result[fieldKey] = defaultsVal;
+            }
+        }
+        return;
+    }
+    // If the proxy is a string but contains the marker as part of larger content,
+    // skip the defaults check (recursion into arrays/objects still applies below).
+    if (proxyStr?.includes('__KUBERNETES_REF___schema___')) {
+        return;
+    }
+    if (Array.isArray(proxyVal) && Array.isArray(defaultsVal)) {
+        for (let i = 0; i < Math.min(proxyVal.length, defaultsVal.length); i++) {
+            extractDefaultsByComparison(proxyVal[i], defaultsVal[i], result);
+        }
+        return;
+    }
+    if (proxyVal && typeof proxyVal === 'object' && defaultsVal && typeof defaultsVal === 'object') {
+        for (const key of Object.keys(proxyVal)) {
+            extractDefaultsByComparison(proxyVal[key], defaultsVal[key], result);
+        }
+    }
+}
+/**
+ * Detect ternary conditional sections by finding markers in the proxy-run
+ * string that are completely ABSENT from the defaults-run string.
+ *
+ * When `spec.redisUrl ? \`redis: ...\` : ''` is evaluated:
+ * - Proxy run (truthy): the redis section with markers is included
+ * - Defaults run (falsy): the redis section is empty — the marker is absent
+ *
+ * For each such "orphan" marker, we extract the surrounding section
+ * (from the previous newline-at-start-of-key to the marker's end) as a
+ * ternary-controlled conditional.
+ *
+ * Ternary test-field hints
+ * ------------------------
+ * Re-execution only shows that a marker-containing section disappeared;
+ * it does not leave runtime metadata for the ternary TEST expression. The
+ * caller supplies a best-effort map derived from the composition source so
+ * common decoupled patterns can guard on the tested field:
+ *
+ *     spec.redisUrl ? `redis:\n  url: ${spec.redisUrl}` : ''
+ *
+ *     spec.enableRedis ? `redis:\n  url: ${spec.connectionString}` : ''
+ *
+ * If no hint is available, we fall back to the referenced field, preserving
+ * the historical behavior for `spec.redisUrl ? ... ${spec.redisUrl} ...`.
+ *
+ * FRAGILE: this walks line-by-line through the proxy string and backs
+ * through parent YAML keys by regex-matching `^\s*\w+:\s*$` and comparing
+ * against a set of lines from the defaults string. It assumes the
+ * composition constructs YAML-ish content directly (typically via template
+ * literal) with 2-space indentation, canonical key: value syntax, and no
+ * block scalars (`|`, `>`). Compositions that emit flow-style YAML, that
+ * use tab indentation, that quote keys, or that assemble the string
+ * through multiple splice operations will not match cleanly. The
+ * extracted `proxySection` is later consumed by
+ * `applyTernaryConditionalsToResources` via exact substring match — keep
+ * both functions' assumptions in sync when updating either side.
+ *
+ * Tracked for replacement with AST-based detection in
+ * https://github.com/yehudacohen/typekro/issues/57
+ */
+function extractTernaryConditionals(proxyVal, defaultsVal, result, optionalFieldNames, conditionFieldHints) {
+    const proxyStr = typeof proxyVal === 'string' ? proxyVal : null;
+    const defaultsStr = typeof defaultsVal === 'string' ? defaultsVal : null;
+    if (proxyStr && defaultsStr && proxyStr !== defaultsStr && proxyStr.length > defaultsStr.length) {
+        // Find all __KUBERNETES_REF__ markers in the proxy string
+        const markerPattern = new RegExp(SCHEMA_MARKER_PATTERN_SOURCE, 'g');
+        let match = markerPattern.exec(proxyStr);
+        while (match !== null) {
+            const fieldPath = match[1];
+            if (!fieldPath?.startsWith('spec.')) {
+                match = markerPattern.exec(proxyStr);
+                continue;
+            }
+            const field = fieldPath.slice('spec.'.length);
+            const conditionField = conditionFieldHints.get(field) ?? field;
+            const marker = match[0];
+            // Only optional fields can be ternary-controlled. Required fields always
+            // have a value (the sentinel in the defaults run), so their markers are
+            // always "absent" from the defaults string but they're substitutions,
+            // not conditionals.
+            const topLevelField = conditionField.split('.')[0];
+            if (!topLevelField) {
+                match = markerPattern.exec(proxyStr);
+                continue;
+            }
+            if (!optionalFieldNames.has(topLevelField)) {
+                match = markerPattern.exec(proxyStr);
+                continue;
+            }
+            // Check if this marker is a TERNARY conditional (section absent from defaults)
+            // vs a ?? fallback (same key exists with a different value in defaults).
+            // Find the YAML key before the marker (e.g., `url: ` before the redisUrl marker).
+            const lineStart = proxyStr.lastIndexOf('\n', match.index) + 1;
+            const line = proxyStr.slice(lineStart, match.index + marker.length);
+            const keyMatch = line.match(/(\w+):\s*$/)?.[1] || line.match(/^\s*(\w+):/)?.[1];
+            const keyExistsInDefaults = keyMatch
+                ? new RegExp(`\\b${keyMatch}\\s*:`).test(defaultsStr)
+                : false;
+            // If the key exists in defaults, this is a ?? fallback (handled elsewhere).
+            // If the key is absent, this is a ternary conditional (section not present).
+            if (!keyExistsInDefaults && !defaultsStr.includes(marker)) {
+                // Extract the section containing this marker.
+                // Walk backward from the marker to find the start of the conditional
+                // section. Include parent YAML keys at ALL nesting levels (not just one)
+                // so that `redis:\n  connection:\n    url: ${ref}` captures all three lines.
+                let sectionStart = match.index;
+                while (sectionStart > 0 && proxyStr[sectionStart - 1] !== '\n') {
+                    sectionStart--;
+                }
+                // Walk back through preceding blank lines
+                while (sectionStart > 0 && proxyStr[sectionStart - 1] === '\n') {
+                    sectionStart--;
+                }
+                // Walk back through parent YAML keys (lines with `key:` and no value).
+                // Keep walking as long as the previous line is a key-only line that
+                // doesn't exist as a complete line in the defaults. Set membership
+                // (not substring match) avoids false stops on coincidental substrings.
+                const defaultsLines = new Set(defaultsStr.split('\n'));
+                const allLines = proxyStr.slice(0, sectionStart).split('\n');
+                while (allLines.length > 0) {
+                    const prevLine = allLines[allLines.length - 1];
+                    if (prevLine === undefined)
+                        break;
+                    const isKeyOnlyLine = /^\s*\w+:\s*$/.test(prevLine);
+                    const lineExistsInDefaults = defaultsLines.has(prevLine);
+                    if (isKeyOnlyLine && !lineExistsInDefaults) {
+                        sectionStart -= prevLine.length + 1; // +1 for the \n
+                        allLines.pop();
+                    }
+                    else {
+                        break;
+                    }
+                }
+                // Section ends after the marker
+                const sectionEnd = match.index + marker.length;
+                const proxySection = proxyStr.slice(sectionStart, sectionEnd);
+                // Verify the section, when removed from proxy string, makes it closer to defaults
+                if (proxySection.includes(marker)) {
+                    result.push({
+                        proxySection,
+                        falsyValue: '',
+                        conditionField,
+                    });
+                }
+            }
+            match = markerPattern.exec(proxyStr);
+        }
+        return;
+    }
+    // Recurse into arrays and objects
+    if (Array.isArray(proxyVal) && Array.isArray(defaultsVal)) {
+        for (let i = 0; i < Math.min(proxyVal.length, defaultsVal.length); i++) {
+            extractTernaryConditionals(proxyVal[i], defaultsVal[i], result, optionalFieldNames, conditionFieldHints);
+        }
+        return;
+    }
+    if (proxyVal && typeof proxyVal === 'object' && defaultsVal && typeof defaultsVal === 'object') {
+        for (const key of Object.keys(proxyVal)) {
+            extractTernaryConditionals(proxyVal[key], defaultsVal[key], result, optionalFieldNames, conditionFieldHints);
+        }
+    }
+}
+function extractTernaryConditionFieldHints(source) {
+    const hints = new Map();
+    const ternaryTemplatePattern = /spec\.([A-Za-z_$][\w$]*(?:\?\.[A-Za-z_$][\w$]*|\.[A-Za-z_$][\w$]*)*)\s*\?\s*`([\s\S]*?)`\s*:\s*(?:''|""|``)/g;
+    let match = ternaryTemplatePattern.exec(source);
+    while (match) {
+        const conditionField = normalizeSpecFieldPath(match[1]);
+        const consequent = match[2] ?? '';
+        if (conditionField) {
+            const refPattern = /\$\{\s*spec\.([A-Za-z_$][\w$]*(?:\?\.[A-Za-z_$][\w$]*|\.[A-Za-z_$][\w$]*)*)/g;
+            let refMatch = refPattern.exec(consequent);
+            while (refMatch) {
+                const referencedField = normalizeSpecFieldPath(refMatch[1]);
+                if (referencedField && !hints.has(referencedField)) {
+                    hints.set(referencedField, conditionField);
+                }
+                refMatch = refPattern.exec(consequent);
+            }
+        }
+        match = ternaryTemplatePattern.exec(source);
+    }
+    return hints;
+}
+function normalizeSpecFieldPath(path) {
+    return path?.replace(/\?\./g, '.');
+}
+/**
+ * Apply extracted nullish defaults to a KRO SimpleSchema spec fields object.
+ * Appends `| default=<value>` to the field's type string.
+ *
+ * The two-phase default extraction uses this function twice:
+ *   - Phase 1 (regex, `extractNullishDefaults`) — fast but may misfire on
+ *     edge cases (multi-line expressions, nested parens). Called with
+ *     `overwrite: false` so it doesn't clobber existing annotations.
+ *   - Phase 2 (re-execution, `resolveDefaultsByReExecution`) — slower but
+ *     authoritative. Called with `overwrite: true` so it REPLACES any
+ *     Phase 1 annotation for the same field, ensuring a wrong Phase 1
+ *     result doesn't survive when Phase 2 produces a corrected value.
+ */
+function applyNullishDefaults(specFields, defaults, overwrite = false) {
+    for (const [path, value] of Object.entries(defaults)) {
+        const parts = path.split('.');
+        let current = specFields;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (!part)
+                continue;
+            if (current[part] && typeof current[part] === 'object') {
+                current = current[part];
+            }
+            else {
+                current = undefined;
+                break;
+            }
+        }
+        if (!current)
+            continue;
+        const fieldName = parts[parts.length - 1];
+        if (!fieldName)
+            continue;
+        const existingType = current[fieldName];
+        if (typeof existingType !== 'string')
+            continue;
+        // Escape special characters in string defaults so they survive
+        // the KRO SimpleSchema default= annotation format. Without this,
+        // multiline strings (e.g., YAML config blobs) break the parser.
+        const defaultStr = typeof value === 'string'
+            ? `"${escapeCelString(value)}"`
+            : String(value);
+        const hasDefault = existingType.includes('default=');
+        if (!hasDefault) {
+            current[fieldName] = `${existingType} | default=${defaultStr}`;
+        }
+        else if (overwrite) {
+            // Strip any existing `| default=...` segment and replace with the
+            // authoritative Phase 2 value. The segment may appear as `| default="x"`,
+            // `| default=123`, or `| default=true` — match to the end of the value
+            // or to the next `|` (for additional annotations chained after it).
+            const withoutDefault = existingType.replace(/\s*\|\s*default=(?:"[^"]*"|[^|]*)/, '');
+            current[fieldName] = `${withoutDefault} | default=${defaultStr}`;
+        }
+    }
+}
+/**
+ * Infer the KRO SimpleSchema type string for a literal default value.
+ */
+function kroTypeForLiteral(value) {
+    if (typeof value === 'string') {
+        return `string | default="${escapeCelString(value)}"`;
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value)
+            ? `integer | default=${value}`
+            : `number | default=${value}`;
+    }
+    if (typeof value === 'boolean') {
+        return `boolean | default=${value}`;
+    }
+    return 'string';
+}
+/**
+ * For each default whose path doesn't exist in `specFields`, CREATE the
+ * missing leaf (and any intermediate object nodes along the way) with
+ * an appropriate KRO type string + default annotation.
+ *
+ * This is the complement to {@link applyNullishDefaults}, which only
+ * annotates fields that already exist. Adding missing fields enables the
+ * "propagate inner composition `?? defaults` to the outer schema"
+ * mechanism: when an inner composition reads `spec.X?.Y ?? <literal>`
+ * and the outer schema doesn't declare Y, we auto-declare it with the
+ * inner's default so KRO can resolve the reference at apply time.
+ *
+ * **Scope rules:**
+ *  - We only auto-create a missing field if EITHER the full path's parent
+ *    already exists as an object in `specFields` (we're filling in a
+ *    single missing leaf under a known object), OR the top-level parent
+ *    (the first segment) doesn't exist at all (we're adding a whole new
+ *    optional field). We do NOT create intermediate objects where the
+ *    outer has explicitly declared a non-object type.
+ *  - Existing fields are never modified — use `applyNullishDefaults`
+ *    for that.
+ */
+function addMissingDefaultFields(specFields, defaults) {
+    for (const [path, value] of Object.entries(defaults)) {
+        const parts = path.split('.');
+        if (parts.length === 0)
+            continue;
+        // Walk existing intermediate objects.
+        let current = specFields;
+        let i = 0;
+        for (; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (!part)
+                continue;
+            const next = current[part];
+            if (next && typeof next === 'object' && !Array.isArray(next)) {
+                current = next;
+            }
+            else if (next === undefined) {
+                // Create missing intermediate object node.
+                const obj = {};
+                current[part] = obj;
+                current = obj;
+            }
+            else {
+                // Intermediate path conflicts with an existing scalar — bail.
+                current = undefined;
+                break;
+            }
+        }
+        if (!current)
+            continue;
+        const leafName = parts[parts.length - 1];
+        if (!leafName)
+            continue;
+        if (leafName in current)
+            continue; // existing — skip
+        current[leafName] = kroTypeForLiteral(value);
+    }
+}
+function remapDefaultPath(path, mappings) {
+    if (Object.hasOwn(mappings, '')) {
+        const mappedPrefix = mappings[''];
+        return mappedPrefix ? `${mappedPrefix}.${path}` : path;
+    }
+    const matches = Object.keys(mappings)
+        .filter((prefix) => path === prefix || path.startsWith(`${prefix}.`))
+        .sort((left, right) => right.length - left.length);
+    const prefix = matches[0];
+    if (prefix === undefined)
+        return undefined;
+    const mappedPrefix = mappings[prefix];
+    if (mappedPrefix === undefined)
+        return undefined;
+    const suffix = path.slice(prefix.length);
+    if (mappedPrefix === '') {
+        return suffix.startsWith('.') ? suffix.slice(1) : suffix;
+    }
+    return `${mappedPrefix}${suffix}`;
+}
+function remapNullishDefaults(defaults, mappings) {
+    const remapped = {};
+    for (const [path, value] of Object.entries(defaults)) {
+        const mappedPath = remapDefaultPath(path, mappings);
+        if (mappedPath !== undefined) {
+            remapped[mappedPath] = value;
+        }
+    }
+    return remapped;
+}
+function schemaSpecMarker(path) {
+    return `__KUBERNETES_REF___schema___spec.${path}__`;
+}
+function remapTernaryConditionals(conditionals, mappings) {
+    return conditionals.flatMap((conditional) => {
+        const conditionField = remapDefaultPath(conditional.conditionField, mappings);
+        if (conditionField === undefined)
+            return [];
+        const proxySection = conditional.proxySection.replace(new RegExp(SCHEMA_MARKER_PATTERN_SOURCE, 'g'), (marker, fieldPath) => {
+            if (!fieldPath.startsWith('spec.'))
+                return marker;
+            const remappedPath = remapDefaultPath(fieldPath.slice('spec.'.length), mappings);
+            return remappedPath === undefined ? marker : schemaSpecMarker(remappedPath);
+        });
+        return [{ ...conditional, conditionField, proxySection }];
+    });
+}
+/**
+ * Collect optional spec fields that don't have | default= annotations.
+ * These fields need omit() wrapping in resource templates (KRO 0.9+)
+ * so they're removed from the K8s resource when not provided, rather
+ * than failing with an invalid zero value.
+ *
+ * Recurses into ALL object types so that both top-level optionals
+ * (`env?`, `resources?`) and nested optionals (`database.storageClass?`,
+ * `cache.replicas?`) are collected. Returns dotted field paths
+ * (e.g., `['baseUrl', 'env', 'database.storageClass', 'cache', 'cache.replicas']`).
+ *
+ * **Both parent and children are tracked** when a whole object is
+ * optional: if the user provides `cache: { shards: 1 }` (present but
+ * with `replicas` absent), `has(cache)` is true and we must still
+ * guard `cache.replicas` with its own omit. The ancestor resolution
+ * in `maybeWrapWithOmit` prefers the deepest matching prefix, so a
+ * ref to `cache.replicas` gets `has(cache.replicas) ? ... : omit()`
+ * while a ref to `cache.shards` (required scalar with no default,
+ * not in the set) falls back to the ancestor `cache` guard.
+ */
+function collectOmitFields(specFields, specType) {
+    const omitFields = [];
+    walk(specFields, specType.json, '');
+    return omitFields;
+    function walk(fields, node, pathPrefix) {
+        if (!node || typeof node !== 'object')
+            return;
+        const nodeObj = node;
+        const optionalKeys = new Set((nodeObj.optional ?? []).map((p) => p.key));
+        const allEntries = [...(nodeObj.required ?? []), ...(nodeObj.optional ?? [])];
+        for (const entry of allEntries) {
+            const fieldName = entry.key;
+            const fullPath = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
+            const existingType = fields[fieldName];
+            const isOptional = optionalKeys.has(fieldName);
+            // Scalar optional without default → needs its own omit() guard.
+            if (isOptional &&
+                typeof existingType === 'string' &&
+                !existingType.includes('default=')) {
+                omitFields.push(fullPath);
+                continue;
+            }
+            // Object (optional or required) → record the path if optional,
+            // AND recurse to catch nested optional leaves. Even when the
+            // object is required, its children may have their own optional
+            // markers. Even when the object is optional, its children still
+            // need their own guards because a present-but-sparse object
+            // (e.g., `cache: { shards: 1 }` with `replicas` absent) must
+            // not fail on ref-time `cache.replicas` access.
+            if (typeof existingType === 'object' && existingType !== null) {
+                if (isOptional) {
+                    omitFields.push(fullPath);
+                }
+                walk(existingType, entry.value, fullPath);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 /**
@@ -111,6 +781,112 @@ export function arktypeToKroSchema(name, schemaDefinition, resources, statusMapp
     if (!specFields.name) {
         specFields.name = `string | default="${name}"`;
     }
+    // Extract ?? defaults and add | default= annotations to the schema.
+    // KRO uses these when a field isn't provided in the CR instance.
+    //
+    // Phase 1: fn.toString() regex — extracts literal ?? fallbacks quickly,
+    //   for BOTH the outer composition AND every nested composition in the
+    //   tree. See the nested-composition branch below for why.
+    // Phase 2: Defaults resolution run — calls the composition function with
+    //   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;
+    // Phase 1a: regex extraction for the outer composition's own defaults.
+    if (typeof compositionFn === 'function') {
+        const regexDefaults = extractNullishDefaults(compositionFn.toString());
+        applyNullishDefaults(specFields, regexDefaults);
+        // Missing-field variant: also ADD any default path whose first
+        // segment exists in specFields but whose full path doesn't. Handles
+        // cases where the outer's own spec has `cache: { ... }` and reads
+        // `spec.cache?.foo ?? bar` — the user expects `cache.foo` to be
+        // optional with a default, but they forgot to declare it. We auto-
+        // declare it for them.
+        addMissingDefaultFields(specFields, regexDefaults);
+    }
+    // Phase 1b: regex extraction for every nested composition in the tree.
+    //
+    // When an inner composition uses `spec.X?.Y ?? <literal>` and the outer
+    // passes its own `spec.X` proxy through (i.e., `innerComp({ X: spec.X, ... })`),
+    // the inner's KRO-mode emission produces `${schema.spec.X.Y}` in the
+    // flattened resource templates. The OUTER schema typically doesn't
+    // declare Y — KRO rejects the RGD with "undefined field".
+    //
+    // We scan every nested composition's fn source for these `??` defaults
+    // and ADD the missing fields to the outer specFields with the literal
+    // as a KRO default. KRO then resolves the field using the default at
+    // apply time, matching what direct-mode JS does via the `??` operator.
+    //
+    // This is the framework-side counterpart to the user workaround of
+    // explicitly mirroring inner fields in the outer schema. It preserves
+    // the "composition looks like native TypeScript" design goal — users
+    // shouldn't have to repeat every inner schema detail.
+    // `__nestedCompositionFns` was stored via Reflect.set. Read it via
+    // getOwnPropertyDescriptor to bypass the Enhanced proxy's get-trap
+    // (same pattern as `__nestedStatusCel`). The descriptor's value is
+    // the real Map, not a proxy.
+    const ternaryConditionals = [];
+    const nestedFnsRaw = statusMappings
+        ? Object.getOwnPropertyDescriptor(statusMappings, '__nestedCompositionFns')?.value
+        : undefined;
+    const nestedSpecMappingsRaw = statusMappings
+        ? Object.getOwnPropertyDescriptor(statusMappings, '__nestedCompositionSpecMappings')?.value
+        : undefined;
+    const nestedDefinitionsRaw = statusMappings
+        ? Object.getOwnPropertyDescriptor(statusMappings, '__nestedCompositionDefinitions')?.value
+        : undefined;
+    const nestedResourcesRaw = statusMappings
+        ? Object.getOwnPropertyDescriptor(statusMappings, '__nestedCompositionResources')?.value
+        : undefined;
+    if (nestedFnsRaw instanceof Map) {
+        for (const [baseId, fn] of nestedFnsRaw) {
+            if (typeof fn !== 'function')
+                continue;
+            const specMappings = nestedSpecMappingsRaw instanceof Map
+                ? nestedSpecMappingsRaw.get(baseId)
+                : undefined;
+            if (!specMappings || typeof specMappings !== 'object')
+                continue;
+            const extractedDefaults = extractNullishDefaults(fn.toString());
+            const nestedDefinition = nestedDefinitionsRaw instanceof Map
+                ? nestedDefinitionsRaw.get(baseId)
+                : undefined;
+            const nestedResources = nestedResourcesRaw instanceof Map
+                ? nestedResourcesRaw.get(baseId)
+                : undefined;
+            const reExecutionResult = nestedDefinition && nestedResources
+                ? resolveDefaultsByReExecution(fn, nestedDefinition.spec, nestedResources)
+                : undefined;
+            const reExecutionDefaults = reExecutionResult?.defaults ?? {};
+            const innerDefaults = remapNullishDefaults({ ...extractedDefaults, ...reExecutionDefaults }, specMappings);
+            // Non-destructive: don't overwrite existing outer defaults.
+            applyNullishDefaults(specFields, innerDefaults, false);
+            // Also add any fields the outer doesn't declare — the inner's
+            // `?? <literal>` is the only signal we have that the field should
+            // exist with a default.
+            addMissingDefaultFields(specFields, innerDefaults);
+            ternaryConditionals.push(...remapTernaryConditionals(reExecutionResult?.ternaryConditionals ?? [], specMappings));
+        }
+    }
+    // Phase 2: resolve imported constants + detect ternary conditionals.
+    // Phase 2 is AUTHORITATIVE — if it produces a value for a field that
+    // Phase 1 also annotated, Phase 2 wins. This corrects Phase 1 misfires
+    // on edge cases (multi-line expressions, nested parens) without breaking
+    // the common case where both phases agree.
+    if (typeof compositionFn === 'function' && resources) {
+        const reExecutionResult = resolveDefaultsByReExecution(compositionFn, schemaDefinition.spec, resources);
+        if (reExecutionResult) {
+            applyNullishDefaults(specFields, reExecutionResult.defaults, true);
+            ternaryConditionals.push(...reExecutionResult.ternaryConditionals);
+        }
+    }
+    // Collect optional fields that DON'T have | default= after ?? extraction
+    // AND aren't already handled by ternary conditionals.
+    // These need omit() wrapping in resource templates (KRO 0.9+).
+    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)
     // that should never appear in the KRO schema.
@@ -125,25 +901,62 @@ export function arktypeToKroSchema(name, schemaDefinition, resources, statusMapp
     // Separate static and dynamic status fields.
     // Dynamic = references non-schema resource fields (status, metadata, spec) → KRO CEL
     // Static = references only schema.spec.* or literal values → TypeKro runtime hydration
-    const { dynamicFields } = separateStatusFields(userStatusMappings);
-    // Only serialize dynamic fields that need Kro resolution
-    // Build the set of known resource IDs for schema.spec → resource.spec mapping
+    // Classification is transitive through nestedStatusCel: a nested composition
+    // reference whose inner analyzed value is schema-only/literal is treated as static.
     const resourceIds = resources ? new Set(Object.keys(resources)) : undefined;
+    const resourceAliases = resources ? new Map() : undefined;
+    if (resources && resourceAliases) {
+        for (const [resourceId, resource] of Object.entries(resources)) {
+            resourceAliases.set(resourceId, resourceId);
+            for (const alias of deriveResourceIdAliases(resourceId)) {
+                if (!resourceAliases.has(alias)) {
+                    resourceAliases.set(alias, resourceId);
+                }
+            }
+            const aliases = getMetadataField(resource, 'resourceAliases');
+            if (aliases) {
+                for (const alias of aliases) {
+                    resourceAliases.set(alias, resourceId);
+                }
+            }
+        }
+    }
+    const { dynamicFields } = separateStatusFields(userStatusMappings, nestedStatusCel, resourceIds);
     const statusCelExpressions = Object.keys(dynamicFields).length > 0
-        ? serializeStatusMappingsToCel(dynamicFields, nestedStatusCel, resourceIds)
+        ? serializeStatusMappingsToCel(dynamicFields, nestedStatusCel, resourceIds, resourceAliases)
         : {};
     // Extract just the version part for the schema (Kro expects v1alpha1, not kro.run/v1alpha1)
     const schemaApiVersion = schemaDefinition.apiVersion.includes('/')
         ? schemaDefinition.apiVersion.split('/')[1] || schemaDefinition.apiVersion
         : schemaDefinition.apiVersion;
-    return {
+    const schemaGroup = schemaDefinition.group ?? (schemaDefinition.apiVersion.includes('/')
+        ? schemaDefinition.apiVersion.split('/')[0]
+        : undefined);
+    const schema = {
         apiVersion: schemaApiVersion,
         kind: schemaDefinition.kind,
+        ...(schemaGroup && { group: schemaGroup }),
         spec: specFields,
         status: {
             ...statusCelExpressions,
         },
     };
+    // Attach metadata as non-enumerable properties — they're typed on
+    // KroSimpleSchemaWithMetadata so consumers can read them without casts,
+    // but non-enumerable so they don't appear in the schema YAML.
+    if (ternaryConditionals.length > 0) {
+        Object.defineProperty(schema, '__ternaryConditionals', {
+            value: ternaryConditionals,
+            enumerable: false,
+        });
+    }
+    if (omitFields.length > 0) {
+        Object.defineProperty(schema, '__omitFields', {
+            value: omitFields,
+            enumerable: false,
+        });
+    }
+    return schema;
 }
 /**
  * Generate a minimal Kro schema from a resource map (no Arktype).