@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/feedback/privacy.ts

@@ -0,0 +1,150 @@
+/**
+ * The two privacy primitives of anonymous feedback: screening the text for
+ * direct identifiers and secrets before it goes anywhere, and keyed
+ * pseudonyms for the user, session and message so issues can be grouped
+ * without revealing who wrote them or about which conversation.
+ */
+
+/** Direct identifiers and credentials a feedback text must not carry. */
+const DIRECT_IDENTIFIER_PATTERNS: ReadonlyArray<{
+  kind: string;
+  pattern: RegExp;
+}> = [
+  {
+    kind: 'email address',
+    pattern: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i,
+  },
+  { kind: 'Matrix identifier', pattern: /@[A-Z0-9._=-]+:[A-Z0-9.-]+/i },
+  {
+    kind: 'decentralized identifier',
+    pattern: /\bdid:[a-z0-9]+:[A-Za-z0-9._:%-]+\b/i,
+  },
+  {
+    kind: 'wallet address',
+    pattern: /\b(?:ixo|cosmos)1[0-9a-z]{20,}\b|\b0x[a-fA-F0-9]{40}\b/,
+  },
+  {
+    kind: 'credential',
+    pattern:
+      /-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:api[_ -]?key|password|secret|token|authorization)\s*[:=]\s*\S+/i,
+  },
+  {
+    kind: 'secret-bearing URL',
+    pattern:
+      /https?:\/\/\S+[?&](?:access_token|api_key|apikey|auth|key|password|secret|token)=/i,
+  },
+];
+
+/**
+ * A run of digits and phone separators, opening at the start or after a
+ * space or `(`, closing before the end, a space or punctuation. A run can
+ * hold more than one number (a date, then a phone number), so every window
+ * of its whitespace-separated pieces is checked on its own.
+ */
+const DIGIT_RUN = /(?:^|[\s(])([+(]?\d[\d\s().-]*\d\)?)(?=$|[\s.,;:)!?])/gu;
+const ISO_DATE = /^\(?\d{4}-\d{2}-\d{2}\)?$/;
+/** A grouped amount such as `1 000 000` or `1,250,000`. */
+const GROUPED_AMOUNT = /^\d{1,3}(?:[ .,]\d{3})+$/;
+/** E.164 allows 15 digits; national numbers have at least 9 with the trunk prefix. */
+const PHONE_DIGITS = { min: 9, max: 15 };
+/** Fifteen digits with every digit separated still fit: `+1 (234) 567-890-123-45` is 24. */
+const PHONE_MAX_CHARS = 40;
+
+function looksLikePhone(candidate: string): boolean {
+  if (!/^[+(]?\d/.test(candidate) || !/\d\)?$/.test(candidate)) return false;
+  const digits = candidate.replace(/\D/g, '').length;
+  return (
+    digits >= PHONE_DIGITS.min &&
+    digits <= PHONE_DIGITS.max &&
+    !GROUPED_AMOUNT.test(candidate)
+  );
+}
+
+function containsPhoneNumber(text: string): boolean {
+  for (const run of text.matchAll(DIGIT_RUN)) {
+    const pieces = run[1]!.split(/\s+/);
+    const digitCounts = pieces.map((p) => p.replace(/\D/g, '').length);
+    for (let start = 0; start < pieces.length; start += 1) {
+      let digits = 0;
+      let chars = 0;
+      for (let end = start; end < pieces.length; end += 1) {
+        // A date is never part of a phone number; wider windows keep it.
+        if (ISO_DATE.test(pieces[end]!)) break;
+        // A window past the longest possible number only grows, so stop
+        // there. Pieces of bare separators (`-`, `(`) carry no digit, hence
+        // the character bound as well: both keep the scan linear in the
+        // run's length instead of quadratic in its pieces.
+        digits += digitCounts[end]!;
+        chars += pieces[end]!.length + 1;
+        if (digits > PHONE_DIGITS.max || chars > PHONE_MAX_CHARS) break;
+        if (looksLikePhone(pieces.slice(start, end + 1).join(' '))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * What is screened is what is sent: compatibility forms folded (a fullwidth
+ * `＠` is `@`) and invisible format characters (zero-width spaces and joiners,
+ * bidi marks) removed, so neither can split an identifier past the patterns.
+ */
+function normalizeFeedbackText(raw: string): string {
+  return raw
+    .normalize('NFKC')
+    .replace(/\p{Cf}/gu, '')
+    .trim();
+}
+
+export type FeedbackScreening =
+  | { ok: true; text: string }
+  | { ok: false; reason: 'empty' }
+  | { ok: false; reason: 'personal_data'; kind: string };
+
+/**
+ * Normalise and trim the text, and reject it when it is empty or carries a direct
+ * identifier or a secret. The caller answers a rejection without saying
+ * which part matched, and never logs the text.
+ */
+export function screenFeedbackText(raw: string): FeedbackScreening {
+  const text = normalizeFeedbackText(raw);
+  if (!text) return { ok: false, reason: 'empty' };
+  const match = DIRECT_IDENTIFIER_PATTERNS.find(({ pattern }) =>
+    pattern.test(text),
+  );
+  if (match) return { ok: false, reason: 'personal_data', kind: match.kind };
+  if (containsPhoneNumber(text))
+    return { ok: false, reason: 'personal_data', kind: 'phone number' };
+  return { ok: true, text };
+}
+
+export type FingerprintNamespace = 'user' | 'session' | 'message' | 'ip';
+
+/**
+ * `<namespace>_<hex HMAC-SHA256>` over the namespace and the parts. Stable
+ * for one secret, unlinkable across namespaces, and not reversible without
+ * the secret — the same derivation the Node runtime used.
+ */
+export async function feedbackFingerprint(
+  secret: string,
+  namespace: FingerprintNamespace,
+  ...parts: string[]
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const digest = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    encoder.encode([namespace, ...parts].join('\0')),
+  );
+  const hex = Array.from(new Uint8Array(digest), (b) =>
+    b.toString(16).padStart(2, '0'),
+  ).join('');
+  return `${namespace}_${hex}`;
+}

package/src/feedback/reservation.ts

@@ -0,0 +1,298 @@
+/**
+ * The user object's half of anonymous feedback: check the message the
+ * feedback is about, apply the user's own submission limit, and keep the
+ * idempotency marker that makes one Agent message produce at most one issue.
+ *
+ * Only ids, a status and timestamps are stored — never the feedback text,
+ * which stays in the shell for the length of one request.
+ */
+import type { DoSqliteDatabase } from '../sqlite/database';
+import type { MessageDto } from '../do/transcript';
+import type {
+  FeedbackReservation,
+  FeedbackSettlement,
+  FeedbackTarget,
+} from './contract';
+
+/** Submissions one user may start per window (the Node runtime's 3 per minute). */
+export const FEEDBACK_USER_LIMIT = 3;
+export const FEEDBACK_WINDOW_MS = 60_000;
+/**
+ * A reservation the shell never settled (its isolate died mid-delivery) is
+ * reclaimed after this. Longer than the sink can take (three attempts of at
+ * most 8 s plus waits); the sink's own marker lookup stops a reclaimed
+ * delivery from creating a second issue.
+ */
+export const FEEDBACK_PENDING_STALE_MS = 2 * 60_000;
+
+interface MarkerRow extends Record<string, string | number | null> {
+  submission_id: string;
+  previous_submission_id: string | null;
+  status: string;
+  reserved_at: number;
+  submitted_at: string;
+}
+
+/**
+ * A completed Agent reply: an `ai` message of the transcript that is not
+ * part of the turn still running in the session. The listing marks every
+ * stored message complete, so the in-flight turn is told apart by position:
+ * while a run is active, everything after the last user message belongs to it.
+ */
+export function isCompletedAgentMessage(
+  messages: readonly MessageDto[],
+  messageId: string,
+  runActive: boolean,
+): boolean {
+  const index = messages.findIndex((m) => m.id === messageId);
+  const message = index === -1 ? undefined : messages[index];
+  if (!message || message.type !== 'ai' || message.isComplete === false)
+    return false;
+  return (
+    !runActive || messages.slice(index + 1).some((m) => m.type === 'human')
+  );
+}
+
+/**
+ * A column of a feedback table. `add` is the `ALTER TABLE … ADD COLUMN`
+ * definition for a column added after the table first shipped; a column
+ * without one was in the first shape (a key or NOT NULL column SQLite cannot
+ * add in place), so a table lacking it is not one this runtime made.
+ */
+interface ColumnSpec {
+  name: string;
+  add?: string;
+}
+
+const MARKER_COLUMNS: readonly ColumnSpec[] = [
+  { name: 'session_id' },
+  { name: 'message_id' },
+  { name: 'submission_id' },
+  { name: 'status' },
+  { name: 'reserved_at' },
+  { name: 'submitted_at' },
+  { name: 'previous_submission_id', add: 'TEXT' },
+];
+
+const ATTEMPT_COLUMNS: readonly ColumnSpec[] = [{ name: 'at' }];
+
+/** Add the columns an older table lacks; idempotent. */
+async function ensureColumns(
+  db: DoSqliteDatabase,
+  table: string,
+  columns: readonly ColumnSpec[],
+): Promise<void> {
+  const present = new Set(
+    (await db.exec<{ name: string }>(`PRAGMA table_info(${table})`)).map(
+      (column) => column.name,
+    ),
+  );
+  for (const column of columns) {
+    if (present.has(column.name)) continue;
+    if (column.add === undefined)
+      throw new Error(
+        `${table} lacks the column ${column.name}, which cannot be added in place`,
+      );
+    await db.run(
+      `ALTER TABLE ${table} ADD COLUMN ${column.name} ${column.add}`,
+    );
+  }
+}
+
+export class FeedbackMarkers {
+  private setupPromise: Promise<void> | undefined;
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    private readonly db: DoSqliteDatabase,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  setup(): Promise<void> {
+    this.setupPromise ??= (async () => {
+      await this.db.run(`CREATE TABLE IF NOT EXISTS message_feedback_markers (
+        session_id TEXT NOT NULL,
+        message_id TEXT NOT NULL,
+        submission_id TEXT NOT NULL,
+        -- the submission whose stale reservation this one took over, if any
+        previous_submission_id TEXT,
+        status TEXT NOT NULL CHECK (status IN ('pending', 'delivered')),
+        reserved_at INTEGER NOT NULL,
+        submitted_at TEXT NOT NULL,
+        PRIMARY KEY (session_id, message_id)
+      )`);
+      await this.db.run(`CREATE TABLE IF NOT EXISTS message_feedback_attempts (
+        at INTEGER NOT NULL
+      )`);
+      // CREATE TABLE IF NOT EXISTS leaves a table an older build created as
+      // it was: bring every column up to the current shape.
+      await ensureColumns(this.db, 'message_feedback_markers', MARKER_COLUMNS);
+      await ensureColumns(
+        this.db,
+        'message_feedback_attempts',
+        ATTEMPT_COLUMNS,
+      );
+    })().catch((error: unknown) => {
+      this.setupPromise = undefined;
+      throw error;
+    });
+    return this.setupPromise;
+  }
+
+  /** Reservations and settlements run one at a time. */
+  private serialize<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.queue.then(work);
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+
+  /**
+   * Reserve delivery for a message the caller has already validated. A
+   * replay of the delivered submission answers with it again; other
+   * feedback for the same message is a conflict; only a fresh reservation
+   * counts against the user's limit.
+   */
+  reserve(
+    target: FeedbackTarget,
+  ): Promise<Exclude<FeedbackReservation, { kind: 'not_found' }>> {
+    return this.serialize(async () => {
+      await this.setup();
+      return this.db.transaction(async () => {
+        const now = this.now();
+        const existing = await this.db.get<MarkerRow>(
+          `SELECT submission_id, previous_submission_id, status, reserved_at, submitted_at
+             FROM message_feedback_markers
+            WHERE session_id = ? AND message_id = ?`,
+          [target.sessionId, target.messageId],
+        );
+        if (existing?.status === 'delivered')
+          return existing.submission_id === target.submissionId
+            ? { kind: 'delivered', submittedAt: existing.submitted_at }
+            : { kind: 'conflict' };
+        const sameSubmission = existing?.submission_id === target.submissionId;
+        if (existing && now - existing.reserved_at < FEEDBACK_PENDING_STALE_MS)
+          return sameSubmission ? { kind: 'in_flight' } : { kind: 'conflict' };
+
+        await this.db.run(
+          'DELETE FROM message_feedback_attempts WHERE at <= ?',
+          [now - FEEDBACK_WINDOW_MS],
+        );
+        const recent = await this.db.get<{ n: number }>(
+          'SELECT COUNT(*) AS n FROM message_feedback_attempts',
+        );
+        if ((recent?.n ?? 0) >= FEEDBACK_USER_LIMIT)
+          return { kind: 'rate_limited' };
+        await this.db.run(
+          'INSERT INTO message_feedback_attempts (at) VALUES (?)',
+          [now],
+        );
+
+        // A stale reservation of another submission may have created the
+        // issue before its isolate died; remember whose it was, so the shell
+        // never reports this submission as delivered when it sent nothing.
+        const previous = existing
+          ? sameSubmission
+            ? existing.previous_submission_id
+            : existing.submission_id
+          : null;
+        const submittedAt = new Date(now).toISOString();
+        await this.db.run(
+          `INSERT OR REPLACE INTO message_feedback_markers
+             (session_id, message_id, submission_id, previous_submission_id,
+              status, reserved_at, submitted_at)
+           VALUES (?, ?, ?, ?, 'pending', ?, ?)`,
+          [
+            target.sessionId,
+            target.messageId,
+            target.submissionId,
+            previous,
+            now,
+            submittedAt,
+          ],
+        );
+        return {
+          kind: 'reserved',
+          submittedAt,
+          replacesOtherSubmission: previous !== null,
+        };
+      });
+    });
+  }
+
+  /**
+   * Settle this submission's reservation:
+   * - `delivered`: its issue exists — the marker is kept for good;
+   * - `superseded`: the issue that exists is the earlier submission's, so
+   *   the marker is kept under that submission and this one becomes a
+   *   conflict on any retry;
+   * - `released`: delivery failed — the marker is removed so the user can
+   *   try again.
+   */
+  settle(target: FeedbackTarget, outcome: FeedbackSettlement): Promise<void> {
+    return this.serialize(async () => {
+      await this.setup();
+      const match = [target.sessionId, target.messageId, target.submissionId];
+      switch (outcome) {
+        case 'delivered':
+          await this.db.run(
+            `UPDATE message_feedback_markers SET status = 'delivered'
+              WHERE session_id = ? AND message_id = ? AND submission_id = ?`,
+            match,
+          );
+          return;
+        case 'superseded':
+          await this.db.run(
+            `UPDATE message_feedback_markers
+                SET status = 'delivered',
+                    submission_id = COALESCE(previous_submission_id, submission_id)
+              WHERE session_id = ? AND message_id = ? AND submission_id = ?`,
+            match,
+          );
+          return;
+        case 'released':
+          await this.db.run(
+            `DELETE FROM message_feedback_markers
+              WHERE session_id = ? AND message_id = ? AND submission_id = ?
+                AND status = 'pending'`,
+            match,
+          );
+          return;
+      }
+    });
+  }
+
+  /** A deleted session's markers go with it. */
+  forgetSession(sessionId: string): Promise<void> {
+    return this.serialize(async () => {
+      await this.setup();
+      await this.db.run(
+        'DELETE FROM message_feedback_markers WHERE session_id = ?',
+        [sessionId],
+      );
+    });
+  }
+}
+
+/** What {@link reserveFeedback} needs from the user object. */
+export interface FeedbackReservationHost {
+  sessionExists(sessionId: string): Promise<boolean>;
+  transcript(sessionId: string): Promise<MessageDto[]>;
+  runActive(sessionId: string): Promise<boolean>;
+  markers: FeedbackMarkers;
+}
+
+/** Validate the target against the user's own database, then reserve. */
+export async function reserveFeedback(
+  host: FeedbackReservationHost,
+  target: FeedbackTarget,
+): Promise<FeedbackReservation> {
+  if (!(await host.sessionExists(target.sessionId)))
+    return { kind: 'not_found' };
+  const [messages, runActive] = await Promise.all([
+    host.transcript(target.sessionId),
+    host.runActive(target.sessionId),
+  ]);
+  if (!isCompletedAgentMessage(messages, target.messageId, runActive))
+    return { kind: 'not_found' };
+  return host.markers.reserve(target);
+}

package/src/feedback/submit.ts

@@ -0,0 +1,247 @@
+/**
+ * `POST /messages/:sessionId/:messageId/feedback`, after authentication:
+ * validate, rate-limit, screen, reserve with the user's object, deliver to
+ * the sink, settle. The feedback text lives only in this request — it is
+ * never logged, never stored in the user's database and never sent to the
+ * user object.
+ */
+import type { TurnIdentity } from '../do/contracts';
+import type { FeedbackConfig } from './config';
+import {
+  FeedbackSubmission,
+  type FeedbackDelivery,
+  type FeedbackReservation,
+  type FeedbackResponse,
+  type FeedbackSettlement,
+  type FeedbackSink,
+  type FeedbackTarget,
+} from './contract';
+import { LinearFeedbackError } from './linear-sink';
+import { feedbackFingerprint, screenFeedbackText } from './privacy';
+
+/** What the shell needs to serve the route; absent = the feature is off. */
+export interface FeedbackShellOptions {
+  config: FeedbackConfig;
+  sink: FeedbackSink;
+}
+
+/** The user object's feedback RPCs (`UserOracleDO`). */
+export interface FeedbackUserObject {
+  reserveMessageFeedback(
+    identity: TurnIdentity,
+    target: FeedbackTarget,
+  ): Promise<FeedbackReservation>;
+  settleMessageFeedback(
+    identity: TurnIdentity,
+    target: FeedbackTarget,
+    outcome: FeedbackSettlement,
+  ): Promise<void>;
+}
+
+export interface FeedbackLog {
+  info(message: string): void;
+  warn(message: string): void;
+}
+
+export interface SubmitFeedbackInput {
+  options: FeedbackShellOptions;
+  user: FeedbackUserObject;
+  identity: TurnIdentity;
+  sessionId: string;
+  messageId: string;
+  /** The parsed JSON body, or undefined when it was not JSON. */
+  body: unknown;
+  /** `cf-connecting-ip`; only its keyed pseudonym is used. */
+  clientIp: string | undefined;
+  ipLimiter: RateLimit | undefined;
+  log: FeedbackLog;
+}
+
+/** Machine-readable reasons, so clients branch without matching messages. */
+export type FeedbackErrorCode =
+  | 'FEEDBACK_DISABLED'
+  | 'FEEDBACK_INVALID'
+  | 'FEEDBACK_EMPTY'
+  | 'FEEDBACK_TARGET_NOT_FOUND'
+  | 'FEEDBACK_IN_FLIGHT'
+  | 'FEEDBACK_ALREADY_SUBMITTED'
+  | 'FEEDBACK_CONTAINS_PERSONAL_DATA'
+  | 'FEEDBACK_RATE_LIMITED'
+  | 'FEEDBACK_DELIVERY_FAILED';
+
+export interface FeedbackErrorBody {
+  statusCode: number;
+  code: FeedbackErrorCode;
+  message: string;
+  retryable: boolean;
+}
+
+export type FeedbackHttpResult =
+  | { status: 200; body: FeedbackResponse }
+  | { status: 400 | 404 | 409 | 422 | 429 | 502; body: FeedbackErrorBody };
+
+export function feedbackFailure(
+  status: 400 | 404 | 409 | 422 | 429 | 502,
+  code: FeedbackErrorCode,
+  message: string,
+  retryable = false,
+): { status: typeof status; body: FeedbackErrorBody } {
+  return { status, body: { statusCode: status, code, message, retryable } };
+}
+
+const RATE_LIMITED = 'Too many feedback attempts. Please try again later.';
+
+function errorName(error: unknown): string {
+  return error instanceof Error ? error.name : 'unknown error';
+}
+
+export async function submitFeedback(
+  input: SubmitFeedbackInput,
+): Promise<FeedbackHttpResult> {
+  const { options, identity, sessionId, messageId, log } = input;
+  const { config, sink } = options;
+  const parsed = FeedbackSubmission.safeParse(input.body);
+  if (!parsed.success)
+    return feedbackFailure(
+      400,
+      'FEEDBACK_INVALID',
+      'Invalid feedback submission',
+    );
+  const { submissionId, context } = parsed.data;
+
+  if (input.ipLimiter) {
+    const ipKey = await feedbackFingerprint(
+      config.hmacSecret,
+      'ip',
+      input.clientIp ?? 'unknown',
+    );
+    if (!(await input.ipLimiter.limit({ key: `feedback:${ipKey}` })).success)
+      return feedbackFailure(429, 'FEEDBACK_RATE_LIMITED', RATE_LIMITED, true);
+  }
+
+  const screened = screenFeedbackText(parsed.data.feedback);
+  if (!screened.ok)
+    return screened.reason === 'empty'
+      ? feedbackFailure(400, 'FEEDBACK_EMPTY', 'Feedback cannot be empty')
+      : feedbackFailure(
+          422,
+          'FEEDBACK_CONTAINS_PERSONAL_DATA',
+          'Remove personal information, account identifiers, or secrets before submitting feedback',
+        );
+
+  const target: FeedbackTarget = { sessionId, messageId, submissionId };
+  const reservation = await input.user.reserveMessageFeedback(identity, target);
+  const submitted = (submittedAt: string): FeedbackHttpResult => ({
+    status: 200,
+    body: { submissionId, status: 'submitted', submittedAt },
+  });
+  const alreadySubmitted = feedbackFailure(
+    409,
+    'FEEDBACK_ALREADY_SUBMITTED',
+    'Feedback for this message was already submitted',
+  );
+  switch (reservation.kind) {
+    case 'not_found':
+      return feedbackFailure(
+        404,
+        'FEEDBACK_TARGET_NOT_FOUND',
+        'Completed Agent message not found',
+      );
+    case 'rate_limited':
+      return feedbackFailure(429, 'FEEDBACK_RATE_LIMITED', RATE_LIMITED, true);
+    case 'in_flight':
+      return feedbackFailure(
+        409,
+        'FEEDBACK_IN_FLIGHT',
+        'This feedback is being delivered; retry shortly with the same submissionId',
+        true,
+      );
+    case 'conflict':
+      return alreadySubmitted;
+    case 'delivered':
+      return submitted(reservation.submittedAt);
+    case 'reserved':
+      break;
+  }
+
+  const { userDid } = identity;
+  const [userPseudonym, sessionFingerprint, messageFingerprint] =
+    await Promise.all([
+      feedbackFingerprint(config.hmacSecret, 'user', userDid),
+      feedbackFingerprint(config.hmacSecret, 'session', userDid, sessionId),
+      feedbackFingerprint(
+        config.hmacSecret,
+        'message',
+        userDid,
+        sessionId,
+        messageId,
+      ),
+    ]);
+  let delivery: FeedbackDelivery;
+  try {
+    delivery = await sink.submit({
+      submissionId,
+      feedback: screened.text,
+      submittedAt: reservation.submittedAt,
+      userPseudonym,
+      sessionFingerprint,
+      messageFingerprint,
+      agent: config.agent,
+      context,
+    });
+  } catch (error) {
+    // The sink's own errors carry a status and code only; anything else is
+    // reduced to its class name so no upstream detail reaches the logs.
+    log.warn(
+      `[feedback] delivery failed: ${error instanceof LinearFeedbackError ? error.message : errorName(error)}`,
+    );
+    await input.user
+      .settleMessageFeedback(identity, target, 'released')
+      .catch((settleError: unknown) =>
+        log.warn(
+          `[feedback] could not release the reservation: ${errorName(settleError)}`,
+        ),
+      );
+    return feedbackFailure(
+      502,
+      'FEEDBACK_DELIVERY_FAILED',
+      'Feedback could not be delivered. Please try again.',
+      true,
+    );
+  }
+
+  // This reservation took over a stale one of another submission, and the
+  // issue was already there: it is that submission's, and this text was not
+  // sent. Answer like any other second feedback for the message.
+  const superseded =
+    reservation.replacesOtherSubmission && delivery === 'existing';
+  // The issue exists either way; a settle that fails leaves a pending marker
+  // that a retry reclaims once stale, and the sink finds the issue then.
+  await input.user
+    .settleMessageFeedback(
+      identity,
+      target,
+      superseded ? 'superseded' : 'delivered',
+    )
+    .catch((settleError: unknown) =>
+      log.warn(
+        `[feedback] could not settle the reservation: ${errorName(settleError)}`,
+      ),
+    );
+  if (superseded) {
+    log.info('[feedback] an earlier submission already delivered the issue');
+    return alreadySubmitted;
+  }
+  log.info('[feedback] issue delivered');
+  return submitted(reservation.submittedAt);
+}
+
+/**
+ * Splice the capability flag into a transcript response the user object
+ * already serialised (`{"messages":...}` or a page), without re-parsing it.
+ */
+export function withFeedbackCapability(json: string, enabled: boolean): string {
+  if (!enabled || !json.startsWith('{')) return json;
+  const rest = json.slice(1).trimStart();
+  return `{"capabilities":{"anonymousMessageFeedback":true}${rest.startsWith('}') ? '' : ','}${rest}`;
+}