@lokascript/framework 2.6.0 → 2.7.0

package/src/multilingual/bridge.test.ts

@@ -0,0 +1,441 @@
+/**
+ * Tests for the framework ↔ semantic bridge builders.
+ *
+ * Uses inline fixture slices (en-like SVO, ja-like SOV particle, ar-like RTL
+ * VSO) — no semantic dependency: any `@lokascript/semantic` LanguageProfile
+ * satisfies GrammarProfileSlice structurally, and so do these fixtures.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildPatternProfile,
+  buildDomainTokenizer,
+  buildLanguageConfig,
+  deriveRoleMarkers,
+} from './builders';
+import type { GrammarProfileSlice, DomainVocabulary } from './types';
+import { generatePattern } from '../generation/pattern-generator';
+import { defineCommand, defineRole } from '../schema';
+import { createMultilingualDSL } from '../api/create-dsl';
+
+// =============================================================================
+// Fixture slices (mirror the shape of semantic KNOWN_PROFILES entries)
+// =============================================================================
+
+const EN_SLICE: GrammarProfileSlice = {
+  code: 'en',
+  name: 'English',
+  nativeName: 'English',
+  wordOrder: 'SVO',
+  direction: 'ltr',
+  script: 'latin',
+  usesSpaces: true,
+  markingStrategy: 'preposition',
+  roleMarkers: {
+    source: { primary: 'from', position: 'before' },
+    destination: { primary: 'into', alternatives: ['to'], position: 'before' },
+  },
+};
+
+const JA_SLICE: GrammarProfileSlice = {
+  code: 'ja',
+  name: 'Japanese',
+  nativeName: '日本語',
+  wordOrder: 'SOV',
+  direction: 'ltr',
+  script: 'cjk',
+  usesSpaces: false,
+  markingStrategy: 'particle',
+  tokenization: { particles: ['を', 'に', 'から'], boundaryStrategy: 'particle' },
+  roleMarkers: {
+    patient: { primary: 'を', position: 'after' },
+    destination: { primary: 'に', alternatives: ['へ'], position: 'after' },
+    source: { primary: 'から', position: 'after' },
+  },
+};
+
+const AR_SLICE: GrammarProfileSlice = {
+  code: 'ar',
+  wordOrder: 'VSO',
+  direction: 'rtl',
+  script: 'arabic',
+  usesSpaces: true,
+  markingStrategy: 'preposition',
+  roleMarkers: {
+    source: { primary: 'من', position: 'before' },
+    destination: { primary: 'في', position: 'before' },
+  },
+};
+
+const EN_VOCAB: DomainVocabulary = {
+  keywords: {
+    select: { primary: 'select', alternatives: ['get'] },
+    insert: { primary: 'insert' },
+  },
+  tokenizerKeywords: ['where', 'and'],
+};
+
+const JA_VOCAB: DomainVocabulary = {
+  keywords: {
+    select: { primary: '選択' },
+    insert: { primary: '挿入' },
+  },
+  roleMarkerOverrides: {
+    condition: { primary: '条件', position: 'before' },
+  },
+};
+
+const AR_VOCAB: DomainVocabulary = {
+  keywords: {
+    select: { primary: 'اختر' },
+    insert: { primary: 'أدخل' },
+  },
+};
+
+// =============================================================================
+// GrammarProfileSlice structural acceptance
+// =============================================================================
+
+describe('GrammarProfileSlice', () => {
+  it('accepts a full semantic-LanguageProfile-shaped object without a cast', () => {
+    // Mirrors the field set of a semantic LanguageProfile, including the
+    // hyperscript-specific fields the slice ignores (keywords, references,
+    // possessive, eventHandler). Structural typing must accept it as-is.
+    const semanticShaped = {
+      code: 'ja',
+      name: 'Japanese',
+      nativeName: '日本語',
+      regions: ['east-asian', 'priority'],
+      direction: 'ltr',
+      script: 'cjk',
+      wordOrder: 'SOV',
+      markingStrategy: 'particle',
+      usesSpaces: false,
+      defaultVerbForm: 'base',
+      verb: { position: 'end', suffixes: ['る', 'て'], subjectDrop: true },
+      references: { me: '自分', it: 'それ' },
+      possessive: { marker: 'の', markerPosition: 'between' },
+      roleMarkers: {
+        patient: { primary: 'を', position: 'after' },
+        destination: { primary: 'に', alternatives: ['へ', 'で'], position: 'after' },
+      },
+      keywords: {
+        toggle: { primary: '切り替え', alternatives: ['トグル'], normalized: 'toggle' },
+      },
+      tokenization: { particles: ['を', 'に'], boundaryStrategy: 'particle' },
+    } as const;
+
+    const slice: GrammarProfileSlice = semanticShaped;
+    expect(slice.code).toBe('ja');
+    expect(slice.roleMarkers?.patient?.primary).toBe('を');
+  });
+});
+
+// =============================================================================
+// buildPatternProfile
+// =============================================================================
+
+describe('buildPatternProfile', () => {
+  it('combines domain keywords with slice grammar', () => {
+    const profile = buildPatternProfile(EN_SLICE, EN_VOCAB);
+
+    expect(profile.code).toBe('en');
+    expect(profile.wordOrder).toBe('SVO');
+    expect(profile.keywords.select).toEqual({ primary: 'select', alternatives: ['get'] });
+    expect(profile.keywords.insert).toEqual({ primary: 'insert' });
+    expect(profile.roleMarkers?.source).toEqual({ primary: 'from', position: 'before' });
+    expect(profile.roleMarkers?.destination).toEqual({
+      primary: 'into',
+      alternatives: ['to'],
+      position: 'before',
+    });
+  });
+
+  it('merges vocab roleMarkerOverrides over slice markers (vocab wins, adds domain roles)', () => {
+    const profile = buildPatternProfile(JA_SLICE, JA_VOCAB);
+
+    // Slice defaults preserved
+    expect(profile.roleMarkers?.patient).toEqual({ primary: 'を', position: 'after' });
+    // Domain-specific role added by the vocabulary
+    expect(profile.roleMarkers?.condition).toEqual({ primary: '条件', position: 'before' });
+  });
+
+  it('lets an override replace a slice marker, and an empty primary remove one', () => {
+    const vocab: DomainVocabulary = {
+      keywords: { select: { primary: 'seç' } },
+      roleMarkerOverrides: {
+        source: { primary: 'den', position: 'after' },
+        destination: { primary: '' },
+      },
+    };
+    const profile = buildPatternProfile(JA_SLICE, vocab);
+
+    expect(profile.roleMarkers?.source).toEqual({ primary: 'den', position: 'after' });
+    expect(profile.roleMarkers?.destination).toBeUndefined();
+  });
+
+  it('omits roleMarkers entirely when neither slice nor vocab provides any', () => {
+    const bare: GrammarProfileSlice = { code: 'xx', wordOrder: 'SVO' };
+    const profile = buildPatternProfile(bare, { keywords: { go: { primary: 'go' } } });
+
+    expect(profile.roleMarkers).toBeUndefined();
+  });
+
+  it('copies alternatives into fresh mutable arrays', () => {
+    const profile = buildPatternProfile(EN_SLICE, EN_VOCAB);
+    const alternatives = EN_VOCAB.keywords.select.alternatives!;
+
+    expect(profile.keywords.select.alternatives).not.toBe(alternatives);
+    expect(profile.keywords.select.alternatives).toEqual([...alternatives]);
+  });
+
+  describe('generatePattern integration', () => {
+    const moveSchema = defineCommand({
+      action: 'move',
+      description: 'Move a thing',
+      category: 'test',
+      primaryRole: 'patient',
+      roles: [
+        defineRole({
+          role: 'patient',
+          required: true,
+          expectedTypes: ['expression'],
+          svoPosition: 2,
+          sovPosition: 2,
+        }),
+        defineRole({
+          role: 'destination',
+          required: true,
+          expectedTypes: ['expression'],
+          svoPosition: 1,
+          sovPosition: 1,
+        }),
+      ],
+    });
+
+    it('SVO (en-like): keyword first, prepositional marker before its role', () => {
+      const vocab: DomainVocabulary = { keywords: { move: { primary: 'move' } } };
+      const pattern = generatePattern(moveSchema, buildPatternProfile(EN_SLICE, vocab));
+
+      expect(pattern.template.tokens).toEqual([
+        { type: 'literal', value: 'move' },
+        { type: 'role', role: 'patient', optional: false, expectedTypes: ['expression'] },
+        { type: 'literal', value: 'into' },
+        { type: 'role', role: 'destination', optional: false, expectedTypes: ['expression'] },
+      ]);
+    });
+
+    it('SOV (ja-like): particles after their roles, verb last', () => {
+      const vocab: DomainVocabulary = { keywords: { move: { primary: '移動' } } };
+      const pattern = generatePattern(moveSchema, buildPatternProfile(JA_SLICE, vocab));
+
+      expect(pattern.template.tokens).toEqual([
+        { type: 'role', role: 'patient', optional: false, expectedTypes: ['expression'] },
+        { type: 'literal', value: 'を' },
+        { type: 'role', role: 'destination', optional: false, expectedTypes: ['expression'] },
+        { type: 'literal', value: 'に' },
+        { type: 'literal', value: '移動' },
+      ]);
+    });
+
+    it('VSO (ar-like): verb first', () => {
+      const vocab: DomainVocabulary = { keywords: { move: { primary: 'انقل' } } };
+      const pattern = generatePattern(moveSchema, buildPatternProfile(AR_SLICE, vocab));
+
+      expect(pattern.template.tokens[0]).toEqual({ type: 'literal', value: 'انقل' });
+    });
+  });
+});
+
+// =============================================================================
+// buildDomainTokenizer
+// =============================================================================
+
+describe('buildDomainTokenizer', () => {
+  it('sets language and direction from the slice', () => {
+    expect(buildDomainTokenizer(EN_SLICE, EN_VOCAB).language).toBe('en');
+    expect(buildDomainTokenizer(EN_SLICE, EN_VOCAB).direction).toBe('ltr');
+    expect(buildDomainTokenizer(AR_SLICE, AR_VOCAB).direction).toBe('rtl');
+  });
+
+  it('classifies vocab verbs, alternatives, slice markers, and extra keywords as keywords', () => {
+    const tokenizer = buildDomainTokenizer(EN_SLICE, EN_VOCAB);
+
+    expect(tokenizer.classifyToken('select')).toBe('keyword');
+    expect(tokenizer.classifyToken('get')).toBe('keyword'); // alternative
+    expect(tokenizer.classifyToken('from')).toBe('keyword'); // slice role marker
+    expect(tokenizer.classifyToken('to')).toBe('keyword'); // marker alternative
+    expect(tokenizer.classifyToken('where')).toBe('keyword'); // tokenizerKeywords
+    expect(tokenizer.classifyToken('users')).toBe('identifier');
+    expect(tokenizer.classifyToken('42')).toBe('literal');
+  });
+
+  it('is case-insensitive by default for Latin scripts', () => {
+    const tokenizer = buildDomainTokenizer(EN_SLICE, EN_VOCAB);
+    expect(tokenizer.classifyToken('SELECT')).toBe('keyword');
+    expect(tokenizer.classifyToken('From')).toBe('keyword');
+  });
+
+  it('classifies particles and non-Latin verbs as keywords (ja-like)', () => {
+    const tokenizer = buildDomainTokenizer(JA_SLICE, JA_VOCAB);
+
+    expect(tokenizer.classifyToken('選択')).toBe('keyword');
+    expect(tokenizer.classifyToken('を')).toBe('keyword'); // tokenization particle
+    expect(tokenizer.classifyToken('条件')).toBe('keyword'); // vocab roleMarkerOverride
+  });
+
+  it('excludes operators by default (matching createSimpleTokenizer) and honors includeOperators: true', () => {
+    const defaultTokenizer = buildDomainTokenizer(EN_SLICE, EN_VOCAB);
+    const withOps = buildDomainTokenizer(EN_SLICE, EN_VOCAB, { includeOperators: true });
+
+    expect(defaultTokenizer.classifyToken('=')).toBe('identifier');
+    expect(withOps.classifyToken('=')).toBe('operator');
+  });
+
+  it('keeps diacritic identifiers whole for latin-script slices (R8 by construction)', () => {
+    const esSlice: GrammarProfileSlice = { code: 'es', wordOrder: 'SVO', script: 'latin' };
+    const vocab: DomainVocabulary = { keywords: { insert: { primary: 'añadir' } } };
+    const tokenizer = buildDomainTokenizer(esSlice, vocab);
+
+    const stream = tokenizer.tokenize('añadir usuarios');
+    const first = stream.advance();
+    expect(first.value).toBe('añadir');
+    expect(tokenizer.classifyToken(first.value)).toBe('keyword');
+  });
+
+  it('tokenizes multi-word vocab keywords as a single normalized token', () => {
+    const frSlice: GrammarProfileSlice = { code: 'fr', wordOrder: 'SVO', script: 'latin' };
+    const vocab: DomainVocabulary = { keywords: { update: { primary: 'mettre à jour' } } };
+    const tokenizer = buildDomainTokenizer(frSlice, vocab);
+
+    const stream = tokenizer.tokenize('mettre à jour utilisateurs');
+    const first = stream.advance();
+    expect(first.value).toBe('mettre à jour');
+    expect(first.kind).toBe('keyword');
+    expect(first.normalized).toBe('update');
+  });
+
+  it('threads vocab keywordExtras into the keyword map', () => {
+    const vocab: DomainVocabulary = {
+      ...JA_VOCAB,
+      keywordExtras: [{ native: 'すべて 削除', normalized: 'truncate' }],
+    };
+    const tokenizer = buildDomainTokenizer(JA_SLICE, vocab);
+
+    const stream = tokenizer.tokenize('すべて 削除');
+    const first = stream.advance();
+    expect(first.value).toBe('すべて 削除');
+    expect(first.normalized).toBe('truncate');
+  });
+});
+
+// =============================================================================
+// buildLanguageConfig
+// =============================================================================
+
+describe('buildLanguageConfig', () => {
+  it('assembles a complete LanguageConfig from slice + vocab', () => {
+    const config = buildLanguageConfig(JA_SLICE, JA_VOCAB);
+
+    expect(config.code).toBe('ja');
+    expect(config.name).toBe('Japanese');
+    expect(config.nativeName).toBe('日本語');
+    expect(config.tokenizer.language).toBe('ja');
+    expect(config.patternProfile.code).toBe('ja');
+    expect(config.patternProfile.wordOrder).toBe('SOV');
+  });
+
+  it('falls back to the language code when the slice has no names', () => {
+    const config = buildLanguageConfig(AR_SLICE, AR_VOCAB);
+
+    expect(config.name).toBe('ar');
+    expect(config.nativeName).toBe('ar');
+  });
+
+  it('lets meta override names and tokenizer', () => {
+    const customTokenizer = buildDomainTokenizer(EN_SLICE, EN_VOCAB, { includeOperators: false });
+    const config = buildLanguageConfig(EN_SLICE, EN_VOCAB, {
+      name: 'English (US)',
+      nativeName: 'American English',
+      tokenizer: customTokenizer,
+    });
+
+    expect(config.name).toBe('English (US)');
+    expect(config.nativeName).toBe('American English');
+    expect(config.tokenizer).toBe(customTokenizer);
+  });
+
+  describe('createMultilingualDSL integration', () => {
+    const selectSchema = defineCommand({
+      action: 'select',
+      description: 'Select data',
+      category: 'query',
+      primaryRole: 'columns',
+      roles: [
+        defineRole({
+          role: 'columns',
+          required: true,
+          expectedTypes: ['expression'],
+          svoPosition: 2,
+          sovPosition: 1,
+        }),
+        defineRole({
+          role: 'source',
+          required: true,
+          expectedTypes: ['expression'],
+          svoPosition: 1,
+          sovPosition: 2,
+        }),
+      ],
+    });
+
+    const dsl = createMultilingualDSL({
+      name: 'BridgeTestSQL',
+      schemas: [selectSchema],
+      languages: [buildLanguageConfig(EN_SLICE, EN_VOCAB), buildLanguageConfig(JA_SLICE, JA_VOCAB)],
+    });
+
+    it('parses English through a bridge-built config', () => {
+      const node = dsl.parse('select name from users', 'en');
+
+      expect(node.action).toBe('select');
+      expect(node.roles.has('columns')).toBe(true);
+      expect(node.roles.has('source')).toBe(true);
+    });
+
+    it('parses Japanese (SOV, particle markers) through a bridge-built config', () => {
+      const node = dsl.parse('users から name 選択', 'ja');
+
+      expect(node.action).toBe('select');
+      expect(node.roles.has('source')).toBe(true);
+    });
+  });
+});
+
+// =============================================================================
+// deriveRoleMarkers
+// =============================================================================
+
+describe('deriveRoleMarkers', () => {
+  it('maps domain roles to the slice markers of their semantic counterparts', () => {
+    expect(deriveRoleMarkers(JA_SLICE, { table: 'source', target: 'destination' })).toEqual({
+      table: 'から',
+      target: 'に',
+    });
+    expect(deriveRoleMarkers(EN_SLICE, { table: 'source', target: 'destination' })).toEqual({
+      table: 'from',
+      target: 'into',
+    });
+  });
+
+  it('omits domain roles whose semantic role has no marker in the slice', () => {
+    expect(deriveRoleMarkers(EN_SLICE, { table: 'source', cond: 'condition' })).toEqual({
+      table: 'from',
+    });
+  });
+
+  it('returns an empty record for a slice without roleMarkers', () => {
+    const bare: GrammarProfileSlice = { code: 'xx', wordOrder: 'SVO' };
+    expect(deriveRoleMarkers(bare, { table: 'source' })).toEqual({});
+  });
+});

package/src/multilingual/builders.ts

@@ -0,0 +1,224 @@
+/**
+ * Framework ↔ Semantic bridge builders.
+ *
+ * Pure functions that combine an injected {@link GrammarProfileSlice} (the
+ * per-language grammar facts, typically a `@lokascript/semantic`
+ * `LanguageProfile`) with a {@link DomainVocabulary} (the only thing a domain
+ * authors per language) into the shapes `createMultilingualDSL` consumes:
+ * a `PatternGenLanguageProfile`, a `LanguageTokenizer`, or a complete
+ * `LanguageConfig`.
+ */
+
+import type { LanguageTokenizer } from '../core/types';
+import type { PatternGenLanguageProfile } from '../generation/pattern-generator';
+import type { LanguageConfig } from '../api/create-dsl';
+import type { LanguageProfile as GrammarProfile } from '../grammar';
+import { createSimpleTokenizer, type TokenizerProfile } from '../core/tokenization/base-tokenizer';
+import {
+  LatinExtendedIdentifierExtractor,
+  type ValueExtractor,
+} from '../interfaces/value-extractor';
+import type { DomainVocabulary, GrammarProfileSlice, RoleMarkerSlice } from './types';
+
+/** Mutable role-marker shape shared by PatternGenLanguageProfile and TokenizerProfile. */
+type MergedRoleMarker = { primary: string; alternatives?: string[]; position?: 'before' | 'after' };
+
+/**
+ * Merge the slice's language-default role markers with the vocabulary's
+ * domain-specific overrides (vocabulary wins). Empty-string primaries are
+ * dropped — an empty override means "bare positional arg, no marker".
+ */
+function mergeRoleMarkers(
+  slice: GrammarProfileSlice,
+  vocab: DomainVocabulary
+): Record<string, MergedRoleMarker> {
+  const merged: Record<string, MergedRoleMarker> = {};
+  const add = (role: string, marker: RoleMarkerSlice | undefined) => {
+    if (!marker?.primary) {
+      delete merged[role];
+      return;
+    }
+    merged[role] = {
+      primary: marker.primary,
+      ...(marker.alternatives?.length && { alternatives: [...marker.alternatives] }),
+      ...(marker.position && { position: marker.position }),
+    };
+  };
+  for (const [role, marker] of Object.entries(slice.roleMarkers ?? {})) add(role, marker);
+  for (const [role, marker] of Object.entries(vocab.roleMarkerOverrides ?? {})) add(role, marker);
+  return merged;
+}
+
+/**
+ * Build a pattern-generation profile: domain keywords + slice grammar
+ * (word order, role markers). The result feeds `generatePattern` /
+ * `generatePatternVariants` and `LanguageConfig.patternProfile`.
+ */
+export function buildPatternProfile(
+  slice: GrammarProfileSlice,
+  vocab: DomainVocabulary
+): PatternGenLanguageProfile {
+  const keywords: Record<string, { primary: string; alternatives?: string[] }> = {};
+  for (const [action, translation] of Object.entries(vocab.keywords)) {
+    keywords[action] = {
+      primary: translation.primary,
+      ...(translation.alternatives?.length && { alternatives: [...translation.alternatives] }),
+    };
+  }
+
+  const roleMarkers = mergeRoleMarkers(slice, vocab);
+
+  return {
+    code: slice.code,
+    wordOrder: slice.wordOrder,
+    keywords,
+    ...(Object.keys(roleMarkers).length > 0 && { roleMarkers }),
+  };
+}
+
+/** Options for {@link buildDomainTokenizer}, overriding the slice-derived defaults. */
+export interface DomainTokenizerOptions {
+  /**
+   * Recognize operator tokens (default: false, matching `createSimpleTokenizer`).
+   * Domains whose grammar contains operators (e.g. SQL's `WHERE age > 18`) pass
+   * `true`; most natural-language DSLs leave it off.
+   */
+  readonly includeOperators?: boolean;
+  /**
+   * Case-insensitive keyword matching. Defaults to true for bicameral scripts
+   * (`latin`, `cyrillic`, or when the slice omits `script`), false otherwise.
+   */
+  readonly caseInsensitive?: boolean;
+  /** Extra extractors, registered before the slice-derived ones */
+  readonly customExtractors?: readonly ValueExtractor[];
+}
+
+function defaultCaseInsensitive(script: string | undefined): boolean {
+  return script === undefined || script === 'latin' || script === 'cyrillic';
+}
+
+/**
+ * Build a domain tokenizer from a grammar slice + domain vocabulary, wrapping
+ * `createSimpleTokenizer`. Derived from the slice:
+ *
+ * - `direction` (rtl for e.g. Arabic/Hebrew slices)
+ * - keyword set: vocabulary verbs (primary + alternatives), role markers
+ *   (slice defaults merged with `vocab.roleMarkerOverrides`), tokenization
+ *   particles, and `vocab.tokenizerKeywords`
+ * - keyword-normalization profile (native verb → action name, marker → role)
+ * - a `LatinExtendedIdentifierExtractor` when `slice.script === 'latin'`, so
+ *   diacritics (ñ, é, ş, …) never split identifiers
+ * - case-insensitivity for bicameral scripts
+ */
+export function buildDomainTokenizer(
+  slice: GrammarProfileSlice,
+  vocab: DomainVocabulary,
+  options: DomainTokenizerOptions = {}
+): LanguageTokenizer {
+  const roleMarkers = mergeRoleMarkers(slice, vocab);
+
+  // Flat keyword list for token classification.
+  const keywords = new Set<string>();
+  for (const translation of Object.values(vocab.keywords)) {
+    keywords.add(translation.primary);
+    for (const alt of translation.alternatives ?? []) keywords.add(alt);
+  }
+  for (const marker of Object.values(roleMarkers)) {
+    keywords.add(marker.primary);
+    for (const alt of marker.alternatives ?? []) keywords.add(alt);
+  }
+  for (const particle of slice.tokenization?.particles ?? []) keywords.add(particle);
+  for (const extra of vocab.tokenizerKeywords ?? []) keywords.add(extra);
+
+  // Normalization profile: native verb forms → action names, markers → roles.
+  const profileKeywords: NonNullable<TokenizerProfile['keywords']> = {};
+  for (const [action, translation] of Object.entries(vocab.keywords)) {
+    profileKeywords[action] = {
+      primary: translation.primary,
+      ...(translation.alternatives?.length && { alternatives: [...translation.alternatives] }),
+      normalized: translation.normalized ?? action,
+    };
+  }
+  const keywordProfile: TokenizerProfile = {
+    keywords: profileKeywords,
+    ...(Object.keys(roleMarkers).length > 0 && { roleMarkers }),
+  };
+
+  const customExtractors: ValueExtractor[] = [
+    ...(options.customExtractors ?? []),
+    ...(slice.script === 'latin' ? [new LatinExtendedIdentifierExtractor()] : []),
+  ];
+
+  return createSimpleTokenizer({
+    language: slice.code,
+    direction: slice.direction ?? 'ltr',
+    keywords: [...keywords],
+    ...(vocab.keywordExtras?.length && { keywordExtras: vocab.keywordExtras.map(e => ({ ...e })) }),
+    keywordProfile,
+    includeOperators: options.includeOperators ?? false,
+    caseInsensitive: options.caseInsensitive ?? defaultCaseInsensitive(slice.script),
+    ...(customExtractors.length > 0 && { customExtractors }),
+  });
+}
+
+/** Metadata / overrides for {@link buildLanguageConfig}. */
+export interface LanguageConfigMeta {
+  /** English name (default: `slice.name`, falling back to `slice.code`) */
+  readonly name?: string;
+  /** Native name (default: `slice.nativeName`, falling back to the English name) */
+  readonly nativeName?: string;
+  /** Grammar-transformation profile to attach (optional, as on `LanguageConfig`) */
+  readonly grammarProfile?: GrammarProfile;
+  /** Use this tokenizer instead of the slice-derived one */
+  readonly tokenizer?: LanguageTokenizer;
+  /** Options for the slice-derived tokenizer (ignored when `tokenizer` is given) */
+  readonly tokenizerOptions?: DomainTokenizerOptions;
+}
+
+/**
+ * The one-call path into `createMultilingualDSL`: build a complete
+ * `LanguageConfig` (tokenizer + pattern profile + names) from a grammar slice
+ * and a domain vocabulary.
+ */
+export function buildLanguageConfig(
+  slice: GrammarProfileSlice,
+  vocab: DomainVocabulary,
+  meta: LanguageConfigMeta = {}
+): LanguageConfig {
+  const name = meta.name ?? slice.name ?? slice.code;
+  return {
+    code: slice.code,
+    name,
+    nativeName: meta.nativeName ?? slice.nativeName ?? name,
+    tokenizer: meta.tokenizer ?? buildDomainTokenizer(slice, vocab, meta.tokenizerOptions),
+    patternProfile: buildPatternProfile(slice, vocab),
+    ...(meta.grammarProfile && { grammarProfile: meta.grammarProfile }),
+  };
+}
+
+/**
+ * Derive schema `markerOverride` defaults for ONE language from the slice's
+ * role markers, given a domain-role → semantic-role mapping. Returns
+ * `{ domainRole: primaryMarker }` with entries only where the slice has a
+ * marker for the mapped semantic role.
+ *
+ * ```ts
+ * deriveRoleMarkers(jaSlice, { table: 'source', target: 'destination' });
+ * // → { table: 'から', target: 'に' }
+ * ```
+ *
+ * Explicitly authored `markerOverride` entries stay authoritative — when
+ * assembling a per-language marker map for a schema role, spread the explicit
+ * entries after the derived defaults.
+ */
+export function deriveRoleMarkers(
+  slice: GrammarProfileSlice,
+  roleMapping: Readonly<Record<string, string>>
+): Record<string, string> {
+  const derived: Record<string, string> = {};
+  for (const [domainRole, semanticRole] of Object.entries(roleMapping)) {
+    const marker = slice.roleMarkers?.[semanticRole];
+    if (marker?.primary) derived[domainRole] = marker.primary;
+  }
+  return derived;
+}