@sema-agent/core 7.26.3 → 7.28.0

package/dist/core/tool-policy.js

@@ -414,11 +414,31 @@ export function createApprovalPolicy(opts) {
                 if (signal?.aborted) {
                     return attest({ action: "deny", message: `approval aborted for "${req.toolName}" (run or turn interrupted)` }, settledByNobody("task_aborted"));
                 }
+                if (typeof ok === "object" && ok !== null) {
+                    const reading = readApproverOutcomeObject(ok, req.toolName, "none");
+                    if (reading.kind === "refused")
+                        return attest({ action: "deny", message: reading.message }, reading.settlement);
+                    if (reading.kind === "deny") {
+                        return attest({
+                            action: "deny",
+                            message: reading.word === "policy"
+                                ? policyRefusalMessage(req.toolName, undefined, reading.note)
+                                : reading.word === "timeout"
+                                    ? `no one answered the approval request for "${req.toolName}" — the approver reported its own window elapsed with no answer; denied fail-closed${reading.note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reading.note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
+                                    : `approval denied for "${req.toolName}"${reading.note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reading.note, REVIEWER_NOTE_MAX_BODY)}` : ""}`,
+                        }, reading.settlement);
+                    }
+                    return attest({ action: "allow" }, reading.settlement);
+                }
                 const okRaw = ok;
                 if (okRaw === true)
                     return attest({ action: "allow" }, settledByPerson("human_allowed", undefined));
                 if (okRaw !== false) {
-                    return attest({ action: "deny", message: `approval callback for "${req.toolName}" returned an out-of-contract value (${typeof ok}) — denied fail-closed (this policy's \`approve\` returns a boolean: return true or false)` }, settledByNobody("approver_contract"));
+                    return attest({
+                        action: "deny",
+                        message: `approval callback for "${req.toolName}" returned an out-of-contract value (${typeof ok}) — denied fail-closed ` +
+                            `(this policy's \`approve\` returns true, false, or the {allow, settledBy?, reason?, approver?} outcome object)`,
+                    }, settledByNobody("approver_contract"));
                 }
                 return attest({ action: "deny", message: `approval denied for "${req.toolName}"` }, settledByPerson("human_refused", undefined));
             }
@@ -1134,6 +1154,78 @@ function detachLateAskWait(wait, onLate) {
     })
         .catch(() => undefined);
 }
