@lokascript/framework 4.6.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokascript/framework",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Generic framework for building multilingual DSLs with semantic parsing and grammar transformation",
   "type": "module",
   "main": "dist/index.cjs",
@@ -56,6 +56,10 @@
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
     },
+    "./testing/gate": {
+      "types": "./dist/testing/gate/index.d.ts",
+      "import": "./dist/testing/gate/index.js"
+    },
     "./ir": {
       "types": "./dist/ir/index.d.ts",
       "import": "./dist/ir/index.js"
@@ -96,7 +100,7 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@lokascript/intent": "^4.6.0"
+    "@lokascript/intent": "^4.7.0"
   },
   "devDependencies": {
     "@lokascript/domains": "^4.0.0",

package/src/__test__/fixtures/sql-dsl.ts

@@ -13,6 +13,7 @@ import {
   getDefaultExtractors,
   type SemanticNode,
   type MultilingualDSL,
+  type DSLConfig,
 } from '../../index';
 
 // =============================================================================
@@ -168,7 +169,12 @@ function generateSQL(node: SemanticNode): string {
 // =============================================================================
 
 export function createSQLDSL(): MultilingualDSL {
-  return createMultilingualDSL({
+  return createMultilingualDSL(sqlDSLConfig());
+}
+
+/** The fixture's config, for a test that builds the DSL with another factory. */
+export function sqlDSLConfig(): DSLConfig {
+  return {
     name: 'SQL DSL Test Fixture',
     schemas: [selectCommand],
     languages: [
@@ -190,7 +196,7 @@ export function createSQLDSL(): MultilingualDSL {
     codeGenerator: {
       generate: generateSQL,
     },
-  });
+  };
 }
 
 // =============================================================================

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

@@ -0,0 +1,86 @@
+/**
+ * `engine: 'core'` (domains rethink Phase 4.7): the same config and DSL as the
+ * classic engine, read by the core. framework's SQL fixture reads, compiles and
+ * translates as it does on the classic engine, refuses what it does not read,
+ * and renders through its own patterns where no renderer is configured.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createMultilingualDSL, UnreadInputError, type DSLConfig } from './create-dsl';
+import { sqlDSLConfig, testQueries, expectedSQL } from '../__test__/fixtures/sql-dsl';
+import type { SemanticNode } from '../core/types';
+import { generatePattern } from '../generation/pattern-generator';
+import { createSchemaPatternGenerator } from '../generation/schema-patterns';
+
+// Pass-through spies. On the SQL fixture the two engines read, compile and render alike, so
+// these are what show which engine a DSL was built on.
+vi.mock('../generation/pattern-generator', async importOriginal => {
+  const actual = await importOriginal<typeof import('../generation/pattern-generator')>();
+  return { ...actual, generatePattern: vi.fn(actual.generatePattern) };
+});
+vi.mock('../generation/schema-patterns', async importOriginal => {
+  const actual = await importOriginal<typeof import('../generation/schema-patterns')>();
+  return { ...actual, createSchemaPatternGenerator: vi.fn(actual.createSchemaPatternGenerator) };
+});
+
+const core = createMultilingualDSL({ ...sqlDSLConfig(), engine: 'core' });
+const classic = createMultilingualDSL(sqlDSLConfig());
+
+const reading = (node: SemanticNode) =>
+  [
+    node.action,
+    ...[...node.roles].map(
+      ([role, v]) =>
+        `${role}=${String((v as { value?: unknown; raw?: unknown }).value ?? (v as { raw?: unknown }).raw)}`
+    ),
+  ].join(' ');
+
+describe("createMultilingualDSL with engine: 'core'", () => {
+  const queries = [
+    ['en', testQueries.english.simple, expectedSQL.simple],
+    ['en', testQueries.english.withWhere, expectedSQL.withWhere],
+    ['es', testQueries.spanish.simple, 'SELECT nombre FROM usuarios'],
+    ['es', testQueries.spanish.withWhere, 'SELECT nombre FROM usuarios WHERE edad > 18'],
+  ] as const;
+
+  it.each(queries)('reads and compiles %s `%s` as the classic engine does', (lang, input, sql) => {
+    expect(reading(core.parse(input, lang))).toBe(reading(classic.parse(input, lang)));
+    expect(core.compile(input, lang).code).toBe(sql);
+  });
+
+  it.each(queries)('translates %s `%s` as the classic engine does', (lang, input) => {
+    const to = lang === 'en' ? 'es' : 'en';
+    expect(core.translate(input, lang, to)).toBe(classic.translate(input, lang, to));
+  });
+
+  it('refuses input it does not read', () => {
+    expect(() => core.parse('select name from users banana', 'en')).toThrow(UnreadInputError);
+    expect(core.validate('select name from users banana', 'en')).toMatchObject({
+      valid: false,
+      errorCode: 'unread-input',
+    });
+  });
+
+  it('renders through its patterns, in each language, what it reads back', () => {
+    const node = core.parse(testQueries.english.withWhere, 'en');
+    expect(core.render?.(node, 'en')).toBe('select name from users where age > 18');
+    expect(core.render?.(node, 'es')).toBe('seleccionar name de users donde age > 18');
+    expect(reading(core.parse(core.render!(node, 'es')!, 'es'))).toBe(reading(node));
+  });
+
+  it.each([
+    ['core', { engine: 'core' }],
+    ['classic', { engine: 'classic' }],
+    ['classic', {}],
+  ] as const)('builds on the %s engine with %o', (expected, option) => {
+    vi.mocked(generatePattern).mockClear();
+    vi.mocked(createSchemaPatternGenerator).mockClear();
+    createMultilingualDSL({ ...sqlDSLConfig(), ...option }).parse(testQueries.english.simple, 'en');
+    expect(vi.mocked(createSchemaPatternGenerator).mock.calls.length > 0).toBe(expected === 'core');
+    expect(vi.mocked(generatePattern).mock.calls.length > 0).toBe(expected === 'classic');
+  });
+
+  it('throws on an engine it does not know, rather than reading with the classic one', () => {
+    const misspelled = { ...sqlDSLConfig(), engine: 'cor' } as unknown as DSLConfig;
+    expect(() => createMultilingualDSL(misspelled)).toThrow('Unknown DSL engine "cor"');
+  });
+});

package/src/api/create-dsl.ts

@@ -7,11 +7,20 @@ import type {
   LanguageTokenizer,
   LanguagePattern,
   PatternMatchResult,
+  RolePatternToken,
+  TokenStream,
 } from '../core/types';
+import { extractRoleValue } from '../core/types';
 import type { CommandSchema } from '../schema';
-import { PatternMatcher, type PatternMatcherProfile } from '../core/pattern-matching';
+import { PatternMatcher } from '../core/pattern-matching';
+import { MatchSkeleton, createStockReader, stockConfidenceModel } from '../core/matching';
 import { generatePattern, type PatternGenLanguageProfile } from '../generation/pattern-generator';
 import { createDomainRenderer, type DomainRenderFn } from '../generation/renderer';
+import {
+  createSchemaPatternGenerator,
+  type SchemaPatternProfile,
+} from '../generation/schema-patterns';
+import { renderPattern, selectRenderPattern } from '../generation/pattern-render';
 import { GrammarTransformer, type LanguageProfile as GrammarProfile } from '../grammar';
 import {
   type Dictionary,
@@ -174,6 +183,20 @@ export interface DSLConfig {
 
   /** Custom patterns to supplement generated ones */
   readonly customPatterns?: LanguagePattern[];
+
+  /**
+   * What reads and writes the DSL (domains rethink Phase 4.7). `'classic'`, the
+   * default: framework's first pattern generator, matcher and schema renderer.
+   * `'core'`: the core semantic's hyperscript parser runs — patterns from
+   * `createSchemaPatternGenerator` (positions descending, as a domain's schemas
+   * read), matched by `MatchSkeleton` with the stock reader and confidence
+   * model, and rendered through those patterns where the domain's own renderer
+   * declines. Parsing's whole-input rule, the refusals, translation's
+   * read-back, compile, explicit syntax and extensions are the same on both.
+   * The domains move to `'core'` one at a time against their gate (Phase 5);
+   * `'classic'` is removed in a later major, once no domain uses it.
+   */
+  readonly engine?: 'classic' | 'core';
 }
 
 /**
@@ -308,7 +331,11 @@ class DSLRegistry {
    *   subset of the DSL's languages. A built-in command missing a keyword stays
    *   an error, since that is a domain-authoring mistake.
    */
-  constructor(config: DSLConfig, partiallyTranslatedActions: ReadonlySet<string> = new Set()) {
+  constructor(
+    config: DSLConfig,
+    partiallyTranslatedActions: ReadonlySet<string>,
+    private readonly generate: DSLEngine['generate']
+  ) {
     this.schemas = config.schemas;
     this.partiallyTranslatedActions = partiallyTranslatedActions;
 
@@ -331,7 +358,7 @@ class DSLRegistry {
       ) {
         continue; // this extension command was not translated into this language
       }
-      const pattern = generatePattern(schema, lang.patternProfile);
+      const pattern = this.generate(schema, lang.patternProfile);
       patterns.push(pattern);
     }
 
@@ -356,7 +383,7 @@ class DSLRegistry {
  */
 class MultilingualDSLImpl implements MultilingualDSL {
   private registry: DSLRegistry;
-  private matcher: PatternMatcher;
+  private match: DSLEngine['match'];
   private transformer: GrammarTransformer;
   private profileProvider: ProfileProvider;
   private codeGenerator?: CodeGenerator;
@@ -369,10 +396,11 @@ class MultilingualDSLImpl implements MultilingualDSL {
     config: DSLConfig,
     registry: DSLRegistry,
     transformer: GrammarTransformer,
-    profileProvider: ProfileProvider
+    profileProvider: ProfileProvider,
+    engine: DSLEngine
   ) {
     this.registry = registry;
-    this.matcher = new PatternMatcher();
+    this.match = engine.match;
     this.transformer = transformer;
     this.profileProvider = profileProvider;
     if (config.codeGenerator) {
@@ -390,10 +418,7 @@ class MultilingualDSLImpl implements MultilingualDSL {
     // Last resort for render(): covers extension commands with no custom
     // renderer, and any built-in action the domain renderer declines. Lazy, so
     // a DSL that never renders pays nothing.
-    this.schemaFallbackRenderer = createDomainRenderer({
-      schemas: config.schemas,
-      profiles: config.languages.map(l => l.patternProfile),
-    });
+    this.schemaFallbackRenderer = engine.fallbackRenderer(config, registry);
 
     // Build SchemaLookup from config schemas for explicit syntax validation
     const schemaMap = new Map(config.schemas.map(s => [s.action, s]));
@@ -430,11 +455,6 @@ class MultilingualDSLImpl implements MultilingualDSL {
     // Get patterns for language
     const patterns = this.registry.getPatterns(language);
 
-    // Create profile for matcher
-    const profile: PatternMatcherProfile = {
-      code: language,
-    };
-
     // Every pattern is tried, and only a match that reads the WHOLE input counts; of those, the
     // highest priority wins, then the highest confidence, then the earliest pattern. The first match
     // used to win however much it read, so a trailing word was dropped without a word (the domain
@@ -445,7 +465,7 @@ class MultilingualDSLImpl implements MultilingualDSL {
     let longestPartial: PatternMatchResult | null = null;
     for (const pattern of patterns) {
       const mark = tokens.mark();
-      const match = this.matcher.matchPattern(tokens, pattern, profile);
+      const match = this.match(tokens, pattern, language);
       tokens.reset(mark);
       if (!match) continue;
       if (match.consumedTokens < total) {
@@ -830,6 +850,109 @@ export function createMultilingualDSL(config: DSLConfig): MultilingualDSL {
   });
 
   // Create registry and implementation
-  const registry = new DSLRegistry(effectiveConfig, extensionActions);
-  return new MultilingualDSLImpl(effectiveConfig, registry, transformer, profileProvider);
+  const engine = engineFor(config);
+  const registry = new DSLRegistry(effectiveConfig, extensionActions, engine.generate);
+  return new MultilingualDSLImpl(effectiveConfig, registry, transformer, profileProvider, engine);
+}
+
+// =============================================================================
+// The engines: how a DSL turns its schemas into patterns and reads with them
+// =============================================================================
+
+/**
+ * What differs between the engines {@link DSLConfig.engine} names: how each
+ * command's pattern is generated, how input is matched against it, and the
+ * renderer `render()` falls back to. Parsing's whole-input rule, refusals,
+ * translation's read-back, compile, explicit syntax and extensions are shared.
+ */
+interface DSLEngine {
+  generate(schema: CommandSchema, profile: PatternGenLanguageProfile): LanguagePattern;
+  match(tokens: TokenStream, pattern: LanguagePattern, language: string): PatternMatchResult | null;
+  fallbackRenderer(config: DSLConfig, registry: DSLRegistry): DomainRenderFn;
+}
+
+/**
+ * The engine `config.engine` names. An unknown name throws rather than reading
+ * with the default: a domain that misspells `'core'` would otherwise measure
+ * the classic engine against its gate and take the result for the core's.
+ */
+function engineFor(config: DSLConfig): DSLEngine {
+  const name = config.engine ?? 'classic';
+  if (name === 'classic') return classicEngine();
+  if (name === 'core') return coreEngine();
+  throw new Error(`Unknown DSL engine "${String(name)}" (expected "classic" or "core")`);
+}
+
+/** framework's first generator and matcher, and its schema renderer (`engine: 'classic'`). */
+function classicEngine(): DSLEngine {
+  const matcher = new PatternMatcher();
+  return {
+    generate: (schema, profile) => generatePattern(schema, profile),
+    match: (tokens, pattern, language) => matcher.matchPattern(tokens, pattern, { code: language }),
+    fallbackRenderer: config =>
+      createDomainRenderer({
+        schemas: config.schemas,
+        profiles: config.languages.map(l => l.patternProfile),
+      }),
+  };
+}
+
+/**
+ * A domain profile as the schema-pattern generator reads it: every role marker
+ * with a side (the word order's default where the profile names none).
+ */
+function schemaProfileOf(profile: PatternGenLanguageProfile): SchemaPatternProfile {
+  const side = profile.wordOrder === 'SOV' ? 'after' : 'before';
+  const roleMarkers: Record<string, NonNullable<SchemaPatternProfile['roleMarkers'][string]>> = {};
+  for (const [role, marker] of Object.entries(profile.roleMarkers ?? {})) {
+    roleMarkers[role] = {
+      primary: marker.primary,
+      ...(marker.alternatives ? { alternatives: marker.alternatives } : {}),
+      position: marker.position ?? side,
+    };
+  }
+  return {
+    code: profile.code,
+    wordOrder: profile.wordOrder,
+    keywords: profile.keywords,
+    roleMarkers,
+  };
+}
+
+/**
+ * The core (domains rethink Phase 4, `engine: 'core'`): the schema-pattern
+ * generator, the skeleton, the stock reader.
+ */
+function coreEngine(): DSLEngine {
+  const generator = createSchemaPatternGenerator({ positionOrder: 'descending' });
+  const matcher = new MatchSkeleton(createStockReader(), stockConfidenceModel);
+  return {
+    generate: (schema, profile) => generator.generatePattern(schema, schemaProfileOf(profile)),
+    match: (tokens, pattern) => matcher.matchPattern(tokens, pattern),
+    fallbackRenderer: (config, registry) => {
+      const schemas = new Map(config.schemas.map(s => [s.action, s]));
+      const hooks = {
+        hasRealRole: (node: SemanticNode, role: string) => {
+          const value = node.roles.get(role) as { implicit?: unknown } | undefined;
+          return value !== undefined && value.implicit !== true;
+        },
+        writeRole: (token: RolePatternToken, node: SemanticNode) => {
+          if (!node.roles.has(token.role)) return null;
+          let value = extractRoleValue(node, token.role);
+          const spec = schemas.get(node.action)?.roles.find(r => r.role === token.role);
+          if (spec?.quoteMultiword && /\s/.test(value) && !/^(["']).*\1$/.test(value)) {
+            value = `"${value}"`;
+          }
+          return value || null;
+        },
+      };
+      return (node, language) => {
+        const patterns = registry.getPatterns(language).filter(p => p.command === node.action);
+        const pattern = selectRenderPattern(node, patterns, hooks);
+        if (!pattern) return null;
+        const text = renderPattern(node, pattern, hooks).join(' ');
+        return text || null;
+      };
+    },
+  };
 }

package/src/api/index.ts

@@ -5,3 +5,4 @@
 export * from './create-dsl';
 export * from './domain-registry';
 export * from './dispatcher';
+export * from './translation-loss';

package/src/api/translation-loss.test.ts

@@ -0,0 +1,89 @@
+/**
+ * The translation-loss checks, with rules of a toy grammar: each check in its
+ * place in the order, and the error a refusing translation throws.
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  findTranslationLoss,
+  LossyTranslationError,
+  unconsumedSpans,
+  type TranslationLossRules,
+} from './translation-loss';
+
+interface Node {
+  readonly action: string;
+  readonly diagnostics?: ReadonlyArray<{ readonly code?: string; readonly message: string }>;
+}
+
+const unread = (text: string): Node => ({
+  action: 'go',
+  diagnostics: [{ code: 'unconsumed-input', message: `input not read: "${text}"` }],
+});
+
+const rules: TranslationLossRules<Node> = {
+  unwritable: node => (node.action === 'legacy' ? ['legacy'] : []),
+  differences: [(written, back) => (written.action === back.action ? [] : [`-${written.action}`])],
+  missingValues: (input, output) => (input.includes('#a') && !output.includes('#a') ? ['#a'] : []),
+};
+
+describe('findTranslationLoss', () => {
+  const ok: Node = { action: 'go' };
+
+  it('finds nothing in a translation that reads back with its values', () => {
+    expect(findTranslationLoss('go #a', ok, 've #a', () => ok, rules)).toBeUndefined();
+  });
+
+  it('checks in order: truncation, core-only, read-back, invariant', () => {
+    expect(findTranslationLoss('go #a x', unread('x'), '', () => ok, rules)).toEqual({
+      kind: 'truncation',
+      lost: ['x'],
+    });
+    expect(findTranslationLoss('x', { action: 'legacy' }, '', () => ok, rules)?.kind).toBe(
+      'core-only'
+    );
+    expect(
+      findTranslationLoss(
+        'go #a',
+        ok,
+        '?',
+        () => {
+          throw new Error('no pattern');
+        },
+        rules
+      )
+    ).toEqual({ kind: 'read-back', lost: ['the output does not read: no pattern'] });
+    expect(findTranslationLoss('go #a', ok, 've #a y', () => unread('y'), rules)).toEqual({
+      kind: 'read-back',
+      lost: ['y'],
+    });
+    expect(findTranslationLoss('go #a', ok, 'stop #a', () => ({ action: 'stop' }), rules)).toEqual({
+      kind: 'read-back',
+      lost: ['-go'],
+    });
+    expect(findTranslationLoss('go #a', ok, 've', () => ok, rules)).toEqual({
+      kind: 'invariant',
+      lost: ['#a'],
+    });
+  });
+
+  it('compares the read-back with what was written', () => {
+    const written: TranslationLossRules<Node> = { ...rules, written: () => ({ action: 'stop' }) };
+    expect(
+      findTranslationLoss('go #a', ok, 'stop #a', () => ({ action: 'stop' }), written)
+    ).toBeUndefined();
+  });
+});
+
+describe('unconsumedSpans and LossyTranslationError', () => {
+  it('reads the unread text out of the diagnostics', () => {
+    expect(unconsumedSpans(unread('banana'))).toEqual(['banana']);
+    expect(unconsumedSpans({ action: 'go' })).toEqual([]);
+  });
+
+  it('says what the translation loses', () => {
+    const error = new LossyTranslationError('ve', { kind: 'invariant', lost: ['#a'] }, 'en', 'es');
+    expect(error.name).toBe('LossyTranslationError');
+    expect(error.partial).toBe('ve');
+    expect(error.message).toBe('translation en → es would lose part of the script (invariant): #a');
+  });
+});

package/src/api/translation-loss.ts

@@ -0,0 +1,128 @@
+/**
+ * Fail-loud translation: what a translation checks before it returns (domains
+ * rethink Phase 4.5, `docs-internal/DOMAINS_RETHINK.md`). Moved from
+ * `@lokascript/semantic`'s `explicit/lossy.ts`, whose `translate` runs it with
+ * hyperscript's rules; `createMultilingualDSL`'s `translate` keeps its own
+ * read-back (`TranslationReadBackError`).
+ *
+ * A parse that matches a prefix of a script and leaves the rest unread used to
+ * come back from `translate()` as though it were the whole: `toggle .a .b`
+ * became `toggle .a`. A surface that cannot carry a script now says so: the
+ * translation throws a {@link LossyTranslationError}, which carries the output
+ * it would have returned and what it loses. Four checks, cheapest first:
+ *
+ *   - `truncation`  the parse of the input left input bound to no role (its
+ *                   `unconsumed-input` diagnostics);
+ *   - `core-only`   the input holds a form the grammar's writer has no spelling
+ *                   for (hyperscript: a form only `@hyperfixi/core` ran, which
+ *                   upstream reads with another meaning) — `rules.unwritable`;
+ *   - `read-back`   the output, read in the target language, does not read,
+ *                   leaves input unread, or differs from what was written
+ *                   (`rules.differences`, in order);
+ *   - `invariant`   a value the translation must write verbatim is missing
+ *                   from the output (`rules.missingValues`).
+ *
+ * None of them can say a translation is right. Each says one way it is wrong.
+ */
+
+export type TranslationLossKind = 'truncation' | 'core-only' | 'read-back' | 'invariant';
+
+/** One way a translation loses part of its input. */
+export interface TranslationLoss {
+  kind: TranslationLossKind;
+  /**
+   * What is lost: the input left unread (`truncation`); the forms nothing
+   * writes (`core-only`, as `swap <strategy>`); the output left unread or what
+   * it reads back without or with in excess (`read-back`, as `-cmd` / `+cmd`);
+   * or the verbatim values missing from the output (`invariant`).
+   */
+  lost: string[];
+}
+
+export class LossyTranslationError extends Error {
+  override readonly name = 'LossyTranslationError';
+
+  constructor(
+    /** The output `translate()` would have returned: NOT the whole script. */
+    readonly partial: string,
+    readonly loss: TranslationLoss,
+    readonly from: string,
+    readonly to: string
+  ) {
+    super(
+      `translation ${from} → ${to} would lose part of the script (${loss.kind}): ` +
+        loss.lost.join(', ')
+    );
+  }
+}
+
+/** What the checks read of a parse: its diagnostics. */
+export interface LossCheckedNode {
+  readonly diagnostics?: ReadonlyArray<{ readonly code?: string; readonly message: string }>;
+}
+
+/** The spans a parse left bound to no role (its top node carries them all). */
+export function unconsumedSpans(node: LossCheckedNode): string[] {
+  const out: string[] = [];
+  for (const d of node.diagnostics ?? []) {
+    if (d.code !== 'unconsumed-input') continue;
+    out.push(/"(.*)"\s*$/s.exec(d.message)?.[1] ?? d.message);
+  }
+  return out;
+}
+
+/** A grammar's rules for `findTranslationLoss`, for its node type `N`. */
+export interface TranslationLossRules<N extends LossCheckedNode> {
+  /** The forms in `node` the grammar's writer has no spelling for (`core-only`). */
+  unwritable?(node: N): string[];
+  /**
+   * `node` as it was written into the target language, to compare its
+   * read-back with (hyperscript: in upstream's spelling for English). Default:
+   * `node` itself.
+   */
+  written?(node: N): N;
+  /**
+   * How the read-back differs from what was written, checked in order: the
+   * first that finds a difference is the loss (hyperscript: commands, then
+   * roles, then clauses kept as written).
+   */
+  readonly differences: ReadonlyArray<(written: N, back: N) => string[]>;
+  /** The values `input` holds that `output` must write verbatim and does not (`invariant`). */
+  missingValues?(input: string, output: string): string[];
+}
+
+/**
+ * How a translation of `input` (parsed as `node`) into `output` loses part of
+ * it, or undefined. `readBack` parses the output in the target language; it
+ * throws when the output does not read.
+ */
+export function findTranslationLoss<N extends LossCheckedNode>(
+  input: string,
+  node: N,
+  output: string,
+  readBack: (output: string) => N,
+  rules: TranslationLossRules<N>
+): TranslationLoss | undefined {
+  const unread = unconsumedSpans(node);
+  if (unread.length) return { kind: 'truncation', lost: unread };
+  const unwritable = rules.unwritable?.(node) ?? [];
+  if (unwritable.length) return { kind: 'core-only', lost: unwritable };
+
+  let back: N;
+  try {
+    back = readBack(output);
+  } catch (e) {
+    return { kind: 'read-back', lost: [`the output does not read: ${(e as Error).message}`] };
+  }
+  const misread = unconsumedSpans(back);
+  if (misread.length) return { kind: 'read-back', lost: misread };
+  const written = rules.written ? rules.written(node) : node;
+  for (const difference of rules.differences) {
+    const lost = difference(written, back);
+    if (lost.length) return { kind: 'read-back', lost };
+  }
+
+  const values = rules.missingValues?.(input, output) ?? [];
+  if (values.length) return { kind: 'invariant', lost: values };
+  return undefined;
+}

package/src/core/index.ts

@@ -5,3 +5,4 @@
 export * from './types';
 export * from './tokenization';
 export * from './pattern-matching';
+export * from './matching';

package/src/core/matching/confidence-model.ts

@@ -0,0 +1,58 @@
+/**
+ * The matcher's confidence model: an injectable score for a pattern's match
+ * (domains rethink Phase 4.3). The interface moved here with the skeleton
+ * (`match-skeleton.ts`), which calls `calculate` once per matched pattern;
+ * hyperscript's model is `@lokascript/semantic`'s `DefaultConfidenceModel`.
+ */
+
+import type { LanguagePattern, SemanticRole, SemanticValue } from '../types';
+
+/**
+ * Context passed to confidence model methods.
+ */
+export interface ConfidenceContext {
+  /** The pattern being matched */
+  readonly pattern: LanguagePattern;
+  /** Captured semantic roles */
+  readonly captured: ReadonlyMap<SemanticRole, SemanticValue>;
+  /** Number of stem (morphological) keyword matches */
+  readonly stemMatchCount: number;
+  /** Total keyword matches attempted */
+  readonly totalKeywordMatches: number;
+}
+
+/**
+ * Breakdown of confidence scoring factors (for diagnostics/debugging).
+ */
+export interface ConfidenceBreakdown {
+  /** Role coverage score (0-1) */
+  readonly roleCoverage: number;
+  /** Stem match penalty applied (0 to -0.15) */
+  readonly stemPenalty: number;
+  /** Language-specific boost (e.g., VSO verb-first) */
+  readonly languageBoost: number;
+  /** Language-specific adjustment (e.g., preposition disambiguation) */
+  readonly languageAdjustment: number;
+  /** Final clamped confidence (0-1) */
+  readonly final: number;
+}
+
+/**
+ * Injectable confidence scoring model.
+ *
+ * Each method computes one factor of the confidence score.
+ * Override individual methods to customize scoring without rewriting the pipeline.
+ */
+export interface ConfidenceModel {
+  /**
+   * Calculate the full confidence score.
+   * Default implementation calls each factor method and combines them.
+   */
+  calculate(ctx: ConfidenceContext): number;
+
+  /**
+   * Calculate confidence with a detailed breakdown.
+   * Useful for diagnostics and debugging.
+   */
+  calculateWithBreakdown(ctx: ConfidenceContext): ConfidenceBreakdown;
+}

package/src/core/matching/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The pattern matcher's skeleton and its value-reader seam (domains rethink
+ * Phase 4.3): the matcher semantic's hyperscript parser runs, with
+ * hyperscript's reading behind `ValueReader`.
+ */
+
+export { MatchSkeleton } from './match-skeleton';
+export type { MatchView, RoleSlot, ValueReader } from './value-reader';
+export type { ConfidenceBreakdown, ConfidenceContext, ConfidenceModel } from './confidence-model';
+export { StockValueReader, createStockReader, greedyStopMarkers, readGreedy } from './stock-reader';
+export { readRoleValue, type ReadingProfile } from './stock-reading';
+export { stockConfidenceModel } from './stock-confidence';