@kernlang/core 3.3.4 → 3.3.6

package/dist/codegen/ground-layer.js

@@ -29,6 +29,38 @@ export function generateDerive(node) {
     const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
     return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = ${expr};`];
 }
+// ── Ground Layer: fmt ────────────────────────────────────────────────────
+// `fmt name=label template="${count} files"` →
+//   const label = `${count} files`;
+//
+// Why a dedicated node: string interpolation is ~15-20% of handler-block
+// volume in agon (2026-04-20 scan). Expressing it as a named primitive keeps
+// the IR declarative and lets tooling (reviewers, decompiler, codegen)
+// recognise "this is a formatted string" without parsing a handler body.
+//
+// The template body is spliced verbatim into a JS template literal, so
+// `${expr}` placeholders work exactly as in JS. Raw backticks in the author
+// input are escaped to `\`` so the emitted template literal cannot be closed
+// accidentally — `${...}` is the contract, arbitrary JS injection is not.
+export function generateFmt(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'formatted', node);
+    const template = props.template;
+    if (template === undefined || template === null) {
+        throw new KernCodegenError("fmt node requires a 'template' prop", node);
+    }
+    const constType = props.type;
+    const exp = exportPrefix(node);
+    // Escape backticks so the emitted template literal can't be closed
+    // prematurely. `${...}` is intentionally passed through untouched — that's
+    // the whole reason fmt exists.
+    const escapedTemplate = String(template).replace(/\\/g, '\\\\').replace(/`/g, '\\`');
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = \`${escapedTemplate}\`;`];
+}
 // ── Ground Layer: transform ──────────────────────────────────────────────
 export function generateTransform(node) {
     const annotations = emitReasonAnnotations(node);
@@ -292,6 +324,945 @@ export function generateExpect(node) {
     lines.push('}');
     return lines;
 }
+// ── Ground Layer: array methods ──────────────────────────────────────────
+// Declarative array-method primitives — each is its own named node type:
+//   filter / find / some / every / findIndex → predicate-over-collection
+//   map / flatMap                             → projection (arrow body)
+//   reduce                                    → accumulation (acc + item)
+//   sort                                      → optional compare function (immutable via spread)
+//   reverse / flat / slice / at               → shape-preserving or range ops
+//   join / includes / indexOf / lastIndexOf   → value-returning lookups
+//   concat                                    → array concatenation
+//   forEach                                   → side-effect loop (statement, no binding)
+//
+// Why distinct names instead of one generic: KERN is an LLM-authored
+// language. Giving each method a named structural anchor lets tooling
+// (decompiler, review, codegen) recognise author intent without grepping
+// a method name out of a string. The `where` / `expr` prop split mirrors
+// the semantic distinction: `where` = boolean predicate, `expr` = arrow
+// body returning a value. `each` remains the render-block JSX iteration
+// primitive; `map` is its expression-form sibling for data-transformation.
+/** Unwrap an `{ __expr: true, code }` shape or pass through a plain string. */
+function unwrapExpr(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw === 'object' && raw.__expr) {
+        return raw.code;
+    }
+    return typeof raw === 'string' ? raw : String(raw);
+}
+function generateArrayMethod(node, method) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, method, node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError(`${method} node requires an 'in' prop`, node);
+    const predicate = unwrapExpr(props.where);
+    if (!predicate)
+        throw new KernCodegenError(`${method} node requires a 'where' prop`, node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).${method}((${item}) => ${predicate});`,
+    ];
+}
+export function generateFilter(node) {
+    return generateArrayMethod(node, 'filter');
+}
+// ── Ground Layer: reduce ─────────────────────────────────────────────────
+// `reduce name=total in=items initial="0" expr="acc + item.value"`
+//   → const total = items.reduce((acc, item) => acc + item.value, 0);
+// Two bound names (acc, item) default to those identifiers; override with
+// `acc=` / `item=`. Body (`expr`) and seed (`initial`) are both required.
+export function generateReduce(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'reduced', node);
+    const acc = emitIdentifier(props.acc || 'acc', 'acc', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("reduce node requires an 'in' prop", node);
+    const initial = unwrapExpr(props.initial);
+    if (!initial)
+        throw new KernCodegenError("reduce node requires an 'initial' prop", node);
+    const body = unwrapExpr(props.expr);
+    if (!body)
+        throw new KernCodegenError("reduce node requires an 'expr' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).reduce((${acc}, ${item}) => ${body}, ${initial});`,
+    ];
+}
+// ── Ground Layer: flatMap ────────────────────────────────────────────────
+// `flatMap name=tags in=posts expr="item.tags"`
+//   → const tags = posts.flatMap((item) => item.tags);
+// `expr` is the arrow body (array/iterable), not a predicate. Use the same
+// shape as `filter` etc., but with `expr` instead of `where`.
+export function generateFlatMap(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'flatMapped', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("flatMap node requires an 'in' prop", node);
+    const body = unwrapExpr(props.expr);
+    if (!body)
+        throw new KernCodegenError("flatMap node requires an 'expr' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).flatMap((${item}) => ${body});`,
+    ];
+}
+// ── Ground Layer: slice ──────────────────────────────────────────────────
+// `slice name=first5 in=items start=0 end=5`
+//   → const first5 = items.slice(0, 5);
+// Both indices are optional — `.slice()` with no args copies the whole
+// array, `.slice(2)` copies from index 2 onward. Emit exactly what was
+// supplied, in that order.
+export function generateSlice(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'sliced', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("slice node requires an 'in' prop", node);
+    const start = unwrapExpr(props.start);
+    const end = unwrapExpr(props.end);
+    const args = [];
+    if (start !== undefined)
+        args.push(start);
+    if (end !== undefined) {
+        if (start === undefined)
+            args.push('0');
+        args.push(end);
+    }
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).slice(${args.join(', ')});`];
+}
+export function generateFind(node) {
+    return generateArrayMethod(node, 'find');
+}
+export function generateSome(node) {
+    return generateArrayMethod(node, 'some');
+}
+export function generateEvery(node) {
+    return generateArrayMethod(node, 'every');
+}
+// ── Ground Layer: map ────────────────────────────────────────────────────
+// `map name=names in=users expr="item.name"`
+//   → const names = (users).map((item) => item.name);
+// Sibling to `each` (JSX form). Shape mirrors flatMap exactly — expr is the
+// arrow body, not a predicate.
+export function generateMap(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'mapped', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("map node requires an 'in' prop", node);
+    const body = unwrapExpr(props.expr);
+    if (!body)
+        throw new KernCodegenError("map node requires an 'expr' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).map((${item}) => ${body});`];
+}
+// ── Ground Layer: findIndex ──────────────────────────────────────────────
+// `findIndex name=i in=users where="item.active"`
+//   → const i = (users).findIndex((item) => item.active);
+// Predicate-shaped like find, but returns a number. Defaults the binding
+// type suggestion to `number` in comments; author-supplied `type=` wins.
+export function generateFindIndex(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'index', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("findIndex node requires an 'in' prop", node);
+    const predicate = unwrapExpr(props.where);
+    if (!predicate)
+        throw new KernCodegenError("findIndex node requires a 'where' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).findIndex((${item}) => ${predicate});`,
+    ];
+}
+// ── Ground Layer: sort ───────────────────────────────────────────────────
+// `sort name=sorted in=items compare="a.age - b.age"`
+//   → const sorted = [...(items)].sort((a, b) => a.age - b.age);
+// With no `compare`, emits `[...(items)].sort()` — JS lexicographic default.
+// Immutable via spread so the source collection is not mutated.
+export function generateSort(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'sorted', node);
+    const a = emitIdentifier(props.a || 'a', 'a', node);
+    const b = emitIdentifier(props.b || 'b', 'b', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("sort node requires an 'in' prop", node);
+    const compare = unwrapExpr(props.compare);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    const call = compare ? `sort((${a}, ${b}) => ${compare})` : 'sort()';
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = [...(${collection})].${call};`];
+}
+// ── Ground Layer: reverse ────────────────────────────────────────────────
+// `reverse name=reversed in=items` → const reversed = [...(items)].reverse();
+// Immutable via spread; matches sort's shape for consistency.
+export function generateReverse(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'reversed', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("reverse node requires an 'in' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = [...(${collection})].reverse();`];
+}
+// ── Ground Layer: flat ───────────────────────────────────────────────────
+// `flat name=flattened in=nested depth=2` → const flattened = (nested).flat(2);
+// `depth` omitted → bare `.flat()` (default depth 1).
+export function generateFlat(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'flattened', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("flat node requires an 'in' prop", node);
+    const depth = unwrapExpr(props.depth);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    const call = depth !== undefined ? `flat(${depth})` : 'flat()';
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).${call};`];
+}
+// ── Ground Layer: at ─────────────────────────────────────────────────────
+// `at name=first in=items index=0` → const first = (items).at(0);
+export function generateAt(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'element', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("at node requires an 'in' prop", node);
+    const index = unwrapExpr(props.index);
+    if (index === undefined)
+        throw new KernCodegenError("at node requires an 'index' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).at(${index});`];
+}
+// ── Ground Layer: join ───────────────────────────────────────────────────
+// `join name=csv in=fields separator=","` → const csv = (fields).join(',');
+// `separator` omitted → bare `.join()` (default "," per JS).
+// The separator is emitted as a quoted string literal when plain, or as a
+// raw expression when wrapped as `{{ expr }}`.
+export function generateJoin(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'joined', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("join node requires an 'in' prop", node);
+    const sepRaw = props.separator;
+    let sepArg = '';
+    if (sepRaw !== undefined && sepRaw !== null) {
+        if (typeof sepRaw === 'object' && sepRaw.__expr) {
+            sepArg = sepRaw.code;
+        }
+        else {
+            const s = String(sepRaw);
+            sepArg = `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+        }
+    }
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).join(${sepArg});`];
+}
+// ── Ground Layer: includes / indexOf / lastIndexOf ───────────────────────
+// All three share shape: `<method> name=X in=Y value="..." [from=N]`.
+// `value` is always a raw expression (no implicit quoting — authors write
+// `value="'fatal'"` for a string literal, `value=target` for a variable).
+function generateValueLookup(node, method) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const fallback = method === 'includes' ? 'has' : 'idx';
+    const name = emitIdentifier(props.name, fallback, node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError(`${method} node requires an 'in' prop`, node);
+    const value = unwrapExpr(props.value);
+    if (value === undefined)
+        throw new KernCodegenError(`${method} node requires a 'value' prop`, node);
+    const from = unwrapExpr(props.from);
+    const args = from !== undefined ? `${value}, ${from}` : value;
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).${method}(${args});`];
+}
+export function generateIncludes(node) {
+    return generateValueLookup(node, 'includes');
+}
+export function generateIndexOf(node) {
+    return generateValueLookup(node, 'indexOf');
+}
+export function generateLastIndexOf(node) {
+    return generateValueLookup(node, 'lastIndexOf');
+}
+// ── Ground Layer: concat ─────────────────────────────────────────────────
+// `concat name=all in=items with="a, b"` → const all = (items).concat(a, b);
+// `with` is a raw expression injected directly — supports one arg or
+// comma-separated spread. For a single array arg, write `with="other"`.
+export function generateConcat(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'combined', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("concat node requires an 'in' prop", node);
+    const withArg = unwrapExpr(props.with);
+    if (!withArg)
+        throw new KernCodegenError("concat node requires a 'with' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).concat(${withArg});`];
+}
+// ── Ground Layer: forEach ────────────────────────────────────────────────
+// Statement primitive — no `name`, no `const` binding. Takes a handler child
+// and emits `(in).forEach((item[, index]) => { handlerBody });`.
+// Distinct from `each` (JSX composition) and `map` (value binding).
+export function generateForEach(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const indexName = props.index ? emitIdentifier(props.index, 'index', node) : undefined;
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("forEach node requires an 'in' prop", node);
+    const handler = firstChild(node, 'handler');
+    if (!handler) {
+        throw new KernCodegenError('forEach node requires a `handler <<<>>>` child with the loop body', node);
+    }
+    const body = handlerCode(node);
+    const params = indexName ? `(${item}, ${indexName})` : `(${item})`;
+    const lines = [...todo, ...annotations];
+    lines.push(`(${collection}).forEach(${params} => {`);
+    for (const line of body.split('\n'))
+        lines.push(`  ${line}`);
+    lines.push('});');
+    return lines;
+}
+// ── Ground Layer: compact ────────────────────────────────────────────────
+// `compact name=truthy in=items` → `const truthy = (items).filter(Boolean);`
+// Lodash-style named primitive for the very common `.filter(Boolean)` pattern.
+// Agon scan: 36 call sites. Zero runtime cost vs the raw form; pure naming win.
+export function generateCompact(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'compacted', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("compact node requires an 'in' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).filter(Boolean);`];
+}
+// ── Ground Layer: pluck ──────────────────────────────────────────────────
+// `pluck name=names in=users prop=name`
+//   → const names = (users).map((item) => item.name);
+// `prop` is a raw identifier path — `prop=user.profile.name` emits
+// `item.user.profile.name`. Distinct from `map` because the author's intent is
+// just "lift one field out of each item" and the shape is fixed.
+export function generatePluck(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'plucked', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("pluck node requires an 'in' prop", node);
+    const prop = unwrapExpr(props.prop);
+    if (!prop)
+        throw new KernCodegenError("pluck node requires a 'prop' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).map((${item}) => ${item}.${prop});`,
+    ];
+}
+// ── Ground Layer: unique ─────────────────────────────────────────────────
+// `unique name=distinct in=items` → `const distinct = [...new Set(items)];`
+// Deduplicates by JS `Set` identity (triple-equals on primitives, reference
+// equality on objects). For object arrays with a key selector, use
+// `uniqueBy` (ships in the arrays-complete-pt2 PR).
+export function generateUnique(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'distinct', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("unique node requires an 'in' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = [...new Set(${collection})];`];
+}
+// ── Ground Layer: uniqueBy ───────────────────────────────────────────────
+// `uniqueBy name=distinct in=users by="item.id"`
+//   → const distinct = [...new Map((users).map((item) => [item.id, item])).values()];
+export function generateUniqueBy(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'distinct', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("uniqueBy node requires an 'in' prop", node);
+    const by = unwrapExpr(props.by);
+    if (!by)
+        throw new KernCodegenError("uniqueBy node requires a 'by' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    // First-wins semantics to match Lodash `uniqBy`. Uses Set+filter rather
+    // than Map-constructor (which would keep the last occurrence).
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__seen) => (${collection}).filter((${item}) => {`,
+        `  const __k = ${by};`,
+        `  if (__seen.has(__k)) return false;`,
+        `  __seen.add(__k);`,
+        `  return true;`,
+        `}))(new Set());`,
+    ];
+}
+// ── Ground Layer: groupBy ────────────────────────────────────────────────
+// `groupBy name=byType in=items by="item.type"`
+//   → const byType = Object.groupBy(items, (item) => item.type);
+// ES2024 Object.groupBy. Returns `Partial<Record<K, T[]>>`.
+export function generateGroupBy(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'grouped', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("groupBy node requires an 'in' prop", node);
+    const by = unwrapExpr(props.by);
+    if (!by)
+        throw new KernCodegenError("groupBy node requires a 'by' prop", node);
+    const constType = props.type || 'Record<string, unknown[]>';
+    const typeAnn = emitTypeAnnotation(constType, 'Record<string, unknown[]>', node);
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}: ${typeAnn} = (${collection}).reduce((acc, ${item}) => {`,
+        `  const __k = ${by};`,
+        `  (acc[__k] ??= []).push(${item});`,
+        `  return acc;`,
+        `}, Object.create(null) as ${typeAnn});`,
+    ];
+}
+// ── Ground Layer: partition ──────────────────────────────────────────────
+// Two-output primitive: emits a destructured const. Dual-filter shape for
+// clarity (two passes but readable).
+export function generatePartition(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const passName = emitIdentifier(props.pass, 'pass', node);
+    const failName = emitIdentifier(props.fail, 'fail', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("partition node requires an 'in' prop", node);
+    const predicate = unwrapExpr(props.where);
+    if (!predicate)
+        throw new KernCodegenError("partition node requires a 'where' prop", node);
+    const constType = props.type;
+    const elemType = constType ? emitTypeAnnotation(constType, 'unknown', node) : 'unknown';
+    const typeAnnotation = constType ? `: [${elemType}[], ${elemType}[]]` : '';
+    const exp = exportPrefix(node);
+    // Single-pass reduce so the collection and predicate each evaluate once
+    // per item — avoids double side effects from the dual-filter shape.
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const [${passName}, ${failName}]${typeAnnotation} = (${collection}).reduce<[${elemType}[], ${elemType}[]]>((acc, ${item}) => {`,
+        `  (${predicate} ? acc[0] : acc[1]).push(${item});`,
+        `  return acc;`,
+        `}, [[], []]);`,
+    ];
+}
+// ── Ground Layer: indexBy ────────────────────────────────────────────────
+// `indexBy name=byId in=users by="item.id"`
+//   → const byId = Object.fromEntries((users).map((item) => [item.id, item]));
+export function generateIndexBy(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'indexed', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("indexBy node requires an 'in' prop", node);
+    const by = unwrapExpr(props.by);
+    if (!by)
+        throw new KernCodegenError("indexBy node requires a 'by' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = Object.fromEntries((${collection}).map((${item}) => [${by}, ${item}]));`,
+    ];
+}
+// ── Ground Layer: countBy ────────────────────────────────────────────────
+// Multi-line reduce — `Record<string, number>` default type.
+export function generateCountBy(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'counts', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("countBy node requires an 'in' prop", node);
+    const by = unwrapExpr(props.by);
+    if (!by)
+        throw new KernCodegenError("countBy node requires a 'by' prop", node);
+    const constType = props.type || 'Record<string, number>';
+    const typeAnn = emitTypeAnnotation(constType, 'Record<string, number>', node);
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}: ${typeAnn} = (${collection}).reduce((acc, ${item}) => {`,
+        `  const __k = ${by};`,
+        `  acc[__k] = (acc[__k] ?? 0) + 1;`,
+        `  return acc;`,
+        `}, Object.create(null) as ${typeAnn});`,
+    ];
+}
+// ── Ground Layer: chunk ──────────────────────────────────────────────────
+// Fixed-size splitting.
+export function generateChunk(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'chunks', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("chunk node requires an 'in' prop", node);
+    const size = unwrapExpr(props.size);
+    if (!size)
+        throw new KernCodegenError("chunk node requires a 'size' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    // IIFE so the collection and size expressions are evaluated once each —
+    // important if either is expensive or has side effects.
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__src, __n) => Array.from({ length: Math.ceil(__src.length / __n) }, (_, i) => __src.slice(i * __n, (i + 1) * __n)))((${collection}), (${size}));`,
+    ];
+}
+// ── Ground Layer: zip ────────────────────────────────────────────────────
+export function generateZip(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'pairs', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const indexName = emitIdentifier(props.index || '__i', '__i', node);
+    const left = unwrapExpr(props.in);
+    if (!left)
+        throw new KernCodegenError("zip node requires an 'in' prop", node);
+    const right = unwrapExpr(props.with);
+    if (!right)
+        throw new KernCodegenError("zip node requires a 'with' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    // Bind the right collection once via IIFE — without this, `with=getOther()`
+    // would call getOther() once per element inside the map callback.
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__r) => (${left}).map((${item}, ${indexName}) => [${item}, __r[${indexName}]]))((${right}));`,
+    ];
+}
+// ── Ground Layer: range ──────────────────────────────────────────────────
+export function generateRange(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'range', node);
+    const end = unwrapExpr(props.end);
+    if (!end)
+        throw new KernCodegenError("range node requires an 'end' prop", node);
+    const start = unwrapExpr(props.start) ?? '0';
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'number[]', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = Array.from({ length: (${end}) - (${start}) }, (_, i) => i + (${start}));`,
+    ];
+}
+// ── Ground Layer: take / drop ────────────────────────────────────────────
+function generateTakeOrDrop(node, which) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const fallback = which === 'take' ? 'taken' : 'dropped';
+    const name = emitIdentifier(props.name, fallback, node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError(`${which} node requires an 'in' prop`, node);
+    const n = unwrapExpr(props.n);
+    if (!n)
+        throw new KernCodegenError(`${which} node requires an 'n' prop`, node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    const call = which === 'take' ? `slice(0, ${n})` : `slice(${n})`;
+    return [...todo, ...annotations, `${exp}const ${name}${typeAnnotation} = (${collection}).${call};`];
+}
+export function generateTake(node) {
+    return generateTakeOrDrop(node, 'take');
+}
+export function generateDrop(node) {
+    return generateTakeOrDrop(node, 'drop');
+}
+// ── Ground Layer: min / max ──────────────────────────────────────────────
+// Reduce-based (not `Math.min(...arr)` / `Math.max(...arr)`) to avoid:
+//   1. Stack overflow on huge arrays (spread blows the arg count limit).
+//   2. `Math.min()` returning `Infinity` and `Math.max()` returning
+//      `-Infinity` on empty arrays — we return `undefined` instead.
+function generateMathAgg(node, which) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const fallback = which === 'min' ? 'lowest' : 'highest';
+    const name = emitIdentifier(props.name, fallback, node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError(`${which} node requires an 'in' prop`, node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'number', node)} | undefined` : '';
+    const exp = exportPrefix(node);
+    const op = which === 'min' ? '<' : '>';
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__src) => __src.length === 0 ? undefined : __src.reduce((__a: number, __b: number) => __b ${op} __a ? __b : __a))((${collection}));`,
+    ];
+}
+export function generateMin(node) {
+    return generateMathAgg(node, 'min');
+}
+export function generateMax(node) {
+    return generateMathAgg(node, 'max');
+}
+// ── Ground Layer: minBy / maxBy ──────────────────────────────────────────
+// Emits a closure `__key = (item) => by` so the author's `by` expression is
+// evaluated as an arrow body — no fragile regex over the raw expression
+// text that would corrupt string literals like `by="item.tags.includes('item')"`.
+// The collection is bound once, so expensive or side-effecting `in=` only
+// runs one time. Returns `undefined` for empty collections.
+function generateByReducer(node, which) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const fallback = which === 'min' ? 'youngest' : 'oldest';
+    const name = emitIdentifier(props.name, fallback, node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError(`${which}By node requires an 'in' prop`, node);
+    const by = unwrapExpr(props.by);
+    if (!by)
+        throw new KernCodegenError(`${which}By node requires a 'by' prop`, node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)} | undefined` : '';
+    const exp = exportPrefix(node);
+    const op = which === 'min' ? '<' : '>';
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__src) => {`,
+        `  if (__src.length === 0) return undefined;`,
+        `  const __key = (${item}: typeof __src[number]) => ${by};`,
+        `  return __src.reduce((__best, __cur) => __key(__cur) ${op} __key(__best) ? __cur : __best);`,
+        `})((${collection}));`,
+    ];
+}
+export function generateMinBy(node) {
+    return generateByReducer(node, 'min');
+}
+export function generateMaxBy(node) {
+    return generateByReducer(node, 'max');
+}
+// ── Ground Layer: sum / avg / sumBy ──────────────────────────────────────
+export function generateSum(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'total', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("sum node requires an 'in' prop", node);
+    const constType = props.type || 'number';
+    const typeAnnotation = `: ${emitTypeAnnotation(constType, 'number', node)}`;
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).reduce((acc, n) => acc + n, 0);`,
+    ];
+}
+export function generateAvg(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'mean', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("avg node requires an 'in' prop", node);
+    const constType = props.type || 'number';
+    const typeAnnotation = `: ${emitTypeAnnotation(constType, 'number', node)}`;
+    const exp = exportPrefix(node);
+    // Returns `NaN` on empty input (matches Lodash `_.mean([])` and math
+    // convention — "no data" signal rather than a fake 0). Bound via IIFE so
+    // the `in=` expression is evaluated exactly once.
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__src) => __src.length === 0 ? Number.NaN : __src.reduce((acc, n) => acc + n, 0) / __src.length)((${collection}));`,
+    ];
+}
+export function generateSumBy(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'total', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError("sumBy node requires an 'in' prop", node);
+    const by = unwrapExpr(props.by);
+    if (!by)
+        throw new KernCodegenError("sumBy node requires a 'by' prop", node);
+    const constType = props.type || 'number';
+    const typeAnnotation = `: ${emitTypeAnnotation(constType, 'number', node)}`;
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).reduce((acc, ${item}) => acc + (${by}), 0);`,
+    ];
+}
+// ── Ground Layer: intersect ──────────────────────────────────────────────
+// Uses `new Set(right)` for O(N+M) lookup instead of the naive O(N×M)
+// `.filter(...includes...)` pair. The right collection is bound once so
+// expensive `with=` expressions don't re-run per element.
+export function generateIntersect(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'shared', node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const left = unwrapExpr(props.in);
+    if (!left)
+        throw new KernCodegenError("intersect node requires an 'in' prop", node);
+    const right = unwrapExpr(props.with);
+    if (!right)
+        throw new KernCodegenError("intersect node requires a 'with' prop", node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = ((__r) => (${left}).filter((${item}) => __r.has(${item})))(new Set((${right})));`,
+    ];
+}
+// ── Ground Layer: findLast / findLastIndex (ES2023) ──────────────────────
+function generateFindLastPair(node, which) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const fallback = which === 'findLast' ? 'lastMatch' : 'lastIndex';
+    const name = emitIdentifier(props.name, fallback, node);
+    const item = emitIdentifier(props.item || 'item', 'item', node);
+    const collection = unwrapExpr(props.in);
+    if (!collection)
+        throw new KernCodegenError(`${which} node requires an 'in' prop`, node);
+    const predicate = unwrapExpr(props.where);
+    if (!predicate)
+        throw new KernCodegenError(`${which} node requires a 'where' prop`, node);
+    const constType = props.type;
+    const typeAnnotation = constType ? `: ${emitTypeAnnotation(constType, 'unknown', node)}` : '';
+    const exp = exportPrefix(node);
+    return [
+        ...todo,
+        ...annotations,
+        `${exp}const ${name}${typeAnnotation} = (${collection}).${which}((${item}) => ${predicate});`,
+    ];
+}
+export function generateFindLast(node) {
+    return generateFindLastPair(node, 'findLast');
+}
+export function generateFindLastIndex(node) {
+    return generateFindLastPair(node, 'findLastIndex');
+}
+// ── Ground Layer: async ──────────────────────────────────────────────────
+// `async name=loadUser` with a `handler` child runs its body inside an IIFE.
+// With an optional trailing `recover` child, delegates recovery to the
+// existing `recover`/`strategy` machinery (see `generateRecover` below) —
+// the emitted `<name>WithRecovery<T>` wrapper is invoked with the body as
+// its Promise-returning `fn`.
+//
+// Design: the `async` primitive reuses existing recover/strategy semantics
+// rather than inventing a new error-handling path. `derive` and `set` are
+// intentionally NOT made awaitable — their identity as direct bindings /
+// state updates stays pure.
+export function generateAsync(node) {
+    const annotations = emitReasonAnnotations(node);
+    const props = propsOf(node);
+    const conf = props.confidence;
+    const todo = emitLowConfidenceTodo(node, conf);
+    const name = emitIdentifier(props.name, 'asyncBlock', node);
+    const handler = firstChild(node, 'handler');
+    if (!handler) {
+        throw new KernCodegenError('async block requires a `handler <<<>>>` child with the body', node);
+    }
+    // handlerCode() takes the PARENT that has a handler child — pass `node`, not `handler`.
+    const body = handlerCode(node);
+    const recover = firstChild(node, 'recover');
+    const lines = [...todo, ...annotations];
+    if (!recover) {
+        // Bare IIFE — fire-and-forget. Parent context decides whether to await it.
+        lines.push(`(async () => {`);
+        if (body) {
+            for (const line of body.split('\n')) {
+                lines.push(`  ${line}`);
+            }
+        }
+        lines.push(`})();`);
+        return lines;
+    }
+    // With recovery: emit the reusable wrapper, then invoke it. The recover
+    // node inherits the async block's name so generateRecover emits
+    // `<name>WithRecovery<T>(...)` — one symbol that ties the two together.
+    const namedRecover = {
+        ...recover,
+        props: { ...(recover.props || {}), name },
+    };
+    lines.push(...generateRecover(namedRecover));
+    lines.push(`${name}WithRecovery(async () => {`);
+    if (body) {
+        for (const line of body.split('\n')) {
+            lines.push(`  ${line}`);
+        }
+    }
+    lines.push(`});`);
+    return lines;
+}
 // ── Ground Layer: recover / strategy ─────────────────────────────────────
 export function generateRecover(node) {
     const annotations = emitReasonAnnotations(node);