@lokascript/framework 4.7.0 → 4.8.0

package/src/api/create-dsl.ts

@@ -4,6 +4,7 @@
 
 import type {
   SemanticNode,
+  LanguageToken,
   LanguageTokenizer,
   LanguagePattern,
   PatternMatchResult,
@@ -229,7 +230,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 +241,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 +498,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',

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/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/schema-patterns.test.ts

@@ -1,7 +1,7 @@
 /**
  * The schema-pattern generator semantic's hyperscript parser runs (domains
  * rethink Phase 4.4), on a schema of its own: the grammar's position order,
- * the variants, and a profile's optional markers.
+ * the variants, a profile's optional markers, and a role's word list.
  */
 import { describe, expect, it } from 'vitest';
 import { defineCommand, defineRole } from '../schema';
@@ -80,6 +80,46 @@ describe('createSchemaPatternGenerator', () => {
     ]);
   });
 
+  it("puts a role's word list for the pattern's language on its token, in every variant", () => {
+    const close = defineCommand({
+      action: 'send',
+      roles: [
+        defineRole({
+          role: 'patient',
+          required: true,
+          expectedTypes: ['expression'],
+          words: { '*': ['tab'], tr: ['sekme'] },
+        }),
+        defineRole({ role: 'destination', required: false, expectedTypes: ['selector'] }),
+      ],
+    });
+    const generator = createSchemaPatternGenerator({ positionOrder: 'ascending' });
+    const wordsOf = (tokens: readonly PatternToken[]): unknown[] =>
+      tokens.flatMap(t =>
+        t.type === 'role' ? [[t.role, t.words]] : t.type === 'group' ? wordsOf(t.tokens) : []
+      );
+    const at = (profile: SchemaPatternProfile) => {
+      const variants = generator.generatePatternVariants(close, profile, {
+        basePriority: 100,
+        generateSimpleVariants: true,
+      });
+      const roles = variants.flatMap(p => wordsOf(p.template.tokens)) as [string, unknown][];
+      return {
+        variants: variants.length,
+        patient: [
+          ...new Set(roles.filter(([r]) => r === 'patient').map(([, w]) => JSON.stringify(w))),
+        ],
+        destination: [
+          ...new Set(roles.filter(([r]) => r === 'destination').map(([, w]) => JSON.stringify(w))),
+        ],
+      };
+    };
+    expect(at(en)).toEqual({ variants: 2, patient: ['["tab"]'], destination: [undefined] });
+    expect(at(tr)).toEqual({ variants: 3, patient: ['["tab","sekme"]'], destination: [undefined] });
+    // No list, no field: the patterns of a grammar that lists no words are unchanged.
+    expect(JSON.stringify(generator.generatePattern(send, en))).not.toContain('words');
+  });
+
   it('drops variant-only roles', () => {
     const scroll = defineCommand({
       action: 'scroll',

package/src/generation/schema-patterns.ts

@@ -382,11 +382,13 @@ function generateVerbFirstPattern(
   // verb-first, which is exactly this shape (trailing particle tolerated).
   const roleTokens: PatternToken[] = requiredRoles.flatMap(r => {
     const prefix = r.valuePrefixLiteral?.[profile.code];
+    const words = wordsFor(r, profile.code);
     const roleToken: PatternToken = {
       type: 'role',
       role: r.role,
       optional: false,
       expectedTypes: r.expectedTypes,
+      ...(words ? { words } : {}),
     };
     return prefix ? [{ type: 'literal', value: prefix } as PatternToken, roleToken] : [roleToken];
   });
@@ -673,6 +675,13 @@ function buildRoleTokens(
  * use — a hand-rolled copy there is what let the two drift apart in the first
  * place (see `appendRemainingOptionalRoles` in event-handlers-sov.ts).
  */
+/** The words a role reads in `language` (`RoleSpec.words`: its `'*'` list and the language's own). */
+function wordsFor(roleSpec: RoleSpec, language: string): readonly string[] | undefined {
+  if (!roleSpec.words) return undefined;
+  const words = [...(roleSpec.words['*'] ?? []), ...(roleSpec.words[language] ?? [])];
+  return words.length > 0 ? words : undefined;
+}
+
 function buildRoleToken(roleSpec: RoleSpec, profile: SchemaPatternProfile): PatternToken[] {
   const tokens: PatternToken[] = [];
 
@@ -686,6 +695,7 @@ function buildRoleToken(roleSpec: RoleSpec, profile: SchemaPatternProfile): Patt
   // `fetch "/api"`). Tag the emitted marker literal so the renderer skips it;
   // the pattern matcher ignores the flag, so parsing is unchanged.
   const suppressMarker = roleSpec.renderOverride?.[profile.code] === '';
+  const words = wordsFor(roleSpec, profile.code);
 
   // Role value token
   const roleValueToken: PatternToken = {
@@ -700,6 +710,8 @@ function buildRoleToken(roleSpec: RoleSpec, profile: SchemaPatternProfile): Patt
     // A greedy role reads up to the next marker the pattern owes (a domain's
     // SQL condition); its value reader does the reading.
     ...(roleSpec.greedy ? { greedy: true } : {}),
+    // A role with a word list reads only one of its words.
+    ...(words ? { words } : {}),
   };
 
   // Required literal immediately before the role VALUE (rolePrefixLiteralVariants

package/src/testing/gate/round-trip.test.ts

@@ -1,14 +1,17 @@
 /**
  * The round-trip gate kit on framework's SQL fixture DSL: the commands it writes,
- * the outcomes it reads, and the baseline and snapshot it compares with.
+ * the outcomes it reads (an unknown word read into a role among them), and the
+ * baseline and snapshot it compares with.
  */
 import { describe, expect, it } from 'vitest';
-import { createSQLDSL, selectCommand } from '../../__test__/fixtures/sql-dsl';
+import { createSQLDSL, selectCommand, sqlDSLConfig } from '../../__test__/fixtures/sql-dsl';
+import { createMultilingualDSL } from '../../api/create-dsl';
 import {
   commandsFor,
   compare,
   countsOf,
   listingOf,
+  readsWord,
   runRoundTrip,
   snapshotChanges,
   snapshotOf,
@@ -42,11 +45,19 @@ describe('runRoundTrip', () => {
     ]);
   });
 
+  it("writes a fixture's own commands after the generated ones, once each", () => {
+    const own = '[select columns:email source:users condition:age]';
+    expect(
+      commandsFor([selectCommand], { ...fixture, commands: [own, '[select columns:id source:t]'] })
+    ).toEqual([...commandsFor([selectCommand], fixture), '[select columns:id source:t]']);
+    expect(commandsFor([selectCommand], fixture)).toContain(own);
+  });
+
   it('reads every render back, in every language, and tries each with an unknown word after it', () => {
     expect(countsOf(results)).toEqual({
       roundTrip: { cases: 8, pass: 8, refused: 0, silent: 0 },
-      // The `where` condition is greedy: it takes the unknown word as text (an open-text role).
-      leftover: { cases: 8, pass: 0, refused: 4, silent: 4 },
+      // The `where` condition is greedy: it takes the unknown word as text, into the SQL (`pass`).
+      leftover: { cases: 8, pass: 4, refused: 4, silent: 0 },
     });
     expect(results.find(r => r.kind === 'roundTrip' && r.lang === 'es')).toMatchObject({
       text: 'seleccionar name de users',
@@ -65,12 +76,14 @@ describe('compare', () => {
   });
 
   it('reports a case worse than listed, one better, and a listed case that is gone', () => {
+    // Two leftover cases accepted that the baseline lists as refused.
+    const accepted = '[select columns:name source:users]';
+    const now = results.map(r =>
+      r.kind === 'leftover' && r.source === accepted ? { ...r, outcome: 'silent' as const } : r
+    );
     const listing = listingOf(results);
-    const accepted = Object.keys(listing.leftover)[0]!;
-    const better = { ...listing.leftover };
-    delete better[accepted];
-    const drift = compare('sql', results, {
-      ...baselineOf({ roundTrip: listing.roundTrip, leftover: better }),
+    const drift = compare('sql', now, {
+      ...baselineOf(listing),
       roundTrip: {
         sql: {
           '[select columns:name source:users]': {
@@ -97,6 +110,83 @@ describe('compare', () => {
   });
 });
 
+describe('an unknown word read into a role', () => {
+  const leftover = (rs: typeof results) =>
+    rs
+      .filter(r => r.kind === 'leftover' && r.source.includes('condition'))
+      .map(r => [r.lang, r.outcome, r.why]);
+
+  it('is read (`pass`) where it extends an open-text role and reaches the code', () => {
+    expect(leftover(results)).toEqual([
+      ['en', 'pass', undefined],
+      ['es', 'pass', undefined],
+      ['en', 'pass', undefined],
+      ['es', 'pass', undefined],
+    ]);
+    expect(results.find(r => r.kind === 'leftover' && r.source.includes('condition'))?.read).toBe(
+      'select columns:expression=name condition:expression="age zzqx" source:expression=users'
+    );
+  });
+
+  it('is accepted (`silent`) where it does not reach the code', () => {
+    const dropsCondition = createMultilingualDSL({
+      ...sqlDSLConfig(),
+      codeGenerator: { generate: () => 'SELECT name FROM users' },
+    });
+    const rs = runRoundTrip('sql', dropsCondition, [selectCommand], fixture);
+    expect(leftover(rs)[0]).toEqual([
+      'en',
+      'silent',
+      'accepted as select; the word does not reach the code',
+    ]);
+  });
+
+  it('is refused where the input stops compiling, unless the command never compiles on its own', () => {
+    const refusesTheWord = createMultilingualDSL({
+      ...sqlDSLConfig(),
+      codeGenerator: {
+        generate: n => {
+          const c = n.roles.get('condition') as { raw?: string } | undefined;
+          if (c?.raw?.includes('zzqx')) throw new Error('not a condition');
+          return 'SELECT';
+        },
+      },
+    });
+    const rs = runRoundTrip('sql', refusesTheWord, [selectCommand], fixture);
+    expect(leftover(rs)[0]).toEqual(['en', 'refused', 'does not compile']);
+    const alone = runRoundTrip('sql', refusesTheWord, [selectCommand], {
+      ...fixture,
+      englishDoesNotCompile: ['select'],
+    });
+    expect(leftover(alone)[0]).toEqual(['en', 'pass', undefined]);
+  });
+
+  const node = (action: string, roles: Record<string, string>) => ({
+    action,
+    roles: new Map(Object.entries(roles).map(([k, v]) => [k, { type: 'expression', raw: v }])),
+  });
+
+  it.each([
+    ['extends one role', { condition: 'age' }, { condition: 'age zzqx' }, true],
+    ['fills a role the text left empty', {}, { list: 'zzqx' }, true],
+    [
+      'moves a value to make room for it (`when clicks zzqx`)',
+      { action: 'clicks' },
+      { actor: 'clicks', action: 'zzqx' },
+      false,
+    ],
+    ['replaces a value', { quantity: '2' }, { quantity: 'zzqx' }, false],
+    ['is in two roles', {}, { a: 'zzqx', b: 'zzqx' }, false],
+    ['is not read at all', { a: 'x' }, { a: 'x' }, false],
+  ] as const)('a parse that %s is the text read with the word: %s', (_, was, now, want) => {
+    expect(readsWord(node('when', was), node('when', now), 'zzqx')).toBe(want);
+  });
+
+  it('a parse as another command is not', () => {
+    expect(readsWord(node('when', {}), node('given', { a: 'zzqx' }), 'zzqx')).toBe(false);
+  });
+});
+
 describe('the parse snapshot', () => {
   it('shows a parse that moved', () => {
     const parses = snapshotOf(results);

package/src/testing/gate/round-trip.ts

@@ -13,8 +13,13 @@
  *   generator normalizes: bdd ja `#box0 が 表示 前提` is `visible`). English is a lane like the others.
  *   `refused` when the render is null or the parse throws: the caller is told. `silent` otherwise: it
  *   reads, or compiles to, something else.
- * - **leftover**: the same render plus one unknown word. `refused` is the expected outcome; a parse
- *   that returns accepted input it did not read (`silent`).
+ * - **leftover**: the same render plus one unknown word. `refused` is the expected outcome: the parse
+ *   throws, or the input does not compile. `pass` where the word is READ: the parse is the text's own
+ *   with the word in one role (an open-text role extended by it, `where active zzqx`, or a role the
+ *   text left empty, `list zzqx`), and the word is in the code (for a command that never compiles on
+ *   its own, `englishDoesNotCompile`, the parse alone). `silent` otherwise: the input is accepted and
+ *   read as something else (`when clicks zzqx`: actor `clicks`, action `zzqx`), or the word goes
+ *   nowhere (voice `back zzqx` compiles as `back`).
  *
  * The outcomes are the command-shape gate's (hyperfixi `testing-framework`). A baseline lists every
  * case that is not at its best outcome; `compare` reports a case worse than listed and one better than
@@ -93,7 +98,16 @@ export interface GateFixture {
   oracle: 'compile' | 'node';
   /** Keys are `<action>.<role>` or `<role>` (every action). The first value is the one the other cases use. */
   values: Record<string, string[]>;
-  /** Actions that do not compile on their own (a gate may check every other one does). */
+  /**
+   * Commands (bracket syntax) written besides the generated ones, where one role's value depends on
+   * another's and no single list fits both: behaviorspec's `[given subject:#box value:visible]` beside
+   * `[given subject:viewport value:1024x768]`.
+   */
+  commands?: string[];
+  /**
+   * Actions that do not compile on their own (a gate may check every other one does). Leftover input
+   * in such a command is judged by its parse alone.
+   */
   englishDoesNotCompile?: string[];
 }
 
@@ -132,6 +146,7 @@ export function commandsFor(schemas: readonly GateSchema[], fixture: GateFixture
       });
     }
   }
+  for (const command of fixture.commands ?? []) out.add(command);
   return [...out];
 }
 
@@ -181,6 +196,35 @@ function describeRead(want: Record<string, string>, ref: GateNode, back: GateNod
 
 const message = (e: unknown) => String((e as Error)?.message ?? e).slice(0, 160);
 
+/** What `text` compiles to, or `undefined` when it does not compile. */
+function codeOf(dsl: GateDSL, text: string, lang: string): string | undefined {
+  try {
+    const c = dsl.compile(text, lang);
+    return c.ok && typeof c.code === 'string' ? c.code : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether `read`, the parse of a text plus `word`, is `back`, the text's own parse, with the word read
+ * into it: the same action and roles, except one role, whose value is its value in `back` followed by
+ * the word (an open-text role at the end: sql `where active zzqx`) or, where `back` has no such role,
+ * the word itself (todo `list zzqx`).
+ */
+export function readsWord(back: GateNode, read: GateNode, word: string): boolean {
+  if (read.action !== back.action) return false;
+  const was = roleValues(back);
+  const now = roleValues(read);
+  let changed = 0;
+  for (const role of new Set([...Object.keys(was), ...Object.keys(now)])) {
+    if (was[role] === now[role]) continue;
+    if (now[role] !== (role in was ? `${was[role]} ${word}` : word)) return false;
+    changed++;
+  }
+  return changed === 1;
+}
+
 /** What a command (bracket syntax) compiles to; null when it does not compile on its own. */
 export function referenceCode(dsl: GateDSL, source: string): string | null {
   try {
@@ -253,18 +297,39 @@ export function runRoundTrip(
 
       // Leftover input: only where the text itself reads, or a refusal would say nothing.
       const extended = `${text} ${UNKNOWN_WORD}`;
+      let read: GateNode;
       try {
-        const read = dsl.parse(extended, lang);
-        results.push({
-          ...at,
-          kind: 'leftover',
-          outcome: 'silent',
-          text: extended,
-          why: `accepted as ${read.action}`,
-        });
+        read = dsl.parse(extended, lang);
       } catch {
         results.push({ ...at, kind: 'leftover', outcome: 'refused', text: extended });
+        continue;
       }
+      // Read with the word, the word must reach the code. Where the input does not compile, compile
+      // tells the caller (`refused`), except for a command that never compiles on its own (bdd's
+      // `and`), where only the parse can say.
+      const kept = readsWord(back, read, UNKNOWN_WORD);
+      const code = kept ? codeOf(dsl, extended, lang) : undefined;
+      const alone = fixture.englishDoesNotCompile?.includes(read.action) ?? false;
+      const [left, leftWhy]: [Outcome, string | undefined] = !kept
+        ? [
+            'silent',
+            `accepted as ${read.action}; reads ${describeRead(roleValues(back), back, read)}`,
+          ]
+        : code !== undefined
+          ? code.includes(UNKNOWN_WORD)
+            ? ['pass', undefined]
+            : ['silent', `accepted as ${read.action}; the word does not reach the code`]
+          : alone
+            ? ['pass', undefined]
+            : ['refused', 'does not compile'];
+      results.push({
+        ...at,
+        kind: 'leftover',
+        outcome: left,
+        text: extended,
+        ...(leftWhy ? { why: leftWhy } : {}),
+        read: summarize(read),
+      });
     }
   }
   return results;