approval-md 0.4.0 → 0.4.1

package/dist/src/channels/telegram.d.ts

@@ -219,10 +219,10 @@
  * process memory and nothing else: no event is appended, no message is edited,
  * and the log is not opened.
  */
-import type { ChannelBatch, ChannelDecision, ChannelHealth, ChannelRequest, DecisionOutcome, DeliveryId, RenderedRequest, TaggedField, TestableChannel } from "./contract.js";
+import type { ChannelBatch, ChannelDecision, ChannelDecisionRefusal, ChannelHealth, ChannelRequest, DecisionOutcome, DeliveryId, RenderedRequest, TaggedField, TestableChannel } from "./contract.js";
 import type { ChannelSender } from "../core/sender-identity.js";
 import { type Reaction, type ReviewVerdict } from "../core/audit.js";
-import { type PromptLayout } from "../core/prompt-layout.js";
+import { type PromptLayout, type PromptSay, type PromptStyle } from "../core/prompt-layout.js";
 export { TELEGRAM_CHAT_ENV, TELEGRAM_TOKEN_ENV, telegramChatEnvFor, telegramTokenEnvFor, } from "../core/telegram-config.js";
 /** The real Bot API. Overridden only by tests, against a local mock. */
 export declare const TELEGRAM_DEFAULT_API_BASE = "https://api.telegram.org";
@@ -486,6 +486,66 @@ export interface TelegramConfig {
      * what it rendered before the key existed.
      */
     layout?: PromptLayout;
+    /**
+     * Whether APRV-196's stale-copy fallback is on (APRV-456). Defaults to `true`,
+     * the direct-bot shape.
+     *
+     * On, a decision tap whose nonce this process is not holding falls back to
+     * its action reference, and is carried to the gate when this process holds
+     * that action open. The bound that makes that safe is that only the bot token
+     * can put a button in front of the approver, so any button carrying a live
+     * reference was put there by some process of this gate.
+     *
+     * Off, that tap is refused `nonce-not-issued` before the gate is called and
+     * never reaches the decision handler; at most one `audit.decision_refused` is
+     * written for it, through {@link TelegramChannel.onRefusedDecision}. The verb
+     * turns it off when the channel runs through a relay (an `--api-base` other
+     * than the Bot API), where anyone holding the relay's token can send the
+     * approver a card with forged text and a real action's reference, and when
+     * the operator passes `--no-stale-copy`. It is launch configuration and
+     * nothing else: no policy key and nothing in an update can set it.
+     */
+    staleCopy?: boolean;
+    /**
+     * Which layout a prompt is drawn in (APRV-489), from
+     * `channels.telegram.prompt.style`. Passed in by the verb, which has already
+     * loaded the policy, for {@link TelegramConfig.layout}'s reason. Defaults to
+     * `technical`, so a channel constructed without one sends exactly what it
+     * sent before the key existed.
+     */
+    promptStyle?: PromptStyle;
+    /**
+     * The operator's plain-words declarations per class (APRV-489), from
+     * `channels.telegram.prompt.say`. Read only under `promptStyle: minimal`.
+     */
+    say?: PromptSay;
+    /**
+     * Where the style and the `say` map come from FOR EACH DELIVERY (fix round
+     * 2, S4). The verb passes a function that reads the policy file the tagger
+     * reads, so a re-attested style or `say` takes effect on the next card
+     * without a restart, exactly as a re-attested class rule does. When absent,
+     * {@link TelegramConfig.promptStyle} and {@link TelegramConfig.say} are used.
+     * A resolver that throws means `technical`.
+     */
+    promptFor?: () => {
+        style: PromptStyle;
+        say: PromptSay;
+        fallback?: string;
+    };
+}
+/**
+ * A decision tap the channel refused on its own, before any handler ran
+ * (APRV-456), handed to {@link TelegramChannel.onRefusedDecision} so the
+ * runtime can record that a human's attention was spent.
+ *
+ * `decision.action_key` and `decision.deliveryId` come from the delivery THIS
+ * process holds open for the reference the bytes carried, never from the bytes
+ * themselves; a tap whose reference names nothing open here produces no
+ * {@link TelegramRefusedDecision} at all.
+ */
+export interface TelegramRefusedDecision {
+    decision: ChannelDecision;
+    refusal: ChannelDecisionRefusal;
 }
 /**
  * Why a callback was ignored.
@@ -542,6 +602,14 @@ export interface TelegramStats {
      * restart is costing the approver a wrong tap.
      */
     staleCopyDecisions: number;
