@lokascript/framework 2.0.0 → 2.1.0

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   CrossDomainDispatcher: () => CrossDomainDispatcher,
   DEFAULT_OPERATORS: () => DEFAULT_OPERATORS,
   DEFAULT_PUNCTUATION: () => DEFAULT_PUNCTUATION,
+  DEFAULT_REFERENCES: () => DEFAULT_REFERENCES,
   DomainAwareScanner: () => DomainAwareScanner,
   DomainRegistry: () => DomainRegistry,
   GrammarTransformer: () => GrammarTransformer,
@@ -36,24 +37,31 @@ __export(index_exports, {
   NumberExtractor: () => NumberExtractor,
   OperatorExtractor: () => OperatorExtractor,
   PatternMatcher: () => PatternMatcher,
+  PatternTracker: () => PatternTracker,
   PunctuationExtractor: () => PunctuationExtractor,
   StringLiteralExtractor: () => StringLiteralExtractor,
   TokenStreamImpl: () => TokenStreamImpl,
   UnicodeIdentifierExtractor: () => UnicodeIdentifierExtractor,
   WhitespaceExtractor: () => WhitespaceExtractor,
   accumulateBlocks: () => accumulateBlocks,
+  buildDisambiguation: () => buildDisambiguation,
+  buildFeedback: () => buildFeedback,
   buildPhrase: () => buildPhrase,
   buildTablesFromProfiles: () => buildTablesFromProfiles,
   combineClassifiers: () => combineClassifiers,
+  convertValue: () => convertValue,
+  createAsyncNode: () => createAsyncNode,
   createCommandNode: () => createCommandNode,
   createCompoundNode: () => createCompoundNode,
   createConditionalNode: () => createConditionalNode,
   createDiagnosticCollector: () => createDiagnosticCollector,
   createEventHandlerNode: () => createEventHandlerNode,
   createExpression: () => createExpression,
+  createFlag: () => createFlag,
   createLatinCharClassifiers: () => createLatinCharClassifiers,
   createLiteral: () => createLiteral,
   createLoopNode: () => createLoopNode,
+  createMatchNode: () => createMatchNode,
   createMultiStatementParser: () => createMultiStatementParser,
   createMultilingualDSL: () => createMultilingualDSL,
   createPosition: () => createPosition,
@@ -64,6 +72,7 @@ __export(index_exports, {
   createSimpleTokenizer: () => createSimpleTokenizer,
   createToken: () => createToken,
   createTokenizerContext: () => createTokenizerContext,
+  createTryNode: () => createTryNode,
   createUnicodeRangeClassifier: () => createUnicodeRangeClassifier,
   defineCommand: () => defineCommand,
   defineRole: () => defineRole,
@@ -75,9 +84,15 @@ __export(index_exports, {
   extractUrl: () => extractUrl,
   extractValue: () => extractValue,
   filterBySeverity: () => filterBySeverity,
+  fromEnvelopeJSON: () => fromEnvelopeJSON,
   fromError: () => fromError,
+  fromInterchangeNode: () => fromInterchangeNode,
+  fromProtocolJSON: () => fromProtocolJSON,
+  generateExamples: () => generateExamples,
   generatePattern: () => generatePattern,
   generatePatternVariants: () => generatePatternVariants,
+  generatePrompt: () => generatePrompt,
+  generateProtocolReference: () => generateProtocolReference,
   getAllPossessiveKeywords: () => getAllPossessiveKeywords,
   getDefaultExtractors: () => getDefaultExtractors,
   getPossessiveReference: () => getPossessiveReference,
@@ -90,6 +105,8 @@ __export(index_exports, {
   isClassName: () => isClassName,
   isContextAwareExtractor: () => isContextAwareExtractor,
   isDigit: () => isDigit,
+  isEnvelope: () => isEnvelope,
+  isExplicitSyntax: () => isExplicitSyntax,
   isIdSelector: () => isIdSelector,
   isNumericValue: () => isNumericValue,
   isPossessiveKeyword: () => isPossessiveKeyword,
@@ -99,17 +116,33 @@ __export(index_exports, {
   isSelectorStart: () => isSelectorStart,
   isTypeCompatible: () => isTypeCompatible,
   isUrlStart: () => isUrlStart,
+  isValidReference: () => isValidReference2,
   isVariableRef: () => isVariableRef,
   isWhitespace: () => isWhitespace,
   joinTokens: () => joinTokens,
+  jsonToSemanticNode: () => jsonToSemanticNode,
   lookupKeyword: () => lookupKeyword,
   lookupMarker: () => lookupMarker,
   matchBest: () => matchBest,
   matchPattern: () => matchPattern,
+  needsDisambiguation: () => needsDisambiguation,
   noChange: () => noChange,
   normalized: () => normalized,
+  parseExplicit: () => parseExplicit,
+  parseJSONL: () => parseJSONL,
   patternMatcher: () => patternMatcher,
+  registryToAOTBackends: () => registryToAOTBackends,
+  renderExplicit: () => renderExplicit,
+  renderExpr: () => renderExpr,
   reorderRoles: () => reorderRoles,
+  semanticNodeToJSON: () => semanticNodeToJSON,
+  synthesizeFromSchemas: () => synthesizeFromSchemas,
+  toEnvelopeJSON: () => toEnvelopeJSON,
+  toJSONL: () => toJSONL,
+  toJSONLRow: () => toJSONLRow,
+  toProtocolJSON: () => toProtocolJSON,
+  validateProtocolJSON: () => validateProtocolJSON,
+  validateSemanticJSON: () => validateSemanticJSON,
   validateValueType: () => validateValueType,
   withDefaultExtractors: () => withDefaultExtractors
 });
@@ -131,6 +164,9 @@ function createPropertyPath(object, property) {
 function createExpression(raw) {
   return { type: "expression", raw };
 }
+function createFlag(name, enabled = true) {
+  return { type: "flag", name, enabled };
+}
 function createCommandNode(action, roles, metadata) {
   const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));
   const node = {
@@ -182,6 +218,7 @@ function createCompoundNode(statements, chainType = "sequential", metadata) {
   return metadata ? { ...base, metadata } : base;
 }
 function extractValue(value) {
+  if (value.type === "flag") return value.name;
   if ("raw" in value && value.raw !== void 0) return String(value.raw);
   if ("value" in value && value.value !== void 0) return String(value.value);
   if (value.type === "property-path") return `${extractValue(value.object)}.${value.property}`;
@@ -208,6 +245,38 @@ function createLoopNode(action, roles, loopVariant, body, loopVariable, indexVar
     ...metadata && { metadata }
   };
 }
+function createTryNode(body, catchBranch, finallyBranch, metadata) {
+  return {
+    kind: "command",
+    action: "try",
+    roles: /* @__PURE__ */ new Map(),
+    body,
+    ...catchBranch && catchBranch.length > 0 ? { catchBranch } : {},
+    ...finallyBranch && finallyBranch.length > 0 ? { finallyBranch } : {},
+    ...metadata ? { metadata } : {}
+  };
+}
+function createAsyncNode(variant, asyncBody, metadata) {
+  return {
+    kind: "command",
+    action: variant,
+    roles: /* @__PURE__ */ new Map(),
+    asyncVariant: variant,
+    asyncBody,
+    ...metadata ? { metadata } : {}
+  };
+}
+function createMatchNode(roles, arms, defaultArm, metadata) {
+  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));
+  return {
+    kind: "command",
+    action: "match",
+    roles: rolesMap,
+    arms,
+    ...defaultArm && defaultArm.length > 0 ? { defaultArm } : {},
+    ...metadata ? { metadata } : {}
+  };
+}
 
 // src/core/logger.ts
 var DebugLogger = class {
@@ -463,7 +532,7 @@ var _PatternMatcher = class _PatternMatcher {
    * a token and the immediately following pattern token fails, the matcher
    * resets to before the optional role and retries the failed token.
    */
-  matchTokenSequence(tokens, patternTokens, captured) {
+  matchTokenSequence(tokens, patternTokens, captured, parentStopMarkers) {
     const firstPatternToken = patternTokens[0];
     const patternExpectsConjunction = firstPatternToken?.type === "literal" && (firstPatternToken.value === "and" || firstPatternToken.value === "then" || firstPatternToken.alternatives?.includes("and") || firstPatternToken.alternatives?.includes("then"));
     if (this.currentProfile?.code === "ar" && !patternExpectsConjunction) {
@@ -487,6 +556,9 @@ var _PatternMatcher = class _PatternMatcher {
       );
       if (patternToken.type === "role" && patternToken.greedy) {
         const stopMarkers = this.collectStopMarkers(patternTokens, i + 1);
+        if (parentStopMarkers) {
+          for (const m of parentStopMarkers) stopMarkers.add(m);
+        }
         const values = [];
         while (!tokens.isAtEnd()) {
           const nextToken = tokens.peek();
@@ -506,8 +578,58 @@ var _PatternMatcher = class _PatternMatcher {
           return false;
         }
       }
+      if (patternToken.type === "group") {
+        const siblingStopMarkers = this.collectStopMarkers(patternTokens, i + 1);
+        if (parentStopMarkers) {
+          for (const m of parentStopMarkers) siblingStopMarkers.add(m);
+        }
+        const groupMatched = this.matchGroupToken(
+          tokens,
+          patternToken,
+          captured,
+          siblingStopMarkers
+        );
+        if (groupMatched) {
+          prevOptionalMark = null;
+          prevOptionalRole = null;
+          continue;
+        }
+        if (this.isOptional(patternToken)) {
+          continue;
+        }
+        return false;
+      }
       const isOptionalRole = patternToken.type === "role" && patternToken.optional === true;
       const markBefore = isOptionalRole ? tokens.mark() : null;
+      const isRoleToken = patternToken.type === "role";
+      if (isRoleToken && !isOptionalRole) {
+        const nextPT = i + 1 < patternTokens.length ? patternTokens[i + 1] : null;
+        if (nextPT?.type === "literal") {
+          const currentToken = tokens.peek();
+          if (currentToken && this.getMatchType(currentToken, nextPT.value) !== "none") {
+            this.logger.debug(
+              "  >> MARKER-STEAL GUARD: current token matches next literal, skipping role"
+            );
+            this.logger.debug("  >> Token match FAILED");
+            if (this.isOptional(patternToken)) {
+              continue;
+            }
+            if (prevOptionalMark && prevOptionalRole) {
+              this.logger.debug("  >> BACKTRACKING: undoing optional role", prevOptionalRole);
+              tokens.reset(prevOptionalMark);
+              captured.delete(prevOptionalRole);
+              prevOptionalMark = null;
+              prevOptionalRole = null;
+              const retryMatched = this.matchPatternToken(tokens, patternToken, captured);
+              this.logger.debug("  >> Backtrack retry result:", retryMatched);
+              if (retryMatched) {
+                continue;
+              }
+            }
+            return false;
+          }
+        }
+      }
       const matched = this.matchPatternToken(tokens, patternToken, captured);
       this.logger.debug("  >> Match result:", matched);
       if (matched) {
@@ -628,7 +750,7 @@ var _PatternMatcher = class _PatternMatcher {
     const possessiveValue = this.tryMatchPossessiveExpression(tokens);
     if (possessiveValue) {
       if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
-        if (!patternToken.expectedTypes.includes(possessiveValue.type) && !patternToken.expectedTypes.includes("expression")) {
+        if (!isTypeCompatible(possessiveValue.type, patternToken.expectedTypes)) {
           return patternToken.optional || false;
         }
       }
@@ -638,7 +760,7 @@ var _PatternMatcher = class _PatternMatcher {
     const methodCallValue = this.tryMatchMethodCallExpression(tokens);
     if (methodCallValue) {
       if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
-        if (!patternToken.expectedTypes.includes(methodCallValue.type) && !patternToken.expectedTypes.includes("expression")) {
+        if (!isTypeCompatible(methodCallValue.type, patternToken.expectedTypes)) {
           return patternToken.optional || false;
         }
       }
@@ -658,7 +780,7 @@ var _PatternMatcher = class _PatternMatcher {
     const propertyAccessValue = this.tryMatchPropertyAccessExpression(tokens);
     if (propertyAccessValue) {
       if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
-        if (!patternToken.expectedTypes.includes(propertyAccessValue.type) && !patternToken.expectedTypes.includes("expression")) {
+        if (!isTypeCompatible(propertyAccessValue.type, patternToken.expectedTypes)) {
           return patternToken.optional || false;
         }
       }
@@ -978,10 +1100,15 @@ var _PatternMatcher = class _PatternMatcher {
    * (e.g., a value like 'hello') to sit between groups without blocking later
    * marker matches.
    */
-  matchGroupToken(tokens, patternToken, captured) {
+  matchGroupToken(tokens, patternToken, captured, parentStopMarkers) {
     const mark = tokens.mark();
     const capturedBefore = new Set(captured.keys());
-    const success = this.matchTokenSequence(tokens, patternToken.tokens, captured);
+    const success = this.matchTokenSequence(
+      tokens,
+      patternToken.tokens,
+      captured,
+      parentStopMarkers
+    );
     if (success) return true;
     tokens.reset(mark);
     for (const role of captured.keys()) {
@@ -1003,7 +1130,12 @@ var _PatternMatcher = class _PatternMatcher {
             "- skipping intervening tokens"
           );
           for (let s = 0; s < offset; s++) tokens.advance();
-          const retrySuccess = this.matchTokenSequence(tokens, patternToken.tokens, captured);
+          const retrySuccess = this.matchTokenSequence(
+            tokens,
+            patternToken.tokens,
+            captured,
+            parentStopMarkers
+          );
           if (retrySuccess) return true;
           tokens.reset(mark);
           for (const role of captured.keys()) {
@@ -1070,7 +1202,7 @@ var _PatternMatcher = class _PatternMatcher {
             break;
           }
         }
-        break;
+        if (!pt.optional) break;
       }
     }
     return markers;
@@ -1080,8 +1212,9 @@ var _PatternMatcher = class _PatternMatcher {
    */
   isStopMarker(token, stopMarkers) {
     if (stopMarkers.size === 0) return false;
-    const value = (token.normalized || token.value).toLowerCase();
-    return stopMarkers.has(value);
+    if (stopMarkers.has(token.value.toLowerCase())) return true;
+    if (token.normalized && stopMarkers.has(token.normalized.toLowerCase())) return true;
+    return false;
   }
   /**
    * Convert a language token to a semantic value.
@@ -1486,7 +1619,7 @@ function addRoleWithMarker(tokens, roleSpec, profile) {
   if (marker) {
     const markerInfo = profile.roleMarkers?.[roleSpec.role];
     const defaultPosition = profile.wordOrder === "SOV" ? "after" : "before";
-    const position = markerInfo?.position ?? defaultPosition;
+    const position = roleSpec.markerPosition ?? markerInfo?.position ?? defaultPosition;
     if (isOptional) {
       if (position === "before") {
         tokens.push({
@@ -2026,6 +2159,1419 @@ function createTokenizerContext(tokenizer) {
   return ctx;
 }
 
+// src/ir/references.ts
+var DEFAULT_REFERENCES = /* @__PURE__ */ new Set([
+  "me",
+  "you",
+  "it",
+  "result",
+  "event",
+  "target",
+  "body"
+]);
+function isValidReference2(value, referenceSet = DEFAULT_REFERENCES) {
+  return referenceSet.has(value);
+}
+
+// src/ir/explicit-parser.ts
+var STRUCTURAL_ROLES = /* @__PURE__ */ new Set([
+  "body",
+  "then",
+  "else",
+  "condition",
+  "loop-body",
+  "variable",
+  "catch",
+  // v1.2: try/catch/finally
+  "finally"
+  // v1.2: try/catch/finally
+]);
+function isNestedCommand(value) {
+  const inner = value.slice(1, -1);
+  let depth = 0;
+  for (const ch of inner) {
+    if (ch === "[") depth++;
+    else if (ch === "]") depth--;
+    else if (depth === 0 && (ch === " " || ch === ":")) return true;
+  }
+  return false;
+}
+function parseExplicit(input, options = {}) {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+    throw new Error("Explicit syntax must be wrapped in brackets: [command role:value ...]");
+  }
+  const content = trimmed.slice(1, -1).trim();
+  if (!content) {
+    throw new Error("Empty explicit statement");
+  }
+  const tokens = tokenizeExplicit(content);
+  if (tokens.length === 0) {
+    throw new Error("No command specified in explicit statement");
+  }
+  const command = tokens[0].toLowerCase();
+  const roles = /* @__PURE__ */ new Map();
+  const refSet = options.referenceSet ?? DEFAULT_REFERENCES;
+  const schema = options.schemaLookup?.getSchema(command);
+  const validRoleNames = schema ? new Set(schema.roles.map((r) => r.role)) : null;
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.startsWith("+") || token.startsWith("~")) {
+      const enabled = token.startsWith("+");
+      const flagName = token.slice(1);
+      if (!flagName) {
+        throw new Error(`Empty flag name: "${token}"`);
+      }
+      if (validRoleNames && !validRoleNames.has(flagName)) {
+        const roleList = [...validRoleNames].join(", ");
+        throw new Error(
+          `Unknown flag "${flagName}" for command "${command}". Valid roles: ${roleList}`
+        );
+      }
+      roles.set(flagName, createFlag(flagName, enabled));
+      continue;
+    }
+    const colonIndex = token.indexOf(":");
+    if (colonIndex === -1) {
+      throw new Error(`Invalid role format: "${token}". Expected role:value or +flag`);
+    }
+    const roleName = token.slice(0, colonIndex);
+    if (validRoleNames && !STRUCTURAL_ROLES.has(roleName) && !validRoleNames.has(roleName)) {
+      const roleList = [...validRoleNames].join(", ");
+      throw new Error(
+        `Unknown role "${roleName}" for command "${command}". Valid roles: ${roleList}`
+      );
+    }
+    const role = roleName;
+    const valueStr = token.slice(colonIndex + 1);
+    if (STRUCTURAL_ROLES.has(roleName) && valueStr.startsWith("[") && isNestedCommand(valueStr)) {
+      const nestedEnd = findMatchingBracket(token, colonIndex + 1);
+      const nestedSyntax = token.slice(colonIndex + 1, nestedEnd + 1);
+      roles.set(role, { type: "expression", raw: nestedSyntax });
+      continue;
+    }
+    const value = parseExplicitValue(valueStr, refSet);
+    roles.set(role, value);
+  }
+  if (schema && command !== "on") {
+    for (const roleSpec of schema.roles) {
+      if (roleSpec.required && !roles.has(roleSpec.role) && !roleSpec.default) {
+        throw new Error(
+          `Missing required role "${roleSpec.role}" for command "${command}": ${roleSpec.description}`
+        );
+      }
+    }
+  }
+  switch (command) {
+    case "on": {
+      const eventValue = roles.get("event");
+      if (!eventValue) {
+        throw new Error("Event handler requires event role: [on event:click ...]");
+      }
+      const body = extractStructuralBody(roles, "body", options);
+      roles.delete("body");
+      return createEventHandlerNode("on", roles, body, {
+        sourceLanguage: "explicit"
+      });
+    }
+    case "if": {
+      const thenBranch = extractStructuralBody(roles, "then", options);
+      const elseBranch = extractStructuralBody(roles, "else", options);
+      roles.delete("then");
+      roles.delete("else");
+      return createConditionalNode(
+        command,
+        roles,
+        thenBranch,
+        elseBranch.length > 0 ? elseBranch : void 0,
+        {
+          sourceLanguage: "explicit"
+        }
+      );
+    }
+    case "repeat": {
+      const loopBody = extractStructuralBody(roles, "loop-body", options);
+      const loopVariantValue = roles.get("loop-variant");
+      const variableValue = roles.get("variable");
+      const indexVariableValue = roles.get("index-variable");
+      roles.delete("loop-body");
+      roles.delete("loop-variant");
+      roles.delete("variable");
+      roles.delete("index-variable");
+      let variant;
+      if (loopVariantValue && loopVariantValue.type === "literal" && typeof loopVariantValue.value === "string") {
+        variant = loopVariantValue.value;
+      } else if (roles.has("quantity")) {
+        variant = "times";
+      } else if (roles.has("source")) {
+        variant = "for";
+      } else if (roles.has("condition")) {
+        variant = "while";
+      } else {
+        variant = "forever";
+      }
+      const loopVariable = variableValue?.type === "literal" && typeof variableValue.value === "string" ? variableValue.value : variableValue?.type === "expression" ? variableValue.raw : void 0;
+      const indexVariable = indexVariableValue?.type === "literal" && typeof indexVariableValue.value === "string" ? indexVariableValue.value : void 0;
+      return createLoopNode(command, roles, variant, loopBody, loopVariable, indexVariable, {
+        sourceLanguage: "explicit"
+      });
+    }
+    default:
+      return createCommandNode(command, roles, {
+        sourceLanguage: "explicit"
+      });
+  }
+}
+function isExplicitSyntax(input) {
+  const trimmed = input.trim();
+  return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+function extractStructuralBody(roles, roleName, options) {
+  const value = roles.get(roleName);
+  if (!value) return [];
+  if (value.type === "expression") {
+    return [parseExplicit(value.raw, options)];
+  }
+  return [];
+}
+function inferSelectorKind(value) {
+  if (!value) return void 0;
+  if (value.startsWith("#")) return "id";
+  if (value.startsWith(".")) return "class";
+  if (value.startsWith("[")) return "attribute";
+  if (value.startsWith("<") || value.startsWith("*")) return "element";
+  if (/[>+~ ]/.test(value) && value.length > 1) return "complex";
+  return void 0;
+}
+function tokenizeExplicit(content) {
+  const tokens = [];
+  let current = "";
+  let inString = false;
+  let stringChar = "";
+  let bracketDepth = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content[i];
+    if (inString) {
+      current += char;
+      if (char === stringChar && content[i - 1] !== "\\") {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      inString = true;
+      stringChar = char;
+      current += char;
+      continue;
+    }
+    if (char === "[") {
+      bracketDepth++;
+      current += char;
+      continue;
+    }
+    if (char === "]") {
+      bracketDepth--;
+      current += char;
+      continue;
+    }
+    if (char === " " && bracketDepth === 0) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (current) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+function parseExplicitValue(valueStr, referenceSet) {
+  if (valueStr.startsWith("#") || valueStr.startsWith(".") || valueStr.startsWith("[") || valueStr.startsWith("@") || valueStr.startsWith("*")) {
+    return createSelector(valueStr, inferSelectorKind(valueStr));
+  }
+  if (valueStr.startsWith('"') || valueStr.startsWith("'")) {
+    const inner = valueStr.slice(1, -1);
+    return createLiteral(inner, "string");
+  }
+  if (valueStr === "true") return createLiteral(true, "boolean");
+  if (valueStr === "false") return createLiteral(false, "boolean");
+  const lowerRef = valueStr.toLowerCase();
+  if (isValidReference2(lowerRef, referenceSet)) {
+    return createReference(lowerRef);
+  }
+  const numMatch = valueStr.match(/^(-?\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (numMatch) {
+    const num = parseFloat(numMatch[1]);
+    const suffix = numMatch[2];
+    if (suffix) {
+      return createLiteral(valueStr, "duration");
+    }
+    return createLiteral(num, "number");
+  }
+  return createLiteral(valueStr);
+}
+function findMatchingBracket(str, start) {
+  let depth = 0;
+  for (let i = start; i < str.length; i++) {
+    if (str[i] === "[") depth++;
+    else if (str[i] === "]") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return str.length - 1;
+}
+
+// src/ir/explicit-renderer.ts
+function renderExplicit(node) {
+  if (node.kind === "compound") {
+    const compoundNode = node;
+    const renderedStatements = compoundNode.statements.map((stmt) => renderExplicit(stmt));
+    return renderedStatements.join(` ${compoundNode.chainType} `);
+  }
+  const parts = [node.action];
+  for (const [role, value] of node.roles) {
+    if (value.type === "flag") {
+      parts.push(value.enabled ? `+${value.name}` : `~${value.name}`);
+    } else {
+      parts.push(`${role}:${valueToString(value)}`);
+    }
+  }
+  if (node.kind === "event-handler") {
+    const eventNode = node;
+    if (eventNode.body && eventNode.body.length > 0) {
+      const bodyParts = eventNode.body.map((n) => renderExplicit(n));
+      parts.push(`body:${bodyParts.join(" ")}`);
+    }
+  }
+  if (node.kind === "conditional") {
+    const condNode = node;
+    if (condNode.thenBranch && condNode.thenBranch.length > 0) {
+      const thenParts = condNode.thenBranch.map((n) => renderExplicit(n));
+      parts.push(`then:${thenParts.join(" ")}`);
+    }
+    if (condNode.elseBranch && condNode.elseBranch.length > 0) {
+      const elseParts = condNode.elseBranch.map((n) => renderExplicit(n));
+      parts.push(`else:${elseParts.join(" ")}`);
+    }
+  }
+  if (node.kind === "loop") {
+    const loopNode = node;
+    if (loopNode.loopVariant) {
+      parts.push(`loop-variant:${loopNode.loopVariant}`);
+    }
+    if (loopNode.loopVariable) {
+      parts.push(`variable:${loopNode.loopVariable}`);
+    }
+    if (loopNode.indexVariable) {
+      parts.push(`index-variable:${loopNode.indexVariable}`);
+    }
+    if (loopNode.body && loopNode.body.length > 0) {
+      const bodyParts = loopNode.body.map((n) => renderExplicit(n));
+      parts.push(`loop-body:${bodyParts.join(" ")}`);
+    }
+  }
+  if (node.kind === "command") {
+    const cmd = node;
+    if (cmd.body && cmd.body.length > 0) {
+      const bodyParts = cmd.body.map((n) => renderExplicit(n));
+      parts.push(`body:${bodyParts.join(" ")}`);
+    }
+    if (cmd.catchBranch && cmd.catchBranch.length > 0) {
+      const catchParts = cmd.catchBranch.map((n) => renderExplicit(n));
+      parts.push(`catch:${catchParts.join(" ")}`);
+    }
+    if (cmd.finallyBranch && cmd.finallyBranch.length > 0) {
+      const finallyParts = cmd.finallyBranch.map((n) => renderExplicit(n));
+      parts.push(`finally:${finallyParts.join(" ")}`);
+    }
+    if (cmd.asyncVariant) {
+      parts.push(`async-variant:${cmd.asyncVariant}`);
+    }
+    if (cmd.asyncBody && cmd.asyncBody.length > 0) {
+      const asyncParts = cmd.asyncBody.map((n) => renderExplicit(n));
+      parts.push(`async-body:${asyncParts.join(" ")}`);
+    }
+  }
+  return `[${parts.join(" ")}]`;
+}
+function valueToString(value) {
+  switch (value.type) {
+    case "literal":
+      if (typeof value.value === "string") {
+        if (value.dataType === "string" || /\s/.test(value.value)) {
+          return `"${value.value}"`;
+        }
+        return value.value;
+      }
+      return String(value.value);
+    case "selector":
+      return value.value;
+    case "reference":
+      return value.value;
+    case "property-path":
+      return `${valueToString(value.object)}'s ${value.property}`;
+    case "expression":
+      return value.raw;
+    case "flag":
+      return value.name;
+  }
+}
+
+// src/ir/json-schema.ts
+var VALID_VALUE_TYPES = /* @__PURE__ */ new Set([
+  "selector",
+  "literal",
+  "reference",
+  "expression",
+  "property-path",
+  "flag"
+]);
+function validateSemanticJSON(input) {
+  const diagnostics = [];
+  if (!input.action || typeof input.action !== "string") {
+    diagnostics.push({
+      severity: "error",
+      code: "INVALID_ACTION",
+      message: 'Field "action" is required and must be a string.',
+      suggestion: 'Provide a command name like "toggle", "add", "set", etc.'
+    });
+    return diagnostics;
+  }
+  if (input.roles && typeof input.roles === "object") {
+    for (const [role, value] of Object.entries(input.roles)) {
+      if (!value || typeof value !== "object") {
+        diagnostics.push({
+          severity: "error",
+          code: "INVALID_ROLE_VALUE",
+          message: `Role "${role}" must be an object with "type" and "value" fields.`,
+          suggestion: 'Use: { "type": "selector", "value": ".active" }'
+        });
+        continue;
+      }
+      const v = value;
+      if (!VALID_VALUE_TYPES.has(v.type)) {
+        diagnostics.push({
+          severity: "error",
+          code: "INVALID_VALUE_TYPE",
+          message: `Role "${role}" has invalid type "${v.type}".`,
+          suggestion: "Valid types: selector, literal, reference, expression, property-path."
+        });
+      }
+      if (v.value === void 0 || v.value === null) {
+        diagnostics.push({
+          severity: "error",
+          code: "MISSING_VALUE",
+          message: `Role "${role}" is missing the "value" field.`
+        });
+      }
+    }
+  }
+  if (input.trigger) {
+    if (!input.trigger.event || typeof input.trigger.event !== "string") {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_TRIGGER",
+        message: 'Trigger "event" is required and must be a string.',
+        suggestion: 'Use an event name like "click", "mouseover", "keydown".'
+      });
+    }
+  }
+  return diagnostics;
+}
+function jsonToSemanticNode(input) {
+  const roles = /* @__PURE__ */ new Map();
+  if (input.roles) {
+    for (const [role, value] of Object.entries(input.roles)) {
+      roles.set(role, convertJSONValue(value));
+    }
+  }
+  if (input.trigger) {
+    roles.set("event", createLiteral(input.trigger.event, "string"));
+    const bodyRoles = new Map(roles);
+    bodyRoles.delete("event");
+    const bodyNode = createCommandNode(input.action, bodyRoles);
+    return createEventHandlerNode(
+      "on",
+      roles,
+      [bodyNode],
+      { sourceLanguage: "json" },
+      input.trigger.modifiers ?? {}
+    );
+  }
+  return createCommandNode(input.action, roles, {
+    sourceLanguage: "json"
+  });
+}
+function semanticNodeToJSON(node) {
+  if (node.kind === "compound") {
+    const compound = node;
+    if (compound.statements.length > 0) {
+      return semanticNodeToJSON(compound.statements[0]);
+    }
+    return { action: "compound", roles: {} };
+  }
+  if (node.kind === "event-handler") {
+    const eventNode = node;
+    const bodyAction = eventNode.body?.[0]?.action ?? node.action;
+    const roles2 = {};
+    if (eventNode.body?.[0]) {
+      for (const [role, value] of eventNode.body[0].roles) {
+        roles2[role] = semanticValueToJSON(value);
+      }
+    }
+    const eventValue = node.roles.get("event");
+    const eventName = eventValue ? "value" in eventValue ? String(eventValue.value) : "raw" in eventValue ? eventValue.raw : "unknown" : "unknown";
+    const result = {
+      action: bodyAction === "on" ? eventNode.body?.[0]?.action ?? "on" : bodyAction,
+      roles: roles2,
+      trigger: {
+        event: eventName
+      }
+    };
+    if (eventNode.eventModifiers && Object.keys(eventNode.eventModifiers).length > 0) {
+      result.trigger.modifiers = eventNode.eventModifiers;
+    }
+    return result;
+  }
+  const roles = {};
+  for (const [role, value] of node.roles) {
+    roles[role] = semanticValueToJSON(value);
+  }
+  return { action: node.action, roles };
+}
+function convertJSONValue(value) {
+  switch (value.type) {
+    case "selector":
+      return createSelector(String(value.value), detectSelectorKind(String(value.value)));
+    case "literal":
+      return createLiteral(
+        value.value,
+        typeof value.value === "number" ? "number" : typeof value.value === "boolean" ? "boolean" : "string"
+      );
+    case "reference":
+      return createReference(String(value.value));
+    case "expression":
+      return createExpression(String(value.value));
+    case "property-path":
+      return createExpression(String(value.value));
+    case "flag":
+      return createFlag(String(value.value), true);
+    default:
+      return createLiteral(String(value.value), "string");
+  }
+}
+function semanticValueToJSON(value) {
+  switch (value.type) {
+    case "selector":
+      return { type: "selector", value: value.value };
+    case "literal":
+      return { type: "literal", value: value.value };
+    case "reference":
+      return { type: "reference", value: value.value };
+    case "expression":
+      return { type: "expression", value: value.raw };
+    case "property-path":
+      return {
+        type: "property-path",
+        value: `${semanticValueToJSON(value.object).value}.${value.property}`
+      };
+    case "flag":
+      return { type: "flag", value: value.enabled };
+  }
+}
+function detectSelectorKind(selector) {
+  if (selector.startsWith("#")) return "id";
+  if (selector.startsWith(".")) return "class";
+  if (selector.startsWith("[")) return "attribute";
+  return "complex";
+}
+
+// src/ir/protocol-json.ts
+function toProtocolJSON(node) {
+  const roles = rolesToProtocol(node.roles);
+  let result;
+  switch (node.kind) {
+    case "command": {
+      const cmd = node;
+      result = { kind: "command", action: node.action, roles };
+      if (cmd.body && cmd.body.length > 0) {
+        result.body = cmd.body.map(toProtocolJSON);
+      }
+      if (cmd.catchBranch && cmd.catchBranch.length > 0) {
+        result.catchBranch = cmd.catchBranch.map(toProtocolJSON);
+      }
+      if (cmd.finallyBranch && cmd.finallyBranch.length > 0) {
+        result.finallyBranch = cmd.finallyBranch.map(toProtocolJSON);
+      }
+      if (cmd.asyncVariant) {
+        result.asyncVariant = cmd.asyncVariant;
+      }
+      if (cmd.asyncBody && cmd.asyncBody.length > 0) {
+        result.asyncBody = cmd.asyncBody.map(toProtocolJSON);
+      }
+      if (cmd.arms && cmd.arms.length > 0) {
+        result.arms = cmd.arms.map((arm) => ({
+          pattern: valueToProtocol(arm.pattern),
+          body: arm.body.map(toProtocolJSON)
+        }));
+      }
+      if (cmd.defaultArm && cmd.defaultArm.length > 0) {
+        result.defaultArm = cmd.defaultArm.map(toProtocolJSON);
+      }
+      break;
+    }
+    case "event-handler": {
+      const eh = node;
+      result = {
+        kind: "event-handler",
+        action: node.action,
+        roles,
+        body: eh.body.map(toProtocolJSON)
+      };
+      break;
+    }
+    case "compound": {
+      const c = node;
+      result = {
+        kind: "compound",
+        action: "compound",
+        statements: c.statements.map(toProtocolJSON),
+        chainType: c.chainType
+      };
+      break;
+    }
+    case "conditional": {
+      const cond = node;
+      result = { kind: "command", action: node.action, roles };
+      result.thenBranch = cond.thenBranch.map(toProtocolJSON);
+      if (cond.elseBranch && cond.elseBranch.length > 0) {
+        result.elseBranch = cond.elseBranch.map(toProtocolJSON);
+      }
+      break;
+    }
+    case "loop": {
+      const loop = node;
+      result = { kind: "command", action: node.action, roles };
+      result.loopVariant = loop.loopVariant;
+      result.loopBody = loop.body.map(toProtocolJSON);
+      if (loop.loopVariable) result.loopVariable = loop.loopVariable;
+      if (loop.indexVariable) result.indexVariable = loop.indexVariable;
+      break;
+    }
+  }
+  if (node.annotations && node.annotations.length > 0) {
+    result.annotations = node.annotations.map(
+      (a) => a.value !== void 0 ? { name: a.name, value: a.value } : { name: a.name }
+    );
+  }
+  if (node.diagnostics && node.diagnostics.length > 0) {
+    result.diagnostics = node.diagnostics.map((d) => ({
+      level: d.level,
+      role: d.role,
+      message: d.message,
+      code: d.code
+    }));
+  }
+  return result;
+}
+function rolesToProtocol(roles) {
+  const result = {};
+  for (const [role, value] of roles) {
+    result[role] = valueToProtocol(value);
+  }
+  return result;
+}
+function valueToProtocol(value) {
+  switch (value.type) {
+    case "selector": {
+      const PROTOCOL_SELECTOR_KINDS = /* @__PURE__ */ new Set([
+        "id",
+        "class",
+        "attribute",
+        "element",
+        "complex"
+      ]);
+      const sk = "selectorKind" in value ? value.selectorKind : void 0;
+      const sv = { type: "selector", value: value.value };
+      if (sk && PROTOCOL_SELECTOR_KINDS.has(sk)) {
+        sv.selectorKind = sk;
+      }
+      return sv;
+    }
+    case "literal":
+      return value.dataType ? { type: "literal", value: value.value, dataType: value.dataType } : { type: "literal", value: value.value };
+    case "reference":
+      return { type: "reference", value: value.value };
+    case "expression":
+      return { type: "expression", raw: value.raw };
+    case "property-path":
+      return { type: "expression", raw: extractValue(value) };
+    case "flag":
+      return { type: "flag", name: value.name, enabled: value.enabled };
+  }
+}
+function fromProtocolJSON(json) {
+  const roles = new Map(
+    Object.entries(json.roles ?? {}).map(([role, val]) => [role, valueFromProtocol(val)])
+  );
+  const annotations = json.annotations?.map(
+    (a) => a.value !== void 0 ? { name: a.name, value: a.value } : { name: a.name }
+  );
+  const diagnostics = json.diagnostics?.map((d) => ({
+    level: d.level,
+    role: d.role,
+    message: d.message,
+    code: d.code
+  }));
+  if (json.trigger) {
+    const eventName = json.trigger.event;
+    roles.set("event", createLiteral(eventName, "string"));
+    const bodyRoles = new Map(roles);
+    bodyRoles.delete("event");
+    const bodyNode = createCommandNode(json.action, bodyRoles);
+    const node2 = createEventHandlerNode(
+      "on",
+      roles,
+      [bodyNode],
+      { sourceLanguage: "json" },
+      json.trigger.modifiers ?? {}
+    );
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  const kind = json.kind ?? "command";
+  if (kind === "event-handler") {
+    const body = (json.body ?? []).map(fromProtocolJSON);
+    const node2 = createEventHandlerNode(json.action, roles, body);
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (kind === "compound") {
+    const statements = (json.statements ?? []).map(fromProtocolJSON);
+    const node2 = createCompoundNode(
+      statements,
+      json.chainType ?? "sequential"
+    );
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (json.thenBranch && json.thenBranch.length > 0) {
+    const thenBranch = json.thenBranch.map(fromProtocolJSON);
+    const elseBranch = json.elseBranch ? json.elseBranch.map(fromProtocolJSON) : void 0;
+    const node2 = createConditionalNode(json.action, roles, thenBranch, elseBranch);
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (json.loopVariant) {
+    const loopBody = (json.loopBody ?? []).map(fromProtocolJSON);
+    const node2 = createLoopNode(
+      json.action,
+      roles,
+      json.loopVariant,
+      loopBody,
+      json.loopVariable,
+      json.indexVariable
+    );
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (json.catchBranch || json.finallyBranch) {
+    const body = (json.body ?? []).map(fromProtocolJSON);
+    const catchBranch = json.catchBranch ? json.catchBranch.map(fromProtocolJSON) : void 0;
+    const finallyBranch = json.finallyBranch ? json.finallyBranch.map(fromProtocolJSON) : void 0;
+    const node2 = createTryNode(body, catchBranch, finallyBranch);
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (json.asyncVariant) {
+    const asyncBody = (json.asyncBody ?? []).map(fromProtocolJSON);
+    const node2 = createAsyncNode(json.asyncVariant, asyncBody);
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (json.arms && json.arms.length > 0) {
+    const arms = json.arms.map((arm) => ({
+      pattern: valueFromProtocol(arm.pattern),
+      body: arm.body.map(fromProtocolJSON)
+    }));
+    const defaultArm = json.defaultArm ? json.defaultArm.map(fromProtocolJSON) : void 0;
+    const node2 = createMatchNode(roles, arms, defaultArm);
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  if (json.body && json.body.length > 0 && kind === "command") {
+    const body = json.body.map(fromProtocolJSON);
+    const node2 = createTryNode(body);
+    return applyV12Metadata(node2, annotations, diagnostics);
+  }
+  const node = createCommandNode(json.action, roles);
+  return applyV12Metadata(node, annotations, diagnostics);
+}
+function applyV12Metadata(node, annotations, diagnostics) {
+  if ((!annotations || annotations.length === 0) && (!diagnostics || diagnostics.length === 0)) {
+    return node;
+  }
+  return {
+    ...node,
+    ...annotations && annotations.length > 0 ? { annotations } : {},
+    ...diagnostics && diagnostics.length > 0 ? { diagnostics } : {}
+  };
+}
+function valueFromProtocol(value) {
+  switch (value.type) {
+    case "selector":
+      return createSelector(String(value.value ?? ""), value.selectorKind);
+    case "literal":
+      return createLiteral(
+        value.value !== void 0 ? value.value : "",
+        value.dataType
+      );
+    case "reference":
+      return createReference(String(value.value ?? ""));
+    case "expression":
+      return createExpression(value.raw ?? String(value.value ?? ""));
+    case "flag":
+      return createFlag(
+        value.name ?? String(value.value ?? ""),
+        value.enabled ?? (typeof value.value === "boolean" ? value.value : true)
+      );
+    case "property-path":
+      return createExpression(String(value.value ?? value.raw ?? ""));
+  }
+}
+function toEnvelopeJSON(envelope) {
+  const result = {
+    lseVersion: envelope.lseVersion,
+    nodes: envelope.nodes.map(toProtocolJSON)
+  };
+  if (envelope.features && envelope.features.length > 0) {
+    result.features = [...envelope.features];
+  }
+  return result;
+}
+function fromEnvelopeJSON(json) {
+  return {
+    lseVersion: json.lseVersion,
+    ...json.features && json.features.length > 0 ? { features: json.features } : {},
+    nodes: json.nodes.map(fromProtocolJSON)
+  };
+}
+function isEnvelope(json) {
+  return typeof json === "object" && json !== null && "lseVersion" in json && "nodes" in json && Array.isArray(json.nodes);
+}
+var VALID_KINDS = /* @__PURE__ */ new Set(["command", "event-handler", "compound"]);
+var VALID_VALUE_TYPES2 = /* @__PURE__ */ new Set([
+  "selector",
+  "literal",
+  "reference",
+  "expression",
+  "property-path",
+  "flag"
+]);
+var VALID_CHAIN_TYPES = /* @__PURE__ */ new Set(["then", "and", "async", "sequential", "pipe"]);
+var VALID_ASYNC_VARIANTS = /* @__PURE__ */ new Set(["all", "race"]);
+var VALID_DIAGNOSTIC_LEVELS = /* @__PURE__ */ new Set(["error", "warning"]);
+function validateProtocolJSON(json) {
+  const diagnostics = [];
+  if (typeof json !== "object" || json === null) {
+    return [{ severity: "error", code: "INVALID_ROOT", message: "Root must be a JSON object" }];
+  }
+  const node = json;
+  const kind = "kind" in node ? String(node.kind) : "command";
+  if ("kind" in node && !VALID_KINDS.has(kind)) {
+    diagnostics.push({
+      severity: "error",
+      code: "INVALID_KIND",
+      message: `Invalid kind "${node.kind}". Must be one of: command, event-handler, compound`
+    });
+  }
+  if (!("action" in node)) {
+    diagnostics.push({
+      severity: "error",
+      code: "MISSING_ACTION",
+      message: "Missing required field: action"
+    });
+  } else if (typeof node.action !== "string" || node.action.length === 0) {
+    diagnostics.push({
+      severity: "error",
+      code: "INVALID_ACTION",
+      message: "action must be a non-empty string"
+    });
+  }
+  if (!("roles" in node) && kind !== "compound") {
+    diagnostics.push({
+      severity: "error",
+      code: "MISSING_ROLES",
+      message: "Missing required field: roles"
+    });
+  } else if ("roles" in node && (typeof node.roles !== "object" || node.roles === null || Array.isArray(node.roles))) {
+    diagnostics.push({
+      severity: "error",
+      code: "INVALID_ROLES",
+      message: "roles must be a plain object"
+    });
+  } else if ("roles" in node && node.roles) {
+    for (const [role, value] of Object.entries(node.roles)) {
+      if (typeof value !== "object" || value === null) {
+        diagnostics.push({
+          severity: "error",
+          code: "INVALID_ROLE_VALUE",
+          message: `Role "${role}" value must be an object`
+        });
+        continue;
+      }
+      const v = value;
+      if (!("type" in v) || !VALID_VALUE_TYPES2.has(String(v.type))) {
+        diagnostics.push({
+          severity: "error",
+          code: "INVALID_VALUE_TYPE",
+          message: `Role "${role}" has invalid type "${v.type}"`
+        });
+      }
+      if (v.type === "flag") {
+        const hasName = typeof v.name === "string";
+        const hasEnabled = typeof v.enabled === "boolean";
+        const hasValue = "value" in v;
+        if (!hasName && !hasValue) {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_FLAG_NAME",
+            message: `Flag role "${role}" missing required field: name (or value)`
+          });
+        }
+        if (!hasEnabled && !hasValue) {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_FLAG_ENABLED",
+            message: `Flag role "${role}" missing required field: enabled (or value)`
+          });
+        }
+      }
+      if (v.type === "expression" && typeof v.raw !== "string" && !("value" in v)) {
+        diagnostics.push({
+          severity: "error",
+          code: "MISSING_EXPRESSION_RAW",
+          message: `Expression role "${role}" missing required field: raw (or value)`
+        });
+      }
+    }
+  }
+  if ("trigger" in node && node.trigger) {
+    const trigger = node.trigger;
+    if (typeof trigger !== "object" || trigger === null) {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_TRIGGER",
+        message: "trigger must be an object"
+      });
+    } else if (!trigger.event || typeof trigger.event !== "string") {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_TRIGGER",
+        message: "trigger.event is required and must be a non-empty string"
+      });
+    }
+  }
+  if (kind === "event-handler" && !("trigger" in node)) {
+    if (!("body" in node) || !Array.isArray(node.body)) {
+      diagnostics.push({
+        severity: "error",
+        code: "MISSING_BODY",
+        message: "event-handler node requires a body array"
+      });
+    }
+  }
+  if (kind === "compound") {
+    if (!("statements" in node) || !Array.isArray(node.statements)) {
+      diagnostics.push({
+        severity: "error",
+        code: "MISSING_STATEMENTS",
+        message: "compound node requires a statements array"
+      });
+    }
+    if ("chainType" in node && !VALID_CHAIN_TYPES.has(String(node.chainType))) {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_CHAIN_TYPE",
+        message: `Invalid chainType "${node.chainType}". Must be one of: then, and, async, sequential, pipe`
+      });
+    }
+  }
+  if ("diagnostics" in node) {
+    if (!Array.isArray(node.diagnostics)) {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_DIAGNOSTICS",
+        message: "diagnostics must be an array"
+      });
+    } else {
+      for (let i = 0; i < node.diagnostics.length; i++) {
+        const d = node.diagnostics[i];
+        if (!d || typeof d !== "object") {
+          diagnostics.push({
+            severity: "error",
+            code: "INVALID_DIAGNOSTIC_ENTRY",
+            message: `diagnostics[${i}] must be an object`
+          });
+          continue;
+        }
+        if (!VALID_DIAGNOSTIC_LEVELS.has(String(d.level))) {
+          diagnostics.push({
+            severity: "error",
+            code: "INVALID_DIAGNOSTIC_LEVEL",
+            message: `diagnostics[${i}].level must be "error" or "warning"`
+          });
+        }
+        if (typeof d.role !== "string") {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_DIAGNOSTIC_ROLE",
+            message: `diagnostics[${i}] missing required field: role`
+          });
+        }
+        if (typeof d.message !== "string") {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_DIAGNOSTIC_MESSAGE",
+            message: `diagnostics[${i}] missing required field: message`
+          });
+        }
+        if (typeof d.code !== "string") {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_DIAGNOSTIC_CODE",
+            message: `diagnostics[${i}] missing required field: code`
+          });
+        }
+      }
+    }
+  }
+  if ("annotations" in node) {
+    if (!Array.isArray(node.annotations)) {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_ANNOTATIONS",
+        message: "annotations must be an array"
+      });
+    } else {
+      for (let i = 0; i < node.annotations.length; i++) {
+        const a = node.annotations[i];
+        if (!a || typeof a !== "object") {
+          diagnostics.push({
+            severity: "error",
+            code: "INVALID_ANNOTATION_ENTRY",
+            message: `annotations[${i}] must be an object`
+          });
+          continue;
+        }
+        if (typeof a.name !== "string" || a.name.length === 0) {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_ANNOTATION_NAME",
+            message: `annotations[${i}] missing required field: name`
+          });
+        }
+      }
+    }
+  }
+  if ("asyncVariant" in node && !VALID_ASYNC_VARIANTS.has(String(node.asyncVariant))) {
+    diagnostics.push({
+      severity: "error",
+      code: "INVALID_ASYNC_VARIANT",
+      message: `Invalid asyncVariant "${node.asyncVariant}". Must be "all" or "race"`
+    });
+  }
+  if ("arms" in node) {
+    if (!Array.isArray(node.arms)) {
+      diagnostics.push({
+        severity: "error",
+        code: "INVALID_ARMS",
+        message: "arms must be an array"
+      });
+    } else {
+      for (let i = 0; i < node.arms.length; i++) {
+        const arm = node.arms[i];
+        if (!arm || typeof arm !== "object") {
+          diagnostics.push({
+            severity: "error",
+            code: "INVALID_ARM_ENTRY",
+            message: `arms[${i}] must be an object`
+          });
+          continue;
+        }
+        if (!arm.pattern || typeof arm.pattern !== "object") {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_ARM_PATTERN",
+            message: `arms[${i}] missing required field: pattern`
+          });
+        }
+        if (!Array.isArray(arm.body)) {
+          diagnostics.push({
+            severity: "error",
+            code: "MISSING_ARM_BODY",
+            message: `arms[${i}] missing required field: body (array)`
+          });
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+
+// src/ir/from-interchange.ts
+function fromInterchangeNode(node) {
+  if (!node || typeof node !== "object") {
+    return createCommandNode("unknown", {});
+  }
+  switch (node.type) {
+    case "event":
+      return convertEvent(node);
+    case "command":
+      return convertCommand(node);
+    case "if":
+      return convertIf(node);
+    case "repeat":
+      return convertRepeat(node);
+    case "foreach":
+      return convertForEach(node);
+    case "while":
+      return convertWhile(node);
+    // Expression nodes — wrap as `get` command with patient role
+    default:
+      return createCommandNode("get", { patient: convertValue(node) });
+  }
+}
+function convertEvent(node) {
+  const event = String(node.event ?? "click");
+  const bodyNodes = Array.isArray(node.body) ? node.body : [];
+  const body = bodyNodes.map(fromInterchangeNode);
+  const roles = {
+    event: createLiteral(event)
+  };
+  if (node.target && typeof node.target === "object") {
+    roles.source = convertValue(node.target);
+  }
+  const modifiers = node.modifiers;
+  let eventModifiers;
+  if (modifiers) {
+    eventModifiers = bridgeEventModifiers(modifiers);
+    if (modifiers.prevent) roles.prevent = createLiteral(true);
+    if (modifiers.stop) roles.stop = createLiteral(true);
+    if (modifiers.passive) roles.passive = createLiteral(true);
+    if (modifiers.capture) roles.capture = createLiteral(true);
+  }
+  return createEventHandlerNode("on", roles, body, void 0, eventModifiers);
+}
+function convertCommand(node) {
+  const name = String(node.name ?? "unknown");
+  const args = Array.isArray(node.args) ? node.args : [];
+  const target = node.target && typeof node.target === "object" ? node.target : void 0;
+  const existingRoles = node.roles;
+  const modifiers = node.modifiers;
+  let roles;
+  if (existingRoles && typeof existingRoles === "object" && Object.keys(existingRoles).length > 0) {
+    roles = {};
+    for (const [role, value] of Object.entries(existingRoles)) {
+      if (value && typeof value === "object" && "type" in value) {
+        roles[role] = convertValue(value);
+      }
+    }
+  } else {
+    roles = inferRoles(name, args, modifiers, target);
+  }
+  return createCommandNode(name, roles);
+}
+function convertIf(node) {
+  const condition = node.condition && typeof node.condition === "object" ? convertValue(node.condition) : createExpression("true");
+  const thenBody = Array.isArray(node.thenBranch) ? node.thenBranch : [];
+  const thenBranch = thenBody.map(fromInterchangeNode);
+  let elseBranch;
+  const elseIfBranches = node.elseIfBranches;
+  if (elseIfBranches && elseIfBranches.length > 0) {
+    elseBranch = [chainElseIfs(elseIfBranches, node.elseBranch)];
+  } else if (Array.isArray(node.elseBranch) && node.elseBranch.length > 0) {
+    elseBranch = node.elseBranch.map(fromInterchangeNode);
+  }
+  const roles = { condition };
+  return createConditionalNode("if", roles, thenBranch, elseBranch);
+}
+function chainElseIfs(branches, finalElse) {
+  const [first, ...rest] = branches;
+  const condition = convertValue(first.condition);
+  const thenBranch = first.body.map(fromInterchangeNode);
+  let elseBranch;
+  if (rest.length > 0) {
+    elseBranch = [chainElseIfs(rest, finalElse)];
+  } else if (finalElse && finalElse.length > 0) {
+    elseBranch = finalElse.map(fromInterchangeNode);
+  }
+  return createConditionalNode("if", { condition }, thenBranch, elseBranch);
+}
+function convertRepeat(node) {
+  const bodyNodes = Array.isArray(node.body) ? node.body : [];
+  const body = bodyNodes.map(fromInterchangeNode);
+  const roles = {};
+  let variant;
+  if (node.count !== void 0 && node.count !== null) {
+    variant = "times";
+    if (typeof node.count === "number") {
+      roles.quantity = createLiteral(node.count, "number");
+    } else if (typeof node.count === "object") {
+      roles.quantity = convertValue(node.count);
+    }
+  } else if (node.whileCondition && typeof node.whileCondition === "object") {
+    variant = "while";
+    roles.condition = convertValue(node.whileCondition);
+  } else if (typeof node.untilEvent === "string") {
+    variant = "until";
+    roles.condition = createLiteral(node.untilEvent);
+  } else {
+    variant = "forever";
+  }
+  return createLoopNode("repeat", roles, variant, body);
+}
+function convertForEach(node) {
+  const bodyNodes = Array.isArray(node.body) ? node.body : [];
+  const body = bodyNodes.map(fromInterchangeNode);
+  const roles = {};
+  if (node.collection && typeof node.collection === "object") {
+    roles.source = convertValue(node.collection);
+  }
+  const itemName = typeof node.itemName === "string" ? node.itemName : void 0;
+  const indexName = typeof node.indexName === "string" ? node.indexName : void 0;
+  return createLoopNode("repeat", roles, "for", body, itemName, indexName);
+}
+function convertWhile(node) {
+  const bodyNodes = Array.isArray(node.body) ? node.body : [];
+  const body = bodyNodes.map(fromInterchangeNode);
+  const roles = {};
+  if (node.condition && typeof node.condition === "object") {
+    roles.condition = convertValue(node.condition);
+  }
+  return createLoopNode("repeat", roles, "while", body);
+}
+function convertValue(node) {
+  switch (node.type) {
+    case "literal":
+      return convertLiteral(node);
+    case "selector":
+      return createSelector(String(node.value ?? ""), inferSelectorKind2(String(node.value ?? "")));
+    case "identifier":
+      return convertIdentifier(node);
+    case "variable":
+      return convertVariable(node);
+    case "possessive":
+      return createPropertyPath(
+        node.object && typeof node.object === "object" ? convertValue(node.object) : createReference("me"),
+        String(node.property ?? "")
+      );
+    // Complex expressions → collapse to raw string
+    case "binary":
+    case "unary":
+    case "member":
+    case "call":
+    case "positional":
+      return createExpression(renderExpr(node));
+    default:
+      if ("value" in node) return createLiteral(String(node.value ?? ""));
+      return createExpression(renderExpr(node));
+  }
+}
+function convertLiteral(node) {
+  const value = node.value;
+  if (value === null || value === void 0) return createLiteral("null");
+  const dataType = typeof value === "number" ? "number" : typeof value === "boolean" ? "boolean" : void 0;
+  return createLiteral(value, dataType);
+}
+function convertIdentifier(node) {
+  const value = String(node.value ?? "");
+  if (DEFAULT_REFERENCES.has(value)) {
+    return createReference(value);
+  }
+  return createLiteral(value);
+}
+function convertVariable(node) {
+  const name = String(node.name ?? "");
+  const scope = String(node.scope ?? "local");
+  switch (scope) {
+    case "element":
+      return createExpression(`:${name}`);
+    case "global":
+      return createExpression(`$${name}`);
+    default:
+      return createExpression(name);
+  }
+}
+function renderExpr(node) {
+  if (!node || typeof node !== "object") return "";
+  switch (node.type) {
+    case "literal": {
+      const v = node.value;
+      if (v === null || v === void 0) return "null";
+      if (typeof v === "string") return /\s/.test(v) ? `"${v}"` : v;
+      return String(v);
+    }
+    case "identifier":
+      return String(node.value ?? "");
+    case "selector":
+      return String(node.value ?? "");
+    case "variable": {
+      const name = String(node.name ?? "");
+      const scope = String(node.scope ?? "local");
+      if (scope === "element") return `:${name}`;
+      if (scope === "global") return `$${name}`;
+      return name;
+    }
+    case "binary": {
+      const left = node.left && typeof node.left === "object" ? renderExpr(node.left) : "";
+      const right = node.right && typeof node.right === "object" ? renderExpr(node.right) : "";
+      return `${left} ${node.operator ?? ""} ${right}`;
+    }
+    case "unary": {
+      const operand = node.operand && typeof node.operand === "object" ? renderExpr(node.operand) : "";
+      return `${node.operator ?? ""} ${operand}`;
+    }
+    case "member": {
+      const obj = node.object && typeof node.object === "object" ? renderExpr(node.object) : "";
+      if (node.computed && node.property && typeof node.property === "object") {
+        return `${obj}[${renderExpr(node.property)}]`;
+      }
+      const prop = typeof node.property === "string" ? node.property : node.property && typeof node.property === "object" ? renderExpr(node.property) : "";
+      return `${obj}.${prop}`;
+    }
+    case "possessive": {
+      const obj = node.object && typeof node.object === "object" ? renderExpr(node.object) : "";
+      return `${obj}'s ${node.property ?? ""}`;
+    }
+    case "call": {
+      const callee = node.callee && typeof node.callee === "object" ? renderExpr(node.callee) : "";
+      const args = Array.isArray(node.args) ? node.args.map((a) => renderExpr(a)).join(", ") : "";
+      return `${callee}(${args})`;
+    }
+    case "positional": {
+      const target = node.target && typeof node.target === "object" ? renderExpr(node.target) : "";
+      return target ? `${node.position ?? ""} ${target}` : String(node.position ?? "");
+    }
+    default:
+      if ("value" in node) return String(node.value ?? "");
+      return "";
+  }
+}
+function inferRoles(name, args, modifiers, target) {
+  const roles = {};
+  switch (name) {
+    case "set": {
+      if (args[0]) roles.destination = convertValue(args[0]);
+      const toVal = modifiers?.to;
+      if (toVal && typeof toVal === "object" && "type" in toVal) {
+        roles.patient = convertValue(toVal);
+      } else if (args[1]) {
+        roles.patient = convertValue(args[1]);
+      }
+      break;
+    }
+    case "put": {
+      if (args[0]) roles.patient = convertValue(args[0]);
+      if (modifiers) {
+        for (const key of ["into", "before", "after"]) {
+          const val = modifiers[key];
+          if (val && typeof val === "object" && "type" in val) {
+            roles.destination = convertValue(val);
+            roles.method = createLiteral(key);
+            break;
+          }
+        }
+      }
+      if (!roles.destination && target) {
+        roles.destination = convertValue(target);
+      }
+      break;
+    }
+    case "increment":
+    case "decrement": {
+      if (args[0]) roles.destination = convertValue(args[0]);
+      const byVal = modifiers?.by;
+      if (byVal && typeof byVal === "object" && "type" in byVal) {
+        roles.quantity = convertValue(byVal);
+      } else if (args[1]) {
+        roles.quantity = convertValue(args[1]);
+      }
+      break;
+    }
+    case "fetch": {
+      if (args[0]) roles.source = convertValue(args[0]);
+      const asVal = modifiers?.as;
+      if (asVal && typeof asVal === "object" && "type" in asVal) {
+        roles.responseType = convertValue(asVal);
+      } else if (typeof asVal === "string") {
+        roles.responseType = createLiteral(asVal);
+      }
+      break;
+    }
+    case "wait":
+    case "settle": {
+      if (args[0]) roles.duration = convertValue(args[0]);
+      break;
+    }
+    case "toggle":
+    case "add":
+    case "show":
+    case "hide": {
+      if (args[0]) roles.patient = convertValue(args[0]);
+      if (target) roles.destination = convertValue(target);
+      break;
+    }
+    case "remove": {
+      if (args[0]) roles.patient = convertValue(args[0]);
+      if (target) roles.source = convertValue(target);
+      break;
+    }
+    case "send":
+    case "trigger": {
+      if (args[0]) roles.patient = convertValue(args[0]);
+      if (target) roles.destination = convertValue(target);
+      break;
+    }
+    case "log": {
+      if (args[0]) roles.patient = convertValue(args[0]);
+      break;
+    }
+    default: {
+      if (args[0]) roles.patient = convertValue(args[0]);
+      if (target) roles.destination = convertValue(target);
+      break;
+    }
+  }
+  return roles;
+}
+function inferSelectorKind2(value) {
+  if (!value) return void 0;
+  if (value.startsWith("#")) return "id";
+  if (value.startsWith(".")) return "class";
+  if (value.startsWith("[")) return "attribute";
+  if (value.startsWith("<") || value.startsWith("*")) return "element";
+  if (/[>\+~ ]/.test(value) && value.length > 1) return "complex";
+  return void 0;
+}
+function inferValueFromString(value) {
+  if (DEFAULT_REFERENCES.has(value)) return createReference(value);
+  const kind = inferSelectorKind2(value);
+  if (kind) return createSelector(value, kind);
+  return createLiteral(value);
+}
+function bridgeEventModifiers(mods) {
+  const once = mods.once === true ? true : void 0;
+  const debounce = typeof mods.debounce === "number" ? mods.debounce : void 0;
+  const throttle = typeof mods.throttle === "number" ? mods.throttle : void 0;
+  const from = typeof mods.from === "string" ? inferValueFromString(mods.from) : void 0;
+  if (once === void 0 && debounce === void 0 && throttle === void 0 && from === void 0) {
+    return void 0;
+  }
+  return {
+    ...once !== void 0 ? { once } : {},
+    ...debounce !== void 0 ? { debounce } : {},
+    ...throttle !== void 0 ? { throttle } : {},
+    ...from !== void 0 ? { from } : {}
+  };
+}
+
 // src/api/create-dsl.ts
 var DSLRegistry = class {
   constructor(config) {
@@ -2063,12 +3609,23 @@ var MultilingualDSLImpl = class {
     if (config.codeGenerator) {
       this.codeGenerator = config.codeGenerator;
     }
+    const schemaMap = new Map(config.schemas.map((s) => [s.action, s]));
+    this.schemaLookup = {
+      getSchema: (action) => schemaMap.get(action)
+    };
   }
   parse(input, language) {
     const result = this.parseWithConfidence(input, language);
     return result.node;
   }
   parseWithConfidence(input, language) {
+    if (isExplicitSyntax(input)) {
+      const node = parseExplicit(input, { schemaLookup: this.schemaLookup });
+      if (!this.schemaLookup.getSchema(node.action)) {
+        throw new Error(`No schema for action "${node.action}" in this DSL`);
+      }
+      return { node, confidence: 1 };
+    }
     const tokenizer = this.registry.getTokenizer(language);
     if (!tokenizer) {
       throw new Error(`No tokenizer registered for language: ${language}`);
@@ -2104,75 +3661,802 @@ var MultilingualDSLImpl = class {
         valid: true,
         node: result.node
       };
-    } catch (error) {
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [error instanceof Error ? error.message : String(error)]
+      };
+    }
+  }
+  translate(input, fromLanguage, toLanguage) {
+    if (isExplicitSyntax(input)) return input;
+    return this.transformer.transform(input, fromLanguage, toLanguage);
+  }
+  compile(input, language) {
+    if (!this.codeGenerator) {
+      return {
+        ok: false,
+        errors: ["No code generator configured for this DSL"]
+      };
+    }
+    try {
+      const result = this.parseWithConfidence(input, language);
+      const code = this.codeGenerator.generate(result.node);
+      return {
+        ok: true,
+        code,
+        node: result.node,
+        metadata: {
+          parser: "semantic",
+          confidence: result.confidence
+        }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        errors: [error instanceof Error ? error.message : String(error)]
+      };
+    }
+  }
+  getSupportedLanguages() {
+    return this.registry.getSupportedLanguages();
+  }
+};
+function createDefaultDictionary(config) {
+  const translations = {};
+  for (const lang of config.languages) {
+    const keywords = {};
+    for (const [canonical, keywordDef] of Object.entries(lang.patternProfile.keywords)) {
+      keywords[canonical] = keywordDef.primary;
+    }
+    translations[lang.code] = keywords;
+  }
+  return new InMemoryDictionary(translations);
+}
+function createDefaultProfileProvider(config) {
+  const profiles = {};
+  for (const lang of config.languages) {
+    if (lang.grammarProfile) {
+      profiles[lang.code] = lang.grammarProfile;
+    }
+  }
+  return new InMemoryProfileProvider(profiles);
+}
+function createMultilingualDSL(config) {
+  const dictionary = config.dictionary ?? createDefaultDictionary(config);
+  const profileProvider = config.profileProvider ?? createDefaultProfileProvider(config);
+  const transformer = new GrammarTransformer({
+    dictionary,
+    profileProvider
+  });
+  const registry = new DSLRegistry(config);
+  return new MultilingualDSLImpl(config, registry, transformer);
+}
+
+// src/prompts/prompt-generator.ts
+function generatePrompt(config) {
+  const outputFormat = config.outputFormat ?? "both";
+  const examplesPerCommand = config.examplesPerCommand ?? 2;
+  const sections = [
+    buildProtocolSection(),
+    buildValueTypeSection(),
+    buildCommandsSection(config.schemas, outputFormat, examplesPerCommand),
+    buildOutputFormatSection(outputFormat),
+    buildErrorRecoverySection()
+  ];
+  let finalSections = sections;
+  if (config.maxTokens && config.maxTokens > 0) {
+    finalSections = truncateToTokenBudget(sections, config.maxTokens);
+  }
+  const text = finalSections.map((s) => `## ${s.title}
+
+${s.content}`).join("\n\n---\n\n");
+  const totalRoles = config.schemas.reduce((sum, s) => sum + s.roles.length, 0);
+  const approximateTokens = estimateTokens(text);
+  const metadata = {
+    domain: config.domain,
+    commandCount: config.schemas.length,
+    roleCount: totalRoles,
+    approximateTokens
+  };
+  return { text, sections: finalSections, metadata };
+}
+function generateExamples(schema, count = 2) {
+  const combos = generateRoleCombinations(schema);
+  const examples = [];
+  for (let i = 0; i < Math.min(count, combos.length); i++) {
+    const combo = combos[i];
+    const roles = /* @__PURE__ */ new Map();
+    for (const role of combo) {
+      const sample = sampleValue(role);
+      roles.set(role.role, sample);
+    }
+    const nodeRoles = /* @__PURE__ */ new Map();
+    for (const [roleName, sample] of roles) {
+      nodeRoles.set(roleName, toSemanticValue(sample));
+    }
+    const node = createCommandNode(schema.action, nodeRoles);
+    const explicit = renderExplicit(node);
+    const jsonRoles = {};
+    for (const [roleName, sample] of roles) {
+      jsonRoles[roleName] = sample;
+    }
+    const json = { action: schema.action, roles: jsonRoles };
+    examples.push({ explicit, json });
+  }
+  return examples;
+}
+function generateProtocolReference() {
+  const protocol = buildProtocolSection();
+  const valueTypes = buildValueTypeSection();
+  return `# LokaScript Explicit Syntax (LSE) Quick Reference
+
+${protocol.content}
+
+${valueTypes.content}`;
+}
+function buildProtocolSection() {
+  const content = `LokaScript Explicit Syntax (LSE) is a bracket-based format for imperative commands.
+
+### Syntax
+
+\`\`\`
+[command role1:value1 role2:value2 +flag1 ~flag2]
+\`\`\`
+
+- **Command**: The first token inside brackets (lowercased)
+- **Role pair**: \`name:value\` \u2014 a named semantic role with a typed value (no space around colon)
+- **Enabled flag**: \`+name\` \u2014 boolean attribute present
+- **Disabled flag**: \`~name\` \u2014 boolean attribute negated
+- **Nested body**: \`body:[command ...]\` \u2014 a bracket command inside a role value
+
+### Rules
+
+1. Commands are always lowercased
+2. Role names preserve their original case
+3. No spaces around the colon in role:value pairs
+4. Strings with spaces must be quoted: \`patient:"hello world"\`
+5. Selectors start with \`#\`, \`.\`, \`[\`, \`@\`, or \`*\`
+6. Output must be valid bracket syntax: \`[action role:value ...]\``;
+  return {
+    id: "protocol",
+    title: "LSE Protocol",
+    content,
+    approximateTokens: estimateTokens(content)
+  };
+}
+function buildValueTypeSection() {
+  const content = `Values in LSE are classified by their syntactic form (first match wins):
+
+| Type | Syntax | Example |
+|------|--------|---------|
+| Selector | Starts with \`#\` \`.\` \`[\` \`@\` \`*\` | \`#button\`, \`.active\`, \`[data-id]\` |
+| String | Quoted with \`"\` or \`'\` | \`"hello world"\`, \`'json'\` |
+| Boolean | Exact: \`true\` / \`false\` | \`visible:true\` |
+| Reference | Built-in name | \`me\`, \`you\`, \`it\`, \`result\`, \`event\`, \`target\`, \`body\` |
+| Duration | Number + suffix | \`500ms\`, \`2s\`, \`1m\`, \`1h\` |
+| Number | Digits with optional decimal | \`5\`, \`3.14\`, \`-1\` |
+| Plain | Fallback (any non-whitespace) | \`/api/users\`, \`json\`, \`production\` |
+
+**Important**: Classification is by prefix, not by intent. \`#true\` is a selector (not boolean). \`event\` as a value is a reference (not plain text).`;
+  return {
+    id: "value-types",
+    title: "Value Types",
+    content,
+    approximateTokens: estimateTokens(content)
+  };
+}
+function buildCommandsSection(schemas, outputFormat, examplesPerCommand) {
+  const parts = [];
+  for (const schema of schemas) {
+    parts.push(formatCommandDoc(schema, outputFormat, examplesPerCommand));
+  }
+  const content = parts.join("\n\n");
+  return {
+    id: "commands",
+    title: "Available Commands",
+    content,
+    approximateTokens: estimateTokens(content)
+  };
+}
+function buildOutputFormatSection(outputFormat) {
+  let content;
+  if (outputFormat === "explicit") {
+    content = `Output valid LSE bracket syntax. Each command must be wrapped in brackets:
+
+\`\`\`
+[command role:value ...]
+\`\`\`
+
+Do NOT output JSON. Only use bracket syntax.`;
+  } else if (outputFormat === "json") {
+    content = `Output valid JSON in the LLM-simplified format:
+
+\`\`\`json
+{
+  "action": "command-name",
+  "roles": {
+    "roleName": { "type": "valueType", "value": "theValue" }
+  }
+}
+\`\`\`
+
+Valid value types: \`selector\`, \`literal\`, \`reference\`, \`expression\`.
+Do NOT output bracket syntax. Only use JSON.`;
+  } else {
+    content = `You may output EITHER format:
+
+**Bracket syntax** (preferred for single commands):
+\`\`\`
+[command role:value ...]
+\`\`\`
+
+**JSON format** (preferred when structured data is needed):
+\`\`\`json
+{
+  "action": "command-name",
+  "roles": {
+    "roleName": { "type": "valueType", "value": "theValue" }
+  }
+}
+\`\`\`
+
+Both formats are equally valid. Use whichever is more natural for the context.`;
+  }
+  return {
+    id: "output-format",
+    title: "Output Format",
+    content,
+    approximateTokens: estimateTokens(content)
+  };
+}
+function buildErrorRecoverySection() {
+  const content = `If you're unsure about a command or role:
+
+1. **Unknown command**: Use the closest matching command from the Available Commands section. Do not invent commands.
+2. **Unknown role**: Use only the roles listed for each command. Do not add roles not in the schema.
+3. **Ambiguous value type**: When in doubt, use \`expression\` type (it's the most permissive).
+4. **Missing required role**: Always include all required roles. Check the Required/Optional labels.
+5. **Selector vs plain value**: If a value starts with \`#\`, \`.\`, \`[\`, \`@\`, or \`*\`, it's a selector. URLs like \`/api/data\` are plain values.
+
+When generating LSE, prefer explicit role labeling over positional guessing. Every value should have a role name.`;
+  return {
+    id: "error-recovery",
+    title: "Error Recovery",
+    content,
+    approximateTokens: estimateTokens(content)
+  };
+}
+function formatCommandDoc(schema, outputFormat, examplesPerCommand) {
+  const lines = [];
+  lines.push(`### \`${schema.action}\` \u2014 ${schema.description}`);
+  lines.push("");
+  const required = schema.roles.filter((r) => r.required);
+  const optional = schema.roles.filter((r) => !r.required);
+  if (required.length > 0) {
+    lines.push("**Required roles:**");
+    for (const role of required) {
+      lines.push(`- \`${role.role}\`: ${role.description} (type: ${formatExpectedTypes(role)})`);
+    }
+  }
+  if (optional.length > 0) {
+    lines.push("**Optional roles:**");
+    for (const role of optional) {
+      lines.push(`- \`${role.role}\`: ${role.description} (type: ${formatExpectedTypes(role)})`);
+    }
+  }
+  const examples = generateExamples(schema, examplesPerCommand);
+  if (examples.length > 0) {
+    lines.push("");
+    if (outputFormat === "explicit" || outputFormat === "both") {
+      lines.push("**Bracket syntax:**");
+      for (const ex of examples) {
+        lines.push(`\`\`\`
+${ex.explicit}
+\`\`\``);
+      }
+    }
+    if (outputFormat === "json" || outputFormat === "both") {
+      lines.push("**JSON format:**");
+      for (const ex of examples) {
+        lines.push(`\`\`\`json
+${JSON.stringify(ex.json, null, 2)}
+\`\`\``);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function formatExpectedTypes(role) {
+  return role.expectedTypes.join(" | ");
+}
+function generateRoleCombinations(schema) {
+  const required = schema.roles.filter((r) => r.required);
+  const optional = schema.roles.filter((r) => !r.required);
+  const combos = [];
+  if (required.length > 0) {
+    combos.push(required);
+  }
+  for (const opt of optional) {
+    combos.push([...required, opt]);
+  }
+  if (optional.length >= 2) {
+    combos.push([...required, ...optional]);
+  }
+  if (combos.length === 0) {
+    combos.push(schema.roles.slice());
+  }
+  return combos;
+}
+function sampleValue(role) {
+  const primaryType = role.expectedTypes[0] || "expression";
+  switch (primaryType) {
+    case "selector":
+      return sampleSelector(role.role);
+    case "literal":
+      return sampleLiteral(role.role);
+    case "reference":
+      return { type: "reference", value: "me" };
+    case "expression":
+      return sampleExpression(role.role);
+    case "flag":
+      return { type: "flag", value: true };
+    default:
+      return { type: "literal", value: "example" };
+  }
+}
+function sampleSelector(roleName) {
+  const selectors = {
+    patient: ".active",
+    destination: "#output",
+    source: "#input",
+    target: "#target"
+  };
+  return { type: "selector", value: selectors[roleName] || `#${roleName}` };
+}
+function sampleLiteral(roleName) {
+  const literals = {
+    duration: "30s",
+    interval: "5s",
+    delay: "500ms",
+    timeout: "10s",
+    quantity: 5,
+    limit: 10,
+    style: "json",
+    manner: "rolling",
+    format: "html"
+  };
+  return { type: "literal", value: literals[roleName] || roleName };
+}
+function sampleExpression(roleName) {
+  const expressions = {
+    source: "/api/data",
+    destination: "#output",
+    patient: ".active",
+    instrument: "toUpperCase",
+    condition: "age > 18",
+    style: "json",
+    duration: "5s",
+    url: "/api/users"
+  };
+  return { type: "expression", value: expressions[roleName] || `/api/${roleName}` };
+}
+function toSemanticValue(sample) {
+  switch (sample.type) {
+    case "selector":
+      return {
+        type: "selector",
+        value: String(sample.value),
+        selectorKind: detectSelectorKind2(String(sample.value))
+      };
+    case "literal":
       return {
-        valid: false,
-        errors: [error instanceof Error ? error.message : String(error)]
+        type: "literal",
+        value: sample.value,
+        dataType: typeof sample.value === "number" ? "number" : typeof sample.value === "boolean" ? "boolean" : "string"
       };
+    case "reference":
+      return { type: "reference", value: String(sample.value) };
+    case "expression":
+      return { type: "expression", value: String(sample.value), raw: String(sample.value) };
+    case "flag":
+      return { type: "flag", value: sample.value };
+    default:
+      return { type: "literal", value: String(sample.value), dataType: "string" };
+  }
+}
+function detectSelectorKind2(selector) {
+  if (selector.startsWith("#")) return "id";
+  if (selector.startsWith(".")) return "class";
+  if (selector.startsWith("[")) return "attribute";
+  return "complex";
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function truncateToTokenBudget(sections, maxTokens) {
+  const result = [];
+  let budget = maxTokens;
+  for (const section of sections) {
+    if (section.approximateTokens <= budget) {
+      result.push(section);
+      budget -= section.approximateTokens;
+    } else {
+      const charBudget = Math.max(budget * 4, 40);
+      const truncatedContent = section.content.slice(0, charBudget) + "\n\n*(truncated)*";
+      result.push({
+        ...section,
+        content: truncatedContent,
+        approximateTokens: estimateTokens(truncatedContent)
+      });
+      break;
     }
   }
-  translate(input, fromLanguage, toLanguage) {
-    return this.transformer.transform(input, fromLanguage, toLanguage);
+  return result;
+}
+
+// src/training/schema-synthesizer.ts
+function synthesizeFromSchemas(schemas, config) {
+  const maxPerCommand = config.maxPairsPerCommand ?? 5;
+  const minQuality = config.minQuality ?? 0.5;
+  const shuffleRoles = config.shuffleRoles ?? true;
+  const languages = config.languages ?? ["en"];
+  const pairs = [];
+  let idCounter = 0;
+  for (const schema of schemas) {
+    const combos = generateRoleCombinations2(schema);
+    for (const language of languages) {
+      let commandPairCount = 0;
+      for (const combo of combos) {
+        if (commandPairCount >= maxPerCommand) break;
+        const pair = buildTrainingPair(
+          schema,
+          combo,
+          language,
+          config.domain,
+          `${config.domain}-synth-${idCounter++}`
+        );
+        if (pair.quality >= minQuality) {
+          pairs.push(pair);
+          commandPairCount++;
+        }
+        if (shuffleRoles && combo.length >= 2 && commandPairCount < maxPerCommand) {
+          const shuffled = [...combo].reverse();
+          const shuffledPair = buildTrainingPair(
+            schema,
+            shuffled,
+            language,
+            config.domain,
+            `${config.domain}-synth-${idCounter++}`
+          );
+          if (shuffledPair.quality >= minQuality) {
+            pairs.push(shuffledPair);
+            commandPairCount++;
+          }
+        }
+      }
+    }
   }
-  compile(input, language) {
-    if (!this.codeGenerator) {
-      return {
-        ok: false,
-        errors: ["No code generator configured for this DSL"]
-      };
+  const metadata = {
+    domain: config.domain,
+    commandCount: schemas.length,
+    pairCount: pairs.length,
+    bySource: { synthetic: pairs.length },
+    languages
+  };
+  return { pairs, metadata };
+}
+function generateRoleCombinations2(schema) {
+  const required = schema.roles.filter((r) => r.required);
+  const optional = schema.roles.filter((r) => !r.required);
+  const combos = [];
+  if (required.length > 0) {
+    combos.push(required);
+  }
+  for (const opt of optional) {
+    combos.push([...required, opt]);
+  }
+  if (optional.length >= 2) {
+    combos.push([...required, ...optional]);
+  }
+  if (combos.length === 0) {
+    combos.push(schema.roles.slice());
+  }
+  return combos;
+}
+function buildTrainingPair(schema, roles, language, domain, id) {
+  const sampledRoles = /* @__PURE__ */ new Map();
+  for (const role of roles) {
+    sampledRoles.set(role.role, sampleValue2(role));
+  }
+  const nodeRoles = /* @__PURE__ */ new Map();
+  for (const [name, sample] of sampledRoles) {
+    nodeRoles.set(name, toSemanticValue2(sample));
+  }
+  const node = createCommandNode(schema.action, nodeRoles);
+  const explicit = renderExplicit(node);
+  const jsonRoles = {};
+  for (const [name, sample] of sampledRoles) {
+    jsonRoles[name] = sample;
+  }
+  const json = { action: schema.action, roles: jsonRoles };
+  const natural = buildNaturalForm(schema, sampledRoles, language);
+  const requiredCount = schema.roles.filter((r) => r.required).length;
+  const filledRequired = roles.filter((r) => r.required).length;
+  const quality = requiredCount > 0 ? filledRequired / requiredCount : 0.8;
+  return {
+    id,
+    natural,
+    language,
+    explicit,
+    json,
+    domain,
+    action: schema.action,
+    source: "synthetic",
+    quality
+  };
+}
+function buildNaturalForm(schema, roles, language) {
+  const parts = [schema.action];
+  for (const roleSpec of schema.roles) {
+    const sample = roles.get(roleSpec.role);
+    if (!sample) continue;
+    const marker = roleSpec.markerOverride?.[language];
+    if (marker) {
+      parts.push(marker);
     }
-    try {
-      const result = this.parseWithConfidence(input, language);
-      const code = this.codeGenerator.generate(result.node);
+    parts.push(String(sample.value));
+  }
+  return parts.join(" ");
+}
+function sampleValue2(role) {
+  const primaryType = role.expectedTypes[0] || "expression";
+  switch (primaryType) {
+    case "selector":
+      return sampleSelector2(role.role);
+    case "literal":
+      return sampleLiteral2(role.role);
+    case "reference":
+      return { type: "reference", value: "me" };
+    case "expression":
+      return sampleExpression2(role.role);
+    case "flag":
+      return { type: "flag", value: true };
+    default:
+      return { type: "literal", value: "example" };
+  }
+}
+function sampleSelector2(roleName) {
+  const selectors = {
+    patient: ".active",
+    destination: "#output",
+    source: "#input",
+    target: "#target"
+  };
+  return { type: "selector", value: selectors[roleName] || `#${roleName}` };
+}
+function sampleLiteral2(roleName) {
+  const literals = {
+    duration: "30s",
+    interval: "5s",
+    delay: "500ms",
+    timeout: "10s",
+    quantity: 5,
+    limit: 10,
+    style: "json",
+    manner: "rolling",
+    format: "html"
+  };
+  return { type: "literal", value: literals[roleName] || roleName };
+}
+function sampleExpression2(roleName) {
+  const expressions = {
+    source: "/api/data",
+    destination: "#output",
+    patient: ".active",
+    instrument: "toUpperCase",
+    condition: "age > 18",
+    style: "json",
+    duration: "5s",
+    url: "/api/users"
+  };
+  return { type: "expression", value: expressions[roleName] || `/api/${roleName}` };
+}
+function toSemanticValue2(sample) {
+  switch (sample.type) {
+    case "selector":
       return {
-        ok: true,
-        code,
-        node: result.node,
-        metadata: {
-          parser: "semantic",
-          confidence: result.confidence
-        }
+        type: "selector",
+        value: String(sample.value),
+        selectorKind: detectSelectorKind3(String(sample.value))
       };
-    } catch (error) {
+    case "literal":
       return {
-        ok: false,
-        errors: [error instanceof Error ? error.message : String(error)]
+        type: "literal",
+        value: sample.value,
+        dataType: typeof sample.value === "number" ? "number" : typeof sample.value === "boolean" ? "boolean" : "string"
       };
+    case "reference":
+      return { type: "reference", value: String(sample.value) };
+    case "expression":
+      return { type: "expression", value: String(sample.value), raw: String(sample.value) };
+    case "flag":
+      return { type: "flag", value: sample.value };
+    default:
+      return { type: "literal", value: String(sample.value), dataType: "string" };
+  }
+}
+function detectSelectorKind3(selector) {
+  if (selector.startsWith("#")) return "id";
+  if (selector.startsWith(".")) return "class";
+  if (selector.startsWith("[")) return "attribute";
+  return "complex";
+}
+
+// src/feedback/feedback-formatter.ts
+function buildFeedback(input, inputFormat, diagnostics, schemaLookup, action) {
+  const hasErrors = diagnostics.some((d) => d.severity === "error");
+  const feedbackDiagnostics = diagnostics.map((d) => toFeedbackDiagnostic(d));
+  const hints = generateHints(feedbackDiagnostics, schemaLookup, action);
+  let schemaInfo;
+  let correctedExample;
+  if (action && schemaLookup) {
+    const schema = schemaLookup.getSchema(action);
+    if (schema) {
+      schemaInfo = extractSchemaInfo(schema);
+      if (hasErrors) {
+        correctedExample = generateCorrectedExample(schema);
+      }
     }
   }
-  getSupportedLanguages() {
-    return this.registry.getSupportedLanguages();
+  return {
+    accepted: !hasErrors,
+    input: { format: inputFormat, text: input },
+    diagnostics: feedbackDiagnostics,
+    hints,
+    ...schemaInfo && { schema: schemaInfo },
+    ...correctedExample && { correctedExample }
+  };
+}
+function toFeedbackDiagnostic(d) {
+  const fixType = classifyFixType(d);
+  return {
+    severity: d.severity,
+    code: d.code || "unknown",
+    message: d.message,
+    ...d.suggestions?.[0] && { suggestion: d.suggestions[0] },
+    ...fixType && { fixType }
+  };
+}
+function classifyFixType(d) {
+  const code = (d.code || "").toLowerCase();
+  const msg = d.message.toLowerCase();
+  if (code.includes("missing-role") || code.includes("missing_role") || msg.includes("required role") || msg.includes("missing role")) {
+    return "missing_role";
   }
-};
-function createDefaultDictionary(config) {
-  const translations = {};
-  for (const lang of config.languages) {
-    const keywords = {};
-    for (const [canonical, keywordDef] of Object.entries(lang.patternProfile.keywords)) {
-      keywords[canonical] = keywordDef.primary;
+  if (code.includes("invalid-type") || code.includes("invalid_type") || code.includes("type-mismatch") || msg.includes("invalid type") || msg.includes("expected type")) {
+    return "invalid_type";
+  }
+  if (code.includes("unknown-command") || code.includes("unknown_command") || msg.includes("unknown command") || msg.includes("not recognized") && msg.includes("command")) {
+    return "unknown_command";
+  }
+  if (code.includes("unknown-role") || code.includes("unknown_role") || msg.includes("unknown role") || msg.includes("not recognized") && msg.includes("role")) {
+    return "unknown_role";
+  }
+  if (code.includes("parse") || code.includes("syntax") || msg.includes("syntax error") || msg.includes("parse error") || msg.includes("unexpected")) {
+    return "syntax_error";
+  }
+  return void 0;
+}
+function generateHints(diagnostics, schemaLookup, action) {
+  const hints = [];
+  const schema = action && schemaLookup ? schemaLookup.getSchema(action) : void 0;
+  for (const d of diagnostics) {
+    if (d.severity !== "error") continue;
+    switch (d.fixType) {
+      case "missing_role": {
+        if (schema) {
+          const required = schema.roles.filter((r) => r.required).map((r) => `'${r.role}' (${r.description}, type: ${r.expectedTypes.join("|")})`).join(", ");
+          hints.push(`Required roles for '${action}': ${required}`);
+        } else {
+          hints.push("Check that all required roles are present.");
+        }
+        break;
+      }
+      case "unknown_command": {
+        hints.push(
+          `Command not recognized. Ensure you're using a valid command from the domain schema.`
+        );
+        break;
+      }
+      case "unknown_role": {
+        if (schema) {
+          const validRoles = schema.roles.map((r) => `'${r.role}'`).join(", ");
+          hints.push(`Valid roles for '${action}': ${validRoles}`);
+        } else {
+          hints.push("Use only roles defined in the command schema.");
+        }
+        break;
+      }
+      case "invalid_type": {
+        hints.push(
+          "Check value types: selectors start with #.[@*, strings use quotes, numbers are plain digits."
+        );
+        break;
+      }
+      case "syntax_error": {
+        hints.push("Ensure bracket syntax: [command role:value ...]. No spaces around the colon.");
+        break;
+      }
+      default: {
+        if (d.suggestion) {
+          hints.push(d.suggestion);
+        }
+      }
     }
-    translations[lang.code] = keywords;
   }
-  return new InMemoryDictionary(translations);
+  return [...new Set(hints)];
 }
-function createDefaultProfileProvider(config) {
-  const profiles = {};
-  for (const lang of config.languages) {
-    if (lang.grammarProfile) {
-      profiles[lang.code] = lang.grammarProfile;
+function extractSchemaInfo(schema) {
+  const requiredRoles = [];
+  const optionalRoles = [];
+  const roleDescriptions = {};
+  for (const role of schema.roles) {
+    if (role.required) {
+      requiredRoles.push(role.role);
+    } else {
+      optionalRoles.push(role.role);
     }
+    roleDescriptions[role.role] = role.description;
   }
-  return new InMemoryProfileProvider(profiles);
+  return {
+    action: schema.action,
+    requiredRoles,
+    optionalRoles,
+    roleDescriptions
+  };
 }
-function createMultilingualDSL(config) {
-  const dictionary = config.dictionary ?? createDefaultDictionary(config);
-  const profileProvider = config.profileProvider ?? createDefaultProfileProvider(config);
-  const transformer = new GrammarTransformer({
-    dictionary,
-    profileProvider
-  });
-  const registry = new DSLRegistry(config);
-  return new MultilingualDSLImpl(config, registry, transformer);
+function generateCorrectedExample(schema) {
+  const roles = /* @__PURE__ */ new Map();
+  const jsonRoles = {};
+  for (const role of schema.roles) {
+    if (!role.required) continue;
+    const sample = sampleDefaultValue(role.role, role.expectedTypes[0] || "expression");
+    roles.set(role.role, toSemanticValue3(sample));
+    jsonRoles[role.role] = sample;
+  }
+  const node = createCommandNode(schema.action, roles);
+  const explicit = renderExplicit(node);
+  const json = { action: schema.action, roles: jsonRoles };
+  return { explicit, json };
+}
+function sampleDefaultValue(roleName, expectedType) {
+  switch (expectedType) {
+    case "selector":
+      return { type: "selector", value: `#${roleName}` };
+    case "expression":
+      return { type: "expression", value: `<${roleName}-value>` };
+    case "literal":
+      return { type: "literal", value: `<${roleName}-value>` };
+    case "reference":
+      return { type: "reference", value: "me" };
+    default:
+      return { type: "expression", value: `<${roleName}-value>` };
+  }
+}
+function toSemanticValue3(sample) {
+  switch (sample.type) {
+    case "selector":
+      return { type: "selector", value: sample.value, selectorKind: "id" };
+    case "expression":
+      return { type: "expression", value: sample.value, raw: sample.value };
+    case "literal":
+      return { type: "literal", value: sample.value, dataType: "string" };
+    case "reference":
+      return { type: "reference", value: sample.value };
+    default:
+      return { type: "literal", value: sample.value, dataType: "string" };
+  }
 }
 
 // src/api/domain-registry.ts
@@ -2192,6 +4476,17 @@ var DomainRegistry = class {
     }
     this.descriptors.set(descriptor.name, descriptor);
   }
+  /**
+   * Attach schemas to an already-registered domain.
+   * Useful for lazy loading schemas after initial registration.
+   */
+  setSchemas(name, schemas) {
+    const existing = this.descriptors.get(name);
+    if (!existing) {
+      throw new Error(`Domain not registered: ${name}`);
+    }
+    this.descriptors.set(name, { ...existing, schemas });
+  }
   /**
    * Get all registered domain names.
    */
@@ -2261,6 +4556,71 @@ var DomainRegistry = class {
     return this.getDSL(descriptor);
   }
   // ---------------------------------------------------------------------------
+  // LLM ↔ LSE Convenience Methods
+  // ---------------------------------------------------------------------------
+  /**
+   * Generate an LLM system prompt for a domain from its schemas.
+   * Returns null if the domain is not registered or has no schemas.
+   */
+  generatePrompt(domain, config) {
+    const descriptor = this.descriptors.get(domain);
+    if (!descriptor?.schemas || descriptor.schemas.length === 0) return null;
+    return generatePrompt({
+      domain,
+      description: descriptor.description,
+      schemas: descriptor.schemas,
+      ...config
+    });
+  }
+  /**
+   * Synthesize training data for a domain from its schemas.
+   * Returns null if the domain is not registered or has no schemas.
+   */
+  generateTrainingData(domain, config) {
+    const descriptor = this.descriptors.get(domain);
+    if (!descriptor?.schemas || descriptor.schemas.length === 0) return null;
+    return synthesizeFromSchemas(descriptor.schemas, {
+      domain,
+      ...config
+    });
+  }
+  /**
+   * Build structured feedback for a failed LSE input in a domain.
+   * Returns null if the domain is not registered or has no schemas.
+   */
+  buildFeedback(domain, input, inputFormat, diagnostics) {
+    const descriptor = this.descriptors.get(domain);
+    if (!descriptor?.schemas || descriptor.schemas.length === 0) return null;
+    const schemaLookup = this.createSchemaLookup(descriptor.schemas);
+    let action;
+    try {
+      if (inputFormat === "explicit") {
+        const node = parseExplicit(input, { schemaLookup });
+        action = node.action;
+      }
+    } catch {
+    }
+    return buildFeedback(input, inputFormat, diagnostics, schemaLookup, action);
+  }
+  /**
+   * Get schemas for a domain (if available).
+   */
+  getSchemas(domain) {
+    const descriptor = this.descriptors.get(domain);
+    if (!descriptor?.schemas) return null;
+    return descriptor.schemas;
+  }
+  /**
+   * Create a SchemaLookup from a domain's schemas.
+   */
+  createSchemaLookup(schemas) {
+    const map = /* @__PURE__ */ new Map();
+    for (const s of schemas) {
+      map.set(s.action, s);
+    }
+    return { getSchema: (action) => map.get(action) };
+  }
+  // ---------------------------------------------------------------------------
   // Private: DSL/renderer lifecycle
   // ---------------------------------------------------------------------------
   async getDSL(descriptor) {
@@ -2360,7 +4720,7 @@ function generateToolDefinitions(desc) {
       case "parse":
         tools.push({
           name: `parse_${desc.name}`,
-          description: `Parse a ${desc.description} input into a semantic representation. Supports: ${langList}.`,
+          description: `Parse a ${desc.description} input into a semantic representation (action, roles, confidence). Supports: ${langList}.`,
           inputSchema: {
             type: "object",
             properties: {
@@ -2381,7 +4741,7 @@ function generateToolDefinitions(desc) {
       case "compile":
         tools.push({
           name: `compile_${desc.name}`,
-          description: `Compile a ${desc.description} input to target code. Supports: ${langList}.`,
+          description: `Compile a ${desc.description} input to ${desc.outputDescription ?? "target code"}. Supports: ${langList}.`,
           inputSchema: {
             type: "object",
             properties: {
@@ -2402,7 +4762,7 @@ function generateToolDefinitions(desc) {
       case "validate":
         tools.push({
           name: `validate_${desc.name}`,
-          description: `Validate ${desc.description} syntax. Returns whether it parses successfully and any errors. Supports: ${langList}.`,
+          description: `Check ${desc.description} syntax for errors. Returns {valid, errors[]}. Supports: ${langList}.`,
           inputSchema: {
             type: "object",
             properties: {
@@ -2423,7 +4783,7 @@ function generateToolDefinitions(desc) {
       case "translate":
         tools.push({
           name: `translate_${desc.name}`,
-          description: `Translate ${desc.description} input between natural languages. Parses in source language and renders in target language.`,
+          description: `Translate ${desc.description} input between natural languages (requires 'from' and 'to' codes). Supports: ${langList}.`,
           inputSchema: {
             type: "object",
             properties: {
@@ -2489,9 +4849,9 @@ var CrossDomainDispatcher = class {
     if (domainNames.length === 0) return null;
     const candidates = [];
     for (const name of domainNames) {
-      const dsl = await this.registry.getDSLForDomain(name);
-      if (!dsl) continue;
       try {
+        const dsl = await this.registry.getDSLForDomain(name);
+        if (!dsl) continue;
         const { node, confidence } = dsl.parseWithConfidence(input, language);
         if (confidence >= this.minConfidence) {
           candidates.push({ domain: name, node, confidence, dsl });
@@ -2500,10 +4860,16 @@ var CrossDomainDispatcher = class {
       }
     }
     if (candidates.length === 0) return null;
-    candidates.sort((a, b) => {
-      if (b.confidence !== a.confidence) return b.confidence - a.confidence;
-      return this.getPriorityIndex(a.domain) - this.getPriorityIndex(b.domain);
-    });
+    if (this.priority.length > 0) {
+      candidates.sort((a, b) => {
+        const pa = this.getPriorityIndex(a.domain);
+        const pb = this.getPriorityIndex(b.domain);
+        if (pa !== pb) return pa - pb;
+        return b.confidence - a.confidence;
+      });
+    } else {
+      candidates.sort((a, b) => b.confidence - a.confidence);
+    }
     return candidates[0];
   }
   /**
@@ -2547,6 +4913,40 @@ var CrossDomainDispatcher = class {
     const result = detected.dsl.compile(input, language);
     return { ...result, domain: detected.domain };
   }
+  /**
+   * Compile multi-line input where each line may belong to a different domain.
+   * Detects the domain for each line and compiles it, returning per-line results.
+   * Empty lines and comment lines are skipped.
+   */
+  async compileComposite(input, language = "en") {
+    const lines = input.split("\n");
+    const statements = [];
+    const errors = [];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (isSkippableLine(line)) continue;
+      const trimmed = line.trim();
+      const detected = await this.detect(trimmed, language);
+      if (detected) {
+        const result = detected.dsl.compile(trimmed, language);
+        statements.push({
+          line: i + 1,
+          input: trimmed,
+          domain: detected.domain,
+          ok: result.ok,
+          code: result.code,
+          errors: result.errors
+        });
+      } else {
+        errors.push({
+          line: i + 1,
+          input: trimmed,
+          message: "No domain matched this input"
+        });
+      }
+    }
+    return { statements, errors };
+  }
   /**
    * Validate input against all domains, returning the best match.
    */
@@ -2828,6 +5228,30 @@ ${body}
   }
 };
 
+// src/aot/registry-bridge.ts
+async function registryToAOTBackends(registry) {
+  const backends = [];
+  for (const name of registry.getDomainNames()) {
+    const descriptor = registry.getDescriptor(name);
+    if (!descriptor?.scanConfig) continue;
+    const dsl = await registry.getDSLForDomain(name);
+    if (!dsl) continue;
+    const scanConfig = {
+      domain: name,
+      attributes: [...descriptor.scanConfig.attributes],
+      ...descriptor.scanConfig.scriptTypes ? { scriptTypes: [...descriptor.scanConfig.scriptTypes] } : {},
+      defaultLanguage: descriptor.scanConfig.defaultLanguage ?? "en"
+    };
+    const codeGenerator = {
+      generate(node) {
+        return JSON.stringify({ action: node.action, roles: Object.fromEntries(node.roles) });
+      }
+    };
+    backends.push({ domain: name, dsl, codeGenerator, scanConfig });
+  }
+  return backends;
+}
+
 // src/schema/command-schema.ts
 function defineCommand(schema) {
   return {
@@ -4119,6 +6543,163 @@ function normalized(stem, confidence, metadata) {
   return { stem, confidence };
 }
 
+// src/training/jsonl-writer.ts
+function toJSONL(pairs) {
+  return pairs.map((pair) => JSON.stringify(toJSONLRow(pair))).join("\n");
+}
+function toJSONLRow(pair) {
+  return {
+    id: pair.id,
+    prompt: pair.natural,
+    completion: pair.explicit,
+    metadata: {
+      domain: pair.domain,
+      action: pair.action,
+      language: pair.language,
+      source: pair.source,
+      quality: pair.quality,
+      ...pair.confidence !== void 0 && { confidence: pair.confidence }
+    }
+  };
+}
+function parseJSONL(text) {
+  return text.split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
+}
+
+// src/feedback/confidence-gate.ts
+function needsDisambiguation(confidence, low = 0.5, high = 0.7) {
+  return confidence >= low && confidence < high;
+}
+function buildDisambiguation(input, candidates) {
+  const sortedCandidates = [...candidates].sort((a, b) => b.confidence - a.confidence);
+  const disambiguationCandidates = sortedCandidates.map((c, i) => ({
+    action: c.action,
+    confidence: c.confidence,
+    explicit: renderExplicit(c.node),
+    description: c.description || `${c.action} (option ${String.fromCharCode(97 + i)})`
+  }));
+  const optionLines = disambiguationCandidates.map(
+    (c, i) => `  (${String.fromCharCode(97 + i)}) ${c.explicit} \u2014 ${c.description} (conf: ${c.confidence.toFixed(2)})`
+  );
+  const question = [
+    `Your input parsed with confidence ${sortedCandidates[0]?.confidence.toFixed(2) ?? "?"}.`,
+    ...optionLines,
+    "Which did you mean?"
+  ].join("\n");
+  return {
+    input,
+    candidates: disambiguationCandidates,
+    question
+  };
+}
+
+// src/feedback/pattern-tracker.ts
+var PatternTracker = class {
+  constructor(maxEvents = 1e3) {
+    this.events = [];
+    this.maxEvents = maxEvents;
+  }
+  /**
+   * Record a pattern event.
+   */
+  record(event) {
+    this.events.push(event);
+    if (this.events.length > this.maxEvents) {
+      this.events = this.events.slice(this.events.length - this.maxEvents);
+    }
+  }
+  /**
+   * Get hit rate by command action.
+   */
+  getHitRateByCommand() {
+    return this.computeHitRate((e) => e.action);
+  }
+  /**
+   * Get hit rate by language.
+   */
+  getHitRateByLanguage() {
+    return this.computeHitRate((e) => e.language);
+  }
+  /**
+   * Get the most frequent failure diagnostic codes.
+   */
+  getTopFailures(limit = 10) {
+    const codeMap = /* @__PURE__ */ new Map();
+    for (const event of this.events) {
+      if (event.outcome !== "rejected" || !event.diagnosticCodes) continue;
+      for (const code of event.diagnosticCodes) {
+        const entry = codeMap.get(code) || { count: 0, actions: /* @__PURE__ */ new Set() };
+        entry.count++;
+        entry.actions.add(event.action);
+        codeMap.set(code, entry);
+      }
+    }
+    return Array.from(codeMap.entries()).map(([code, { count, actions }]) => ({
+      code,
+      count,
+      actions: Array.from(actions)
+    })).sort((a, b) => b.count - a.count).slice(0, limit);
+  }
+  /**
+   * Get a complete summary of tracking data.
+   */
+  getSummary() {
+    const byOutcome = {};
+    for (const event of this.events) {
+      byOutcome[event.outcome] = (byOutcome[event.outcome] || 0) + 1;
+    }
+    return {
+      totalEvents: this.events.length,
+      byOutcome,
+      byCommand: this.getHitRateByCommand(),
+      byLanguage: this.getHitRateByLanguage(),
+      topFailures: this.getTopFailures()
+    };
+  }
+  /**
+   * Export all events as JSONL.
+   */
+  exportJSONL() {
+    return this.events.map((e) => JSON.stringify(e)).join("\n");
+  }
+  /**
+   * Get the number of recorded events.
+   */
+  get size() {
+    return this.events.length;
+  }
+  /**
+   * Clear all events.
+   */
+  clear() {
+    this.events = [];
+  }
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+  computeHitRate(keyFn) {
+    const map = /* @__PURE__ */ new Map();
+    for (const event of this.events) {
+      const key = keyFn(event);
+      const entry = map.get(key) || { attempts: 0, successes: 0 };
+      entry.attempts++;
+      if (event.outcome === "accepted") {
+        entry.successes++;
+      }
+      map.set(key, entry);
+    }
+    const result = {};
+    for (const [key, { attempts, successes }] of map) {
+      result[key] = {
+        attempts,
+        successes,
+        rate: attempts > 0 ? successes / attempts : 0
+      };
+    }
+    return result;
+  }
+};
+
 // src/parsing/multi-statement.ts
 function createMultiStatementParser(dsl, config) {
   return new MultiStatementParserImpl(dsl, config);
@@ -4363,6 +6944,7 @@ function accumulateIndented(statements, config) {
   CrossDomainDispatcher,
   DEFAULT_OPERATORS,
   DEFAULT_PUNCTUATION,
+  DEFAULT_REFERENCES,
   DomainAwareScanner,
   DomainRegistry,
   GrammarTransformer,
@@ -4374,24 +6956,31 @@ function accumulateIndented(statements, config) {
   NumberExtractor,
   OperatorExtractor,
   PatternMatcher,
+  PatternTracker,
   PunctuationExtractor,
   StringLiteralExtractor,
   TokenStreamImpl,
   UnicodeIdentifierExtractor,
   WhitespaceExtractor,
   accumulateBlocks,
+  buildDisambiguation,
+  buildFeedback,
   buildPhrase,
   buildTablesFromProfiles,
   combineClassifiers,
+  convertValue,
+  createAsyncNode,
   createCommandNode,
   createCompoundNode,
   createConditionalNode,
   createDiagnosticCollector,
   createEventHandlerNode,
   createExpression,
+  createFlag,
   createLatinCharClassifiers,
   createLiteral,
   createLoopNode,
+  createMatchNode,
   createMultiStatementParser,
   createMultilingualDSL,
   createPosition,
@@ -4402,6 +6991,7 @@ function accumulateIndented(statements, config) {
   createSimpleTokenizer,
   createToken,
   createTokenizerContext,
+  createTryNode,
   createUnicodeRangeClassifier,
   defineCommand,
   defineRole,
@@ -4413,9 +7003,15 @@ function accumulateIndented(statements, config) {
   extractUrl,
   extractValue,
   filterBySeverity,
+  fromEnvelopeJSON,
   fromError,
+  fromInterchangeNode,
+  fromProtocolJSON,
+  generateExamples,
   generatePattern,
   generatePatternVariants,
+  generatePrompt,
+  generateProtocolReference,
   getAllPossessiveKeywords,
   getDefaultExtractors,
   getPossessiveReference,
@@ -4428,6 +7024,8 @@ function accumulateIndented(statements, config) {
   isClassName,
   isContextAwareExtractor,
   isDigit,
+  isEnvelope,
+  isExplicitSyntax,
   isIdSelector,
   isNumericValue,
   isPossessiveKeyword,
@@ -4437,17 +7035,33 @@ function accumulateIndented(statements, config) {
   isSelectorStart,
   isTypeCompatible,
   isUrlStart,
+  isValidReference,
   isVariableRef,
   isWhitespace,
   joinTokens,
+  jsonToSemanticNode,
   lookupKeyword,
   lookupMarker,
   matchBest,
   matchPattern,
+  needsDisambiguation,
   noChange,
   normalized,
+  parseExplicit,
+  parseJSONL,
   patternMatcher,
+  registryToAOTBackends,
+  renderExplicit,
+  renderExpr,
   reorderRoles,
+  semanticNodeToJSON,
+  synthesizeFromSchemas,
+  toEnvelopeJSON,
+  toJSONL,
+  toJSONLRow,
+  toProtocolJSON,
+  validateProtocolJSON,
+  validateSemanticJSON,
   validateValueType,
   withDefaultExtractors
 });