@lokascript/framework 4.5.0 → 4.6.0

package/dist/api/reading.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How a read-back is compared (internal: not exported from the package). `translate` and the
+ * registry's translate tool both require a rendering to read back as its source; this is their rule.
+ */
+import type { SemanticNode } from '../core/types';
+/** How `back` differs from `source`; empty when it reads the same. */
+export declare function readingDifference(source: SemanticNode, back: SemanticNode): string;
+//# sourceMappingURL=reading.d.ts.map

package/dist/api/reading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../src/api/reading.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAYlD,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAWlF"}

package/dist/index.cjs

@@ -44,7 +44,9 @@ __export(index_exports, {
   PunctuationExtractor: () => PunctuationExtractor,
   StringLiteralExtractor: () => StringLiteralExtractor,
   TokenStreamImpl: () => TokenStreamImpl,
+  TranslationReadBackError: () => TranslationReadBackError,
   UnicodeIdentifierExtractor: () => UnicodeIdentifierExtractor,
+  UnreadInputError: () => UnreadInputError,
   WhitespaceExtractor: () => WhitespaceExtractor,
   accumulateBlocks: () => accumulateBlocks,
   buildDisambiguation: () => buildDisambiguation,
@@ -2954,7 +2956,53 @@ function semanticValueToAST(value) {
   }
 }
 
+// src/api/reading.ts
+function roleValues(node) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [role, value] of node.roles) {
+    const v = value;
+    out.set(role, String(v?.value ?? v?.raw ?? value));
+  }
+  return out;
+}
+function readingDifference(source, back) {
+  if (back.action !== source.action) return `reads as ${back.action}`;
+  const want = roleValues(source);
+  const got = roleValues(back);
+  const parts = [];
+  for (const [role, value] of want) {
+    if (!got.has(role)) parts.push(`${role} lost`);
+    else if (got.get(role) !== value) parts.push(`${role}: ${value} \u2192 ${got.get(role)}`);
+  }
+  for (const role of got.keys()) if (!want.has(role)) parts.push(`${role} added`);
+  return parts.join(", ");
+}
+
 // src/api/create-dsl.ts
