@lokascript/framework 2.0.0 → 2.1.0

package/dist/training/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Training Data Generation
+ *
+ * Generates (natural_language, LSE) pairs from domain schemas for
+ * fine-tuning or few-shot prompting LLMs. Exports as JSONL.
+ */
+export type { TrainingPair, SynthesisConfig, SynthesisResult, SynthesisMetadata } from './types';
+export { synthesizeFromSchemas } from './schema-synthesizer';
+export { toJSONL, toJSONLRow, parseJSONL } from './jsonl-writer';
+export type { JSONLRow } from './jsonl-writer';
+//# sourceMappingURL=index.d.ts.map

package/dist/training/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/training/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjG,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/training/jsonl-writer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * JSONL Writer
+ *
+ * Exports training pairs in JSONL (JSON Lines) format,
+ * compatible with standard fine-tuning pipelines.
+ */
+import type { TrainingPair } from './types';
+/**
+ * Convert training pairs to JSONL format (one JSON object per line).
+ *
+ * Each line contains:
+ * - id: unique pair identifier
+ * - prompt: the natural language input
+ * - completion: the LSE bracket syntax output
+ * - metadata: domain, action, language, source, quality
+ */
+export declare function toJSONL(pairs: readonly TrainingPair[]): string;
+/**
+ * Convert a single training pair to a JSONL row.
+ */
+export declare function toJSONLRow(pair: TrainingPair): JSONLRow;
+/**
+ * Parse JSONL back into rows (for validation/roundtrip testing).
+ */
+export declare function parseJSONL(text: string): JSONLRow[];
+/**
+ * A single row in JSONL format.
+ */
+export interface JSONLRow {
+    readonly id: string;
+    readonly prompt: string;
+    readonly completion: string;
+    readonly metadata: {
+        readonly domain: string;
+        readonly action: string;
+        readonly language: string;
+        readonly source: string;
+        readonly quality: number;
+        readonly confidence?: number;
+    };
+}
+//# sourceMappingURL=jsonl-writer.d.ts.map

package/dist/training/jsonl-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl-writer.d.ts","sourceRoot":"","sources":["../../src/training/jsonl-writer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAcvD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAKnD;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH"}

package/dist/training/schema-synthesizer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema Synthesizer
+ *
+ * Generates synthetic (natural_language, LSE) training pairs from
+ * CommandSchema[]. Enumerates valid role combinations and produces
+ * examples in both bracket syntax and JSON wire format.
+ */
+import type { CommandSchema } from '../schema/command-schema';
+import type { SynthesisConfig, SynthesisResult } from './types';
+/**
+ * Synthesize training pairs from command schemas.
+ *
+ * Generates multiple examples per command by enumerating role combinations:
+ * 1. Required roles only (minimum viable)
+ * 2. Required + each optional role individually
+ * 3. Required + all optional roles (maximum)
+ * 4. Shuffled role order variants (teaches role-label independence)
+ */
+export declare function synthesizeFromSchemas(schemas: readonly CommandSchema[], config: SynthesisConfig): SynthesisResult;
+//# sourceMappingURL=schema-synthesizer.d.ts.map

package/dist/training/schema-synthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-synthesizer.d.ts","sourceRoot":"","sources":["../../src/training/schema-synthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,0BAA0B,CAAC;AAIxE,OAAO,KAAK,EAAgB,eAAe,EAAE,eAAe,EAAqB,MAAM,SAAS,CAAC;AAMjG;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,MAAM,EAAE,eAAe,GACtB,eAAe,CA2DjB"}

