@anthusai/papyrus 2.0.0-next.8 → 2.0.0-next.81

package/lib/automation-overview.ts

@@ -0,0 +1,232 @@
+/** Shapes and wording for the newsroom Automation page. src/papyrus_content/automations.py produces them. */
+import { formatUtc } from "./monitoring-overview";
+import { getNewsroomNavHref } from "./newsroom-nav";
+
+export { formatUtc };
+
+export type AutomationUsage = {
+  calls?: number;
+  promptTokens?: number;
+  completionTokens?: number;
+  models?: Record<string, number>;
+  complete?: boolean;
+  unpricedModels?: string[];
+};
+
+export type AutomationRun = {
+  origin: "monitor" | "manual";
+  requestedBy: string | null;
+  reason: string | null;
+  sourceId: string | null;
+  referenceId: string | null;
+  triggerStatus: string | null;
+  runId: string | null;
+  status: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  durationSeconds: number | null;
+  error: string | null;
+  runRecord: "found" | "missing" | "unavailable" | "none";
+  storyId: string | null;
+  storyVersionId: string | null;
+  storyTitle: string | null;
+  costUsd: number | null;
+  costNote: string;
+  budgetUsd: number | null;
+  overBudget: boolean;
+  usage: AutomationUsage | null;
+};
+
+/** A ProcedureRun of the same procedure that this automation did not start ("Started outside this automation"). */
+export type AutomationOutsideRun = {
+  runId: string | null;
+  status: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  durationSeconds: number | null;
+  error: string | null;
+  requestedBy: string | null;
+  storyId: string | null;
+  storyVersionId: string | null;
+  storyTitle: string | null;
+  costUsd: number | null;
+  costNote: string;
+  overBudget: boolean;
+};
+
+export type AutomationRunNow = { available: boolean; reason: string | null; needsInput: boolean; inputNames: string[] };
+
+export type AutomationLink = {
+  state: "linked" | "input_differs" | "trigger_not_found" | "publication_not_in_router" | "router_not_found" | "not_applicable";
+  text: string;
+  routerMode?: string | null;
+  routerEnabled?: boolean;
+};
+
+export type AutomationNotice = "monitoring_not_configured" | "monitoring_unavailable" | "other_publication" | "publication_not_routed" | "not yet supported";
+
+export type AutomationRecord = {
+  id: string;
+  title: string;
+  description: string | null;
+  enabled: boolean;
+  enabledNote: string;
+  trigger: { kind: "monitor" | "schedule" | "event" | "manual"; config: Record<string, unknown> };
+  supported: boolean;
+  supportNote: string | null;
+  procedureKey: string;
+  inputTemplate: Record<string, string>;
+  limits: { timeoutSeconds?: number; maxConcurrent?: number; budgetUsdPerRun?: number };
+  limitsNote: string;
+  runNow: AutomationRunNow;
+  createdAt: string | null;
+  updatedAt: string | null;
+  link: AutomationLink | null;
+  runs: AutomationRun[];
+  lastRun: AutomationRun | null;
+  skippedAlreadyHadReference: number;
+  notice: AutomationNotice | null;
+  outsideRuns: AutomationOutsideRun[];
+  outsideNotice: "outside_unavailable" | null;
+};
+
+export type AutomationOverview = {
+  state: "ready" | "empty";
+  asOf: string;
+  monitoring: "ready" | "not_configured";
+  automations: AutomationRecord[];
+};
+
+export type AutomationResult = AutomationOverview | { state: "unavailable" } | { error: "forbidden" | "bad_request" };
+
+const KIND_WORDS: Record<string, string> = { monitor: "Monitor", schedule: "Schedule", event: "Event", manual: "Manual" };
+
+export function triggerText(trigger: AutomationRecord["trigger"]): string {
+  const kind = KIND_WORDS[trigger.kind] ?? trigger.kind;
+  if (trigger.kind === "monitor") {
+    return `${kind} ${String(trigger.config.monitorId ?? "?")}, delivering to ${String(trigger.config.publicationId ?? "?")}`;
+  }
+  return kind;
+}
+
+export const ENABLED_NOTE = "the router starts nothing for a disabled automation";
+
+export function enabledText(record: Pick<AutomationRecord, "enabled">): string {
+  return record.enabled ? "Enabled" : "Disabled";
+}
+
+const STATUS_WORDS: Record<string, string> = {
+  completed: "Completed",
+  failed: "Failed",
+  running: "Running",
+  starting: "Starting",
+  started: "Started, no result recorded yet",
+  startFailed: "Could not start",
+  notRunnable: "Not runnable",
+  notTriggered: "Not started",
+  skipped: "Skipped",
+  refused: "Refused",
+  deferred: "Deferred, waiting for room",
+};
+const STATUS_MARKS: Record<string, string> = {
+  completed: "✓", failed: "✕", startFailed: "✕", notRunnable: "✕", refused: "✕", skipped: "–", deferred: "…", started: "…", starting: "…", running: "…",
+};
+
+export function statusText(status: string | null | undefined): string {
+  return status ? (STATUS_WORDS[status] ?? status) : "No runs";
+}
+
+export function statusMark(status: string | null | undefined): string {
+  return status ? (STATUS_MARKS[status] ?? "") : "";
+}
+
+export function durationText(seconds: number | null | undefined): string {
+  if (seconds === null || seconds === undefined) return "duration not recorded";
+  if (seconds < 90) return `${Math.round(seconds)} s`;
+  return `${Math.floor(seconds / 60)} min ${Math.round(seconds % 60)} s`;
+}
+
+export function dollars(value: number): string {
+  return value < 0.01 ? `$${value.toFixed(4)}` : `$${value.toFixed(2)}`;
+}
+
+/** "Cost: $0.04 (estimated ...)" or "Cost: unknown (why)", with the advisory budget flagged in words. */
+export function costText(run: Pick<AutomationRun, "costUsd" | "costNote" | "overBudget"> & { budgetUsd?: number | null }): string {
+  const base = run.costUsd === null ? `Cost: unknown (${run.costNote})` : `Cost: ${dollars(run.costUsd)} (${run.costNote})`;
+  return run.overBudget && run.budgetUsd != null ? `${base}. Over the budget of ${dollars(run.budgetUsd)} per run` : base;
+}
+
+export function whoText(run: Pick<AutomationRun, "origin" | "requestedBy" | "sourceId">): string {
+  return run.origin === "manual" ? `Run now by ${run.requestedBy ?? "someone"}` : `Item: ${run.sourceId ?? "unknown"}`;
+}
+
+export const LIMITS_NOTE = "the timeout and the number at a time (when set) are enforced when a run starts; the budget is advisory and only flagged";
+
+export function atATimeText(limits: { maxConcurrent?: number }): string {
+  return limits.maxConcurrent === undefined ? "no limit on how many at a time" : `${limits.maxConcurrent} at a time`;
+}
+
+export type RunNowResult =
+  | { state: "started"; automationId: string; requestedBy: string }
+  | { state: "refused"; reason: string }
+  | { state: "unavailable" }
+  | { error: "forbidden" | "bad_request" };
+
+export function runNowMessage(result: RunNowResult): string {
+  if ("error" in result) return result.error === "forbidden" ? "Run now is for editors and admins." : "The request was not understood.";
+  if (result.state === "started") return "Started. The run appears in the list below within a minute; the page refreshes by itself.";
+  if (result.state === "refused") return `Not started: ${result.reason}`;
+  return "Not started: the request could not be completed right now. Nothing was started.";
+}
+
+/** The input a person typed for Run now: a JSON object, or nothing (the record's own input is used). */
+export function parseRunInput(text: string): { ok: true; value: Record<string, unknown> | null } | { ok: false; message: string } {
+  if (!text.trim()) return { ok: true, value: null };
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return { ok: false, message: "The input must be a JSON object, for example {\"name\": \"value\"}." };
+    return { ok: true, value: parsed as Record<string, unknown> };
+  } catch {
+    return { ok: false, message: "The input is not valid JSON." };
+  }
+}
+
+/** A starting point for the input box: the record's input names with empty values. */
+export function inputTemplateText(names: string[]): string {
+  return JSON.stringify(Object.fromEntries(names.map((name) => [name, ""])), null, 2);
+}
+
+const LINK_WORDS: Record<AutomationLink["state"], string> = {
+  linked: "Linked: the router's trigger matches this record.",
+  input_differs: "Differs: the router's input template is not the same as this record's.",
+  trigger_not_found: "Not linked: the router has no trigger for this procedure.",
+  publication_not_in_router: "Not linked: the router does not deliver to this publication.",
+  router_not_found: "Not linked: the monitor has no router configuration.",
+  not_applicable: "Not yet supported",
+};
+
+export function linkText(link: AutomationLink | null): string {
+  return link ? LINK_WORDS[link.state] ?? link.text : "Not checked";
+}
+
+const NOTICE_WORDS: Record<string, string> = {
+  monitoring_not_configured: "Monitoring is not connected to this site's account, so run history cannot be shown.",
+  monitoring_unavailable: "Run history could not be read right now. The record is shown without it.",
+  other_publication: "This automation belongs to another publication, so its runs are not shown here.",
+  publication_not_routed: "This publication is not one of the router's outputs, so there are no runs to show.",
+  "not yet supported": "Only monitor automations run today. This one is stored but nothing starts it.",
+};
+
+export const OUTSIDE_NOTICE = "The procedure's other runs could not be read right now.";
+
+export function noticeText(notice: AutomationNotice | null): string | null {
+  return notice ? (NOTICE_WORDS[notice] ?? notice) : null;
+}
+
+export function storyHref(storyId: string, demo?: boolean): string {
+  return getNewsroomNavHref(`/newsroom/articles/${encodeURIComponent(storyId)}`, demo);
+}
+
+export function proceduresHref(demo?: boolean): string {
+  return getNewsroomNavHref("/newsroom/administration/procedures", demo);
+}

