@sema-agent/core 7.29.0 → 7.30.0

package/dist/tools/fs/bash-program-position.d.ts

@@ -8,27 +8,22 @@
  * readable, minted into one sentence by {@link programPositionRefusalSentence}. Reading less than this reader
  * does (an option skipped, a chain member missed) is how one face used to vouch for a program another refused.
  */
-import { SHELL_CONTROL_PREFIXES, type SegmentTokens } from "../../shell/lex.js";
+import { SHELL_CONTROL_PREFIXES, type LexedWord } from "../../shell/lex.js";
 /** The verdict every unresolvable / out-of-root / unbounded finding ends on. The findings differ in what
  *  they found; the consequence is one consequence, and a copy that drifts reads as a second rule. */
 export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
 /** argv[0] as the program bash will resolve it: `/usr/bin/cat` and `cat` are one name. */
 export declare function programBasename(word: string): string;
 /**
- * The `NAME=` / `NAME+=` prefix bash reads as an ASSIGNMENT — the ONE spelling of that grammar, matched where
- * it is WRITTEN. Both operators, because bash reads both; the match IS the prefix, so a caller holding raw
- * text can ask whether its token carries one bare. Every walk that strips leading assignments reads this:
- * a second copy of the grammar is how one walk came to strip `A=x` and skip `A+=x`.
+ * The `NAME=` / `NAME+=` prefix as WRITTEN in a whitespace-split token. This is NOT the position reader's grammar
+ * — the reader reads the lexer's {@link LexedWord.assignment} fact — but the two readers that still walk the
+ * command TEXT rather than its words (the unverifiable-delete policy and the activity summary) read it, and
+ * they read it here so that they read one spelling. It retires with them.
  */
 export declare const ASSIGNMENT_PREFIX: RegExp;
