@xenosystem/blocks 0.2.2 → 0.4.0

package/dist/trust/index.d.ts

@@ -0,0 +1,780 @@
+import { PanelModule, PanelManifest } from '@xenosystem/panel-sdk';
+import { ReactNode } from 'react';
+
+/**
+ * The `xeno.core.consent` contract.
+ *
+ * ## Why nothing in the catalog absorbs this
+ *
+ * Consent is a **blocking, request-scoped, decision-returning** surface. The Inspector edits values
+ * that already exist; the Table shows rows that already exist; this panel exists to *await a
+ * decision that does not exist yet* and hand it back. No other archetype models "await a decision",
+ * which is why five separate implementations grew independently.
+ *
+ * ## The three rules that make it a security surface rather than a dialog
+ *
+ * 1. **A decision must be EXPLICIT.** No default-allow on timeout, dismiss, unmount or navigation.
+ *    An expiring request resolves as `deny` with `reason: 'expired'`.
+ * 2. **The queue is ordered and individually resolvable** — never collapsed into one "allow all".
+ *    Bulk approval is how consent fatigue becomes a security hole.
+ * 3. **Scope and duration are visible IN the decision**, not buried in a settings page. A user who
+ *    cannot see that they are granting "always" has not granted it.
+ *
+ * ## The fourth rule, added when the question kinds landed
+ *
+ * 4. **An answer is not a permission.** `text`, `path` and `choice` are separate KINDS with their
+ *    own results (`./elicitation`), because rule 1's safe automatic outcome — `deny` — has no
+ *    meaning for a question. Their safe automatic outcome is *no answer at all*.
+ *
+ * @module
+ */
+
+/** What is being asked for. Presentation + telemetry; never behaviour. */
+type XenoConsentKind = 'capability' | 'tool' | 'mount' | 'device' | 'credential' | 'network' | 'permission';
+/** How dangerous the grant is. Drives emphasis only — never a default. */
+type XenoConsentRisk = 'low' | 'medium' | 'high';
+/** One thing being granted. Rendered individually so a user sees what they are agreeing to. */
+interface XenoConsentScope {
+    /** Stable id. */
+    id: string;
+    /** Short label ("Read files in ~/Projects"). */
+    label: string;
+    /** Longer explanation. */
+    detail?: string;
+    /** Per-scope risk, when it differs from the request's. */
+    risk?: XenoConsentRisk;
+    /**
+     * The scope is already granted and is shown for context.
+     *
+     * A re-prompt that hides what the user already allowed makes the new ask look bigger than it is.
+     */
+    alreadyGranted?: boolean;
+}
+/** How long a decision lasts. **Always visible in the UI that produces it.** */
+type XenoConsentDuration = 'once' | 'session' | 'always';
+/** A pending request. */
+interface XenoConsentRequest {
+    /** Stable id — the correlation key for the decision. */
+    id: string;
+    /**
+     * Marks this as a PERMISSION rather than one of the question kinds in `./elicitation`.
+     *
+     * ⚠️ **Optional, and it must stay optional.** Every request ever written carries no `ask`, and a
+     * required discriminant would have invalidated all of them at once. Absent means `'permission'`,
+     * which is what this shape has always meant.
+     */
+    ask?: 'permission';
+    kind: XenoConsentKind;
+    /** The question, in the host's words. */
+    title: string;
+    /** Supporting explanation, rendered verbatim. The panel never composes consent prose. */
+    detail?: string;
+    /** Who is asking — an agent name, a plugin id, a device name. */
+    subject?: string;
+    /** What is being asked for. */
+    scopes: XenoConsentScope[];
+    risk: XenoConsentRisk;
+    /** Epoch ms after which the request auto-denies. */
+    expiresAt?: number;
+    /**
+     * Which durations the host will accept.
+     *
+     * `'forbidden'` means only `once` is offered — a host may refuse to let a high-risk grant be
+     * remembered at all, and the panel must not offer what the host will not honour.
+     */
+    remember: 'allowed' | 'forbidden';
+    /** Epoch ms the request arrived. Queue order. */
+    requestedAt: number;
+    /** Pre-formatted extra fields (a path, a fingerprint, a safety number). */
+    fields?: Record<string, string>;
+}
+/**
+ * The answer to a PERMISSION.
+ *
+ * 🔴 **Frozen shape — do not add an `answer` field here.** Text, path and choice results live in
+ * `./elicitation` as a separate type on a separate port, precisely so this one never has to carry
+ * a value with no safe default. See that module's header for the full reasoning; the one-line
+ * version is *an answer is not a permission*.
+ */
+interface XenoConsentDecision {
+    /** Echoes the request id. */
+    id: string;
+    decision: 'allow' | 'deny';
+    /** How long it lasts. Always `'once'` for a deny. */
+    scope: XenoConsentDuration;
+    /** Epoch ms the grant lapses, when the host computes one. */
+    rememberedUntil?: number;
+    /** Why, when the panel decided rather than the user. */
+    reason?: 'user' | 'expired' | 'superseded' | 'dismissed';
+    /** Scope ids the user allowed, when they answered per-scope. Absent ⇒ all of them. */
+    grantedScopeIds?: string[];
+}
+/** The panel's serialized state. **Requests are never persisted.** */
+interface ConsentPanelState {
+    /** Nothing durable — a pending decision must never survive a reload. */
+    readonly _empty?: never;
+}
+/** What the controller exposes to its view. */
+interface ConsentViewState {
+    /**
+     * The elicitation being answered — the head of the queue.
+     *
+     * ⚠️ **Widened from `XenoConsentRequest | null` when the question kinds landed.** Narrow with
+     * `isPermissionElicitation()` before reading `scopes` or `remember`. Runtime behaviour is
+     * unchanged for a host that only ever enqueues permissions: it only ever sees permissions here.
+     */
+    current: XenoElicitation | null;
+    /** Everything else waiting, in arrival order. */
+    queued: XenoElicitation[];
+    /** Total pending. */
+    pending: number;
+    /** Scope ids the user has ticked for the current request. Empty for a non-permission head. */
+    selectedScopeIds: string[];
+    /** The duration the user has chosen for the current request. `'once'` for a non-permission head. */
+    duration: XenoConsentDuration;
+    /** ms until the current request expires, or `null` when it does not. */
+    expiresInMs: number | null;
+    /**
+     * What the user has typed for a text/path/choice head. `''` for a permission.
+     *
+     * ⚠️ **A draft is not an answer.** Nothing is emitted from this field until `submit()` runs, and
+     * every path that settles a question without `submit()` discards it — which is why expiry cannot
+     * leak a half-typed value.
+     */
+    draftText: string;
+    /** The option the user has highlighted, or `null`. Highlighting is not answering. */
+    selectedOptionId: string | null;
+    /**
+     * Would `submit()` succeed right now?
+     *
+     * Drives the button's `disabled` state. Computed from the SAME predicate `submit()` enforces, so
+     * an enabled button cannot be a button that refuses — the affordance and the guard can never
+     * disagree.
+     */
+    canSubmit: boolean;
+}
+/** Durations a request permits, in escalating order. */
+declare function allowedDurations(request: XenoConsentRequest): XenoConsentDuration[];
+/** The scopes a user can actually toggle (already-granted ones are context, not choices). */
+declare function selectableScopes(request: XenoConsentRequest): XenoConsentScope[];
+/**
+ * The highest risk present, so the view can emphasize honestly.
+ *
+ * ⚠️ Takes any elicitation, not only a permission: a question carries `risk` too, and one without
+ * `scopes` simply has nothing to raise it.
+ */
+declare function effectiveRisk(request: XenoElicitation): XenoConsentRisk;
+/** Has this request passed its expiry? */
+declare function isExpired(request: XenoElicitation, now: number): boolean;
+/**
+ * Is this actually a consent request?
+ *
+ * **Why this guard exists.** `xeno.core.tree` emits an op called `consentRequest` whose payload is
+ * `{id, reason}` — a *notification that consent is needed*, not a request this panel can render.
+ * Both ports are `object`, and tree's is deliberately untagged, so one-sided tags pass and a host
+ * can legitimately wire the two together. Before this guard that wire threw
+ * `Cannot read properties of undefined (reading 'filter')` on the first delivery.
+ *
+ * A consent surface that crashes is a consent surface that grants nothing and blocks everything, so
+ * the panel refuses the payload instead — visibly, and without taking the host down with it.
+ *
+ * @param value - A candidate payload.
+ * @returns Whether it carries the fields the panel needs to ask the question.
+ */
+declare function isConsentRequest(value: unknown): value is XenoConsentRequest;
+/** A deny produced by the panel rather than the user. */
+declare function autoDeny(request: XenoConsentRequest, reason: XenoConsentDecision['reason']): XenoConsentDecision;
+
+/**
+ * Elicitation — the general case, of which a permission is one kind.
+ *
+ * ## Why this module exists, and why widening {@link XenoConsentDecision} would have been wrong
+ *
+ * The panel's charter is *"await a decision that does not exist yet and hand it back"*. A
+ * permission is one shape of that; it is not the only one. Real producers need three more, and
+ * **none of them has an allow/deny axis**:
+ *
+ * | ask | the question | the answer |
+ * |---|---|---|
+ * | `permission` | "may I read your project files?" | allow / deny, with scopes and a duration |
+ * | `text` | "what should I name it?" | a string |
+ * | `path` | "which directory?" | a filesystem path |
+ * | `choice` | "inbox, reuse, or new?" | one option, sometimes plus a name |
+ *
+ * 🔴 **The trap, stated plainly.** The obvious fix — widen `decision` to a string, or bolt
+ * `answer?: string` onto {@link XenoConsentDecision} — destroys this panel's stated security
+ * invariant, *"there is no path in this module that produces `allow` without a user action"*. It
+ * destroys it because a free-text answer has no safe value. `autoDeny`'s whole job is to return
+ * the SAFE member of a two-member set; a string has no safe member. `''` is not safety, it is an
+ * answer that happens to be empty, and a host cannot tell the two apart.
+ *
+ * ✅ **The framing that survives: an answer is not a permission.** They are different KINDS with
+ * different safe defaults. The safe automatic outcome for a permission is `deny`. The safe
+ * automatic outcome for a question is **not an answer at all** — and
+ * {@link XenoElicitationCancelled} makes that structural rather than conventional: it carries
+ * `answered: false` and **has no `value` key in the type**. There is no string for the panel to
+ * invent, because there is nowhere to put one.
+ *
+ * The invariant therefore GENERALISES rather than breaking:
+ *
+ * > **No path in this module produces a value the host can act on without a user action — for any
+ * > kind.** Permissions auto-deny; questions auto-cancel; nothing auto-answers.
+ *
+ * ⚠️ **Two ports, not one widened port.** Permission answers keep flowing out of `decision`
+ * (`xeno.consentdecision@1`) in the exact shape they always had; elicitation results flow out of
+ * `result` (`xeno.elicitationresult@1`). Two shapes under one tag is precisely the failure the
+ * SDK's tagging system was introduced to prevent (see `WELL_KNOWN_PORT_SCHEMAS.QUERY_REQUEST`, and
+ * the two-shapes-one-tag incident recorded there). The split also makes the emission a
+ * **partition**: a permission never appears on `result`, so no host can apply one grant twice by
+ * wiring both ports.
+ *
+ * @module
+ */
+
+/**
+ * The shape tag for the `elicitations` input port.
+ *
+ * ⚠️ **Coined here, and it belongs in `WELL_KNOWN_PORT_SCHEMAS`.** That registry is the right home
+ * for the same reason MIME types are registered centrally — a tag is only useful if two
+ * independently built panels spell it identically — and the SDK's own docblock says a third party
+ * may coin its own. Promoting it is a `@xenosystem/panel-sdk` edit and therefore a coordinated
+ * cross-package change; the STRING must not change when it moves, or every wire built against it
+ * silently stops attaching.
+ */
+declare const ELICITATION_SCHEMA = "xeno.elicitation@1";
+/** The shape tag for the `result` output port. Same registration note as {@link ELICITATION_SCHEMA}. */
+declare const ELICITATION_RESULT_SCHEMA = "xeno.elicitationresult@1";
+/**
+ * What kind of answer the host needs. Absent means `'permission'`.
+ *
+ * ⚠️ **Optional on the wire, deliberately.** Every request written before this vocabulary existed
+ * carries no `ask` and must keep meaning exactly what it meant. A required discriminant would have
+ * invalidated every existing producer overnight.
+ */
+type XenoElicitationAsk = 'permission' | 'text' | 'path' | 'choice';
+/**
+ * One offered answer.
+ *
+ * The request side had no way to say "here are the options". A permission's `scopes` are things
+ * being GRANTED, not alternatives being CHOSEN BETWEEN — rendering one as the other would ask the
+ * user to tick three boxes when exactly one may be true.
+ */
+interface XenoElicitationOption {
+    /** Stable id — what comes back in the answer. */
+    id: string;
+    /** Short label ("Reuse the existing workspace"). */
+    label: string;
+    /** Longer explanation. */
+    detail?: string;
+    /** Per-option risk, so "create a new one" can read louder than "reuse". */
+    risk?: XenoConsentRisk;
+    /**
+     * Choosing this option is not a complete answer — it also needs a value ("…and call it what?").
+     *
+     * This is the `workspace-placement` shape exactly: two options answer on their own, the third
+     * needs a name. The panel refuses to submit a `requiresText` option with an empty value, for the
+     * same reason it refuses an allow that would grant nothing — a control that reports success while
+     * carrying nothing is a control that lies about what it did.
+     */
+    requiresText?: boolean;
+}
+/** What every elicitation carries, whatever kind it is. */
+interface XenoElicitationBase {
+    /** Stable id — the correlation key for the result. */
+    id: string;
+    /** The question, in the host's words. */
+    title: string;
+    /** Supporting explanation, rendered verbatim. The panel never composes prose. */
+    detail?: string;
+    /** Who is asking — an agent name, a plugin id, a device name. */
+    subject?: string;
+    /** How dangerous answering is. Drives emphasis only — never a default. */
+    risk: XenoConsentRisk;
+    /** Epoch ms the request arrived. Queue order. */
+    requestedAt: number;
+    /** Epoch ms after which the request settles itself. **Never as an answer.** */
+    expiresAt?: number;
+    /** Pre-formatted extra fields (a path, a fingerprint, a safety number). */
+    fields?: Record<string, string>;
+    /** Presentation + telemetry only, and only meaningful for a permission. */
+    kind?: XenoConsentKind;
+}
+/**
+ * "What should I call it?" — an answer string.
+ *
+ * `options` are shortcuts, not a closed set: picking one fills the field and the user may still
+ * edit it. When the set IS closed, that is a {@link XenoChoiceElicitation}.
+ */
+interface XenoTextElicitation extends XenoElicitationBase {
+    ask: 'text';
+    /** Prefilled value. **Prefilling is not answering** — nothing is emitted until the user submits. */
+    initialValue?: string;
+    placeholder?: string;
+    /** Render a multi-line field. */
+    multiline?: boolean;
+    /** Submission is REFUSED above this length rather than silently truncated. */
+    maxLength?: number;
+    /** Suggested values. Selecting one fills the field. */
+    options?: XenoElicitationOption[];
+    /**
+     * May the user submit an empty string?
+     *
+     * Default `false`. ⚠️ A host that genuinely accepts `''` must say so, because the panel cannot
+     * distinguish "the user meant blank" from "the user pressed the button before typing" — and
+     * defaulting to the permissive reading is how a blank name reaches a filesystem.
+     */
+    allowEmpty?: boolean;
+}
+/**
+ * "Which directory?" — a filesystem path.
+ *
+ * 🔴 **The panel does not browse the filesystem, and must not.** Its manifest declares
+ * `storage.local` and nothing else; a consent surface able to enumerate the disk would BE the
+ * capability it exists to gate. So the host supplies candidates in `options` and the user may type
+ * a path. A host that wants a native picker owns that dialog itself and delivers the chosen path
+ * as `initialValue` on a fresh elicitation.
+ *
+ * ⚠️ **The panel does not validate the path either** — it cannot stat, and a syntactic check that
+ * happily passes a nonexistent directory is worse than none because it reads like verification.
+ * `mustExist` is a statement of intent the HOST enforces when it receives the answer.
+ */
+interface XenoPathElicitation extends XenoElicitationBase {
+    ask: 'path';
+    /** What the host will do with it. Presentation plus host-side validation; the panel cannot check. */
+    pathKind: 'file' | 'directory';
+    /** Prefilled path. */
+    initialValue?: string;
+    placeholder?: string;
+    /** Host-supplied candidates (recent folders, the project root, a default location). */
+    options?: XenoElicitationOption[];
+    /** The host will reject a path that does not exist. Declared for the user's benefit. */
+    mustExist?: boolean;
+}
+/**
+ * "Inbox, reuse, or new?" — exactly one of a closed set, sometimes plus a value.
+ *
+ * ⚠️ **Nothing is selected unless the host asks for it**, and even then `defaultOptionId` only
+ * pre-highlights. A pre-selected option that could be auto-submitted would be a default answer,
+ * which is the thing this module refuses to produce; since expiry cancels rather than submits, a
+ * highlight is only ever a starting point.
+ */
+interface XenoChoiceElicitation extends XenoElicitationBase {
+    ask: 'choice';
+    /** The alternatives, in display order. At least one — a choice of nothing is not a question. */
+    options: XenoElicitationOption[];
+    /** Pre-highlighted option. **Highlighting is not answering.** */
+    defaultOptionId?: string;
+    /** Label for the value field an option may require ("Name"). */
+    textLabel?: string;
+    placeholder?: string;
+    /** Submission is refused above this length. */
+    maxLength?: number;
+}
+/** Anything the panel can put in front of a user. */
+type XenoElicitation = XenoConsentRequest | XenoTextElicitation | XenoPathElicitation | XenoChoiceElicitation;
+/** Every elicitation that is NOT a permission — the three that needed a new answer vocabulary. */
+type XenoQuestionElicitation = XenoTextElicitation | XenoPathElicitation | XenoChoiceElicitation;
+/**
+ * A text answer the user actually gave.
+ *
+ * 🔴 **`reason` is the literal `'user'`, by type.** Every other producer of a result in this module
+ * returns {@link XenoElicitationCancelled}, so "an answer exists" and "a user acted" become the
+ * same statement — checkable by the compiler rather than by reading the controller.
+ */
+interface XenoTextAnswer {
+    id: string;
+    ask: 'text';
+    answered: true;
+    reason: 'user';
+    /** What the user typed. Non-empty unless the request set `allowEmpty`. */
+    value: string;
+    /** The suggestion they started from, when they picked one. */
+    optionId?: string;
+}
+/** A path the user supplied. */
+interface XenoPathAnswer {
+    id: string;
+    ask: 'path';
+    answered: true;
+    reason: 'user';
+    /** The path, verbatim and unvalidated — see {@link XenoPathElicitation}. */
+    value: string;
+    /** The candidate they started from, when they picked one. */
+    optionId?: string;
+}
+/** The option the user chose. */
+interface XenoChoiceAnswer {
+    id: string;
+    ask: 'choice';
+    answered: true;
+    reason: 'user';
+    /** Which option. */
+    optionId: string;
+    /** The accompanying value, when the chosen option required one. */
+    value?: string;
+}
+/**
+ * The question settled without an answer.
+ *
+ * 🔴 **This type has no `value` key, and that ABSENCE is the security property.** It is not "an
+ * empty answer" or "a safe default" — there is structurally nowhere for the panel to put a string
+ * it was never given, so no future edit can quietly make the timeout path produce one. A consumer
+ * must narrow on `answered` before it can read anything, which is the same discipline
+ * `decision === 'allow'` imposes on the permission side.
+ */
+interface XenoElicitationCancelled {
+    id: string;
+    /** Which kind of question went unanswered. Never `'permission'` — those settle as a deny. */
+    ask: 'text' | 'path' | 'choice';
+    answered: false;
+    /** Why the panel settled it. There is no `'user'`: a user who answers produces an answer. */
+    reason: 'expired' | 'superseded' | 'dismissed';
+}
+/** An answer, as opposed to a cancellation. */
+type XenoElicitationAnswer = XenoTextAnswer | XenoPathAnswer | XenoChoiceAnswer;
+/**
+ * What leaves the `result` port.
+ *
+ * ⚠️ **`XenoConsentDecision` is deliberately NOT a member.** Permission answers leave through
+ * `decision` in their original shape and never appear here, so the two ports PARTITION the
+ * outcomes instead of overlapping. A host may wire both and can never receive one grant twice.
+ */
+type XenoElicitationResult = XenoElicitationAnswer | XenoElicitationCancelled;
+/** Which kind of question is this? A request with no `ask` is a permission, as it always was. */
+declare function elicitationAsk(value: XenoElicitation): XenoElicitationAsk;
+/** Is this a permission request rather than a question? */
+declare function isPermissionElicitation(value: XenoElicitation): value is XenoConsentRequest;
+/** The options a question offers, or `[]` when it offers none. */
+declare function elicitationOptions(value: XenoElicitation): XenoElicitationOption[];
+/** The option with this id, or `undefined`. */
+declare function findOption(value: XenoElicitation, optionId: string | null): XenoElicitationOption | undefined;
+/** The longest value this question accepts, or `null` for unbounded. */
+declare function maxTextLength(value: XenoElicitation): number | null;
+/**
+ * Is this a question the panel can render and answer?
+ *
+ * Same job as `isConsentRequest` and the same reason: a wire is a user-editable connection, so the
+ * wrong shape arriving is a normal mis-wire, not an exceptional condition. A surface that crashes
+ * on one grants nothing and blocks everything queued behind it.
+ */
+declare function isElicitation(value: unknown): value is XenoElicitation;
+/** Is this an answer the user gave? */
+declare function isElicitationAnswer(value: unknown): value is XenoElicitationAnswer;
+/** Is this a question that settled without an answer? */
+declare function isElicitationCancelled(value: unknown): value is XenoElicitationCancelled;
+/**
+ * A question settled by the panel rather than by the user.
+ *
+ * 🔴 The counterpart of `autoDeny`, and the reason the security invariant survived this feature:
+ * it **cannot** return an answer. {@link XenoElicitationCancelled} has no `value` field, so there
+ * is no edit to this function that quietly starts producing one.
+ *
+ * @param request - The question being abandoned.
+ * @param reason - Why the panel settled it. Never `'user'`.
+ * @returns A cancellation carrying no answer.
+ */
+declare function autoCancel(request: XenoElicitation, reason: XenoElicitationCancelled['reason']): XenoElicitationCancelled;
+
+/**
+ * The Consent controller — ONE ordered queue of things the user has not answered yet.
+ *
+ * **The panel grants nothing and answers nothing.** It emits and the host enforces.
+ *
+ * 🔴 **The invariant, in its general form.** *No path in this controller produces a value the host
+ * can act on without a user action.* Concretely:
+ *
+ * | path | permission head | question head |
+ * |---|---|---|
+ * | user acted | `allow()` / `deny()` | `submit()` |
+ * | timeout, withdrawal, dismissal, disposal | `autoDeny` ⇒ `deny` | `autoCancel` ⇒ `answered:false` |
+ *
+ * The right-hand column is what makes the invariant survive free text: a cancellation is not a safe
+ * answer, it is the ABSENCE of one, and `XenoElicitationCancelled` has no field to put a value in.
+ *
+ * ⚠️ **One queue, not two.** A text question and a permission ask both block the same user; two
+ * independent queues would put two prompts on screen at once and lose arrival order between them.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface ConsentHostBridge {
+    emit(portId: string, value: unknown): void;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** Construction options. */
+interface ConsentControllerOptions {
+    host: ConsentHostBridge;
+    /** Per-scope checkboxes rather than one all-or-nothing answer. Default `true`. */
+    perScope?: boolean;
+    /** The duration pre-selected when a request permits more than one. Default `'once'`. */
+    defaultDuration?: XenoConsentDuration;
+}
+/** The Consent panel controller. */
+declare class ConsentController {
+    private readonly host;
+    private readonly listeners;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly perScope;
+    private readonly defaultDuration;
+    private queue;
+    private selected;
+    private duration;
+    /** What the user has typed for the head question. Discarded whenever the head changes. */
+    private draftText;
+    /** The option highlighted for the head question. Highlighting is not answering. */
+    private selectedOptionId;
+    private expiryTimer;
+    /** Ids already decided, so a re-delivery cannot produce a second decision. */
+    private readonly resolved;
+    private snapshot;
+    constructor(options: ConsentControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => ConsentViewState;
+    private notify;
+    /**
+     * Enqueue a request.
+     *
+     * Requests are **ordered and individually resolvable**. They are never merged, never deduplicated
+     * into one "allow all", and a second request does not supersede the first — bulk approval is how
+     * consent fatigue turns into a security hole.
+     *
+     * @returns `true` if enqueued; `false` if already pending or already decided.
+     */
+    enqueue(request: XenoElicitation): boolean;
+    /** Enqueue several. */
+    enqueueMany(requests: readonly XenoElicitation[]): number;
+    /**
+     * Withdraw a request the host no longer needs an answer to.
+     *
+     * Emits `superseded` so the host's awaiting promise resolves — a withdrawn request that resolves
+     * nothing leaves the caller hanging forever.
+     */
+    withdraw(id: string): boolean;
+    /**
+     * Selection state for the head of the queue.
+     *
+     * 🔴 **Called on every head change, and that is what stops a draft leaking between questions.**
+     * A name typed for one ask must never arrive as the answer to the next one — the ids differ, so
+     * the host would attribute it to a question the user never saw.
+     */
+    private resetSelection;
+    /**
+     * Arm a timer for the head request's expiry.
+     *
+     * **Expiry denies.** There is no configuration that makes a timeout allow — a grant nobody was
+     * present to give is not a grant.
+     */
+    private armExpiry;
+    /**
+     * Settle every request whose deadline has passed — permissions as a deny, questions as a
+     * cancellation.
+     *
+     * Sweeps the WHOLE queue, not just the head: a request waiting behind a slow decision can expire
+     * while it is still queued, and showing it afterwards would ask for an answer nobody can use.
+     *
+     * @returns How many expired.
+     */
+    expireDue(): number;
+    /** Toggle one scope of the current request. Refused when the head is not a permission. */
+    toggleScope(scopeId: string, selected?: boolean): boolean;
+    /** Choose how long the grant lasts. Refuses a duration the request forbids. */
+    setDuration(duration: XenoConsentDuration): boolean;
+    /**
+     * Record what the user has typed.
+     *
+     * ⚠️ **A draft is not an answer and never leaves the panel on its own.** Only `submit()` emits,
+     * and every other settlement path discards this — so a half-typed name cannot escape through a
+     * timeout.
+     *
+     * @param value - The current field contents.
+     * @returns `true` when the head is a question that takes a value.
+     */
+    setDraftText(value: string): boolean;
+    /**
+     * Highlight one of the offered options.
+     *
+     * For a `choice` this IS the answer-in-progress; for `text`/`path` it is a shortcut that also
+     * fills the field. Either way nothing is emitted — highlighting is not answering.
+     *
+     * @param optionId - The option, or `null` to clear.
+     * @returns `true` when the option belongs to the current question.
+     */
+    selectOption(optionId: string | null): boolean;
+    /**
+     * Allow the current request.
+     *
+     * The ONLY path in this controller that produces `decision: 'allow'`, and it requires a call from
+     * a user gesture. Refuses when nothing is selected — an "Allow" that grants nothing is a button
+     * that lies about what it did.
+     */
+    allow(): boolean;
+    /**
+     * Deny the current request.
+     *
+     * ⚠️ **Permissions only.** "Deny" is a permission verb; a question is refused with
+     * {@link ConsentController.dismiss}, which is what `cancel_request` calls. Returning `false`
+     * here rather than quietly cancelling keeps the two refusals distinguishable to a caller.
+     */
+    deny(): boolean;
+    /**
+     * Submit the answer to the current QUESTION.
+     *
+     * 🔴 **The only path in this controller that produces an answer**, and the exact counterpart of
+     * `allow()`: it requires a user gesture and it refuses to emit something the user did not
+     * supply. An empty text answer, a choice with nothing chosen, or a `requiresText` option with no
+     * value are all refusals — for the same reason `allow()` refuses to grant nothing. A control
+     * that reports success while carrying nothing is a control that lies about what it did.
+     *
+     * @returns `true` when an answer was emitted.
+     */
+    submit(): boolean;
+    /**
+     * The user dismissed the prompt without answering.
+     *
+     * Resolves as **deny** for a permission and as a **cancellation** for a question — never as an
+     * allow, never as an answer, and never as "ask again later": an unanswered request that stays
+     * pending forever blocks the host that is awaiting it.
+     */
+    dismiss(): boolean;
+    /** The head of the queue when it is a permission. */
+    private currentPermission;
+    /** The head of the queue when it is a question rather than a permission. */
+    private currentQuestion;
+    /**
+     * The answer the current draft would produce, or `null` when it would produce none.
+     *
+     * ⚠️ **Pure, and shared with `getState().canSubmit`.** One predicate drives both the guard and
+     * the button's enabled state, so an enabled button cannot be a button that refuses — the class of
+     * bug where an affordance and its guard disagree has no representation here.
+     */
+    private answerFor;
+    /**
+     * Settle a request the user did not answer.
+     *
+     * 🔴 **The generalised safe default lives here, and it is kind-dependent BY NECESSITY.** A
+     * permission's safe outcome is `deny`; a question's safe outcome is the absence of an answer.
+     * There is no third branch and no configuration that reaches one.
+     */
+    private settleUnanswered;
+    private resolveHead;
+    /**
+     * Emit one resolution, on exactly one port.
+     *
+     * ⚠️ **The two output ports PARTITION the outcomes** — a permission answer only ever appears on
+     * `decision`, a question result only ever on `result`. Emitting a permission on both would let a
+     * host that wired both ports apply the same grant twice, which on a security surface is a defect
+     * to design out rather than to document.
+     */
+    private emitResolution;
+    /** Has this request already been answered? */
+    isResolved(id: string): boolean;
+    /**
+     * Pending requests, in order.
+     *
+     * ⚠️ Widened from `XenoConsentRequest[]` with the question kinds. A host that only enqueues
+     * permissions only ever gets permissions back; narrow with `isPermissionElicitation()`.
+     */
+    pending(): XenoElicitation[];
+    /**
+     * Serialize — deliberately empty.
+     *
+     * **A pending decision must never survive a reload.** Restoring one would show a prompt whose
+     * host is long gone, and any answer would resolve nothing.
+     */
+    serialize(): Record<string, never>;
+    /** Restore — a no-op, for the same reason. */
+    deserialize(): void;
+    /**
+     * Tear down.
+     *
+     * Every still-pending request is settled — permissions **denied**, questions **cancelled** — so a
+     * host awaiting one is never left hanging by a panel that simply vanished.
+     *
+     * 🔴 **Disposal is not the same event as unmounting, and the difference matters for a question.**
+     * `render()`/`unrender()` only move the DOM; the controller and its queue outlive them, so
+     * hiding a panel tab does NOT answer or cancel anything and a half-typed draft survives being
+     * hidden. `dispose()` is the panel going away for good, and THAT is what settles the queue. A
+     * host that tears the panel down mid-question receives `answered: false` with reason
+     * `'dismissed'` — never an empty string, which it could not distinguish from a deliberate blank.
+     */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface ConsentRenderContext {
+    controller: ConsentController;
+    config: {
+        showQueueCount: boolean;
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createConsentPanel}. */
+interface CreateConsentPanelOptions {
+    /** Override the view. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: ConsentRenderContext) => () => void;
+}
+/**
+ * Build the Consent panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createConsentPanel(options?: CreateConsentPanelOptions): PanelModule;
+/** The default Consent panel module — view already wired. Register THIS. */
+declare const consentPanel: PanelModule;
+
+/**
+ * The `xeno.core.consent` manifest.
+ *
+ * Capabilities: `storage.local` only. The panel grants nothing and enforces nothing — it emits a
+ * decision and the host acts on it. A consent surface that could itself grant a capability would be
+ * the capability.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const CONSENT_PANEL_ID = "xeno.core.consent";
+/** The `xeno.core.consent` manifest. */
+declare const consentManifest: PanelManifest;
+
+/**
+ * The Consent panel view.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure `@xenosystem/workbench/primitives.css` is
+ * present.
+ *
+ * Two deliberate absences: **no "Allow all"** (bulk approval is how consent fatigue becomes a
+ * security hole) and **no auto-focus on Allow** (a stray Enter must not grant anything).
+ *
+ * 🔴 **A third absence, added with the question kinds: nothing here submits on its own.** The
+ * question forms carry no auto-submit, no debounce-then-send, and no Enter-to-answer on the
+ * single-line field. The emitted answer is always the product of a click the user made, which is
+ * the view's half of the controller's *"no value without a user action"* invariant — the guard
+ * lives in `submit()`, but a view that fired it on a keystroke would satisfy the guard while
+ * defeating the point.
+ *
+ * @module
+ */
+
+/** Props for {@link ConsentPanelView}. */
+interface ConsentPanelViewProps {
+    controller: ConsentController;
+    showQueueCount?: boolean;
+    emptyHint?: string;
+}
+/** The Consent panel view. */
+declare function ConsentPanelView({ controller, showQueueCount, emptyHint, }: ConsentPanelViewProps): ReactNode;
+
+export { CONSENT_PANEL_ID, ConsentController, type ConsentControllerOptions, type ConsentHostBridge, type ConsentPanelState, ConsentPanelView, type ConsentPanelViewProps, type ConsentRenderContext, type ConsentViewState, type CreateConsentPanelOptions, ELICITATION_RESULT_SCHEMA, ELICITATION_SCHEMA, type XenoChoiceAnswer, type XenoChoiceElicitation, type XenoConsentDecision, type XenoConsentDuration, type XenoConsentKind, type XenoConsentRequest, type XenoConsentRisk, type XenoConsentScope, type XenoElicitation, type XenoElicitationAnswer, type XenoElicitationAsk, type XenoElicitationBase, type XenoElicitationCancelled, type XenoElicitationOption, type XenoElicitationResult, type XenoPathAnswer, type XenoPathElicitation, type XenoQuestionElicitation, type XenoTextAnswer, type XenoTextElicitation, allowedDurations, autoCancel, autoDeny, consentManifest, consentPanel, createConsentPanel, effectiveRisk, elicitationAsk, elicitationOptions, findOption, isConsentRequest, isElicitation, isElicitationAnswer, isElicitationCancelled, isExpired, isPermissionElicitation, maxTextLength, selectableScopes };