+    /**
+     * Taps refused `nonce-not-issued` because the stale-copy fallback is off
+     * (APRV-456): a decision button whose nonce this process is not holding, on
+     * a relayed channel or one started with `--no-stale-copy`. Counted whether or
+     * not a record was written, because a rising number here on a relayed gate
+     * is either restarts or somebody putting cards in front of the approver.
+     */
+    staleCopyRefusals: number;
     /**
      * Bot commands handed to the runtime's command handler (APRV-216). Never a
      * decision and never a log event: a command reorders what this process shows
@@ -694,10 +762,21 @@ export interface TelegramRendering {
  * attached one. Naming the subset as a type is what lets {@link reviewRow} and
  * {@link telegramRow} share one implementation of those five without either
  * side casting: a card supplies exactly these fields, and the compiler refuses
- * a card that reaches for `budgets`, `fullPayload`, or anything else that only
- * a pending question has.
+ * a card that reaches for `budgets`, `ttl_remaining_ms`, or anything else that
+ * only a pending question has.
+ *
+ * Since APRV-480 a card also carries `fullPayload`, the bytes the sampled
+ * execution bound to, and `payload_hash`, the binding the log recorded for them.
+ * Under supervised-retro a review counts as the individual approval nobody gave
+ * before the action ran, so the reviewer has to be able to read what was
+ * published; a uuid beside the agent's own summary of what it did is the agent
+ * describing its own homework. `fullPayload` is computed the way a prompt's is
+ * (hash-checked against the binding before anything renders it) and is `null`
+ * when nobody holds the bytes; `payload_hash` is absent only when the execution
+ * recorded no binding at all. Which of the two a card SHOWS is
+ * {@link reviewPayloadView}'s decision, and the card says which.
  */
-export type ReviewCardFields = Pick<ChannelRequest, "action_key" | "class" | "task" | "summary"> & Partial<Pick<ChannelRequest, "command_breakdown" | "gloss">>;
+export type ReviewCardFields = Pick<ChannelRequest, "action_key" | "class" | "task" | "summary" | "fullPayload"> & Partial<Pick<ChannelRequest, "command_breakdown" | "gloss" | "payload_hash">>;
 /** The rows a review card renders, in the order it renders them (APRV-299). */
 export declare const REVIEW_CARD_ROWS: readonly ["class", "command_breakdown", "task", "summary", "gloss"];
 export type ReviewCardRow = (typeof REVIEW_CARD_ROWS)[number];
@@ -726,6 +805,40 @@ export type ReviewCardRow = (typeof REVIEW_CARD_ROWS)[number];
  * computed heading.
  */
 export declare function renderTelegram(request: ChannelRequest, heading?: string, layout?: PromptLayout): TelegramRendering;
