@sema-agent/core 5.56.0 → 5.58.0

package/dist/core/permission-rule-model.d.ts

@@ -16,15 +16,27 @@
  * write gate not covering the shell tool, stripping would turn a rule as innocuous as `Bash(ls)` into a
  * licence for `ls > ~/.ssh/authorized_keys`).
  *
- * CONNECTORS are the one construct the lane does speak for, and only in the EXACT form. `./gradlew
- * build && ./gradlew test` is one thing a person reads and approves in one glance, and the whole of it
- * is written into the rule; nothing is admitted that the rule text does not spell out end to end. The
- * PREFIX form stays single-command on both sides — as a rule BODY (`Bash(a && b:*)` is refused) and as
- * a MATCH (`Bash(npm:*)` does not admit `npm test && curl evil.example`, which is the whole reason the
- * two forms are separated here rather than sharing one matcher arm). Upstream reaches the same
- * placement through a per-segment evaluation of its full decision chain, where a segment DENY is
- * returned strictly before any whole-string allow; this lane's equivalent is that the deny/ask layer
- * (`permission-rule-org.ts`) judges every segment and runs ahead of the allow lane at the gate.
+ * CONNECTORS are the one construct the lane does speak for, in two forms. The EXACT form spells a
+ * whole chain and admits exactly it: `./gradlew build && ./gradlew test` is one thing a person reads
+ * and approves in one glance, and nothing is admitted that the rule text does not spell out end to
+ * end. The COMPOUND-PREFIX form (`Bash(cd /tmp && adb pull:*)`) widens that by ONE seam and no other:
+ * every leading segment — connectors included — is matched byte-for-byte like an exact rule, and only
+ * the FINAL segment takes appended arguments, so the rule text still reads as the concrete combination
+ * the person saw, with the last command's arguments free. A SINGLE-COMMAND prefix body stays
+ * single-command on the match side (`Bash(npm:*)` does not admit `npm test && curl evil.example`) —
+ * the matcher requires the command to read as exactly as many segments as the rule body names, which
+ * is that historical line and the compound form's own containment in one predicate. The compound-prefix
+ * rule TEXT is a registered divergence from upstream, which has no compound rule form at all: upstream
+ * reaches compound coverage through a per-segment evaluation of its full decision chain, where a
+ * segment DENY is returned strictly before any whole-string allow; this lane's equivalent is that the
+ * deny/ask layer (`permission-rule-org.ts`) judges every segment and runs ahead of the allow lane at
+ * the gate — a compound-prefix allow can therefore never outrun a deny on any segment it admits.
+ *
+ * design/375 adds upstream's OTHER half of that per-segment evaluation on the allow side: a compound
+ * whose EVERY segment is admitted by some eligible rule is covered by the CONJUNCTION of those rules
+ * (`findAdmittingRule` answers with the coverage SET). No single rule widens: the matcher predicates
+ * above are untouched, and the set form is the decision layer's answer, fenced by the same
+ * ahead-running per-segment deny/ask layer.
  *
  * The floor is `parseLeadingCommandName` + `splitShellCompoundSegments` — the one simple-command parser
  * and the one segmentation, both already shared with the read-only classifier, the reversibility probe,
