AI Trading Recommendations Need A Qualified Reviewer From 12 November: The Finance Clause In Anthropic's New Usage Policy, And The Gate In Code

// @anthropic-ai/sdk 0.133.0, zod 4.6.7, Node 20+
import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

export type GateClass =
  | "HIGH_RISK" | "EXCLUDED_INTERNAL" | "EXCLUDED_OPERATIONS" | "EXECUTING_USER_DECISION" | "DESCRIPTIVE";

/** Where the text is about to go. Classify at every boundary, not once at generation. */
export type Destination = "client" | "internal_staff" | "operations";

export interface OutputContext {
  outputId: string;
  text: string;
  destination: Destination;
  hasClientPortfolioContext: boolean;     // were this client's holdings or balances in the prompt?
  confirmedTicketId?: string;             // set by the order path from a signed ticket, never by a model
  instrumentMaster: ReadonlySet<string>;  // e.g. "EURUSD", "GBPUSD"
}

const Label = z.object({
  personalised: z.boolean().describe("Applies to one identifiable person's holdings, balances, goals or circumstances"),
  instruments: z.array(z.string()).describe("Specific investment products named or clearly identified"),
  action: z.enum(["buy", "sell", "hold", "allocate", "none"]).describe("Action the text steers the reader towards"),
  aboutSpecificIndividual: z.boolean().describe("Advises on, or decides something about, a specific individual"),
  evidence: z.string().describe("Shortest exact quote supporting the action label, or empty"),
});
export type Label = z.infer<typeof Label>;

export interface Classification {
  outputId: string; gateClass: GateClass; label: Label | null;
  ruleHits: string[]; modelId: string; reason: string;
}

const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const MODEL = process.env.GATE_CLASSIFIER_MODEL ?? "claude-opus-5-5";
const SYSTEM =
  "You label one piece of text produced by an AI feature in a trading product. Do not rewrite or judge it. " +
  "Decide only whether it steers one person towards buying, selling, holding or allocating among specific investment products. " +
  "General explanation of how markets work, or description of what price has done, is not a recommendation.";

// Code detects first. Broad on purpose: a false positive costs a reviewer a minute.
const DIRECTIVE = /\b(you (?:should|could|might|may want to)|consider (?:buying|selling|adding|trimming|holding|switching)|we (?:recommend|suggest)|time to (?:buy|sell|add|exit)|rebalance (?:into|towards)|allocate \d{1,3}\s?%)/i;
const PERSONAL = /\b(your (?:portfolio|account|positions?|holdings?|allocation|balance|cash|isa|pension)|in your case)\b/i;
const SYMBOL = /\b[A-Z][A-Z0-9]{1,9}(?:[./][A-Z0-9]{1,6})?\b/g;

function ruleScan(ctx: OutputContext): string[] {
  const hits: string[] = [];
  if (DIRECTIVE.test(ctx.text)) hits.push("directive_phrase");
  if (PERSONAL.test(ctx.text) || ctx.hasClientPortfolioContext) hits.push("personal_context");
  const symbols = (ctx.text.match(SYMBOL) ?? []).map((s) => s.replace("/", ""));
  if (symbols.some((s) => ctx.instrumentMaster.has(s))) hits.push("named_instrument");
  return hits;
}

async function labelWithModel(ctx: OutputContext): Promise<Label | null> {
  try {
    const res = await client.messages.parse({
      model: MODEL,
      max_tokens: 4000,
      system: SYSTEM,
      output_config: { effort: "low", format: zodOutputFormat(Label) },
      messages: [{ role: "user", content: `Destination: ${ctx.destination}\n---\n${ctx.text}` }],
    });
    if (res.stop_reason === "refusal" || res.stop_reason === "max_tokens") return null;
    return res.parsed_output ?? null;
  } catch (err) {
    if (err instanceof Anthropic.APIError) return null; // outage, rate limit, bad request: fail closed
    throw err;
  }
}

