@kernlang/core 3.4.4 → 3.4.5-canary.15.1.9efc3d4b

package/dist/parser-validate-body-statements.js

@@ -1,13 +1,15 @@
 /** @internal Native KERN body-statement context validator — slice 5b-pre.
  *
- *  Body-statement nodes (`return`, `throw`, `do`, body-form `if`/`else`,
- *  body-form `try`) are valid only inside a `handler lang="kern"` scope
- *  (or nested inside another body-statement under such a handler). Without
- *  this rule, the parser silently accepts orphan `return`/`throw` lines
- *  that then crash codegen with confusing errors deep in the body emitter.
+ *  Body-statement nodes (`return`, `throw`, `do`, `continue`, `break`,
+ *  body-form `if`/`else`, body-form `try`) are valid only inside a
+ *  `handler lang="kern"` scope (or nested inside another body-statement
+ *  under such a handler). Without this rule, the parser silently accepts
+ *  orphan `return`/`throw` lines that then crash codegen with confusing
+ *  errors deep in the body emitter.
  *
  *  Rules:
- *    - `return`, `throw`, and `do` are rejected outside a native-body scope.
+ *    - `return`, `throw`, `do`, `continue`, `break` are rejected outside
+ *      a native-body scope.
  *    - `if` with a `cond` prop is body-statement form (vs `conditional`'s
  *      `if=` prop); rejected outside native-body scope.
  *    - `else` whose parent is not `conditional` is body-statement form
@@ -51,6 +53,8 @@ function isBodyStatementMisplaced(node, ctx) {
         case 'return':
         case 'throw':
         case 'do':
+        case 'continue':
+        case 'break':
             return true;
         case 'if':
             // Body-statement `if` carries a `cond` prop. `conditional` and route-

package/dist/parser-validate-body-statements.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser-validate-body-statements.js","sourceRoot":"","sources":["../src/parser-validate-body-statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAmB,MAAM,yBAAyB,CAAC;AAU1E,MAAM,QAAQ,GAAgB,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAExE,MAAM,UAAU,sBAAsB,CAAC,KAAiB,EAAE,IAAY;IACpE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,IAAI,CAAC,KAAiB,EAAE,IAAY,EAAE,GAAgB;IAC7D,IAAI,wBAAwB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QACvD,cAAc,CACZ,KAAK,EACL,uCAAuC,EACvC,OAAO,EACP,KAAK,IAAI,CAAC,IAAI,sJAAsJ,EACpK,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,GAAG,EACP,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,EAAE,CACtC,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAgB;QAC5B,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,mBAAmB,CAAC,IAAI,CAAC;QAC3D,UAAU,EAAE,IAAI,CAAC,IAAI;KACtB,CAAC;IACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,MAAM,CAAC;AAChE,CAAC;AAED,SAAS,wBAAwB,CAAC,IAAY,EAAE,GAAgB;IAC9D,IAAI,GAAG,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAEnC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,IAAI;YACP,OAAO,IAAI,CAAC;QACd,KAAK,IAAI;YACP,sEAAsE;YACtE,mEAAmE;YACnE,kEAAkE;YAClE,kBAAkB;YAClB,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,SAAS,CAAC;QACxC,KAAK,MAAM;YACT,oEAAoE;YACpE,kEAAkE;YAClE,wBAAwB;YACxB,OAAO,GAAG,CAAC,UAAU,KAAK,aAAa,CAAC;QAC1C,KAAK,KAAK;YACR,kEAAkE;YAClE,gEAAgE;YAChE,+DAA+D;YAC/D,4DAA4D;YAC5D,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,SAAS,CAAC;QACxC;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}
+{"version":3,"file":"parser-validate-body-statements.js","sourceRoot":"","sources":["../src/parser-validate-body-statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,cAAc,EAAmB,MAAM,yBAAyB,CAAC;AAU1E,MAAM,QAAQ,GAAgB,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAExE,MAAM,UAAU,sBAAsB,CAAC,KAAiB,EAAE,IAAY;IACpE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,IAAI,CAAC,KAAiB,EAAE,IAAY,EAAE,GAAgB;IAC7D,IAAI,wBAAwB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QACvD,cAAc,CACZ,KAAK,EACL,uCAAuC,EACvC,OAAO,EACP,KAAK,IAAI,CAAC,IAAI,sJAAsJ,EACpK,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,GAAG,EACP,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,EAAE,CACtC,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAgB;QAC5B,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,mBAAmB,CAAC,IAAI,CAAC;QAC3D,UAAU,EAAE,IAAI,CAAC,IAAI;KACtB,CAAC;IACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,MAAM,CAAC;AAChE,CAAC;AAED,SAAS,wBAAwB,CAAC,IAAY,EAAE,GAAgB;IAC9D,IAAI,GAAG,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAEnC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,IAAI,CAAC;QACV,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,IAAI,CAAC;QACd,KAAK,IAAI;YACP,sEAAsE;YACtE,mEAAmE;YACnE,kEAAkE;YAClE,kBAAkB;YAClB,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,SAAS,CAAC;QACxC,KAAK,MAAM;YACT,oEAAoE;YACpE,kEAAkE;YAClE,wBAAwB;YACxB,OAAO,GAAG,CAAC,UAAU,KAAK,aAAa,CAAC;QAC1C,KAAK,KAAK;YACR,kEAAkE;YAClE,gEAAgE;YAChE,+DAA+D;YAC/D,4DAA4D;YAC5D,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,SAAS,CAAC;QACxC;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/schema.js

@@ -482,7 +482,22 @@ export const NODE_SCHEMAS = {
         //    plus a required `catch` child. Schema permits both child sets;
         //    body-ts.ts disambiguates by inspecting the children, and validateBodyStatements
         //    enforces the body-statement-only constraints when the enclosing handler is `lang="kern"`.
-        allowedChildren: ['step', 'handler', 'catch', 'let', 'do', 'return', 'if', 'else', 'each', 'try', 'throw'],
+        allowedChildren: [
+            'step',
+            'handler',
+            'catch',
+            'let',
+            'do',
+            'return',
+            'if',
+            'else',
+            'each',
+            'try',
+            'throw',
+            'continue',
+            'break',
+            'branch',
+        ],
     },
     step: {
         description: 'Sequential awaited step inside a `try` block — `step name=X await="expr"` emits `const X = await (expr);` in order with its siblings. Must be a direct child of `try`. Earlier step names are in scope for later ones.',
@@ -499,7 +514,20 @@ export const NODE_SCHEMAS = {
         props: {
             name: { kind: 'identifier' },
         },
-        allowedChildren: ['handler', 'let', 'do', 'return', 'if', 'else', 'each', 'try', 'throw'],
+        allowedChildren: [
+            'handler',
+            'let',
+            'do',
+            'return',
+            'if',
+            'else',
+            'each',
+            'try',
+            'throw',
+            'continue',
+            'break',
+            'branch',
+        ],
     },
     filter: {
         description: 'Declarative `.filter` binding — `filter name=active in=items where="item.active"` lowers to `const active = items.filter(item => item.active);`. Use `item=x` to rename the per-item binding.',
@@ -1080,13 +1108,21 @@ export const NODE_SCHEMAS = {
         },
     },
     each: {
-        description: 'Iteration — renders children for each item in a collection. Inside a render block emits `items.map(...)` with auto-key; elsewhere emits `for...of`. `let` children become iteration-scoped `const` bindings inside the callback (hook-safe, unlike `derive`).',
+        description: 'Iteration — renders children for each item in a collection. Inside a render block emits `items.map(...)` with auto-key; elsewhere emits `for...of`. `let` children become iteration-scoped `const` bindings inside the callback (hook-safe, unlike `derive`). Three forms in body-statement position: (1) `each name=x in=xs` → `for (const x of xs)`; (2) `each name=x index=i in=xs` → `for (const [i, x] of xs.entries())`; (3) `each pairKey=k pairValue=v in=map` → `for (const [k, v] of map)` (TS) / `for k, v in map.items():` (Python). In pair-mode `name` is optional. `key=` (render-only) is the React render key, distinct from `pairKey=`.',
         example: 'each name=f in=files index=i key="f.path"\n  let name=isSel expr="focused && i === selIdx"\n  handler <<<\n    <Text bold={isSel}>{f.path}</Text>\n  >>>',
         props: {
+            // `name` is required schema-side for the array-iteration forms; the
+            // pair-mode (`pairKey` + `pairValue`) form relaxes this via a
+            // conditional-required exemption inside `checkRequiredProps` in this
+            // same file. (The `each-pair-mode-body-stmt-only` semantic rule in
+            // semantic-validator.ts is unrelated — it just blocks pair-mode in
+            // render/group ancestor scope.)
             name: { required: true, kind: 'identifier' },
             in: { required: true, kind: 'rawExpr' },
             index: { kind: 'identifier' },
             key: { kind: 'rawExpr' },
+            pairKey: { kind: 'identifier' },
+            pairValue: { kind: 'identifier' },
         },
         // Intentionally unrestricted — statement-form `each` composes with `derive`,
         // `transform`, etc. in fn/handler contexts. The `let` node is constrained
@@ -1124,9 +1160,11 @@ export const NODE_SCHEMAS = {
         },
     },
     branch: {
-        description: 'Pattern-match/switch on an expression — contains path children',
-        example: 'branch name=route on=path\n  path value="/home"\n  path value="/about"',
+        description: 'Pattern-match/switch on an expression — contains `path` children. Top-level form (statement context) emits TS `switch` with `case` blocks. Body-statement form (child of `handler lang="kern"` / `try` / `catch`) emits the same TS `switch` plus a Python `if/elif/else` chain on the fastapi target. Each `path value=X` is a case; `path default=true` is the trailing default case (parallels JS `switch`/`default`). Identifier values like `path value=Status.Active` (unquoted) emit raw refs; quoted strings emit JSON-quoted literals.',
+        example: 'branch name=route on=path\n  path value="/home"\n  path value="/about"\n  path default=true',
         props: {
+            // `name` is required for the top-level branch shape; body-statement
+            // branches inherit the same shape for diagnostic clarity.
             name: { required: true, kind: 'identifier' },
             on: { required: true, kind: 'rawExpr' },
         },
@@ -1338,7 +1376,7 @@ export const NODE_SCHEMAS = {
     },
     // ── Cross-target nodes ────────────────────────────────────────────────
     handler: {
-        description: 'Code block — the body of a function, method, route, tool, or event handler. Use <<<...>>> for raw multiline code, or `lang="kern"` with body-statement children (`let`/`do`/`return`/`if`/`else`/`each`/`try`/`catch`/`throw`) for cross-target structured bodies.',
+        description: 'Code block — the body of a function, method, route, tool, or event handler. Use <<<...>>> for raw multiline code, or `lang="kern"` with body-statement children (`let`/`do`/`return`/`if`/`else`/`each`/`try`/`catch`/`throw`/`continue`/`break`/`branch`) for cross-target structured bodies. Use `continue` inside `each` to skip the current iteration; use `break` inside `each` to exit the innermost loop. Use `branch` for switch-style structural matching (TS `switch`, Python `if/elif/else`). Prefer these over raw handlers for loop-control and dispatch bodies.',
         example: 'handler <<<\n  const result = await doWork();\n  return result;\n>>>',
         props: {
             code: { kind: 'rawBlock' },
@@ -1348,7 +1386,21 @@ export const NODE_SCHEMAS = {
         // body statements are rejected by validateBodyStatements (the schema list
         // is intentionally permissive so the validator can produce a clearer
         // context-aware error).
-        allowedChildren: ['let', 'do', 'return', 'if', 'else', 'each', 'try', 'catch', 'throw'],
+        allowedChildren: [
+            'let',
+            'destructure',
+            'do',
+            'return',
+            'if',
+            'else',
+            'each',
+            'try',
+            'catch',
+            'throw',
+            'continue',
+            'break',
+            'branch',
+        ],
     },
     return: {
         description: 'Body-statement return — emits `return value` (or bare `return;` when `value` is omitted) inside a `lang="kern"` handler body. Only valid as a child of `handler lang="kern"` or another body-statement (if/else/each/try/catch).',
@@ -1371,6 +1423,16 @@ export const NODE_SCHEMAS = {
             value: { kind: 'expression' },
         },
     },
+    continue: {
+        description: 'Body-statement loop-continue — emits `continue;` (TS) or `continue` (Python). Only valid inside a `lang="kern"` handler body, and the surrounding TS/Python compiler still rejects use outside an enclosing loop. Pair with `each` to express skip-this-iteration logic without dropping into a raw handler.',
+        example: 'each name=item in=items\n  if cond="item.skip"\n    continue\n  do value="process(item)"',
+        props: {},
+    },
+    break: {
+        description: 'Body-statement loop-break — emits `break;` (TS) or `break` (Python). Only valid inside a `lang="kern"` handler body, and the surrounding TS/Python compiler still rejects use outside an enclosing loop. Pair with `each` to express early-exit search/find loops without dropping into a raw handler.',
+        example: 'each name=item in=items\n  if cond="item.matches"\n    let name=found value="item"\n    break',
+        props: {},
+    },
     if: {
         description: 'Body-statement if — emits `if (cond) { ... }` inside a `lang="kern"` handler body. Optional `else` SIBLING (not child) emits `} else { ... }`. Distinct from the `if=` prop on `conditional` and route-guard nodes.',
         example: 'if cond="user.active"\n  return value="true"',
@@ -2233,9 +2295,15 @@ export const NODE_SCHEMAS = {
     },
     // Ground layer — semantic reasoning
     path: {
-        description: 'Decision path — a named branch in a resolve/branch tree',
-        example: 'path value="/api/users"',
-        props: { value: { required: true, kind: 'string' } },
+        description: 'Decision path — a named branch inside a `branch` (or resolve) tree. Provide exactly one of `value=` (the case literal: quoted → string compare, unquoted → identifier reference such as `Status.Active`) or `default=true` (the trailing fallback case, parallels JS `switch`/`default`). The validator rejects paths that supply neither or both. Body-statement child of `branch` admits the same body-statements as `handler lang="kern"`.',
+        example: 'path value="/api/users"\npath value=Status.Active\npath default=true',
+        props: {
+            // `value` is no longer schema-required because `path default=true` is a
+            // legal alternative shape. `path-shape` semantic rule enforces
+            // exactly-one-of(value, default) at validation time.
+            value: { kind: 'string' },
+            default: { kind: 'boolean' },
+        },
     },
     resolve: {
         description: 'Resolution node — selects among candidates using a discriminator',
@@ -2431,14 +2499,33 @@ const UNIVERSAL_CHILDREN = new Set(['handler', 'cleanup', 'reason', 'evidence',
 function checkRequiredProps(node, schema, violations) {
     const props = node.props || {};
     for (const [propName, propSchema] of Object.entries(schema.props)) {
-        if (propSchema.required && !(propName in props)) {
-            violations.push({
-                nodeType: node.type,
-                message: `'${node.type}' requires prop '${propName}'`,
-                line: node.loc?.line,
-                col: node.loc?.col,
-            });
+        if (!propSchema.required)
+            continue;
+        if (propName in props)
+            continue;
+        // each-pair-mode (2026-05-06): `name` becomes optional when both
+        // `pairKey` and `pairValue` are present (Map / iterable-of-pairs form).
+        // The schema can't express conditional-required, so suppress the
+        // `name`-required violation here under that exact shape. Other props
+        // (notably `in=`) still error if missing.
+        // Codex review-fix (mid-build, confidence 0.91): require BOTH props to
+        // be non-empty strings — accepting `null`/`0`/`false` here would let
+        // malformed source bypass the `name=` requirement and emit silently-wrong
+        // loop bindings (codegen does strict-truthy detection later).
+        if (node.type === 'each' &&
+            propName === 'name' &&
+            typeof props.pairKey === 'string' &&
+            props.pairKey.length > 0 &&
+            typeof props.pairValue === 'string' &&
+            props.pairValue.length > 0) {
+            continue;
         }
+        violations.push({
+            nodeType: node.type,
+            message: `'${node.type}' requires prop '${propName}'`,
+            line: node.loc?.line,
+            col: node.loc?.col,
+        });
     }
 }
 function checkCrossProps(node, violations) {
@@ -2699,6 +2786,80 @@ function checkCrossProps(node, violations) {
         // is only valid inside `render`/`group` — the positional check lives in
         // the semantic validator, which has ancestry context.
     }
+    if (node.type === 'path') {
+        // path-shape (2026-05-06): exactly one of `value=` (case literal) or
+        // `default=true` (trailing fallback). Both → ambiguous; neither → empty
+        // case clause that codegen can't emit. Schema dropped `value: required`
+        // so this rule replaces the requirement with a context-aware shape check.
+        const hasValue = 'value' in props;
+        const hasDefault = isTruthyProp(props.default);
+        if (!hasValue && !hasDefault) {
+            violations.push({
+                nodeType: 'path',
+                message: "'path' requires either 'value=' (case literal) or 'default=true' (trailing fallback)",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasValue && hasDefault) {
+            violations.push({
+                nodeType: 'path',
+                message: "'path' must not combine 'value=' and 'default=true' — choose one",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+    }
+    if (node.type === 'branch') {
+        // At most one default `path` per branch. More than one is a structural
+        // bug — codegen would emit unreachable trailing default clauses.
+        const defaultCount = (node.children ?? []).filter((c) => c.type === 'path' && isTruthyProp(c.props?.default)).length;
+        if (defaultCount > 1) {
+            violations.push({
+                nodeType: 'branch',
+                message: `'branch' must contain at most one 'path default=true' (found ${defaultCount})`,
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+    }
+    if (node.type === 'each') {
+        // each-pair-mode (2026-05-06): the Map / iterable-of-pairs form uses
+        // `pairKey=` + `pairValue=` for `for (const [k, v] of m)`. Three rules:
+        //   1. pairKey and pairValue come as a pair — neither alone is meaningful.
+        //   2. pair-mode is incompatible with `index=` (entries-with-index form).
+        //   3. `name=` becomes optional in pair-mode (relaxes schema `required`).
+        // Codex review-fix (2026-05-06, mid-build, confidence 0.91): use a strict
+        // string check so malformed source like `pairKey: null` / `pairValue: 0`
+        // is treated as ABSENT rather than as a truthy pair-mode declaration.
+        // The previous `!== '' && !== undefined` check accepted `null`/`0`/`false`,
+        // which allowed validator bypass when codegen later does a strict-truthy
+        // check (codegen would fall back to plain `each name=item` and silently
+        // emit a wrong loop binding).
+        const isPairProp = (raw) => typeof raw === 'string' && raw.length > 0;
+        const hasPairKey = isPairProp(props.pairKey);
+        const hasPairValue = isPairProp(props.pairValue);
+        const hasIndex = isPairProp(props.index);
+        if (hasPairKey !== hasPairValue) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each' pair-mode requires both 'pairKey=' AND 'pairValue=' (or neither)",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasPairKey && hasPairValue && hasIndex) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each' pair-mode ('pairKey'+'pairValue') is mutually exclusive with 'index='",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        // Pair-mode relaxes `name` requirement — handled by checkRequiredProps
+        // (suppresses the `name`-required violation when pairKey+pairValue are
+        // both present).
+    }
 }
 function isTruthyProp(raw) {
     return raw === true || raw === 'true';