@lokascript/framework 4.5.0 → 4.6.0

package/src/api/domain-registry.ts

@@ -31,6 +31,9 @@
  */
 
 import type { MultilingualDSL, CompileResult, ValidationResult } from './create-dsl';
+import { UnreadInputError, TranslationReadBackError } from './create-dsl';
+import { readingDifference } from './reading';
+import type { SemanticNode } from '../core/types';
 import type { NaturalLanguageRenderer, DomainRenderFn } from '../generation/renderer';
 import type { CommandSchema } from '../schema/command-schema';
 import type { SchemaLookup } from '../ir/types';
@@ -244,6 +247,9 @@ export class DomainRegistry {
           return jsonResponse({ error: `Unknown operation: ${parsed.operation}` }, true);
       }
     } catch (error) {
+      // A refusal is not a tool failure: say what was refused and why, as translate_code does.
+      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);
     }
@@ -412,6 +418,9 @@ export class DomainRegistry {
       ok: result.ok,
       code: result.code,
       errors: result.errors,
+      ...(result.errorCode === 'unread-input'
+        ? { diagnostics: [UNREAD_INPUT(result.errors)] }
+        : {}),
       language,
       input,
     });
@@ -431,6 +440,9 @@ export class DomainRegistry {
     return jsonResponse({
       valid: result.valid,
       errors: result.errors,
+      ...(result.errorCode === 'unread-input'
+        ? { diagnostics: [UNREAD_INPUT(result.errors)] }
+        : {}),
       language,
       [descriptor.inputLabel]: input,
     });
@@ -478,7 +490,28 @@ export class DomainRegistry {
       roles[key] = value;
     }
 
+    // The rendering must read back as the source, by the rule `translate` uses: the same action and
+    // role values, or the same compiled code. A rendering that does not is refused, with the text under
+    // `partial`, never `rendered`.
+    if (rendered != null) {
+      let back: SemanticNode | null = 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 },
@@ -567,7 +600,7 @@ function generateToolDefinitions(desc: DomainDescriptor): MCPToolDefinition[] {
       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: {
@@ -609,6 +642,54 @@ function getString(args: Record<string, unknown>, name: string, defaultValue = '
   return typeof value === 'string' ? value : defaultValue;
 }
 
+function readingOf(node: SemanticNode): { action: string; roles: Record<string, unknown> } {
+  const roles: Record<string, unknown> = {};
+  for (const [key, value] of node.roles) roles[key] = value;
+  return { action: node.action, roles };
+}
+
+const UNREAD_INPUT = (errors?: readonly string[]) => ({
+  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.',
+});
+
+/** A parse refused because it read the command only by leaving input unread. */
+function unreadInputResponse(error: UnreadInputError): MCPToolResponse {
+  return jsonResponse(
+    {
+      ok: false,
+      unread: error.unread,
+      reading: readingOf(error.reading),
+      diagnostics: [UNREAD_INPUT([error.message])],
+    },
+    true
+  );
+}
+
+/** A translation refused because it does not read back as the source; its text under `partial`. */
+function readBackResponse(error: TranslationReadBackError): MCPToolResponse {
+  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: unknown, isError?: boolean): MCPToolResponse {
   return {
     content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],

package/src/api/reading.ts

@@ -0,0 +1,29 @@
+/**
+ * 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';
+
+/** A node's role values as strings, by role: what a read-back is compared on. */
+function roleValues(node: SemanticNode): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [role, value] of node.roles) {
+    const v = value as { value?: unknown; raw?: unknown };
+    out.set(role, String(v?.value ?? v?.raw ?? value));
+  }
+  return out;
+}
+
+/** How `back` differs from `source`; empty when it reads the same. */
+export function readingDifference(source: SemanticNode, back: SemanticNode): string {
+  if (back.action !== source.action) return `reads as ${back.action}`;
+  const want = roleValues(source);
+  const got = roleValues(back);
+  const parts: string[] = [];
+  for (const [role, value] of want) {
+    if (!got.has(role)) parts.push(`${role} lost`);
+    else if (got.get(role) !== value) parts.push(`${role}: ${value} → ${got.get(role)}`);
+  }
+  for (const role of got.keys()) if (!want.has(role)) parts.push(`${role} added`);
+  return parts.join(', ');
+}