@@ -92,7 +104,9 @@ export interface RuleAdd {
  * Organization rules have the opposite polarity (deny/ask only) and never enter this type.
  */
 export interface PersistedAllowRule {
-    /** Canonical rule text: `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). */
+    /** Canonical rule text: `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). A prefix body
+     *  may itself be a connector chain (`Bash(cd /tmp && adb pull:*)`) — see the module note on
+     *  connectors for what such a rule reaches. */
     rule: string;
     tool: PersistedRuleTool;
     match: PersistedRuleMatch;
@@ -145,6 +159,16 @@ export declare const MAX_RULE_TEXT_CHARS = 512;
  * `python manage.py migrate:*` (which an import reports as skipped rather than dropping silently), and
  * an EXACT rule naming a whole interpreter command line stays legal, since it authorizes one command.
  *
+ * TWO READERS, and they consult this table with DIFFERENT questions — do not read either as the other.
+ * {@link parseAllowRuleText} asks "is this rule TEXT's own head a row?" and compares the basename as
+ * SPELLED, so an alias spelling (`SSH host:*`, `ssh.exe host:*`) is a different name to it and enters
+ * the store like any other rule. {@link genericPrefixBody} asks "should the engine PROPOSE a body with
+ * this head?" and normalizes first ({@link screenedHeadName}: case, trailing periods, executable
+ * suffix), because a proposal is the engine's own act and must not hand a person an alias of a row.
+ * The asymmetry is deliberate — normalizing at the validator would also refuse rule texts already
+ * stored, imported or hand-authored — and it is the reason the residual paragraph below is about this
+ * table's reach rather than about either reader.
+ *
  * TWO groups, and the distinction matters when the table is next edited:
  *  · LANGUAGE interpreters (`node`, `python`, `ruby`, …) — the argument IS a program. This half is
  *    wider than upstream's own set, deliberately, and is the argument the paragraph above makes.
@@ -197,50 +221,49 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  */
 export declare const SHELL_RESERVED_WORDS: ReadonlySet<string>;
 /**
- * design/185 §1 — the reviewed command/subcommand grammar the PREFIX suggestion is generated from
- * (exactly the "reviewed command/subcommand grammar" the generator's history note names as the one
- * thing that would let it produce a prefix).
- *
- * A flat set of BODIES — word sequences, each at least two words. A prefix candidate exists for a
- * command iff some body here is a word-boundary prefix of its folded form, and the LONGEST hit wins:
- * the deeper body is the narrower rule, so listing (or not listing) a deeper body is how this table
- * sets suggestion granularity per branch. No groups, no denylist, and no fallback arm: a head outside
- * the table, an unreviewed subcommand, a runtime-defined name (a git alias, a `git-<x>`/`cargo-<x>`
- * external subcommand, a gh extension, a kubectl plugin), a flag or operand in a body position and a
- * quoted token all fail the same way — by not being listed. Closure comes from positive enumeration
- * itself, never from an exclusion list racing names that only exist at runtime.
- *
- * Review criteria — every row must pass BOTH axes (the same principle as the interpreter refusal
- * above: the rule text must not read narrower than what it grants):
- *  · "runs what it is told to": a body whose use is fetching or naming a program to execute
- *    (`npm exec`, `docker run`, `kubectl exec`, `gh extension`, `git submodule foreach`, the install
- *    family) is refused — one click cannot be read as having granted arbitrary execution. Running the
- *    WORKSPACE'S OWN pinned content (`npm run`, `npm ci`, `cargo run`, `cargo test`) is inside the
- *    boundary: the scripts and lockfiles those execute are checked into the repository being worked on.
- *  · "rewrites what others execute": a body whose main use is writing configuration that changes what
- *    OTHER commands later run (`git config` — hooksPath/pager/alias; `kubectl config` —
- *    exec-credential; `npm config`/`npm set` — script-shell; `go env` — persisted GOFLAGS/GOBIN) is
- *    refused — its readable width and its real width differ by a whole composition surface.
- * Past both axes there is deliberately NO "dangerousness" axis: `git push:*` and `git rebase:*` are
- * wide but readable, and a person nodding at that text is granting exactly that.
- *
- * Residual width, stated rather than hidden (a reviewed trade, not an oversight): a prefix rule
- * admits ANY arguments after its body, and some listed bodies carry flags that name a program to
- * execute (`go build`/`go test`/`go vet -toolexec`, `git fetch --upload-pack`, `git rebase -x`,
- * `git grep -O`, `git push --receive-pack`). The axes judge a body's MAIN use, not every flag —
- * per-flag grammar is the road this module's history rejected twice, and applied consistently it
- * would empty the table. Three standing fences hold that residue: the org deny/ask layer runs ahead
- * of the rule lane and cannot be silenced by it; a mandated ask (egress/irreversibility marks,
- * shellGate:"always") is not rule-clearable either; and the narrower exact candidate — plus minting
- * no rule at all — is always on the same card.
- *
- * Maintenance: adding a row is a reviewed change — keep the per-group reasoning beside it current.
- * The integrity pins (every body ≥ 2 words, lowercase word shape, no interpreter heads, no
- * duplicates) are enforced by this module's test suite. This table and the read-only classifier's
- * allowlists are DIFFERENT instruments and must never be merged or cross-referenced: that one is a
- * machine auto-allow face whose criterion is "provably read-only"; this one is a human suggestion
- * face whose criterion is "width a person can read off the rule text". One guards against a machine
- * loosening; the other against a person being misled.
+ * design/185 §1 — the DEEPER-THAN-TWO-WORDS half of the prefix suggestion grammar.
+ *
+ * The prefix candidate itself is produced by {@link genericPrefixBody}: a general two-word rule that
+ * covers every command whose second token reads as a subcommand. This table exists for the one thing
+ * that rule cannot express — a body DEEPER than two words — so every row here makes a suggestion
+ * NARROWER than it would otherwise be, and never wider.
+ *
+ * A flat set of BODIES — word sequences, each at least THREE words. A body takes the seat iff it is a
+ * word-boundary prefix of the command's folded form, and the LONGEST hit wins; with no hit the
+ * two-word generic body is used, and with neither there is no prefix candidate at all.
+ *
+ * Review criterion, one axis, and it is a PRECISION axis rather than a safety one: list a deeper body
+ * when the two-word form names a NAMESPACE rather than an action. `gh pr`, `kubectl rollout`,
+ * `docker compose`, `git stash`, `go mod`, `git submodule` and `yarn workspaces` are families of
+ * verbs, and the verb is what a person reads as the thing they are approving. Listing a row costs
+ * nothing and narrows one family; NOT listing one is not a refusal, since the generic two-word body
+ * still fills the seat.
+ *
+ * WHAT THIS TABLE NO LONGER DOES, stated because two review axes used to live here and their removal
+ * is a WIDENING no reader should have to reconstruct. Rows were once gated on "runs what it is told
+ * to" (`docker run`, `npm exec`, `cargo install`, `gh extension`) and on "rewrites what others
+ * execute" (`git config`, `kubectl config`, `npm config`, `go env`), and a head outside the table
+ * produced NO prefix at all. Under the generic rule those bodies are produced like any other, which
+ * is upstream's own behaviour and the adjudicated form: a positive table of two-word bodies cannot
+ * cover the long tail of real CLIs, and the price of its closure was saying nothing at all for
+ * everything outside nine families — the field report that drove this change was every `adb`,
+ * `gradle` and `terraform` invocation asking forever, with an exact rule for one full command line as
+ * the only offer and no reuse the moment an argument changed.
+ *
+ * What carries that residue is therefore NOT this table, and never was — it is the three standing
+ * fences: the org deny/ask layer runs ahead of the rule lane and cannot be silenced by it; a mandated
+ * ask (egress/irreversibility marks, shellGate:"always") is not rule-clearable either; and the
+ * narrower exact candidate — plus minting no rule at all — is always on the same card. A prefix rule
+ * also still admits ANY arguments after its body and never a second command, which is the property
+ * that makes a body's width readable off its text.
+ *
+ * Maintenance: adding a row is a one-line narrowing of one family. The integrity pins (every body
+ * ≥ 3 words, lowercase word shape, no interpreter heads, no duplicates) are enforced by this module's
+ * test suite. This table and the read-only classifier's allowlists are DIFFERENT instruments and must
+ * never be merged or cross-referenced: that one is a machine auto-allow face whose criterion is
+ * "provably read-only"; this one is a human suggestion face whose criterion is "width a person can
+ * read off the rule text". One guards against a machine loosening; the other against a person being
+ * misled.
  */
 export declare const SUGGESTION_LEXICON: readonly string[];
 /**
@@ -259,6 +282,16 @@ export declare const SUGGESTION_LEXICON: readonly string[];
  * through, so an ordinary rule text reads normally. The result is length-bounded.
  */
 export declare function escapeForDisclosure(value: unknown): string;
+/**
+ * Does this text carry a character of the class {@link escapeForDisclosure} exists for — the class
+ * {@link CONTROL_CHARS_RE} names? Asked by a caller that must REFUSE such a value rather than render
+ * it: the two answers to "these bytes cannot honestly ride a display line" are escape it or do not
+ * take it, and a call site with nothing to display picks the second. Reads the same source regex as
+ * the escape pass, so the screen and the escape cannot drift into two character classes.
+ *
+ * Not part of the package's public surface — an internal screen for lane entry points.
+ */
+export declare function hasUnrenderableCharacters(text: string): boolean;
 /**
  * Parse one rule text into its canonical shape, or refuse it with a reason.
  *
@@ -288,12 +321,15 @@ export declare function formatAllowRuleText(command: string, match: PersistedRul
  * caller can match a command this lane has not read. Returns false for every redirection, substitution,
  * subshell, backgrounded or escaped form.
  *
- * **A PREFIX rule never admits a compound.** This is the single load-bearing line of the connector
- * widening, and it is checked on the MATCH side rather than left to the mint side: `Bash(npm:*)` is an
- * ordinary, legitimately mintable rule, and if the "does this command start with `npm `" arm were
- * allowed to see a compound at all, that rule would admit `npm test && curl evil.example` — one stored
- * yes to a build command turned into a standing yes to whatever is chained behind it. An EXACT rule has
- * no such reach by construction: it admits one string, the one it spells.
+ * **A prefix rule reaches past its body only inside its FINAL segment.** This is the single
+ * load-bearing line of the connector widening, and it is checked on the MATCH side rather than left to
+ * the mint side: the command must read as exactly as many segments as the rule's own body. For the
+ * single-command body that is the historical contract verbatim — `Bash(npm:*)` is an ordinary,
+ * legitimately mintable rule, and if the "does this command start with `npm `" arm were allowed to see
+ * a compound at all, that rule would admit `npm test && curl evil.example` — one stored yes to a build
+ * command turned into a standing yes to whatever is chained behind it. For a compound-prefix body the
+ * same count equality is the containment: `Bash(a && b:*)` admits `a && b x`, never `a && b x && c`.
+ * An EXACT rule has no such reach by construction: it admits one string, the one it spells.
  */
 export declare function ruleAdmitsCommand(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
 /**
@@ -337,50 +373,196 @@ export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined
  *  when tombstones are applied, so a rule with an empty `adds` is a rule that no longer exists. */
 export declare function isRuleLive(rule: PersistedAllowRule): boolean;
 /**
- * Find the rule that admits this command for a task in `cwd`, or `undefined`.
+ * design/375 §5.1 — MAY this rule speak about this call's CONTEXT? Tool identity plus scope coverage,
+ * and nothing about the rule's liveness: the CONTEXT question is the half a not-yet-persisted rule (a
+ * card's proposed candidate, which has no add dots yet) can already answer.
  *
- * Order is defined only for reporting (the first match wins and its text is what the decision names);
- * no rule is stronger than another — they are all the same one answer, "the person already said yes to
- * this".
+ * The tool conjunct is not decoration: more than one tool takes a shell command string, and matching on
+ * the command alone would let an approval given on one surface resolve a call on another. The scope
+ * conjunct is the project fence — project A's approval is not project B's, and a project rule with no
+ * cwd to compare against covers nothing (fail-closed, {@link scopeCoversCwd}).
+ *
+ * `scope` rides beside the rule rather than inside it for the PROPOSED half's sake: a
+ * {@link ParsedAllowRule} carries no scope, so a proposal is judged against the scope it would LAND in.
+ */
+export declare function eligibleContext(rule: {
+    tool: string;
+    scope: RuleScope;
+}, call: {
+    tool: string;
+    cwd: string | undefined;
+}): boolean;
+/**
+ * design/375 §5.1 — MAY this PERSISTED rule participate in admitting this call at all? The liveness
+ * layer on top of {@link eligibleContext}: a tombstoned rule (zero surviving adds) is a rule that no
+ * longer exists and must not count as coverage anywhere.
+ *
+ * THE single eligibility predicate for every consumer that reads the persisted store — the gate's
+ * conjunction arm and its coverage-set selection here, the suggestion face's coverage judgement and the
+ * consent prepare's ({@link segmentCoverageOf} is the shared instrument). One predicate, so a rule that
+ * one consumer refuses cannot be a rule another counts: the historically inlined trio of checks
+ * (live / tool / scope) is this function, verbatim.
+ */
+export declare function eligiblePersisted(rule: PersistedAllowRule, call: {
+    tool: string;
+    cwd: string | undefined;
+}): boolean;
+/**
+ * Find the rules that admit this command for a task in `cwd`, or `undefined`.
+ *
+ * THE ANSWER IS A COVERAGE SET (design/375 §5.1, the upstream per-segment form): a single rule that
+ * admits the whole command is a one-element set — the historical arm, table order preserved verbatim —
+ * and a COMPOUND whose every segment is admitted by some eligible rule is covered by the CONJUNCTION of
+ * those rules, returned as the set that covered it. The judging ladder, in order:
+ *  1. the fail-closed floor (a shape the lane cannot read matches nothing), evaluated once;
+ *  2. the single-rule arm — whole-string exact, single/compound-prefix — exactly the historical loop:
+ *     first table-order match wins and is what the decision names. A single rule naming the command is
+ *     found BEFORE any conjunction: reporting one rule is narrower than reporting a set;
+ *  3. the conjunction arm, compounds only: every segment must be admitted by some eligible rule under
+ *     the MATCH reading (the allow side's own under-approximating instrument — never the deny side's
+ *     wider PROGRAM_RUNS reading). Per segment the FIRST table-order admitting rule is selected, and
+ *     the coverage set is those selections in segment order, de-duplicated — the same command against
+ *     the same rule table always names the same set (reporting-order determinism, the historical
+ *     "order is defined only for reporting" contract extended to sets).
+ *
+ * What the conjunction arm deliberately does NOT change: {@link ruleAdmitsCommand} itself. A
+ * single-command prefix body still never admits a chain — `Bash(npm:*)` does not admit
+ * `npm test && curl evil.example` — but the chain is now admitted when EVERY segment has a standing
+ * yes, which is the upstream decision form (per-segment allow, any-segment deny decided strictly
+ * earlier at the gate's org layer). A trailing-terminator spelling (`a && b ;`) keeps the conservative
+ * answer by construction: under the MATCH reading its tail is an empty segment the floor refuses, so
+ * the whole command is outside the lane and asks.
+ *
+ * Order is defined only for reporting (what the decision names); no rule is stronger than another —
+ * they are all the same one answer, "the person already said yes to this".
  */
 export declare function findAdmittingRule(rules: readonly PersistedAllowRule[], call: {
     tool: string;
     command: string;
     cwd: string | undefined;
-}): PersistedAllowRule | undefined;
-/** A rule the engine offers to mint, as carried on an approval card. */
-export interface RuleSuggestion {
+}): readonly PersistedAllowRule[] | undefined;
+/**
+ * design/375 §5.2 — the per-segment coverage table for `command`: which segments an eligible rule
+ * already admits, judged with the SAME split, the same MATCH reading and the same eligibility
+ * predicates as the gate's conjunction arm — one instrument, so the suggestion face and the consent
+ * prepare can never call a segment covered that the gate would ask about (or vice versa).
+ *
+ * TWO SOURCES, two predicates, and the seat labels are the contract:
+ *  · `persisted` — rules already in the store, judged {@link eligiblePersisted} ∧ admit: a tombstoned
+ *    rule, another project's rule and another tool's rule are uniformly NOT coverage;
+ *  · `proposed` — rules of the CURRENT batch that are not yet persisted (no add dots yet), judged
+ *    {@link eligibleContext} ∧ admit against the scope each would land in. Judging these with the
+ *    persisted predicate would make "this batch, once redeemed, covers the command" permanently false
+ *    — the liveness layer is the one thing a proposal legitimately lacks.
+ *
+ * Returns `undefined` for a command the lane cannot read at all (the fail-closed floor — the caller's
+ * honest answer is then "no coverage table", which every consumer must treat as all-uncovered). The
+ * reported `segment` texts are the FOLDED spellings, trimmed — display/correlation seats, never
+ * adjudication inputs.
+ */
+export declare function segmentCoverageOf(command: string, rules: {
+    persisted: readonly PersistedAllowRule[];
+    proposed?: readonly {
+        rule: ParsedAllowRule;
+        scope: RuleScope;
+    }[];
+}, call: {
+    tool: string;
+    cwd: string | undefined;
+}): readonly SegmentCoverage[] | undefined;
+/** One row of a per-segment coverage table (see {@link segmentCoverageOf}): the FOLDED, trimmed
+ *  segment text (a display/correlation seat, never adjudication input) and whether an eligible rule
+ *  already admits it. */
+export interface SegmentCoverage {
+    readonly segment: string;
+    readonly covered: boolean;
+}
+/** One member of a {@link RuleOffer} batch: a rule the engine offers to mint for ONE segment of a
+ *  compound command. `segment` is the FOLDED segment text the member was minted from — a rendering
+ *  seat, never adjudication input. */
+export interface SegmentRuleSuggestion {
     /** The canonical rule text the host would redeem. */
-    rule: string;
-    match: PersistedRuleMatch;
+    readonly rule: string;
+    readonly match: PersistedRuleMatch;
     /** The command pattern in the rule, for a host that wants to render it without re-parsing. */
-    command: string;
+    readonly command: string;
+    /** The (folded) segment this suggestion came from. Raw post-rewrite command bytes — a substring
+     *  of the same call's `args`/`command` values riding beside it on every surface that carries
+     *  this seat — so render it with contextual escaping, exactly like those. */
+    readonly segment: string;
 }
 /**
- * The 1-2 candidates offered on an approval card for `command`.
- *
- * **Array order is a documented CONTRACT, not an implementation accident**: display order = array
- * order = narrowest first. The EXACT form (this whole command line) is always index 0 whenever
- * anything is offered at all; a broader reviewed PREFIX form — at most one — follows at index 1.
- * Selection indices and redemption tickets are index-keyed against this order (a card's
- * `selectedCandidate` and its `rt.<index>.` tickets), so consumers may rely on it.
- *
- * The prefix candidate comes ONLY from {@link SUGGESTION_LEXICON} — the longest reviewed body that is
- * a word-boundary prefix of the folded command. History, and why there is no heuristic arm: two
- * rounds of guessing produced two different wrong answers — a bare program name (`rm -f x` →
- * `Bash(rm:*)`), then an operand mistaken for a subcommand (`rm harmless.txt` →
- * `Bash(rm harmless.txt:*)`, which admits a second, unnamed target) — and both failed the same way:
- * nothing in the command TEXT distinguishes a subcommand from an operand without a per-command
- * grammar. The lexicon IS that grammar, per reviewed row; anything it does not list (a bare verb, an
- * interpreter head, an unreviewed subcommand, a runtime-defined name) yields no prefix, with no
- * fallback. Naive spacing note: `folded` keeps quoted whitespace, so splitting on single spaces can
- * shear a quoted segment — harmless in this direction, because the sheared pieces carry quote
- * characters and can never equal a bare lexicon word; every suspicious shape lands on "no prefix".
+ * design/375 §3.1 — ONE "don't ask again" option on an approval card. A CLOSED discriminated union
+ * (`kind`); consumers parse it per element, and an element whose `kind` they do not know is dropped
+ * (single-row degrade) while keeping the ORIGINAL wire index for every element they keep — selection
+ * and redemption are keyed on original indices, so a consumer that cannot preserve the mapping must
+ * suppress its persistence actions entirely (fail toward asking).
+ *
+ *  · `kind: "single"` — one rule covering the WHOLE command (the exact spelling, or a broader
+ *    reviewed prefix form for a simple command).
+ *  · `kind: "batch"` — a CONJUNCTION batch of per-segment rules for a compound command. Choosing it
+ *    is one yes to ALL of `rules` at once — there is no per-member selection inside a batch; a
+ *    consumer that wants a narrower answer picks the single offer or approves once without a rule.
+ *    `rules` has 1..5 members (the card-lane minting cap), in segment order, deduplicated by rule
+ *    text. `uncoveredSegments` is the honest surplus disclosure of the cap: judged at MINT time
+ *    against the coverage snapshot the card was drawn from ∪ this batch's FINAL (deduplicated,
+ *    capped) rules, it counts the violating segments still admitted by neither — 0 means "once this
+ *    batch is redeemed, this compound is fully covered by that snapshot's lights". It is a statement
+ *    about the minting snapshot, not a standing guarantee: a concurrent rule removal can date it.
+ *
+ * Array contract (`ruleOffers`, the durable park row, and the consent record's projection while
+ * the card is PENDING all share it): at most 2 offers; the whole-string exact single is index 0
+ * whenever present; the batch offer — at most one — is always last. It is a draw-time contract,
+ * not a settled-record invariant: confirming an EDITED candidate appends a third single offer
+ * AFTER the batch in the same write that settles the record, so a SETTLED record's projection may
+ * carry it. ADVISORY display metadata, never adjudication input, and never a
+ * rule by itself: minting is a separate act that goes through the approval-record protocol, so a
+ * surface that ignores offers entirely changes nothing about what is allowed. The authoritative
+ * render source for a card is the PREPARED record's own offers (record-is-what-you-see); the ask-time
+ * projection here may drift from it across a coverage change, and the drift direction is harmless
+ * (the record is what gets confirmed).
+ */
+export type RuleOffer = {
+    readonly kind: "single";
+    /** The canonical rule text the host would redeem. */
+    readonly rule: string;
+    readonly match: PersistedRuleMatch;
+    /** The command pattern in the rule, for a host that wants to render it without re-parsing. */
+    readonly command: string;
+} | {
+    readonly kind: "batch";
+    /** 1..5 per-segment rules, segment order, deduplicated by rule text. */
+    readonly rules: readonly SegmentRuleSuggestion[];
+    /** Mint-time honest surplus: violating segments admitted by neither the coverage snapshot nor
+     *  this batch's final rules (see the union doc above for the exact arithmetic). */
+    readonly uncoveredSegments: number;
+};
+/**
+ * The offers presented on an approval card for `command` (design/375 §5.2).
+ *
+ * **Array order is a documented CONTRACT, not an implementation accident** (see {@link RuleOffer}):
+ * the whole-string EXACT single is index 0 whenever present; a SIMPLE command may carry a broader
+ * reviewed PREFIX single after it; a COMPOUND carries at most one BATCH offer, always last.
+ * Selection indices are keyed against this order, so consumers may rely on it; redemption TICKETS
+ * are NOT — they key on the consent record's flat CANDIDATE list, and a chosen offer is redeemed
+ * via `redeemRuleBatch` (see the consent record's own doc for the two index spaces).
+ *
+ * The prefix single is the LONGEST body two sources agree to offer: {@link SUGGESTION_LEXICON}'s
+ * deeper-than-two-words rows first, and otherwise {@link genericPrefixBody}'s general two-word form
+ * (`argv[0]` + a token shaped like a subcommand). Read those two for the grammar, its adopted origin,
+ * and the operand false positive it accepts; the short version is that a bare verb (`git`), an
+ * interpreter or wrapper head (`sudo apt`, `node build.js`), a flag in second position
+ * (`git -C /repo status`) and a quoted or dotted token all still yield NO prefix. Naive spacing note:
+ * `folded` keeps quoted whitespace, so splitting on single spaces can shear a quoted segment —
+ * harmless in this direction, because the sheared pieces carry quote characters and can therefore
+ * match neither a lexicon word nor the generic subcommand shape; every suspicious form lands on
+ * "no prefix".
  *
  * Every produced candidate must survive the round trip — parse as a rule, come back as the match form
- * this seat is offering, AND admit the very command it was minted from. Enforced on BOTH seats,
- * fail-closed: a candidate that would not round-trip is silently not offered, since offering an option
- * redemption would refuse is worse than offering one fewer.
+ * its seat is offering, AND admit the very text it was minted from (the whole command for a single,
+ * its own segment for a batch member). Enforced on EVERY seat, fail-closed: a candidate that would
+ * not round-trip is silently not offered, since offering an option redemption would refuse is worse
+ * than offering one fewer.
  *
  * The FORM half of that check is not decoration. A command may end in the rule grammar's own prefix
  * marker — `rm :*` is a legal thing to type — and wrapping it as an exact rule produces the text
@@ -390,13 +572,29 @@ export interface RuleSuggestion {
  * for a lexicon command like `git status :*`, emitted twice — once mislabelled, once as the real prefix
  * candidate). The seat therefore believes the PARSER about what it got back, never its own request.
  *
- * A COMPOUND (`./gradlew build && ./gradlew test`) fills the exact seat and only that one: the offered
- * rule spells the whole chain and admits exactly it. That is the shape this seat was missing — the
- * ordinary build invocation is a connector chain, and a card that could offer nothing for it made every
- * such command a fresh question forever, with no way for an answer to accumulate.
+ * A COMPOUND (`./gradlew build && ./gradlew test`) fills the exact single — the offered rule spells
+ * the whole chain and admits exactly it — and a BATCH offer besides: every segment NOT already
+ * covered (per `ctx.coverage`) yields its own single-segment best form — a prefix when the
+ * single-command grammar grants one for that segment's tokens (the interception screens apply
+ * unchanged), otherwise the segment's exact — deduplicated by rule text in segment order and capped
+ * at FIVE (upstream's own batch cap; the overflow is disclosed via `uncoveredSegments` rather than
+ * silently truncated away). A segment whose every form the floor refuses simply contributes no
+ * member (and stays counted as uncovered — the honest gap). The COMPOUND-PREFIX candidate this seat
+ * used to mint here is deliberately NO LONGER OFFERED (design/375 §5.3): the batch takes its card
+ * position, while the compound-prefix GRAMMAR remains a fully supported rule family — the matcher,
+ * the hand-written/edited/import channels and every persisted such rule are untouched.
+ *
+ * `ctx.coverage` is the per-segment coverage table minted by the SAME store read that adjudicated
+ * the call (see {@link segmentCoverageOf} and the gate's engine-stamped seat) — positional over this
+ * function's own folded segments, belt-checked by text: a table whose length or segment texts do not
+ * line up is discarded whole, and an absent or discarded table reads as ALL-UNCOVERED (fail toward
+ * over-offering; every offered rule still passes the validator at redemption, so an over-offer widens
+ * nothing).
  *
  * Returns an empty array for anything the rule lane cannot speak for (redirections, substitutions,
  * subshells, backgrounding) — the card then simply carries no "don't ask again" option, which is the
  * honest answer.
  */
-export declare function suggestRulesForCommand(command: string): RuleSuggestion[];
+export declare function suggestRulesForCommand(command: string, ctx?: {
+    readonly coverage?: readonly SegmentCoverage[];
+}): RuleOffer[];