Translation Is Not Agreement: Build a Clarification Handshake for Multilingual Chat

open
  ├── original author answers ──> resolved
  ├── source message changes ──> superseded
  └── requester cancels ───────> cancelled

pending -> sent
pending -> failed       // definitely rejected; safe to retry
pending -> uncertain    // timeout or disconnect; do not retry blindly

mkdir multilingual-clarification
cd multilingual-clarification
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src test

{
  "scripts": {
    "test": "tsx --test test/*.test.ts"
  }
}

export type ClarificationStatus =
  | "open"
  | "resolved"
  | "superseded"
  | "cancelled";

export type NoticeState =
  | "pending"
  | "sent"
  | "failed"
  | "uncertain";

export type QuestionKind =
  | "literal_meaning"
  | "tone"
  | "required_action"
  | "other";

export interface Clarification {
  id: string;
  threadId: string;
  messageId: string;
  messageRevision: number;
  requesterId: string;
  authorId: string;
  kind: QuestionKind;
  note: string;
  status: ClarificationStatus;
  notice: NoticeState;
  createdAt: number;
  answer?: string;
  resolvedAt?: number;
  closedReason?: string;
}

export interface ChatPort {
  sendText(threadId: string, text: string): Promise<void>;
}

export class ChatSendError extends Error {
  constructor(public readonly certainty: "rejected" | "unknown") {
    super(`Chat send ${certainty}`);
  }
}

export class ClarificationService {
  private readonly rows = new Map<string, Clarification>();
  private sequence = 0;

  constructor(
    private readonly chat: ChatPort,
    private readonly now: () => number = Date.now,
  ) {}

  async create(input: {
    threadId: string;
    messageId: string;
    messageRevision: number;
    requesterId: string;
    authorId: string;
    kind: QuestionKind;
    note: string;
  }): Promise<Clarification> {
    if (input.requesterId === input.authorId) {
      throw new Error("Authors do not need a clarification request to themselves");
    }

    const note = input.note.trim();
    if (note.length > 280) {
      throw new Error("Clarification note is too long");
    }

    const id = `clarification-${++this.sequence}`;
    const row: Clarification = {
      ...input,
      id,
      note,
      status: "open",
      notice: "pending",
      createdAt: this.now(),
    };

    // Persist first. Sending a chat message is an external side effect.
    this.rows.set(id, row);
    await this.deliverNotice(id);

    return this.get(id);
  }

  async deliverNotice(id: string): Promise<void> {
    const row = this.mutable(id);

    if (row.notice === "sent") return;
    if (row.notice === "uncertain") {
      throw new Error("Reconcile an uncertain send before retrying");
    }

    row.notice = "pending";

    try {
      await this.chat.sendText(
        row.threadId,
        `Clarification ${row.id} requested for message ${row.messageId}.`,
      );
      row.notice = "sent";
    } catch (error) {
      row.notice =
        error instanceof ChatSendError && error.certainty === "rejected"
          ? "failed"
          : "uncertain";
    }
  }

  resolve(input: {
    id: string;
    actorId: string;
    currentMessageRevision: number;
    answer: string;
  }): Clarification {
    const row = this.mutable(input.id);

    if (row.status !== "open") {
      throw new Error(`Cannot resolve a ${row.status} request`);
    }

    if (input.actorId !== row.authorId) {
      throw new Error("Only the original author may resolve this request");
    }

    if (input.currentMessageRevision !== row.messageRevision) {
      row.status = "superseded";
      row.closedReason = "source_message_changed";
      throw new Error("The source message changed; create a new request");
    }

    const answer = input.answer.trim();
    if (!answer) throw new Error("An answer is required");

    row.status = "resolved";
    row.answer = answer;
    row.resolvedAt = this.now();
    return this.get(row.id);
  }

  sourceRevised(messageId: string, newRevision: number): void {
    for (const row of this.rows.values()) {
      if (
        row.messageId === messageId &&
        row.status === "open" &&
        row.messageRevision !== newRevision
      ) {
        row.status = "superseded";
        row.closedReason = "source_message_changed";
      }
    }
  }

