@lokascript/framework 4.7.0 → 5.0.0

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

@@ -1,29 +1,24 @@
 /**
- * `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.
+ * The core engine (domains rethink Phase 4.7), the only engine since 5.0. framework's SQL fixture
+ * reads, compiles and translates as the classic engine did (its readings and translations below
+ * were taken from the classic engine on 4.8), refuses what it does not read, and renders through
+ * its own patterns where no renderer is configured. A role with a word list reads only its words.
  */
 import { describe, expect, it, vi } from 'vitest';
 import { createMultilingualDSL, UnreadInputError, type DSLConfig } from './create-dsl';
+import { defineCommand, defineRole } from '../schema';
+import { BaseTokenizer, getDefaultExtractors } from '../index';
 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) };
-});
+// A pass-through spy: what shows a DSL was built on the core.
 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 core = createMultilingualDSL(sqlDSLConfig());
 
 const reading = (node: SemanticNode) =>
   [
@@ -34,23 +29,54 @@ const reading = (node: SemanticNode) =>
     ),
   ].join(' ');
 
-describe("createMultilingualDSL with engine: 'core'", () => {
+describe('createMultilingualDSL on the core engine', () => {
+  // [language, input, SQL, reading, translation] — the reading and translation the classic engine gave.
   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'],
+    [
+      'en',
+      testQueries.english.simple,
+      expectedSQL.simple,
+      'select columns=name source=users',
+      'seleccionar name de users',
+    ],
+    [
+      'en',
+      testQueries.english.withWhere,
+      expectedSQL.withWhere,
+      'select columns=name source=users condition=age > 18',
+      'seleccionar name de users donde age > 18',
+    ],
+    [
+      'es',
+      testQueries.spanish.simple,
+      'SELECT nombre FROM usuarios',
+      'select columns=nombre source=usuarios',
+      'select nombre from usuarios',
+    ],
+    [
+      'es',
+      testQueries.spanish.withWhere,
+      'SELECT nombre FROM usuarios WHERE edad > 18',
+      'select columns=nombre source=usuarios condition=edad > 18',
+      '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)(
+    'reads and compiles %s `%s` as the classic engine did',
+    (lang, input, sql, read) => {
+      expect(reading(core.parse(input, lang))).toBe(read);
+      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.each(queries)(
+    'translates %s `%s` as the classic engine did',
+    (lang, input, _sql, _read, translated) => {
+      const to = lang === 'en' ? 'es' : 'en';
+      expect(core.translate(input, lang, to)).toBe(translated);
+    }
+  );
 
   it('refuses input it does not read', () => {
     expect(() => core.parse('select name from users banana', 'en')).toThrow(UnreadInputError);
@@ -68,19 +94,82 @@ describe("createMultilingualDSL with engine: 'core'", () => {
   });
 
   it.each([
-    ['core', { engine: 'core' }],
-    ['classic', { engine: 'classic' }],
-    ['classic', {}],
-  ] as const)('builds on the %s engine with %o', (expected, option) => {
-    vi.mocked(generatePattern).mockClear();
+    ['no engine option', {}],
+    ["engine: 'core'", { engine: 'core' }],
+  ] as const)('builds on the core with %s', (_label, option) => {
     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');
+    expect(vi.mocked(createSchemaPatternGenerator).mock.calls.length).toBeGreaterThan(0);
   });
 
-  it('throws on an engine it does not know, rather than reading with the classic one', () => {
+  it("refuses engine: 'classic', removed in 5.0, and says what replaced it", () => {
+    const classic = { ...sqlDSLConfig(), engine: 'classic' } as unknown as DSLConfig;
+    expect(() => createMultilingualDSL(classic)).toThrow(/removed in @lokascript\/framework 5\.0/);
+  });
+
+  it('throws on an engine it does not know, rather than reading with the default', () => {
     const misspelled = { ...sqlDSLConfig(), engine: 'cor' } as unknown as DSLConfig;
     expect(() => createMultilingualDSL(misspelled)).toThrow('Unknown DSL engine "cor"');
   });
 });
+
+describe('a role with a word list, on the core', () => {
+  class WordTokenizer extends BaseTokenizer {
+    readonly language = 'en';
+    readonly direction = 'ltr' as const;
+    constructor() {
+      super();
+      this.registerExtractors(getDefaultExtractors());
+    }
+    classifyToken(token: string): 'keyword' | 'identifier' {
+      return token.toLowerCase() === 'when' ? 'keyword' : 'identifier';
+    }
+  }
+  // behaviorspec's `when [actor] action`: both are bare words.
+  const when = defineCommand({
+    action: 'when',
+    primaryRole: 'action',
+    roles: [
+      defineRole({ role: 'actor', required: false, expectedTypes: ['expression'], svoPosition: 2 }),
+      defineRole({
+        role: 'action',
+        required: true,
+        expectedTypes: ['expression'],
+        svoPosition: 1,
+        words: { '*': ['clicks', 'types'] },
+      }),
+    ],
+  });
+  const dsl = createMultilingualDSL({
+    name: 'when',
+    schemas: [when],
+    languages: [
+      {
+        code: 'en',
+        name: 'English',
+        nativeName: 'English',
+        tokenizer: new WordTokenizer(),
+        patternProfile: {
+          code: 'en',
+          wordOrder: 'SVO',
+          keywords: { when: { primary: 'when' } },
+          roleMarkers: {},
+        },
+      },
+    ],
+    engine: 'core',
+  });
+
+  it('reads a listed word, with or without the optional role before it', () => {
+    expect(reading(dsl.parse('when clicks', 'en'))).toBe('when action=clicks');
+    expect(reading(dsl.parse('when user clicks', 'en'))).toBe('when actor=user action=clicks');
+  });
+
+  it('refuses a word it does not list, rather than reading the listed word as the role before it', () => {
+    // Without the list: actor `clicks`, action `zzqx`.
+    expect(() => dsl.parse('when clicks zzqx', 'en')).toThrow(UnreadInputError);
+    // A listed word is not part of a longer value, so the refusal does not say to quote it.
+    expect(() => dsl.parse('when clicks zzqx', 'en')).toThrow(/leaving "zzqx" unread$/);
+    expect(() => dsl.parse('when user frobs', 'en')).toThrow();
+  });
+});

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

@@ -449,6 +449,13 @@ describe('MultilingualDSL: Explicit Syntax Support', () => {
       expect(refusal.message).toMatch(/leaving "banana" unread/);
     });
 
+    it('says when the bare word read last and the next may be one value, to be quoted', () => {
+      const dsl = createTestDSL();
+      expect(() => dsl.parse('select name from users banana', 'en')).toThrow(
+        /unread; if "users banana" is one value, quote it$/
+      );
+    });
+
     it('compile and validate report the refusal instead of compiling the shorter reading', () => {
       const dsl = createTestDSL();
       const compiled = dsl.compile('select name from users banana banana', 'en');

package/src/api/create-dsl.ts

@@ -4,6 +4,7 @@
 
 import type {
   SemanticNode,
+  LanguageToken,
   LanguageTokenizer,
   LanguagePattern,
   PatternMatchResult,
@@ -12,10 +13,9 @@ import type {
 } from '../core/types';
 import { extractRoleValue } from '../core/types';
 import type { CommandSchema } from '../schema';
-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 type { PatternGenLanguageProfile } from '../generation/profile';
+import type { DomainRenderFn } from '../generation/renderer';
 import {
   createSchemaPatternGenerator,
   type SchemaPatternProfile,
@@ -185,18 +185,17 @@ export interface DSLConfig {
   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
+   * What reads and writes the DSL. `'core'`, the only engine (and the
+   * default): 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.
+   * declines. The option stays so a config written for framework 4.7–4.8
+   * (`engine: 'core'`) builds unchanged; `'classic'`, framework's first
+   * generator and matcher, was removed in 5.0 (domains rethink Phase 6) and
+   * throws.
    */
-  readonly engine?: 'classic' | 'core';
+  readonly engine?: 'core';
 }
 
 /**
@@ -229,7 +228,9 @@ export interface CompileResult {
 /**
  * Thrown by `parse` (and so `compile`, `validate`, `translate`) when the input reads as a command
  * only by leaving some of it unread: `select name from users banana` is not `select name from users`.
- * `reading` is what the longest such match read, `unread` the text after it.
+ * `reading` is what the longest such match read, `unread` the text after it. `hint`, when there is
+ * one, says how the input might read: where a bare word read as a value is followed by another, the
+ * two may be one value written without quotes (todo `add buy milk to groceries`).
  */
 export class UnreadInputError extends Error {
   readonly code = 'unread-input';
@@ -238,9 +239,13 @@ export class UnreadInputError extends Error {
     readonly input: string,
     readonly language: string,
     readonly reading: SemanticNode,
-    readonly unread: string
+    readonly unread: string,
+    readonly hint?: string
   ) {
-    super(`"${input}" (${language}) reads as ${reading.action} only by leaving "${unread}" unread`);
+    super(
+      `"${input}" (${language}) reads as ${reading.action} only by leaving "${unread}" unread` +
+        (hint ? `; ${hint}` : '')
+    );
     this.name = 'UnreadInputError';
   }
 }
@@ -491,16 +496,37 @@ class MultilingualDSLImpl implements MultilingualDSL {
         .slice(longestPartial.consumedTokens)
         .map(t => t.value)
         .join(' ');
+      const hint = this.quoteHint(longestPartial, tokens.tokens);
       throw new UnreadInputError(
         input,
         language,
         this.nodeOf(longestPartial, input, language),
-        unread
+        unread,
+        ...(hint ? [hint] : [])
       );
     }
     throw new Error(`No pattern matched for input: ${input}`);
   }
 
+  /**
+   * `if "buy milk" is one value, quote it`, where the last token a match read is a bare word it took
+   * as a role's value (a role with no word list) and the first it left is a bare word too.
+   */
+  private quoteHint(
+    match: PatternMatchResult,
+    tokens: readonly LanguageToken[]
+  ): string | undefined {
+    const last = tokens[match.consumedTokens - 1];
+    const next = tokens[match.consumedTokens];
+    if (last?.kind !== 'identifier' || next?.kind !== 'identifier') return undefined;
+    const schema = this.schemaLookup.getSchema(match.pattern.command);
+    const role = [...match.captured].find(
+      ([, v]) => (v as { raw?: unknown }).raw === last.value
+    )?.[0];
+    if (!role || schema?.roles.find(r => r.role === role)?.words) return undefined;
+    return `if "${last.value} ${next.value}" is one value, quote it`;
+  }
+
   private nodeOf(match: PatternMatchResult, input: string, language: string): SemanticNode {
     return {
       kind: 'command',
@@ -860,10 +886,10 @@ export function createMultilingualDSL(config: DSLConfig): MultilingualDSL {
 // =============================================================================
 
 /**
- * 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.
+ * What reads and writes a DSL: 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 sit above it.
  */
 interface DSLEngine {
   generate(schema: CommandSchema, profile: PatternGenLanguageProfile): LanguagePattern;
@@ -872,29 +898,20 @@ interface DSLEngine {
 }
 
 /**
- * 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.
+ * The engine `config.engine` names: the core, the only one since 5.0. An
+ * unknown name throws rather than reading with the default, and `'classic'`
+ * says what replaced it.
  */
 function engineFor(config: DSLConfig): DSLEngine {
-  const name = config.engine ?? 'classic';
-  if (name === 'classic') return classicEngine();
+  const name: string = config.engine ?? 'core';
   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),
-      }),
-  };
+  if (name === 'classic') {
+    throw new Error(
+      'The "classic" DSL engine was removed in @lokascript/framework 5.0. ' +
+        'Omit `engine` (or pass "core"): every domain reads on the core.'
+    );
+  }
+  throw new Error(`Unknown DSL engine "${name}" (expected "core")`);
 }
 
 /**

package/src/core/index.ts

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

package/src/core/matching/index.ts

@@ -10,3 +10,5 @@ export type { ConfidenceBreakdown, ConfidenceContext, ConfidenceModel } from './
 export { StockValueReader, createStockReader, greedyStopMarkers, readGreedy } from './stock-reader';
 export { readRoleValue, type ReadingProfile } from './stock-reading';
 export { stockConfidenceModel } from './stock-confidence';
+export * from './type-validation';
+export * from './possessive-keywords';

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

@@ -1,8 +1,7 @@
 /**
- * The stock confidence model: how framework's old matcher scored a domain
- * pattern's match (`core/pattern-matching/`), moved here as a `ConfidenceModel`
- * for the matcher's skeleton (domains rethink Phase 4.7); the old matcher calls
- * it too until Phase 6.
+ * The stock confidence model: how framework's first matcher scored a domain
+ * pattern's match, moved here as a `ConfidenceModel` for the matcher's
+ * skeleton (domains rethink Phase 4.7).
  *
  * Role coverage (a required slot 1, an optional one 0.8, an absent optional one
  * with a default 60% of that), a stem-match penalty (up to 15%, floor 0.5), and

package/src/core/matching/stock-reader.test.ts

@@ -1,7 +1,7 @@
 /**
  * The stock value reader on the matcher's skeleton (domains rethink Phase 4.7):
- * each kind of value it reads, a greedy slot's stop markers, the guard against a
- * marker read as a value, and the skip of an optional slot.
+ * each kind of value it reads, a greedy slot's stop markers, a slot's word list,
+ * the guard against a marker read as a value, and the skip of an optional slot.
  */
 import { describe, expect, it } from 'vitest';
 import { MatchSkeleton } from './match-skeleton';
@@ -29,7 +29,7 @@ const lit = (value: string, ...alternatives: string[]): PatternToken =>
   alternatives.length ? { type: 'literal', value, alternatives } : { type: 'literal', value };
 const slot = (
   role: string,
-  extra: { optional?: boolean; greedy?: boolean; expectedTypes?: string[] } = {}
+  extra: { optional?: boolean; greedy?: boolean; expectedTypes?: string[]; words?: string[] } = {}
 ): PatternToken => ({ type: 'role', role, ...extra }) as PatternToken;
 const group = (...tokens: PatternToken[]): PatternToken => ({
   type: 'group',
@@ -129,6 +129,53 @@ describe('a greedy slot', () => {
   });
 });
 
+describe('a slot with a word list', () => {
+  const click = pattern([lit('when'), slot('action', { words: ['clicks', 'クリック'] })]);
+
+  it('reads one of its words, in any case, by value or normalized form', () => {
+    expect(read(click, ['when', 'keyword'], ['Clicks', 'identifier'])).toEqual({
+      action: { type: 'expression', raw: 'Clicks' },
+    });
+    expect(read(click, ['when', 'keyword'], ['クリックする', 'identifier', 'クリック'])).toEqual({
+      action: { type: 'expression', raw: 'クリックする' },
+    });
+  });
+
+  it('leaves any other word unread', () => {
+    expect(read(click, ['when', 'keyword'], ['zzqx', 'identifier'])).toBeNull();
+  });
+
+  it('gives the word to the required slot when the optional slot before it took it (behaviorspec `when clicks zzqx`)', () => {
+    const when = pattern([
+      lit('when'),
+      group(slot('actor', { optional: true })),
+      slot('action', { words: ['clicks'] }),
+    ]);
+    const result = matcher().matchPattern(
+      stream(['when', 'keyword'], ['clicks', 'identifier'], ['zzqx', 'identifier']),
+      when
+    );
+    expect(result && Object.fromEntries(result.captured)).toEqual({
+      action: { type: 'expression', raw: 'clicks' },
+    });
+    // `zzqx` is left for the caller to refuse as unread.
+    expect(result?.consumedTokens).toBe(2);
+  });
+
+  it('an optional one is skipped for a word it does not list (voice `close zzqx`)', () => {
+    const close = pattern([lit('close'), slot('patient', { optional: true, words: ['tab'] })]);
+    expect(read(close, ['close', 'keyword'], ['tab', 'identifier'])).toEqual({
+      patient: { type: 'expression', raw: 'tab' },
+    });
+    const result = matcher().matchPattern(
+      stream(['close', 'keyword'], ['zzqx', 'identifier']),
+      close
+    );
+    expect(result && Object.fromEntries(result.captured)).toEqual({});
+    expect(result?.consumedTokens).toBe(1);
+  });
+});
+
 describe('the marker guard and the optional skip', () => {
   it('a required slot does not read the marker the pattern wants next', () => {
     // SOV `{patient} を 実行` given `を 実行`: the patient is missing, not `を`.
@@ -136,6 +183,43 @@ describe('the marker guard and the optional skip', () => {
     expect(read(sov, ['を', 'particle'], ['実行', 'keyword'])).toBeNull();
   });
 
+  it('an optional slot does not read a marker the rest of the pattern owes, through its optional groups', () => {
+    // behaviorspec `when user types into #search`: the typed text is optional and has no marker.
+    const when = pattern([
+      lit('when'),
+      slot('action'),
+      group(slot('value', { optional: true })),
+      group(lit('on'), slot('target')),
+      group(lit('into'), slot('destination')),
+    ]);
+    expect(
+      read(
+        when,
+        ['when', 'keyword'],
+        ['types', 'identifier'],
+        ['into', 'keyword'],
+        ['#q', 'selector']
+      )
+    ).toEqual({
+      action: { type: 'expression', raw: 'types' },
+      destination: { type: 'selector', value: '#q' },
+    });
+    expect(
+      read(
+        when,
+        ['when', 'keyword'],
+        ['types', 'identifier'],
+        ["'hi'", 'literal'],
+        ['into', 'keyword'],
+        ['#q', 'selector']
+      )
+    ).toEqual({
+      action: { type: 'expression', raw: 'types' },
+      value: { type: 'literal', value: 'hi', dataType: 'string' },
+      destination: { type: 'selector', value: '#q' },
+    });
+  });
+
   it('an optional slot is skipped for the literal the pattern wants next, when the rest then reads to the end', () => {
     const p = pattern([lit('go'), group(slot('x', { optional: true })), lit('now')]);
     expect(read(p, ['go', 'keyword'], ['now', 'keyword'])).toEqual({});

package/src/core/matching/stock-reader.ts

@@ -7,13 +7,18 @@
  * - A **greedy** slot (`RoleSpec.greedy`: a SQL condition, a column list) reads
  *   every token up to the next marker the pattern still owes, or the end, as
  *   one expression (`readGreedy`).
+ * - A slot with a **word list** (`RoleSpec.words`: behaviorspec's interaction,
+ *   voice's thing to close) reads only one of its words, compared lower-cased
+ *   by value or normalized form; any other word leaves the slot unread.
  * - Any other slot reads one value (`readRoleValue`, the old matcher's reading):
  *   a selector, a quoted string, a number, a boolean, a duration, a URL, an
  *   identifier, or one of the multi-token forms it knows (`user.name`,
  *   `#dialog.showModal()`), checked against the slot's expected types.
  * - A **required** slot reads nothing where the stream is at the marker the
  *   pattern wants next (the old matcher's guard against an SOV marker taken as
- *   a value). Where a required slot finds nothing to read, and the optional,
+ *   a value). An **optional** one reads nothing at any marker the rest of the
+ *   pattern owes, through its optional groups (behaviorspec `when user types
+ *   into #search`, whose typed text is optional and has no marker). Where a required slot finds nothing to read, and the optional,
  *   marker-less slot just before it read a value with nothing read since, that
  *   value is given back and the required slot reads again (the old matcher's
  *   backtrack: behaviorspec `when clicks`, where the optional actor took
@@ -89,6 +94,13 @@ export function readGreedy(
 }
 
 /** The stock reader, for a matcher whose profiles it may consult (possessive words). */
+/** Whether `token` is one of a slot's `words`, by value or normalized form, lower-cased. */
+export function isListedWord(token: LanguageToken | null, words: readonly string[]): boolean {
+  if (!token) return false;
+  const forms = [token.value, token.normalized].filter((f): f is string => typeof f === 'string');
+  return forms.some(form => words.some(word => word.toLowerCase() === form.toLowerCase()));
+}
+
 export class StockValueReader implements ValueReader {
   private profile: ReadingProfile | undefined;
   /** The last optional, marker-less slot that read a value: what a failing required slot may take back. */
@@ -147,6 +159,13 @@ export class StockValueReader implements ValueReader {
       const token = tokens.peek();
       if (token && this.view.wouldMatch(next, token)) return false;
     }
+    if (slot.words && !isListedWord(tokens.peek(), slot.words)) return slot.optional ?? false;
+    // Nor does an optional slot read a marker the rest of the pattern owes, through its optional
+    // groups (`when user types into #search`: `into` is the destination's, not the typed text).
+    if (slot.optional && !slot.greedy) {
+      const token = tokens.peek();
+      if (token && isStopMarker(token, greedyStopMarkers(this.view.patternRest()))) return true;
+    }
     if (slot.greedy) {
       const value = readGreedy(tokens, greedyStopMarkers(this.view.patternRest()));
       if (value) {

package/src/core/matching/stock-reading.ts

@@ -1,8 +1,8 @@
 /**
- * Reading a domain value at a role slot: the value reading framework's old
- * matcher (`core/pattern-matching/`) did, moved here so the stock reader on the
- * matcher's skeleton (`stock-reader.ts`, domains rethink Phase 4.7) and the old
- * matcher run the same code until Phase 6 deletes the old one.
+ * Reading a domain value at a role slot: the value reading framework's first
+ * matcher did, moved here for the stock reader on the matcher's skeleton
+ * (`stock-reader.ts`, domains rethink Phase 4.7). The first matcher was
+ * deleted in 5.0 (Phase 6).
  *
  * In order: an English noise word before a selector (`the`), then the
  * multi-token forms (a possessive, `my value`; a method call,
@@ -22,8 +22,8 @@ import type {
   LanguageToken,
 } from '../types';
 import { createSelector, createLiteral, createReference, createPropertyPath } from '../types';
-import { isTypeCompatible } from '../pattern-matching/utils/type-validation';
-import { getPossessiveReference } from '../pattern-matching/utils/possessive-keywords';
+import { isTypeCompatible } from './type-validation';
+import { getPossessiveReference } from './possessive-keywords';
 
 /** What value reading needs of a language profile: its code, and its possessive words. */
 export interface ReadingProfile {

package/src/core/{pattern-matching/utils → matching}/type-validation.test.ts

@@ -1,7 +1,7 @@
 /**
  * Type Validation Tests
  *
- * Tests the type compatibility and validation utilities used by PatternMatcher.
+ * Tests the type compatibility and validation utilities the stock reader uses.
  */
 
 import { describe, it, expect } from 'vitest';
@@ -17,7 +17,7 @@ import {
   isVariableRef,
   isBuiltInReference,
 } from './type-validation';
-import type { SemanticValue } from '../../types';
+import type { SemanticValue } from '../types';
 
 describe('Type Validation', () => {
   describe('isTypeCompatible', () => {

package/src/core/{pattern-matching/utils → matching}/type-validation.ts

@@ -5,7 +5,7 @@
  * Used by pattern-matcher to validate captured role values.
  */
 
-import type { SemanticValue } from '../../types';
+import type { SemanticValue } from '../types';
 
 /**
  * Semantic value type strings.

package/src/core/types.ts

@@ -174,6 +174,11 @@ export interface RolePatternToken {
   readonly optional?: boolean;
   readonly expectedTypes?: Array<ExpectedType>;
   readonly greedy?: boolean;
+  /**
+   * The words the slot reads, from the schema's `RoleSpec.words` for the pattern's language (its
+   * `'*'` list and the language's own): the stock reader reads the slot only from one of them.
+   */
+  readonly words?: readonly string[];
   /**
    * Mirrors the schema's `RoleSpec.valueShape`: the slot's surface form is
    * unambiguous on its own. Carried onto the pattern token because the value

package/src/generation/domain-renderer.test.ts

@@ -12,7 +12,7 @@ import { createDomainRenderer, createSchemaRenderer } from './renderer';
 import type { SemanticNode } from '../core/types';
 import type { CommandSchema } from '../schema';
 import { defineCommand, defineRole } from '../schema';
-import type { PatternGenLanguageProfile } from './pattern-generator';
+import type { PatternGenLanguageProfile } from './profile';
 
 function makeNode(action: string, roles: Record<string, string>): SemanticNode {
   const rolesMap = new Map<string, { type: 'expression'; raw: string }>();