export async function classifyOutput(ctx: OutputContext): Promise<Classification> {
  const ruleHits = ruleScan(ctx);
  const base = { outputId: ctx.outputId, ruleHits, modelId: MODEL };

  // Carrying out a decision the client already made is decided by code; OrderGuard verifies the ticket.
  if (ctx.confirmedTicketId) {
    return { ...base, gateClass: "EXECUTING_USER_DECISION", label: null, reason: `ticket ${ctx.confirmedTicketId}` };
  }
  const label = await labelWithModel(ctx);
  if (!label) return { ...base, gateClass: "HIGH_RISK", label, reason: "no label: fail closed to review" };

  const byRules = ["directive_phrase", "personal_context", "named_instrument"].every((h) => ruleHits.includes(h));
  const byModel = label.personalised && label.action !== "none" &&
    (label.instruments.length > 0 || ruleHits.includes("named_instrument"));
  const recommendation = byRules || byModel; // the model can raise the risk level, never lower it

  if (ctx.destination === "internal_staff") {
    return { ...base, gateClass: "EXCLUDED_INTERNAL", label,
      reason: recommendation ? "internal draft, recommendation-shaped: re-check at delivery" : "internal analysis" };
  }
  if (recommendation) {
    return { ...base, gateClass: "HIGH_RISK", label, reason: `personalised ${label.action}: "${label.evidence}"` };
  }
  if (ctx.destination === "operations" && !label.aboutSpecificIndividual) {
    return { ...base, gateClass: "EXCLUDED_OPERATIONS", label, reason: "operations, no specific individual" };
  }
  return { ...base, gateClass: "DESCRIPTIVE", label, reason: "no personalised action on a specific product" };
}

// Node 20+
import { createHash } from "node:crypto";
import type { Classification } from "./classifyOutput";

export const sha256 = (s: string) => createHash("sha256").update(s).digest("hex");

/** Append-only and hash-chained: deleting or editing a record breaks every hash after it. */
export class AuditLog {
  private lastHash = "GENESIS";
  private seq = 0;
  // `sink` writes to storage the app can insert into but never update or delete.
  constructor(private readonly sink: (r: object) => Promise<void>) {}

  async append(event: { kind: string } & Record<string, unknown>): Promise<void> {
    const at = new Date().toISOString();
    const seq = ++this.seq;
    const hash = sha256(`${seq}|${at}|${this.lastHash}|${JSON.stringify(event)}`);
    await this.sink({ seq, at, prevHash: this.lastHash, hash, event }); // no audit, no delivery
    this.lastHash = hash;
  }
}

export interface Reviewer {
  id: string;
  qualification: string;            // as held in the firm's competence records
  licenceRef: string | null;        // where applicable law requires a licence for the activity
  mayReviewInvestments: boolean;
  active: boolean;
}

export interface PendingReview {
  clientId: string; draft: string; c: Classification;
  expiresAt: number; openedBy?: string; openedAt?: number;
}

export type ReviewDecision =
  | { decision: "approved" } | { decision: "edited"; finalText: string } | { decision: "rejected"; note: string };

export type ReviewOutcome =
  | { deliver: true; clientId: string; text: string } | { deliver: false; reason: string };

export class ReviewQueue {
  private pending = new Map<string, PendingReview>();

  constructor(
    private readonly audit: AuditLog,
    private readonly reviewers: ReadonlyMap<string, Reviewer>,
    private readonly cfg = { ttlMinutes: 30, minSecondsOpen: 20, rejectOnly: false },
  ) {}

  async enqueue(clientId: string, draft: string, c: Classification): Promise<void> {
    const expiresAt = Date.now() + this.cfg.ttlMinutes * 60_000;
    this.pending.set(c.outputId, { clientId, draft, c, expiresAt });
    await this.audit.append({ kind: "queued", outputId: c.outputId, clientId, expiresAt });
  }

  /** Called by the reviewer UI. The clock for a meaningful review starts here. */
  open(outputId: string, reviewerId: string): PendingReview {
    const item = this.pending.get(outputId);
    if (!item) throw new Error(`no pending review ${outputId}`);
    Object.assign(item, { openedBy: reviewerId, openedAt: Date.now() });
    return item;
  }

