broapp 0.2.0 → 0.3.0

package/src/ai/shared/contract.ts

@@ -34,7 +34,7 @@ const providerInfo = s.object({
   label: s.string(),
   local: s.boolean(),
   needs: s.object({
-    apiKey: s.boolean(),
+    apiKey: s.enum(['required', 'optional', 'none']),
     baseUrl: s.enum(['required', 'optional', 'none']),
   }),
   defaultBaseUrl: s.nullable(s.string()),
@@ -55,6 +55,53 @@ const chatTurn = s.object({
   content: s.string({ max: 20_000 }),
 });
 
+/**
+ * One image on a turn. `data` is base64 without the `data:` prefix.
+ *
+ * The bounds are the browser's contract as much as the host's: the panel
+ * downscales before it sends, and four images of two million characters still
+ * fit inside one Brobridge frame with room to spare.
+ */
+const chatFile = s.object({
+  name: s.string({ max: 200 }),
+  mediaType: s.string({ pattern: /image\/(png|jpeg|gif|webp)/ }),
+  data: s.string({ min: 1, max: 2_000_000 }),
+});
+
+/** A conversation identifier. The host chooses it; the browser only echoes it. */
+const threadId = s.string({ pattern: /[A-Za-z0-9_-]{8,64}/ });
+
+/** A conversation, without its messages. */
+const thread = s.object({
+  id: threadId,
+  title: s.string({ max: 120 }),
+  /** Null means "whatever Settings says". */
+  modelId: s.nullable(s.string({ max: 200 })),
+  createdAt: s.number(),
+  updatedAt: s.number(),
+  messageCount: s.number({ int: true, min: 0 }),
+});
+
+/**
+ * One stored UI message. Parts are the AI SDK's; the host stores, never
+ * interprets.
+ *
+ * `s.unknown()` is normally forbidden on an input, because the point of an
+ * input schema is that browser-supplied data is untrusted. It is right here
+ * for the one reason that exempts it: nothing on the host ever reads inside a
+ * part. They are written to SQLite as JSON and handed back to the same browser
+ * that sent them, so the shape the host would be validating is a shape only
+ * the AI SDK understands and only the AI SDK consumes. What is still bounded
+ * is the *amount*: 200 parts to a message, 200 messages to a save, and a byte
+ * ceiling on the whole save in `threads.ts`.
+ */
+const storedMessage = s.object({
+  id: s.string({ max: 200 }),
+  role: s.enum(['user', 'assistant', 'system']),
+  parts: s.array(s.unknown(), { max: 200 }),
+  metadata: s.optional(s.unknown()),
+});
+
 /**
  * One stream event, flat because the validator has no unions.
  *
@@ -72,6 +119,10 @@ const chatEvent = s.object({
   output: s.optional(s.unknown()),
   denied: s.optional(s.boolean()),
   permission: s.optional(s.enum(['read', 'confirm'])),
+  requestId: s.optional(s.string()),
+  releaseId: s.optional(s.string()),
+  argumentsHash: s.optional(s.string()),
+  expiresAt: s.optional(s.number()),
   inputTokens: s.optional(s.number()),
   outputTokens: s.optional(s.number()),
   code: s.optional(s.string()),
@@ -119,6 +170,56 @@ export const aiContract = defineContract({
       output: s.object({ accepted: s.boolean() }),
       summary: 'Answer a confirm event. `accepted` is false when no run is waiting on that call.',
     },
+    // Conversations are the user's own data, so every route below answers even
+    // when no provider is configured: somebody who has just removed their key
+    // is still entitled to read and delete what they wrote.
+    'ai.threadsList': {
+      input: s.void(),
+      output: s.object({ threads: s.array(thread, { max: 500 }) }),
+      summary: 'Every stored conversation, most recently changed first.',
+    },
+    'ai.threadsCreate': {
+      input: s.object({
+        title: s.optional(s.string({ max: 120 })),
+        modelId: s.optional(s.nullable(s.string({ max: 200 }))),
+      }),
+      output: thread,
+      summary: 'Start a conversation. Without a title it is named after its first message.',
+    },
+    'ai.threadsGet': {
+      input: s.object({ id: threadId }),
+      output: s.object({ thread, messages: s.array(storedMessage, { max: 200 }) }),
+      summary: 'One conversation and its messages.',
+    },
+    'ai.threadsSave': {
+      input: s.object({
+        id: threadId,
+        messages: s.array(storedMessage, { max: 200 }),
+        title: s.optional(s.string({ max: 120 })),
+      }),
+      output: thread,
+      summary: 'Replace the messages of a conversation, whole.',
+    },
+    'ai.threadsUpdate': {
+      input: s.object({
+        id: threadId,
+        title: s.optional(s.string({ max: 120 })),
+        // Null puts the conversation back on whatever Settings says.
+        modelId: s.optional(s.nullable(s.string({ max: 200 }))),
+      }),
+      output: thread,
+      summary: 'Rename a conversation, or give it a model of its own.',
+    },
+    'ai.threadsDelete': {
+      input: s.object({ id: threadId }),
+      output: s.object({ deleted: s.boolean() }),
+      summary: 'Delete one conversation and its messages.',
+    },
+    'ai.threadsClear': {
+      input: s.void(),
+      output: s.object({ deleted: s.number({ int: true, min: 0 }) }),
+      summary: 'Delete every conversation.',
+    },
   },
   streams: {
     'ai.chat': {
@@ -127,6 +228,14 @@ export const aiContract = defineContract({
         message: s.string({ min: 1, max: 20_000 }),
         refs: s.array(s.string({ max: 200 }), { max: 50 }),
         history: s.array(chatTurn, { max: 100 }),
+        // Images travel with the turn they arrive on. History keeps a
+        // placeholder instead, because a transcript of base64 would not fit.
+        files: s.optional(s.array(chatFile, { max: 4 })),
+        // The model for this turn only, and only *within* the configured
+        // provider. A provider is never overridden per turn: a different
+        // provider means a different key and a different answer to "does this
+        // leave my computer", and that stays a Settings decision.
+        modelId: s.optional(s.string({ max: 200 })),
       }),
       event: chatEvent,
       summary: 'One chat turn. Emits text, tool calls, confirmations and usage.',

package/src/ai/shared/index.ts

@@ -10,7 +10,10 @@ export type {
   AiSettings,
   BroappModel,
   ChatEvent,
+  ChatFile,
   ChatTurn,
   ProviderInfo,
+  StoredMessage,
+  Thread,
   ToolPermission,
 } from './types.ts';

package/src/ai/shared/types.check.ts

@@ -5,9 +5,22 @@
  * without changing the matching interface in `types.ts` fails `tsc` instead of
  * failing later, in the browser, as a shape that is almost right.
  */
-import type { OperationInput, OperationOutput, StreamEvent } from '../../shared/contract.ts';
+import type {
+  OperationInput,
+  OperationOutput,
+  StreamEvent,
+  StreamParams,
+} from '../../shared/contract.ts';
 import type { AiContract } from './contract.ts';
-import type { AiSettings, BroappModel, ChatEvent, ProviderInfo } from './types.ts';
+import type {
+  AiSettings,
+  BroappModel,
+  ChatEvent,
+  ChatFile,
+  ProviderInfo,
+  StoredMessage,
+  Thread,
+} from './types.ts';
 
 type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
   ? true
@@ -37,6 +50,21 @@ void providerMatch;
 const chatEventMatch: Equal<StreamEvent<AiContract, 'ai.chat'>, ChatEvent> = true;
 void chatEventMatch;
 
+const chatFileMatch: Equal<
+  NonNullable<StreamParams<AiContract, 'ai.chat'>['files']>[number],
+  ChatFile
+> = true;
+void chatFileMatch;
+
+const threadMatch: Equal<OperationOutput<AiContract, 'ai.threadsCreate'>, Thread> = true;
+void threadMatch;
+
+const storedMessageMatch: Equal<
+  OperationOutput<AiContract, 'ai.threadsGet'>['messages'][number],
+  StoredMessage
+> = true;
+void storedMessageMatch;
+
 // The update route is the only one that takes a partial: every field optional,
 // so a browser can change one setting without restating the rest.
 const updateAcceptsNothing: OperationInput<AiContract, 'ai.settingsUpdate'> = {};

package/src/ai/shared/types.ts

@@ -31,7 +31,10 @@ export interface ProviderInfo {
   label: string;
   /** True when requests stay on this machine with the current settings. */
   local: boolean;
-  needs: { apiKey: boolean; baseUrl: 'required' | 'optional' | 'none' };
+  needs: {
+    apiKey: 'required' | 'optional' | 'none';
+    baseUrl: 'required' | 'optional' | 'none';
+  };
   defaultBaseUrl: string | null;
 }
 
@@ -58,6 +61,56 @@ export interface ChatTurn {
   content: string;
 }
 
+/**
+ * One image sent with a chat turn.
+ *
+ * `data` is base64 with no `data:` prefix, at most 2,000,000 characters, and
+ * `mediaType` is one of `image/png`, `image/jpeg`, `image/gif`, `image/webp`.
+ * At most four travel with one message, and they travel only with the message
+ * they arrive on: a later turn's `history` keeps the line
+ * `[image: <name>]` in place of the image itself, because a transcript of
+ * base64 would not fit inside the contract's bound on a turn.
+ */
+export interface ChatFile {
+  name: string;
+  mediaType: string;
+  data: string;
+}
+
+/**
+ * A stored conversation, without its messages.
+ *
+ * `modelId` is null for a conversation that follows Settings, and a model id
+ * for one that has been pinned to a model of its own. The provider is never
+ * part of a conversation: it is a Settings decision, because changing it
+ * changes which key is used and whether anything leaves the computer.
+ */
+export interface Thread {
+  id: string;
+  title: string;
+  modelId: string | null;
+  createdAt: number;
+  updatedAt: number;
+  messageCount: number;
+}
+
+/**
+ * One message as it is stored.
+ *
+ * `parts` are the AI SDK's own message parts. The host writes them as JSON and
+ * hands them back unread — it has no opinion about what a part is, which is
+ * why the type is `unknown[]` rather than a copy of the SDK's union that would
+ * drift from it. One thing the host *does* change on the way in: a `file` part
+ * becomes the text `[image: name]`, because a data URL in SQLite would be a
+ * copy of the image nobody asked to keep.
+ */
+export interface StoredMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  parts: unknown[];
+  metadata?: unknown;
+}
+
 /**
  * One event on the `ai.chat` stream. Flat on purpose: the `s` validator has
  * no unions, so the discriminant is `type` and the other fields are
@@ -65,7 +118,8 @@ export interface ChatTurn {
  *
  *   text        text
  *   tool-call   callId, tool, input, permission
- *   confirm     callId, tool, input          (waits for ai.chat.confirm)
+ *   confirm     callId, tool, input, requestId, releaseId, argumentsHash,
+ *               expiresAt                    (waits for ai.chatConfirm)
  *   tool-result callId, tool, output, denied?
  *   usage       inputTokens, outputTokens
  *   done        —
@@ -80,6 +134,12 @@ export interface ChatEvent {
   output?: unknown;
   denied?: boolean;
   permission?: ToolPermission;
+  /** On `confirm`: what the gate is waiting on, so an answer can name it. */
+  requestId?: string;
+  releaseId?: string;
+  argumentsHash?: string;
+  /** On `confirm`: when the question stops waiting, so the card can count down. */
+  expiresAt?: number;
   inputTokens?: number;
   outputTokens?: number;
   code?: string;

package/src/host/app.ts

@@ -16,6 +16,7 @@ import type { BridgeStream } from '@brobridgejs/core';
 
 import type {
   AnyContract,
+  Effect,
   OperationInput,
   OperationName,
   OperationOutput,
@@ -23,10 +24,18 @@ import type {
   StreamName,
   StreamParams,
 } from '../shared/contract.ts';
-import { assertNoReservedRoutes, splitRoute } from '../shared/contract.ts';
-import { INTERNAL_ERROR_MESSAGE, isPublicBridgeError, PublicError } from '../shared/errors.ts';
+import { assertNoReservedRoutes, effectOf, splitRoute } from '../shared/contract.ts';
+import {
+  INTERNAL_ERROR_MESSAGE,
+  isPublicBridgeError,
+  isPublicError,
+  PublicError,
+} from '../shared/errors.ts';
 import { encodeEvent } from '../shared/ndjson.ts';
-import { ValidationError } from '../shared/schema.ts';
+import { isValidationError } from '../shared/schema.ts';
+
+import { createGate } from './gate.ts';
+import type { Channel, Envelope, ExecutionMode, Gate } from './gate.ts';
 
 /**
  * What an operation handler is told about its caller.
@@ -41,6 +50,14 @@ import { ValidationError } from '../shared/schema.ts';
 export interface CallContext {
   /** The route name, for logging. */
   readonly route: string;
+  /** Correlates this call with the gate's record and any approval it needed. */
+  readonly requestId: string;
+  /** Who asked, as the adapter that received the request said so. */
+  readonly channel: Channel;
+  /** Free text naming the caller: 'tab', 'ai:<runId>', 'mcp:<client>'. */
+  readonly caller: string;
+  /** `preview` means the data directory is a copy and nothing may leave the machine. */
+  readonly mode: ExecutionMode;
 }
 
 /** A unary operation implementation. */
@@ -81,6 +98,12 @@ export interface HostLogger {
 /** Options for {@link createHostApp}. */
 export interface HostAppOptions {
   readonly logger?: HostLogger;
+  /**
+   * The gate every call passes. An application that does not supply one gets a
+   * live gate for an unreleased application: the policy still applies, there is
+   * simply nothing recording it and no release to bind an approval to.
+   */
+  readonly gate?: Gate;
 }
 
 /** A contract with implementations attached, ready to mount on a bridge. */
@@ -106,12 +129,22 @@ export interface HostApp<C extends AnyContract> {
    * A route that is a stream, or one no handler implements, is a programming
    * error rather than a call failure, so it throws `TypeError` at the call
    * site instead of rejecting.
+   *
+   * The envelope is required, and required to be built by the adapter making
+   * the call rather than passed through from whatever asked it to. That is
+   * what stops a model from invoking an operation as the user.
    */
-  invoke<K extends OperationName<C>>(name: K, input: unknown): Promise<OperationOutput<C, K>>;
+  invoke<K extends OperationName<C>>(
+    name: K,
+    input: unknown,
+    envelope: Envelope,
+  ): Promise<OperationOutput<C, K>>;
   /** Abort every stream this app currently has open. Called during shutdown. */
   abortAll(reason: string): void;
   /** How many streams are running right now. */
   readonly activeStreams: number;
+  /** The gate this application's calls pass through. */
+  readonly gate: Gate;
 }
 
 /**
@@ -141,6 +174,12 @@ export function createReservedHostApp<C extends AnyContract>(
   options: HostAppOptions = {},
 ): HostApp<C> {
   const logger: HostLogger = options.logger ?? console;
+  // An application that was not given a gate still has one. There is no
+  // ungated path into a handler, so the only question a missing option answers
+  // is what the records say, not whether the policy applies.
+  const gate: Gate =
+    options.gate ??
+    createGate({ appId: 'app', releaseId: 'unreleased', mode: 'live', logger });
   const operations = new Map<string, OperationHandler<C, never>>();
   const streams = new Map<string, StreamHandlerFor<C, never>>();
   const running = new Set<AbortController>();
@@ -159,13 +198,12 @@ export function createReservedHostApp<C extends AnyContract>(
    * call is not more trusted than a browser call just because it originates
    * inside the host — so there is one implementation and two callers.
    */
-  async function runOperation(route: string, raw: unknown): Promise<unknown> {
+  async function runOperation(route: string, raw: unknown, envelope: Envelope): Promise<unknown> {
     const spec = contract.operations[route];
     const handler = operations.get(route);
     if (spec === undefined || handler === undefined) {
       throw new TypeError(`operation ${JSON.stringify(route)} has no implementation`);
     }
-    const context: CallContext = { route };
     let input: unknown;
     try {
       input = spec.input.parse(raw);
@@ -173,13 +211,27 @@ export function createReservedHostApp<C extends AnyContract>(
       // A validation message names a field and a constraint from the contract
       // the browser already has. It carries nothing the caller did not send,
       // so it is safe to return and useful to see.
+      //
+      // This is deliberately before the gate. A call that never had valid
+      // arguments asked nobody for anything, so there is nothing to approve and
+      // nothing worth recording.
       throw new PublicError(
         'invalid_input',
-        cause instanceof ValidationError ? cause.message : 'invalid input',
+        isValidationError(cause) ? cause.message : 'invalid input',
       ).toBridgeError();
     }
+    const context: CallContext = {
+      route,
+      requestId: envelope.requestId,
+      channel: envelope.channel,
+      caller: envelope.caller,
+      mode: gate.mode === 'preview' || envelope.mode === 'preview' ? 'preview' : 'live',
+    };
     try {
-      const output = await handler(input as never, context);
+      const output = await gate.guard(
+        { ...envelope, route, effect: spec.effect ?? envelope.effectHint ?? 'write', input },
+        () => Promise.resolve(handler(input as never, context)),
+      );
       return spec.output.parse(output);
     } catch (cause) {
       throw wrap(cause, route, logger);
@@ -201,7 +253,7 @@ export function createReservedHostApp<C extends AnyContract>(
       return app;
     },
 
-    invoke(name, input) {
+    invoke(name, input, envelope) {
       // Structural mistakes surface synchronously: a stream is not invokable
       // and a missing handler is a bug, and neither should look like a failed
       // call to whatever is awaiting the result.
@@ -214,7 +266,7 @@ export function createReservedHostApp<C extends AnyContract>(
       if (!operations.has(name)) {
         throw new TypeError(`operation ${JSON.stringify(name)} has no implementation`);
       }
-      return runOperation(name, input).catch((cause: unknown) => {
+      return runOperation(name, input, envelope).catch((cause: unknown) => {
         // On the bridge, Brobridge reduces an unexpected failure to a fixed
         // sentence on the way out. `invoke` has no transport to do that, and
         // its caller is the AI layer, which may put what it is given into a
@@ -227,6 +279,8 @@ export function createReservedHostApp<C extends AnyContract>(
       return running.size;
     },
 
+    gate,
+
     abortAll(reason) {
       for (const controller of running) controller.abort(new Error(reason));
     },
@@ -248,7 +302,15 @@ export function createReservedHostApp<C extends AnyContract>(
         const { group, member } = splitRoute(route);
         if (contract.operations[route] === undefined) continue;
         const service = groups.get(group) ?? {};
-        service[member] = (raw: unknown): Promise<unknown> => runOperation(route, raw);
+        // The envelope is built here and nowhere else on this path. A tab has
+        // no way to describe itself as anything other than the user, because
+        // nothing it sends is read when this is filled in.
+        service[member] = (raw: unknown): Promise<unknown> =>
+          runOperation(route, raw, {
+            requestId: crypto.randomUUID(),
+            channel: 'user',
+            caller: 'tab',
+          });
         groups.set(group, service);
       }
       for (const [group, service] of groups) bridge.expose(group, service);
@@ -257,7 +319,7 @@ export function createReservedHostApp<C extends AnyContract>(
         const spec = contract.streams[route];
         if (spec === undefined) continue;
         bridge.stream(route, (stream: BridgeStream, streamContext: StreamContext) =>
-          runStream(stream, streamContext, route, spec, handler, running, logger),
+          runStream(stream, streamContext, route, spec, handler, running, logger, gate),
         );
       }
     },
@@ -276,7 +338,7 @@ export function createReservedHostApp<C extends AnyContract>(
  * accidentally undo the reduction by wrapping the message.
  */
 function wrap(cause: unknown, route: string, logger: HostLogger): unknown {
-  if (cause instanceof PublicError) return cause.toBridgeError();
+  if (isPublicError(cause)) return cause.toBridgeError();
   logger.error(`[broapp] ${route} failed: ${String(cause instanceof Error ? cause.stack ?? cause.message : cause)}`);
   return cause;
 }
@@ -297,10 +359,15 @@ async function runStream<E>(
   stream: BridgeStream,
   streamContext: StreamContext,
   route: string,
-  spec: { params: { parse(value: unknown): unknown }; event: { parse(value: unknown): unknown } },
+  spec: {
+    params: { parse(value: unknown): unknown };
+    event: { parse(value: unknown): unknown };
+    effect?: Effect;
+  },
   handler: (params: never, sink: StreamSink<E>) => void | Promise<void>,
   running: Set<AbortController>,
   logger: HostLogger,
+  gate: Gate,
 ): Promise<void> {
   const controller = new AbortController();
   running.add(controller);
@@ -319,7 +386,7 @@ async function runStream<E>(
     running.delete(controller);
     throw new PublicError(
       'invalid_input',
-      cause instanceof ValidationError ? cause.message : 'invalid stream parameters',
+      isValidationError(cause) ? cause.message : 'invalid stream parameters',
     ).toBridgeError();
   }
 
@@ -333,7 +400,23 @@ async function runStream<E>(
   };
 
   try {
-    await handler(params as never, sink);
+    // A stream is guarded once, when it starts. Its events are the one call's
+    // output, not a series of calls, so there is nothing further to decide
+    // once the handler is running.
+    await gate.guard(
+      {
+        requestId: crypto.randomUUID(),
+        channel: 'user',
+        caller: 'tab',
+        signal: controller.signal,
+        route,
+        effect: effectOf(spec),
+        input: params,
+      },
+      async () => {
+        await handler(params as never, sink);
+      },
+    );
     if (!controller.signal.aborted) await stream.end();
   } catch (cause) {
     // A cancelled stream is not a fault: the browser asked for it, the stream

package/src/host/approvals.ts

@@ -0,0 +1,115 @@
+/**
+ * The table a waiting question and a later answer meet in.
+ *
+ * An approver has to ask somebody, and the somebody is at the other end of a
+ * route: a chat stream, a launcher tab, an MCP client's own UI. So the ask and
+ * the answer are two separate calls, and something has to hold the question in
+ * between. That is all this is — with one property that matters more than the
+ * bookkeeping.
+ *
+ * An answer must name the question it is answering. A `requestId` alone would
+ * let an answer meant for one call approve a different one that happened to be
+ * pending under the same identifier after a rebuild, or after a model changed
+ * its arguments between the question and the click. So an answer may carry the
+ * release and the arguments hash it believes it is approving, and a value that
+ * does not match the pending question is a denial, not a near miss.
+ */
+import type { HostLogger } from './app.ts';
+import type { ApprovalQuestion, Approver } from './gate.ts';
+
+/** What the route that received a person's answer passes back in. */
+export interface ApprovalAnswer {
+  readonly requestId: string;
+  readonly approved: boolean;
+  /** When given, must equal the pending question's value or the answer is a mismatch. */
+  readonly releaseId?: string;
+  readonly argumentsHash?: string;
+}
+
+/** What happened to an answer. */
+export type AnswerResult = 'accepted' | 'unknown' | 'mismatch';
+
+/** An {@link Approver} whose answers arrive later, over some other route. */
+export interface PendingApprovals extends Approver {
+  /** Called by the route that receives the person's answer. */
+  answer(answer: ApprovalAnswer): AnswerResult;
+  /**
+   * Questions currently waiting, for a UI to show. `input` is shown as-is;
+   * adapters must not put secrets in inputs.
+   */
+  readonly pending: readonly ApprovalQuestion[];
+}
+
+/** One question, and the callback that settles it. */
+interface Waiting {
+  readonly question: ApprovalQuestion;
+  settle(approved: boolean): void;
+}
+
+/** Build a pending-approval table. */
+export function createPendingApprovals(logger?: HostLogger): PendingApprovals {
+  const log: HostLogger = logger ?? console;
+  const waiting = new Map<string, Waiting>();
+
+  return {
+    ask(question: ApprovalQuestion, signal: AbortSignal): Promise<boolean> {
+      // Two questions under one identifier would make an answer ambiguous, and
+      // an ambiguous approval is the one thing this table exists to prevent.
+      // The caller chose the identifier, so a collision is its bug.
+      if (waiting.has(question.requestId)) {
+        throw new TypeError(
+          `an approval for request ${JSON.stringify(question.requestId)} is already pending`,
+        );
+      }
+      return new Promise<boolean>((resolve) => {
+        let settled = false;
+        const finish = (approved: boolean): void => {
+          if (settled) return;
+          settled = true;
+          waiting.delete(question.requestId);
+          signal.removeEventListener('abort', onAbort);
+          resolve(approved);
+        };
+        // A question nobody answers is a denial, not a hung call: the person
+        // may have closed the tab, and nothing may run unattended.
+        const onAbort = (): void => finish(false);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) finish(false);
+        else waiting.set(question.requestId, { question, settle: finish });
+      });
+    },
+
+    answer(answer: ApprovalAnswer): AnswerResult {
+      const entry = waiting.get(answer.requestId);
+      // Nobody waiting covers both a stale answer and a second answer for a
+      // question that has already been settled and removed.
+      if (entry === undefined) return 'unknown';
+
+      const wrong =
+        answer.releaseId !== undefined && answer.releaseId !== entry.question.releaseId
+          ? 'releaseId'
+          : answer.argumentsHash !== undefined &&
+              answer.argumentsHash !== entry.question.argumentsHash
+            ? 'argumentsHash'
+            : null;
+      if (wrong !== null) {
+        // An answer about a different release or different arguments is not
+        // this question's answer. It is treated as a denial rather than
+        // ignored, so the caller stops waiting instead of hanging until the
+        // deadline for a question that will never be answered correctly.
+        log.warn(
+          `[broapp] an approval for ${entry.question.route} named a different ${wrong} and was refused`,
+        );
+        entry.settle(false);
+        return 'mismatch';
+      }
+
+      entry.settle(answer.approved);
+      return 'accepted';
+    },
+
+    get pending(): readonly ApprovalQuestion[] {
+      return [...waiting.values()].map((entry) => entry.question);
+    },
+  };
+}