@sema-agent/core 7.24.2 → 7.24.3

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

@@ -1,4 +1,4 @@
-import { type ShellSegmentConnector } from "./bash-lexer.js";
+import { type SegmentTokens, type ShellSegmentConnector } from "./bash-lexer.js";
 import { type ShellScanDecline } from "./bash-program-position.js";
 /**
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
@@ -480,6 +480,30 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  * the compound grammar refuses first, so a command-level pin cannot tell a live guard from an absent one.
  */
 export declare function deepestCommonDir(a: string, b: string): string | undefined;
+/** Programs whose operands are NEVER filesystem paths, so no operand of theirs is checked:
+ *  `echo`'s words are literal text, `which`'s are PATH lookups, `tr`'s are character sets, and
+ *  `basename`/`dirname` do pure string surgery on a path without ever opening it. Everything else —
+ *  including a deployment-widened name this file does not know — goes through the path-shaped
+ *  operand scan below, which is safe for an unknown command because a bare word can only ever name
+ *  something under the working directory. */
+export declare const NO_PATH_OPERAND_COMMANDS: ReadonlySet<string>;
+/** True for a token that can denote a filesystem location OUTSIDE the working directory. A bare word
+ *  (`foo`, `a.txt`, a grep pattern, an awk program) cannot: with no separator and no `..` it always
+ *  resolves under the cwd, which the caller's cwd governance already covers.
+ *
+ *  The one spelling that would break that argument is a win-form absolute written with
+ *  backslashes only (`\\host\share\secret`, `C:\other\secret`): no `/`, so not path-shaped, yet it names
+ *  something the cwd does not contain. Two separate facts, once written as one:
+ *   · on the COMPOUND faces it is indeed unreachable — {@link SHELL_SEGMENT_QUOTE_BLIND_REJECT} refuses the
+ *     whole command as soon as it contains a backslash, wherever it stands, so no such token reaches this scan;
+ *   · on {@link classifySimpleCommandReadBoundary} — one command, no compound grammar, and therefore no
+ *     such gate — it DOES reach it. Measured on a win32-rooted boundary, before the lane split below: the operand
+ *     resolved to nothing, was dropped, and the verdict was empty, i.e. a read outside every root
+ *     AUTO-ALLOWED on the one face whose doctrine is hard refusal in exactly that direction.
+ *  The second fact is why the lane split in
+ *  {@link collectSegmentBoundaryFindings} tests {@link isAbsolutePathForm} BESIDE this predicate,
+ *  which is what the option-payload arm always did; the two now read one rule rather than two. */
+export declare function isPathShapedToken(tok: string): boolean;
 /** Resolve one operand against the boundary's base, WITHOUT touching the filesystem. Returns undefined
  *  when the token cannot be resolved statically — the fail-closed direction, reported as its own
  *  demotion rather than silently treated as in-root.
@@ -519,6 +543,13 @@ export interface OperandSpellings {
 /** Resolve one operand into {@link OperandSpellings}, or `undefined` on the same unresolvable operands
  *  {@link resolveOperandLexically} reports (it is this function's folded half). */
 export declare function resolveOperandSpellings(base: string | undefined, operand: string, homeDir: string | undefined): OperandSpellings | undefined;