+/**
+ * The settle edit of a minimal card (APRV-489): the outcome, the card's
+ * headline, the detail lines, and the collapsed block WHOLE.
+ *
+ * The edit replaces the only message that holds the canonical rendering, so
+ * the rendering is never what gives way to fit: the runtime's own detail lines
+ * are shortened instead, with a marker, and the outcome headline always stays.
+ * The card was at most 3800 characters with its quote box and
+ * deadline line, which the edit drops, so headline plus collapsed block always
+ * fit under {@link TELEGRAM_SETTLE_BUDGET} (the card budget is `MINIMAL_MESSAGE_BUDGET` in `telegram-minimal.ts`).
+ */
+export declare function minimalSettleText(outcome: string, detail: string[], card: {
+    headline: string;
+    details: string;
+}): string;
+/**
+ * The settle edit of last resort (fix round 2, S3): sent when Telegram refused
+ * the full settle edit of a minimal card, so a decided card never keeps looking
+ * undecided. The outcome, the request's key, the first detail line (who, when,
+ * which record) cut to fit, and where the rest is. Always under 1000 units.
+ */
+export declare function shortSettleText(outcome: string, actionKey: string, detail: string[]): string;
+/**
+ * Whether a Bot API failure is a refusal of THIS message rather than a passing
+ * failure (fix round 2, S2): any 4xx but 429. A 429, a 5xx and a transport
+ * failure are retried by the dispatch cycle as before; a refusal never will
+ * succeed with the same text, so the minimal card gives way to the technical one.
+ */
+export declare function isMessageRefusal(cause: unknown): boolean;
+/**
+ * The longest settle edit of a minimal card, in characters of HTML: under
+ * Telegram's 4096 with room for a relay's `Agent: <name>` line.
+ */
+export declare const TELEGRAM_SETTLE_BUDGET = 3990;
 /**
  * Split `text` so every chunk survives HTML escaping inside the message limit.
  *
@@ -1017,6 +1130,13 @@ export declare const TELEGRAM_REVIEW_DENIED = "\u2717 REVIEWED \u2014 DENIED";
  * been recorded.
  */
 export declare const TELEGRAM_REVIEW_ARMED = "DENY ARMED \u2014 nothing is recorded yet";
+/**
+ * The headline a card wears while a grade is held and no verdict has been
+ * given (APRV-482). A grade is not a verdict: tapping one with nothing armed
+ * records nothing, and the card keeps the grade so the OK or the Deny that
+ * follows records it.
+ */
+export declare function telegramReviewGradeHeld(reaction: Reaction): string;
 /**
  * What a review tap's single answer says (APRV-302).
  *
@@ -1032,8 +1152,25 @@ export declare const TELEGRAM_REVIEW_ARMED = "DENY ARMED \u2014 nothing is recor
 export declare const TELEGRAM_REVIEW_ACK = "Heard \u2014 recording your review. The card will say what the log recorded.";
 /** The toast a first Deny tap gets: it says plainly that nothing was written. */
 export declare const TELEGRAM_REVIEW_ARM_TOAST = "Deny armed \u2014 nothing recorded. Tap Deny again to record it, or a reaction to record it with a grade.";
+/**
+ * The card line and toast for a tap that would finish another account's
+ * half-finished review (PR #614 refutation F3): an armed Deny or a held grade
+ * belongs to the account that tapped it, and nothing is recorded. A held grade
+ * is replaced by the tapper's own grade (a grade finishes nothing), which the
+ * line says (PR #614 recheck NF-1, minor). Under 200 characters, the Bot API's
+ * limit for a callback answer.
+ */
+export declare const TELEGRAM_REVIEW_OTHER_SENDER = "Another account's unfinished review (armed Deny or held grade) is on this card. Nothing was recorded. Tap your own grade to replace a held one; an armed Deny is theirs to finish.";
 /** The toast a reaction that needs the human's own words gets. */
 export declare const TELEGRAM_REVIEW_NOTE_TOAST = "Heard \u2014 reply to the prompt with why. Nothing is recorded until it arrives.";
+/**
+ * The card line for a note prompt that could not be sent (APRV-492). The toast
+ * went out before the send and told the human to reply to a prompt, so the
+ * card says the prompt is not coming and how to be asked again: a grade tap is
+ * what the relay licenses a prompt for. With Deny armed the grade alone asks;
+ * otherwise the grade is held and OK asks.
+ */
+export declare function telegramReviewNoteUnasked(verdict: ReviewVerdict): string;
 /**
  * What the ForceReply prompt asks for.
  *
@@ -1057,7 +1194,14 @@ export declare function reviewNotePromptLines(reaction: Reaction, verdict: Revie
 export interface ReviewTap {
     /** `seq` of the `audit.sampled` record this card was drawn for. */
     sampleSeq: number;
-    verdict: ReviewVerdict;
+    /**
+     * The verdict the taps added up to, or absent when the human gave none
+     * (APRV-482): a grade tapped with nothing armed. The channel still hands that
+     * tap to the runtime, which refuses it `verdict-required`, so the refusal a
+     * reviewer reads is the core's own and no channel decides which gestures are
+     * approvals.
+     */
+    verdict?: ReviewVerdict;
     /** The grade, when the human gave one. Absent means absent. */
     reaction?: Reaction;
     /** The human's words, when a note prompt collected any. */
