Build a Needs-you queue: one clarification queue every module can ask through

Define the record once, and make every module fill the same fields. The schema below maps field for field onto a human-in-the-loop work item: who asked, what it is about, the input shown, the sourced guess, the decision, the resume handle, and the audit stamp.

create table clarification_queue (
  id            uuid primary key default gen_random_uuid(),
  tenant        text not null,
  emitter       text not null,                 -- the module that asked
  reason_code   text not null,                 -- stable code, e.g. meetings.attendee_unknown
  subject_key   text not null,                 -- the thing it is about (a meeting id, a doc id)
  question      text not null,                 -- one plain sentence
  context       jsonb,                         -- { text, link }, optional
  guesses       jsonb not null default '[]',   -- [{ value, label, source }], 0 to 3
  answer_kind   text not null,                 -- 'email' | 'text' | 'choice'
  blocking      boolean not null default false,
  resume        jsonb not null,                -- opaque handle the emitter uses to finish
  status        text not null default 'open',  -- 'open' | 'answered' | 'withdrawn'
  answer        jsonb,                         -- { value, typed, who, when }
  created_at    timestamptz not null default now(),
  answered_at   timestamptz,
  unique (tenant, reason_code, subject_key)    -- the ask-once key (Step 2)
);

There is deliberately no expired status. You know it worked when a module can write a row with one call and the row carries everything the cockpit needs to render a card without going back to the module.

1

A question's identity is reason_code plus subject_key. Before you ever enqueue, check memory: if this exact thing was answered before, return the answer and enqueue nothing. If an open question with the same identity already exists, fold the new one into it rather than stacking a duplicate. That single unique constraint from Step 1 does the folding for you.

type Guess = { value: string; label: string; source: string };

export async function queueQuestion(q: {
  tenant: string; emitter: string; reasonCode: string; subjectKey: string;
  question: string; context?: { text: string; link?: string };
  guesses: Guess[]; answerKind: "email" | "text" | "choice";
  blocking?: boolean; resume: unknown;
}): Promise<{ status: "answered" | "queued"; answer?: string }> {
  // Ask once: did we answer this exact thing before?
  const known = await recallAnswer(q.tenant, q.reasonCode, q.subjectKey);
  if (known) return { status: "answered", answer: known };

  // Fold a duplicate into the question already open (the unique key no-ops the insert).
  await db.insert("clarification_queue", {
    tenant: q.tenant, emitter: q.emitter, reason_code: q.reasonCode,
    subject_key: q.subjectKey, question: q.question, context: q.context ?? null,
    guesses: q.guesses.slice(0, 3), answer_kind: q.answerKind,
    blocking: q.blocking ?? false, resume: q.resume,
  }).onConflict(["tenant", "reason_code", "subject_key"]).doNothing();

  return { status: "queued" };
}