+function readApproverOutcomeObject(ok, toolName, editLane) {
+    const refused = (message, settlement) => ({ kind: "refused", message, settlement });
+    let supplied;
+    let allowed;
+    let suppliedEdit;
+    let suppliedApprover;
+    try {
+        supplied = ok.settledBy;
+        allowed = ok.allow;
+        suppliedEdit = ok.updatedInput;
+        suppliedApprover = ok.approver;
+    }
+    catch (err) {
+        return refused(`the approver's outcome for "${toolName}" could not be read (${describeThrown(err)}) — denied fail-closed`, settledByNobody("approver_contract"));
+    }
+    if (typeof allowed !== "boolean") {
+        return refused(`the approver for "${toolName}" returned an object whose allow is not a boolean ` +
+            `(got ${allowed === null ? "null" : typeof allowed}) — a verdict is exactly true or false; denied fail-closed`, settledByNobody("approver_contract"));
+    }
+    if (supplied !== undefined && supplied !== "human" && supplied !== "timeout" && supplied !== "policy") {
+        return refused(`the approver for "${toolName}" reported settledBy "${typeof supplied === "string" ? containThrownText(supplied) : supplied === null ? "null" : typeof supplied}", which is outside what a synchronous ` +
+            `approver may self-report — it is exactly "human", "timeout" or "policy" (or omitted); denied fail-closed`, settledByNobody("approver_contract"));
+    }
+    const settledWord = supplied === "timeout" ? "timeout" : supplied === "policy" ? "policy" : "human";
+    const attribution = screenApproverAttribution(suppliedApprover);
+    if (attribution.defect !== undefined) {
+        return refused(`the approver for "${toolName}" reported an attribution this seam refuses: ${attribution.defect}; denied fail-closed`, settledByNobody("approver_contract"));
+    }
+    if (settledWord !== "human" && allowed === true) {
+        return refused(`the approver for "${toolName}" returned an allow settled by "${settledWord}" — only a person approves, and that word ` +
+            `names a wait that ended with nobody judging: it cannot be what approved a call; denied fail-closed ` +
+            `(report "${settledWord}" with allow:false, or allow with settledBy "human"/omitted)`, settledByNobody("approver_contract"));
+    }
+    if (allowed !== true) {
+        let reasonText;
+        try {
+            const suppliedReason = ok.reason;
+            if (suppliedReason !== undefined && typeof suppliedReason !== "string") {
+                return refused(`the approver for "${toolName}" attached a reason that is not a plain string ` +
+                    `(got ${suppliedReason === null ? "null" : typeof suppliedReason}) — a deny note is the decider's plain text; denied fail-closed`, settledByNobody("approver_contract"));
+            }
+            reasonText = typeof suppliedReason === "string" ? suppliedReason : undefined;
+        }
+        catch (err) {
+            return refused(`the approver for "${toolName}" attached a reason that could not be read (${describeThrown(err)}) — denied fail-closed`, settledByNobody("approver_contract"));
+        }
+        const note = decidersNote(reasonText);
+        return {
+            kind: "deny",
+            word: settledWord,
+            note,
+            settlement: settledWord === "timeout"
+                ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() }
+                : settledWord === "policy"
+                    ? settledByNobody("policy_refused")
+                    : settledByPerson("human_refused", attribution.approver, note),
+        };
+    }
+    if (suppliedEdit === undefined)
+        return { kind: "allow", edit: undefined, settlement: settledByPerson("human_allowed", attribution.approver) };
+    if (editLane === "none") {
+        return refused(`the approver for "${toolName}" attached an edit (updatedInput) on a seat that has no lane to adjudicate one — ` +
+            `this seat's answer is the deployment POLICY's verdict, and an edit arriving through it would execute without the ` +
+            `re-adjudication an approver's edit gets; denied fail-closed (approve or refuse what was shown, and route edits ` +
+            `through the run's approver seat)`, settledByNobody("approver_contract"));
+    }
+    const edit = tryCloneArgs(suppliedEdit);
+    if (!edit.ok) {
+        return refused(`the approved edit for "${toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`, settledByNobody("presentation_failed"));
+    }
+    return { kind: "allow", edit: { value: edit.value }, settlement: settledByPerson("human_allowed", attribution.approver) };
+}
 async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
     if (onAsk === "allow") {
         if (req.requiresRealApproval === true) {
@@ -1229,113 +1321,24 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
         };
     }
     if (typeof ok === "object" && ok !== null) {
-        let supplied;
-        let allowed;
-        let suppliedEdit;
-        let suppliedApprover;
-        try {
-            supplied = ok.settledBy;
-            allowed = ok.allow;
-            suppliedEdit = ok.updatedInput;
-            suppliedApprover = ok.approver;
-        }
-        catch (err) {
-            return {
-                action: "deny",
-                message: `the approver's outcome for "${req.toolName}" could not be read (${describeThrown(err)}) — denied fail-closed`,
-                decisionReason: "mode",
-                settlement: settledByNobody("approver_contract"),
-            };
-        }
-        if (typeof allowed !== "boolean") {
+        const reading = readApproverOutcomeObject(ok, req.toolName, "readjudicated");
+        if (reading.kind === "refused")
+            return { action: "deny", message: reading.message, decisionReason: "mode", settlement: reading.settlement };
+        if (reading.kind === "deny") {
             return {
                 action: "deny",
-                message: `the approver for "${req.toolName}" returned an object whose allow is not a boolean ` +
-                    `(got ${allowed === null ? "null" : typeof allowed}) — a verdict is exactly true or false; denied fail-closed`,
+                message: reading.word === "timeout"
+                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${reading.note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reading.note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
+                    : reading.word === "policy"
+                        ? policyRefusalMessage(req.toolName, req.message, reading.note)
+                        : humanRefusalMessage(req, reading.note),
                 decisionReason: "mode",
-                settlement: settledByNobody("approver_contract"),
-            };
-        }
-        if (supplied !== undefined && supplied !== "human" && supplied !== "timeout" && supplied !== "policy") {
-            return {
-                action: "deny",
-                message: `the approver for "${req.toolName}" reported settledBy "${typeof supplied === "string" ? containThrownText(supplied) : supplied === null ? "null" : typeof supplied}", which is outside what a synchronous ` +
-                    `approver may self-report — it is exactly "human", "timeout" or "policy" (or omitted); denied fail-closed`,
-                decisionReason: "mode",
-                settlement: settledByNobody("approver_contract"),
-            };
-        }
-        const settledWord = supplied === "timeout" ? "timeout" : supplied === "policy" ? "policy" : "human";
-        const attribution = screenApproverAttribution(suppliedApprover);
-        if (attribution.defect !== undefined) {
-            return {
-                action: "deny",
-                message: `the approver for "${req.toolName}" reported an attribution this seam refuses: ${attribution.defect}; denied fail-closed`,
-                decisionReason: "mode",
-                settlement: settledByNobody("approver_contract"),
-            };
-        }
-        if (settledWord !== "human" && allowed === true) {
-            return {
-                action: "deny",
-                message: `the approver for "${req.toolName}" returned an allow settled by "${settledWord}" — only a person approves, and that word ` +
-                    `names a wait that ended with nobody judging: it cannot be what approved a call; denied fail-closed ` +
-                    `(report "${settledWord}" with allow:false, or allow with settledBy "human"/omitted)`,
-                decisionReason: "mode",
-                settlement: settledByNobody("approver_contract"),
-            };
-        }
-        if (allowed !== true) {
-            let reasonText;
-            try {
-                const suppliedReason = ok.reason;
-                if (suppliedReason !== undefined && typeof suppliedReason !== "string") {
-                    return {
-                        action: "deny",
-                        message: `the approver for "${req.toolName}" attached a reason that is not a plain string ` +
-                            `(got ${suppliedReason === null ? "null" : typeof suppliedReason}) — a deny note is the decider's plain text; denied fail-closed`,
-                        decisionReason: "mode",
-                        settlement: settledByNobody("approver_contract"),
-                    };
-                }
-                reasonText = typeof suppliedReason === "string" ? suppliedReason : undefined;
-            }
-            catch (err) {
-                return {
-                    action: "deny",
-                    message: `the approver for "${req.toolName}" attached a reason that could not be read (${describeThrown(err)}) — denied fail-closed`,
-                    decisionReason: "mode",
-                    settlement: settledByNobody("approver_contract"),
-                };
-            }
-            const note = decidersNote(reasonText);
-            return {
-                action: "deny",
-                message: settledWord === "timeout"
-                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
-                    : settledWord === "policy"
-                        ? policyRefusalMessage(req.toolName, req.message, note)
-                        : humanRefusalMessage(req, note),
-                decisionReason: "mode",
-                settlement: settledWord === "timeout"
-                    ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() }
-                    : settledWord === "policy"
-                        ? settledByNobody("policy_refused")
-                        : settledByPerson("human_refused", attribution.approver, note),
-            };
-        }
-        if (suppliedEdit === undefined)
-            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settlement: settledByPerson("human_allowed", attribution.approver) };
-        const edit = tryCloneArgs(suppliedEdit);
-        if (!edit.ok) {
-            return {
-                action: "deny",
-                message: `the approved edit for "${req.toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`,
-                decisionReason: "mode",
-                settlement: settledByNobody("presentation_failed"),
+                settlement: reading.settlement,
             };
         }
-        return { action: "allow", updatedInput: edit.value, decisionReason: "mode", settlement: settledByPerson("human_allowed", attribution.approver) };
+        if (reading.edit === undefined)
+            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settlement: reading.settlement };
+        return { action: "allow", updatedInput: reading.edit.value, decisionReason: "mode", settlement: reading.settlement };
     }
     const okRaw = ok;
     if (okRaw === true)