@@ -1074,6 +1218,14 @@ export interface ReviewTap {
      * policy, refuses an account it does not name, and records the one it does.
      */
     sender?: ChannelSender;
+    /**
+     * The payload binding this card showed WHOLE (APRV-481), present only when
+     * {@link reviewPayloadView} put the bytes on the screen. Set by the channel
+     * from the card it is holding, never from anything the network sent; the
+     * runtime checks it against the log before recording it as the review's
+     * `payload_hash`.
+     */
+    payloadHash?: string;
 }
 /** What the runtime did with a review tap, as it reports it back. */
 export interface ReviewTapResponse {
@@ -1085,6 +1237,15 @@ export interface ReviewTapResponse {
     detail: string[];
     /** The toast, which Telegram caps at a short sentence. */
     toast: string;
+    /**
+     * The refusal code, when the runtime refused (PR #614 refutation N6/F3).
+     * The card holds a lone grade only when this is `verdict-required`: the
+     * runtime judges the verdict after the sender and the roster, so that code
+     * says the tapper may review and lacks only the verdict. A grade refused for
+     * anything else (an unmapped sender, a reviewer off the roster) is not held,
+     * so it cannot block the next account's tap.
+     */
+    code?: string;
 }
 export type ReviewTapHandler = (tap: ReviewTap) => ReviewTapResponse | Promise<ReviewTapResponse>;
 /**
@@ -1130,6 +1291,22 @@ export interface ReviewCardState {
      * whose next Deny tap arms again.
      */
     denyArmed: boolean;
+    /**
+     * A grade tapped before any verdict (APRV-482), held so the OK or the second
+     * Deny that follows records it. **Process memory**, like the arming: it
+     * appends nothing, the card states it, and losing it to a restart costs a tap.
+     */
+    heldReaction: Reaction | null;
+    /**
+     * Who armed Deny and who holds the grade, as the transport attributed the tap
+     * (PR #614 refutation F3): the sender's id, or `null` for a tap that carried
+     * none. A held grade or an armed Deny is one person's half-finished review,
+     * so it rides only on that person's next verdict tap; another account's tap
+     * is refused on the card rather than recording someone else's grade or
+     * denial under its own name. Process memory, cleared with the state it owns.
+     */
+    armedBy: string | null;
+    heldBy: string | null;
     /**
      * The outcome, once the runtime has recorded one. Written only from the
      * handler's answer, never inferred here.
@@ -1198,6 +1375,105 @@ export declare function parseReviewCallback(data: unknown): {
     nonce: string;
     choice: ReviewChoice;
 } | null;
+/**
+ * How much payload, in ESCAPED characters, a review card carries whole
+ * (APRV-480).
+ *
+ * A card is one message edited in place, so it cannot spill the payload over
+ * several messages the way a prompt does: the edit that settles it replaces one
+ * message, and a second message holding the rest of the bytes would outlive the
+ * card it belonged to. So the bytes are shown whole or not at all. Never cut:
+ * a review that recorded a payload hash over bytes the reviewer saw half of
+ * would claim more than they read. This is the CEILING; the budget a given
+ * card gets is {@link reviewPayloadBudget}, which is this or the headroom the
+ * card's own rows leave under {@link TELEGRAM_MAX_MESSAGE_CHARS}, whichever is
+ * smaller (PR #614 refutation F4).
+ */
+export declare const REVIEW_PAYLOAD_BUDGET = 2000;
+/**
+ * The longest agent-written summary a review card shows, in characters (PR
+ * #614 refutation F4). The summary is the requesting party's own claim and its
+ * schema sets no length, so before this cap an agent could write a summary
+ * that pushed the card past Telegram's limit, which failed the send and held
+ * the review queue. Longer text is cut with a marker saying how much is not
+ * shown; the registration record keeps it whole.
+ */
+export declare const REVIEW_SUMMARY_MAX = 400;
+/**
+ * The most characters a review card's notice region (a refusal, or the arming
+ * line) shows, all its lines together (PR #614 refutation F4). Each line was
+ * already cut at {@link REVIEW_NOTICE_MAX}; the region had no total, so a
+ * refusal with several long lines could take the card over the limit and make
+ * the redraw that carries it fail. The whole refusal is on the listener's
+ * stderr.
+ */
+export declare const REVIEW_NOTICE_REGION_MAX = 600;
+/**
+ * The visible length of HTML this channel wrote: tags removed and each entity
+ * {@link escapeHtml} produces counted as the one character it stands for.
+ * Telegram measures its limit after entity parsing, so this is the number the
+ * limit applies to.
+ */
+export declare function telegramVisibleLength(html: string): number;
+/**
+ * The longest payload text, in characters, a review card will even try to
+ * render (APRV-480 refutation: review-delivery resource cap).
+ *
+ * Supervised payloads carry no size cap of their own (`PROPOSE_PAYLOAD_MAX_BYTES`
+ * binds proposals only), and the party under review writes them. Without this
+ * bound every render of a card, every redraw after a tap, and every tap's
+ * {@link reviewPayloadView} would run the canonical renderer and HTML escaping
+ * over the whole payload only to conclude "too long", so an agent could make
+ * each review gesture cost work proportional to bytes it chose. Text past this
+ * length is `too-long` without being rendered at all; the card builder
+ * (`cli/audit-card.ts`) keeps no more than this much text in the card it holds.
+ * Eight times the card budget, because a canonical rendering is never that much
+ * shorter than the JSON it renders, and erring here only ever shows the hash.
+ */
+export declare const REVIEW_RENDER_INPUT_MAX: number;
+/** The heading over a payload the card shows whole (APRV-480). */
+export declare const TELEGRAM_REVIEW_PAYLOAD_BYTES = "PAYLOAD \u2014 the bytes that ran, shown whole; this review covers them";
+/** The heading over a payload the card names by hash only (APRV-480). */
+export declare const TELEGRAM_REVIEW_PAYLOAD_HASH_ONLY = "PAYLOAD \u2014 NOT SHOWN, hash only; this review does not cover the bytes";
+/** The heading on a card whose execution recorded no payload binding (APRV-480). */
+export declare const TELEGRAM_REVIEW_PAYLOAD_NONE = "PAYLOAD \u2014 none recorded; the execution bound to no payload hash";
+/**
+ * What a review card shows of the payload, decided once from the card alone
+ * (APRV-480).
+ *
+ * - `bytes`: the canonical rendering, whole. Only this case lets a review
+ *   record a payload hash (APRV-481), because only here did the reviewer read
+ *   the bytes the hash names.
+ * - `hash`: the binding, and the reason the bytes are not on the card: nobody
+ *   holds them (`unavailable`), or they are longer than one card carries
+ *   (`too-long`). The card says so in its heading.
+ * - `none`: the execution recorded no binding, so there is nothing to show and
+ *   nothing to name.
+ *
+ * Pure and deterministic over the card, so the rendering and the tap that
+ * follows it can never disagree about which case was on the screen.
+ */
+export type ReviewPayloadView = {
+    kind: "bytes";
+    hash: string;
+    text: string;
+} | {
+    kind: "hash";
+    hash: string;
+    reason: "unavailable" | "too-long";
+} | {
+    kind: "none";
+};
+export declare function reviewPayloadView(card: ReviewCard): ReviewPayloadView;
+/**
+ * How many escaped characters of payload this card can show whole (PR #614
+ * refutation F4): {@link REVIEW_PAYLOAD_BUDGET}, or the room the card's own
+ * rows leave under {@link TELEGRAM_MAX_MESSAGE_CHARS} after the longest heading,
+ * the payload heading and the largest notice a tap can add, whichever is
+ * smaller. Pure over the card, so the view a card is drawn with and the view a
+ * tap records are the same view.
+ */
+export declare function reviewPayloadBudget(card: ReviewCard): number;
 /**
  * The card's message: the rows, whatever notice the last tap produced, and the
  * keyboard.
@@ -1210,13 +1486,15 @@ export declare function parseReviewCallback(data: unknown): {
  * every card said the same thing to a reader who had already read them once, and
  * pushed the rows a review is actually about off the first screen.
  *
- * Pure. Two things it deliberately does NOT carry, and both are the same rule
- * read twice: no payload region, and no approve button. SPEC.md §10.3 requires
- * the canonical rendering in front of an approver before a DECISION is
- * collected, and this collects none — the action ran, the review says only what
- * a person thought of it, and a card that offered an approve would be
- * presenting a settled fact as a live authorization. A sample is never
- * delivered as an approval request and never accepts a token.
+ * Pure. It carries no approve button: the action ran, and a card that offered
+ * an approve would be presenting a settled fact as a live authorization. A
+ * sample is never delivered as an approval request and never accepts a token.
+ *
+ * It DOES carry a payload region since APRV-480, between the computed rows and
+ * the claimed ones, exactly where a prompt puts its own. Under supervised-retro
+ * the review is the individual approval, so the reviewer reads the bytes that
+ * ran, or is told plainly that the card shows only their hash and why
+ * ({@link reviewPayloadView}). The heading says which, every time.
  */
 export declare function renderReviewCard(state: ReviewCardState): {
     text: string;
@@ -1239,6 +1517,13 @@ export declare class TelegramApiError extends Error {
      * JSON, or carried no description.
      */
     readonly description: string | null;
+    /**
+     * The Bot API's `parameters.retry_after`, in seconds, when the failure
+     * carried one (PR #614 recheck NF-2). Telegram sends it with 429 "Too Many
+     * Requests" and means it: a send before it elapses is refused again.
+     * `null` when the body named none.
+     */
+    readonly retryAfterSeconds: number | null;
     constructor(message: string, method: string, 
     /**
      * The HTTP status, when the failure was an HTTP one. `null` for a transport
@@ -1251,8 +1536,32 @@ export declare class TelegramApiError extends Error {
      * error body carried one. `null` when the body was absent, unreadable, not
      * JSON, or carried no description.
      */
-    description?: string | null);
+    description?: string | null, 
+    /**
+     * The Bot API's `parameters.retry_after`, in seconds, when the failure
+     * carried one (PR #614 recheck NF-2). Telegram sends it with 429 "Too Many
+     * Requests" and means it: a send before it elapses is refused again.
+     * `null` when the body named none.
+     */
+    retryAfterSeconds?: number | null);
 }
+/**
+ * Whether a failed send is the Bot API refusing the message itself, so that
+ * sending the same message again can only fail again (PR #614 recheck NF-2).
+ *
+ * Only an HTTP 400 whose description matches
+ * {@link TELEGRAM_DETERMINISTIC_SEND_REFUSALS} qualifies. Anything else, an
+ * error that is not a {@link TelegramApiError} included, is treated as
+ * transient, which is the direction that keeps a card in front of the
+ * approver: a transient failure misread as deterministic hides a sample from
+ * the phone, and the converse costs a bounded number of retries.
+ */
+export declare function isDeterministicSendRefusal(cause: unknown): boolean;
+/**
+ * The wait, in milliseconds, a failed call's `retry_after` asks for, or `null`
+ * when it named none (PR #614 recheck NF-2).
+ */
+export declare function retryAfterMsOf(cause: unknown): number | null;
 /**
  * Whether a failed call is the Bot API saying an edit changed nothing
  * (APRV-277).
@@ -1302,6 +1611,17 @@ export interface TelegramPollResult {
         tap: ReviewTap;
         ok: boolean;
     }[];
+    /**
+     * Decision taps the channel itself refused before any handler ran (APRV-456),
+     * in order. `action_key` is the action this process holds open for the
+     * reference the tap carried, or `null` when it holds nothing for it; only a
+     * non-null one can have produced an `audit.decision_refused`.
+     */
+    refused: {
+        code: ChannelDecisionRefusal["code"];
+        action_key: string | null;
+        detail: string;
+    }[];
 }
 /**
  * How updates reach this channel (APRV-424).
@@ -1414,6 +1734,12 @@ export declare class TelegramChannel implements TestableChannel {
     private readonly describeAction;
     /** The policy's row layout for this channel (APRV-218). Read-only, and pure input to the renderer. */
     private readonly layout;
