@anthusai/papyrus 2.0.0-next.11 → 2.0.0-next.110

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,

package/lib/editorial-checks-client.ts

@@ -161,6 +161,24 @@ export async function importStarterPack(name: string): Promise<{ created: number
   return parsed(data.importEditorialStarterPack);
 }
 
+export type StarterPackSummary = {
+  name: string;
+  title: string;
+  version?: string | null;
+  language?: string | null;
+  guidance?: string | null;
+  policyCount: number;
+  importedCount: number;
+  isDefault: boolean;
+  policies: { id: string; title?: string | null; severity?: string | null; tags: string[]; lanes: string[] }[];
+};
+
+/** The starter packs the site's Humanus ships, with how many of each pack's policies the site already has. */
+export async function listStarterPacks(): Promise<{ humanusVersion?: string | null; packs: StarterPackSummary[] }> {
+  const data = await call<{ listEditorialStarterPacks: unknown }>(`query ListStarterPacks { listEditorialStarterPacks }`);
+  return parsed(data.listEditorialStarterPacks);
+}
+
 export async function tryPolicy(policy: Record<string, unknown>, text: string): Promise<EditorialCheckResult> {
   const data = await call<{ tryEditorialPolicy: unknown }>(
     `query TryEditorialPolicy($policy: AWSJSON!, $text: String!) { tryEditorialPolicy(policy: $policy, text: $text, format: "markus") }`,

package/lib/editorial-checks-demo.ts

@@ -1,6 +1,6 @@
 /**
  * Demo-mode editorial checks: no backend, a few stock phrases, canned rewrites.
- * The shapes match Limatus results so the editor, the preview marks and the
+ * The shapes match Humanus results so the editor, the preview marks and the
  * rewrite flow behave as they do against the real backend.
  */
 import type { EditorialCheckResult, EditorialFinding, EditorialSegment, RewriteResult, Span } from "./editorial-checks";

package/lib/editorial-checks.ts

@@ -1,6 +1,6 @@
 /**
- * Editorial checks: the Limatus result shapes the newsroom uses, and pure helpers
- * over them. Limatus counts offsets in UTF-16 code units, which is exactly how
+ * Editorial checks: the Humanus result shapes the newsroom uses, and pure helpers
+ * over them. Humanus counts offsets in UTF-16 code units, which is exactly how
  * JavaScript indexes strings, so spans apply to the body text as they are.
  */
 
@@ -38,7 +38,8 @@ export type EditorialSegment = {
   text?: string;
 };
 
-export type LaneStatus = { status: "ran" | "disabled" | "unavailable" | "failed" | "partial"; reason?: string; detectors?: number };
+/** "skipped": Papyrus did not ask for judgments because the publication has no mission or policy for them to apply. */
+export type LaneStatus = { status: "ran" | "disabled" | "unavailable" | "failed" | "partial" | "skipped"; reason?: string; detectors?: number };
 
 export type EditorialCheckResult = {
   schemaVersion: 1;
@@ -49,7 +50,8 @@ export type EditorialCheckResult = {
   protected: { kind: string; start: number; end: number }[];
   findings: EditorialFinding[];
   coverage: unknown[];
-  lanes: { rules: LaneStatus; classifier: LaneStatus };
+  /** lanes.section is "skipped" when the story's section has no NewsroomSection record to take a mission and policy from. */
+  lanes: { rules: LaneStatus; classifier: LaneStatus; section?: LaneStatus };
   usage?: Record<string, number>;
 };
 
@@ -164,8 +166,10 @@ export function describeProbability(finding: EditorialFinding): string | null {
 
 export function laneNotice(result: EditorialCheckResult): string | null {
   const classifier = result.lanes.classifier;
+  if (classifier.status === "skipped") return `Mission-based checks skipped: ${classifier.reason ?? "this publication has no mission yet"}.`;
   if (classifier.status === "partial") return `Some sentences were not judged: ${classifier.reason ?? "the check ran out of time"}.`;
   if (classifier.status === "failed") return `The judgment checks failed: ${classifier.reason ?? "unknown error"}. Rule checks still ran.`;
   if (classifier.status === "unavailable" && (classifier.detectors ?? 0) === 0 && classifier.reason) return `Judgment checks are not configured: ${classifier.reason}.`;
+  if (result.lanes.section?.status === "skipped") return `Section-based checks skipped: ${result.lanes.section.reason ?? "no section configuration"}.`;
   return null;
 }

package/lib/editorial-preview.ts

@@ -1,12 +1,12 @@
 /**
- * Places Limatus findings on the rendered Markus preview.
+ * Places Humanus findings on the rendered Markus preview.
  *
- * Limatus reports spans in the markup; the preview renders an IR tree with no
+ * Humanus reports spans in the markup; the preview renders an IR tree with no
  * character offsets. Both sides agree on the words a reader sees, so findings
- * are placed by text: each Limatus paragraph is matched, in document order, to
+ * are placed by text: each Humanus paragraph is matched, in document order, to
  * the rendered prose block with the same words, and each finding's plain
  * excerpt is located inside that block. Whitespace is ignored while matching,
- * because rendering and Limatus collapse it differently (citations, breaks).
+ * because rendering and Humanus collapse it differently (citations, breaks).
  *
  * "Rendered text" is defined by `inlineLeaves`, which the preview renderer also
  * uses, so offsets computed here are offsets the renderer can split on.
@@ -131,7 +131,7 @@ function blockKey(text: string): string {
   return compact(text).value.replace(/[*_`~]/g, "");
 }
 
-/** Match every Limatus paragraph to a rendered block and place its findings and sentences there. */
+/** Match every Humanus paragraph to a rendered block and place its findings and sentences there. */
 export function planPreview(
   document: MarkusDocument,
   result: EditorialCheckResult,

package/lib/monitoring-client.ts

@@ -0,0 +1,83 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import { emailReferenceBatches } from "./monitoring-overview";
+import type {
+  EmailReferenceImportItem,
+  EmailReferenceImportOutcome,
+  MonitoringEmailArticleResolution,
+  MonitoringEmailDetails,
+  MonitoringResult,
+} from "./monitoring-overview";
+
+type QueryField = "monitoringOverview" | "monitoringEmailSubmission" | "monitoringResolveEmailArticleLink" | "intakeEmailSubmissionReferences";
+type GraphQLResult = { data?: Partial<Record<QueryField, unknown>>; errors?: { message?: string; errorType?: string }[] };
+
+async function query<T>(field: QueryField, queryText: string, variables: Record<string, string | number>): Promise<T | { error: "forbidden" } | { state: "unavailable" }> {
+  const client = generateClient({ authMode: "userPool" });
+  let result: GraphQLResult;
+  try {
+    result = (await client.graphql({ query: queryText, variables })) as GraphQLResult;
+  } catch (error) {
+    result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+  const refused = result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`));
+  if (refused) return { error: "forbidden" };
+  const raw = result.data?.[field];
+  if (result.errors?.length || raw === undefined || raw === null) return { state: "unavailable" };
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as T;
+}
+
+/** Reads monitoring data only through the site's authenticated editor/admin API. */
+export async function loadMonitoringOverview(scope: "publication" | "all"): Promise<MonitoringResult> {
+  return query<MonitoringResult>("monitoringOverview",
+    `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`, { scope });
+}
+
+/** Loads one receipt's safe plain-text rendering and its already extracted candidate links. */
+export async function loadMonitoringEmailSubmission(receiptId: string): Promise<MonitoringEmailDetails> {
+  return query<MonitoringEmailDetails>("monitoringEmailSubmission",
+    `query MonitoringEmailSubmission($receiptId: String!) { monitoringEmailSubmission(receiptId: $receiptId) }`, { receiptId });
+}
+
+/** Resolve one explicitly selected Beehiiv article redirect; this may register a click with the sender. */
+export async function resolveMonitoringEmailArticleLink(receiptId: string, candidateIndex: number): Promise<MonitoringEmailArticleResolution> {
+  return query<MonitoringEmailArticleResolution>("monitoringResolveEmailArticleLink",
+    `mutation MonitoringResolveEmailArticleLink($receiptId: String!, $candidateIndex: Int!) { monitoringResolveEmailArticleLink(receiptId: $receiptId, candidateIndex: $candidateIndex) }`,
+    { receiptId, candidateIndex });
+}
+
+/** Use the existing editor-authorized Reference intake; 20 is its request batch size, not a total limit. */
+export async function importMonitoringEmailCandidates(
+  receiptId: string,
+  items: EmailReferenceImportItem[],
+): Promise<EmailReferenceImportOutcome> {
+  const client = generateClient({ authMode: "userPool" });
+  const references: EmailReferenceImportOutcome["references"] = [];
+  for (const batch of emailReferenceBatches(items)) {
+    let result: GraphQLResult;
+    try {
+      result = (await client.graphql({
+        query: `mutation IntakeEmailSubmissionReferences($input: AWSJSON!) { intakeEmailSubmissionReferences(input: $input) }`,
+        variables: { input: JSON.stringify({ receiptId, items: batch }) },
+      })) as GraphQLResult;
+    } catch {
+      return { imported: references.length, references, error: "The import stopped. Completed links are safe to retry." };
+    }
+    if (result.errors?.length) {
+      return { imported: references.length, references, error: "The import stopped. Completed links are safe to retry." };
+    }
+    const raw = result.data?.intakeEmailSubmissionReferences;
+    let response: { ok?: boolean; references?: EmailReferenceImportOutcome["references"] } | null | undefined;
+    try {
+      response = (typeof raw === "string" ? JSON.parse(raw) : raw) as typeof response;
+    } catch {
+      return { imported: references.length, references, error: "The import response could not be read. Completed links are safe to retry." };
+    }
+    if (!response?.ok || !Array.isArray(response.references)) {
+      return { imported: references.length, references, error: "The import was not accepted. Check your editor access and retry." };
+    }
+    references.push(...response.references);
+  }
+  return { imported: references.length, references };
+}

package/lib/monitoring-overview-fixture.ts

@@ -0,0 +1,51 @@
+import type { MonitoringOverview } from "./monitoring-overview";
+
+/** A realistic overview for tests and the `?demo=1` newsroom. Public Hacker News titles only. */
+export const FIXTURE_MONITORING_OVERVIEW: MonitoringOverview = {
+  state: "ready",
+  asOf: "2026-10-21T02:40:00Z",
+  scope: { mode: "publication", publicationId: "desk-a", site: "a.example.test", canViewAll: true },
+  feeds: [{ id: "hn", sourceUrl: "https://news.ycombinator.com/rss", intervalSeconds: 900, limit: 30, enabled: true,
+    lastStatus: "complete", lastFinishedAt: "2026-10-21T02:33:00Z", nextDueAt: "2026-10-21T02:50:00Z" }],
+  runs: [
+    { runId: "r3", startedAt: "2026-10-21T02:33:00.000000Z", status: "complete", new: 2, revised: 1, unchanged: 27, itemCount: 30, errorCount: 0, errors: [] },
+    { runId: "r1", startedAt: "2026-10-21T02:18:00.000000Z", status: "complete", new: 0, revised: 0, unchanged: 30, itemCount: 30, errorCount: 0, errors: [] },
+    { runId: "r0", startedAt: "2026-10-21T02:03:00.000000Z", status: "partial", new: 1, revised: 0, unchanged: 28, itemCount: 30, errorCount: 1, errors: ["ConnectionError: timeout"] },
+  ],
+  routerRuns: [{ runId: "q2", startedAt: "2026-10-21T02:37:00.000000Z", mode: "live", status: "stopped", stoppedBy: "request_ceiling_reached",
+    counts: { examined: 3, decided: 1, delivered: 1, deliveryFailed: 1, routed: 1 }, errorCount: 0 }],
+  router: { mode: "live", feedback: true, enabled: true, maxItemsPerRun: 5 },
+  usage: { day: "2026-10-21", decisionsToday: 2, decisionsTotal: 3, historyComplete: true },
+  hiddenNotRelevant: 1,
+  items: [
+    { sourceId: "104", revision: 1, title: "Fresh Show HN", url: "https://example.org/104", discussionUrl: "https://news.ycombinator.com/item?id=104",
+      observedAt: "2026-10-21T02:30:00.000000Z", routing: "collected", routingNote: null, decidedAt: null,
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: null, label: null, confidence: null, delivery: { state: null } }] },
+    { sourceId: "105", revision: 1, title: "Broken request", url: "https://example.org/105", discussionUrl: "https://news.ycombinator.com/item?id=105",
+      observedAt: "2026-10-21T01:30:00.000000Z", routing: "error", routingNote: "invalid request: bad title", decidedAt: null,
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: null, label: null, confidence: null, delivery: { state: null } }] },
+    { sourceId: "101", revision: 1, title: "Quantum paper on arXiv", url: "https://example.org/101", discussionUrl: "https://news.ycombinator.com/item?id=101",
+      observedAt: "2026-10-21T00:10:00.000000Z", routing: "routed", routingNote: null, decidedAt: "2026-10-21T01:00:00Z",
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: true, label: "include", confidence: 0.91,
+        delivery: { state: "delivered", referenceId: "ref-1", referenceLineageId: "lin-1", deliveredAt: "2026-10-21T01:00:05Z" } }] },
+    { sourceId: "103", revision: 1, title: "Phishing kit leaks", url: "https://example.org/103", discussionUrl: "https://news.ycombinator.com/item?id=103",
+      observedAt: "2026-10-20T23:00:00.000000Z", routing: "decided", routingNote: null, decidedAt: "2026-10-20T23:10:00Z",
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: true, label: "include", confidence: 0.7,
+        delivery: { state: "failed", error: "ClientError: throttled", attempts: 2 } }] },
+  ],
+};
+
+export const FIXTURE_ALL_PIPELINE_OVERVIEW: MonitoringOverview = {
+  ...FIXTURE_MONITORING_OVERVIEW,
+  scope: { mode: "all", publicationId: "desk-a", site: "a.example.test", canViewAll: true },
+  hiddenNotRelevant: 0,
+  items: FIXTURE_MONITORING_OVERVIEW.items.map((item) => item.sourceId !== "101" ? item : {
+    ...item,
+    relevance: [
+      ...item.relevance,
+      { publicationId: "desk-b", site: "b.example.test", relevant: false, label: "exclude", confidence: 0.8, delivery: { state: "not_applicable" } },
+      { publicationId: "desk-c", site: "desk-c", relevant: true, label: "include", confidence: null,
+        delivery: { state: "delivered", referenceId: "ref-2", referenceLineageId: "lin-2" } },
+    ],
+  }),
+};