package/dist/training/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Training Data Types
+ *
+ * Types for generating (natural_language, LSE) training pairs from
+ * domain schemas. Used for fine-tuning or few-shot prompting LLMs
+ * to output valid LokaScript Explicit Syntax.
+ */
+import type { SemanticJSON } from '../ir/types';
+/**
+ * A single training pair: natural language ↔ explicit syntax.
+ */
+export interface TrainingPair {
+    /** Unique identifier for deduplication */
+    readonly id: string;
+    /** Natural language form (e.g., "fetch /api/users as json into #list") */
+    readonly natural: string;
+    /** Language code (e.g., "en") */
+    readonly language: string;
+    /** LSE bracket syntax (e.g., "[fetch source:/api/users style:json destination:#list]") */
+    readonly explicit: string;
+    /** LLM-simplified JSON wire format */
+    readonly json: SemanticJSON;
+    /** Domain this pair belongs to */
+    readonly domain: string;
+    /** Command action */
+    readonly action: string;
+    /** How this pair was generated */
+    readonly source: 'synthetic' | 'test' | 'compilation';
+    /** Parse confidence (if from real parsing) */
+    readonly confidence?: number;
+    /** Quality score 0-1 for filtering */
+    readonly quality: number;
+}
+/**
+ * Configuration for training data synthesis.
+ */
+export interface SynthesisConfig {
+    /** Domain identifier */
+    readonly domain: string;
+    /** Maximum pairs per command */
+    readonly maxPairsPerCommand?: number;
+    /** Minimum quality threshold (0-1). Default: 0.5 */
+    readonly minQuality?: number;
+    /** Whether to shuffle role order for some examples. Default: true */
+    readonly shuffleRoles?: boolean;
+    /** Language codes to generate for. Default: ['en'] */
+    readonly languages?: readonly string[];
+}
+/**
+ * Result of training data synthesis.
+ */
+export interface SynthesisResult {
+    /** Generated training pairs */
+    readonly pairs: readonly TrainingPair[];
+    /** Metadata about the synthesis */
+    readonly metadata: SynthesisMetadata;
+}
+/**
+ * Metadata about a synthesis run.
+ */
+export interface SynthesisMetadata {
+    /** Domain the data was synthesized for */
+    readonly domain: string;
+    /** Number of command schemas processed */
+    readonly commandCount: number;
+    /** Total pairs generated */
+    readonly pairCount: number;
+    /** Pairs per source type */
+    readonly bySource: Record<string, number>;
+    /** Languages included */
+    readonly languages: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/training/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/training/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,qBAAqB;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,aAAa,CAAC;IAEtD,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,gCAAgC;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAErC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAExC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokascript/framework",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Generic framework for building multilingual DSLs with semantic parsing and grammar transformation",
   "type": "module",
   "main": "dist/index.cjs",
@@ -55,6 +55,10 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
+    },
+    "./ir": {
+      "types": "./dist/ir/index.d.ts",
+      "import": "./dist/ir/index.js"
     }
   },
   "scripts": {

package/src/aot/index.ts

@@ -6,3 +6,4 @@ export * from './types';
 export { DomainAwareScanner } from './domain-scanner';
 export { AOTOrchestrator } from './aot-orchestrator';
 export type { DomainCompilationBackend } from './aot-orchestrator';
+export { registryToAOTBackends } from './registry-bridge';

package/src/aot/registry-bridge.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { DomainRegistry } from '../api/domain-registry';
+import { registryToAOTBackends } from './registry-bridge';
+
+describe('registryToAOTBackends', () => {
+  it('converts domains with scanConfig to backends', async () => {
+    const registry = new DomainRegistry();
+
+    registry.register({
+      name: 'test-domain',
+      description: 'Test domain',
+      languages: ['en'],
+      inputLabel: 'input',
+      inputDescription: 'Test input',
+      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      scanConfig: {
+        attributes: ['data-test'],
+        scriptTypes: ['text/test'],
+        defaultLanguage: 'en',
+      },
+    });
+
+    const backends = await registryToAOTBackends(registry);
+    expect(backends).toHaveLength(1);
+    expect(backends[0].domain).toBe('test-domain');
+    expect(backends[0].scanConfig.domain).toBe('test-domain');
+    expect(backends[0].scanConfig.attributes).toEqual(['data-test']);
+    expect(backends[0].dsl).toBeDefined();
+    expect(backends[0].codeGenerator).toBeDefined();
+  });
+
+  it('skips domains without scanConfig', async () => {
+    const registry = new DomainRegistry();
+
+    registry.register({
+      name: 'with-config',
+      description: 'Has scanConfig',
+      languages: ['en'],
+      inputLabel: 'input',
+      inputDescription: 'Test',
+      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      scanConfig: {
+        attributes: ['data-with'],
+        defaultLanguage: 'en',
+      },
+    });
+
+    registry.register({
+      name: 'without-config',
+      description: 'No scanConfig',
+      languages: ['en'],
+      inputLabel: 'input',
+      inputDescription: 'Test',
+      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      // no scanConfig
+    });
+
+    const backends = await registryToAOTBackends(registry);
+    expect(backends).toHaveLength(1);
+    expect(backends[0].domain).toBe('with-config');
+  });
+
+  it('returns empty array when no domains have scanConfig', async () => {
+    const registry = new DomainRegistry();
+
+    registry.register({
+      name: 'no-scan',
+      description: 'No scanConfig',
+      languages: ['en'],
+      inputLabel: 'input',
+      inputDescription: 'Test',
+      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+    });
+
+    const backends = await registryToAOTBackends(registry);
+    expect(backends).toHaveLength(0);
+  });
+
+  it('codeGenerator produces JSON from semantic node', async () => {
+    const registry = new DomainRegistry();
+
+    registry.register({
+      name: 'gen-test',
+      description: 'Generator test',
+      languages: ['en'],
+      inputLabel: 'input',
+      inputDescription: 'Test',
+      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      scanConfig: {
+        attributes: ['data-gen'],
+        defaultLanguage: 'en',
+      },
+    });
+
+    const backends = await registryToAOTBackends(registry);
+    const node = {
+      action: 'select',
+      roles: new Map([['source', { type: 'expression' as const, raw: 'users' }]]),
+    };
+    const output = backends[0].codeGenerator.generate(node as any);
+    const parsed = JSON.parse(output);
+    expect(parsed.action).toBe('select');
+  });
+});

package/src/aot/registry-bridge.ts

@@ -0,0 +1,66 @@
+/**
+ * Registry-to-AOT Bridge
+ *
+ * Converts DomainRegistry entries into DomainCompilationBackend instances
+ * for use with AOTOrchestrator. Only domains that have scanConfig defined
+ * are included.
+ *
+ * @example
+ * ```typescript
+ * const registry = new DomainRegistry();
+ * // ... register domains with scanConfig ...
+ *
+ * const backends = await registryToAOTBackends(registry);
+ * const orchestrator = new AOTOrchestrator();
+ * for (const backend of backends) {
+ *   orchestrator.registerBackend(backend);
+ * }
+ * ```
+ */
+
+import type { DomainCompilationBackend } from './aot-orchestrator';
+import type { DomainScanConfig } from './types';
+import type { DomainRegistry } from '../api/domain-registry';
+import type { CodeGenerator } from '../api/create-dsl';
+import type { SemanticNode } from '../core/types';
+
+/**
+ * Convert all registry entries with scanConfig into AOT backends.
+ * Domains without scanConfig are skipped.
+ */
+export async function registryToAOTBackends(
+  registry: DomainRegistry
+): Promise<DomainCompilationBackend[]> {
+  const backends: DomainCompilationBackend[] = [];
+
+  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: DomainScanConfig = {
+      domain: name,
+      attributes: [...descriptor.scanConfig.attributes],
+      ...(descriptor.scanConfig.scriptTypes
+        ? { scriptTypes: [...descriptor.scanConfig.scriptTypes] }
+        : {}),
+      defaultLanguage: descriptor.scanConfig.defaultLanguage ?? 'en',
+    };
+
+    // The AOTOrchestrator only calls backend.dsl.compile(), not codeGenerator directly.
+    // Provide a thin adapter that parses then generates via the DSL's internal pipeline.
+    const codeGenerator: CodeGenerator = {
+      generate(node: SemanticNode): string {
+        // Fallback: compile through the DSL by reconstructing explicit syntax.
+        // In practice, AOTOrchestrator uses dsl.compile() directly.
+        return JSON.stringify({ action: node.action, roles: Object.fromEntries(node.roles) });
+      },
+    };
+
+    backends.push({ domain: name, dsl, codeGenerator, scanConfig });
+  }
+
+  return backends;
+}

