@sema-agent/core 7.47.0 → 7.49.0

package/dist/scenarios/full-body.d.ts

@@ -56,7 +56,7 @@ export interface CodeToolsConfig {
 }
 /**
  * Single-source bundle of the `code` scenario's `spec.tools`-class tools, so each deployment doesn't re-wire it
- * (the single-source discipline; mirrors the blessed `SCENARIO_REGISTRY` "data (named bundles)" precedent).
+ * (the single-source discipline: a scenario is data — a named bundle).
  * Profile-as-data — the engine iterates `spec.tools` branch-free; nothing keys off the scenario name. A trusted
  * assembler (service) calls this, sets `systemPrompt = CODE_SYSTEM_PROMPT` (or `role = CODE_ROLE`) +
  * `enablePlanMode:true`, and wires the deps seams (executionEnv/onQuestion/lspManager/skillSpecs/memoryStore/

package/dist/shell/lex.d.ts

@@ -1,24 +1,3 @@
-/**
- * The ONE shell lexer: one walk over a bash command mints a structure of words made of PIECES, and every other
- * spelling a reader consumes — `raw`, `folded`, the quoted spans, the expansion list, the assignment fact, the
- * reason a value cannot be read off the text — is a view of that structure. Dialect: bash (the execution
- * environment's last-resort `sh` reads `$'…'`, `+=`, a subscript, `<<<`, `<(…)` and `&>` differently; see
- * {@link bashOnlyConstructsOf}).
- *
- * ONE walk, ONE reading: every construct bash reads is RECORDED — a redirection, a substitution, an escape, a
- * comment, a line break, a backgrounding `&` — never refused here. Which of them a face refuses is that face's
- * predicate over the result (the classify faces' residual predicate in the read-only classifier); the lexer has
- * no modes. Bash's own word rules hold throughout: an unquoted word-start `#` begins a comment, and only a blank
- * (space or tab) bounds a word — a non-breaking space or a vertical tab is a word character.
- *
- * A command bash cannot parse is a {@link LexParseFailure}, never a guessed reading: an unterminated quote,
- * substitution, subscript or here-document yields NO segments. A word bash reads but whose VALUE the text does not
- * contain carries {@link LexedWord.unresolved}; the word is still delimited and its neighbours still read.
- *
- * Line continuations. Bash removes a `\<newline>` pair before it recognises anything — except inside single quotes,
- * a comment and a QUOTED here-document body. Every lookahead below reads the next LOGICAL character past any
- * continuation, so a pair can stand inside a construct's spelling and never inside the three places bash keeps it.
- */
 /** The dialect this lexer reads. The execution environment falls back to `sh` when no bash is found; a reader on
  *  that path must degrade every word carrying a {@link BashOnlyConstruct} to the conservative reading. */
 export declare const SHELL_LEX_DIALECT = "bash";

package/dist/shell/lex.js

@@ -1,3 +1,4 @@
+import { shellWordsOf } from "./shell-words.js";
 export const SHELL_LEX_DIALECT = "bash";
 export const QUOTE_KINDS = Object.freeze(["'", '"', "$'", '$"', "\\"]);
 export const EXPANSION_KINDS = Object.freeze(["parameter", "command", "process", "arithmetic", "tilde", "brace", "glob"]);
@@ -67,9 +68,14 @@ export const ANSI_C_ESCAPES = {
     "?": "?",
 };
 export const SUBSTITUTION_PLACEHOLDER = " subst";
-export const SHELL_CONTROL_PREFIXES = new Set(["!", "if", "then", "elif", "else", "while", "until", "do", "time"]);
+export const SHELL_CONTROL_PREFIXES = shellWordsOf("control_prefix");
 const COMPOUND_OPERAND_COMMANDS = new Set(["alias", "declare", "eval", "export", "let", "local", "readonly", "typeset"]);