package/dist/index.d.ts

@@ -177,7 +177,12 @@ export type { SchedulerCapability, SchedulerErrorCode, ScheduledIntent, Schedule
 export { createSchedulerTools, type SchedulerToolContext, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, type AutonomousLoopPromptOptions, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, 
+/** The return type of `createApprovalPolicy.approve` — a boolean, or the `AskOutcome` object minus the two
+ *  members that seat has no lane for (`"unavailable"`, a routing answer; `updatedInput`, an operator edit a
+ *  policy verdict cannot get re-adjudicated). Exported so a host can NAME it instead of deriving it through
+ *  `Parameters<typeof createApprovalPolicy>[0]["approve"]`. */
+type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, type RuleStoreUnreadable, isRuleStoreUnreadable } from "./core/ask-origin.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, screenGateOutcome } from "./core/gate-outcome.js";

package/dist/shell/lex.d.ts

@@ -0,0 +1,279 @@
+/**
+ * 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}).
+ *
+ * Two modes remain. STRICT is the residual space the classify faces live in: the caller has hard-rejected
+ * `< > $ ( ) \` \n \r \\` (or passes `<`/`>` through as text under the rule lane's tolerate option), so the whole of
+ * bash's word grammar left to model there is quote pairing, the four connectors and whitespace. LENIENT is the space
+ * the read faces read — everything the strict gate refused, RECORDED instead of refused. The lenient-only
+ * constructs are branches the strict caller can never reach, so for every strict-accepted input the two modes
+ * produce the same words and connectors, up to the strict mode's two residuals (a `#` is a word there, and JS
+ * whitespace rather than bash's blanks bounds a word).
+ *
+ * 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.
+ */
+export type LexMode = "strict" | "lenient";
+export interface LexOptions {
+    readonly mode: LexMode;
+    /** `"split"` (default): the connectors bound segments. `"text"`: a single segment is being tokenized and an
+     *  unquoted connector character is a word character. */
+    readonly connectors?: "split" | "text";
+}
+/** 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";
+/** What holds a character quoted: the four quote forms and the backslash escape, one reason each. */
+export declare const QUOTE_KINDS: readonly ["'", "\"", "$'", "$\"", "\\"];
+export type QuoteKind = (typeof QUOTE_KINDS)[number];
+/** The expansions this lexer names. Extended globs are absent on purpose: `bash -c` runs with `extglob` off, so
+ *  `?(…)` is a syntax error there and `(` is a group token here. */
+export declare const EXPANSION_KINDS: readonly ["parameter", "command", "process", "arithmetic", "tilde", "brace", "glob"];
+export type ExpansionKind = (typeof EXPANSION_KINDS)[number];
+/** Why a word's value cannot be read off the text. Each member is a spelling whose value the text does not
+ *  contain — never "the lexer did not look". */
+export declare const UNRESOLVED_REASONS: readonly ["ansi_c_escape", "locale_string", "parameter_text", "subscript_text", "compound_array_value"];
+export type UnresolvedReason = (typeof UNRESOLVED_REASONS)[number];
+/** What the {@link lexShellText} view does with an unresolved word: `refuse` hands the consumer the reason's
+ *  sentence; `fold` hands it the folded spelling as the pre-fact readers judged it. The locale string folds:
+ *  refusing it would turn a deny row's HIT (judged on the untranslated spelling) into a mere question, and a
+ *  reader that asks on both faces AND keeps the deny judgment reads the fact, not this view. */
+export declare const UNRESOLVED_VIEW: {
+    readonly ansi_c_escape: "refuse";
+    readonly locale_string: "fold";
+    readonly parameter_text: "refuse";
+    readonly subscript_text: "refuse";
+    readonly compound_array_value: "refuse";
+};
+/** The sentence the {@link lexShellText} view hands a consumer for an unresolved word it refuses. */
+export declare const UNRESOLVED_SENTENCE: {
+    readonly ansi_c_escape: "an ANSI-C quoted word carries an escape this lexer does not fold";
+    readonly locale_string: "a locale-translated string carries text this lexer does not read";
+    readonly parameter_text: "a parameter expansion carries text this lexer does not read";
+    readonly subscript_text: "a subscript carries text this lexer does not read";
+    readonly compound_array_value: "a compound assignment value is a list this lexer does not read";
+};
+/** Why a command yields no segments: bash's own syntax errors, the two constructs this lexer cannot delimit, and
+ *  the strict mode's backgrounding refusal. */
+export declare const PARSE_FAILURE_REASONS: readonly ["unterminated_single_quote", "unterminated_double_quote", "unterminated_ansi_c", "unterminated_subscript", "unterminated_compound_value", "unterminated_command_substitution", "unterminated_process_substitution", "unterminated_parameter_expansion", "unterminated_heredoc", "undelimited_substitution", "redirect_without_target", "heredoc_without_delimiter", "heredoc_delimiter_expands", "background_operator"];
+export type ParseFailureReason = (typeof PARSE_FAILURE_REASONS)[number];
+export declare const PARSE_FAILURE_SENTENCE: {
+    readonly unterminated_single_quote: "a single-quoted word never closes";
+    readonly unterminated_double_quote: "a double-quoted word never closes";
+    readonly unterminated_ansi_c: "an ANSI-C quoted word never closes";
+    readonly unterminated_subscript: "a subscript never closes";
+    readonly unterminated_compound_value: "a compound assignment value never closes";
+    readonly unterminated_command_substitution: "a command substitution never terminates";
+    readonly unterminated_process_substitution: "a process substitution never terminates";
+    readonly unterminated_parameter_expansion: "a parameter expansion never terminates";
+    readonly unterminated_heredoc: "a here-document body never terminates";
+    readonly undelimited_substitution: "a command substitution carries a construct this lexer cannot delimit";
+    readonly redirect_without_target: "a redirection names no target";
+    readonly heredoc_without_delimiter: "a here-document operator names no delimiter";
+    readonly heredoc_delimiter_expands: "a here-document delimiter is not a plain word";
+    readonly background_operator: "`&` backgrounding is not allowed — a backgrounded process outlives the command";
+};
+/** The constructs of this dialect a POSIX `sh` reads as something else. */
+export declare const BASH_ONLY_CONSTRUCTS: readonly ["ansi_c_quoting", "locale_string", "append_assignment", "subscript_assignment", "compound_assignment", "here_string", "process_substitution", "redirect_both", "brace_expansion"];
+export type BashOnlyConstruct = (typeof BASH_ONLY_CONSTRUCTS)[number];
+/**
+ * The ANSI-C escapes this lexer folds: the thirteen single-letter ones, whose byte is the same in every bash and
+ * in the reference implementation's table. Numeric, control and unicode escapes are NOT here — their bytes differ
+ * between bash 3.2 and 5.x (`\c?`, `\u`, `\U`) or truncate the region (NUL) — and a body carrying one is
+ * `unresolved` rather than decoded. Admission to this table is a differential test against the real shells.
+ */
+export declare const ANSI_C_ESCAPES: {
+    readonly a: "\u0007";
+    readonly b: "\b";
+    readonly e: "\u001B";
+    readonly E: "\u001B";
+    readonly f: "\f";
+    readonly n: "\n";
+    readonly r: "\r";
+    readonly t: "\t";
+    readonly v: "\v";
+    readonly "\\": "\\";
+    readonly "'": "'";
+    readonly '"': "\"";
+    readonly "?": "?";
+};
+export interface WordPiece {
+    /** Source offsets of the written text, `[start, end)`; a continuation between two pieces is nobody's. */
+    readonly span: readonly [number, number];
+    readonly quotedBy: QuoteKind | undefined;
+    /** The text the program receives from this piece — absent for an expansion and for an unresolved piece. */
+    readonly literal?: string;
+    readonly expansion?: WordExpansion;
+}
+export interface WordExpansion {
+    readonly kind: ExpansionKind;
+    /** `"many"` where the result is word-split (an unquoted parameter or command substitution, a brace list, a glob). */
+    readonly yields: "one" | "many";
+    /** The text between the delimiters, where there is one (a substitution body, a brace list, a tilde-prefix). */
+    readonly body?: string;
+    /** The parameter name, where the expansion names one. */
+    readonly name?: string;
+}
+export interface QuotedSpan {
+    /** Offsets into {@link LexedWord.raw}, `[start, end)`; the quote characters belong to their span. */
+    readonly start: number;
+    readonly end: number;
+    readonly by: QuoteKind;
+}
+/** Bash's assignment fact for a word whose folded spelling is `NAME[subscript]?(+)?=value`, minted wherever the
+ *  word stands. Whether bash STRIPS it before choosing the program is `bare && atCommandPosition`; whether the
+ *  program that receives it reads it as an assignment is the program's own grammar. */
+export interface AssignmentFact {
+    readonly name: string;
+    readonly op: "=" | "+=";
+    readonly subscript?: {
+        readonly raw: string;
+        readonly folded: string;
+        readonly expansions: readonly WordPiece[];
+    };
+    readonly value: {
+        readonly raw: string;
+        readonly folded: string;
+        readonly pieces: readonly WordPiece[];
+        readonly expansions: readonly WordPiece[];
+        readonly unresolved?: UnresolvedReason;
+    };
+    /** The name, the brackets and the operator are written unquoted and unescaped — the subscript's CONTENT and the
+     *  value may be quoted and still leave the word an assignment. */
+    readonly bare: boolean;
+    readonly form: "scalar" | "compound";
+    /** `op === "="` with no subscript and a scalar value: the whole name is settled by this word's text. */
+    readonly settlesWholeName: boolean;
+}
+/** An argv word. `raw` is what the SHELL sees (quotes, escapes and substitution text retained); `folded` is what
+ *  the PROGRAM receives after quote removal, with every substitution replaced by {@link SUBSTITUTION_PLACEHOLDER},
+ *  every other expansion left in its written spelling, and a literal leading tilde spelled `./~…`
+ *  ({@link literalTildeSpelling}). Both are views of {@link LexedWord.pieces}. */
+export interface LexedWord {
+    readonly kind: "word";
+    readonly raw: string;
+    readonly folded: string;
+    readonly pieces: readonly WordPiece[];
+    readonly quotedSpans: readonly QuotedSpan[];
+    /** The pieces that carry an expansion, in order. */
+    readonly expansions: readonly WordPiece[];
+    readonly assignment?: AssignmentFact;
+    /** The first reason, in reading order, that a value in this word cannot be read off the text. */
+    readonly unresolved?: UnresolvedReason;
+    /** The word was read where bash accepts an assignment or a command name: at a segment's start, after a bare
+     *  assignment word, after a bare control-prefix word, or after a leading redirection list. */
+    readonly atCommandPosition: boolean;
+}
+/** A redirection and the word it takes. A descriptor duplication (`>&2`, `<&0`, `>&-`, `>&1-`) takes none. */
+export interface LexedRedirect {
+    readonly kind: "redirect";
+    readonly op: "<" | ">" | ">>" | "<<<" | "&>" | "&>>" | ">&" | "<&";
+    readonly target?: LexedWord;
+}
+/** A here-document: the body is DATA the program reads on stdin, never command text. `quoted` records whether
+ *  the delimiter word carried a quote or an escape, which is bash's rule for "the body does not expand". */
+export interface LexedHeredoc {
+    readonly kind: "heredoc";
+    readonly delimiter: string;
+    readonly quoted: boolean;
+    readonly body: string;
+}
+/** A subshell parenthesis, standing alone: structure, not a word. */
+export interface LexedGroup {
+    readonly kind: "group";
+    readonly op: "(" | ")";
+}
+export type LexedToken = LexedWord | LexedRedirect | LexedHeredoc | LexedGroup;
+/** The connector bash ran a segment through — `"start"` for the first one. A closed set, because the read
+ *  boundary distinguishes all four: `&&` is the only one under which the previous segment is known to have
+ *  exited ZERO, `||` is the only one under which the previous segment may have been SKIPPED ENTIRELY, `|`
+ *  puts the segment in a subshell whose directory changes never reach the parent, and `;` is plain sequence. */
+export type ShellSegmentConnector = "start" | ";" | "&&" | "||" | "|";
+/** The lenient mode's two extra boundaries: a backgrounding `&` and a line break. */
+export type LenientConnector = ShellSegmentConnector | "&" | "\n";
+export interface LexedSegment {
+    /** The segment's text exactly as written (surrounding whitespace included). Here-document bodies are not part
+     *  of any segment's text. */
+    readonly text: string;
+    readonly connector: LenientConnector;
+    readonly tokens: readonly LexedToken[];
+    /** The bodies of the substitutions found in THIS segment (its words and its redirection targets), in order. */
+    readonly substitutions: readonly string[];
+}
+export interface LexedCommand {
+    readonly segments: readonly LexedSegment[];
+    /** Every substitution body of the command, in order (the per-segment lists concatenated). */
+    readonly substitutions: readonly string[];
+}
+export interface LexParseFailure {
+    readonly parseFailure: {
+        readonly reason: ParseFailureReason;
+        readonly at: number;
+    };
+}
+/** A command: its segments, or the one reason it has none. */
+export type ShellLex = LexedCommand | LexParseFailure;
+/** One segment's argv words in both spellings, index-aligned by construction (folding is strictly per word — it
+ *  never splits or joins). The one shape every downstream arm of the classifier reads. */
+export interface SegmentTokens {
+    readonly folded: readonly string[];
+    readonly raw: readonly string[];
+}
+/** What a substitution leaves in a word's FOLDED spelling: a marker no argv word can spell, so a consumer that
+ *  judges words sees "this word carries text the shell computes" rather than the computing text itself. */
+export declare const SUBSTITUTION_PLACEHOLDER = " subst";
+/** Shell control words that stand BEFORE a command: transparent for the boundary walk (the command behind them is
+ *  judged), and a position after which bash still accepts an assignment word. */
+export declare const SHELL_CONTROL_PREFIXES: ReadonlySet<string>;
+export type QuoteOpen = '"' | "'" | undefined;
+/**
+ * Does the `$` at `at` OPEN a quote form (`$'…'` / `$"…"`)? ONE question, asked by every walker that has to
+ * answer it. Escaped means an ODD run of backslashes in front of it: `\$'y'` is a literal `$`, while `x\\$'y'`
+ * is a literal backslash followed by a real ANSI-C quote. Counting the run is what a one-character peek behind
+ * cannot do.
+ */
+export declare function dollarOpensQuote(text: string, at: number): boolean;
+/** The `'` that CLOSES the ANSI-C quote opened at `open`, or `undefined` when none does. `\'` does not close
+ *  one — the single place a quote region honours a backslash. */
+export declare function ansiCQuoteClose(source: string, open: number): number | undefined;
+/**
+ * Which QUOTE holds each character of `s`, by the same pairing rule the lexer walks with, and the boolean view of
+ * it. The pairing quote characters belong to the region they bound. `balanced` is false when a region is still
+ * open at the end of the string; callers must then NOT use the mask. This models bash only for the residual
+ * character space the strict faces operate in, where backslash escapes are rejected outright.
+ */
+export declare function quoteMask(s: string): {
+    openedBy: readonly QuoteOpen[];
+    quoted: readonly boolean[];
+    balanced: boolean;
+};
+/** The ONE spelling of a LITERAL leading tilde — `./~…`, the relative path it is — for every position bash does not
+ *  expand it in; a word without a leading tilde is returned as is. */
+export declare function literalTildeSpelling(word: string): string;
+/** The argv-word projection of a segment: redirections, here-documents and groups are not words the program
+ *  receives (bash removes them before exec). */
+export declare function wordsOf(segment: LexedSegment): SegmentTokens;
+/** The substitution bodies of an UNQUOTED here-document body: `$(…)` and backticks are live there, quotes are
+ *  ordinary characters, a backslash protects the next character. `undefined` when a substitution never closes. */
+export declare function substitutionsInHeredocBody(body: string): string[] | undefined;
+/** Lex a command: its segments, or the one reason bash (or this lexer) cannot delimit them. */
+export declare function lexShell(source: string, opts: LexOptions): ShellLex;
+/**
+ * The refused-reading view of {@link lexShell}: a parse failure, and any word whose value cannot be read off the
+ * text and whose reason {@link UNRESOLVED_VIEW} refuses, become the one `{ reject }` sentence a consumer's
+ * unreadable arm already takes.
+ */
+export declare function lexShellText(source: string, opts: LexOptions): LexedCommand | {
+    reject: string;
+};
+/** The constructs of this dialect the command leans on — what a POSIX `sh` would read as something else. Empty
+ *  when the command reads the same under either shell's word grammar. */
+export declare function bashOnlyConstructsOf(command: LexedCommand): readonly BashOnlyConstruct[];