+/** Programs that run their argument AS SHELL TEXT (the sh family, `eval`, `source`, `.`): what they read is decided
+ *  by text nobody here parsed. Spelled as a pattern, not a name list — these are program names, never tool names.
+ *  The prefix alternation is the SPELLINGS of the shell, not a curated subset of them: the Almquist shell and
+ *  its descendants (`ash`, `mksh`, `yash`, `pdksh`) and the C shell family (`csh`, `tcsh`) all run `-c` text
+ *  exactly as `sh` does, and a deployment that meets one of them meets the whole member. GNU `parallel` is a member
+ *  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;
 /** Whether a command the grammar gate REFUSED WHOLE may READ a file the boundary never judged. The answer is the
  *  complement of a WHITELIST: the command is exempt only when every part of it is a shape the scan fully understands
  *  and none of those shapes reads a file outside the walk's reach — everything else is read evidence, so a token the
@@ -540,6 +571,446 @@ export interface RefusedCommandScan {
     readonly mayRead: boolean;
     readonly declined: boolean;
 }
+/**
+ * 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.
+ */
+export declare function hasUnquotedExpansionMetachar(rawToken: string): 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.
+ */
+export declare function hasUnquotedGlobMetachar(rawToken: string): 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.
+ *
+ * Read over the whole leading letter RUN, not a prefix: GNU clusters short options (`-if` is `-i -f`) and a
+ * prefix reading left the slot to swallow — and therefore skip — a real file operand. Digits belong to the run
+ * (grep's obsolete numeric context spec: `-2ebeta` is `-C2 -e beta`), and a long option is matched as an
+ * ABBREVIATION of the declared name (`grep --reg=X <outside>` is `--regexp`). Over-triggering is harmless in
+ * the direction that matters: a token wrongly counted here makes the first operand a CHECKED path candidate.
+ */
+export declare function suppliesFirstOperandSlot(slot: NonNullable<VerbOptionSlots["firstOperand"]>, tok: string): boolean;
+/**
+ * WHAT ONE OPTION'S VALUE IS, per verb — the one declaration every reader of an option token shares.
+ *
+ * The question asked of a value is always "can this name a file?", and the answer is a property of the
+ * OPTION and its own grammar, never of the value's shape: `sed -e 's/a/b/'` and `sed -f s.sed` differ in
+ * nothing a shape test can see. The kinds spell that answer out per slot so a row is auditable letter by
+ * letter, and {@link slotValueCandidates} is where every consumer gets it — a kind that cannot name a
+ * file yields nothing there, which is the same answer as "this value named none".
+ */
+export type OptionValueKind = "path" | "indirect" | "pattern" | "script" | "count" | "delimiter" | "name-pattern" | "form" | "header" | "url" | "label";
+/**
+ * One verb's option grammar: which short letters and long names take a VALUE, and what that value is.
+ *
+ * FAIL-SAFE BY CONSTRUCTION, which is what makes a PARTIAL row sound: the reader must account for every
+ * option character it walks, so the first character a row does not declare ends the reading as
+ * `unexplained` and hands the token back to the verb-blind payload scan ({@link attachedOptionPayloads})
+ * — today's over-approximation, unchanged. A row therefore only ever makes an answer MORE precise where
+ * it recognizes the option; omitting one costs precision, never a judgement.
+ *
+ * THREE ARITIES, because `getopt_long` has three. An option that takes no value, one that requires a
+ * value (attached or the next token), and one whose value is OPTIONAL — and the third is not the second
+ * with a caveat: `getopt_long` gives an optional value NO separated spelling, so `diff --unified a b`
+ * hands diff two FILES while `diff --unified=3 a b` hands it a width. A row that files an optional-value
+ * option under {@link VerbOptionSlots.longValue} therefore eats `a`, and the file operand it swallowed
+ * is judged by nobody — the one direction this table may never move. They go in
+ * {@link VerbOptionSlots.longOptionalValue}, which reads the attached spelling and consumes nothing in
+ * the separated one. A short letter whose value is optional (`sed -i[SUFFIX]`) is left out of BOTH short
+ * maps for the same reason: an optional value can only ever be attached, and the blind scan is the safe
+ * reading of a token this row will not explain.
+ *
+ * WHAT A ROW MAY NOT GET WRONG, stated as the rule for adding one: declaring a FILE-valued option
+ * as something else hides a read, and so does declaring an OPTIONAL-value option as a required one —
+ * the value it eats in the separated spelling is a file operand. Declaring a value-taking option as
+ * plain is safe (the reading ends unexplained at its value), and declaring the non-file slots is what
+ * removes the phantom candidates a blind split invents — admitting one more option character moves the
+ * split right, and a split that lands on a `/` manufactures an absolute path the command never names.
+ *
+ * AND A ROW IS ABOUT A NAME, WHICH TWO IMPLEMENTATIONS MAY NOT SPELL ALIKE. `sed -l` takes a required
+ * line length in one widely deployed sed and NO value in another; `grep --context` is optional in one
+ * and required in another; and the engine runs whichever the host ships. A disputed arity is resolved
+ * towards the reading that CONSUMES NOTHING, because only consuming can swallow a file operand: a
+ * disputed LONG name is filed as optional-value (right under one reading, merely imprecise under the
+ * other), and a disputed SHORT letter is left out of both short maps, since the short maps have no way
+ * to say "attached only". Where implementations disagree about a value's KIND rather than its arity,
+ * the file-naming reading is the one to declare — over-approximating a value costs an ask and
+ * under-approximating one costs the read. Every row here is checked against the binaries this
+ * repository's own tools run on; a row added from a manual page alone is a guess.
+ *
+ * AND A ROW APPLIES WHILE THE COMMAND IS STILL IN ITS OPTION SECTION. POSIX ends option parsing at the
+ * first operand, GNU permutes, and a transfer program parses its own options anywhere — so once the
+ * operands have begun, whether a dash-leading token is an option at all is implementation-dependent and
+ * BOTH readings are taken: the token is not consumed (it is judged as the operand it may be) and the
+ * slot's candidates are judged too (it may name a file). Adding a candidate is always safe; consuming
+ * is what hides one.
+ *
+ * @contract shell.read_boundary.option_value_slots — where this table declares a verb's option, the
+ * read boundary reads that option's value from the DECLARED slot and nowhere else: a slot that can name
+ * a file yields exactly its value as a path candidate (an `indirect` slot also yields what the value
+ * names past its `@`, a `header` slot only for a whole-value `@<file>`, and a `url` slot the local path
+ * a `file:` URL names), and a slot that cannot yields none — the attached and separated spellings of one
+ * option read the same row and can never disagree, except where the row declares the value OPTIONAL,
+ * which has no separated spelling at all. Past the command's first operand the separated spelling
+ * consumes nothing and its value is judged BOTH as that value and as an operand, because which of the
+ * two it is, is implementation-dependent. Where it declares nothing — no row for the verb, an
+ * option character the row does not account for, a long-option prefix whose reachable names leave this
+ * spelling's value unsettled —
+ * the verb-blind payload scan judges the token exactly as it did before, so an absent or partial row
+ * costs precision and never a judgement. A row is DATA about a PROGRAM and not about the read-only
+ * allowlist: it says what that program does with its own argument, never that the program may be read
+ * from, and it grants no per-verb arm to a program a deployment has not listed.
+ */
+export interface VerbOptionSlots {
+    /** Short letters whose value is the rest of the token, or the NEXT token when the letter ends it. */
+    readonly shortValue: Readonly<Record<string, OptionValueKind>>;
+    /** Short letters taking no value. */
+    readonly shortPlain: string;
+    /** Long option FULL names whose value is `=<value>` or the next token. */
+    readonly longValue: Readonly<Record<string, OptionValueKind>>;
+    /** Long option FULL names whose value exists ONLY as `=<value>`: `getopt_long`'s `optional_argument`,
+     *  which never reaches for the next token. Reading one of these as {@link longValue} would consume the
+     *  operand that follows the bare spelling, so the operand goes unjudged — see the THREE ARITIES note. */
+    readonly longOptionalValue: Readonly<Record<string, OptionValueKind>>;
+    /** Long option FULL names taking no value — declared so that an abbreviation reaching one is seen to be
+     *  ambiguous rather than read as its value-taking neighbour. */
+    readonly longPlain: readonly string[];
+    /** SINGLE-dash WORD options — a grammar getopt does not have and a cluster walk cannot read: `-name` is not
+     *  `-n -a -m -e`, and splitting it that way manufactures a path candidate per suffix. Asked before the cluster
+     *  walk, only for a dash plus MORE THAN ONE character; a name in neither map falls to the verb-blind scan. */
+    readonly dashWordValue?: Readonly<Record<string, OptionValueKind>>;
+    /** The value-less half of {@link dashWordValue}. */
+    readonly dashWordPlain?: readonly string[];
+    /** The FIRST positional operand, where this verb's grammar gives it a meaning that is NOT a file: grep's
+     *  PATTERN, sed's SCRIPT. Read with the same {@link OptionValueKind} vocabulary the option slots use, so
+     *  {@link slotValueCandidates} answers "can this word name a file" once for both spellings — `sed -e '/x/p' f`
+     *  and `sed '/x/p' f` are one invocation and were two readings. `suppliedBy*` name the options that deliver
+     *  the slot instead, leaving the first operand a file after all. No row ⇒ an ordinary first operand. */
+    readonly firstOperand?: {
+        readonly kind: OptionValueKind;
+        /** Short letters, matched inside a cluster and with digits allowed in front (grep's obsolete numeric
+         *  context spec: `-2ebeta` is `-C2 -e beta`). */
+        readonly suppliedByLetters: string;
+        /** Long option FULL names; an abbreviation reaching one counts ({@link isLongOptionAbbrevOf}). */
+        readonly suppliedByLongNames: readonly string[];
+    };
+    /** This program parses its options WHEREVER they appear, so the permute ambiguity the both-readings rule
+     *  below answers (POSIX/GNU/BSD disagree whether a dash-token past the first operand is still an option) does
+     *  not exist for it. Declared only where the program's manual states the grammar, and never to rescue a
+     *  spelling into auto-allow: a token the row does not explain still goes to the verb-blind scan. */
+    readonly optionsArePositionIndependent?: true;
+}
+/** What one row makes of ONE option token. `unexplained` = the row cannot account for the token, and the
+ *  caller reads it the verb-blind way it always did. */
+export type VerbOptionSlotReading = {
+    readonly form: "unexplained";
+} | {
+    readonly form: "no-value";
+} | {
+    readonly form: "attached";
+    readonly value: string;
+    readonly kind: OptionValueKind;
+} | {
+    readonly form: "separated";
+    readonly kind: OptionValueKind;
+};
+/**
+ * Read one option token of `name` through its row. `undefined` ⇒ this verb has no row.
+ *
+ * Short form is getopt: scanning the cluster left to right, the FIRST value-taking letter owns the
+ * remainder of the token, or the next token when it ends there. Long form is `getopt_long`'s
+ * unambiguous-prefix rule with an EXACT name resolved first; a prefix reaching several names is settled
+ * only where they agree about what THIS spelling does with its value, which is one question for an
+ * attached `=value` (can it name a file?) and two for a separated one (does the option take the next
+ * token at all?) — see the branch below.
+ *
+ * An unsettled prefix falls back rather than guessing, because skipping a value that is really a FILE
+ * hides a read: the verb-blind scan that judges every suffix is the safe answer to "this row does not
+ * know". That direction is why this reading is NOT the stdin floor's ({@link SEPARATED_VALUE_OPTIONS}),
+ * which asks a different question — does this value fill one of the SLOTS the floor counts — and answers
+ * it in the other direction. Measured rather than argued: reading the floor off this table moved twelve
+ * of its verdicts, eight of them wrongly (`grep -e pat file` blocks on nothing, and its pattern value is
+ * exactly what makes grep's floor of two `<pattern> <file>`).
+ */
+export declare function readVerbOptionSlot(name: string, tok: string): VerbOptionSlotReading | undefined;
+/** Does this verb's row declare that its options are parsed WHEREVER they appear — i.e. that the permute
+ *  ambiguity the both-readings rule answers does not exist for it? See
+ *  {@link VerbOptionSlots.optionsArePositionIndependent}. */
+export declare function verbOptionsArePositionIndependent(name: string): boolean;
+/** The verb's first-operand slot row, for a reader outside this module that walks operands with the same tables. */
+export declare function verbFirstOperandSlot(name: string): VerbOptionSlots["firstOperand"];
+/**
+ * The path candidates one DECLARED value offers, which is also the answer to "did this value name a
+ * file?" — an empty list IS the no.
+ *
+ * Three readings, one per grammar the declared slots have: a value that always names a file offers
+ * itself; an `indirect` one may name a file either way, so it offers itself AND what it names past an
+ * `@`; and a `header` names a file ONLY as a whole-value `@<file>` — `curl -H 'X: /etc/x'` sends that
+ * text and opens nothing, while `curl -H @<file>` adds a header per line of the file (measured against
+ * the binary, both directions). Reading `header` the `indirect` way would refuse a header whose text
+ * merely looks like a path; reading it as a non-file kind hides the `@` spelling, which is the direction
+ * that may not be taken.
+ */
+export declare function slotValueCandidates(value: string, kind: OptionValueKind): string[];
+/**
+ * The per-command model of RECURSIVE/EXPANDING read forms: invocations that read the
+ * SUBTREE of a path operand, not the operand itself. Consumed by {@link collectSegmentBoundaryFindings}
+ * only when a {@link BashReadonlyRootBoundary.denyMatch} seat is wired and has entries to apply (see
+ * {@link CompoundReadonlyVerdict.recursiveReadPaths} for the contract and why the deny seat is the
+ * trigger), and then only for the rows whose {@link RecursiveReadFormModel.discloses} column reads
+ * "contents". The reference implementation draws the same line as a verb set: its recursive-reach breaker
+ * fires for `grep`/`egrep`/`fgrep`/`rg`/`diff` (plus two copy verbs a WRITE face answers for here) and for no
+ * name that merely lists a tree; `tar` is a contents row here and absent there, because that implementation
+ * ships no built-in deny table and this one does.
+ *
+ * Membership covers every {@link BASH_READONLY_DEFAULT_ALLOW} verb with a recursive form, PLUS the
+ * common tree-reading verbs a deployment plausibly widens its allowlist with (`find`, `rg`, …): the
+ * allow set is a caller parameter, and a table pinned to the default list would silently go blind the
+ * day a deployment adds `rg` — whose recursion needs no flag at all. A widened verb this table does
+ * not know stays name-only classified (recorded residual: the deployment owns that widening, same
+ * posture as the allowlist's own header note).
+ *
+ * DIRECTION. Detection over-approximates deliberately: a flag mis-read as recursive costs one ask on
+ * a command that is usually a real-getopt error anyway (`grep -dr …` — ambiguous enum value), while an
+ * under-read auto-allows a traversal the deny judge never saw — the leaking direction. The cluster
+ * walk therefore honours getopt value-owner semantics ONLY where skipping prevents a false fire on a
+ * value AND the ownership holds on every supported implementation (`grep -eRfoo` is a pattern under
+ * GNU and BSD alike), never to rescue a spelling into auto-allow — a letter whose ownership DIVERGES
+ * across implementations is not modeled at all (see the `ls` row), because a scan stopped on the
+ * wrong platform's table is an auto-allowed real traversal.
+ */
+export interface RecursiveReadFormModel {
+    /** What the traversal puts in front of the CALLER: the file CONTENTS it walked over, or only their
+     *  NAMES and sizes. The demotion arm reads "contents" rows only — the deny judge cannot pre-check a
+     *  subtree, and handing back the bytes it guards is the hazard; handing back names is a different
+     *  disclosure with a different answer. WHERE THE BYTES GO is part of the question and not always a
+     *  property of the verb (`tar -cf -` writes the archive to stdout), and reading that per invocation is a
+     *  per-program option model this zero-IO pass does not carry — so an ambiguous row resolves demote-ward,
+     *  as every ambiguity here does. A "names" row's other fields have no behavioural consumer today; the
+     *  row stays because it is a DECISION, and a verb deleted from this table reads as one nobody made. */
+    readonly discloses: "contents" | "names";
+    /** The verb's ordinary operation IS a tree walk — every invocation with a path operand recurses,
+     *  no flag required (`du`, `find`, `rg`, `tree`, `ag`, `ack`). */
+    readonly always?: true;
+    /** Short option letters selecting recursion, judged over the getopt option-letter run. */
+    readonly shortLetters?: string;
+    /** Value-taking short letters: the FIRST one hit owns the token remainder (or, when it ends the
+     *  token, the next token) — letters inside that value are not options and must not fire. List a
+     *  letter ONLY when it takes a value on EVERY supported implementation (GNU and BSD): stopping the
+     *  scan on one platform's table is an under-read on the other, the leaking direction. */
+    readonly valueOwners?: string;
+    /** Long option names selecting recursion, abbreviation-aware ({@link isLongOptionAbbrevOf} — an
+     *  abbreviation real getopt_long would call ambiguous over-fires into an ask, the safe side). */
+    readonly longNames?: readonly string[];
+    /** Enum-valued options where one VALUE selects recursion (grep's `-d recurse` /
+     *  `--directories=recurse`). The value is matched as a CASE-FOLDED unambiguous-prefix
+     *  over-approximation: GNU argmatch accepts prefixes, and BSD grep accepts the value
+     *  case-insensitively (`-d RECURSE` recurses — verified on the real binary), so
+     *  both laxities fold in. A spelling only one implementation accepts over-fires on the other
+     *  into an ask on an erroring command — the required side. */
+    readonly enumOptions?: readonly {
+        shortLetter?: string;
+        longName?: string;
+        recursiveValue: string;
+    }[];
+    /** tar's traditional dash-less FIRST-operand key word (`tar cf out.tar dir`, the "old option
+     *  style" in tar's own manual): mode letters found there select recursion exactly as their dashed
+     *  spellings do. */
+    readonly bundledModeLetters?: string;
+    /** `true` when a bare `-` operand denotes STDIN for this command (content readers: grep's file
+     *  slot, diff, tar's `-f -`). Absent ⇒ `-` is an ordinary filename (ls/du/find/tree have no stdin
+     *  sense) and stays a positional operand for the recursion demotion. */
+    readonly dashIsStdin?: boolean;
+}
+export declare const RECURSIVE_READ_FORMS: Readonly<Record<string, RecursiveReadFormModel>>;
+/**
+ * Read ONE sed script and answer whether it can name a file or run a command.
+ *
+ * sed's command letters are a CLOSED set, which is what makes this a small recognizer over a known
+ * grammar rather than a second hand-written parser over an open one: address → optional negation →
+ * command letter → the argument that letter takes. Anything the walk cannot finish reading — an
+ * unbalanced `s` delimiter, an unclosed `{`, a letter outside the set — answers `unparsed`, which
+ * its caller treats exactly as it treats `names`: sed itself rejects those scripts, so the cost of the
+ * conservative answer is one approval on a script that was not going to run.
+ */
+/** What one sed script NAMES: the files its `r`/`R` commands read, the files its `w`/`W` commands (and `s///w`)
+ *  write, the command lines its `e` commands run, and whether an `s///e` flag executes the pattern space. */
+export interface SedScriptNames {
+    readonly reads: readonly string[];
+    readonly writes: readonly string[];
+    readonly commands: readonly string[];
+    readonly executesPatternSpace: boolean;
+}
+/**
+ * Does this verb's SCRIPT SLOT put a file name or a command line somewhere the walk's operand reading
+ * cannot see? Table-driven by verb so a second such verb is a row rather than a second branch.
+ *
+ * EVERY implementation reading is asked, and the answers combined: an affirmative `names` under any one
+ * refuses; a script no reading could SEE refuses, because file-supplied program text may carry anything;
+ * and a script no reading could finish refuses. A reading that lands on a clean script is what clears the
+ * invocation — which is what keeps the everyday spellings, whose other reading lands on a plain file name,
+ * at their old verdict.
+ */
+/** Every file and command line a sed invocation's script slot names, under BOTH option dialects (the union,
+ *  deduplicated): what a candidate extraction hands the read judge (`reads`), the write face (`writes`) and a
+ *  nested plan (`commands`). A reading that saw no text names nothing here — that fact rides the verdict face. */
+export declare function sedScriptSlotFiles(args: readonly string[]): SedScriptNames;
+/**
+ * How an INTERPRETER receives the program it runs, declared per interpreter rather than guessed.
+ *
+ * The member that completes the ARGUMENT-AS-PROGRAM family. An interpreter's program can arrive three
+ * ways: as an OPTION's value (`perl -e '...'`, `python3 -c '...'`, `node --eval '...'`), as the first
+ * OPERAND (the awk family, whose program is mandatory and is not a file unless `-f` named one), or on
+ * STANDARD INPUT when the command line names none at all. Only the third and the first are this arm's
+ * business together with the second; a program named as a FILE operand (`perl x.pl`, `python3 app.py`)
+ * is a path the ordinary operand walk already judges, and stays exactly where it was.
+ *
+ * WHAT IS JUDGED IS THE PRESENCE OF PROGRAM TEXT, NEVER ITS CONTENT. A quoted program is ONE word to
+ * this file's lexer and its contents are never parsed — so the answer cannot be "does this program read
+ * a file", only "is there a program this walk did not read". That is why the everyday harmless
+ * spellings (`node -e 'console.log(1)'`) refuse along with the rest: telling them apart needs a parser
+ * per language, which is exactly the thing a lexical floor must not grow.
+ *
+ * A row is DATA, so a further interpreter is a row rather than a branch, and a versioned spelling
+ * (`python3.11`, `perl5.36`, `tclsh8.6`) is the same row via {@link interpreterKey}.
+ */
+export interface InlineProgramModel {
+    /** Options whose value is program TEXT, separated (`--eval prog`) or fused (`--eval=prog`). Matched on
+     *  the whole token, so a single-dash long option (`-cmd`) is one of these rather than a letter bundle. */
+    readonly longText: ReadonlySet<string>;
+    /** Options whose value NAMES the program (a script file, or a module the interpreter resolves). */
+    readonly longFile: ReadonlySet<string>;
+    /** Options that NAME the program while taking NO value of their own — a mode that selects what runs
+     *  (`node --test` runs the test files it discovers, and reads no program from its input). */
+    readonly longNamesProgram: ReadonlySet<string>;
+    /** Options whose value is a file the interpreter reads BESIDE the program it is given — an
+     *  initialization script, a library to preload. Their value is consumed so it is not counted as an
+     *  operand, and they do NOT name the program: what follows still has to. */
+    readonly longSupplemental: ReadonlySet<string>;
+    /** Options whose value is the NEXT token and means none of the above. */
+    readonly longValue: ReadonlySet<string>;
+    /** Long options this row declares to take NO value. Declaring them is what keeps an invocation
+     *  EXPLAINED past them, so a later script operand still ends the interpreter's own option scanning. */
+    readonly longPlain: ReadonlySet<string>;
+    /** Whether an option that NAMES the program also ends this interpreter's option processing, because
+     *  what follows is the named program's own argument list (`python3 -m <module> -c` passes `-c` to the
+     *  module). False where a named source is PRELIMINARY and further sources still follow (`dc -f <file>
+     *  -e '<program>'` runs both). */
+    readonly fileOptionEndsOptions: boolean;
+    /** Short-option letters that introduce program text — alone (`-e prog`), fused (`-eprog`) or inside a
+     *  bundle (`-pe`, `-lne`, `-uc`, `-0777e`). */
+    readonly textLetters: string;
+    /** Short-option letters whose value names the program (`-f prog.awk`, `-fprog.awk`, `-m <module>`). */
+    readonly fileLetters: string;
+    /** Short-option letters whose value is the rest of the token, or the NEXT token when the token ends on
+     *  them (`perl -I lib`). The bundle scan stops there — what follows in the token is that value. */
+    readonly separatedValueLetters: string;
+    /** Short-option letters whose value can only be ATTACHED (`perl -i.bak`, `-C<flags>`): the bundle scan
+     *  stops there too, but a bare spelling takes NOTHING from the next token — reading `perl -C -e '…'`
+     *  as "-C whose value is -e" swallowed the option that carries the program. */
+    readonly attachedValueLetters: string;
+    /** Short-option letters that take no value at all. Declaring them is what makes an invocation EXPLAINED
+     *  (see `explained` in the recognizer); they change nothing else. */
+    readonly plainLetters: string;
+    /** Short-option letters that make this interpreter PRINT AND EXIT. Per interpreter, because the same
+     *  letter is a banner in one and something else entirely in another (`-v` is the version in ruby and
+     *  VERBOSE EXECUTION in python; `-h` is the version banner in lua and the HOST in psql). */
+    readonly bannerLetters: string;
+    /** Short-option letters that make the interpreter read commands INTERACTIVELY after whatever else it
+     *  was given — a banner or a named script does not end the session, so the program still arrives on
+     *  standard input (`lua -v -i`, `lua -i script.lua`). */
+    readonly interactiveLetters: string;
+    /** Which OPERAND names the program, when any does, and whether it is program TEXT (the awk family, a
+     *  jq filter, the SQL after a database) or a program FILE (every script interpreter). Absent when no
+     *  operand ever names the program — psql's are connection arguments, and an interactive compiler's are
+     *  modules it loads before reading commands from its input. */
+    readonly programOperand?: {
+        readonly at: number;
+        readonly isText: boolean;
+    };
+    /** Whether an invocation that names no program anywhere reads one from its standard input. */
+    readonly stdinWhenUnnamed: boolean;
+}
+/** The interpreters this file has a row for, keyed by the basename bash resolves, with the trailing
+ *  version dropped ({@link interpreterKey} — which is also why the key for `sqlite3` is `sqlite`). */
+export declare const INTERPRETER_INLINE_PROGRAMS: ReadonlyMap<string, InlineProgramModel>;
+/** The row a versioned spelling belongs to: `python3`, `python3.11` and `python` are one program with
+ *  one program-delivery grammar, so the trailing version is dropped before the lookup. */
+export declare function interpreterKey(name: string): string;
+/**
+ * How this invocation receives its program, or `undefined` when it NAMES one (a script file, a module,
+ * a program file option) or names none at all on an interpreter that then reads none.
+ *
+ * Read over the folded arguments with the program word excluded. Three sources in one pass — an option
+ * whose value is program text, the operand a row declares as the program, and standard input — and one
+ * rule for every doubt: an option this file has no row for never ENDS the search for program text. The
+ * word that names the program stops the scan (past a script, `-p` belongs to the SCRIPT), but only while
+ * every option so far was one the row EXPLAINS: after an option of unknown arity the following word may
+ * be that option's value rather than the script, so the search has to run to the end.
+ */
+export declare function inlineProgramClause(model: InlineProgramModel, args: readonly string[]): string | undefined;
+/** Does this already-vetted segment (FOLDED tokens — quoting does not change what getopt sees) invoke
+ *  a {@link RECURSIVE_READ_FORMS} verb in a recursive form that DISCLOSES CONTENTS? `args` excludes the
+ *  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;
+export declare function assignmentWordPayload(word: string): {
+    kind: "value";
+    value: string;
+} | {
+    kind: "unresolved";
+    reason: 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
+ *  shape of the verb-blind rule that MANDATED the everyday build line. The exemption is theirs alone.
+ *
+ *  The polarity is the whole point. Listing the programs that DO open such a value means anything the walk
+ *  fails to recognise is exempt — and what it fails to recognise is WHICH PROGRAM RUNS: an undeclared
+ *  wrapper is read as the program (`caffeinate dd if=<path>`), and a launcher can carry the program inside
+ *  an option payload with no word equal to it (`env -Sdd if=<path>`). Both were verified to execute the
+ *  read. Inverted, none of those is on this list, so none is exempt — nor is a fifth spelling of the same
+ *  trick. A further program is a member, not a branch, and adding one is a claim about it alone.
+ *
+ *  NOT its business: the LEADING environment assignments and an OPTION word's payload, each with its own arm. */
+export declare const ASSIGNMENT_VALUE_NOT_PATHS: ReadonlySet<string>;
+/** The program the shell will RUN here and where its OWN argv begins — the two seats
+ *  {@link HeadedSegment.argvProgram} / {@link HeadedSegment.argvFrom} carry, from one reader so they cannot
+ *  disagree. Both assignment spellings are stripped BEFORE the program-position reader runs: it does not
+ *  read `NAME+=value` as an assignment (quoting makes `'A+=x'` a command NAME on folded text), so a leading
+ *  append word arrives AS the program and hides any launcher — measured on `A+=x env B=<outside> <prog>`. */
+export declare function argvProgramOf(tokens: SegmentTokens): {
+    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
@@ -643,6 +1114,10 @@ export interface OutOfRootReadGateVerdict {
     readonly checked: readonly string[];
     readonly undecided: readonly string[];
 }
+/** Working-directory moves {@link evaluateReadBoundary} does NOT model. `cd` is deliberately absent —
+ *  it IS modelled (the walk threads the base through it), which is the whole difference: a move the
+ *  walk follows keeps the verdict decidable, and one it cannot follow does not. */
+export declare const UNMODELLED_BASE_MOVERS: ReadonlySet<string>;
 /** Test seam for the lockstep pin that the launcher table (the ONE launcher truth, in the program-position
  *  reader's module) stays a SUBSET of the rule lane's curated `BARE_INTERPRETER_NAMES`. Exported for that one
  *  assertion — production code reads the table directly. The containment face ({@link classifyOutOfRootReadGate})