-const GROUP_WORDS = new Set(["{", "}"]);
+const GROUP_WORDS = shellWordsOf("group");
+const DEFINITION_WORDS = shellWordsOf("definition");
+const BACKGROUND_WORDS = shellWordsOf("background");
+const COMPOUND_OPEN_WORDS = shellWordsOf("compound_open");
+const CASE_ARM_WORDS = shellWordsOf("case_arms");
+const TIMER_WORDS = shellWordsOf("timer");
 export function dollarOpensQuote(text, at) {
     const next = text[at + 1];
     if (next !== "'" && next !== '"')
@@ -134,19 +140,149 @@ function past(text, j) {
         k += 2;
     return k;
 }
-function parenBodyEnd(text, open) {
+function heredocHeaderOf(word, dash) {
+    if (word.folded === "" || /[$`]/.test(word.raw))
+        return undefined;
+    return { delimiter: word.folded, quoted: /["'\\]/.test(word.raw), dash };
+}
+function heredocBodies(text, from, headers, inSubstitution) {
+    const bodies = [];
+    let p = from;
+    for (const h of headers) {
+        const lines = [];
+        for (;;) {
+            if (p > text.length)
+                return "unterminated";
+            let nl = text.indexOf("\n", p);
+            let line = nl < 0 ? text.slice(p) : text.slice(p, nl);
+            if (!h.quoted) {
+                while (nl >= 0 && /(?<!\\)(?:\\\\)*\\$/.test(line)) {
+                    const after = text.indexOf("\n", nl + 1);
+                    line = line.slice(0, -1) + (after < 0 ? text.slice(nl + 1) : text.slice(nl + 1, after));
+                    nl = after;
+                }
+            }
+            const compared = h.dash ? line.replace(/^\t+/, "") : line;
+            if (compared === h.delimiter) {
+                p = nl < 0 ? text.length + 1 : nl + 1;
+                break;
+            }
+            if (inSubstitution && compared.startsWith(h.delimiter))
+                return "ambiguous";
+            if (nl < 0)
+                return "unterminated";
+            lines.push(line);
+            p = nl + 1;
+        }
+        bodies.push(lines.join("\n"));
+    }
+    return { bodies, resume: Math.min(p, text.length) };
+}
+function heredocHeaderAt(text, from, dash, op) {
+    let j = from;
+    while (text[j] === " " || text[j] === "\t" || (text[j] === "\\" && text[j + 1] === "\n"))
+        j += text[j] === "\\" ? 2 : 1;
+    const start = j;
+    let quote;
+    for (; j < text.length; j++) {
+        const c = text[j];
+        if (c === "$" || c === "`")
+            return fail("heredoc_delimiter_expands", start);
+        if (quote === "'") {
+            if (c === "'")
+                quote = undefined;
+            continue;
+        }
+        if (quote === '"') {
+            if (c === "\\")
+                j++;
+            else if (c === '"')
+                quote = undefined;
+            continue;
+        }
+        if (c === "\\") {
+            j++;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            continue;
+        }
+        if (/[ \t\n;&|()<>]/.test(c))
+            break;
+    }
+    if (quote !== undefined)
+        return "unterminated";
+    const raw = text.slice(start, Math.min(j, text.length));
+    if (raw === "" || raw.startsWith("#"))
+        return fail("heredoc_without_delimiter", op);
+    if (/[~[]/.test(raw))
+        return "undelimited";
+    const lexed = scan(raw, true);
+    const tokens = "command" in lexed && lexed.command.segments.length === 1 ? lexed.command.segments[0].tokens : [];
+    const word = tokens.length === 1 ? tokens[0] : undefined;
+    if (word?.kind !== "word")
+        return "undelimited";
+    const header = heredocHeaderOf(word, dash);
+    return header === undefined ? fail("heredoc_delimiter_expands", start) : { ...header, end: j };
+}
+const BASH_READING = { heredoc: true, startComment: true };
+const BASH32_READINGS = [{ heredoc: false, startComment: true }, { heredoc: false, startComment: false }];
+const BODY_NESTING_MAX = 64;
+function walkBody(text, open, reading, inDouble, level = 0) {
+    if (level > BODY_NESTING_MAX)
+        return "undelimited";
     let depth = 0;
     let quoted;
     let wordStart = true;
     let word = "";
+    let heredoc = false;
+    const owed = [];
+    const nested = (at, dq) => {
+        const inner = walkBody(text, at, reading, dq, level + 1);
+        if (typeof inner === "object" && "end" in inner) {
+            heredoc ||= inner.heredoc;
+            return inner.end - 1;
+        }
+        return inner;
+    };
     for (let j = open; j < text.length; j++) {
         const c = text[j];
-        if (quoted !== undefined) {
-            if (c === "\\" && quoted === '"')
+        if (quoted === "'") {
+            if (c === "'")
+                quoted = undefined;
+            continue;
+        }
+        if (quoted === '"') {
+            if (c === "\\") {
                 j++;
-            else if (c === quoted)
+                continue;
+            }
+            if (c === '"') {
                 quoted = undefined;
-            wordStart = false;
+                continue;
+            }
+            if (c === "`") {
+                const tick = backtickBody(text, j);
+                if (tick === undefined)
+                    return "unterminated";
+                j = tick.close;
+                continue;
+            }
+            const k = past(text, j + 1);
+            if (c === "$" && text[k] === "(") {
+                const r = nested(k, true);
+                if (typeof r !== "number")
+                    return r;
+                j = r;
+                continue;
+            }
+            if (c === "$" && text[k] === "{") {
+                const close = braceExpansionEnd(text, k);
+                if (close === undefined)
+                    return "unterminated";
+                j = close - 1;
+            }
             continue;
         }
         if (c === "\\") {
@@ -162,9 +298,8 @@ function parenBodyEnd(text, open) {
         if (c === "#" && wordStart) {
             const nl = text.indexOf("\n", j);
             if (nl < 0)
-                return undefined;
-            j = nl;
-            wordStart = true;
+                return "unterminated";
+            j = nl - 1;
             word = "";
             continue;
         }
@@ -174,34 +309,107 @@ function parenBodyEnd(text, open) {
             word = "";
             continue;
         }
-        if (c === "$" && text[past(text, j + 1)] === "{") {
-            const open2 = past(text, j + 1);
-            const close = braceExpansionEnd(text, open2);
+        const k = past(text, j + 1);
+        if (c === "$" && text[k] === "'") {
+            const close = ansiCQuoteClose(text, k);
             if (close === undefined)
-                return undefined;
-            if (UNREADABLE_EXPANSION_TEXT.test(text.slice(open2 + 1, close - 1)))
-                return "unreadable";
+                return "unterminated";
+            j = close;
+            wordStart = false;
+            word = "";
+            continue;
+        }
+        if (c === "`") {
+            const tick = backtickBody(text, j);
+            if (tick === undefined)
+                return "unterminated";
+            j = tick.close;
+            wordStart = false;
+            word = "`";
+            continue;
+        }
+        if (reading.heredoc && c === "<" && text[k] === "<") {
+            const third = past(text, k + 1);
+            if (text[third] === "<") {
+                j = third;
+                wordStart = false;
+                word = "";
+                continue;
+            }
+            const dash = text[third] === "-";
+            const header = heredocHeaderAt(text, dash ? third + 1 : third, dash, j);
+            if (typeof header !== "object" || !("delimiter" in header))
+                return header;
+            owed.push(header);
+            heredoc = true;
+            j = header.end - 1;
+            wordStart = false;
+            word = "";
+            continue;
+        }
+        if ((c === "$" || c === "<" || c === ">") && text[k] === "(") {
+            const r = nested(k, false);
+            if (typeof r !== "number")
+                return r;
+            j = r;
+            wordStart = false;
+            word = "$";
+            continue;
+        }
+        if (reading.heredoc && c === "$" && text[k] === "{") {
+            const close = braceExpansionEnd(text, k);
+            if (close === undefined)
+                return "unterminated";
+            if (UNREADABLE_EXPANSION_TEXT.test(text.slice(k + 1, close - 1)))
+                return "undelimited";
             j = close - 1;
             wordStart = false;
             word = "";
             continue;
         }
-        if (c === "<" && text[past(text, j + 1)] === "<" && text[past(text, past(text, j + 1) + 1)] !== "<")
-            return "unreadable";
+        if (c === "\n" && owed.length > 0) {
+            const read = heredocBodies(text, j + 1, owed, true);
+            if (read === "unterminated")
+                return fail("unterminated_heredoc", j + 1);
+            if (read === "ambiguous")
+                return "undelimited";
+            owed.length = 0;
+            j = read.resume - 1;
+            wordStart = true;
+            word = "";
+            continue;
+        }
         if (c === "(")
             depth++;
         else if (c === ")") {
             depth--;
             if (depth === 0)
-                return j + 1;
+                return owed.length > 0 ? "undelimited" : { end: j + 1, heredoc };
+        }
+        if (!reading.heredoc) {
+            wordStart = j === open ? reading.startComment && !inDouble && level === 0 : c === " " || c === "\t" || c === "\n";
+            continue;
         }
         const boundary = /[\s;|&()]/.test(c);
-        if (boundary && word === "case")
-            return "unreadable";
+        if (boundary && CASE_ARM_WORDS.has(word))
+            return "undelimited";
         word = boundary ? "" : word + c;
         wordStart = boundary;
     }
-    return undefined;
+    return "unterminated";
+}
+function substitutionBodyEnd(text, open, inDouble) {
+    const read = walkBody(text, open, BASH_READING, inDouble);
+    if (typeof read !== "object" || !("end" in read))
+        return read;
+    if (!read.heredoc)
+        return read.end;
+    for (const reading of BASH32_READINGS) {
+        const counted = walkBody(text, open, reading, inDouble);
+        if (counted !== "unterminated" && !(typeof counted === "object" && "end" in counted && counted.end === read.end))
+            return "undelimited";
+    }
+    return read.end;
 }
 function braceExpansionEnd(text, open) {
     let quoted;
@@ -310,7 +518,7 @@ export function substitutionsInHeredocBody(body) {
             continue;
         }
         if (ch === "$" && body[i + 1] === "(") {
-            const end = parenBodyEnd(body, i + 1);
+            const end = substitutionBodyEnd(body, i + 1, true);
             if (typeof end !== "number")
                 return undefined;
             out.push({ body: body.slice(i + 2, end - 1), kind: body[i + 2] === "(" ? "arithmetic" : "command" });
@@ -541,10 +749,24 @@ class WordBuilder {
             return at;
         };
         const unitCloses = new Map([":", "=", "."].map((d) => [d, unitClose(d)]));
+        const lettersEnd = new Array(nf + 1).fill(nf);
+        for (let f = nf - 1; f >= 0; f--) {
+            const lower = text.charCodeAt(f) | 0x20;
+            lettersEnd[f] = lower >= 0x61 && lower <= 0x7a && readableAt(f) ? lettersEnd[f + 1] : f;
+        }
+        const unitEndAt = (f) => {
+            if (!(readableAt(f) && text[f] === "[" && readableAt(f + 1)))
+                return -1;
+            const d = text[f + 1];
+            const end = unitCloses.get(d)?.[f + 2] ?? -1;
+            if (end < 0)
+                return -1;
+            return d === ":" ? (end > f + 2 && lettersEnd[f + 2] === end ? end : -1) : end === f + 3 ? end : -1;
+        };
         const nextBracketClose = new Array(nf + 2).fill(-1);
         const nextSlash = new Array(nf + 1).fill(nf);
         for (let f = nf - 1; f >= 0; f--) {
-            const unitEnd = readableAt(f) && text[f] === "[" && readableAt(f + 1) ? unitCloses.get(text[f + 1] ?? "")?.[f + 2] ?? -1 : -1;
+            const unitEnd = unitEndAt(f);
             nextBracketClose[f] = readableAt(f) && text[f] === "]" ? f : unitEnd >= 0 ? nextBracketClose[unitEnd + 2] : nextBracketClose[f + 1];
             nextSlash[f] = text[f] === "/" ? f : nextSlash[f + 1];
         }
@@ -584,7 +806,7 @@ class WordBuilder {
                 for (let m = k + 1; m < close && !widened; m++)
                     widened = this.rawQuoted[m] !== undefined;
                 for (let f = j; f < closeAt && !widened; f++)
-                    widened = readableAt(f) && text[f] === "[" && readableAt(f + 1) && (unitCloses.get(text[f + 1] ?? "")?.[f + 2] ?? -1) >= 0;
+                    widened = readableAt(f) && text[f] === "[" && readableAt(f + 1) && (text[f + 1] === ":" || text[f + 1] === "=" || text[f + 1] === ".");
                 const from = this.foldedOf(k);
                 const to = this.foldedOf(close + 1);
                 if (!expands && widened)
@@ -748,6 +970,7 @@ function scan(source, connectorsAreText) {
     let acceptable = true;
     let timeGrammar;
     let definitionName = false;
+    let coprocWord;
     let afterLeadingRedirect = false;
     let assignmentSeen = false;
     let subscriptsClosed = false;
@@ -761,7 +984,7 @@ function scan(source, connectorsAreText) {
         w.opaque(source.slice(from, to), SUBSTITUTION_PLACEHOLDER, by, from, to, { kind, yields: kind === "command" && by === undefined ? "many" : "one", body });
         current().substitutions.push(body);
     };
-    const resetPosition = () => { acceptable = true; commandWord = undefined; afterLeadingRedirect = false; assignmentSeen = false; subscriptsClosed = false; timeGrammar = undefined; definitionName = false; };
+    const resetPosition = () => { acceptable = true; commandWord = undefined; afterLeadingRedirect = false; assignmentSeen = false; subscriptsClosed = false; timeGrammar = undefined; definitionName = false; coprocWord = undefined; };
     const endWord = () => {
         if (!w.started)
             return undefined;
@@ -771,13 +994,13 @@ function scan(source, connectorsAreText) {
         const at = w.at;
         w = new WordBuilder();
         if (pendingHeredoc !== undefined) {
-            const header = pendingHeredoc;
+            const header = heredocHeaderOf(word, pendingHeredoc.dash);
             pendingHeredoc = undefined;
-            if (word.folded === "" || /[$`]/.test(word.raw))
+            if (header === undefined)
                 return fail("heredoc_delimiter_expands", at);
-            const token = { kind: "heredoc", delimiter: word.folded, quoted: /["'\\]/.test(word.raw), body: "" };
+            const token = { kind: "heredoc", delimiter: header.delimiter, quoted: header.quoted, body: "" };
             current().tokens.push(token);
-            pendingHeredocs.push({ delimiter: word.folded, quoted: token.quoted, dash: header.dash, token });
+            pendingHeredocs.push({ ...header, token });
             if (acceptable) {
                 if (assignmentSeen)
                     subscriptsClosed = true;
@@ -809,13 +1032,18 @@ function scan(source, connectorsAreText) {
             resetPosition();
             return undefined;
         }
-        if (acceptable && bare && word.folded === "function") {
+        if (acceptable && bare && DEFINITION_WORDS.has(word.folded)) {
             acceptable = false;
             definitionName = true;
             return undefined;
         }
         if (acceptable && bare && (SHELL_CONTROL_PREFIXES.has(word.folded) || GROUP_WORDS.has(word.folded))) {
-            timeGrammar = word.folded === "time" ? "opt" : undefined;
+            timeGrammar = TIMER_WORDS.has(word.folded) ? "opt" : undefined;
+            coprocWord = undefined;
+            return undefined;
+        }
+        if (acceptable && bare && BACKGROUND_WORDS.has(word.folded)) {
+            coprocWord = "head";
             return undefined;
         }
         if (acceptable && bare && timeGrammar === "opt" && word.folded === "-p") {
@@ -829,10 +1057,16 @@ function scan(source, connectorsAreText) {
         timeGrammar = undefined;
         if (word.assignment !== undefined && word.assignment.bare && acceptable) {
             assignmentSeen = true;
+            coprocWord = undefined;
             return undefined;
         }
-        if (acceptable)
+        if (acceptable && coprocWord !== "name")
             commandWord = bare ? word.folded : undefined;
+        if (coprocWord === "head" && !(bare && COMPOUND_OPEN_WORDS.has(word.folded))) {
+            coprocWord = "name";
+            return undefined;
+        }
+        coprocWord = undefined;
         acceptable = false;
         return undefined;
     };
@@ -847,34 +1081,12 @@ function scan(source, connectorsAreText) {
         return undefined;
     };
     const readHeredocBodies = (from) => {
-        let p = from;
-        for (const h of pendingHeredocs) {
-            const lines = [];
-            for (;;) {
-                if (p > source.length)
-                    return fail("unterminated_heredoc", from);
-                let nl = source.indexOf("\n", p);
-                let line = nl < 0 ? source.slice(p) : source.slice(p, nl);
-                if (!h.quoted) {
-                    while (nl >= 0 && /(?<!\\)(?:\\\\)*\\$/.test(line)) {
-                        const after = source.indexOf("\n", nl + 1);
-                        line = line.slice(0, -1) + (after < 0 ? source.slice(nl + 1) : source.slice(nl + 1, after));
-                        nl = after;
-                    }
-                }
-                if ((h.dash ? line.replace(/^\t+/, "") : line) === h.delimiter) {
-                    p = nl < 0 ? source.length + 1 : nl + 1;
-                    break;
-                }
-                if (nl < 0)
-                    return fail("unterminated_heredoc", from);
-                lines.push(line);
-                p = nl + 1;
-            }
-            h.token.body = lines.join("\n");
-        }
+        const read = heredocBodies(source, from, pendingHeredocs, false);
+        if (typeof read !== "object")
+            return fail("unterminated_heredoc", from);
+        pendingHeredocs.forEach((h, k) => { h.token.body = read.bodies[k]; });
         pendingHeredocs.length = 0;
-        return Math.min(p, source.length);
+        return read.resume;
     };
     for (let i = 0; i < source.length; i++) {
         if (!inSingle) {
@@ -1006,11 +1218,9 @@ function scan(source, connectorsAreText) {
         }
         if (ch === "$" && source[n1] === "(") {
             const arithmetic = source[next(n1)] === "(";
-            const end = parenBodyEnd(source, n1);
-            if (end === undefined)
-                return fail("unterminated_command_substitution", i);
-            if (end === "unreadable")
-                return fail("undelimited_substitution", i);
+            const end = substitutionBodyEnd(source, n1, inDouble);
+            if (typeof end !== "number")
+                return end === "unterminated" ? fail("unterminated_command_substitution", i) : end === "undelimited" ? fail("undelimited_substitution", i) : end;
             substitution(i, end, source.slice(n1 + 1, end - 1), arithmetic ? "arithmetic" : "command");
             i = end - 1;
             continue;
@@ -1042,11 +1252,9 @@ function scan(source, connectorsAreText) {
             continue;
         }
         if ((ch === "<" || ch === ">") && source[n1] === "(") {
-            const end = parenBodyEnd(source, n1);
-            if (end === undefined)
-                return fail("unterminated_process_substitution", i);
-            if (end === "unreadable")
-                return fail("undelimited_substitution", i);
+            const end = substitutionBodyEnd(source, n1, false);
+            if (typeof end !== "number")
+                return end === "unterminated" ? fail("unterminated_process_substitution", i) : end === "undelimited" ? fail("undelimited_substitution", i) : end;
             substitution(i, end, source.slice(n1 + 1, end - 1), "process");
             i = end - 1;
             continue;

package/dist/shell/shell-words.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The ONE table of the words bash's grammar owns — and the builtins that move the working directory — with the part each plays for a reader.
+ *
+ * "Which word is syntax" is one fact about bash. Every reader that acts on it — the lexer's position walk, the program
+ * model, the read plan, the binding walk, the tightening reader, the read-only classifier, the rule model — asks it of
+ * THIS table through {@link shellWordsOf} instead of keeping a set of its own. A role is one question a reader asks of
+ * a word; a word a reader must know is a row here carrying that role. Adding a keyword is one row.
+ *
+ * The table holds every SET of words. A reader that tests the spelling of ONE word on its own (the conditional's `[[`
+ * and `]]`, the `in` of a loop header, the `for NAME in …; do …; done` shape the poll classifier matches) holds no set
+ * and compares it. A test reads the source tree for a second set of the table's words, and for a chain of comparisons
+ * that spells one.
+ *
+ * Measured with `compgen -k`: bash 3.2.57 and 5.3 list the same 21 words, and 5.3 adds `coproc`. The structural roles
+ * `control_prefix`, `group` and `block` partition exactly those 22 (3.2 reads `coproc` as a command name; the
+ * position walk reads it as syntax all the same — the side that judges more). `((` and `))` are no reserved words:
+ * they are the arithmetic command's tokens, kept for the one role that refuses every word which cannot name a program.
+ *
+ * The table also owns the four builtins that carry the shell's WORKING DIRECTORY — `cd`, `pushd`, `popd`, `dirs` — because
+ * "which word moves where a command stands" is the same kind of fact (they are no reserved words, so the structural
+ * roles above do not touch them): the working-directory thread reads where a move leads, the rule model asks whether a
+ * segment moved the cursor, and the program model's stack rows derive from the same roles. A move word is a row here;
+ * none of those readers spells the set. (Which programs the read-only classifier admits is another fact — the reference's
+ * read-only command set — and is not a role of this table.)
+ *
+ * Pure data and a pure projection: this module imports nothing.
+ */
+export declare const SHELL_WORD_ROLES: readonly ["control_prefix", "group", "block", "compound_open", "loop_list_head", "loop_iterates", "loop_condition", "loop_end", "definition", "background", "case_arms", "timer", "scope_open", "scope_close", "scope_switch", "stripped_prefix", "stripped_standalone", "opaque", "rule_reserved", "base_mover", "stack_mover", "stack_editor"];
+export type ShellWordRole = (typeof SHELL_WORD_ROLES)[number];
+/** Every word that plays `role`. The same set object on every call: a projection is a view, not a copy to edit. */
+export declare function shellWordsOf(role: ShellWordRole): ReadonlySet<string>;
+/** The roles one word plays, in {@link SHELL_WORD_ROLES} order; empty for a word the table does not own. */
+export declare function shellWordRolesOf(word: string): readonly ShellWordRole[];
+/** Every word the table owns, in row order. */
+export declare function shellWordTable(): readonly string[];

package/dist/shell/shell-words.js

@@ -0,0 +1,65 @@
+export const SHELL_WORD_ROLES = Object.freeze([
+    "control_prefix",
+    "group",
+    "block",
+    "compound_open",
+    "loop_list_head",
+    "loop_iterates",
+    "loop_condition",
+    "loop_end",
+    "definition",
+    "background",
+    "case_arms",
+    "timer",
+    "scope_open",
+    "scope_close",
+    "scope_switch",
+    "stripped_prefix",
+    "stripped_standalone",
+    "opaque",
+    "rule_reserved",
+    "base_mover",
+    "stack_mover",
+    "stack_editor",
+]);
+const ROWS = [
+    ["!", "control_prefix", "stripped_prefix", "rule_reserved"],
+    ["if", "control_prefix", "compound_open", "scope_open", "stripped_prefix", "rule_reserved"],
+    ["then", "control_prefix", "stripped_prefix", "rule_reserved"],
+    ["elif", "control_prefix", "scope_switch", "stripped_prefix", "rule_reserved"],
+    ["else", "control_prefix", "scope_switch", "stripped_prefix", "rule_reserved"],
+    ["while", "control_prefix", "compound_open", "loop_condition", "scope_open", "stripped_prefix", "rule_reserved"],
+    ["until", "control_prefix", "compound_open", "loop_condition", "scope_open", "stripped_prefix", "rule_reserved"],
+    ["do", "control_prefix", "stripped_prefix", "rule_reserved"],
+    ["time", "control_prefix", "timer", "rule_reserved"],
+    ["{", "group", "compound_open", "scope_open", "stripped_standalone", "rule_reserved"],
+    ["}", "group", "scope_close", "stripped_standalone", "rule_reserved"],
+    ["for", "block", "compound_open", "loop_list_head", "loop_iterates", "scope_open", "opaque", "rule_reserved"],
+    ["select", "block", "compound_open", "loop_list_head", "scope_open", "opaque", "rule_reserved"],
+    ["case", "block", "compound_open", "case_arms", "scope_open", "opaque", "rule_reserved"],
+    ["esac", "block", "scope_close", "stripped_standalone", "rule_reserved"],
+    ["fi", "block", "scope_close", "stripped_standalone", "rule_reserved"],
+    ["done", "block", "loop_end", "scope_close", "stripped_standalone", "rule_reserved"],
+    ["function", "block", "definition", "opaque", "rule_reserved"],
+    ["coproc", "block", "background", "opaque", "rule_reserved"],
+    ["]]", "block", "stripped_standalone", "rule_reserved"],
+    ["in", "block", "opaque", "rule_reserved"],
+    ["[[", "block", "compound_open", "rule_reserved"],
+    ["((", "rule_reserved"],
+    ["))", "rule_reserved"],
+    ["cd", "base_mover"],
+    ["pushd", "base_mover", "stack_mover"],
+    ["popd", "base_mover", "stack_mover"],
+    ["dirs", "stack_editor"],
+];
+const PROJECTIONS = new Map(SHELL_WORD_ROLES.map((role) => [role, new Set(ROWS.filter(([, ...roles]) => roles.includes(role)).map(([word]) => word))]));
+export function shellWordsOf(role) {
+    return PROJECTIONS.get(role);
+}
+export function shellWordRolesOf(word) {
+    const row = ROWS.find(([w]) => w === word);
+    return row === undefined ? [] : SHELL_WORD_ROLES.filter((role) => row.includes(role));
+}
+export function shellWordTable() {
+    return ROWS.map(([word]) => word);
+}

package/dist/stores/file/checkpoint-store.d.ts

@@ -20,11 +20,11 @@ export declare class FileCheckpointStore implements CheckpointStore {
      *  directory's writer fence and refuses a second OS process by name (see the class header). Serving
      *  many writers at once remains Pg/TiDB's job — this refuses the second one, it does not coordinate it. */
     readonly durability: "durable";
-    /** Honest declaration on the fidelity axis: the ledger is JSONL, so what survives the restart this
-     *  backend promises is the JSON PROJECTION of the row — a `Date` replays as its ISO string, a
-     *  `Map`/`Set` as `{}`, `NaN` as `null`. The in-process map holds the structured clone, which is why
-     *  the loss is invisible until something reads the disk; the declaration is what makes it visible to
-     *  the mint BEFORE the row is filed. */
+    /** Honest declaration on the fidelity axis: the ledger is JSONL, so what this backend holds is the JSON
+     *  PROJECTION of the row — a `Date` reads as its ISO string, a `Map`/`Set` as `{}`, `NaN` as `null`, an
+     *  `undefined`-valued key not at all — before a restart and after it alike (the live map is filled from the
+     *  same JSON reading as the ledger line); the declaration is what makes the loss visible to the mint BEFORE the
+     *  row is filed. */
     readonly fidelity: "json";
     /** F-012 L2: `reopen` here is a real resolved→pending CAS journaled to the ledger — declared, not sniffed. */
     readonly redecision: {