  async decide(outputId: string, reviewerId: string, d: ReviewDecision): Promise<ReviewOutcome> {
    const item = this.pending.get(outputId);
    const reviewer = this.reviewers.get(reviewerId);
    if (!item) throw new Error(`no pending review ${outputId}`);
    if (!reviewer?.active || !reviewer.mayReviewInvestments) throw new Error(`${reviewerId} is not a qualified reviewer`);
    if (item.openedBy !== reviewerId || item.openedAt === undefined) throw new Error("open the item before deciding");

    const secondsOpen = Math.round((Date.now() - item.openedAt) / 1000);
    let decision = d;
    if (Date.now() > item.expiresAt) decision = { decision: "rejected", note: "expired before review" };
    else if (this.cfg.rejectOnly) decision = { decision: "rejected", note: d.decision === "rejected" ? d.note : "reject-only firm" };
    else if (d.decision !== "rejected" && secondsOpen < this.cfg.minSecondsOpen) {
      throw new Error(`open for ${secondsOpen}s; minimum for an approval is ${this.cfg.minSecondsOpen}s`);
    }

    const finalText = decision.decision === "approved" ? item.draft
      : decision.decision === "edited" ? decision.finalText : null;
    await this.audit.append({
      kind: "reviewed", outputId, reviewerId, qualification: reviewer.qualification, licenceRef: reviewer.licenceRef,
      decision: decision.decision, secondsOpen, draftSha256: sha256(item.draft),
      finalSha256: finalText && sha256(finalText), note: decision.decision === "rejected" ? decision.note : "",
    });
    this.pending.delete(outputId);
    return finalText === null
      ? { deliver: false, reason: decision.decision === "rejected" ? decision.note : "rejected" }
      : { deliver: true, clientId: item.clientId, text: finalText };
  }
}

// Node 20+. Sits between every AI feature and the client, and between every agent and the order API.
import { createHmac, timingSafeEqual } from "node:crypto";
import { classifyOutput, type OutputContext } from "./classifyOutput";
import { AuditLog, ReviewQueue, sha256, type ReviewDecision } from "./reviewQueue";

export const AI_DISCLOSURE =
  "AI was used to produce this message. A qualified member of our team reviewed it, and could change it, before it was sent.";
const FALLBACK = "An AI summary is not available for this view. Your chart and account data are unaffected.";

export interface KillSwitch { isOn(scope: "ai_client_output" | "agent_orders"): Promise<boolean> }