+    /** The policy's prompt style for this channel (APRV-489). */
+    private readonly promptStyle;
+    /** The policy's `say` declarations (APRV-489). Pure input to the minimal renderer. */
+    private readonly say;
+    /** The per-delivery resolver (fix round 2, S4), or null for the fixed values above. */
+    private readonly promptFor;
     /** When {@link sweep} last ran, so the poll loop can call it every cycle. */
     private lastSweepMs;
     /**
@@ -1423,6 +1749,25 @@ export declare class TelegramChannel implements TestableChannel {
      */
     private ack;
     private handler;
+    /**
+     * APRV-196's stale-copy fallback, on or off (APRV-456). Fixed at
+     * construction from {@link TelegramConfig.staleCopy}; nothing an update
+     * carries can change it.
+     */
+    private readonly staleCopy;
+    /**
+     * Where a `nonce-not-issued` refusal is recorded (APRV-456). The runtime's,
+     * like every other handler here; absent, the refusal still happens and only
+     * the record is missing.
+     */
+    private refusedDecisionHandler;
+    /**
+     * Nonces already refused `nonce-not-issued` (APRV-456), oldest first, capped
+     * at {@link TELEGRAM_REFUSED_NONCE_CAP}. A redelivered or replayed tap on the
+     * same button is refused again with the same toast and records nothing, so
+     * one button costs the log at most one record.
+     */
+    private readonly unissuedRefused;
     /**
      * What to do with a bot command (APRV-216). Absent unless the runtime asked
      * for commands, and its absence is what keeps `message` out of
@@ -1527,6 +1872,21 @@ export declare class TelegramChannel implements TestableChannel {
     private readonly counters;
     constructor(config: TelegramConfig);
     onDecision(handler: (decision: ChannelDecision) => DecisionOutcome): void;
+    /**
+     * Register where a tap this channel refused on its own is recorded
+     * (APRV-456).
+     *
+     * Separate from {@link onDecision} on purpose: that handler's job is to call
+     * the gate, and a `nonce-not-issued` tap must never reach the gate. The
+     * runtime wires this to an audit-tier append that grants nothing.
+     */
+    onRefusedDecision(handler: (refused: TelegramRefusedDecision) => void): void;
+    /**
+     * Whether APRV-196's stale-copy fallback is on (APRV-456). Read by the
+     * listener for the restart banner, which must not promise that earlier
+     * copies still decide when they do not.
+     */
+    staleCopyEnabled(): boolean;
     /**
      * Register what to do with a checkpoint tap (APRV-257).
      *
@@ -1569,8 +1929,9 @@ export declare class TelegramChannel implements TestableChannel {
      * A unit like a checkpoint prompt: one thing to read, never grouped into a
      * digest, and never delivered through {@link notify} — a digest is a set of
      * similar pending REQUESTS decided together, and a sample is neither pending
-     * nor a request. It sends ONE message: no payload region, and a keyboard
-     * whose six buttons collect a verdict and a grade and mint nothing.
+     * nor a request. It sends ONE message: the rows, the payload whole or by hash
+     * (APRV-480, never split across messages), and a keyboard whose six buttons
+     * collect a verdict and a grade and mint nothing.
      *
      * Refuses when no handler is registered, rather than sending a dead button.
      */
