@open-everywhere/core 0.1.0

package/agent/channels/rate-limit-retry.ts

@@ -0,0 +1,355 @@
+// rate-limit-retry — the ONE 429 and `Retry-After` backoff a provider write seam wraps its HTTP call in. It lives in CORE because no provider package here depends on a vendor SDK, so no vendor retry policy applies anywhere and one shared primitive keeps the six seams from growing six different answers.
+// A response that is NOT a rate-limit refusal comes back unchanged; a refusal waits the delay its `Retry-After` names, capped per wait and bounded in attempts, and an exhausted retry throws a NAMED error so it can never read as an empty answer or a silent drop. It does not pace calls ahead of a refusal, and it never retries a request the vendor never answered — such a request MAY have applied, so repeating it could double a post.
+
+/** The HTTP status every vendor in this repo uses for a rate-limit refusal. */
+export const RATE_LIMITED_STATUS = 429;
+
+/** The ordinary "you are not allowed to do this" status — and GitHub's SECOND spelling of a
+ *  rate-limit refusal. See {@link isRateLimitedForbidden} for why those two need separating. */
+const FORBIDDEN_STATUS = 403;
+
+/**
+ * Does this 403 prove itself a RATE-LIMIT refusal rather than a permission refusal? A BARE 403 IS A REFUSAL, EVERYWHERE, ALWAYS — retrying a genuine permission denial is a hot loop against an API that already said no — so this answers true for exactly ONE shape: a 403 carrying a `Retry-After` the shared parser can read. The vendor's other documented marker resets up to an hour away, which no bounded budget can reach, so it stays a refusal.
+ * THE LIVE RESIDUAL, stated where the code is: the `Retry-After`-bearing 403 rests on an assumption this repo has NOT measured — that a genuine permission denial never carries one. An intermediary answering 403 with its own header would be retried, at a bounded cost of a few refused calls and then a named failure; the predicate can equally UNDER-fire, leaving the seam exactly as it was. Do not widen it from documentation alone.
+ */
+export function isRateLimitedForbidden(res: RetryableResponse, nowMs: number): boolean {
+  if (res.status !== FORBIDDEN_STATUS) return false;
+  return parseRetryAfterMs(res.headers.get("retry-after"), nowMs) !== undefined;
+}
+
+/** Total attempts, the first call included. 4 attempts ⇒ at most 3 waits. */
+export const DEFAULT_MAX_ATTEMPTS = 4;
+
+/** The ceiling on ONE wait. A vendor may name a `Retry-After` of minutes; a write path that blocks
+ *  that long is worse for the caller than a named failure it can act on. */
+export const DEFAULT_CAP_MS = 30_000;
+
+/**
+ * The ceiling on the TOTAL wait across one call's retries. READ THE ARITHMETIC BEFORE CHANGING A DEFAULT: attempts and the per-wait cap alone do not bound latency, and a caller that retries the whole call spends the budget again.
+ * A latency-critical caller must therefore pass its own tighter policy rather than trust these defaults — the identity probe that sits on a vendor's short event-ack path does exactly that.
+ */
+export const DEFAULT_TOTAL_BUDGET_MS = 60_000;
+
+/** The wait used when a 429 carries no usable `Retry-After`. The header is mandatory on Slack and
+ *  usual elsewhere, so this is a floor for a malformed answer, not the normal path. */
+export const DEFAULT_FALLBACK_MS = 1_000;
+
+/**
+ * The NAMED failure an exhausted retry produces. NAMING IT DOES NOT MAKE IT LOUD: a caller that catches everything still catches this, and it leaves no trace unless that caller logs it — so a fail-soft caller must log it by name, or the drop IS silent.
+ * Every field is safe to log: no token, no body, no personal data.
+ */
+export class RateLimitExhaustedError extends Error {
+  /** The refusal's HTTP status, so a failure classifier reads the same 429 a vendor error carried.
+   *  `channels/platform-failure.ts` treats 429 as AMBIGUOUS — an unanswered write may have applied. */
+  readonly status = RATE_LIMITED_STATUS;
+  /**
+   * The status the vendor ACTUALLY sent on the last refusal — 429, or 403 on a seam that opted in.
+   * `status` above stays 429 ON PURPOSE: it is what a failure classifier reads, and this error always MEANS "rate limited" whatever spelling the vendor used, so reporting 403 there would route a rate-limit exhaustion into the permission-denied arm.
+   */
+  readonly refusalStatus: number;
+  /** The provider surface, e.g. `slack`. */
+  readonly surface: string;
+  /** The vendor operation, e.g. `chat.postMessage`. */
+  readonly operation: string;
+  /** Attempts made, the first call included. */
+  readonly attempts: number;
+  /** The total time spent waiting across every honoured `Retry-After`. */
+  readonly waitedMs: number;
+
+  constructor(init: { surface: string; operation: string; attempts: number; waitedMs: number; refusalStatus?: number }) {
+    super(
+      `${init.surface} ${init.operation} stayed rate limited after ${init.attempts} attempts ` +
+        `(waited ${init.waitedMs} ms across the honoured Retry-After delays).`,
+    );
+    this.name = "RateLimitExhaustedError";
+    this.surface = init.surface;
+    this.operation = init.operation;
+    this.attempts = init.attempts;
+    this.waitedMs = init.waitedMs;
+    this.refusalStatus = init.refusalStatus ?? RATE_LIMITED_STATUS;
+  }
+}
+
+/**
+ * Read a `Retry-After` header value as milliseconds. RFC 9110 allows two forms and a vendor uses either: delta-seconds, and an HTTP-date, which is a delay only relative to `nowMs`.
+ * It answers undefined when the header is absent, empty, or in neither form, so a caller uses its own fallback rather than guessing a delay from a value it could not read. A past HTTP-date clamps to 0, because the vendor says the wait is over.
+ */
+export function parseRetryAfterMs(value: string | null | undefined, nowMs: number): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  const raw = value.trim();
+  if (raw.length === 0) return undefined;
+  // Integer seconds. The pattern rejects a sign and a fraction on purpose: neither is delta-seconds,
+  // and `Number("-5")` would otherwise produce a negative delay.
+  if (/^\d+$/.test(raw)) return Number(raw) * 1000;
+  // GUARD THE DATE BRANCH BEFORE `Date.parse` SEES IT: it is far more permissive than HTTP-date and reads a bare "-5" as a date, which lands in the past and clamps to a ZERO delay — a hot loop against an API that just asked us to slow down, and strictly worse than the caller's fallback.
+  // All three HTTP-date formats RFC 9110 allows start with a day name, so anything that does not is not a date.
+  if (!/^[A-Za-z]{3,9},? /.test(raw)) return undefined;
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) return undefined;
+  return Math.max(0, at - nowMs);
+}
+
+/**
+ * The subset of a response this primitive reads — a status, a header lookup, and an optionally-cancellable body. Every real `Response` satisfies it, as does a `{ok, status, text, json}` vendor fetch shape once that shape also carries a `headers` accessor.
+ * Generic over `T`, so a caller gets back the EXACT response type it sent in and `res.ok` and `res.json()` keep working unchanged downstream.
+ */
+export interface RetryableResponse {
+  readonly status: number;
+  readonly headers: { get(name: string): string | null };
+  readonly body?: { cancel(): Promise<unknown> } | null;
+}
+
+/**
+ * One refusal, reported to an observer so a caller can AUDIT its own retries. Every field is an id, a count or a duration — the same log-safe discipline {@link RateLimitExhaustedError} states for itself.
+ * It is the ONLY way a caller learns a retry happened at all: the primitive returns the first non-refused answer and says nothing about the attempts behind it, so a path whose retries must leave a trace reads them here.
+ */
+export interface RateLimitRefusal {
+  /** The provider surface, e.g. `slack`. */
+  readonly surface: string;
+  /** The vendor operation, e.g. `chat.postMessage`. */
+  readonly operation: string;
+  /** Which attempt was refused, the first call counted as 1. */
+  readonly attempt: number;
+  /** The status the vendor actually sent — 429, or 403 on a seam that opted in. */
+  readonly refusalStatus: number;
+  /** The wait about to be honoured. ZERO when `outcome` is `"exhausted"`: nothing is waited then. */
+  readonly delayMs: number;
+  /** The total already waited BEFORE this refusal, across the honoured delays. */
+  readonly waitedMs: number;
+  /** `"retrying"` ⇒ the wait below happens and the call is repeated. `"exhausted"` ⇒ the attempts
+   *  or the total budget are spent, and {@link RateLimitExhaustedError} is thrown instead. */
+  readonly outcome: "retrying" | "exhausted";
+}
+
+/** The seams a test drives instead of the clock and the network. */
+export interface RateLimitRetryOptions {
+  /** The provider surface, for the named failure. */
+  readonly surface: string;
+  /** The vendor operation, for the named failure. */
+  readonly operation: string;
+  /** Total attempts, the first call included. Defaults to {@link DEFAULT_MAX_ATTEMPTS}. */
+  readonly maxAttempts?: number;
+  /** The ceiling on ONE wait. Defaults to {@link DEFAULT_CAP_MS}. */
+  readonly capMs?: number;
+  /** The wait for a 429 with no usable `Retry-After`. Defaults to {@link DEFAULT_FALLBACK_MS}. */
+  readonly fallbackMs?: number;
+  /** The ceiling on the TOTAL wait for this call. Defaults to {@link DEFAULT_TOTAL_BUDGET_MS}. A
+   *  retry whose wait would exceed what is left gives up NOW rather than overrunning the budget. */
+  readonly totalBudgetMs?: number;
+  /** The sleep. A test injects one that records the delay instead of waiting it. */
+  readonly sleep?: (ms: number) => Promise<void>;
+  /** The clock, read only to turn an HTTP-date `Retry-After` into a delay. */
+  readonly now?: () => number;
+  /**
+   * An override that reads the honoured delay from somewhere OTHER than the `Retry-After` header — the response BODY, for a vendor that states its delay there. It runs ONLY for a response already judged a rate-limit refusal; a finite, non-negative answer WINS over the header; and it MUST NOT throw, because a body it cannot read answers `undefined` and falls back to the header.
+   * FUNNEL-FIXED, not a caller policy: a seam sets it once for its vendor, which is why it is deliberately absent from {@link RetryPolicy}. A reader that reads the body MUST read a CLONE — the primitive cancels the original body after this returns.
+   */
+  readonly retryAfterMs?: (res: RetryableResponse) => number | undefined | Promise<number | undefined>;
+  /**
+   * PER-SEAM OPT-IN: also honour a 403 that proves itself a rate-limit refusal. It is OFF BY DEFAULT AND MUST STAY THAT WAY, because a 403 is the ordinary spelling of a permission denial on every provider that uses this primitive, and widening it would change the contract for all of them.
+   * When true, a 403 is retried ONLY when {@link isRateLimitedForbidden} says so; a bare 403 comes back unchanged on EVERY seam, this one included. FUNNEL-FIXED and absent from {@link RetryPolicy}, so a caller tuning attempts or waits can never turn a permission refusal into a retry.
+   */
+  readonly retryForbiddenWithRetryAfter?: boolean;
+  /**
+   * Called once per refusal, BEFORE the wait it describes — so a row it writes survives a process that dies during the sleep, which is the incident an operator most needs the row for.
+   * AWAITED. On a RETRYING refusal that costs the call nothing: the only thing it delays is a sleep that was about to happen anyway. On the EXHAUSTED refusal there is no sleep left, so it delays the THROW by one observer round trip — the price of a row that outlives the failure. It MUST NOT throw; a rejection is caught and dropped here, because an observer is never allowed to fail the call it observes.
+   * FUNNEL-FIXED like {@link retryAfterMs} and deliberately absent from {@link RetryPolicy}: a caller tuning attempts or waits must not be able to attach or remove a seam's audit trail.
+   */
+  readonly onRefusal?: (refusal: RateLimitRefusal) => void | Promise<void>;
+}
+
+/**
+ * The tunable half of {@link RateLimitRetryOptions} — everything except the NAMED `surface` and `operation`, which a funnel fixes per call site rather than leaving to its caller.
+ * This is the shape a write seam exposes as its own `retry?:` option, so a caller can tighten the policy, or a test inject a stub clock, without the funnel itself taking `surface`/`operation` as caller-settable.
+ */
+export type RetryPolicy = Pick<RateLimitRetryOptions, "maxAttempts" | "capMs" | "fallbackMs" | "totalBudgetMs" | "sleep" | "now">;
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Call `send`, honouring a rate-limit refusal's `Retry-After` up to a bounded number of attempts. It returns the FIRST response that is not a rate-limit refusal — whatever that response is.
+ * A refusal is a 429, and on a seam that sets `retryForbiddenWithRetryAfter` also a 403 carrying a readable `Retry-After`. It throws {@link RateLimitExhaustedError} when the last allowed attempt is still refused.
+ */
+export async function withRetryAfter<T extends RetryableResponse>(send: () => Promise<T>, opts: RateLimitRetryOptions): Promise<T> {
+  const maxAttempts = Math.max(1, Math.floor(opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS));
+  const capMs = Math.max(0, opts.capMs ?? DEFAULT_CAP_MS);
+  const fallbackMs = Math.max(0, opts.fallbackMs ?? DEFAULT_FALLBACK_MS);
+  const totalBudgetMs = Math.max(0, opts.totalBudgetMs ?? DEFAULT_TOTAL_BUDGET_MS);
+  const sleep = opts.sleep ?? defaultSleep;
+  const now = opts.now ?? Date.now;
+
+  let waitedMs = 0;
+  for (let attempt = 1; ; attempt += 1) {
+    const res = await send();
+    // A 429 is a rate-limit refusal on every seam. A 403 is one ONLY on a seam that opted in, and
+    // only when the response proves it (OPE-1256) — a bare 403 stays a refusal and returns unchanged
+    // here, exactly as it did before the flag existed.
+    const rateLimited =
+      res.status === RATE_LIMITED_STATUS || ((opts.retryForbiddenWithRetryAfter ?? false) && isRateLimitedForbidden(res, now()));
+    if (!rateLimited) return res;
+    // This refusal is discarded either way. Read the honoured delay BEFORE releasing the body: a vendor may state the delay in the BODY as well as the header, and its body value wins.
+    // The override reads a CLONE, so the cancel below still frees the original body. A body override that yields nothing, or an unusable value, falls back to the header — the same answer an unreadable header gives.
+    let named = opts.retryAfterMs ? await opts.retryAfterMs(res) : undefined;
+    if (named === undefined || !Number.isFinite(named) || named < 0) {
+      named = parseRetryAfterMs(res.headers.get("retry-after"), now());
+    }
+    void res.body?.cancel().catch(() => undefined);
+    const delayMs = Math.min(capMs, named ?? fallbackMs);
+    // Give up NOW when the attempts are spent, or when this wait would overrun the total budget.
+    // Checking BEFORE the sleep is what makes the budget a real ceiling: waiting first and then
+    // discovering the overrun would spend exactly the time the budget exists to refuse.
+    const exhausted = attempt >= maxAttempts || waitedMs + delayMs > totalBudgetMs;
+    // The observer sees EVERY refusal, the last one included, and it runs before the wait — see
+    // `onRefusal`. Its own failure is dropped: an audit row must never turn a retryable call into a
+    // failed one, which is the same posture every audit call on the wake path already takes.
+    if (opts.onRefusal) {
+      try {
+        await opts.onRefusal({
+          surface: opts.surface,
+          operation: opts.operation,
+          attempt,
+          refusalStatus: res.status,
+          delayMs: exhausted ? 0 : delayMs,
+          waitedMs,
+          outcome: exhausted ? "exhausted" : "retrying",
+        });
+      } catch {
+        /* an observer never fails the call it observes */
+      }
+    }
+    if (exhausted) {
+      throw new RateLimitExhaustedError({
+        surface: opts.surface,
+        operation: opts.operation,
+        attempts: attempt,
+        waitedMs,
+        refusalStatus: res.status,
+      });
+    }
+    waitedMs += delayMs;
+    await sleep(delayMs);
+  }
+}
+
+/**
+ * `withRetryAfter` for a `{ok, status, text, json}` vendor fetch shape whose OWN declared type carries no `headers`. At RUNTIME every one of those shapes' production value is the real `fetch`, whose `Response` already carries them, so this reads them when present and honours a refusal exactly as {@link withRetryAfter} does; a genuinely header-less response retries on the fallback wait, the same answer an unreadable header gives.
+ * It wraps the header-less response in a `Proxy` rather than spreading it, because a shallow copy takes only own enumerable properties and would silently drop `text`/`json` from a class instance. The shared fetch types are not widened instead: both are used far beyond these seams, and a required `headers` field would force every untouched test fake to grow one just to keep compiling.
+ */
+export function withRetryAfterLoose<T extends { readonly status: number }>(
+  send: () => Promise<T>,
+  opts: RateLimitRetryOptions,
+): Promise<T> {
+  return withRetryAfter(async () => {
+    const res = await send();
+    const existing = (res as { headers?: unknown }).headers;
+    if (existing !== null && typeof existing === "object" && typeof (existing as { get?: unknown }).get === "function") {
+      return res as T & RetryableResponse;
+    }
+    // A `Proxy` rather than `{...res, headers: ...}`: a shallow spread copies only OWN enumerable
+    // properties, which would silently drop `text`/`json` for a response whose methods live on a
+    // prototype (a class instance). The proxy overrides only `headers` and delegates everything
+    // else to `res`, binding a delegated function to `res` so its `this` still resolves correctly
+    // when called through the proxy.
+    const noHeaders: { get(name: string): string | null } = { get: () => null };
+    const withHeaders = new Proxy(res as object, {
+      get(target, prop, receiver) {
+        if (prop === "headers") return noHeaders;
+        const value = Reflect.get(target, prop, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+    return withHeaders as T & RetryableResponse;
+  }, opts);
+}
+
+// ── THE THROWN SPELLING OF A REFUSAL ───────────────────────────────────────────────────────────
+// Everything above reads a RESPONSE. A caller that never sees one reads a THROW instead — a client
+// that has already turned the vendor's 429 into an error class before OE gets the answer. The WAKE
+// DISPATCH is that caller: eve's queue client maps a 429 on its `send message` POST to a
+// `TooManyRequestsError` and throws it, so a wake refused by the queue reached OE as an exception
+// with no status to read (OPE-1871). It is the same refusal, so it takes the same road rather than
+// a second one: the adapter below turns the throw into the response shape the loop above already
+// knows, and every bound — attempts, the per-wait cap, the total budget, the named failure — is that
+// loop's, unchanged.
+
+/** The error-class name a vendor client gives a 429 it has already thrown. eve's queue client is the one this repo meets; the constant is matched against `err.name`, which is a CLASS identity, not the message prose `platform-failure.ts` refuses to read. */
+const RATE_LIMIT_THROW_NAME = "TooManyRequestsError";
+
+/** How far up a `cause` chain the classifier looks. A re-wrap is one or two links deep; a bound keeps a cyclic `cause` from spinning. */
+const MAX_CAUSE_DEPTH = 5;
+
+/** The matched link of a `cause` chain, or undefined when nothing on it is a rate-limit refusal. */
+function rateLimitThrowLink(err: unknown): { readonly retryAfterMs?: number } | undefined {
+  let node: unknown = err;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && node !== null && typeof node === "object"; depth += 1) {
+    const e = node as { status?: unknown; name?: unknown; retryAfter?: unknown; cause?: unknown };
+    if (e.status === RATE_LIMITED_STATUS || e.name === RATE_LIMIT_THROW_NAME) {
+      // The vendor client states its delay in SECONDS on the error, the same unit `Retry-After`
+      // carries. Absent, negative or unparseable ⇒ no reading, and the caller's fallback decides —
+      // the same answer an unreadable header gives a response-shaped refusal.
+      const secs = e.retryAfter;
+      return typeof secs === "number" && Number.isFinite(secs) && secs >= 0 ? { retryAfterMs: secs * 1000 } : {};
+    }
+    node = e.cause;
+  }
+  return undefined;
+}
+
+/**
+ * Does this THROWN error prove itself a rate-limit refusal? Two SHAPES answer yes, never a word in the message: a numeric `status` of 429 (what an OE arm stamps, `channels/platform-failure.ts`), and the vendor client's own error-class `name`. A `cause` chain is walked, because a re-wrap keeps the class of the error it wraps only in that chain.
+ * Everything else — a transport throw, a 5xx, a permission refusal — answers false and is rethrown untouched by {@link withRetryAfterThrown}, exactly as a non-refusal response comes back unchanged above.
+ */
+export function isRateLimitThrow(err: unknown): boolean {
+  return rateLimitThrowLink(err) !== undefined;
+}
+
+/** One attempt of a thrown-shape call, dressed as the response the shared loop reads. */
+interface ThrownAttempt<T> extends RetryableResponse {
+  /** Present on the attempt that SETTLED — a one-element tuple, so a `run` that resolves `undefined` is still tellable apart from an attempt that never settled at all. */
+  readonly settled?: readonly [T];
+  /** The delay the thrown refusal named, in milliseconds. Read through the loop's own `retryAfterMs` override. */
+  readonly retryAfterMs?: number;
+}
+
+/** The status a settled attempt reports — anything that is not a refusal ends the loop, and 200 is the plainest such answer. */
+const SETTLED_STATUS = 200;
+
+/** A synthetic attempt carries no headers: a thrown refusal states its delay on the error, never in a header this adapter could read. */
+const NO_HEADERS: { get(name: string): string | null } = { get: () => null };
+
+/**
+ * {@link withRetryAfter} for a call that THROWS its rate-limit refusal instead of returning one. It returns whatever `run` resolves, on the first attempt that is not a refusal.
+ * A refusal is what {@link isRateLimitThrow} says it is; EVERY other rejection propagates unchanged, on the first attempt, so a permission denial and a transport throw keep their exact behaviour. An exhausted retry throws the same {@link RateLimitExhaustedError} a response-shaped one does, so a caller's failure classifier reads the same 429 either way.
+ * `retryAfterMs` is OWNED BY THIS ADAPTER — a thrown refusal states its delay on the error, not in a body — so a value a caller passes in `opts` is ignored. Nothing needs one today; the line is here so a seam that tries does not debug a silently dropped reader.
+ *
+ * 🔴 WHAT IS REPEATED IS THE WHOLE `run` CLOSURE, not a vendor call. Two things follow, and a caller owes both:
+ *  • THE VENDOR CALL is safe to repeat exactly because a refusal is an ANSWER: the primitive above never repeats a request the vendor left UNanswered — such a request may have applied — and a 429 is the vendor saying it did NOT take the call.
+ *  • EVERYTHING ELSE INSIDE THE CLOSURE RUNS AGAIN, so the closure must be RE-RUNNABLE. `divertToUnifiedWindow`'s closure is the live example and not a trivial one: `receive(channel, target).send(...)` re-enters the unified channel's own `receive` hook in-process, which re-registers the wake target (an idempotent upsert) and re-enters the answer leg — which is why that leg rethrows a rate-limit refusal instead of catching it (see its own note).
+ */
+export async function withRetryAfterThrown<T>(run: () => Promise<T>, opts: RateLimitRetryOptions): Promise<T> {
+  const attempt = async (): Promise<ThrownAttempt<T>> => {
+    try {
+      return { status: SETTLED_STATUS, headers: NO_HEADERS, settled: [await run()] };
+    } catch (err) {
+      const refusal = rateLimitThrowLink(err);
+      if (refusal === undefined) throw err;
+      return { status: RATE_LIMITED_STATUS, headers: NO_HEADERS, ...refusal };
+    }
+  };
+  const res = await withRetryAfter<ThrownAttempt<T>>(attempt, {
+    ...opts,
+    // The delay comes off the ERROR, which the header lookup above cannot see — so it is handed to
+    // the loop through the one seam built for a delay stated somewhere other than the header.
+    retryAfterMs: (r) => (r as ThrownAttempt<T>).retryAfterMs,
+  });
+  // Defensive, and unreachable by construction: `withRetryAfter` returns the first attempt it does
+  // not judge a refusal, and this adapter builds exactly one such attempt — the settled one. A
+  // NAMED failure rather than an `undefined` return, because a silent undefined on the wake path is
+  // the drop this module exists to end.
+  if (res.settled === undefined) {
+    throw new RateLimitExhaustedError({ surface: opts.surface, operation: opts.operation, attempts: 0, waitedMs: 0 });
+  }
+  return res.settled[0];
+}

package/agent/channels/react-signal.ts

@@ -0,0 +1,26 @@
+// Per-session "the react tool was called this turn" signal, the twin of approvals/card-signal.ts and no-reply-signal.ts.
+// The bare-stop check reads it, so a turn that only reacted is never counted as a silent turn. See card-signal.ts for the session-scoped `defineState` rationale.
+
+import { defineState } from "eve/context";
+
+const slot = defineState<boolean>("open-everywhere.reacted-this-turn", () => false);
+
+export function markReactedThisTurn(): void {
+  try {
+    slot.update(() => true);
+  } catch {
+    /* no session context here — nothing to signal, never blocks the react tool */
+  }
+}
+
+/** Read-and-reset: did `react` fire this turn? Always clears the slot so the next
+ *  turn starts clean. */
+export function consumeReactedThisTurn(): boolean {
+  try {
+    const was = slot.get();
+    slot.update(() => false);
+    return was;
+  } catch {
+    return false;
+  }
+}

package/agent/channels/reaction-ingest.ts

@@ -0,0 +1,221 @@
+// reaction-ingest — the SURFACE-NEUTRAL inbound half: a parsed reaction from any surface becomes an {@link IngestedReaction}, and {@link ingestReaction} is the ONE place that decides what to do with it. A reaction on the BOT'S OWN reply is a human feedback signal and is recorded durably; a reaction on any other message emits telemetry only, never a stored row. The bot's own status reaction is dropped by the per-surface parse before it reaches here.
+// A reaction is UNTRUSTED input but a SIGNAL, not an instruction — an emoji name, message refs and a reactor id, all treated as DATA — and no reaction ever triggers a privileged action. A future consumer subscribes by fanning out from `ingestReaction` on the same object, and must not re-plumb the parse, route or identity path.
+
+import { appendAudit } from "../audit/audit.js";
+import { emitTelemetry } from "../observability/telemetry.js";
+import type { Partition } from "../memory/partition.js";
+import { admitProviderRegistration } from "../access/provider-selection.js";
+
+// Emoji bucketing, a CLOSED vocabulary so the telemetry dimension stays anonymous and bounded. A custom emoji NAME is high-cardinality and can itself carry text, so it is never emitted as a raw label.
+// It covers Slack shortcodes and unicode alike, with skin-tone and variation-selector modifiers stripped first. Anything unrecognised is `other`, the safe default, and no name is ever leaked.
+
+export type EmojiClass = "positive" | "negative" | "other";
+
+// 🔴 THE VOCABULARY CARRIES VENDOR SPELLINGS, NOT ONLY SLACK SHORTCODES. Teams sends six FIXED
+// values (`like`, `heart`, `laugh`, `sad`, `angry`, `surprised`) and GitHub sends eight (`+1`, `-1`,
+// `laugh`, `confused`, `heart`, `hooray`, `rocket`, `eyes`). A vocabulary that knew only Slack's
+// names bucketed a Teams `like` — the commonest reaction that surface has — as `other`, which is the
+// same telemetry a shrug gets. `surprised` and `eyes` stay `other` on purpose: neither is sentiment.
+const POSITIVE_EMOJI: ReadonlySet<string> = new Set([
+  "like", "laugh", "laughing", "hooray",
+  "thumbsup", "+1", "white_check_mark", "heavy_check_mark", "ballot_box_with_check",
+  "heart", "hearts", "yellow_heart", "green_heart", "blue_heart", "purple_heart",
+  "tada", "raised_hands", "clap", "fire", "100", "pray", "star", "star2", "ok_hand",
+  "muscle", "rocket", "smile", "smiley", "grinning", "joy", "sunglasses", "the_horns",
+  "👍", "✅", "✔", "❤", "🧡", "💛", "💚", "💙", "💜", "🎉", "🙌", "👏", "🔥", "💯",
+  "🙏", "⭐", "🌟", "👌", "💪", "🚀", "😄", "😀", "😁", "😂", "🤣", "😎",
+]);
+
+const NEGATIVE_EMOJI: ReadonlySet<string> = new Set([
+  "thumbsdown", "-1", "x", "negative_squared_cross_mark", "no_entry", "no_entry_sign",
+  "rage", "angry", "cry", "sob", "disappointed", "poop", "hankey", "confused", "no_good",
+  "-1_tone", "warning", "sad",
+  "👎", "❌", "⛔", "🚫", "😡", "😠", "😢", "😭", "😞", "💩", "😕", "🙅", "⚠",
+]);
+
+/**
+ * Bucket an emoji — a Slack shortcode or a unicode char — into the closed class the telemetry dimension is allowed to carry.
+ * It strips Slack skin-tone suffixes and unicode variation-selector and skin-tone modifiers, so a toned reaction still classifies, and it never returns the raw name.
+ */
+export function classifyEmoji(raw: string): EmojiClass {
+  const name = raw
+    .split("::")[0] // drop Slack "::skin-tone-N"
+    .replace(/[\uFE0E\uFE0F]/g, "") // variation selectors (text/emoji presentation)
+    .replace(/[\u{1F3FB}-\u{1F3FF}]/gu, "") // unicode skin-tone modifiers
+    .trim()
+    .toLowerCase();
+  if (POSITIVE_EMOJI.has(name)) return "positive";
+  if (NEGATIVE_EMOJI.has(name)) return "negative";
+  return "other";
+}
+
+// The surfaces whose inbound reaction path reaches {@link ingestReaction}. Slack and Discord came
+// first (OPE-114); Teams, GitHub and Linear joined under OPE-1502. Notion is absent because the
+// vendor pushes no reaction event and exposes no reaction resource on a comment — see that bundle's
+// surface-parity declaration for the reason it declares `unsupported` rather than "not built yet".
+export type ReactionSurface = "slack" | "discord" | "teams" | "github" | "linear";
+export type ReactionVerb = "added" | "removed";
+
+// The reaction-surface REGISTRY — the runtime counterpart to {@link ReactionSurface}, which is a compile-time-only union the compiler forgets at runtime.
+// Nothing in this file consults the registry, so an unregistered platform behaves at RUNTIME exactly as a registered one does. The registry is read by `npm run lint:surface-parity`, whose two arms do NOT cover the same set: an UNDERCLAIM reds always (an `unsupported` cell this registry contradicts), while an OVERCLAIM reds only a BARE `"supported"` — a `{ supported: "<note>" }` cell is exempt by design. So the call is load-bearing for the ledger, not for the ingest path, and a bundle declaring the noted form must keep its own registration honest.
+
+const REACTION_SURFACE_REGISTRY = new Set<string>();
+
+/** Register one surface as a valid reaction-ingest source. Exported so a future surface (or a
+ *  test's fake platform) registers the same way slack/discord do immediately below. */
+export function registerReactionSurface(platform: string): void {
+  if (!admitProviderRegistration(platform, "reaction-surface")) return;
+  REACTION_SURFACE_REGISTRY.add(platform);
+}
+
+/** Whether `platform` has been registered as a reaction surface — the runtime counterpart to
+ *  the {@link ReactionSurface} compile-time union. */
+export function isRegisteredReactionSurface(platform: string): boolean {
+  return REACTION_SURFACE_REGISTRY.has(platform);
+}
+
+/** The platforms registered as reaction surfaces (for tests/introspection). */
+export function registeredReactionSurfaces(): readonly string[] {
+  return [...REACTION_SURFACE_REGISTRY];
+}
+
+// slack: registered by @open-everywhere/provider-slack's registerSlackProvider() (OPE-114 stage 4).
+// discord: registered by @open-everywhere/provider-discord's registerDiscordProvider() (stage 4).
+// teams, github, linear: registered by their own bundles under OPE-1502. Notion registers none —
+// the vendor pushes no reaction event and exposes no reaction resource on a comment.
+
+/**
+ * A parsed inbound reaction, surface-neutral — THE SEAM every consumer reads. The per-surface parse resolves identity and partition and fills this, so downstream code never touches wire shapes.
+ * It carries only DATA — ids plus a bucketable emoji — never text and never an instruction.
+ */
+export interface IngestedReaction {
+  readonly surface: ReactionSurface;
+  readonly verb: ReactionVerb;
+  /** WHO reacted (the reactor's platform user id). Never the bot itself (dropped earlier). */
+  readonly reactorId: string;
+  /** The raw emoji name/char — DATA. Stored in audit detail; bucketed for telemetry. */
+  readonly emoji: string;
+  readonly emojiClass: EmojiClass;
+  /** The message the reaction landed on. */
+  readonly target: { readonly channelId: string; readonly messageId: string };
+  /** True when the target message was authored by the bot — the feedback case. */
+  readonly onBotReply: boolean;
+  // The resolved partition coordinates (org is the outermost tenant key; the rest name
+  // the audit surface). Kept flat rather than the whole Partition so the seam doesn't
+  // couple a future consumer to memory internals.
+  readonly org: string;
+  readonly platform: string;
+  readonly workspace: string;
+  readonly surfaceKey: string;
+}
+
+/** Build an {@link IngestedReaction} from a per-surface parse + its resolved partition. */
+export function buildIngestedReaction(input: {
+  readonly surface: ReactionSurface;
+  readonly verb: ReactionVerb;
+  readonly reactorId: string;
+  readonly emoji: string;
+  readonly target: { readonly channelId: string; readonly messageId: string };
+  readonly onBotReply: boolean;
+  readonly partition: Pick<Partition, "org" | "platform" | "workspace" | "surfaceKey">;
+}): IngestedReaction {
+  return {
+    surface: input.surface,
+    verb: input.verb,
+    reactorId: input.reactorId,
+    emoji: input.emoji,
+    emojiClass: classifyEmoji(input.emoji),
+    target: input.target,
+    onBotReply: input.onBotReply,
+    org: input.partition.org,
+    platform: input.partition.platform,
+    workspace: input.partition.workspace,
+    surfaceKey: input.partition.surfaceKey,
+  };
+}
+
+/** Where an ingested reaction goes. `record` is the durable feedback write (bot-reply
+ *  reactions only); `telemetry` fires for every reaction (volume). Both injected so
+ *  {@link ingestReaction} is unit-tested against stubs. */
+export interface ReactionSinkDeps {
+  readonly record: (r: IngestedReaction, atIso: string) => Promise<void>;
+  readonly telemetry: (r: IngestedReaction) => void;
+  /**
+   * OPTIONAL EXTRA SINK for a NEGATIVE reaction on the bot's own message. Nothing wires it today, so `ingestReaction` never enters that branch.
+   * It stays as the declared seam a future negative-reaction consumer attaches to, rather than re-plumbing the parse and route path.
+   */
+  readonly negativeOnBotReply?: (r: IngestedReaction) => Promise<void>;
+  readonly now?: () => string;
+}
+
+/** The result of ingesting one reaction — did it get durably recorded, and why. */
+export interface ReactionIngestOutcome {
+  readonly recorded: boolean;
+  readonly onBotReply: boolean;
+  readonly reason: string;
+}
+
+/** The stable audit action key for a bot-reply feedback reaction — the query anchor for
+ *  "reactions on bot replies per surface/session" (readAudit({ action })). */
+export const REACTION_FEEDBACK_ACTION = "reaction.feedback";
+
+/**
+ * THE EXTENSION POINT. Ingest one parsed reaction: emit telemetry always, and durably record it ONLY when it landed on the bot's own reply, which is the human-feedback signal.
+ * A future consumer adds its sink to the fan-out below and reads the same {@link IngestedReaction} — it must NOT re-plumb the per-surface parse, route or identity path. It never throws into the caller: both sinks are best-effort.
+ */
+export async function ingestReaction(r: IngestedReaction, deps: ReactionSinkDeps): Promise<ReactionIngestOutcome> {
+  // Telemetry first (volume signal for EVERY reaction, on-bot-reply or not).
+  deps.telemetry(r);
+  // FAN-OUT: a future consumer adds its sink here, gated on whatever it needs from `r`.
+  // Only the ADD verb drives the negative-on-bot-reply seam: a retraction is a CANCEL, never a second firing. It is unwired today, so this branch is never entered.
+  if (r.verb === "added" && r.emojiClass === "negative" && r.onBotReply && deps.negativeOnBotReply) {
+    await deps.negativeOnBotReply(r);
+  }
+  if (!r.onBotReply) {
+    return { recorded: false, onBotReply: false, reason: "reaction not on the bot's own message — telemetry only" };
+  }
+  const at = deps.now?.() ?? new Date().toISOString();
+  await deps.record(r, at);
+  return { recorded: true, onBotReply: true, reason: `reaction ${r.verb} on a bot reply — feedback recorded` };
+}
+
+/**
+ * Emit the anonymised reaction telemetry event, on the closed vocabulary.
+ * It carries ONLY the surface, the on-bot-reply flag and the bucketed emoji class — no channel id, no user id, no raw emoji name — and `emitTelemetry` drops any stray key.
+ */
+function emitReactionTelemetry(r: IngestedReaction): void {
+  emitTelemetry(r.verb === "added" ? "oe.reaction.added" : "oe.reaction.removed", {
+    "oe.surface": r.surface,
+    "oe.on_bot_reply": r.onBotReply,
+    "oe.emoji_class": r.emojiClass,
+  });
+}
+
+/**
+ * The production sink: durable feedback through the append-only audit log, which is already org-partitioned and already answers "reactions on bot replies per surface", so it needs no new table and no store-interface change.
+ * The row carries only the reactor id, the emoji and its bucket, and the message refs — NO message text, and no PII beyond the reactor. Both sinks are best-effort.
+ */
+export function liveReactionSink(): ReactionSinkDeps {
+  return {
+    record: (r, atIso) =>
+      appendAudit({
+        ts: atIso,
+        org: r.org,
+        platform: r.platform,
+        workspace: r.workspace,
+        surface: r.surfaceKey,
+        principalId: r.reactorId,
+        action: REACTION_FEEDBACK_ACTION,
+        detail: {
+          surface: r.surface,
+          verb: r.verb,
+          emoji: r.emoji,
+          emojiClass: r.emojiClass,
+          channelId: r.target.channelId,
+          messageId: r.target.messageId,
+          onBotReply: true,
+        },
+      }),
+    telemetry: emitReactionTelemetry,
+  };
+}