@kernlang/core 3.1.7 → 3.1.9

package/dist/schema.js

@@ -15,9 +15,22 @@
  *   - 'boolean'        → 'true'/'false'
  *   - 'number'         → numeric value
  */
+import { VALID_TARGETS } from './config.js';
+import { defaultRuntime } from './runtime.js';
+import { KERN_VERSION, NODE_TYPES, STYLE_SHORTHANDS, VALUE_SHORTHANDS } from './spec.js';
 // ── Schema Definitions ──────────────────────────────────────────────────
 export const NODE_SCHEMAS = {
+    doc: {
+        description: 'JSDoc documentation comment attached to the next declaration. Supports inline (text=) or multiline (<<<>>>)',
+        example: 'doc text="Represents a user account"',
+        props: {
+            text: { kind: 'string' },
+            code: { kind: 'rawBlock' },
+        },
+    },
     type: {
+        description: 'TypeScript type alias — union of string literals or alias to another type',
+        example: 'type name=Status values="active|inactive|banned"',
         props: {
             name: { required: true, kind: 'identifier' },
             values: { kind: 'string' },
@@ -26,6 +39,8 @@ export const NODE_SCHEMAS = {
         },
     },
     interface: {
+        description: 'TypeScript interface with typed fields',
+        example: 'interface name=User export=true\n  field name=id type=string\n  field name=email type=string',
         props: {
             name: { required: true, kind: 'identifier' },
             extends: { kind: 'typeAnnotation' },
@@ -34,6 +49,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['field'],
     },
     union: {
+        description: 'Discriminated union type with variants, each having their own fields',
+        example: 'union name=Shape discriminant=kind\n  variant name=circle\n    field name=radius type=number',
         props: {
             name: { required: true, kind: 'identifier' },
             discriminant: { required: true, kind: 'identifier' },
@@ -42,12 +59,17 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['variant'],
     },
     variant: {
+        description: 'A case within a discriminated union. Use name= for inline variants with fields, or type= to reference an existing interface.',
+        example: 'variant name=circle\n  field name=radius type=number',
         props: {
-            name: { required: true, kind: 'identifier' },
+            name: { required: false, kind: 'identifier' },
+            type: { required: false, kind: 'typeAnnotation' },
         },
         allowedChildren: ['field'],
     },
     field: {
+        description: 'A typed property within an interface, variant, service, config, or error',
+        example: 'field name=email type=string optional=true',
         props: {
             name: { required: true, kind: 'identifier' },
             type: { kind: 'typeAnnotation' },
@@ -58,6 +80,8 @@ export const NODE_SCHEMAS = {
         },
     },
     service: {
+        description: 'Class-based service with methods and dependency injection',
+        example: 'service name=AuthService export=true\n  method name=login params="email:string,password:string" async=true',
         props: {
             name: { required: true, kind: 'identifier' },
             implements: { kind: 'typeAnnotation' },
@@ -66,6 +90,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['field', 'method', 'constructor', 'singleton'],
     },
     method: {
+        description: 'A method within a service or repository, with handler body',
+        example: 'method name=findById params="id:string" returns=User async=true\n  handler <<<\n    return db.users.find(id)\n  >>>',
         props: {
             name: { required: true, kind: 'identifier' },
             params: { kind: 'string' },
@@ -78,6 +104,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler'],
     },
     fn: {
+        description: 'Standalone function — the most common code unit in KERN',
+        example: 'fn name=calculateTotal params="items:CartItem[]" returns=number export=true\n  handler <<<\n    return items.reduce((sum, i) => sum + i.price, 0)\n  >>>',
         props: {
             name: { required: true, kind: 'identifier' },
             params: { kind: 'string' },
@@ -89,6 +117,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler', 'signal', 'cleanup'],
     },
     machine: {
+        description: 'State machine with states and guarded transitions — 12 lines of KERN generates 140+ lines of TypeScript',
+        example: 'machine name=OrderStatus export=true\n  state name=pending initial=true\n  state name=confirmed\n  transition name=confirm from=pending to=confirmed',
         props: {
             name: { required: true, kind: 'identifier' },
             export: { kind: 'boolean' },
@@ -96,12 +126,17 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['state', 'transition'],
     },
     state: {
+        description: 'State — machine state (initial=true/false) or React component state (initial=expression, type=Type)',
+        example: 'state name=pending initial=true\nstate name=count initial=0 type=number',
         props: {
             name: { required: true, kind: 'identifier' },
-            initial: { kind: 'boolean' },
+            initial: { kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
         },
     },
     transition: {
+        description: 'A guarded transition between machine states, with optional handler',
+        example: 'transition name=confirm from=pending to=confirmed\n  handler <<<\n    await notifyUser()\n  >>>',
         props: {
             name: { required: true, kind: 'identifier' },
             from: { required: true, kind: 'string' },
@@ -110,6 +145,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler'],
     },
     error: {
+        description: 'Custom error class extending a base error, with typed fields',
+        example: 'error name=ValidationError extends=Error message="Invalid input" export=true\n  field name=field type=string',
         props: {
             name: { required: true, kind: 'identifier' },
             extends: { required: true, kind: 'identifier' },
@@ -119,6 +156,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['field', 'handler'],
     },
     config: {
+        description: 'Configuration interface with typed fields — generates an interface',
+        example: 'config name=AppConfig export=true\n  field name=port type=number default=3000\n  field name=debug type=boolean',
         props: {
             name: { required: true, kind: 'identifier' },
             export: { kind: 'boolean' },
@@ -126,6 +165,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['field'],
     },
     store: {
+        description: 'File-based JSON store with typed key and model',
+        example: 'store name=UserStore path="data/users" key=id model=User export=true',
         props: {
             name: { required: true, kind: 'identifier' },
             path: { required: true, kind: 'string' },
@@ -135,12 +176,16 @@ export const NODE_SCHEMAS = {
         },
     },
     test: {
+        description: 'Test suite container with describe/it blocks',
+        example: 'test name="AuthService"\n  describe name="login"\n    it name="rejects invalid email"',
         props: {
             name: { required: true, kind: 'string' },
         },
         allowedChildren: ['describe', 'it', 'handler'],
     },
     event: {
+        description: 'Typed event with payload type children',
+        example: 'event name=UserCreated export=true\n  type name=id type=string\n  type name=email type=string',
         props: {
             name: { required: true, kind: 'identifier' },
             export: { kind: 'boolean' },
@@ -148,6 +193,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['type'],
     },
     import: {
+        description: 'ES module import — named, default, or type-only',
+        example: 'import from="./user.js" names="User,UserRole" types=true',
         props: {
             from: { required: true, kind: 'importPath' },
             names: { kind: 'string' },
@@ -156,6 +203,8 @@ export const NODE_SCHEMAS = {
         },
     },
     const: {
+        description: 'Constant declaration with optional type and value or handler body',
+        example: 'const name=MAX_RETRIES type=number value=3 export=true',
         props: {
             name: { required: true, kind: 'identifier' },
             type: { kind: 'typeAnnotation' },
@@ -165,6 +214,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler'],
     },
     on: {
+        description: 'Event listener — binds a handler to a named event',
+        example: 'on event=click handler=handleClick',
         props: {
             event: { required: true, kind: 'string' },
             handler: { kind: 'identifier' },
@@ -174,6 +225,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler'],
     },
     websocket: {
+        description: 'WebSocket server endpoint with event handlers',
+        example: 'websocket path="/ws" name=chatSocket export=true\n  on event=message\n    handler <<<\n      broadcast(data)\n    >>>',
         props: {
             path: { kind: 'string' },
             name: { kind: 'identifier' },
@@ -182,6 +235,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['on'],
     },
     derive: {
+        description: 'Computed/derived value from an expression',
+        example: 'derive name=fullName expr="first + " " + last" type=string',
         props: {
             name: { required: true, kind: 'identifier' },
             expr: { required: true, kind: 'rawExpr' },
@@ -190,6 +245,8 @@ export const NODE_SCHEMAS = {
         },
     },
     transform: {
+        description: 'Data transformation pipeline — maps target through a via function or handler',
+        example: 'transform name=normalized target=rawData via=normalize type=NormalizedData',
         props: {
             name: { required: true, kind: 'identifier' },
             target: { kind: 'rawExpr' },
@@ -200,6 +257,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler'],
     },
     action: {
+        description: 'Named side-effecting operation — can be idempotent or reversible',
+        example: 'action name=sendEmail params="to:string,body:string" async=true export=true\n  handler <<<\n    await mailer.send(to, body)\n  >>>',
         props: {
             name: { required: true, kind: 'identifier' },
             params: { kind: 'string' },
@@ -211,14 +270,42 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler'],
     },
     guard: {
+        description: 'Guard — runtime assertion (expr-based) or MCP security guard (kind-based: sanitize, pathContainment, validate, auth, rateLimit, sizeLimit, sanitizeOutput)',
+        example: 'guard expr="user !== null" else="throw new Error(\'No user\')"\nguard type=sanitize param=query\nguard type=pathContainment param=filePath allowlist=/data,/home',
         props: {
             name: { kind: 'string' },
-            expr: { required: true, kind: 'rawExpr' },
+            expr: { kind: 'rawExpr' },
             else: { kind: 'rawExpr' },
             confidence: { kind: 'number' },
+            kind: { kind: 'identifier' },
+            type: { kind: 'identifier' },
+            param: { kind: 'identifier' },
+            field: { kind: 'identifier' },
+            target: { kind: 'identifier' },
+            pattern: { kind: 'string' },
+            replacement: { kind: 'string' },
+            regex: { kind: 'string' },
+            min: { kind: 'number' },
+            max: { kind: 'number' },
+            allowlist: { kind: 'string' },
+            allow: { kind: 'string' },
+            roots: { kind: 'string' },
+            baseDir: { kind: 'string' },
+            base: { kind: 'string' },
+            root: { kind: 'string' },
+            envVar: { kind: 'string' },
+            env: { kind: 'string' },
+            header: { kind: 'string' },
+            windowMs: { kind: 'number' },
+            window: { kind: 'number' },
+            maxRequests: { kind: 'number' },
+            requests: { kind: 'number' },
+            maxBytes: { kind: 'number' },
         },
     },
     assume: {
+        description: 'Documented assumption with evidence and fallback for when it breaks',
+        example: 'assume expr="items.length > 0" evidence="validated upstream" fallback="return []"',
         props: {
             expr: { required: true, kind: 'rawExpr' },
             scope: { kind: 'string' },
@@ -228,6 +315,8 @@ export const NODE_SCHEMAS = {
         },
     },
     invariant: {
+        description: 'Compile-time documented invariant — runtime assertion with confidence score',
+        example: 'invariant name="positive balance" expr="balance >= 0"',
         props: {
             name: { kind: 'string' },
             expr: { required: true, kind: 'rawExpr' },
@@ -235,6 +324,8 @@ export const NODE_SCHEMAS = {
         },
     },
     each: {
+        description: 'Iteration — renders children for each item in a collection (target-agnostic loop)',
+        example: 'each name=item in=items index=i',
         props: {
             name: { required: true, kind: 'identifier' },
             in: { required: true, kind: 'rawExpr' },
@@ -242,6 +333,8 @@ export const NODE_SCHEMAS = {
         },
     },
     collect: {
+        description: 'Query/collect from a data source with optional filter, sort, and limit',
+        example: 'collect name=activeUsers from=users where="u => u.active" order="u => u.name" limit=10',
         props: {
             name: { required: true, kind: 'identifier' },
             from: { required: true, kind: 'rawExpr' },
@@ -252,6 +345,8 @@ 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"',
         props: {
             name: { required: true, kind: 'identifier' },
             on: { required: true, kind: 'rawExpr' },
@@ -259,6 +354,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['path'],
     },
     model: {
+        description: 'Database model/entity with columns and relations (generates Prisma or TypeORM)',
+        example: 'model name=User table="users" export=true\n  column name=id type=string\n  column name=email type=string\n  relation name=posts type=Post[]',
         props: {
             name: { required: true, kind: 'identifier' },
             table: { kind: 'string' },
@@ -267,6 +364,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['column', 'relation'],
     },
     repository: {
+        description: 'Data access layer class with typed methods for a model',
+        example: 'repository name=UserRepo model=User export=true\n  method name=findByEmail params="email:string" returns=User async=true',
         props: {
             name: { required: true, kind: 'identifier' },
             model: { required: true, kind: 'identifier' },
@@ -275,6 +374,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['method'],
     },
     dependency: {
+        description: 'Dependency injection container entry with scope and injected services',
+        example: 'dependency name=authService scope=singleton export=true',
         props: {
             name: { required: true, kind: 'identifier' },
             scope: { kind: 'string' },
@@ -283,6 +384,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['inject', 'returns'],
     },
     cache: {
+        description: 'Cache layer with backend selection, TTL, and entry/invalidation rules',
+        example: 'cache name=userCache backend=redis prefix="user:" ttl=3600 export=true',
         props: {
             name: { required: true, kind: 'identifier' },
             backend: { kind: 'string' },
@@ -293,12 +396,16 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['entry', 'invalidate'],
     },
     module: {
+        description: 'Logical module grouping for code organization',
+        example: 'module name=auth export=true',
         props: {
             name: { required: true, kind: 'identifier' },
             export: { kind: 'boolean' },
         },
     },
     provider: {
+        description: 'React context provider component with typed value',
+        example: 'provider name=AuthProvider type=AuthContext',
         props: {
             name: { required: true, kind: 'identifier' },
             type: { required: true, kind: 'typeAnnotation' },
@@ -306,6 +413,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['prop', 'handler'],
     },
     hook: {
+        description: 'React custom hook with lifecycle methods',
+        example: 'hook name=useAuth returns=AuthState\n  handler <<<\n    const [user, setUser] = useState(null)\n    return { user }\n  >>>',
         props: {
             name: { required: true, kind: 'identifier' },
             params: { kind: 'string' },
@@ -314,6 +423,8 @@ export const NODE_SCHEMAS = {
         allowedChildren: ['handler', 'memo', 'callback', 'ref', 'effect'],
     },
     effect: {
+        description: 'React useEffect — side effect with dependency tracking',
+        example: 'effect deps="userId" once=false\n  handler <<<\n    fetchUser(userId)\n  >>>\n  cleanup <<<\n    controller.abort()\n  >>>',
         props: {
             name: { kind: 'identifier' },
             deps: { kind: 'string' },
@@ -323,6 +434,8 @@ export const NODE_SCHEMAS = {
     },
     // ── Web / UI node types ──────────────────────────────────────────────
     page: {
+        description: 'Page/route component — generates Next.js page or React route component',
+        example: 'page name=Dashboard client=true route="/dashboard"',
         props: {
             name: { required: true, kind: 'identifier' },
             client: { kind: 'boolean' },
@@ -332,15 +445,21 @@ export const NODE_SCHEMAS = {
         },
     },
     layout: {
+        description: 'Layout wrapper component (Next.js layout or generic wrapper)',
+        example: 'layout lang="en" route="/"',
         props: {
             lang: { kind: 'string' },
             route: { kind: 'string' },
         },
     },
     loading: {
+        description: 'Next.js loading.tsx — shown while page content loads',
+        example: 'loading\n  spinner',
         props: {},
     },
     metadata: {
+        description: 'Page metadata — title, description, og:image for SEO',
+        example: 'metadata title="Dashboard" description="Your account overview"',
         props: {
             title: { kind: 'string' },
             description: { kind: 'string' },
@@ -349,11 +468,15 @@ export const NODE_SCHEMAS = {
         },
     },
     link: {
+        description: 'Navigation link to an internal route',
+        example: 'link to="/about"\n  text "About Us"',
         props: {
             to: { required: true, kind: 'string' },
         },
     },
     textarea: {
+        description: 'Multi-line text input with optional two-way binding',
+        example: 'textarea bind=notes placeholder="Enter notes..."',
         props: {
             bind: { kind: 'identifier' },
             placeholder: { kind: 'string' },
@@ -361,6 +484,8 @@ export const NODE_SCHEMAS = {
         },
     },
     slider: {
+        description: 'Range slider input with min/max/step',
+        example: 'slider bind=volume min=0 max=100 step=5',
         props: {
             bind: { kind: 'identifier' },
             min: { kind: 'number' },
@@ -369,17 +494,23 @@ export const NODE_SCHEMAS = {
         },
     },
     toggle: {
+        description: 'Boolean toggle/switch input',
+        example: 'toggle bind=darkMode',
         props: {
             bind: { kind: 'identifier' },
         },
     },
     grid: {
+        description: 'CSS grid container with column count and gap',
+        example: 'grid cols=3 gap=4',
         props: {
             cols: { kind: 'number' },
             gap: { kind: 'number' },
         },
     },
     component: {
+        description: 'Reference to an external or dynamic React component',
+        example: 'component ref=UserCard props="user,onEdit"',
         props: {
             ref: { kind: 'identifier' },
             name: { kind: 'identifier' },
@@ -390,23 +521,31 @@ export const NODE_SCHEMAS = {
         },
     },
     icon: {
+        description: 'Icon component by name',
+        example: 'icon name=ArrowRight',
         props: {
             name: { required: true, kind: 'identifier' },
         },
     },
     logic: {
+        description: 'Inline TypeScript logic block — embedded code in a component',
+        example: 'logic <<<\n  const filtered = items.filter(i => i.active)\n>>>',
         props: {
             code: { kind: 'rawBlock' },
         },
         allowedChildren: ['handler'],
     },
     form: {
+        description: 'HTML form element with action and method',
+        example: 'form action="/api/submit" method="POST"',
         props: {
             action: { kind: 'string' },
             method: { kind: 'string' },
         },
     },
     svg: {
+        description: 'SVG element with viewBox, dimensions, and fill/stroke',
+        example: 'svg icon=logo width=24 height=24 viewBox="0 0 24 24"',
         props: {
             icon: { kind: 'string' },
             size: { kind: 'number' },
@@ -418,6 +557,787 @@ export const NODE_SCHEMAS = {
             stroke: { kind: 'string' },
         },
     },
+    // ── Cross-target nodes ────────────────────────────────────────────────
+    handler: {
+        description: 'Code block — the body of a function, method, route, tool, or event handler. Use <<<...>>> for multiline code.',
+        example: 'handler <<<\n  const result = await doWork();\n  return result;\n>>>',
+        props: {
+            code: { kind: 'rawBlock' },
+            lang: { kind: 'string' },
+        },
+    },
+    conditional: {
+        description: 'Conditional rendering — shows children when if-expression is truthy',
+        example: 'conditional if="user !== null"',
+        props: {
+            if: { required: true, kind: 'rawExpr' },
+        },
+    },
+    // ── Express / Backend nodes ───────────────────────────────────────────
+    server: {
+        description: 'Express server entry point with name and port',
+        example: 'server name=MyAPI port=3000\n  route path="/api/users" method=get\n    handler <<<\n      res.json(users)\n    >>>',
+        props: {
+            name: { kind: 'identifier' },
+            port: { kind: 'number' },
+        },
+        allowedChildren: ['route', 'middleware', 'websocket', 'model', 'dependency', 'job', 'storage', 'email'],
+    },
+    route: {
+        description: 'HTTP route — defines an endpoint with method, path, and handler',
+        example: 'route path="/api/users" method=get\n  handler <<<\n    res.json(users)\n  >>>',
+        props: {
+            path: { required: true, kind: 'string' },
+            method: { kind: 'identifier' },
+        },
+        allowedChildren: [
+            'handler',
+            'middleware',
+            'schema',
+            'auth',
+            'validate',
+            'params',
+            'respond',
+            'error',
+            'guard',
+            'derive',
+            'branch',
+            'each',
+            'collect',
+            'effect',
+        ],
+    },
+    middleware: {
+        description: 'Express middleware — named built-in (json, cors, rateLimit) or custom with handler',
+        example: 'middleware name=cors\nmiddleware name=auth\n  handler <<<\n    if (!req.user) return res.status(401).json({ error: "Unauthorized" });\n    next();\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            names: { kind: 'string' },
+        },
+        allowedChildren: ['handler'],
+    },
+    params: {
+        description: 'Query/path parameter definitions for a route — items is an array of {name, type, default?}',
+        example: 'params items="[{name:page,type:number,default:1},{name:limit,type:number,default:20}]"',
+        props: {
+            items: { kind: 'rawExpr' },
+        },
+    },
+    auth: {
+        description: 'Authentication requirement on a route — required or optional',
+        example: 'auth mode=required',
+        props: {
+            mode: { kind: 'identifier' },
+        },
+    },
+    validate: {
+        description: 'Request validation schema reference for a route',
+        example: 'validate schema=CreateUserSchema',
+        props: {
+            schema: { kind: 'identifier' },
+        },
+    },
+    respond: {
+        description: 'Declarative HTTP response — status, body, redirect, or error',
+        example: 'respond status=200 json="{ success: true }"',
+        props: {
+            status: { kind: 'number' },
+            json: { kind: 'rawExpr' },
+            text: { kind: 'string' },
+            error: { kind: 'string' },
+            redirect: { kind: 'string' },
+            type: { kind: 'string' },
+            headers: { kind: 'rawExpr' },
+        },
+    },
+    schema: {
+        description: 'Request schema — TypeScript types for body, params, query, and response validation',
+        example: 'schema body=CreateUserInput params="{id: string}" response=UserResponse',
+        props: {
+            body: { kind: 'typeAnnotation' },
+            params: { kind: 'typeAnnotation' },
+            query: { kind: 'typeAnnotation' },
+            response: { kind: 'typeAnnotation' },
+        },
+    },
+    // ── MCP (Model Context Protocol) nodes ────────────────────────────────
+    mcp: {
+        description: 'MCP server definition — compiles to a full Model Context Protocol server with tools, resources, and prompts',
+        example: 'mcp name=FileTools version=1.0 transport=stdio\n  tool name=readFile\n    param name=path type=string required=true\n    handler <<<\n      return { content: [{ type: "text", text: await fs.readFile(path) }] };\n    >>>',
+        props: {
+            name: { kind: 'identifier' },
+            version: { kind: 'string' },
+            transport: { kind: 'identifier' },
+            port: { kind: 'number' },
+            allowlist: { kind: 'string' },
+            allowedPaths: { kind: 'string' },
+            baseDir: { kind: 'string' },
+        },
+        allowedChildren: ['tool', 'resource', 'prompt'],
+    },
+    tool: {
+        description: 'MCP tool definition — a callable function exposed to AI agents with typed params and security guards',
+        example: 'tool name=searchFiles\n  description text="Search for files"\n  param name=query type=string required=true\n  guard type=sanitize param=query\n  handler <<<\n    return { content: [{ type: "text", text: results }] };\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+        },
+        allowedChildren: ['param', 'handler', 'description', 'guard', 'sampling', 'elicitation'],
+    },
+    resource: {
+        description: 'MCP resource — a data source exposed to AI agents via URI. Use {variables} for templated URIs.',
+        example: 'resource name=config uri="config://app"\n  description text="Application configuration"\n  handler <<<\n    return { contents: [{ uri: uri.href, text: JSON.stringify(config) }] };\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            uri: { required: true, kind: 'string' },
+        },
+        allowedChildren: ['param', 'handler', 'description', 'guard'],
+    },
+    param: {
+        description: 'Parameter definition for a tool, resource, or prompt — name, type, required, default, and description',
+        example: 'param name=query type=string required=true description="Search query"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            type: { kind: 'identifier' },
+            required: { kind: 'boolean' },
+            default: { kind: 'rawExpr' },
+            description: { kind: 'string' },
+            min: { kind: 'number' },
+            max: { kind: 'number' },
+        },
+        allowedChildren: ['guard', 'description'],
+    },
+    prompt: {
+        description: 'MCP prompt template — a reusable system prompt exposed to AI agents',
+        example: 'prompt name=analyzeFile\n  param name=filePath type=string required=true\n  handler <<<\n    return { messages: [{ role: "user", content: { type: "text", text: `Analyze ${filePath}` } }] };\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+        },
+        allowedChildren: ['param', 'handler', 'description'],
+    },
+    description: {
+        description: 'Documentation text for a tool, resource, or prompt',
+        example: 'description text="Read a file within allowed directories"',
+        props: {
+            text: { kind: 'string' },
+            value: { kind: 'string' },
+        },
+    },
+    sampling: {
+        description: 'MCP sampling configuration — requests LLM completion within a tool handler',
+        example: 'sampling maxTokens=500',
+        props: {
+            maxTokens: { kind: 'number' },
+        },
+    },
+    elicitation: {
+        description: 'MCP elicitation — requests user input during tool execution',
+        example: 'elicitation message="Confirm deletion?"',
+        props: {
+            message: { kind: 'string' },
+            text: { kind: 'string' },
+        },
+    },
+    // ── React / UI element nodes ──────────────────────────────────────────
+    screen: {
+        description: 'Full-screen container component (minHeight: 100vh flex column)',
+        example: 'screen name=Dashboard\n  row\n    text value="Welcome"',
+        props: {
+            name: { kind: 'identifier' },
+        },
+    },
+    row: {
+        description: 'Flexbox row container — horizontal layout',
+        example: 'row\n  col\n    text value="Left"\n  col\n    text value="Right"',
+        props: {},
+    },
+    col: {
+        description: 'Flexbox column container — vertical layout',
+        example: 'col\n  text value="Stacked content"',
+        props: {},
+    },
+    card: {
+        description: 'Card component — rounded container with shadow',
+        example: 'card\n  text value="Card title"\n  text value="Card body"',
+        props: {},
+    },
+    text: {
+        description: 'Text element — renders a paragraph or span with content',
+        example: 'text value="Hello, world!"',
+        props: {
+            value: { kind: 'string' },
+        },
+    },
+    button: {
+        description: 'Button element with label text and optional navigation',
+        example: 'button text="Submit"\nbutton text="Go Home" to="/home"',
+        props: {
+            text: { kind: 'string' },
+            to: { kind: 'string' },
+        },
+    },
+    input: {
+        description: 'Form input — text, number, email, etc. with optional state binding',
+        example: 'input bind=email type=email placeholder="Enter email"',
+        props: {
+            bind: { kind: 'identifier' },
+            type: { kind: 'identifier' },
+            placeholder: { kind: 'string' },
+        },
+    },
+    image: {
+        description: 'Image element with source and alt text',
+        example: 'image src="/logo.png" alt="Company logo"',
+        props: {
+            src: { required: true, kind: 'string' },
+            alt: { kind: 'string' },
+        },
+    },
+    modal: {
+        description: 'Modal dialog overlay — renders a centered popup',
+        example: 'modal\n  text value="Are you sure?"\n  button text="Confirm"\n  button text="Cancel"',
+        props: {},
+    },
+    table: {
+        description: 'Table container for tabular data display',
+        example: 'table\n  header\n    text value="Name"\n    text value="Email"',
+        props: {},
+    },
+    header: {
+        description: 'Header/heading element or table header row',
+        example: 'header\n  text value="Page Title"',
+        props: {},
+    },
+    tabs: {
+        description: 'Tabbed navigation container',
+        example: 'tabs\n  tab label="Profile"\n    text value="Profile content"\n  tab label="Settings"\n    text value="Settings content"',
+        props: {},
+    },
+    theme: {
+        description: 'Theme/styling definitions — CSS custom properties and style objects applied to descendant nodes',
+        example: 'theme styles="{ background: #1a1a2e, color: #e0e0e0, fontFamily: system-ui }"',
+        props: {
+            name: { kind: 'identifier' },
+            styles: { kind: 'rawExpr' },
+        },
+    },
+    // ── Backend: Stream / Spawn / Timer ───────────────────────────────────
+    stream: {
+        description: 'SSE stream route — sets up Server-Sent Events with heartbeat and structured emit helper',
+        example: 'route path="/api/stream" method=get\n  stream\n    spawn binary=ffmpeg args="[\'-i\',input]"\n      on name=stdout\n        handler <<<\n          emit({ chunk: chunk.toString() })\n        >>>',
+        props: {
+            name: { kind: 'identifier' },
+            source: { kind: 'rawExpr' },
+            append: { kind: 'boolean' },
+        },
+        allowedChildren: ['spawn', 'handler', 'on', 'timer'],
+    },
+    spawn: {
+        description: 'Child process — spawns a binary with shell:false safety, SIGTERM/SIGKILL escalation, and abort-on-disconnect',
+        example: "spawn binary=ffmpeg args=\"['-i',input,'-f','mp3','pipe:1']\" timeout=30",
+        props: {
+            binary: { required: true, kind: 'string' },
+            args: { kind: 'rawExpr' },
+            timeout: { kind: 'number' },
+            stdin: { kind: 'rawExpr' },
+        },
+        allowedChildren: ['on', 'env', 'handler'],
+    },
+    timer: {
+        description: 'Request timeout — wraps handler in a deadline with AbortController and configurable timeout handler',
+        example: 'timer timeout=15\n  handler <<<\n    const result = await longRunningTask();\n    res.json(result);\n  >>>',
+        props: {
+            timeout: { kind: 'number' },
+            name: { kind: 'identifier' },
+        },
+        allowedChildren: ['handler', 'on'],
+    },
+    env: {
+        description: 'Environment variable — declares a required or optional env var, used in spawn or server config',
+        example: 'env name=DATABASE_URL required=true',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            value: { kind: 'rawExpr' },
+            required: { kind: 'boolean' },
+        },
+    },
+    trigger: {
+        description: 'Event trigger — fires an action on a named event from a source',
+        example: 'trigger kind=webhook on=push from=github',
+        props: {
+            kind: { kind: 'identifier' },
+            on: { kind: 'string' },
+            from: { kind: 'string' },
+        },
+        allowedChildren: ['handler'],
+    },
+    // ── Next.js production patterns ───────────────────────────────────────
+    fetch: {
+        description: 'Server-side data fetch — generates an async fetch call in a Next.js server component',
+        example: 'fetch name=posts url="/api/posts" options="{ next: { revalidate: 60 } }"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            url: { required: true, kind: 'rawExpr' },
+            options: { kind: 'rawExpr' },
+        },
+    },
+    generateMetadata: {
+        description: 'Next.js generateMetadata export — async function for dynamic page metadata',
+        example: 'generateMetadata params="slug:string"',
+        props: {
+            params: { kind: 'string' },
+        },
+        allowedChildren: ['handler'],
+    },
+    notFound: {
+        description: 'Next.js notFound() call — triggers 404 page',
+        example: 'notFound',
+        props: {},
+    },
+    redirect: {
+        description: 'Next.js redirect() call — server-side redirect to another route',
+        example: 'redirect to="/login"',
+        props: {
+            to: { required: true, kind: 'string' },
+        },
+    },
+    // ── CLI nodes ─────────────────────────────────────────────────────────
+    cli: {
+        description: 'CLI application root — defines a command-line tool with commands, flags, and imports',
+        example: 'cli name=myapp version=1.0.0 description="My CLI tool"\n  command name=init description="Initialize project"\n    handler <<<\n      console.log("Initializing...")\n    >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            version: { kind: 'string' },
+            description: { kind: 'string' },
+        },
+        allowedChildren: ['command', 'flag', 'import'],
+    },
+    command: {
+        description: 'CLI subcommand with arguments, flags, and handler',
+        example: 'command name=deploy description="Deploy to production" alias=d\n  arg name=target type=string required=true\n  flag name=dry-run alias=n type=boolean\n  handler <<<\n    deploy(target, { dryRun })\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            description: { kind: 'string' },
+            alias: { kind: 'string' },
+        },
+        allowedChildren: ['arg', 'flag', 'handler', 'import'],
+    },
+    arg: {
+        description: 'CLI positional argument — required args must come before optional ones',
+        example: 'arg name=target type=string required=true description="Deploy target"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            type: { kind: 'identifier' },
+            required: { kind: 'boolean' },
+            description: { kind: 'string' },
+            default: { kind: 'rawExpr' },
+        },
+    },
+    flag: {
+        description: 'CLI flag/option — named with optional short alias',
+        example: 'flag name=verbose alias=v type=boolean description="Enable verbose output"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            alias: { kind: 'string' },
+            type: { kind: 'identifier' },
+            required: { kind: 'boolean' },
+            description: { kind: 'string' },
+            default: { kind: 'rawExpr' },
+        },
+    },
+    // ── React lifecycle hooks (Batch 2) ───────────────────────────────────
+    memo: {
+        description: 'React useMemo — memoized computation with dependency tracking',
+        example: 'memo name=filtered deps="items,filter"\n  handler <<<\n    return items.filter(i => i.active)\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            deps: { kind: 'string' },
+        },
+        allowedChildren: ['handler'],
+    },
+    callback: {
+        description: 'React useCallback — memoized function reference with dependency tracking',
+        example: 'callback name=handleSubmit deps="formData" async=true\n  handler <<<\n    await api.submit(formData)\n  >>>',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            params: { kind: 'string' },
+            deps: { kind: 'string' },
+            async: { kind: 'boolean' },
+        },
+        allowedChildren: ['handler'],
+    },
+    ref: {
+        description: 'React useRef — mutable ref object that persists across renders',
+        example: 'ref name=inputRef type=HTMLInputElement initial=null',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            type: { kind: 'typeAnnotation' },
+            initial: { kind: 'rawExpr' },
+        },
+    },
+    context: {
+        description: 'React useContext — consume a React context by name',
+        example: 'context name=theme source=ThemeContext',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            source: { required: true, kind: 'identifier' },
+        },
+    },
+    prop: {
+        description: 'Component prop declaration — name, type, optionality, and default value',
+        example: 'prop name=title type=string\nprop name=count type=number optional=true default=0',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            type: { kind: 'typeAnnotation' },
+            optional: { kind: 'boolean' },
+            default: { kind: 'rawExpr' },
+        },
+    },
+    returns: {
+        description: 'Return type declaration or return statement for a hook/function',
+        example: 'returns type=AuthState with="{ user, login, logout }"',
+        props: {
+            name: { kind: 'identifier' },
+            type: { kind: 'typeAnnotation' },
+            with: { kind: 'rawExpr' },
+        },
+    },
+    render: {
+        description: 'Render function — JSX output block for a component or hook',
+        example: 'render\n  handler <<<\n    return <div>{children}</div>\n  >>>',
+        props: {},
+        allowedChildren: ['handler'],
+    },
+    template: {
+        description: 'Reusable template with named slots — defines a composable layout pattern',
+        example: 'template name=PageLayout\n  slot name=header\n  slot name=content\n  slot name=footer optional=true',
+        props: {
+            name: { required: true, kind: 'identifier' },
+        },
+        allowedChildren: ['slot', 'body', 'handler'],
+    },
+    // ── Data layer (Batch 3) ──────────────────────────────────────────────
+    column: {
+        description: 'Database column definition within a model — type, constraints, and default value',
+        example: 'column name=email type=string unique=true\ncolumn name=age type=number optional=true',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            type: { kind: 'typeAnnotation' },
+            optional: { kind: 'boolean' },
+            primary: { kind: 'boolean' },
+            unique: { kind: 'boolean' },
+            default: { kind: 'rawExpr' },
+        },
+    },
+    relation: {
+        description: 'Database relation — defines a foreign key relationship between models',
+        example: 'relation name=author target=User kind=many-to-one',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            target: { required: true, kind: 'identifier' },
+            kind: { kind: 'string' },
+        },
+    },
+    inject: {
+        description: 'Dependency injection — inject a service or value into the current scope',
+        example: 'inject name=db type=Database from="./database.js"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            type: { kind: 'typeAnnotation' },
+            from: { kind: 'rawExpr' },
+            with: { kind: 'rawExpr' },
+        },
+    },
+    entry: {
+        description: 'Cache entry — defines a cached value with key and optional strategy',
+        example: 'entry name=userProfile key="user:{id}"\n  strategy name=stale-while-revalidate max=60',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            key: { kind: 'string' },
+        },
+        allowedChildren: ['strategy', 'handler'],
+    },
+    invalidate: {
+        description: 'Cache invalidation rule — trigger cache clearing on an event',
+        example: 'invalidate on=userUpdate tags="user,profile"',
+        props: {
+            on: { required: true, kind: 'string' },
+            tags: { kind: 'string' },
+        },
+    },
+    signal: {
+        description: 'Reactive signal — named state that triggers updates on change (used in hooks/components)',
+        example: 'signal name=isLoading',
+        props: {
+            name: { required: true, kind: 'identifier' },
+        },
+    },
+    // ── Structural + UI controls (Batch 4) ────────────────────────────────
+    section: {
+        description: 'Semantic section container — groups related content with optional title',
+        example: 'section title="User Settings"',
+        props: {
+            title: { kind: 'string' },
+        },
+    },
+    list: {
+        description: 'List container — renders child items as an ordered or unordered list',
+        example: 'list\n  item value="First"\n  item value="Second"',
+        props: {},
+        allowedChildren: ['item'],
+    },
+    item: {
+        description: 'List item — single entry within a list container',
+        example: 'item value="Buy groceries"',
+        props: {
+            value: { kind: 'string' },
+        },
+    },
+    option: {
+        description: 'Select option — a selectable choice within a select dropdown',
+        example: 'option value=admin label="Administrator"',
+        props: {
+            value: { required: true, kind: 'string' },
+            label: { kind: 'string' },
+        },
+    },
+    select: {
+        description: 'Select dropdown — bound to state with child options',
+        example: 'select bind=role\n  option value=admin label="Admin"\n  option value=user label="User"',
+        props: {
+            bind: { kind: 'identifier' },
+        },
+        allowedChildren: ['option'],
+    },
+    slot: {
+        description: 'Template slot — named insertion point within a template',
+        example: 'slot name=header optional=true default="Default Header"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            slotType: { kind: 'string' },
+            optional: { kind: 'boolean' },
+            default: { kind: 'rawExpr' },
+        },
+    },
+    body: {
+        description: 'Body block — raw code content for templates or structural containers',
+        example: 'body <<<\n  <main>{children}</main>\n>>>',
+        props: {
+            code: { kind: 'rawBlock' },
+        },
+    },
+    // ── Phase 3: Remaining node schemas (100% coverage) ───────────────────
+    // Terminal / Ink UI
+    scroll: { description: 'Scrollable container', example: 'scroll', props: {} },
+    progress: {
+        description: 'Progress bar — shows completion status',
+        example: 'progress value=75 max=100 label="Loading"',
+        props: { value: { kind: 'number' }, max: { kind: 'number' }, label: { kind: 'string' } },
+    },
+    divider: { description: 'Visual divider / horizontal rule', example: 'divider', props: {} },
+    codeblock: {
+        description: 'Code block with syntax highlighting',
+        example: 'codeblock lang=typescript <<<\n  const x = 1;\n>>>',
+        props: { lang: { kind: 'string' }, code: { kind: 'rawBlock' } },
+    },
+    tab: {
+        description: 'Single tab within a tabs container',
+        example: 'tab label="Settings"\n  text value="Settings content"',
+        props: { label: { kind: 'string' } },
+    },
+    separator: { description: 'Ink horizontal rule / separator', example: 'separator', props: {} },
+    thead: { description: 'Table head section', example: 'thead', props: {} },
+    tbody: { description: 'Table body section', example: 'tbody', props: {} },
+    tr: { description: 'Table row', example: 'tr', props: {} },
+    th: { description: 'Table header cell', example: 'th value="Name"', props: { value: { kind: 'string' } } },
+    td: { description: 'Table data cell', example: 'td value="John"', props: { value: { kind: 'string' } } },
+    scoreboard: {
+        description: 'Dashboard scoreboard — container for metric widgets',
+        example: 'scoreboard\n  metric label="Users" value=1234',
+        props: {},
+        allowedChildren: ['metric'],
+    },
+    metric: {
+        description: 'Single metric display — label + value pair',
+        example: 'metric label="Active Users" value={{users.length}}',
+        props: { label: { required: true, kind: 'string' }, value: { required: true, kind: 'rawExpr' } },
+    },
+    spinner: {
+        description: 'Loading spinner with optional text',
+        example: 'spinner text="Loading..."',
+        props: { text: { kind: 'string' } },
+    },
+    box: {
+        description: 'Ink box container with border styling',
+        example: 'box borderStyle=round borderColor=green',
+        props: { borderStyle: { kind: 'string' }, borderColor: { kind: 'string' } },
+    },
+    gradient: {
+        description: 'Gradient text effect (Ink)',
+        example: 'gradient text="Hello" colors="red,blue"',
+        props: { text: { kind: 'string' }, colors: { kind: 'string' } },
+    },
+    // Ink-specific input nodes
+    'input-area': { description: 'Ink text input area', example: 'input-area', props: {} },
+    'output-area': { description: 'Ink text output area', example: 'output-area', props: {} },
+    'text-input': {
+        description: 'Ink text input with binding',
+        example: 'text-input value={{query}} onChange={{setQuery}} placeholder="Search..."',
+        props: { value: { kind: 'rawExpr' }, onChange: { kind: 'rawExpr' }, placeholder: { kind: 'string' } },
+    },
+    'select-input': {
+        description: 'Ink select input — choose from a list',
+        example: 'select-input items={{options}} onSelect={{handleSelect}}',
+        props: { items: { kind: 'rawExpr' }, onSelect: { kind: 'rawExpr' } },
+    },
+    // Control flow / structural
+    repl: {
+        description: 'Read-eval-print loop — interactive terminal command loop',
+        example: 'repl name=shell prompt=">"',
+        props: { name: { kind: 'identifier' }, prompt: { kind: 'string' } },
+        allowedChildren: ['on', 'handler'],
+    },
+    parallel: {
+        description: 'Parallel execution — run children concurrently',
+        example: 'parallel\n  dispatch to=worker1\n  dispatch to=worker2',
+        props: { name: { kind: 'identifier' } },
+    },
+    dispatch: {
+        description: 'Dispatch an action or message to a target',
+        example: 'dispatch to=worker payload={{data}}',
+        props: { to: { required: true, kind: 'string' }, payload: { kind: 'rawExpr' } },
+    },
+    // biome-ignore lint/suspicious/noThenProperty: `then` is a valid KERN node type, not a Promise thenable
+    then: {
+        description: 'Sequential continuation — runs after parent completes',
+        example: 'then\n  handler <<<\n    console.log("done")\n  >>>',
+        props: {},
+        allowedChildren: ['handler'],
+    },
+    // Lifecycle / structural children
+    singleton: {
+        description: 'Singleton marker — service is instantiated once',
+        example: 'singleton name=cache',
+        props: { name: { kind: 'identifier' } },
+    },
+    constructor: {
+        description: 'Constructor for a service — runs on instantiation',
+        example: 'constructor params="size:number"\n  handler <<<\n    this.data = new Map();\n  >>>',
+        props: { params: { kind: 'string' } },
+        allowedChildren: ['handler'],
+    },
+    cleanup: {
+        description: 'Cleanup handler — runs on teardown (useEffect return, signal dispose)',
+        example: 'cleanup <<<\n  controller.abort();\n>>>',
+        props: { code: { kind: 'rawBlock' } },
+    },
+    export: {
+        description: 'Re-export statement — export names from another module',
+        example: 'export from="./utils.js" names="add,subtract"',
+        props: {
+            from: { kind: 'importPath' },
+            names: { kind: 'string' },
+            types: { kind: 'string' },
+            star: { kind: 'boolean' },
+            default: { kind: 'identifier' },
+        },
+    },
+    describe: {
+        description: 'Test suite — groups related test cases',
+        example: 'describe name="UserService"\n  it name="creates a user"\n    handler <<<\n      expect(createUser()).toBeDefined();\n    >>>',
+        props: { name: { required: true, kind: 'string' } },
+        allowedChildren: ['it', 'describe', 'handler'],
+    },
+    it: {
+        description: 'Test case — single test assertion',
+        example: 'it name="returns 200 on success"\n  handler <<<\n    expect(res.status).toBe(200);\n  >>>',
+        props: { name: { required: true, kind: 'string' } },
+        allowedChildren: ['handler'],
+    },
+    // 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' } },
+    },
+    resolve: {
+        description: 'Resolution node — selects among candidates using a discriminator',
+        example: 'resolve name=bestRoute\n  candidate name=fast\n  candidate name=reliable',
+        props: { name: { kind: 'identifier' } },
+        allowedChildren: ['candidate', 'discriminator', 'handler'],
+    },
+    candidate: {
+        description: 'Candidate option within a resolve block',
+        example: 'candidate name=primary\n  handler <<<\n    return fastPath();\n  >>>',
+        props: { name: { required: true, kind: 'identifier' } },
+        allowedChildren: ['handler'],
+    },
+    discriminator: {
+        description: 'Selection strategy for choosing among candidates',
+        example: 'discriminator method=latency metric=p99',
+        props: { method: { kind: 'identifier' }, metric: { kind: 'string' } },
+        allowedChildren: ['handler'],
+    },
+    pattern: {
+        description: 'Pattern match — structural matching on values',
+        example: 'pattern name=classify on={{input.type}}',
+        props: { name: { kind: 'identifier' }, on: { kind: 'rawExpr' } },
+        allowedChildren: ['path', 'handler'],
+    },
+    apply: {
+        description: 'Apply a transform or function to data',
+        example: 'apply fn=normalize to={{rawData}}',
+        props: { fn: { kind: 'identifier' }, to: { kind: 'rawExpr' } },
+    },
+    expect: {
+        description: 'Assertion — declare an expected condition at runtime',
+        example: 'expect expr={{items.length > 0}} message="Items must not be empty"',
+        props: { expr: { required: true, kind: 'rawExpr' }, message: { kind: 'string' } },
+    },
+    recover: {
+        description: 'Recovery handler — runs when a parent node fails',
+        example: 'recover\n  handler <<<\n    return fallbackValue;\n  >>>',
+        props: {},
+        allowedChildren: ['handler'],
+    },
+    strategy: {
+        description: 'Retry/fallback strategy configuration',
+        example: 'strategy name=exponential-backoff max=3 delay=1000',
+        props: { name: { required: true, kind: 'identifier' }, max: { kind: 'number' }, delay: { kind: 'number' } },
+        allowedChildren: ['handler'],
+    },
+    // Reason layer — metadata children
+    reason: {
+        description: 'Reason annotation — explains why a decision was made',
+        example: 'reason text="Using cache to avoid repeated API calls"',
+        props: { text: { kind: 'string' } },
+    },
+    evidence: {
+        description: 'Evidence annotation — links to supporting data for a decision',
+        example: 'evidence text="Benchmarks show 3x speedup" source="perf-report.md"',
+        props: { text: { kind: 'string' }, source: { kind: 'string' } },
+    },
+    needs: {
+        description: 'Confidence gap — declares what evidence is missing',
+        example: 'needs text="Integration test for concurrent writes"',
+        props: { text: { kind: 'string' } },
+    },
+    // Rule layer — native .kern lint rules
+    rule: {
+        description: 'Custom lint rule definition — matches patterns and emits findings',
+        example: 'rule id=no-console severity=warning category=style\n  message template="Avoid console.log in production"',
+        props: {
+            id: { required: true, kind: 'identifier' },
+            severity: { kind: 'string' },
+            category: { kind: 'string' },
+            confidence: { kind: 'number' },
+        },
+        allowedChildren: ['message', 'handler'],
+    },
+    message: {
+        description: 'Rule message template — the text shown when a lint rule matches',
+        example: 'message template="Found {count} unused imports"',
+        props: { template: { kind: 'string' } },
+    },
 };
 /**
  * Validate an IR tree against the schema definitions (required props, allowed children, cross-prop rules).
@@ -433,54 +1353,90 @@ export function validateSchema(root) {
     validateNode(root, violations);
     return violations;
 }
-function validateNode(node, violations) {
-    const schema = Object.hasOwn(NODE_SCHEMAS, node.type) ? NODE_SCHEMAS[node.type] : undefined;
-    if (schema) {
-        const props = node.props || {};
-        // Check required 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,
-                });
-            }
-        }
-        // Cross-prop validation: component needs ref or name
-        if (node.type === 'component' && !('ref' in props) && !('name' in props)) {
+const UNIVERSAL_CHILDREN = new Set(['handler', 'cleanup', 'reason', 'evidence', 'needs', 'signal', 'doc']);
+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: 'component',
-                message: "'component' requires either 'ref' or 'name' prop",
+                nodeType: node.type,
+                message: `'${node.type}' requires prop '${propName}'`,
                 line: node.loc?.line,
                 col: node.loc?.col,
             });
         }
-        // Check allowed children
-        if (schema.allowedChildren && node.children) {
-            for (const child of node.children) {
-                if (!schema.allowedChildren.includes(child.type)) {
-                    // Don't flag structural children that are consumed by parents
-                    // (handler, reason, evidence, needs, etc.)
-                    const universalChildren = ['handler', 'cleanup', 'reason', 'evidence', 'needs', 'signal'];
-                    if (!universalChildren.includes(child.type)) {
-                        violations.push({
-                            nodeType: node.type,
-                            message: `'${node.type}' does not allow child type '${child.type}' (allowed: ${schema.allowedChildren.join(', ')})`,
-                            line: child.loc?.line,
-                            col: child.loc?.col,
-                        });
-                    }
-                }
-            }
+    }
+}
+function checkCrossProps(node, violations) {
+    const props = node.props || {};
+    if (node.type === 'component' && !('ref' in props) && !('name' in props)) {
+        violations.push({
+            nodeType: 'component',
+            message: "'component' requires either 'ref' or 'name' prop",
+            line: node.loc?.line,
+            col: node.loc?.col,
+        });
+    }
+    if (node.type === 'guard' && !('expr' in props) && !('kind' in props) && !('type' in props)) {
+        violations.push({
+            nodeType: 'guard',
+            message: "'guard' requires either 'expr' (assertion) or 'kind'/'type' (security guard)",
+            line: node.loc?.line,
+            col: node.loc?.col,
+        });
+    }
+}
+function checkAllowedChildren(node, schema, violations) {
+    if (!schema.allowedChildren || !node.children)
+        return;
+    for (const child of node.children) {
+        if (!schema.allowedChildren.includes(child.type) && !UNIVERSAL_CHILDREN.has(child.type)) {
+            violations.push({
+                nodeType: node.type,
+                message: `'${node.type}' does not allow child type '${child.type}' (allowed: ${schema.allowedChildren.join(', ')})`,
+                line: child.loc?.line,
+                col: child.loc?.col,
+            });
         }
     }
-    // Recurse into children
+}
+function validateNode(node, violations) {
+    const schema = Object.hasOwn(NODE_SCHEMAS, node.type) ? NODE_SCHEMAS[node.type] : undefined;
+    if (schema) {
+        checkRequiredProps(node, schema, violations);
+        checkCrossProps(node, violations);
+        checkAllowedChildren(node, schema, violations);
+    }
     if (node.children) {
-        for (const child of node.children) {
+        for (const child of node.children)
             validateNode(child, violations);
-        }
     }
 }
+/**
+ * Export the full KERN schema as a JSON-serializable object.
+ *
+ * Designed for LLM consumption — an LLM can call `kern schema --json`
+ * and use the output to generate valid `.kern` files.
+ *
+ * @param runtime - Optional KernRuntime instance (includes evolved types)
+ */
+export function exportSchemaJSON(runtime) {
+    const rt = runtime ?? defaultRuntime;
+    const schemaedTypes = new Set(Object.keys(NODE_SCHEMAS));
+    const unschemaed = NODE_TYPES.filter((t) => !schemaedTypes.has(t));
+    const evolvedTypes = [...rt.dynamicNodeTypes];
+    // Return defensive copies so callers can't mutate process-wide state
+    return {
+        version: KERN_VERSION,
+        nodeTypes: [...NODE_TYPES],
+        schemas: JSON.parse(JSON.stringify(NODE_SCHEMAS)),
+        unschemaed,
+        targets: [...VALID_TARGETS],
+        styleShorthands: { ...STYLE_SHORTHANDS },
+        valueShorthands: { ...VALUE_SHORTHANDS },
+        multilineBlockTypes: [...rt.multilineBlockTypes],
+        propKinds: ['identifier', 'typeAnnotation', 'importPath', 'rawExpr', 'rawBlock', 'string', 'boolean', 'number'],
+        ...(evolvedTypes.length > 0 ? { evolvedTypes } : {}),
+    };
+}
 //# sourceMappingURL=schema.js.map