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

package/lib/relevance-decisions.ts

@@ -7,8 +7,12 @@ export type RelevanceProvenance = {
   labelSet: string[];
   doctrineFingerprint: string | null;
   teachingFingerprint: string | null;
-  teachingLabels: number;
-  primingExamples: number;
+  teachingLabels: number | null;
+  primingExamples: number | null;
+  /** Recorded by the shared monitoring router, absent on local sweep provenance. */
+  system?: string;
+  publicationId?: string;
+  output?: string;
 };
 
 /** The relevance cyclotron's current decision about one reference, as the References tab shows it. */
@@ -28,6 +32,7 @@ export type RelevanceDecisionView = {
   /** Thumbs for a two-class decision with a positive label; per-class buttons otherwise. */
   reviewControl: "thumbs" | "labels";
   cyclotronId: string | null;
+  classifierId?: string;
   /** When the cyclotron made the suggestion, if the decision recorded it. */
   decidedAt: string | null;
   /** Null for decisions made before provenance was recorded. */
@@ -44,6 +49,7 @@ export type RelevanceReview = {
 
 /** The existing curation action an editor's review becomes. */
 export type RelevanceCuration = {
+  sectionId?: string | null;
   action: "accept" | "reject";
   reasonCode: string | null;
   note: string | null;
@@ -65,7 +71,7 @@ function parseMetadata(value: unknown): Record<string, unknown> {
 function parseProvenance(value: unknown): RelevanceProvenance | null {
   const record = parseMetadata(value);
   if (!Object.keys(record).length) return null;
-  const count = (entry: unknown) => (Number.isFinite(Number(entry)) ? Number(entry) : 0);
+  const count = (entry: unknown) => typeof entry === "number" && Number.isInteger(entry) && entry >= 0 ? entry : null;
   const text = (entry: unknown) => (typeof entry === "string" && entry ? entry : null);
   return {
     labelSet: Array.isArray(record.labelSet) ? record.labelSet.map(String) : [],
@@ -73,27 +79,52 @@ function parseProvenance(value: unknown): RelevanceProvenance | null {
     teachingFingerprint: text(record.teachingFingerprint),
     teachingLabels: count(record.teachingLabels),
     primingExamples: count(record.primingExamples),
+    ...(text(record.system) ? { system: text(record.system)! } : {}),
+    ...(text(record.publicationId) ? { publicationId: text(record.publicationId)! } : {}),
+    ...(text(record.output) ? { output: text(record.output)! } : {}),
   };
 }
 
+function recordedVersion(value: unknown): number | null {
+  if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "") return null;
+  const version = Number(value);
+  return Number.isInteger(version) && version >= 0 ? version : null;
+}
+
+function decisionTime(relation: SemanticRelationRecord): number {
+  const metadata = parseMetadata(relation.metadata);
+  for (const value of [metadata.decidedAt, relation.importedAt, relation.createdAt]) {
+    if (typeof value !== "string") continue;
+    const timestamp = Date.parse(value);
+    if (Number.isFinite(timestamp)) return timestamp;
+  }
+  return 0;
+}
+
 /**
  * Current decisions keyed by reference lineage, from relations the Newsroom
  * already loads: no extra request per row.
  */
 export function currentRelevanceDecisions(relations: SemanticRelationRecord[]): Map<string, RelevanceDecisionView> {
   const decisions = new Map<string, RelevanceDecisionView>();
-  for (const relation of relations) {
-    if (relation.predicate !== RELEVANCE_RELATION || relation.relationState !== "current") continue;
+  // Realtime events can briefly expose both sides of a superseding write. The
+  // result must not depend on list pagination or subscription arrival order.
+  const ordered = [...relations].sort((left, right) => decisionTime(left) - decisionTime(right) || left.id.localeCompare(right.id));
+  for (const relation of ordered) {
+    if (relation.predicate !== RELEVANCE_RELATION || relation.relationState !== "current" || relation.subjectKind !== "reference") continue;
     const metadata = parseMetadata(relation.metadata);
+    if (!relation.subjectLineageId || typeof metadata.label !== "string" || !metadata.label.trim()
+      || typeof metadata.decisionId !== "string" || !metadata.decisionId.trim()) continue;
     const probabilities = parseMetadata(metadata.probabilities);
     const reason = metadata.reviewReason === "program" || metadata.reviewReason === "audit" ? metadata.reviewReason : null;
-    const version = Number(relation.modelVersion ?? metadata.version);
+    const version = recordedVersion(relation.modelVersion ?? metadata.version);
     decisions.set(relation.subjectLineageId, {
       decisionRelationId: relation.id,
-      decisionId: String(metadata.decisionId ?? ""),
-      label: String(metadata.label ?? ""),
-      confidence: typeof relation.confidence === "number" ? relation.confidence : null,
-      version: Number.isFinite(version) ? version : null,
+      decisionId: metadata.decisionId,
+      label: metadata.label,
+      confidence: typeof relation.confidence === "number" && Number.isFinite(relation.confidence)
+        && relation.confidence >= 0 && relation.confidence <= 1 ? relation.confidence : null,
+      version,
       reviewRecommended: Boolean(relation.reviewRecommended),
       reviewReason: reason,
       reviewDetail: typeof metadata.reviewDetail === "string" ? metadata.reviewDetail : null,
@@ -104,6 +135,7 @@ export function currentRelevanceDecisions(relations: SemanticRelationRecord[]):
       question: typeof metadata.question === "string" ? metadata.question : null,
       reviewControl: metadata.reviewControl === "thumbs" ? "thumbs" : "labels",
       cyclotronId: typeof metadata.cyclotronId === "string" ? metadata.cyclotronId : null,
+      ...(relation.classifierId ? { classifierId: relation.classifierId } : {}),
       decidedAt: typeof metadata.decidedAt === "string" ? metadata.decidedAt : null,
       provenance: parseProvenance(metadata.provenance),
     });

package/lib/relevance-status.ts

@@ -52,10 +52,10 @@ export const DEMO_CYCLOTRON_STATUS: CyclotronStatus = {
   },
   calibration: { saysSure: null, isRight: null, gapPoints: null, curve: [] },
   reviewRate: {
-    state: "onboarding", rate: 1, reason: "Onboarding: every decision is reviewed until the cyclotron earns a lower rate.",
+    state: "onboarding", rate: 1, reason: "Getting started: every suggestion is reviewed until suggestions earn a lower review rate.",
     auditFloor: 0.05, confidenceThreshold: 0.7, override: null,
     nextCheckAfterDecisions: 99,
-    nextStep: "Steps down to 50% after 2 more windows of 100 decisions with accuracy on confident decisions of at least 85% (at least 20 reviewed) and a calibration gap under 5 points. Next check in 99 decisions.",
+    nextStep: "Steps down to 50% after 2 more windows of 100 decisions with accuracy on confident decisions of at least 85% (at least 20 reviewed) and a gap under 5 points between how sure suggestions say they are and how often they are right. Next check in 99 decisions.",
     expectedReviewsPerWeek: 1,
   },
   lastChange: null,

package/lib/review-client.ts

@@ -0,0 +1,99 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import { getCurrentUser } from "aws-amplify/auth";
+import {
+  answerUpdate, isDue, normalizeReviewRow, timeoutUpdate,
+  type AnswerInput, type ReviewRequest,
+} from "./review-requests";
+
+/**
+ * Review requests through the site's own authenticated API (user pool; editors and admins). The condition `state = open`
+ * on every change means two people answering at once, or an answer racing the deadline, cannot both win.
+ */
+
+const FIELDS = "id subject mode reason ask raisedBy raisedAt deadline state answer links history appliedIn updatedAt";
+const MAX_PAGES = 10;
+
+type GraphQLResult = { data?: Record<string, any>; errors?: { message?: string; errorType?: string }[] };
+
+async function run(query: string, variables: Record<string, unknown>): Promise<GraphQLResult> {
+  const client = generateClient({ authMode: "userPool" });
+  try {
+    return (await client.graphql({ query, variables })) as GraphQLResult;
+  } catch (error) {
+    // Amplify throws the response when AppSync returns errors.
+    return (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+}
+
+export type ReviewLoad = { state: "ready"; requests: ReviewRequest[]; readIds: string[]; userKey: string } | { state: "forbidden" } | { state: "unavailable" };
+
+export async function currentUserKey(): Promise<string> {
+  return (await getCurrentUser()).userId;
+}
+
+/** Loads every request (newest pages first), marks due soft reviews as timed out ("proceeded without review"), and reads this user's marks. */
+export async function loadReviews(now: Date = new Date()): Promise<ReviewLoad> {
+  let userKey: string;
+  try {
+    userKey = await currentUserKey();
+  } catch {
+    return { state: "unavailable" };
+  }
+  const rows: Record<string, unknown>[] = [];
+  let nextToken: string | null = null;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const result = await run(
+      `query ListReviews($limit: Int, $nextToken: String) { listReviewRequests(limit: $limit, nextToken: $nextToken) { items { ${FIELDS} } nextToken } }`,
+      { limit: 500, nextToken },
+    );
+    if (result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) return { state: "forbidden" };
+    const connection = result.data?.listReviewRequests;
+    if (result.errors?.length || !connection) return { state: "unavailable" };
+    rows.push(...connection.items.filter(Boolean));
+    nextToken = connection.nextToken ?? null;
+    if (!nextToken) break;
+  }
+  const requests = rows.map(normalizeReviewRow);
+  for (const [index, request] of requests.entries()) {
+    if (!isDue(request, now)) continue;
+    const update = timeoutUpdate(request, now);
+    const written = await run(
+      `mutation Expire($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+      { input: update, condition: { state: { eq: "open" } } },
+    );
+    const row = written.data?.updateReviewRequest;
+    requests[index] = row ? normalizeReviewRow(row) : { ...request, state: "timed_out", updatedAt: String(update.updatedAt), history: JSON.parse(String(update.history)) };
+  }
+  const marks = await run(
+    `query Marks($filter: ModelReviewReadMarkFilterInput, $limit: Int) { listReviewReadMarks(filter: $filter, limit: $limit) { items { requestId } } }`,
+    { filter: { userKey: { eq: userKey } }, limit: 5000 },
+  );
+  const readIds = (marks.data?.listReviewReadMarks?.items ?? []).filter(Boolean).map((mark: { requestId: string }) => mark.requestId);
+  return { state: "ready", requests, readIds, userKey };
+}
+
+/** Records an answer. Throws an Error with a sentence for the page when the request is closed or the write loses a race. */
+export async function answerReviewRequest(request: ReviewRequest, input: AnswerInput, by: string, now: Date = new Date()): Promise<ReviewRequest> {
+  const update = answerUpdate(request, input, by, now);
+  const result = await run(
+    `mutation Answer($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+    { input: update, condition: { state: { eq: "open" } } },
+  );
+  if (result.errors?.some((entry) => /conditional/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) {
+    throw new Error("Someone else answered this, or it proceeded at its deadline. Refresh to see the result.");
+  }
+  if (result.errors?.length || !result.data?.updateReviewRequest) throw new Error("Could not save the answer. Nothing was changed.");
+  return normalizeReviewRow(result.data.updateReviewRequest);
+}
+
+/** This user has seen the request. Create the mark; if it exists, refresh it. */
+export async function markReviewRead(userKey: string, requestId: string, now: Date = new Date()): Promise<void> {
+  const input = { id: `${userKey}#${requestId}`, requestId, userKey, readAt: now.toISOString() };
+  const created = await run(
+    `mutation Mark($input: CreateReviewReadMarkInput!) { createReviewReadMark(input: $input) { id } }`, { input });
+  if (created.errors?.length) {
+    await run(`mutation Mark($input: UpdateReviewReadMarkInput!) { updateReviewReadMark(input: $input) { id } }`, { input });
+  }
+}

package/lib/review-fixture.ts

@@ -0,0 +1,45 @@
+import type { ReviewRequest } from "./review-requests";
+
+/** Demo and test data: one of each mode, a timed-out soft review, and an answered one whose steering was applied. */
+export const FIXTURE_REVIEW_REQUESTS: ReviewRequest[] = [
+  {
+    id: "rr-hard-1", subject: { type: "story", id: "story-ruling-1" }, mode: "hard_gate", reason: "Approve this ruling summary before it is published",
+    ask: "Check the holding and the quoted passages.", raisedBy: "distinctive.ttab.ruling-analysis", raisedAt: "2026-10-23T08:00:00Z", deadline: null,
+    state: "open", answer: null, links: [], history: [{ at: "2026-10-23T08:00:00Z", event: "raised", by: "distinctive.ttab.ruling-analysis", note: "hard_gate" }],
+    appliedIn: null, updatedAt: "2026-10-23T08:00:00Z",
+  },
+  {
+    id: "rr-soft-2", subject: { type: "batch", id: "2026-W43" }, mode: "soft_review", reason: "3 new story ideas to review",
+    ask: "Approve to keep them all, reject to drop the batch, or steer with a note.", raisedBy: "idea-pipeline", raisedAt: "2026-10-23T07:00:00Z",
+    deadline: "2026-10-30T07:00:00Z", state: "open", answer: null,
+    links: [{ type: "proposal", id: "proposal-1", label: "story idea 1" }, { type: "proposal", id: "proposal-2", label: "story idea 2" }, { type: "proposal", id: "proposal-3", label: "story idea 3" }],
+    history: [], appliedIn: null, updatedAt: "2026-10-23T07:00:00Z",
+  },
+  {
+    id: "rr-soft-1", subject: { type: "proposal", id: "proposal-9" }, mode: "soft_review", reason: "A trend story draft is ready",
+    ask: null, raisedBy: "trend-pipeline", raisedAt: "2026-10-22T07:00:00Z", deadline: "2026-10-25T07:00:00Z", state: "open", answer: null,
+    links: [], history: [], appliedIn: null, updatedAt: "2026-10-22T07:00:00Z",
+  },
+  {
+    id: "rr-flag-1", subject: { type: "reference", id: "ref-1" }, mode: "flag", reason: "Two sources disagree about the filing date",
+    ask: null, raisedBy: "reference-intake", raisedAt: "2026-10-22T10:00:00Z", deadline: null, state: "open", answer: null, links: [], history: [],
+    appliedIn: null, updatedAt: "2026-10-22T10:00:00Z",
+  },
+  {
+    id: "rr-late-1", subject: { type: "story", id: "story-old" }, mode: "soft_review", reason: "Check the headline", ask: null, raisedBy: "copy-editor",
+    raisedAt: "2026-10-10T07:00:00Z", deadline: "2026-10-17T07:00:00Z", state: "timed_out", answer: null, links: [],
+    history: [{ at: "2026-10-17T07:00:00Z", event: "timed_out", by: "system", note: "proceeded without review" }], appliedIn: null, updatedAt: "2026-10-17T07:00:00Z",
+  },
+  {
+    id: "rr-done-1", subject: { type: "batch", id: "2026-W42" }, mode: "soft_review", reason: "4 new story ideas to review", ask: null, raisedBy: "idea-pipeline",
+    raisedAt: "2026-10-16T07:00:00Z", deadline: "2026-10-23T07:00:00Z", state: "answered",
+    answer: { decision: "feedback", feedback: "Fewer listicles", steer: "not_this_kind", by: "Ed Itor", at: "2026-10-17T09:00:00Z" },
+    links: [], history: [], appliedIn: { runId: "run-w43", by: "idea-pipeline", at: "2026-10-20T07:00:00Z" }, updatedAt: "2026-10-17T09:00:00Z",
+  },
+  {
+    id: "rr-done-2", subject: { type: "proposal", id: "proposal-4" }, mode: "soft_review", reason: "A concept rename was proposed", ask: null, raisedBy: "concept-bot",
+    raisedAt: "2026-10-18T07:00:00Z", deadline: "2026-10-25T07:00:00Z", state: "answered",
+    answer: { decision: "feedback", feedback: "Keep the old name for sports", steer: "adjust", by: "Ed Itor", at: "2026-10-19T09:00:00Z" },
+    links: [], history: [], appliedIn: null, updatedAt: "2026-10-19T09:00:00Z",
+  },
+];

package/lib/review-requests.ts

@@ -0,0 +1,238 @@
+/**
+ * The Notification Center's model (PPY-1cd261, PPY-ab6a50): review requests, the Cyclotron items that wait for a person,
+ * the auto-decided stream, and the words the page says about each. Pure functions only, so the page and its tests share them.
+ *
+ * Principle (docs/notification-center.md): everything except a hard gate keeps moving if nobody acts. Each entry says in words
+ * what happens next without the reader, and only a hard gate says "Waiting for you".
+ */
+import type { ReferenceRecord } from "./category-repository";
+import { getNewsroomNavHref } from "./newsroom-nav";
+import { referenceDisplayTitle, referenceLineageId } from "./newsroom-references";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+
+export type ReviewMode = "flag" | "soft_review" | "hard_gate";
+export type ReviewState = "open" | "answered" | "timed_out" | "withdrawn";
+export type ReviewDecision = "approve" | "reject" | "feedback";
+export type ReviewSteer = "adjust" | "not_this_kind";
+
+export type ReviewAnswer = { decision: ReviewDecision; feedback: string | null; steer: ReviewSteer | null; by: string; at: string };
+export type ReviewHistoryEntry = { at: string; event: string; by?: string; note?: string };
+export type ReviewLink = { label?: string; url?: string; type?: string; id?: string };
+
+export type ReviewRequest = {
+  id: string;
+  subject: { type: string; id: string };
+  mode: ReviewMode;
+  reason: string;
+  ask: string | null;
+  raisedBy: string;
+  raisedAt: string;
+  deadline: string | null;
+  state: ReviewState;
+  answer: ReviewAnswer | null;
+  links: ReviewLink[];
+  history: ReviewHistoryEntry[];
+  appliedIn: { runId: string; by: string; at: string; note?: string | null } | null;
+  updatedAt: string;
+};
+
+export const PROCEEDED_WITHOUT_REVIEW = "proceeded without review";
+const MAX_HISTORY = 50;
+
+function parseJson<T>(value: unknown, fallback: T): T {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return fallback;
+    }
+  }
+  return value === null || value === undefined ? fallback : (value as T);
+}
+
+/** A row from the API (JSON fields arrive as strings) as a request. */
+export function normalizeReviewRow(row: Record<string, unknown>): ReviewRequest {
+  return {
+    id: String(row.id),
+    subject: parseJson(row.subject, { type: "unknown", id: "" }),
+    mode: row.mode as ReviewMode,
+    reason: String(row.reason ?? ""),
+    ask: typeof row.ask === "string" ? row.ask : null,
+    raisedBy: String(row.raisedBy ?? ""),
+    raisedAt: String(row.raisedAt ?? ""),
+    deadline: typeof row.deadline === "string" ? row.deadline : null,
+    state: row.state as ReviewState,
+    answer: parseJson<ReviewAnswer | null>(row.answer, null),
+    links: parseJson<ReviewLink[]>(row.links, []),
+    history: parseJson<ReviewHistoryEntry[]>(row.history, []),
+    appliedIn: parseJson(row.appliedIn, null),
+    updatedAt: String(row.updatedAt ?? row.raisedAt ?? ""),
+  };
+}
+
+// --- the deadline (checked on read) ---------------------------------------------------------------------
+
+export function isDue(request: ReviewRequest, now: Date): boolean {
+  return request.mode === "soft_review" && request.state === "open" && request.deadline !== null && new Date(request.deadline).getTime() <= now.getTime();
+}
+
+/** The update that marks a due soft review as timed out, "proceeded without review". Applied with the condition state = open. */
+export function timeoutUpdate(request: ReviewRequest, now: Date): Record<string, unknown> {
+  const at = now.toISOString();
+  const history = [...request.history, { at, event: "timed_out", by: "system", note: PROCEEDED_WITHOUT_REVIEW }].slice(-MAX_HISTORY);
+  return { id: request.id, state: "timed_out", updatedAt: at, history: JSON.stringify(history) };
+}
+
+export type AnswerInput = { decision: ReviewDecision; feedback?: string | null; steer?: ReviewSteer | null };
+
+/** The update for an answer, or an Error saying why it is refused. Applied with the condition state = open. */
+export function answerUpdate(request: ReviewRequest, input: AnswerInput, by: string, now: Date): Record<string, unknown> {
+  if (request.state !== "open") throw new Error(`This request is ${request.state.replace("_", " ")}${request.state === "timed_out" ? ` (${PROCEEDED_WITHOUT_REVIEW})` : ""} and can no longer be answered.`);
+  const feedback = input.feedback?.trim() || null;
+  const steer = input.steer ?? null;
+  if (input.decision === "feedback" && !feedback && !steer) throw new Error("Write a note, or choose \"Not this kind of thing\".");
+  const at = now.toISOString();
+  const answer: ReviewAnswer = { decision: input.decision, feedback, steer, by, at };
+  const history = [...request.history, { at, event: "answered", by, note: input.decision }].slice(-MAX_HISTORY);
+  return { id: request.id, state: "answered", answer: JSON.stringify(answer), updatedAt: at, history: JSON.stringify(history) };
+}
+
+// --- words ------------------------------------------------------------------------------------------------
+
+export function formatWhen(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "";
+  return `${date.toISOString().slice(0, 10)} ${date.toISOString().slice(11, 16)} UTC`;
+}
+
+export function modeLabel(mode: ReviewMode): string {
+  return mode === "hard_gate" ? "Hard gate" : mode === "soft_review" ? "Soft review" : "Flag";
+}
+
+/** A mark and the words, never colour alone. */
+export function modeMark(mode: ReviewMode): string {
+  return mode === "hard_gate" ? "■" : mode === "soft_review" ? "◐" : "⚑";
+}
+
+/** What happens next without the reader. Only a hard gate says "Waiting for you". */
+export function nextText(request: ReviewRequest): string {
+  if (request.state === "open") {
+    if (request.mode === "hard_gate") return "Waiting for you. Nothing continues until you approve or reject.";
+    if (request.mode === "soft_review") return `Proceeds automatically on ${formatWhen(request.deadline)} unless you steer it.`;
+    return "Nothing is waiting on this. It stays here until you acknowledge it.";
+  }
+  if (request.state === "timed_out") return `Proceeded without review on ${formatWhen(request.updatedAt)}.`;
+  if (request.state === "withdrawn") return "Withdrawn by the step that raised it.";
+  const answer = request.answer;
+  return answer ? `${answerWords(answer)} by ${answer.by} on ${formatWhen(answer.at)}.` : "Answered.";
+}
+
+export function answerWords(answer: ReviewAnswer): string {
+  if (answer.steer === "not_this_kind") return "Steered: not this kind of thing";
+  if (answer.decision === "approve") return "Approved";
+  if (answer.decision === "reject") return "Rejected";
+  return "Steered with a note";
+}
+
+/** "You steered X, applied in run Y": what became of a person's input. */
+export function steeringText(request: ReviewRequest): string | null {
+  const answer = request.answer;
+  if (request.state !== "answered" || !answer || !(answer.feedback || answer.steer || answer.decision === "reject")) return null;
+  const said = answer.feedback ? `"${answer.feedback}"` : answerWords(answer).toLowerCase();
+  if (request.appliedIn) return `You steered ${said}. Applied in run ${request.appliedIn.runId} on ${formatWhen(request.appliedIn.at)}.`;
+  return `You steered ${said}. ${request.raisedBy} has not used it yet; it will on its next run.`;
+}
+
+export function subjectHref(subject: { type: string; id: string }, demo = false): string | null {
+  const id = encodeURIComponent(subject.id);
+  if (subject.type === "story") return getNewsroomNavHref(`/newsroom/articles/${id}`, demo);
+  if (subject.type === "reference" || subject.type === "cyclotron_decision") return getNewsroomNavHref(`/newsroom/references/${id}`, demo);
+  if (subject.type === "proposal") return getNewsroomNavHref(`/newsroom/topics?proposal=${id}`, demo);
+  if (subject.type === "automation_run") return getNewsroomNavHref("/newsroom/administration/automations", demo);
+  return null;
+}
+
+// --- Cyclotron items ---------------------------------------------------------------------------------------
+
+export type CyclotronEntry = {
+  lineageId: string;
+  title: string;
+  label: string;
+  confidence: number | null;
+  decidedAt: string | null;
+  reviewDetail: string | null;
+  reviewedByPerson: boolean;
+  href: string;
+};
+
+function cyclotronEntry(reference: ReferenceRecord, decision: RelevanceDecisionView, reviewed: ReadonlySet<string>, demo: boolean): CyclotronEntry {
+  const lineageId = referenceLineageId(reference);
+  return {
+    lineageId, title: referenceDisplayTitle(reference), label: decision.label, confidence: decision.confidence,
+    decidedAt: decision.decidedAt, reviewDetail: decision.reviewDetail, reviewedByPerson: reviewed.has(lineageId),
+    href: getNewsroomNavHref(`/newsroom/references/${encodeURIComponent(lineageId)}`, demo),
+  };
+}
+
+/** Items the Cyclotron routed to a person (the References tab's own rule: review recommended and still pending). Least confident first. */
+export function cyclotronHeldForReview(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView>, demo = false): CyclotronEntry[] {
+  const entries: CyclotronEntry[] = [];
+  for (const reference of references) {
+    const decision = decisions.get(referenceLineageId(reference));
+    if (decision?.reviewRecommended && normalizeReferenceCurationStatus(reference.curationStatus) === "pending") {
+      entries.push(cyclotronEntry(reference, decision, new Set(), demo));
+    }
+  }
+  return entries.sort((a, b) => (a.confidence ?? 1) - (b.confidence ?? 1));
+}
+
+/** Recent classifications the Cyclotron made on its own confidence. Read only here; correcting happens on the reference. Newest first. */
+export function cyclotronAutoDecided(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView>, reviewed: ReadonlySet<string>, demo = false, limit = 20): CyclotronEntry[] {
+  const entries: CyclotronEntry[] = [];
+  for (const reference of references) {
+    const decision = decisions.get(referenceLineageId(reference));
+    if (decision && !decision.reviewRecommended) entries.push(cyclotronEntry(reference, decision, reviewed, demo));
+  }
+  return entries.sort((a, b) => (b.decidedAt ?? "").localeCompare(a.decidedAt ?? "")).slice(0, limit);
+}
+
+// --- the page's shape -------------------------------------------------------------------------------------------
+
+export type NotificationSections = {
+  hardGates: ReviewRequest[];
+  softReviews: ReviewRequest[];
+  flags: ReviewRequest[];
+  /** Answered, timed out or withdrawn, newest first: what people said and what became of it. */
+  decided: ReviewRequest[];
+};
+
+export function sectionReviews(requests: ReviewRequest[]): NotificationSections {
+  const open = requests.filter((request) => request.state === "open");
+  const byRaised = (a: ReviewRequest, b: ReviewRequest) => a.raisedAt.localeCompare(b.raisedAt);
+  return {
+    hardGates: open.filter((request) => request.mode === "hard_gate").sort(byRaised),
+    softReviews: open.filter((request) => request.mode === "soft_review").sort((a, b) => (a.deadline ?? "").localeCompare(b.deadline ?? "")),
+    flags: open.filter((request) => request.mode === "flag").sort((a, b) => b.raisedAt.localeCompare(a.raisedAt)),
+    decided: requests.filter((request) => request.state !== "open").sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)),
+  };
+}
+
+export type NotificationSummary = { waiting: number; proceedingSoon: number; decidedBySystem: number; unread: number };
+
+/**
+ * "N waiting for you · N proceeding soon · N recently decided by the system".
+ * Waiting = hard gates plus Cyclotron items held for review (both stay put until a person acts). Proceeding soon = open soft reviews.
+ */
+export function summarize(sections: NotificationSections, held: CyclotronEntry[], autoDecided: CyclotronEntry[], unread: number): NotificationSummary {
+  return { waiting: sections.hardGates.length + held.length, proceedingSoon: sections.softReviews.length, decidedBySystem: autoDecided.length, unread };
+}
+
+export function summaryText(summary: NotificationSummary): string {
+  return `${summary.waiting} waiting for you · ${summary.proceedingSoon} proceeding soon · ${summary.decidedBySystem} recently decided by the system`;
+}
+
+export function isUnread(request: ReviewRequest, readIds: ReadonlySet<string>): boolean {
+  return !readIds.has(request.id);
+}

package/lib/semantic-graph.ts

@@ -57,6 +57,7 @@ export type SemanticPredicateId =
   | "related_to"
   | "broader_than"
   | "narrower_than"
+  | "member_of"
   | "supports"
   | "contradicts";
 
@@ -96,6 +97,7 @@ export const SEMANTIC_PREDICATES: SemanticPredicateDefinition[] = [
   { id: "related_to", label: "related to", group: "generic", inverseLabel: "related from" },
   { id: "broader_than", label: "broader than", group: "ontology", inverseLabel: "narrower concept" },
   { id: "narrower_than", label: "narrower than", group: "ontology", inverseLabel: "broader concept" },
+  { id: "member_of", label: "member of", group: "ontology", inverseLabel: "members" },
   { id: "supports", label: "supports", group: "evidence", inverseLabel: "supported by" },
   { id: "contradicts", label: "contradicts", group: "evidence", inverseLabel: "contradicted by" },
 ];

package/lib/site-brand-tenant.ts

@@ -9,14 +9,19 @@ export function resolveBrandConfigPath(relativePath: string): string {
   return path.isAbsolute(relativePath) ? relativePath : path.join(process.cwd(), relativePath);
 }
 
-export function getBrandSteeringConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string {
-  return resolveBrandConfigPath(brand.steeringConfigPath);
+/** Optional repo files a brand may still name; undefined means the site keeps that configuration as backend data and nothing is looked up. */
+function optionalBrandConfigPath(relativePath: string | undefined): string | undefined {
+  return relativePath ? resolveBrandConfigPath(relativePath) : undefined;
 }
 
-export function getBrandNewsroomSectionsConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string {
-  return resolveBrandConfigPath(brand.newsroomSectionsConfigPath);
+export function getBrandSteeringConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string | undefined {
+  return optionalBrandConfigPath(brand.steeringConfigPath);
 }
 
-export function getBrandAnalysisProfilesPath(brand: SiteBrand = resolveActiveSiteBrand()): string {
-  return resolveBrandConfigPath(brand.analysisProfilesPath);
+export function getBrandNewsroomSectionsConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string | undefined {
+  return optionalBrandConfigPath(brand.newsroomSectionsConfigPath);
+}
+
+export function getBrandAnalysisProfilesPath(brand: SiteBrand = resolveActiveSiteBrand()): string | undefined {
+  return optionalBrandConfigPath(brand.analysisProfilesPath);
 }

package/lib/site-brand.ts

@@ -142,9 +142,12 @@ export type SiteBrand = {
   readerBasePath?: string;
   opsChrome: OpsChrome;
   corpusKey: string;
-  steeringConfigPath: string;
-  newsroomSectionsConfigPath: string;
-  analysisProfilesPath: string;
+  /** Optional repo file for topic steering. Editorial and steering configuration is backend data; a data-driven site sets none and nothing is looked up. */
+  steeringConfigPath?: string;
+  /** Optional repo file for the local-preview demo sections only. Sections live in the backend. */
+  newsroomSectionsConfigPath?: string;
+  /** Optional repo file listing analysis profiles. */
+  analysisProfilesPath?: string;
   publicationName: string;
   components?: SiteBrandComponents;
   /**

package/lib/site-origin.ts

@@ -0,0 +1,67 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { getSiteEnv } from "./site-env";
+
+type EnvironmentVariables = Record<string, string | undefined>;
+
+export const SITE_ORIGIN_ENV = "PAPYRUS_SITE_ORIGIN";
+
+/**
+ * The site's public origin cannot be read from the request on Amplify SSR (WEB_COMPUTE):
+ * there `request.nextUrl.origin` is the compute adapter's internal https://localhost:3000.
+ * It also must never be derived from Host or X-Forwarded-* headers, which a client can set.
+ * The one trusted source is PAPYRUS_SITE_ORIGIN, set by the app shell from the site's host.
+ */
+export class SiteOriginNotConfiguredError extends Error {
+  readonly status = 503;
+  readonly code = "site_origin_not_configured";
+}
+
+export function siteOriginNotConfiguredResponse(error: SiteOriginNotConfiguredError): NextResponse {
+  return NextResponse.json({ error: error.code, message: error.message }, { status: error.status, headers: { "cache-control": "no-store" } });
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+
+function configuredOrigin(value: string): string {
+  const invalid = () => new SiteOriginNotConfiguredError(`${SITE_ORIGIN_ENV} must be an https origin such as https://example.com with no path.`);
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw invalid();
+  }
+  if (parsed.protocol !== "https:" || parsed.origin !== value) throw invalid();
+  return parsed.origin;
+}
+
+function siteEnvOrNull(environment: EnvironmentVariables): string | null {
+  try {
+    return getSiteEnv(environment);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The site's public origin, from trusted configuration.
+ * - PAPYRUS_SITE_ORIGIN set: it must be an https origin with no path; it is used as is.
+ * - Unset: `request.nextUrl.origin` only when it is loopback, SITE_ENV resolves to development
+ *   and NODE_ENV is not production (a local `next dev` server). Anything else, production and staging included, throws
+ *   SiteOriginNotConfiguredError so routes answer 503 instead of redirecting to localhost.
+ */
+export function publicSiteOrigin(request: Pick<NextRequest, "nextUrl">, environment: EnvironmentVariables = process.env): string {
+  const configured = (environment[SITE_ORIGIN_ENV] ?? "").trim();
+  if (configured) return configuredOrigin(configured);
+  const { hostname, origin } = request.nextUrl;
+  // SITE_ENV defaults to development when a runtime never received it, so NODE_ENV=production also closes the fallback.
+  const developing = siteEnvOrNull(environment) === "development" && environment.NODE_ENV !== "production";
+  if (isLoopbackHostname(hostname) && developing) return origin;
+  throw new SiteOriginNotConfiguredError(`${SITE_ORIGIN_ENV} is not set; this site cannot tell its public origin.`);
+}
+
+/** An absolute URL on the site's public origin, for redirects. Fails closed like publicSiteOrigin. */
+export function publicSiteUrl(path: string, request: Pick<NextRequest, "nextUrl">, environment: EnvironmentVariables = process.env): URL {
+  return new URL(path, publicSiteOrigin(request, environment));
+}