+var UnreadInputError = class extends Error {
+  constructor(input, language, reading, unread) {
+    super(`"${input}" (${language}) reads as ${reading.action} only by leaving "${unread}" unread`);
+    this.input = input;
+    this.language = language;
+    this.reading = reading;
+    this.unread = unread;
+    this.code = "unread-input";
+    this.name = "UnreadInputError";
+  }
+};
+var TranslationReadBackError = class extends Error {
+  constructor(partial, from, to, source, reading, why) {
+    super(`translation ${from} \u2192 ${to} does not read back as the source (${why}): "${partial}"`);
+    this.partial = partial;
+    this.from = from;
+    this.to = to;
+    this.source = source;
+    this.reading = reading;
+    this.why = why;
+    this.code = "translation-does-not-read-back";
+    this.name = "TranslationReadBackError";
+  }
+};
 var DSLRegistry = class {
   /**
    * @param partiallyTranslatedActions Actions permitted to lack a keyword in
@@ -3039,25 +3087,50 @@ var MultilingualDSLImpl = class {
     const profile = {
       code: language
     };
+    const total = tokens.tokens.length;
+    let best = null;
+    let longestPartial = null;
     for (const pattern of patterns) {
+      const mark = tokens.mark();
       const match = this.matcher.matchPattern(tokens, pattern, profile);
-      if (match) {
-        const node = {
-          kind: "command",
-          action: pattern.command,
-          roles: match.captured,
-          metadata: {
-            sourceLanguage: language,
-            sourceText: input,
-            patternId: pattern.id,
-            confidence: match.confidence
-          }
-        };
-        return { node, confidence: match.confidence };
+      tokens.reset(mark);
+      if (!match) continue;
+      if (match.consumedTokens < total) {
+        if (!longestPartial || match.consumedTokens > longestPartial.consumedTokens)
+          longestPartial = match;
+        continue;
       }
+      if (!best || match.pattern.priority > best.pattern.priority || match.pattern.priority === best.pattern.priority && match.confidence > best.confidence + 1e-3)
+        best = match;
+    }
+    if (best) {
+      const node = this.nodeOf(best, input, language);
+      return { node, confidence: best.confidence };
+    }
+    if (longestPartial) {
+      const unread = tokens.tokens.slice(longestPartial.consumedTokens).map((t) => t.value).join(" ");
+      throw new UnreadInputError(
+        input,
+        language,
+        this.nodeOf(longestPartial, input, language),
+        unread
+      );
     }
     throw new Error(`No pattern matched for input: ${input}`);
   }
+  nodeOf(match, input, language) {
+    return {
+      kind: "command",
+      action: match.pattern.command,
+      roles: match.captured,
+      metadata: {
+        sourceLanguage: language,
+        sourceText: input,
+        patternId: match.pattern.id,
+        confidence: match.confidence
+      }
+    };
+  }
   validate(input, language) {
     try {
       const result = this.parseWithConfidence(input, language);
@@ -3068,11 +3141,12 @@ var MultilingualDSLImpl = class {
     } catch (error) {
       return {
         valid: false,
-        errors: [error instanceof Error ? error.message : String(error)]
+        errors: [error instanceof Error ? error.message : String(error)],
+        ...error instanceof UnreadInputError ? { errorCode: error.code } : {}
       };
     }
   }
-  translate(input, fromLanguage, toLanguage) {
+  translate(input, fromLanguage, toLanguage, options) {
     if ((0, import_intent3.isExplicitSyntax)(input)) return input;
     let node;
     try {
@@ -3084,14 +3158,46 @@ var MultilingualDSLImpl = class {
       throw parseError;
     }
     const rendered = this.registry.getSupportedLanguages().includes(toLanguage) ? this.render(node, toLanguage) : null;
-    if (rendered != null) return rendered;
+    if (rendered != null) return this.readsBack(rendered, node, fromLanguage, toLanguage, options);
     if (this.hasGrammarProfile(fromLanguage) && this.hasGrammarProfile(toLanguage)) {
-      return this.transformer.transform(input, fromLanguage, toLanguage);
+      return this.readsBack(
+        this.transformer.transform(input, fromLanguage, toLanguage),
+        node,
+        fromLanguage,
+        toLanguage,
+        options
+      );
     }
     throw new Error(
       `translate() could not render action "${node.action}" in language "${toLanguage}": no custom renderer, domain renderer, or schema pattern covers it, and no grammar profile is configured for the transformer fallback. Either add "${toLanguage}" to the DSL's languages/renderer, or set 'grammarProfile' on its LanguageConfig in createMultilingualDSL() (parse/validate/compile do not need it).`
     );
   }
+  /**
+   * `rendered`, read in `to`, must be `source`: the same action and role values, or, when the DSL
+   * compiles, the same code (a parser may keep a translated word its generator normalizes: bdd ja
+   * `表示` is `visible`). The rule is the domain gate's (lokascript-domains). A translation used to be
+   * returned whatever it read as: ja/ko bdd `select` dropped its value, and nothing said so.
+   */
+  readsBack(rendered, source, from, to, options) {
+    if (options?.lossy === "allow") return rendered;
+    let back;
+    try {
+      back = this.parseWithConfidence(rendered, to).node;
+    } catch (error) {
+      const why = error instanceof Error ? error.message : String(error);
+      throw new TranslationReadBackError(rendered, from, to, source, null, why);
+    }
+    const difference = readingDifference(source, back);
+    if (!difference) return rendered;
+    if (this.codeGenerator) {
+      try {
+        if (this.codeGenerator.generate(back) === this.codeGenerator.generate(source))
+          return rendered;
+      } catch {
+      }
+    }
+    throw new TranslationReadBackError(rendered, from, to, source, back, difference);
+  }
   hasGrammarProfile(language) {
     return this.profileProvider.getProfile(language) != null;
   }
@@ -3117,7 +3223,8 @@ var MultilingualDSLImpl = class {
     } catch (error) {
       return {
         ok: false,
-        errors: [error instanceof Error ? error.message : String(error)]
+        errors: [error instanceof Error ? error.message : String(error)],
+        ...error instanceof UnreadInputError ? { errorCode: error.code } : {}
       };
     }
   }