@@ -1666,6 +2027,28 @@ export declare class TelegramChannel implements TestableChannel {
      */
     private sendPrompt;
     private deliverOne;
+    /**
+     * Send `request` as ONE minimal card (APRV-489), or report why it was not.
+     *
+     * The card is drawn from the same `renderTelegram` output the technical card
+     * would send, under the same layout, so the collapsed block IS the technical
+     * card. The buttons carry the same callback data as the technical card's; only
+     * the reject label reads "Deny" (R7). Nothing is sent when the card is refused,
+     * so the caller's technical send is the only send.
+     */
+    private sendMinimal;
+    /**
+     * The style and `say` map in force for the delivery about to be drawn (fix
+     * round 2, S4): the resolver's answer when the verb gave one, else the fixed
+     * configuration. A resolver that throws is `technical`, the side that shows more.
+     */
+    private currentPrompt;
+    /**
+     * What a decision on a digest records about its layout (APRV-489): nothing
+     * under a technical policy, and the technical card with its reason under a
+     * minimal one, since a digest is always drawn technical.
+     */
+    private digestRendering;
     /**
      * Forget every nonce issued for `deliveryId`, and report the action key it
      * was issued for.
@@ -2113,9 +2496,32 @@ export declare class TelegramChannel implements TestableChannel {
      * stays open, and a fresh card is offered — and can never cost a record
      * nobody asked for.
      *
-     * A second prompt replaces the first: only one grade can be outstanding on
-     * one card, and the older prompt stops resolving so a late reply to it lands
-     * nowhere rather than recording a grade the human moved on from.
+     * Only one grade can be outstanding on one card, so a second prompt that is
+     * SENT replaces the first, and the older prompt stops resolving: a late reply
+     * to it lands nowhere rather than recording a grade the human moved on from.
+     *
+     * APRV-492, and the relay licenses one prompt per GRADE tap, so which taps
+     * get a prompt sent is not this method's choice alone. Three rules:
+     *
+     * - A tap that would ask the SAME question again (same verdict, same grade,
+     *   same account: a doubled OK or a doubled second Deny) sends nothing. The
+     *   prompt on screen already collects those words, and a second send would
+     *   be refused.
+     * - A prompt for a DIFFERENT VERDICT retires the old one BEFORE the send. A
+     *   verdict change is not a grade tap, so the relay refuses that send, and an
+     *   old prompt left live would record the verdict the human just changed. A
+     *   note may be lost this way; a wrong verdict is never recorded.
+     * - A prompt for the same verdict and a different grade follows a grade tap,
+     *   which the relay licenses, and retires the old one only once the new send
+     *   has succeeded. A send that fails anyway (the network, not the relay)
+     *   leaves the old prompt live, and a reply to it records the grade the old
+     *   prompt names in its own text, not the one the card now holds: an
+     *   accepted residual (PR #619 refutation S2).
+     *
+     * A send that fails says so on the card, because the toast already told the
+     * human to reply to a prompt: the note was not asked for, nothing was
+     * recorded, and a grade tap asks again. Then it throws, so the operator hears
+     * of it. A later prompt that is sent clears that line.
      */
     private askForNote;
     /**
@@ -2145,6 +2551,35 @@ export declare class TelegramChannel implements TestableChannel {
     private recordReview;
     /** One `editMessageText` that replaces a review card's text and its keyboard. */
     private redrawReview;
+    /**
+     * Refuse a decision tap whose nonce this process is not holding, with the
+     * stale-copy fallback off (APRV-456).
+     *
+     * What it does, in order, and what it never does:
+     *
+     * - It never calls the decision handler, so the gate is never asked. That is
+     *   the property: a button this process did not put on the screen cannot
+     *   carry a human's tap to `decide()`, whatever reference it carries.
+     * - It looks the reference up among the deliveries THIS process holds open,
+     *   and only to name the action on the audit record. A reference that names
+     *   nothing open here produces no record: there is no action key this
+     *   process could truthfully write, and inventing one from bytes that came
+     *   off the network is the self-report §11.1 invariant 4 forbids.
+     * - It hands at most one record per nonce to {@link onRefusedDecision}: a
+     *   redelivered or replayed tap on the same button is refused with the same
+     *   toast and records nothing.
+     * - It leaves the live card alone. The request stays pending, and the card
+     *   this process did send still decides it.
+     *
+     * "Not holding" covers a nonce this process never issued and one it issued
+     * and has since forgotten (an annotated card, a swept delivery, a restart).
+     * It does not try to tell them apart: a set of every nonce ever issued would
+     * reopen the hole for anyone who has seen one genuine button's bytes, because
+     * an old nonce with a new reference would pass it. The cost is that a tap on
+     * an earlier copy after a restart is refused on this shape and the approver
+     * taps the newest card, which the restart banner says.
+     */
+    private refuseUnissued;
     private ignore;
     private answer;
     /**