  cancel(id: string, requesterId: string): Clarification {
    const row = this.mutable(id);

    if (row.requesterId !== requesterId) {
      throw new Error("Only the requester may cancel this request");
    }
    if (row.status !== "open") {
      throw new Error(`Cannot cancel a ${row.status} request`);
    }

    row.status = "cancelled";
    row.closedReason = "requester_cancelled";
    return this.get(id);
  }

  get(id: string): Clarification {
    return { ...this.mutable(id) };
  }

  private mutable(id: string): Clarification {
    const row = this.rows.get(id);
    if (!row) throw new Error(`Unknown clarification: ${id}`);
    return row;
  }
}

import assert from "node:assert/strict";
import test from "node:test";
import {
  ChatPort,
  ChatSendError,
  ClarificationService,
} from "../src/clarifications.js";

const baseRequest = {
  threadId: "group-7",
  messageId: "message-42",
  messageRevision: 1,
  requesterId: "reader",
  authorId: "author",
  kind: "required_action" as const,
  note: "Is this optional, or should it be done today?",
};

test("only the original author can resolve a request", async () => {
  const chat: ChatPort = { sendText: async () => {} };
  const service = new ClarificationService(chat, () => 1000);
  const request = await service.create(baseRequest);

  assert.throws(
    () =>
      service.resolve({
        id: request.id,
        actorId: "another-member",
        currentMessageRevision: 1,
        answer: "It is required",
      }),
    /Only the original author/,
  );

  const resolved = service.resolve({
    id: request.id,
    actorId: "author",
    currentMessageRevision: 1,
    answer: "It is optional; tomorrow is also fine.",
  });

  assert.equal(resolved.status, "resolved");
  assert.equal(resolved.answer, "It is optional; tomorrow is also fine.");
});

test("editing the source supersedes an open request", async () => {
  const chat: ChatPort = { sendText: async () => {} };
  const service = new ClarificationService(chat);
  const request = await service.create(baseRequest);

  service.sourceRevised("message-42", 2);

  const current = service.get(request.id);
  assert.equal(current.status, "superseded");
  assert.equal(current.closedReason, "source_message_changed");
});

test("an ambiguous send failure is not retried automatically", async () => {
  let attempts = 0;
  const chat: ChatPort = {
    sendText: async () => {
      attempts += 1;
      throw new ChatSendError("unknown");
    },
  };

  const service = new ClarificationService(chat);
  const request = await service.create(baseRequest);

  assert.equal(request.status, "open");
  assert.equal(request.notice, "uncertain");
  assert.equal(attempts, 1);

  await assert.rejects(
    service.deliverNotice(request.id),
    /Reconcile an uncertain send/,
  );
  assert.equal(attempts, 1);
});

test("a definitely rejected notification can be retried", async () => {
  let attempts = 0;
  const chat: ChatPort = {
    sendText: async () => {
      attempts += 1;
      if (attempts === 1) throw new ChatSendError("rejected");
    },
  };

  const service = new ClarificationService(chat);
  const request = await service.create(baseRequest);

  assert.equal(request.notice, "failed");
  await service.deliverNotice(request.id);
  assert.equal(service.get(request.id).notice, "sent");
  assert.equal(attempts, 2);
});

npm test

Translation is not available for this message.
You can still ask the author for clarification.

await clarifications.create({
  threadId: currentThread.id,
  messageId: selectedMessage.id,
  messageRevision: selectedMessage.revision,
  requesterId: currentUser.id,
  authorId: selectedMessage.authorId,
  kind: "tone",
  note: "Does this mean you agree, or that you want more discussion?",
});

Clarification requested · Tone
“Does this mean you agree, or that you want more discussion?”
Waiting for the original author

Answered by the original author
“I agree with the direction, but not the proposed deadline.”

UPDATE clarifications
SET status = 'resolved', answer = ?, resolved_at = ?
WHERE id = ?
  AND status = 'open'
  AND author_id = ?
  AND message_revision = ?;