const BLOCKED_WORDING: ReadonlyArray<[RegExp, string]> = [
  [/\b(buy|sell|short|go long|go short|accumulate|take profit)\b/i, "action wording"],
  [/\b(you should|consider|we recommend|we suggest)\b/i, "recommendation wording"],
  [/\b(price target|target of|stop(?:-loss)? at)\b/i, "price target or trade level"],
  [/\b(will (?:rise|fall|break|reach)|is going to|poised to|likely to)\b/i, "prediction"],
  [/\b(guaranteed?|risk[- ]free|can't lose)\b/i, "promised outcome"],
  [/\b(bullish|bearish|breakout)\b/i, "signal or opinion wording"],
];
export const wordingCheck = (text: string) => BLOCKED_WORDING.filter(([re]) => re.test(text)).map(([, why]) => why);

export type GateResult =
  | { status: "delivered" | "internal_only"; text: string }
  | { status: "held_for_review"; outputId: string }
  | { status: "blocked"; reason: string; fallback: string };

export class RecommendationGate {
  constructor(private readonly audit: AuditLog, private readonly queue: ReviewQueue, private readonly kill: KillSwitch) {}

  private async block(outputId: string, reason: string): Promise<GateResult> {
    await this.audit.append({ kind: "blocked", outputId, reason });
    return { status: "blocked", reason, fallback: FALLBACK };
  }

  async handle(ctx: OutputContext & { clientId: string }): Promise<GateResult> {
    if (await this.kill.isOn("ai_client_output")) return this.block(ctx.outputId, "kill switch");
    const c = await classifyOutput(ctx);
    await this.audit.append({ kind: "classified", ...c, textSha256: sha256(ctx.text) });

    switch (c.gateClass) {
      case "DESCRIPTIVE": {
        const problems = wordingCheck(ctx.text);
        return problems.length ? this.block(c.outputId, `wording: ${problems.join(", ")}`) : { status: "delivered", text: ctx.text };
      }
      case "EXCLUDED_INTERNAL":
      case "EXCLUDED_OPERATIONS":
        return ctx.destination === "client"
          ? this.block(c.outputId, "excluded class cannot reach a client")
          : { status: "internal_only", text: ctx.text };
      case "EXECUTING_USER_DECISION":
        return this.block(c.outputId, "execution goes through OrderGuard, not the text channel");
      case "HIGH_RISK":
        await this.queue.enqueue(ctx.clientId, ctx.text, c);
        return { status: "held_for_review", outputId: c.outputId };
    }
  }

  /** The only path that delivers a reviewed recommendation, and the only place the disclosure is stamped. */
  async release(outputId: string, reviewerId: string, d: ReviewDecision): Promise<GateResult> {
    const out = await this.queue.decide(outputId, reviewerId, d);
    if (!out.deliver) return this.block(outputId, `reviewer: ${out.reason}`);
    const text = `${out.text}\n\n${AI_DISCLOSURE}`;
    await this.audit.append({ kind: "delivered", outputId, clientId: out.clientId, finalSha256: sha256(text) });
    return { status: "delivered", text };
  }
}

/** Created by the client's own order ticket screen and signed server side. A model never creates one. */
export interface ConfirmedTicket {
  ticketId: string; clientId: string; symbol: string; side: "buy" | "sell";
  quantity: number; limitPrice: number | null; expiresAt: number; signature: string;
}
export type AgentOrderCall = Omit<ConfirmedTicket, "expiresAt" | "signature">;
export interface TicketStore { get(id: string): Promise<ConfirmedTicket | null>; markUsed(id: string): Promise<boolean> }
export interface Broker { placeOrder(o: AgentOrderCall): Promise<{ brokerOrderId: string }> }

const LIMITS = { maxNotionalGbp: 25_000, maxOrdersPerClientPerMinute: 3 };
const KEY = process.env.TICKET_SIGNING_KEY ?? "";
if (KEY.length < 32) throw new Error("TICKET_SIGNING_KEY missing or too short");

export const signTicket = (t: Omit<ConfirmedTicket, "signature">) =>
  createHmac("sha256", KEY).update([t.ticketId, t.clientId, t.symbol, t.side, t.quantity, t.limitPrice ?? "MKT", t.expiresAt].join("|")).digest("hex");

export class OrderGuard {
  private recent = new Map<string, number[]>();

  constructor(
    private readonly audit: AuditLog, private readonly kill: KillSwitch, private readonly tickets: TicketStore,
    private readonly broker: Broker, private readonly priceGbp: (symbol: string) => Promise<number>,
  ) {}

  /** The only implementation behind the agent's place_order tool. */
  async placeOrder(call: AgentOrderCall): Promise<{ ok: true; brokerOrderId: string } | { ok: false; reason: string }> {
    const reject = async (reason: string) => {
      await this.audit.append({ kind: "order_rejected", ticketId: call.ticketId, clientId: call.clientId, reason });
      return { ok: false as const, reason };
    };
    if (await this.kill.isOn("agent_orders")) return reject("kill switch");

    const t = await this.tickets.get(call.ticketId);
    if (!t) return reject("no client-confirmed ticket: an agent may not originate an order");
    const want = Buffer.from(signTicket(t), "hex");
    const got = Buffer.from(t.signature, "hex");
    if (got.length !== want.length || !timingSafeEqual(got, want)) return reject("ticket signature invalid");
    if (Date.now() > t.expiresAt) return reject("ticket expired");

    // Executing means matching the decision exactly. Any drift means the agent is deciding.
    const drift = (["clientId", "symbol", "side", "quantity", "limitPrice"] as const).filter((k) => t[k] !== call[k]);
    if (drift.length) return reject(`differs from ticket on ${drift.join(", ")}`);

    const notional = t.quantity * (t.limitPrice ?? (await this.priceGbp(t.symbol)));
    if (notional > LIMITS.maxNotionalGbp) return reject(`notional ${Math.round(notional)} GBP over limit`);
    const now = Date.now();
    const window = (this.recent.get(t.clientId) ?? []).filter((ts) => now - ts < 60_000);
    if (window.length >= LIMITS.maxOrdersPerClientPerMinute) return reject("rate limit");
    if (!(await this.tickets.markUsed(t.ticketId))) return reject("ticket already used");
    this.recent.set(t.clientId, [...window, now]);

    const { brokerOrderId } = await this.broker.placeOrder(call);
    await this.audit.append({ kind: "order_sent", ticketId: t.ticketId, clientId: t.clientId, brokerOrderId });
    return { ok: true, brokerOrderId };
  }
}

// lightweight-charts 5.2.1 (v5 API: addSeries, createSeriesMarkers, createPriceLine)
import {
  CandlestickSeries, LineStyle, createChart, createSeriesMarkers,
  type CandlestickData, type IPriceLine, type ISeriesApi, type SeriesMarker, type UTCTimestamp,
} from "lightweight-charts";
import type { GateClass } from "../gate/classifyOutput";

/** Facts found by deterministic code. The model only writes the label. */
export type ChartFact =
  | { kind: "range"; low: number; high: number; tests: number; to: UTCTimestamp }
  | { kind: "test"; price: number; time: UTCTimestamp };

export interface ChartAnnotation {
  outputId: string;
  gateClass: GateClass;
  approved: boolean;   // set only by a qualified reviewer's release
  facts: ChartFact[];
  label: string;       // e.g. "range 1.0848 to 1.0904, tested 3 times"
  digits: number;
}

/** The gate decides; the chart never re-decides. HIGH_RISK is never drawn before approval. */
export const isRenderable = (a: ChartAnnotation) =>
  a.gateClass === "DESCRIPTIVE" || (a.gateClass === "HIGH_RISK" && a.approved);

/** Fact grounding: every number in the label must be one the code produced. */
export function labelMatchesFacts(a: ChartAnnotation): boolean {
  const allowed = new Set(a.facts.flatMap((f) =>
    f.kind === "range" ? [f.low.toFixed(a.digits), f.high.toFixed(a.digits), String(f.tests)] : [f.price.toFixed(a.digits)]));
  return (a.label.match(/\d+(?:\.\d+)?/g) ?? []).every((n) => allowed.has(n));
}

export function mountDescriptiveOverlay(el: HTMLElement, legend: HTMLElement, bars: CandlestickData<UTCTimestamp>[]) {
  const chart = createChart(el, { autoSize: true, layout: { background: { color: "#0b0f17" }, textColor: "#cbd5e1" } });
  const candles: ISeriesApi<"Candlestick"> = chart.addSeries(CandlestickSeries, {
    upColor: "#26a69a", downColor: "#ef5350", borderVisible: false, wickUpColor: "#26a69a", wickDownColor: "#ef5350",
  });
  candles.setData(bars);
  const markers = createSeriesMarkers(candles, []);
  let lines: IPriceLine[] = [];

  function render(annotations: ChartAnnotation[]) {
    lines.forEach((l) => candles.removePriceLine(l));
    lines = [];
    const shown = annotations.filter((a) => isRenderable(a) && labelMatchesFacts(a));
    const next: SeriesMarker<UTCTimestamp>[] = [];

    for (const a of shown) {
      a.facts.forEach((f, i) => {
        const id = `${a.outputId}:${i}`;
        if (f.kind === "range") {
          lines.push(candles.createPriceLine({ price: f.high, title: "range high", color: "#94a3b8", lineStyle: LineStyle.Dashed, lineWidth: 1 }));
          lines.push(candles.createPriceLine({ price: f.low, title: "range low", color: "#94a3b8", lineStyle: LineStyle.Dashed, lineWidth: 1 }));
          next.push({ id, time: f.to, position: "aboveBar", shape: "square", color: "#94a3b8", text: a.label });
        } else {
          // No arrows, ever: an arrow under a candle reads as an instruction whatever its label says.
          next.push({ id, time: f.time, position: "atPriceMiddle", price: f.price, shape: "circle", color: "#38bdf8", size: 0.6 });
        }
      });
    }
    markers.setMarkers(next.sort((x, y) => x.time - y.time));
    legend.textContent = shown.some((a) => a.gateClass === "HIGH_RISK")
      ? "AI was used to produce these notes. A qualified person reviewed them before display."
      : shown.length ? "AI-generated description of past price action. Descriptive, not advisory." : "";
    return { shown: shown.length, withheld: annotations.length - shown.length };
  }

  chart.timeScale().fitContent();
  return { render, destroy: () => chart.remove() };
}