package/src/api/create-dsl.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Tests for MultilingualDSLImpl explicit syntax support.
+ *
+ * Verifies that createMultilingualDSL() returns a DSL that accepts
+ * explicit bracket syntax [command role:value ...] as input, in addition
+ * to natural language.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createMultilingualDSL,
+  defineCommand,
+  defineRole,
+  BaseTokenizer,
+  getDefaultExtractors,
+  type SemanticNode,
+} from '../index';
+
+// =============================================================================
+// Test Helpers
+// =============================================================================
+
+const selectSchema = defineCommand({
+  action: 'select',
+  description: 'Select data',
+  category: 'query',
+  primaryRole: 'columns',
+  roles: [
+    defineRole({
+      role: 'columns',
+      description: 'Columns to select',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+    }),
+    defineRole({
+      role: 'source',
+      description: 'Table to select from',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      markerOverride: { en: 'from' },
+    }),
+  ],
+});
+
+const insertSchema = defineCommand({
+  action: 'insert',
+  description: 'Insert data',
+  category: 'mutation',
+  primaryRole: 'values',
+  roles: [
+    defineRole({
+      role: 'values',
+      description: 'Values to insert',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'Target table',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      markerOverride: { en: 'into' },
+    }),
+  ],
+});
+
+class EnglishTestTokenizer extends BaseTokenizer {
+  readonly language = 'en';
+  readonly direction = 'ltr' as const;
+
+  constructor() {
+    super();
+    this.registerExtractors(getDefaultExtractors());
+  }
+
+  classifyToken(token: string): 'keyword' | 'identifier' | 'literal' | 'operator' {
+    const keywords = ['select', 'insert', 'from', 'into'];
+    if (keywords.includes(token.toLowerCase())) return 'keyword';
+    return 'identifier';
+  }
+}
+
+const englishProfile = {
+  code: 'en',
+  name: 'English',
+  nativeName: 'English',
+  wordOrder: 'SVO' as const,
+  direction: 'ltr' as const,
+  caseMarking: 'preposition' as const,
+  keywords: {
+    select: { primary: 'select', aliases: [] },
+    insert: { primary: 'insert', aliases: [] },
+    from: { primary: 'from', aliases: [] },
+    into: { primary: 'into', aliases: [] },
+  },
+  roleMarkers: {},
+};
+
+function createTestDSL() {
+  return createMultilingualDSL({
+    name: 'TestSQL',
+    schemas: [selectSchema, insertSchema],
+    languages: [
+      {
+        code: 'en',
+        name: 'English',
+        nativeName: 'English',
+        tokenizer: new EnglishTestTokenizer(),
+        patternProfile: englishProfile,
+      },
+    ],
+    codeGenerator: {
+      generate(node: SemanticNode): string {
+        const action = node.action.toUpperCase();
+        const roles: string[] = [];
+        for (const [role, value] of node.roles) {
+          const v =
+            value && 'value' in value
+              ? value.value
+              : value && 'raw' in value
+                ? value.raw
+                : String(value);
+          roles.push(`${role}=${v}`);
+        }
+        return `${action} ${roles.join(' ')}`;
+      },
+    },
+  });
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('MultilingualDSL: Explicit Syntax Support', () => {
+  // ---------------------------------------------------------------------------
+  // parseWithConfidence
+  // ---------------------------------------------------------------------------
+
+  describe('parseWithConfidence', () => {
+    it('parses explicit bracket syntax with confidence 1.0', () => {
+      const dsl = createTestDSL();
+      const result = dsl.parseWithConfidence('[select columns:name source:users]', 'en');
+
+      expect(result.confidence).toBe(1.0);
+      expect(result.node.action).toBe('select');
+      expect(result.node.kind).toBe('command');
+    });
+
+    it('extracts roles from explicit syntax', () => {
+      const dsl = createTestDSL();
+      const result = dsl.parseWithConfidence('[select columns:name source:users]', 'en');
+
+      const columns = result.node.roles.get('columns');
+      const source = result.node.roles.get('source');
+      expect(columns).toBeDefined();
+      expect(source).toBeDefined();
+      expect(columns && 'value' in columns ? columns.value : undefined).toBe('name');
+      expect(source && 'value' in source ? source.value : undefined).toBe('users');
+    });
+
+    it('throws for explicit syntax with unknown action', () => {
+      const dsl = createTestDSL();
+      expect(() => {
+        dsl.parseWithConfidence('[deploy destination:production]', 'en');
+      }).toThrow('No schema for action "deploy"');
+    });
+
+    it('validates roles against schema', () => {
+      const dsl = createTestDSL();
+      expect(() => {
+        dsl.parseWithConfidence('[select columns:name bogus:value]', 'en');
+      }).toThrow('Unknown role "bogus"');
+    });
+
+    it('validates required roles', () => {
+      const dsl = createTestDSL();
+      expect(() => {
+        dsl.parseWithConfidence('[select columns:name]', 'en');
+      }).toThrow('Missing required role "source"');
+    });
+
+    it('works with any language parameter for explicit syntax', () => {
+      const dsl = createTestDSL();
+      // Explicit syntax is language-agnostic — language param is ignored
+      const result = dsl.parseWithConfidence('[select columns:name source:users]', 'ja');
+      expect(result.confidence).toBe(1.0);
+      expect(result.node.action).toBe('select');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // parse
+  // ---------------------------------------------------------------------------
+
+  describe('parse', () => {
+    it('parses explicit syntax and returns SemanticNode', () => {
+      const dsl = createTestDSL();
+      const node = dsl.parse('[insert values:data destination:users]', 'en');
+
+      expect(node.action).toBe('insert');
+      expect(node.roles.has('values')).toBe(true);
+      expect(node.roles.has('destination')).toBe(true);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // compile
+  // ---------------------------------------------------------------------------
+
+  describe('compile', () => {
+    it('compiles explicit syntax through code generator', () => {
+      const dsl = createTestDSL();
+      const result = dsl.compile('[select columns:name source:users]', 'en');
+
+      expect(result.ok).toBe(true);
+      expect(result.code).toContain('SELECT');
+      expect(result.code).toContain('columns=name');
+      expect(result.code).toContain('source=users');
+    });
+
+    it('returns metadata with parser=explicit and confidence=1.0', () => {
+      const dsl = createTestDSL();
+      const result = dsl.compile('[select columns:name source:users]', 'en');
+
+      expect(result.metadata?.confidence).toBe(1.0);
+    });
+
+    it('returns error for explicit syntax with unknown action', () => {
+      const dsl = createTestDSL();
+      const result = dsl.compile('[deploy destination:production]', 'en');
+
+      expect(result.ok).toBe(false);
+      expect(result.errors?.[0]).toContain('No schema for action "deploy"');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // validate
+  // ---------------------------------------------------------------------------
+
+  describe('validate', () => {
+    it('validates correct explicit syntax', () => {
+      const dsl = createTestDSL();
+      const result = dsl.validate('[select columns:name source:users]', 'en');
+
+      expect(result.valid).toBe(true);
+      expect(result.node?.action).toBe('select');
+    });
+
+    it('returns invalid for explicit syntax with unknown action', () => {
+      const dsl = createTestDSL();
+      const result = dsl.validate('[deploy destination:production]', 'en');
+
+      expect(result.valid).toBe(false);
+      expect(result.errors?.[0]).toContain('No schema for action "deploy"');
+    });
+
+    it('returns invalid for explicit syntax with bad roles', () => {
+      const dsl = createTestDSL();
+      const result = dsl.validate('[select columns:name bogus:value]', 'en');
+
+      expect(result.valid).toBe(false);
+      expect(result.errors?.[0]).toContain('Unknown role "bogus"');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // translate
+  // ---------------------------------------------------------------------------
+
+  describe('translate', () => {
+    it('returns explicit syntax unchanged', () => {
+      const dsl = createTestDSL();
+      const result = dsl.translate('[select columns:name source:users]', 'en', 'ja');
+      expect(result).toBe('[select columns:name source:users]');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Natural language regression
+  // ---------------------------------------------------------------------------
+
+  describe('natural language (regression)', () => {
+    it('still parses natural language input', () => {
+      const dsl = createTestDSL();
+      const result = dsl.parseWithConfidence('select name from users', 'en');
+
+      expect(result.node.action).toBe('select');
+      expect(result.confidence).toBeGreaterThan(0);
+      expect(result.confidence).toBeLessThanOrEqual(1.0);
+    });
+
+    it('still compiles natural language input', () => {
+      const dsl = createTestDSL();
+      const result = dsl.compile('select name from users', 'en');
+
+      expect(result.ok).toBe(true);
+      expect(result.code).toContain('SELECT');
+    });
+  });
+});