-/**
- * The prefix this raw token BEGINS with, or `undefined`.
- *
- * `name` is the VARIABLE the word assigns to, which is the part before any subscript: `A[0]=x` writes one
- * element of `A`, so a reader asking "is `$A` settled" must not be told that `A[0]` is. `settlesWholeName` is
- * false for exactly the two spellings that do not settle it — an append (the earlier content is not in the
- * text) and a subscript (the other elements are not) — so a consumer of that question asks it once.
- */
+/** The prefix a whitespace-split token BEGINS with, or `undefined` — the text readers' view of
+ *  {@link ASSIGNMENT_PREFIX}; `name` is the variable before any subscript, `settlesWholeName` false for an
+ *  append and for a subscript. */
 export declare function writtenAssignmentPrefix(token: string): {
     readonly prefix: string;
     readonly name: string;
@@ -40,18 +35,14 @@ export { SHELL_CONTROL_PREFIXES };
 export declare const SHELL_BLOCK_WORDS: ReadonlySet<string>;
 /** A control word is a keyword only when bash sees it BARE: `'if'` / `"do"` / `\\!` are command names (a program
  *  looked up on PATH, whose failure changes nothing), so a quoted or escaped spelling never counts as one. */
-export declare function isBareControlWord(toks: SegmentTokens, i: number, words: ReadonlySet<string>): boolean;
+export declare function isBareControlWord(words: readonly LexedWord[], i: number, set: ReadonlySet<string>): boolean;
 /**
- * A word bash strips as an ASSIGNMENT before it chooses the program.
- *
- * WHAT HAS TO BE BARE IS THE PREFIX, NOT THE WORD, and it is ONE question for BOTH operators. Bash decides this
- * before it removes any quoting, and only the NAME and the OPERATOR take part in it: quoting any of `NAME=` /
- * `NAME+=` makes the whole word a program name looked up on PATH (`'A=x'`, `'A+=x'`, `A\+=x`), while quoting the
- * VALUE does not (`A+=".env"` assigns `.env` exactly as `A+=.env` does — verified against the shell). A
- * whole-word test conflates the two and reads the quoted VALUE as a program name; a FOLDED-word test conflates
- * them the other way and reads the quoted PROGRAM NAME as an assignment, stepping over the real program.
+ * A word bash strips as an ASSIGNMENT before it chooses the program: the lexer's assignment fact, written BARE
+ * (the name, the brackets and the operator unquoted — a quoted VALUE still assigns, a quoted operator is a
+ * program name), read where bash accepts one (the lexer's own command-position state, which this reader's walk
+ * over control words and earlier assignments re-traces). One fact, two readers that must agree.
  */
-export declare function isLeadingAssignmentWord(toks: SegmentTokens, i: number): boolean;
+export declare function isLeadingAssignmentWord(words: readonly LexedWord[], i: number): boolean;
 /**
  * Programs that turn their STANDARD INPUT into the OPERANDS of another program, and EXEC that program directly.
  *
@@ -189,7 +180,7 @@ export interface ProgramPosition {
  * WRITTEN word (judged on its basename, as the program it names) refuses the same way: it is where the program
  * would be, and the word in front took an option no row explains.
  */
-export declare function readProgramPosition(toks: SegmentTokens): ProgramPosition;
+export declare function readProgramPosition(words: readonly LexedWord[]): ProgramPosition;
 /** Does this program position hand a program operands the walk cannot see? True when the chain re-enters through
  *  stdin AND the program it runs is not one the caller accepts as a stream target. ONE reading, shared by every
  *  consumer; WHICH targets are accepted is the caller's declaration, not this reader's. */

package/dist/tools/fs/bash-program-position.js

@@ -15,31 +15,13 @@ export function writtenAssignmentPrefix(token) {
 }
 export { SHELL_CONTROL_PREFIXES };
 export const SHELL_BLOCK_WORDS = new Set(["for", "select", "case", "esac", "fi", "done", "function", "coproc", "[[", "]]", "in"]);
-export function isBareControlWord(toks, i, words) {
-    const word = toks.folded[i];
-    return word !== undefined && toks.raw[i] === word && words.has(word);
+export function isBareControlWord(words, i, set) {
+    const w = words[i];
+    return w !== undefined && w.raw === w.folded && set.has(w.folded);
 }
-export function isLeadingAssignmentWord(toks, i) {
-    const word = toks.folded[i];
-    const raw = toks.raw[i];
-    if (word === undefined || raw === undefined)
-        return false;
-    const written = writtenAssignmentPrefix(word);
-    return written !== undefined && prefixWrittenBare(raw, written);
-}
-function prefixWrittenBare(raw, written) {
-    if (!raw.startsWith(written.name))
-        return false;
-    let at = written.name.length;
-    if (written.prefix[at] === "[") {
-        if (raw[at] !== "[")
-            return false;
-        const close = raw.indexOf("]", at);
-        if (close < 0)
-            return false;
-        at = close + 1;
-    }
-    return raw.startsWith(written.appends ? "+=" : "=", at);
+export function isLeadingAssignmentWord(words, i) {
+    const w = words[i];
+    return w !== undefined && w.assignment !== undefined && w.assignment.bare && w.atCommandPosition;
 }
 export const ARGV_REENTRY_PROGRAM_RE = /^xargs$/;
 export const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
@@ -63,7 +45,7 @@ export const LAUNCHER_TABLE = new Map([
         ], { requiredOperands: 1 })],
     ["time", {
             optionArity: new Map([
-                ["-p", 0], ["-a", 0], ["-v", 0], ["-q", 0], ["--portability", 0], ["--append", 0], ["--verbose", 0], ["--quiet", 0], ["--help", 0], ["--version", 0],
+                ["-p", 0], ["-a", 0], ["-v", 0], ["-q", 0], ["--portability", 0], ["--append", 0], ["--verbose", 0], ["--quiet", 0], ["--help", 0], ["--version", 0], ["--", 0],
                 ["-f", 1], ["-o", 1], ["--format", 1], ["--output", 1],
             ]),
         }],
@@ -108,11 +90,11 @@ function launcherOptionStep(row, tok) {
     return undefined;
 }
 export const PROGRAM_POSITION_REFUSAL_KINDS = ["option_at_program_position", "control_syntax_at_program_position"];
-export function readProgramPosition(toks) {
-    const { folded } = toks;
+export function readProgramPosition(words) {
+    const folded = words.map((w) => w.folded);
     const controlWords = [];
     let i = 0;
-    while (i < folded.length && isBareControlWord(toks, i, SHELL_CONTROL_PREFIXES)) {
+    while (i < folded.length && isBareControlWord(words, i, SHELL_CONTROL_PREFIXES)) {
         const controlWord = folded[i];
         controlWords.push(i);
         i = pastLauncherOptions(controlWord, folded, i + 1);
@@ -122,7 +104,7 @@ export function readProgramPosition(toks) {
         return none(undefined, []);
     const written = i;
     const assignments = [];
-    while (i < folded.length && isLeadingAssignmentWord(toks, i)) {
+    while (i < folded.length && isLeadingAssignmentWord(words, i)) {
         assignments.push(i);
         i++;
     }

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -1,4 +1,4 @@
-import { type SegmentTokens, type ShellSegmentConnector } from "../../shell/lex.js";
+import { type LexedSegment, type LexedWord, type ShellLex, type ShellSegmentConnector, type WordPiece } from "../../shell/lex.js";
 /**
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
  * The {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
@@ -75,16 +75,15 @@ export interface LeadingCommandNameOptions {
      * Read a shell operator that sits inside a QUOTED region as ordinary argument TEXT rather than as an
      * operator, so `grep -E "a|b" f.log` parses as the single simple command it is.
      *
-     * OPT-IN, and the two callers that set it share one premise: the whole command has ALREADY been refused
-     * for backslashes / an expanding `$` / backticks / subshells / line breaks, so they are inside
-     * {@link quoteMask}'s exactness envelope — the compound classify face
+     * OPT-IN, read off the one lexer's result: an operator character bash reads as text (inside quotes, or
+     * behind an escape) is text here. Two callers set it — the compound classify face
      * ({@link classifyCompoundReadonlyDetailed}) and the persisted permission-RULE lane (`RULE_LANE_FLOOR`),
-     * whose segments come out of that same gate ({@link splitShellCompoundSegments}). The `bash_readonly`
-     * DECLARATION face does NOT set it: its contract is "a single simple command with no operator characters
-     * at all", and it runs on raw tool input with no whole-string gate in front of it.
+     * whose segments come out of the same residual predicate ({@link splitShellCompoundSegments}). The
+     * `bash_readonly` DECLARATION face does NOT set it: its contract is "a single simple command with no
+     * operator characters at all", and it runs on raw tool input with no whole-string gate in front of it.
      *
-     * Fail-closed on unbalanced quoting: with a region left open, the mask is not trusted and every
-     * operator character counts, exactly as without this option.
+     * Fail-closed on a command the lexer cannot delimit: every operator character then counts, exactly as
+     * without this option.
      */
     quotedOperatorsAreText?: boolean;
     /**
@@ -146,10 +145,36 @@ export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<
  * Exported because the tolerating caller owes a PER-SEGMENT judgement in its place, and that judgement
  * must read the same character class this module tolerated — two hand-kept lists would drift, and a
  * drift here is a segment nobody judged. Says nothing about what a caller should DO about a hit: the
- * rule lane's offer face contributes no member for such a segment; the read-only classify face removes
- * its exempt spellings before splitting at all.
+ * rule lane's offer face contributes no member for such a segment; the read-only classify face passes
+ * only the two data-free spellings ({@link isDataFreeRedirection}).
  */
 export declare function carriesShellRedirection(text: string): boolean;
+/** What a caller asks the residual predicate to pass: see {@link strictResidualRefusal}. */
+export interface StrictResidualOptions {
+    /** `<`/`>` are not refused and a redirection is the segment's own business (the rule lane's offer reading). */
+    readonly tolerateRedirection?: boolean;
+    /** Only the two data-free spellings pass ({@link isDataFreeRedirection}); every other redirection refuses. */
+    readonly dataFreeRedirections?: boolean;
+    /** The declared home: a word that spells it ({@link homeExpansionOf}) is not an expansion to refuse — unless the
+     *  command may rebind `HOME` ({@link homeMayBeRebound}), which makes the declared home a guess. */
+    readonly homeDir?: string;
+}
+/**
+ * THE classify faces' whole-string gate, as a PREDICATE over the one lexer's result: the residual space those
+ * faces live in is what this function does not refuse. Four passes, in the order the gate's sentences were
+ * always minted, so a refused command is refused for the same stated reason:
+ *  1. the quote-blind class ({@link SHELL_SEGMENT_QUOTE_BLIND_REJECT}) over every written spelling — a word, a
+ *     redirection target under `tolerateRedirection` — plus every group, here-document, line-break connector
+ *     and (unless tolerated or data-free) redirection token;
+ *  2. the expansion character where bash expands it ({@link expandsDollar}), the home-directory word excepted
+ *     under `homeDeclared`;
+ *  3. a backgrounding `&` and a `|&`;
+ *  4. a word whose value the text does not settle ({@link UNRESOLVED_SENTENCE}) — a compound array, an
+ *     off-table ANSI-C escape, a subscript or parameter expansion this lexer does not read.
+ * A command the lexer cannot delimit is refused for the class if its text carries one (the reading the gate
+ * gave an unbalanced string), else for the parse failure. Returns the refusal REASON, or `undefined` to proceed.
+ */
+export declare function strictResidualRefusal(lexed: ShellLex, source: string, opts?: StrictResidualOptions): string | undefined;
 /** What {@link splitShellCompoundSegments} produces: the connector-delimited segments, plus which of
  *  them a PIPE fed (the read-only classifier's stdin arm needs that distinction; a rule lane does not). */
 export interface ShellCompoundSegments {
@@ -163,39 +188,28 @@ export interface ShellCompoundSegments {
      *  one this walk cannot verify. A consumer that does not read it gets the unverified reading, which is
      *  the fail-closed one. */
     connectors: ShellSegmentConnector[];
+    /** Parallel to {@link segments}: the segments as the lexer minted them — the words (with their facts) and
+     *  the redirections of each. A consumer that tokenizes reads these; the text is for the sentences. */
+    lexed: readonly LexedSegment[];
 }
 /**
  * Split a compound command into the segments bash would run, or refuse the whole string.
  *
- * THE one segmentation in this repository. Extracted from {@link classifyCompoundReadonlyDetailed}
- * (whose behaviour it reproduces exactly) when a SECOND face needed segments — the persisted
- * permission-rule lane, which must judge every segment of a compound against the deny/ask rules rather
- * than reading the whole string as one unmatched blob. The same argument that keeps ONE
- * {@link parseLeadingCommandName} applies with more force here: a second splitter would drift, and
- * drift in a segmentation is drift in what a deny rule is even looking at.
- *
- * Three steps, in this order and load-bearing:
- *  1. WHOLE-STRING hard reject ({@link hardRejectReason}) — redirection, substitution,
- *     subshells, escapes, line breaks. This is what makes step 3's quote mask EXACT: with those
- *     characters gone, `'`/`"` pairing is the entirety of quoting, so the mask's regions are exactly
- *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
- *     that tolerate a narrow redirection subset (the read-only classify face and its two data-free
- *     spellings) remove those words BEFORE calling; nothing here restores them. `redirection:
- *     "tolerate"` narrows this step to {@link rejectedSansRedirection} — the mask argument
- *     is untouched (`<`/`>` neither quote nor bound) and the refusal moves to the caller's per-segment
- *     vetting via {@link carriesShellRedirection}. The default refuses the whole string as it always did.
- *  2. one trailing `;` is stripped — a no-op terminator, not an empty command. OPTIONAL, because it is
- *     the one step whose answer depends on what the caller is asking. A face that asks "which programs
- *     does this run" wants it stripped (`ls;` runs `ls`, nothing else). A face that asks "is this ONE
- *     command" must NOT strip it: `"keep"` makes `ls;` two segments, the second empty, so the caller's
- *     own empty-command rule puts the whole string outside its lane — which is what keeps a statement
- *     like "this rule form never matches a command containing a connector" literally true instead of
- *     true-except-for-one-spelling.
- *  3. the quote-aware connector scan over `;` `&&` `||` `|` — the strict mode of the ONE lexer
- *     ({@link lexShellText}). A lone `&` is REFUSED rather than split on: it backgrounds a process that
- *     outlives the command, which is not a combinator any face here is willing to reason about.
- *     Unbalanced quoting falls back to the quote-blind scan — strictly MORE segments, each of which the
- *     caller must still vet, i.e. the fail-closed direction.
+ * THE one segmentation in this repository, and the one place the classify faces' residual predicate is
+ * applied: the persisted permission-rule lane and the read-only classify face both read their segments
+ * here, so a drift in what a deny rule is even looking at cannot open between them.
+ *
+ * Two steps: the trailing-terminator strip, then ONE lex ({@link lexShell}) judged by
+ * {@link strictResidualRefusal}. The strip is OPTIONAL because it is the one step whose answer depends on
+ * what the caller is asking. A face that asks "which programs does this run" wants it stripped (`ls;` runs
+ * `ls`, nothing else). A face that asks "is this ONE command" must NOT strip it: `"keep"` makes `ls;` two
+ * segments, the second empty, so the caller's own empty-command rule puts the whole string outside its lane
+ * — which is what keeps a statement like "this rule form never matches a command containing a connector"
+ * literally true instead of true-except-for-one-spelling. `redirection` picks which redirections the
+ * predicate passes: none (the default, the incumbent whole-string refusal), every one (`"tolerate"` — the
+ * refusal moves to the caller's per-segment vetting via {@link carriesShellRedirection}), or the two
+ * data-free spellings (`"data-free"`, the read-only classify face). `homeDir` lets the word spelling the
+ * declared home through the expansion refusal.
  *
  * Empty segments are NOT refused here (`;;`, a leading `;`, a trailing `&&`) — they come back as empty
  * strings, and every caller's per-segment vetting rejects them through its own empty-command rule. The
@@ -203,7 +217,8 @@ export interface ShellCompoundSegments {
  */
 export declare function splitShellCompoundSegments(source: string, options?: {
     trailingTerminator?: "strip" | "keep";
-    redirection?: "reject" | "tolerate";
+    redirection?: "reject" | "tolerate" | "data-free";
+    homeDir?: string;
 }): ShellCompoundSegments | {
     reject: string;
 };
@@ -213,7 +228,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
  * {@link coarseReadonlyCheck} (the single {@link parseLeadingCommandName} parser + bare-name allowlist).
  * All segments green ⇒ read-only. Returns a reason when rejected, else undefined.
  *
- * G2 — the split CARRIES QUOTE STATE ({@link quoteMask}): a connector character inside a quoted region is
+ * G2 — the split CARRIES QUOTE STATE (the one lexer): a connector character inside a quoted region is
  * argument text, not a boundary, so `grep -E "error:|BUILD FAILED" x.log | tail -10` is two segments
  * (`grep …` and `tail -10`) rather than four, and the phantom head `BUILD` no longer decides the verdict.
  * The whole compound face is what this fixes: a report of an every-command approval prompt on a read-only
@@ -221,8 +236,8 @@ export declare function splitShellCompoundSegments(source: string, options?: {
  * ordinary spelling of that idiom.
  *
  * Soundness — why the quote-aware split is NOT a relaxation. Backslash/`$`/backtick/subshells/redirection/
- * line breaks are whole-string rejected first (the two neutral forms in {@link EXEMPT_REDIRECTION} are
- * removed beforehand, and they move no data into any file), so in the residual space `'`/`"` pairing is
+ * line breaks are refused first (the two data-free forms of {@link isDataFreeRedirection} pass, and they
+ * move no data into any file), so in the residual space `'`/`"` pairing is
  * the ENTIRETY of quoting and the mask's regions are exactly bash's quoted regions. The unquoted connectors it splits on are therefore exactly bash's command boundaries:
  * every program bash runs still starts at the head of some segment this classifier vetted, and its argv[0]
  * is the head token (a token carrying a quote/brace/glob/tilde character is rejected by the parser's
@@ -231,14 +246,13 @@ export declare function splitShellCompoundSegments(source: string, options?: {
  * program was ever going to run — are gone. Those could only ever ADD a rejection, so removing them
  * removes false demotions and admits no additional program.
  *
- * UNBALANCED QUOTING falls back to the quote-blind scan (fail-closed). A string with an unterminated quote
- * is one bash cannot parse into commands at all, so there is no "true" segmentation to be accurate about;
- * the blind scan yields strictly MORE segments, each of which must still pass the allowlist.
+ * UNBALANCED QUOTING is a parse failure, refused whole (fail-closed). A string with an unterminated quote
+ * is one bash cannot parse into commands at all, so there is no "true" segmentation to be accurate about.
  *
  * A LONE `&` is hard-rejected (not a connector): it backgrounds a process that survives the shell — the node
  * execution env spools stdio and deliberately leaves descendants alive on completion — escaping TaskStop and
  * background-lifecycle governance entirely. Backgrounding is not a read-only combinator, even for a listed
- * reader (`tail -f x &` outlives the call). `|&` falls out of the same scan (its `&` reads as lone → reject).
+ * reader (`tail -f x &` outlives the call). `|&` is refused by name.
  * One TRAILING `;` is stripped (a no-op terminator); any other empty segment (`;;`, leading `;`, trailing
  * `&&`/`|`) rejects via the parser's empty-command rule.
  *
@@ -269,7 +283,7 @@ export interface BashReadonlyRootBoundary {
      *  should pass the LIVE working directory, or a `..` operand will be judged against the wrong base. */
     cwd?: string;
     /** Expansion for a leading `~` — and the value the read faces substitute for the `$HOME` / `${HOME}` word
-     *  spellings before segmenting ({@link foldHomeVariableSpelling}). Without it a `~`-rooted operand is unresolvable
+     *  spellings ({@link homeExpansionOf}). Without it a `~`-rooted operand is unresolvable
      *  and demotes (with no out-of-root signal — the classifier does not know where it points, which is a
      *  different verdict from knowing it points outside). */
     homeDir?: string;
@@ -400,39 +414,29 @@ export declare function resolveOperandSpellings(base: string | undefined, operan
  *  for the reason it is not a launcher: it hands a BUILT command line to a shell. */
 export declare const SHELL_REENTRY_PROGRAM_RE: RegExp;
 /**
- * Does this RAW token carry a metacharacter the shell EXPANDS, unquoted?
- *
- * The boundary scan below judges the token text as if it were the argv word the program receives. Quote
- * removal (folded above) is the only rewriting step it models — but brace expansion runs BEFORE tilde
- * expansion and before the word ever reaches the program, so `cat {<abs>,}` hands the program an absolute
- * path this scan never saw, and `ls {~,}` hands it a home directory the `~` arm of
- * {@link resolveOperandLexically} never got the chance to refuse. Both were real out-of-root reads.
- *
- * Rather than emulate expansion (the classifier resolves paths lexically and has no filesystem, so it
- * cannot know what a brace list or a glob expands TO), an operand carrying one of these unquoted is
- * declared unresolvable — the same verdict `~user` already gets, and the same direction the whole file
- * errs in. Quoting is honoured exactly as bash does it: nothing expands inside single quotes, while `$`
- * and a backtick still expand inside double quotes (braces do not).
- *
- * Deliberately NOT in the set: the GLOB characters `* ? [ ]`. A glob expands only to names that already
- * exist in the directory the pattern itself names, and a path component can never match a `/` — so a glob
- * cannot manufacture a traversal that is not already textually present (`cat ../*` still carries `../`
- * and is judged on it), while listing them would demote the everyday `ls *.txt`. `$`, backtick and the
- * parentheses are redundant against a compliant caller (both faces reject them upstream, whole-string;
- * a home-directory variable word never arrives as `$` — {@link foldHomeVariableSpelling} substituted the
- * declared value before segmentation) and are kept here only so this scan is self-standing.
+ * Does the shell REWRITE this word before the program sees it — a brace list, a parameter, command, process or
+ * arithmetic expansion, or a `$` / backtick / brace character where bash reads it (unquoted; `$` and a backtick
+ * also inside double quotes)? Read off the lexer's pieces. Brace expansion runs BEFORE tilde expansion and
+ * before the word ever reaches the program, so `cat {<abs>,}` hands the program an absolute path no spelling
+ * shows, and `ls {~,}` a home directory the `~` arm of {@link resolveOperandLexically} never got to refuse —
+ * both were real out-of-root reads. Rather than emulate expansion (the classifier resolves paths lexically and
+ * has no filesystem), such a word is declared unresolvable — the direction the whole file errs in.
+ *
+ * Deliberately NOT here: the GLOB characters ({@link globInWord}) — a glob only ever names entries of a
+ * directory that is already on the command line — and a tilde, which the resolver reads.
  */
-export declare function hasUnquotedExpansionMetachar(rawToken: string): boolean;
+export declare function expansionInWord(w: {
+    readonly pieces: readonly WordPiece[];
+}): boolean;
 /**
- * The same quote walk for PATHNAME expansion (`*`, `?`, `[`). Split from
- * {@link hasUnquotedExpansionMetachar} because the two have different consequences, not different
- * detection: a brace/variable/command expansion can produce ANY word (including a fresh absolute path or
- * an extra operand), so it is unresolvable; a glob only ever names entries of a directory that is already
- * on the command line, so a caller holding a filesystem can decide it — see
- * {@link CompoundReadonlyVerdict.undecidedPaths}. Both quoting forms suppress globbing in bash, so unlike
- * the expansion walk there is no `"`-open arm here.
+ * Does this word carry PATHNAME expansion (`*`, `?`, `[`), unquoted? Split from {@link expansionInWord} because
+ * the two have different consequences, not different detection: a brace/variable/command expansion can produce
+ * ANY word, so it is unresolvable; a glob only ever names entries of a directory that is already on the command
+ * line, so a caller holding a filesystem can decide it. Both quoting forms suppress globbing in bash.
  */
-export declare function hasUnquotedGlobMetachar(rawToken: string): boolean;
+export declare function globInWord(w: {
+    readonly pieces: readonly WordPiece[];
+}): boolean;
 /**
  * Does this token supply the verb's FIRST-OPERAND slot, so that the first operand is a FILE rather than the
  * slot ({@link VerbOptionSlots.firstOperand})? One reader, every verb with such a row.
@@ -811,15 +815,6 @@ export declare function inlineProgramClause(model: InlineProgramModel, args: rea
  *  command name. Names-only traversals (`find`, `ls -R`, `du`, `tree`, an archive write) are in the table
  *  and answer `false` here — see {@link RecursiveReadFormModel.discloses}. */
 export declare function segmentSelectsRecursiveRead(name: string, args: readonly string[]): boolean;
-/** `raw` is the word as WRITTEN; it defaults to the folded spelling, which is the reading that expands most. */
-export declare function assignmentWordPayload(word: string, raw?: string): {
-    kind: "value";
-    value: string;
-} | {
-    kind: "unresolved";
-    reason: string;
-    value?: string;
-} | undefined;
 /** WHICH programs are DECLARED not to open the value of a `NAME=value` ARGUMENT — an allow-list, because
  *  the other polarity was measured false. `make PREFIX=/usr/local`, `cmake -D…`, `docker run -e HOME=/root`
  *  name a build prefix and an environment value their program never opens, and judging those was the one
@@ -839,31 +834,48 @@ export declare const ASSIGNMENT_VALUE_NOT_PATHS: ReadonlySet<string>;
  *  disagree. The LEADING assignments (both spellings) are the program-position reader's own step, so this
  *  seat no longer strips them a second time: a second strip read the quoted `'A+=x'` as an assignment the
  *  one reader calls a program name, which is two readers with two answers. */
-export declare function argvProgramOf(tokens: SegmentTokens): {
+export declare function argvProgramOf(words: readonly LexedWord[]): {
     program: string;
     from: number;
 } | undefined;
 export declare function attachedOptionPayloads(tok: string): string[];
 /**
- * The home directory's VARIABLE spellings, SUBSTITUTED with the declared value before a read face segments the
- * command: `$HOME` / `${HOME}` at the START of a word (an empty quote pair before it included), unquoted or
- * double-quoted, followed by `/` or by the word's end. Those are exactly the words whose expansion is the home
- * directory and nothing else, so the word is rewritten to what bash hands the program — the value itself, in
- * place, with the word's quote structure untouched (`"$HOME/x"` → `"/home/u/x"`, `$HOME"/x"` → `/home/u"/x"`)
- * — and every arm reads an ordinary absolute path; no tilde is minted, so the tilde-prefix rule of
- * {@link tokenizeSegment} judges only tildes the command actually wrote. Substituted only against a DECLARED
- * home (`homeDir`): with none declared the child's `$HOME` may differ from what `~` falls back to, so the
- * spelling is left as written and meets the substitution hard-reject. The value must survive this file's own
- * reading of the rewritten word: the UNQUOTED spelling only for a value with no `$IFS` whitespace, glob or
- * shell metacharacter (word splitting / pathname expansion / a connector this file would then split on — none
- * of which a real expansion is subject to here), the double-quoted one for any value carrying no `"`, `$`,
- * backtick, backslash or line break (the characters that would change the quote structure or meet the
- * hard-reject). Everything else is left as written: a single-quoted spelling does not expand, and a mid-word
- * or suffixed one (`x$HOME`, `$HOME.bak`, `$HOMES`) still meets the substitution hard-reject. Bails whole on
- * an escape or a backtick in the command (the hard-reject refuses those strings regardless, and the quote
- * walk below is exact only without them) and on unbalanced quoting.
+ * The home directory's VARIABLE spelling as a word FACT: `$HOME` / `${HOME}` as the word's FIRST piece,
+ * unquoted or double-quoted, followed by `/`, by a double-quoted piece, or by nothing (unquoted), or — inside
+ * the quotes — by `/` or the closing quote; every later piece literal. Those are exactly the words whose expansion
+ * is the DECLARED home and nothing else, so `spelled` is what bash hands the program: `<home><rest>`. Everything
+ * else is left to be the expansion it is: a single-quoted spelling does not expand, a mid-word or suffixed one
+ * (`x$HOME`, `$HOME.bak`, `$HOMES`) is a substitution the classify faces refuse and the read station cannot
+ * place, and an unquoted spelling of a home bash would split or glob ({@link HOME_EXPANDS_TO_ONE_WORD}) is not
+ * one word. The caller reads it only against a declared home (with none declared the child's `$HOME` may differ
+ * from what `~` falls back to) and only when the command cannot rebind `HOME` ({@link homeMayBeRebound}).
  */
-export declare function foldHomeVariableSpelling(command: string, homeDir: string | undefined): string;
+export declare function homeExpansionOf(w: LexedWord, home: string): {
+    readonly spelled: string;
+} | undefined;
+/** May this command text REBIND `HOME` before a later word expands it? Read LEXICALLY, not by grammar: the text
+ *  spells the name `HOME` somewhere other than as a plain read ({@link HOME_PLAIN_READ}) — after `\<newline>`
+ *  continuations are joined and quotes (with the `$` of a `$'…'` / `$"…"` opener) and backslashes are removed, so
+ *  `"HO"ME`, `HO\ME`, `HO$'ME'` and an `eval` string spell it the same as a bare word. That covers an assignment at ANY nesting depth (a `{ … }` group, a
+ *  function body, a `case` arm, a loop), a declaration builtin's operand, a `for` / `select` variable, a `read` /
+ *  `printf -v` / `mapfile` / `getopts` / `unset` target, a nameref value, an arithmetic or `${HOME:=…}` assignment,
+ *  without naming any of them. A reader that substitutes the declared home for `$HOME` / `${HOME}` / a leading `~`
+ *  asks this first; a text it answers yes for leaves those words unplaced (the fail-closed side).
+ *  WHY not a grammar reading: every "where does the name stand" reading of this question (the leading assignment
+ *  words, a declaration builtin's operands) has had a nesting level or a builtin it did not see.
+ *  ACCEPTED COST: a text that merely spells the name while reading through the home — `echo HOME; cat ~/x`, a longer
+ *  name ending in it (`MY_HOME=…`), a comment — asks instead of running.
+ *  A name the shell COMPUTES spells no `HOME` to find, so four more readings count as a rebinding: an unquoted GLOB
+ *  word whose pattern can match the name `HOME` or an array element `HOME[…]` of it ({@link globMayMatchHome} —
+ *  `read H?ME`, `unset [H]OME`, `read H?ME[0]`, `unset *` glob against the working directory when an entry named
+ *  `HOME` sits there); an unquoted EXTGLOB opener ({@link hasUnquotedExtglobOpener} — `read !(x)` matches nearly
+ *  every name); an unquoted BRACE list ({@link wordHasBraceList} — `read H{O,X}ME` expands to a list whose first
+ *  word is the name); an option word that carries a glob ({@link optionWordCarriesGlob} — `read -aH?ME`, where a
+ *  matched entry named `-aHOME` hands the builtin `-a HOME`); and a `printf -v` name that is not a literal
+ *  identifier ({@link printfNamesComputed} — `printf` opens no path, so its words are no candidate of their own).
+ *  Elsewhere a computed word is its own unresolvable candidate, and an escape the lexer does not decode is
+ *  unresolved on its own (asked). */
+export declare function homeMayBeRebound(text: string): boolean;
 /**
  * {@link classifyCompoundReadonly} with the structured verdict. The name/operator/blocking arms
  * run FIRST and unchanged, so an existing demotion keeps its exact reason and never acquires the
@@ -949,16 +961,12 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  *     verdict carrying {@link CompoundReadonlyVerdict.undecidedPaths} (an unexpanded glob) rejects,
  *     because the probe face is reason-only and a repeated read of a runtime-decided target must not
  *     auto-allow.
- *  G5 STRUCTURE SOUNDNESS (the parser sees what bash executes). Whitespace is normalized first: any
- *     non-ASCII / control whitespace ({@link NON_ASCII_WHITESPACE}) rejects the whole command, so this
- *     grammar's `[ \t]`/`\s` word split and bash's `$IFS` split cannot diverge (an NBSP-joined
- *     `ls x` never reads as head `ls` here while bash runs one word). Quote pairing is then checked
- *     whole-string ({@link pollLoopQuotesBalanced}); the var/iterable region admits no quote character
- *     at all; so the `for … ; do … ; done` skeleton the anchored regex matches is exactly the one bash
- *     parses — a `done` hidden in quotes either unbalances (reject) or leaves a body token that fails
- *     the allowlist. Within the body, the quote-blind `;` split inherits the compound face's
- *     soundness argument: with all expansion metacharacters banned, quotes only ever HIDE connectors,
- *     so mis-splits are over-fine and the error direction is reject, never widen.
+ *  G5 STRUCTURE SOUNDNESS (the parser sees what bash executes). Any non-ASCII / control whitespace
+ *     ({@link NON_ASCII_WHITESPACE}) rejects the whole command up front, the reference implementation's
+ *     form. The skeleton is then read off the ONE lexer's segments and words ({@link pollLoopShapeOf}) — the
+ *     same reading bash gives the text: an unterminated quote is a parse failure (reject), a `done` hidden in
+ *     quotes is a word that is not `done`, and the var/iterable words must be written bare. The body's
+ *     segments are the lexer's, so a connector inside quotes is text, never a boundary.
  *  G6 ENVIRONMENT INTEGRITY. The loop variable must be a SINGLE LOWERCASE LETTER: the `for`
  *     assignment mutates a shell variable, and a name like `PATH`/`IFS`/`LD_PRELOAD`/`BASH_ENV`
  *     would change how the body's commands RESOLVE (`for PATH in dir; do cat x; done` would run