package/lib/category-repository.ts

@@ -200,7 +200,6 @@ export type ProcedureRunRecord = {
   newsroomFeedKey?: string | null;
 };
 
-const DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH = path.join(process.cwd(), "corpora", "papyrus-newsroom-sections.yml");
 const NEWSROOM_SECTION_TYPES = new Set<NewsroomSectionType>(["canonical", "floating", "rotating"]);
 type NewsroomSectionSeedRow = Omit<NewsroomSectionRecord, "sortOrder" | "enabled" | "enabledStatus" | "createdAt" | "updatedAt"> & {
   enabled: boolean;
@@ -690,10 +689,10 @@ export type CategorySteeringDashboard = {
   loadError?: string | null;
 };
 
-const DEFAULT_ANALYSIS_PROFILES_PATH = path.join(process.cwd(), "corpora", "papyrus-analysis-profiles.yml");
-const DEFAULT_STEERING_CONFIG_PATH = path.join(process.cwd(), "corpora", "papyrus-steering.yml");
 
-export async function loadAnalysisProfileSummaries(filepath = DEFAULT_ANALYSIS_PROFILES_PATH): Promise<AnalysisProfileSummary[]> {
+/** Analysis profiles the site keeps in a file; a site that configures none (data-driven sites) has none. No default file is looked up. */
+export async function loadAnalysisProfileSummaries(filepath?: string): Promise<AnalysisProfileSummary[]> {
+  if (!filepath) return [];
   try {
     const parsed = YAML.parse(fs.readFileSync(filepath, "utf8")) as {
       schemaVersion?: number;
@@ -722,7 +721,9 @@ export async function loadAnalysisProfileSummaries(filepath = DEFAULT_ANALYSIS_P
   }
 }
 
-export async function loadConfiguredCorpusSummaries(filepath = DEFAULT_STEERING_CONFIG_PATH): Promise<CategorySteeringCorpus[]> {
+/** Corpora a site lists in a steering file; no configured file means none. No default file is looked up. */
+export async function loadConfiguredCorpusSummaries(filepath?: string): Promise<CategorySteeringCorpus[]> {
+  if (!filepath) return [];
   try {
     const parsed = YAML.parse(fs.readFileSync(filepath, "utf8")) as {
       corpora?: Array<Record<string, unknown>>;
@@ -818,7 +819,8 @@ function sortCategorys(categorys: CategorySteeringCategory[]): CategorySteeringC
   });
 }
 
-function defaultNewsroomSections(importedAt: string, sectionsConfigPath = DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH): NewsroomSectionRecord[] {
+function defaultNewsroomSections(importedAt: string, sectionsConfigPath?: string): NewsroomSectionRecord[] {
+  if (!sectionsConfigPath) return [];
   return loadNewsroomSectionSeedRows(sectionsConfigPath).map((row, index) => ({
     ...row,
     enabledStatus: "enabled",
@@ -828,7 +830,7 @@ function defaultNewsroomSections(importedAt: string, sectionsConfigPath = DEFAUL
   }));
 }
 
-function loadNewsroomSectionSeedRows(sectionsConfigPath = DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH) {
+function loadNewsroomSectionSeedRows(sectionsConfigPath: string) {
   const cached = newsroomSectionSeedRowsCache.get(sectionsConfigPath);
   if (cached) return cached;
   const parsed = YAML.parse(fs.readFileSync(sectionsConfigPath, "utf8")) as {
@@ -883,7 +885,7 @@ function normalizeNewsroomSectionSeedRow(
 
 export function createDemoCategorySteeringDashboard(
   brandId: SiteBrandId = resolveSiteBrandId(),
-  newsroomSectionsConfigPath = DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH,
+  newsroomSectionsConfigPath?: string,
 ): CategorySteeringDashboard {
   const importedAt = "2026-05-16T12:00:00.000Z";
   const profile = getNewsroomDemoProfile(brandId);
@@ -1698,7 +1700,7 @@ export function createDemoCategorySteeringDashboard(
           question: "Should this candidate source become a reference for this publication?",
           reviewControl: "thumbs",
           reviewReason: "program",
-          reviewDetail: "Every decision is reviewed while the cyclotron is onboarding.",
+          reviewDetail: "Every suggestion is reviewed while suggestions are getting started.",
           version: 1,
         }),
       },

package/lib/curation-routes.ts

@@ -0,0 +1,345 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { SITE_BRAND } from "./site-brand";
+import type { PublicationCapability } from "./prospectus-publication-access";
+import {
+  currentProspectusPublishingSelection,
+  signedInProspectusSession,
+  type ProspectusPublishingSelection,
+  type ProspectusSignInRouteOptions,
+} from "./prospectus-sign-in-routes";
+import { resolveProspectusSignInRuntime } from "./prospectus-session";
+import { SiteOriginNotConfiguredError, publicSiteOrigin } from "./site-origin";
+
+/**
+ * Same-origin curation routes for the References tab. Each is an authenticated
+ * pass-through to the curation upstream (the central Cyclotron lab): this
+ * module decides who may call and what they may ask, the upstream repeats its
+ * own checks, and neither trusts the browser's pins as identity.
+ *
+ * Order, failing closed at each step: upstream configured, Origin and body,
+ * sealed session cookie, fresh Prospectus re-authorization, scope pins,
+ * capability, forward, then re-authorize again and verify the echoed scope
+ * before any byte of the answer reaches the browser.
+ */
+export const CURATION_UPSTREAM_URL_ENV = "PAPYRUS_CURATION_UPSTREAM_URL";
+export const CURATION_PUBLICATION_ID_ENV = "PAPYRUS_CURATION_PUBLICATION_ID";
+export const CURATION_MAXIMUM_REQUEST_BYTES = 4_000_000;
+export const CURATION_MAXIMUM_RESPONSE_BYTES = 8_000_000;
+export const CURATION_UPSTREAM_TIMEOUT_MILLISECONDS = 15_000;
+
+export type CurationRoute = "context" | "publication" | "priming";
+
+export interface CurationRouteOptions extends ProspectusSignInRouteOptions {
+  /** Overrides PAPYRUS_CURATION_UPSTREAM_URL. null means not configured. */
+  upstreamUrl?: string | null;
+  /** Overrides PAPYRUS_CURATION_PUBLICATION_ID, which defaults to the site brand id. */
+  publicationId?: string;
+  fetcher?: typeof fetch;
+  timeoutMilliseconds?: number;
+}
+
+const NO_STORE_HEADERS = { "cache-control": "no-store", "x-content-type-options": "nosniff" };
+const PIN_HEADERS = ["x-cyclotron-account", "x-papyrus-publication", "x-papyrus-binding"] as const;
+const PUBLICATION_OPERATION_CAPABILITIES: Record<string, PublicationCapability> = {
+  decide: "decide",
+  review: "review",
+  status: "read",
+  history: "read",
+  events: "read",
+  replay: "read",
+  steer: "steer",
+};
+const FORWARDED_UPSTREAM_REFUSALS = new Set([400, 401, 403, 409, 413, 415, 503]);
+
+/** Editor-facing wording for the refusal codes the curation upstream returns. Unknown codes get a generic line. */
+export const UPSTREAM_REFUSAL_MESSAGES: Record<string, string> = {
+  pins_required: "Your account or publication selection is incomplete. Refresh the page and try again.",
+  invalid_request: "That request could not be understood. Refresh the page and try again.",
+  json_required: "That request could not be understood. Refresh the page and try again.",
+  bearer_invalid: "Sign in again: your session expired. Your selection is preserved.",
+  access_refused: "Your account does not have access to this publication.",
+  outside_publication: "That item is outside the publication you selected.",
+  account_changed: "The selected account or publication changed. Refresh and try again.",
+  operation_unavailable: "This action is not available yet.",
+  firewall_overlap: "This example is also in material kept aside for checking results, so it cannot be added.",
+  auto_prime_failed: "Your example could not be fully applied. Check saved history before retrying.",
+  request_too_large: "That request is too large. Try something smaller.",
+  import_too_large: "That file is too large. Try a smaller file.",
+  storage_limit: "This publication has reached its storage limit for imported examples.",
+  authority_unavailable: "Account access could not be confirmed right now. Try again shortly.",
+  priming_not_configured: "Importing examples is not set up for this publication yet.",
+  status_unavailable: "Monitoring is not available right now. Try again shortly.",
+  live_disabled: "Live decisions are switched off for this publication.",
+  no_hosted_transformer: "Adding a reference from a web address is not available. Import a file instead.",
+};
+const GENERIC_UPSTREAM_REFUSAL = "The curation service refused the request. Check saved history before retrying.";
+
+class CurationRefusal extends Error {
+  constructor(readonly status: number, readonly code: string, message: string) {
+    super(message);
+  }
+}
+
+function refusal(status: number, code: string, message: string): CurationRefusal {
+  return new CurationRefusal(status, code, message);
+}
+
+function jsonResponse(body: unknown, status = 200, extraHeaders: Record<string, string> = {}): NextResponse {
+  return NextResponse.json(body, { status, headers: { ...NO_STORE_HEADERS, ...extraHeaders } });
+}
+
+function upstreamBase(options: CurationRouteOptions): URL | null {
+  const configured = options.upstreamUrl !== undefined ? options.upstreamUrl : process.env[CURATION_UPSTREAM_URL_ENV];
+  if (!configured?.trim()) return null;
+  try {
+    const url = new URL(configured.trim());
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if (url.protocol !== "https:" && !(loopback && url.protocol === "http:")) return null;
+    if (url.username || url.password) return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function publicationIdFor(options: CurationRouteOptions): string {
+  return options.publicationId ?? (process.env[CURATION_PUBLICATION_ID_ENV]?.trim() || SITE_BRAND.id);
+}
+
+/** Which capability a priming GraphQL document needs. Any hint of a mutation requires review. */
+export function primingCapability(query: string): PublicationCapability {
+  return /\bmutation\b|\bprimingCommand\b/i.test(query) ? "review" : "read";
+}
+
+async function boundedText(request: NextRequest): Promise<string> {
+  const declared = Number(request.headers.get("content-length") ?? "0");
+  if (declared > CURATION_MAXIMUM_REQUEST_BYTES) throw refusal(413, "request_too_large", "Curation request exceeds the size limit.");
+  const text = await request.text();
+  if (Buffer.byteLength(text) > CURATION_MAXIMUM_REQUEST_BYTES) throw refusal(413, "request_too_large", "Curation request exceeds the size limit.");
+  return text;
+}
+
+async function boundedResponseText(response: Response): Promise<string> {
+  const declared = Number(response.headers.get("content-length") ?? "0");
+  if (declared > CURATION_MAXIMUM_RESPONSE_BYTES) throw refusal(502, "upstream_response_too_large", "The curation service answered too much.");
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > CURATION_MAXIMUM_RESPONSE_BYTES) {
+      await reader.cancel();
+      throw refusal(502, "upstream_response_too_large", "The curation service answered too much.");
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function sameSelection(left: ProspectusPublishingSelection, right: ProspectusPublishingSelection | null): boolean {
+  return right !== null
+    && left.personId === right.personId
+    && left.accountId === right.accountId
+    && left.role === right.role
+    && left.publicationCapabilities.join() === right.publicationCapabilities.join();
+}
+
+interface ParsedRequest {
+  capability: PublicationCapability;
+  /** Raw body to forward; undefined for the context read. */
+  body?: string;
+}
+
+function parseRequest(route: CurationRoute, text: string | null): ParsedRequest {
+  if (route === "context") return { capability: "read" };
+  let value: unknown;
+  try {
+    value = JSON.parse(text ?? "");
+  } catch {
+    throw refusal(400, "invalid_request", "A JSON curation request is required.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw refusal(400, "invalid_request", "A JSON curation request is required.");
+  const body = value as Record<string, unknown>;
+  if (route === "publication") {
+    const keys = Object.keys(body).sort().join();
+    const operation = typeof body.operation === "string" ? body.operation : "";
+    if (keys !== "operation,payload" || !Object.hasOwn(PUBLICATION_OPERATION_CAPABILITIES, operation) || !body.payload || typeof body.payload !== "object" || Array.isArray(body.payload)) {
+      throw refusal(400, "invalid_request", "An explicit publication operation is required.");
+    }
+    return { capability: PUBLICATION_OPERATION_CAPABILITIES[operation], body: text! };
+  }
+  const variablesValid = body.variables === undefined || (body.variables !== null && typeof body.variables === "object" && !Array.isArray(body.variables));
+  if (typeof body.query !== "string" || !body.query.trim() || !variablesValid || Object.keys(body).some((key) => key !== "query" && key !== "variables")) {
+    throw refusal(400, "invalid_request", "An explicit priming query is required.");
+  }
+  return { capability: primingCapability(body.query), body: text! };
+}
+
+function requestPins(request: NextRequest, selection: ProspectusPublishingSelection, publicationId: string): Record<(typeof PIN_HEADERS)[number], string> {
+  const pins = Object.fromEntries(PIN_HEADERS.map((name) => [name, request.headers.get(name)?.trim() ?? ""])) as Record<(typeof PIN_HEADERS)[number], string>;
+  if (PIN_HEADERS.some((name) => !pins[name])) throw refusal(400, "pins_required", "Expected account, publication and binding pins are required.");
+  if (pins["x-cyclotron-account"] !== selection.accountId || pins["x-papyrus-publication"] !== publicationId) {
+    throw refusal(409, "account_changed", "The selected account or publication changed. Refresh and try again.");
+  }
+  return pins;
+}
+
+function authorizedCapabilities(selection: ProspectusPublishingSelection): PublicationCapability[] {
+  return selection.publicationCapabilities;
+}
+
+async function forward(
+  request: NextRequest,
+  route: CurationRoute,
+  base: URL,
+  options: CurationRouteOptions,
+  accessToken: string,
+  upstreamHeaders: Record<string, string>,
+  body: string | undefined,
+): Promise<Response> {
+  const target = new URL(`/api/newsroom/curation/${route}`, base);
+  const headers: Record<string, string> = {
+    ...upstreamHeaders,
+    authorization: `Bearer ${accessToken}`,
+    accept: "application/json",
+  };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  const response = await (options.fetcher ?? fetch)(target, {
+    method: route === "context" ? "GET" : "POST",
+    headers,
+    body,
+    redirect: "manual",
+    cache: "no-store",
+    signal: AbortSignal.timeout(options.timeoutMilliseconds ?? CURATION_UPSTREAM_TIMEOUT_MILLISECONDS),
+  });
+  if (response.status >= 300 && response.status < 400) throw refusal(502, "upstream_redirect", "The curation service redirected, which is refused.");
+  return response;
+}
+
+function sanitizedUpstreamRefusal(status: number, text: string): CurationRefusal {
+  let code = "";
+  try {
+    const parsed = JSON.parse(text) as { code?: unknown };
+    code = typeof parsed.code === "string" ? parsed.code : "";
+  } catch {
+    code = "";
+  }
+  const known = Object.hasOwn(UPSTREAM_REFUSAL_MESSAGES, code);
+  return refusal(status, known ? code : "upstream_refused", known ? UPSTREAM_REFUSAL_MESSAGES[code] : GENERIC_UPSTREAM_REFUSAL);
+}
+
+function validPriming(value: unknown): Record<string, unknown> | null {
+  const priming = value as { listId?: unknown; classifiers?: unknown; transformers?: unknown } | null;
+  if (!priming || typeof priming.listId !== "string" || !priming.listId || !Array.isArray(priming.classifiers) || !priming.classifiers.length) return null;
+  return { listId: priming.listId, classifiers: priming.classifiers, transformers: Array.isArray(priming.transformers) ? priming.transformers : [] };
+}
+
+function contextBootstrap(value: unknown, selection: ProspectusPublishingSelection, publicationId: string): Record<string, unknown> {
+  const body = value as { scope?: Record<string, unknown>; mode?: unknown; priming?: unknown; capabilities?: unknown; bindingRef?: unknown } | null;
+  const scope = body?.scope;
+  if (!scope || scope.accountId !== selection.accountId || scope.publicationId !== publicationId
+    || typeof scope.bindingRevision !== "string" || !scope.bindingRevision
+    || (body!.mode !== "embedded" && body!.mode !== "remote") || !Array.isArray(body!.capabilities)) {
+    throw refusal(502, "upstream_scope_mismatch", "The curation service answered for a different scope.");
+  }
+  const granted = new Set<string>(authorizedCapabilities(selection));
+  return {
+    scope: { accountId: scope.accountId, publicationId: scope.publicationId, bindingRevision: scope.bindingRevision },
+    mode: body!.mode,
+    priming: validPriming(body!.priming),
+    capabilities: body!.capabilities.filter((capability): capability is string => typeof capability === "string" && granted.has(capability)),
+    bindingRef: body!.bindingRef ?? null,
+  };
+}
+
+function verifiedPublicationEnvelope(value: unknown, pins: Record<string, string>): void {
+  const envelope = value as Record<string, unknown> | null;
+  if (!envelope || envelope.contractVersion !== "cyclotron-publication/v1"
+    || envelope.accountId !== pins["x-cyclotron-account"]
+    || envelope.publicationId !== pins["x-papyrus-publication"]
+    || envelope.bindingRevision !== pins["x-papyrus-binding"]) {
+    throw refusal(502, "upstream_scope_mismatch", "The curation service answered for a different scope.");
+  }
+}
+
+export async function handleCurationRoute(request: NextRequest, route: CurationRoute, options: CurationRouteOptions = {}): Promise<NextResponse> {
+  try {
+    const base = upstreamBase(options);
+    if (!base) return jsonResponse({ error: "curation_not_configured", message: "Curation is not configured for this site." }, 503);
+
+    const origin = request.headers.get("origin");
+    const siteOrigin = publicSiteOrigin(request, options.environment);
+    if (route !== "context" ? origin !== siteOrigin : origin !== null && origin !== siteOrigin) {
+      throw refusal(403, "cross_origin", "Curation requests must come from this site.");
+    }
+    let text: string | null = null;
+    if (route !== "context") {
+      if (request.headers.get("content-type")?.split(";")[0].trim() !== "application/json") throw refusal(415, "json_required", "A JSON request is required.");
+      text = await boundedText(request);
+    }
+
+    const runtime = await (options.resolveRuntime ?? resolveProspectusSignInRuntime)(siteOrigin);
+    if (!runtime) return jsonResponse({ error: "prospectus_sign_in_unavailable", message: "Sign-in through Prospectus is not configured for this site." }, 503);
+    const nowInSeconds = options.nowInSeconds?.();
+    const cookieSession = signedInProspectusSession(request, runtime.sealingSecret, nowInSeconds);
+    if (!cookieSession?.selectedAccountId) throw refusal(401, "signed_out", "Sign in and choose an account first.");
+
+    const selection = await currentProspectusPublishingSelection(request, options);
+    if (!selection || selection.accountId !== cookieSession.selectedAccountId) throw refusal(403, "not_authorized", "Your account no longer grants access.");
+
+    const publicationId = publicationIdFor(options);
+    const pins = route === "context" ? null : requestPins(request, selection, publicationId);
+    const parsed = parseRequest(route, text);
+    if (!authorizedCapabilities(selection).includes(parsed.capability)) throw refusal(403, "capability_refused", "Your role does not allow this curation action.");
+
+    // The token is read from the sealed cookie again for this call, never held across calls.
+    const fresh = signedInProspectusSession(request, runtime.sealingSecret, nowInSeconds);
+    if (!fresh || fresh.selectedAccountId !== selection.accountId) throw refusal(401, "signed_out", "Sign in and choose an account first.");
+    const upstreamHeaders = pins ?? { "x-cyclotron-account": selection.accountId, "x-papyrus-publication": publicationId };
+    const upstream = await forward(request, route, base, options, fresh.accessToken, upstreamHeaders, parsed.body);
+    const upstreamText = await boundedResponseText(upstream);
+    if (upstream.status !== 200) {
+      if (FORWARDED_UPSTREAM_REFUSALS.has(upstream.status)) throw sanitizedUpstreamRefusal(upstream.status, upstreamText);
+      throw refusal(502, "upstream_failed", "The curation service could not complete the request. Check saved history before retrying.");
+    }
+
+    // Post-upstream check: nothing is released if authority or scope moved while we waited.
+    if (!sameSelection(selection, await currentProspectusPublishingSelection(request, options))) {
+      throw refusal(409, "account_changed", "The selected account or access changed. Refresh and try again.");
+    }
+    let answer: unknown;
+    try {
+      answer = JSON.parse(upstreamText);
+    } catch {
+      throw refusal(502, "upstream_invalid", "The curation service answered with an invalid response.");
+    }
+    if (pins) {
+      if (PIN_HEADERS.some((name) => upstream.headers.get(name) !== pins[name])) {
+        throw refusal(502, "upstream_scope_mismatch", "The curation service answered for a different scope.");
+      }
+      if (route === "publication") verifiedPublicationEnvelope(answer, pins);
+      if (route === "priming" && (!answer || typeof answer !== "object" || Array.isArray(answer))) {
+        throw refusal(502, "upstream_invalid", "The curation service answered with an invalid response.");
+      }
+      return jsonResponse(answer, 200, pins);
+    }
+    const bootstrap = contextBootstrap(answer, selection, publicationId);
+    const bindingRevision = (bootstrap.scope as { bindingRevision: string }).bindingRevision;
+    if (upstream.headers.get("x-cyclotron-account") !== selection.accountId
+      || upstream.headers.get("x-papyrus-publication") !== publicationId
+      || upstream.headers.get("x-papyrus-binding") !== bindingRevision) {
+      throw refusal(502, "upstream_scope_mismatch", "The curation service answered for a different scope.");
+    }
+    return jsonResponse(bootstrap, 200, {
+      "x-cyclotron-account": selection.accountId, "x-papyrus-publication": publicationId, "x-papyrus-binding": bindingRevision,
+    });
+  } catch (error) {
+    if (error instanceof CurationRefusal) return jsonResponse({ error: error.message, code: error.code }, error.status);
+    if (error instanceof SiteOriginNotConfiguredError) return jsonResponse({ error: error.message, code: error.code }, error.status);
+    console.error(`Curation route failed (${error instanceof Error ? error.name : "error"}).`);
+    return jsonResponse({ error: "Curation is unavailable. Check saved history before retrying.", code: "curation_unavailable" }, 503);
+  }
+}

package/lib/cyclotron-suggestions.ts

@@ -187,8 +187,8 @@ export function curationForSuggestionChoice(decision: RelevanceDecisionView, cho
 }
 
 export type ProvenanceSummary = {
-  teachingLabelsSentence: string;
-  primingExamplesSentence: string;
+  teachingLabelsSentence: string | null;
+  primingExamplesSentence: string | null;
   doctrineShortHash: string | null;
   modelVersion: string | null;
   decidedAt: string | null;
@@ -202,8 +202,8 @@ export function provenanceSummary(decision: RelevanceDecisionView): ProvenanceSu
   if (!provenance) return null;
   const plural = (count: number, singular: string) => `${count} ${singular}${count === 1 ? "" : "s"}`;
   return {
-    teachingLabelsSentence: `Based on ${plural(provenance.teachingLabels, "decision")} that editors made themselves`,
-    primingExamplesSentence: `${plural(provenance.primingExamples, "example reference")} supplied as starting examples`,
+    teachingLabelsSentence: provenance.teachingLabels === null ? null : `Based on ${plural(provenance.teachingLabels, "decision")} that editors made themselves`,
+    primingExamplesSentence: provenance.primingExamples === null ? null : `${plural(provenance.primingExamples, "example reference")} supplied as starting examples`,
     doctrineShortHash: provenance.doctrineFingerprint ? provenance.doctrineFingerprint.slice(0, SHORT_HASH_LENGTH) : null,
     modelVersion: decision.version === null ? null : `revision ${decision.version}`,
     decidedAt: decision.decidedAt,