@@ -4044,6 +4151,8 @@ var DomainRegistry = class {
           return jsonResponse({ error: `Unknown operation: ${parsed.operation}` }, true);
       }
     } catch (error) {
+      if (error instanceof UnreadInputError) return unreadInputResponse(error);
+      if (error instanceof TranslationReadBackError) return readBackResponse(error);
       const message = error instanceof Error ? error.message : String(error);
       return jsonResponse({ error: `${descriptor.name} tool error: ${message}` }, true);
     }
@@ -4169,6 +4278,7 @@ var DomainRegistry = class {
       ok: result.ok,
       code: result.code,
       errors: result.errors,
+      ...result.errorCode === "unread-input" ? { diagnostics: [UNREAD_INPUT(result.errors)] } : {},
       language,
       input
     });
@@ -4181,6 +4291,7 @@ var DomainRegistry = class {
     return jsonResponse({
       valid: result.valid,
       errors: result.errors,
+      ...result.errorCode === "unread-input" ? { diagnostics: [UNREAD_INPUT(result.errors)] } : {},
       language,
       [descriptor.inputLabel]: input
     });
@@ -4211,7 +4322,24 @@ var DomainRegistry = class {
     for (const [key, value] of node.roles) {
       roles[key] = value;
     }
+    if (rendered != null) {
+      let back = null;
+      let why = "";
+      try {
+        back = dsl.parse(rendered, to);
+        why = readingDifference(node, back);
+        if (why && compiled.ok) {
+          const again = dsl.compile(rendered, to);
+          if (again.ok && again.code === compiled.code) why = "";
+        }
+      } catch (error) {
+        why = error instanceof Error ? error.message : String(error);
+      }
+      if (why)
+        return readBackResponse(new TranslationReadBackError(rendered, from, to, node, back, why));
+    }
     return jsonResponse({
+      ok: true,
       input: { [descriptor.inputLabel]: input, language: from },
       ...rendered != null && { rendered: { text: rendered, language: to } },
       semantic: { action: node.action, roles },
@@ -4291,7 +4419,7 @@ function generateToolDefinitions(desc) {
       case "translate":
         tools.push({
           name: `translate_${desc.name}`,
-          description: `Translate ${desc.description} input between natural languages (requires 'from' and 'to' codes). Supports: ${langList}.`,
+          description: `Translate ${desc.description} input between natural languages (requires 'from' and 'to' codes). Supports: ${langList}. A rendering that does not read back as the source is REFUSED: ok is false, the diagnostic is TRANSLATION_DOES_NOT_READ_BACK, and its text is under \`partial\`, never \`rendered\`: do not present it as the translation. Input left unread is refused as UNREAD_INPUT.`,
           inputSchema: {
             type: "object",
             properties: {
@@ -4325,6 +4453,46 @@ function getString(args, name, defaultValue = "") {
   const value = args[name];
   return typeof value === "string" ? value : defaultValue;
 }
+function readingOf(node) {
+  const roles = {};
+  for (const [key, value] of node.roles) roles[key] = value;
+  return { action: node.action, roles };
+}
+var UNREAD_INPUT = (errors) => ({
+  severity: "error",
+  code: "UNREAD_INPUT",
+  message: errors?.[0] ?? "part of the input was not read",
+  suggestion: "Part of the input belongs to no role of the command it reads as: remove it, or quote a value of several words."
+});
+function unreadInputResponse(error) {
+  return jsonResponse(
+    {
+      ok: false,
+      unread: error.unread,
+      reading: readingOf(error.reading),
+      diagnostics: [UNREAD_INPUT([error.message])]
+    },
+    true
+  );
+}
+function readBackResponse(error) {
+  return jsonResponse(
+    {
+      ok: false,
+      partial: error.partial,
+      ...error.reading ? { reading: readingOf(error.reading) } : {},
+      diagnostics: [
+        {
+          severity: "error",
+          code: "TRANSLATION_DOES_NOT_READ_BACK",
+          message: error.message,
+          suggestion: "The rendering would not mean the source in the target language: do not present `partial` as the translation."
+        }
+      ]
+    },
+    true
+  );
+}
 function jsonResponse(data, isError) {
   return {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -6736,7 +6904,9 @@ function accumulateIndented(statements, config) {
   PunctuationExtractor,
   StringLiteralExtractor,
   TokenStreamImpl,
+  TranslationReadBackError,
   UnicodeIdentifierExtractor,
+  UnreadInputError,
   WhitespaceExtractor,
   accumulateBlocks,
   buildDisambiguation,