@anthusai/papyrus 1.0.0-next.32 → 1.0.0-next.34

package/components/reference-cyclotron-status.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { useState } from "react";
+import { CyclotronStatusView } from "cyclotron/components/cyclotron-status";
+import type { CyclotronStatus } from "cyclotron/cyclotron-status";
+
+const RATE_CHOICES = [1, 0.5, 0.25, 0.1, 0];
+const DAY_CHOICES = [1, 7, 14, 30];
+
+export type ReviewRateChoice = { rate: number; days: number } | { clear: true };
+
+/**
+ * The relevance cyclotron's status above the References list: a strip, the
+ * detail card on demand, and, for editors who may change it, a form that asks
+ * the next sweep for a manual review rate.
+ */
+export function ReferenceCyclotronStatus({
+  onRequestRate,
+  status,
+  staleAfterHours = 24,
+  now = new Date(),
+}: {
+  onRequestRate?: (choice: ReviewRateChoice) => Promise<void> | void;
+  status: CyclotronStatus;
+  staleAfterHours?: number;
+  now?: Date;
+}) {
+  const [open, setOpen] = useState(false);
+  const [rate, setRate] = useState(0.5);
+  const [days, setDays] = useState(7);
+  const [message, setMessage] = useState<string | null>(null);
+  const ageHours = Math.max(0, (now.getTime() - Date.parse(status.asOf)) / 3_600_000);
+  const stale = Number.isFinite(ageHours) && ageHours > staleAfterHours;
+  const override = status.reviewRate.override;
+
+  async function submit(choice: ReviewRateChoice) {
+    if (!onRequestRate) return;
+    setMessage("Sending…");
+    try {
+      await onRequestRate(choice);
+      setMessage("The next sweep applies it and the status will show who set it.");
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  return (
+    <section aria-label="Relevance cyclotron" className="space-y-2" data-reference-cyclotron-status>
+      <CyclotronStatusView status={status} />
+      {stale ? (
+        <p className="text-xs text-muted-foreground" data-reference-cyclotron-status-stale>
+          <span aria-hidden="true">⚠ </span>
+          Snapshot from {Math.round(ageHours)} hours ago; the next sweep refreshes it.
+        </p>
+      ) : null}
+      <button
+        aria-expanded={open}
+        className="text-xs text-muted-foreground underline underline-offset-4"
+        onClick={() => setOpen((value) => !value)}
+        type="button"
+      >
+        {open ? "Hide what the cyclotron is doing" : "What the cyclotron is doing"}
+      </button>
+      {open ? (
+        <div className="space-y-3">
+          <CyclotronStatusView classifierName="Relevant to this publication" status={status} variant="card" />
+          {onRequestRate ? (
+            <form
+              aria-label="Manual review rate"
+              className="flex flex-wrap items-end gap-3 text-sm"
+              data-reference-review-rate-form
+              onSubmit={(event) => {
+                event.preventDefault();
+                void submit({ rate, days });
+              }}
+            >
+              <label className="flex flex-col gap-1">
+                <span className="text-xs text-muted-foreground">Review rate for confident decisions</span>
+                <select aria-label="Manual review rate" onChange={(event) => setRate(Number(event.target.value))} value={rate}>
+                  {RATE_CHOICES.map((choice) => (
+                    <option key={choice} value={choice}>{Math.round(choice * 100)}%</option>
+                  ))}
+                </select>
+              </label>
+              <label className="flex flex-col gap-1">
+                <span className="text-xs text-muted-foreground">For</span>
+                <select aria-label="How long the manual rate lasts" onChange={(event) => setDays(Number(event.target.value))} value={days}>
+                  {DAY_CHOICES.map((choice) => (
+                    <option key={choice} value={choice}>{choice} day{choice === 1 ? "" : "s"}</option>
+                  ))}
+                </select>
+              </label>
+              <button className="cyclotron-review-secondary" type="submit">Set manual rate</button>
+              {override ? (
+                <button className="cyclotron-review-secondary" onClick={() => void submit({ clear: true })} type="button">
+                  Clear manual rate
+                </button>
+              ) : null}
+              <p className="basis-full text-xs text-muted-foreground">
+                Low-confidence decisions and the random audit share are always reviewed.
+              </p>
+              {message ? <p className="basis-full text-xs" role="status">{message}</p> : null}
+            </form>
+          ) : null}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/components/reference-relevance-review.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { useState } from "react";
+import { ReviewControl, type ReviewReason } from "cyclotron/components/review-control";
+import { isScopeTrainingNegativeReason, REFERENCE_REJECTION_REASON_CODES } from "../lib/reference-policy";
+import {
+  curationForRelevanceReview,
+  type RelevanceCuration,
+  type RelevanceDecisionView,
+} from "../lib/relevance-decisions";
+
+/**
+ * Papyrus's existing rejection reasons, unchanged. Reasons that are not about
+ * relevance (a duplicate, an unavailable source) close the review without
+ * teaching the cyclotron.
+ */
+export const RELEVANCE_REVIEW_REASONS: ReviewReason[] = REFERENCE_REJECTION_REASON_CODES.map((code) => ({
+  code,
+  text: code.charAt(0).toUpperCase() + code.slice(1).replaceAll("_", " "),
+  ...(isScopeTrainingNegativeReason(code) ? {} : { noLabel: true }),
+}));
+
+export function ReferenceRelevanceReview({
+  disabled,
+  decision,
+  onCurate,
+  referenceLineageId,
+}: {
+  disabled?: boolean;
+  decision: RelevanceDecisionView;
+  onCurate: (curation: RelevanceCuration) => void;
+  referenceLineageId: string;
+}) {
+  const [shareable, setShareable] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const classes = decision.classes.length ? decision.classes : [decision.label];
+  return (
+    <section aria-label="Relevance review" className="space-y-2" data-reference-relevance-review={referenceLineageId}>
+      <ReviewControl
+        decision={{
+          decisionId: decision.decisionId,
+          label: decision.label,
+          confidence: decision.confidence,
+          classes,
+          version: decision.version ?? undefined,
+        }}
+        disabled={disabled}
+        itemId={referenceLineageId}
+        mode={decision.reviewControl === "thumbs" && classes.length === 2 ? "thumbs" : "labels"}
+        onReview={(review) => {
+          try {
+            setError(null);
+            onCurate(curationForRelevanceReview(decision, { ...review, shareable }));
+          } catch (failure) {
+            setError(failure instanceof Error ? failure.message : String(failure));
+          }
+        }}
+        positiveLabel={decision.positiveLabel ?? undefined}
+        question={decision.question ?? undefined}
+        reasons={RELEVANCE_REVIEW_REASONS}
+        reviewReason={decision.reviewRecommended ? decision.reviewDetail ?? undefined : undefined}
+      />
+      <label className="flex items-center gap-2 text-xs text-muted-foreground">
+        <input
+          checked={shareable}
+          disabled={disabled}
+          onChange={(event) => setShareable(event.target.checked)}
+          type="checkbox"
+        />
+        My explanation may be quoted publicly (for the Cyclotron example page)
+      </label>
+      {error ? <p className="text-xs text-destructive" role="alert">{error}</p> : null}
+    </section>
+  );
+}

package/components/topic-steering-workspace.tsx

@@ -53,6 +53,8 @@ import {
   type ForumThreadWithMessages,
   type KnowledgeQueryResponse,
   type NewsroomRecordPage,
+  loadCyclotronStatus,
+  requestCyclotronReviewRate,
 } from "./news-desk-taxonomy-client";
 import { listConsoleThreads } from "../lib/console-chat-client";
 import {
@@ -151,9 +153,13 @@ import {
   type SemanticObjectSummary,
 } from "../lib/semantic-graph";
 import {
+  normalizeReferenceRejectionReasonCode,
   REFERENCE_REJECTION_REASON_CODES,
   referenceCurationStatusForAction,
 } from "../lib/reference-policy";
+import { currentRelevanceDecisions } from "../lib/relevance-decisions";
+import { buildReviewRateRequest, DEMO_CYCLOTRON_STATUS } from "../lib/relevance-status";
+import type { CyclotronStatus } from "cyclotron/cyclotron-status";
 import {
   referenceDisplaySummary,
   referenceMetadataField,
@@ -776,6 +782,24 @@ function NewsDeskDashboard({
   const [referenceAttachments, setReferenceAttachments] = useState(dashboard.referenceAttachments);
   const [messages, setMessages] = useState(dashboard.messages);
   const [semanticRelations, setSemanticRelations] = useState(dashboard.semanticRelations);
+  const relevanceDecisions = useMemo(() => currentRelevanceDecisions(semanticRelations), [semanticRelations]);
+  const relevanceCyclotronId = useMemo(
+    () => [...relevanceDecisions.values()].find((decision) => decision.cyclotronId)?.cyclotronId ?? null,
+    [relevanceDecisions],
+  );
+  const [cyclotronStatus, setCyclotronStatus] = useState<CyclotronStatus | null>(null);
+  useEffect(() => {
+    if (!relevanceCyclotronId) return;
+    if (dashboard.isDemo) {
+      setCyclotronStatus(DEMO_CYCLOTRON_STATUS);
+      return;
+    }
+    let cancelled = false;
+    loadCyclotronStatus(relevanceCyclotronId)
+      .then((status) => { if (!cancelled) setCyclotronStatus(status); })
+      .catch(() => { if (!cancelled) setCyclotronStatus(null); });
+    return () => { cancelled = true; };
+  }, [dashboard.isDemo, relevanceCyclotronId]);
   const [semanticNodes, setSemanticNodes] = useState(dashboard.semanticNodes);
   const [assignments, setAssignments] = useState(dashboard.assignments);
   const [assignmentEvents, setAssignmentEvents] = useState(dashboard.assignmentEvents);
@@ -1507,7 +1531,13 @@ function NewsDeskDashboard({
     });
   }
 
-  function runReferenceCurationAction(reference: ReferenceRecord, action: ReferenceCurationAction, note?: string, reasonCode?: ReferenceRejectionReasonCode | null) {
+  function runReferenceCurationAction(
+    reference: ReferenceRecord,
+    action: ReferenceCurationAction,
+    note?: string,
+    reasonCode?: ReferenceRejectionReasonCode | null,
+    relevance?: { decisionRelationId: string; shareable: boolean },
+  ) {
     const nextStatus = referenceCurationStatusForAction(action);
     setActionState({ id: reference.id, message: `${action} pending`, tone: "pending" });
     if (dashboard.isDemo) {
@@ -1535,6 +1565,7 @@ function NewsDeskDashboard({
           action,
           curationStatus: nextStatus,
           reasonCode: action === "reject" ? reasonCode ?? null : null,
+          ...(relevance ? { decisionRelationId: relevance.decisionRelationId, shareable: relevance.shareable } : {}),
         },
       }, ...current]);
       setSemanticRelations((current) => [{
@@ -1575,6 +1606,8 @@ function NewsDeskDashboard({
               actorLabel: authState.label,
               note: note?.trim() || undefined,
               reasonCode: action === "reject" ? reasonCode ?? undefined : undefined,
+              decisionRelationId: relevance?.decisionRelationId,
+              shareable: relevance ? relevance.shareable : undefined,
             },
             { authMode: USER_POOL_AUTH_MODE },
           );
@@ -3153,6 +3186,20 @@ function NewsDeskDashboard({
             demo={Boolean(dashboard.isDemo)}
             disabled={controlsDisabled}
             initialReferenceLineageId={initialSelection.reference ?? pathnameReferenceLineageId}
+            cyclotronStatus={cyclotronStatus}
+            decisions={relevanceDecisions}
+            onRequestReviewRate={relevanceCyclotronId ? async (choice) => {
+              const request = buildReviewRateRequest(choice, authState.label);
+              if (dashboard.isDemo) return;
+              await requestCyclotronReviewRate(relevanceCyclotronId, request);
+            } : undefined}
+            onRelevanceReview={(reference, curation) => runReferenceCurationAction(
+              reference,
+              curation.action,
+              curation.note ?? undefined,
+              normalizeReferenceRejectionReasonCode(curation.reasonCode),
+              { decisionRelationId: curation.decisionRelationId, shareable: curation.shareable },
+            )}
             onReview={(reference, action) => runReferenceCurationAction(reference, action)}
             referenceAttachments={referenceAttachments}
             references={references}

package/infra/site-config.js

@@ -13,6 +13,14 @@ const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
 const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER"];
+function originOfRedirectUrl(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return value;
+    }
+}
 export function resolveRevalidateSecretParameterName(config) {
     return `/papyrus/${config.siteId}/revalidate-secret`;
 }
@@ -259,14 +267,15 @@ export function parseSiteConfig(raw) {
         fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", "is required");
     const redirectUrls = redirectValue.split(",").map((url) => url.trim());
     const stagingDomainName = resolveStagingDomainName(config);
+    const listedOrigins = new Set(redirectUrls.map(originOfRedirectUrl));
     const requiredOrigins = [
-        ...(resolveCmsHostName(config) ? [`https://${resolveCmsHostName(config)}/`] : []),
-        ...(stagingDomainName ? [`https://${stagingDomainName}/`] : []),
-        LOCAL_DEVELOPMENT_ORIGIN,
+        ...(resolveCmsHostName(config) ? [`https://${resolveCmsHostName(config)}`] : []),
+        ...(stagingDomainName ? [`https://${stagingDomainName}`] : []),
+        originOfRedirectUrl(LOCAL_DEVELOPMENT_ORIGIN),
     ];
     for (const origin of requiredOrigins) {
-        if (!redirectUrls.includes(origin)) {
-            fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}`);
+        if (!listedOrigins.has(origin)) {
+            fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}/ (or just the origin: the backend also registers its newsroom path)`);
         }
     }
     return config;

package/infra/site-config.ts

@@ -57,6 +57,14 @@ const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
 const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER"];
+function originOfRedirectUrl(value: string): string {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return value;
+  }
+}
+
 export function resolveRevalidateSecretParameterName(config: Pick<AmplifyAppShellSiteConfig, "siteId">): string {
   return `/papyrus/${config.siteId}/revalidate-secret`;
 }
@@ -321,14 +329,15 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   if (redirectValue === undefined) fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", "is required");
   const redirectUrls = redirectValue.split(",").map((url) => url.trim());
   const stagingDomainName = resolveStagingDomainName(config);
+  const listedOrigins = new Set(redirectUrls.map(originOfRedirectUrl));
   const requiredOrigins = [
-    ...(resolveCmsHostName(config) ? [`https://${resolveCmsHostName(config)}/`] : []),
-    ...(stagingDomainName ? [`https://${stagingDomainName}/`] : []),
-    LOCAL_DEVELOPMENT_ORIGIN,
+    ...(resolveCmsHostName(config) ? [`https://${resolveCmsHostName(config)}`] : []),
+    ...(stagingDomainName ? [`https://${stagingDomainName}`] : []),
+    originOfRedirectUrl(LOCAL_DEVELOPMENT_ORIGIN),
   ];
   for (const origin of requiredOrigins) {
-    if (!redirectUrls.includes(origin)) {
-      fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}`);
+    if (!listedOrigins.has(origin)) {
+      fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}/ (or just the origin: the backend also registers its newsroom path)`);
     }
   }
 

package/lib/category-repository.ts

@@ -1660,6 +1660,47 @@ export function createDemoCategorySteeringDashboard(
       },
     ],
     semanticRelations: [
+      {
+        // The relevance cyclotron's decision about the pending demo reference.
+        id: "semantic-relation-demo-relevance-history-002",
+        relationState: "current",
+        predicate: "relevance_decision_is",
+        relationTypeKey: "relevance_decision_is",
+        relationDomain: "workflow",
+        subjectKind: "reference",
+        subjectId: referenceHistoryTwoId,
+        subjectLineageId: referenceHistoryTwoLineageId,
+        objectKind: "semanticNode",
+        objectId: "semantic-node-relevance-include-v1",
+        objectLineageId: "semantic-node-relevance-include",
+        subjectStateKey: `reference#${referenceHistoryTwoLineageId}#current`,
+        objectStateKey: "semanticNode#semantic-node-relevance-include#current",
+        objectSubjectStateKey: "semanticNode#semantic-node-relevance-include#current#reference",
+        predicateObjectStateKey: "relevance_decision_is#semanticNode#semantic-node-relevance-include#current",
+        subjectVersionKey: `reference#${referenceHistoryTwoId}`,
+        objectVersionKey: "semanticNode#semantic-node-relevance-include-v1",
+        score: 0.82,
+        confidence: 0.82,
+        rank: 1,
+        classifierId: "papyrus-relevance/relevant",
+        modelVersion: "1",
+        reviewRecommended: true,
+        importRunId: "knowledge-import-demo-projection",
+        importedAt,
+        metadata: JSON.stringify({
+          decisionId: "decision-demo-history-002",
+          cyclotronId: "papyrus-relevance",
+          label: "include",
+          probabilities: { include: 0.82, exclude: 0.18 },
+          labels: ["include", "exclude"],
+          positiveLabel: "include",
+          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.",
+          version: 1,
+        }),
+      },
       {
         id: "semantic-relation-demo-reporting-context-comment",
         relationState: "current",

package/lib/oauth-redirect-priority.ts

@@ -0,0 +1,40 @@
+function originOf(value: string): string {
+  const trimmed = value.replace(/\/+$/, "");
+  try {
+    const parsed = new URL(trimmed);
+    const hostname = parsed.hostname === "127.0.0.1" || parsed.hostname === "::1" ? "localhost" : parsed.hostname;
+    return `${parsed.protocol}//${hostname}${parsed.port ? `:${parsed.port}` : ""}`;
+  } catch {
+    return trimmed;
+  }
+}
+
+function pathOf(value: string): string | null {
+  try {
+    return new URL(value).pathname.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Puts the redirect URLs of the current origin first; among those, the
+ * newsroom return path leads when the site has one, so Amplify (which signs in
+ * with the first entry) returns an editor to the newsroom.
+ */
+export function prioritizeRedirectUrlsForOrigin(
+  urls: readonly string[],
+  currentOrigin: string,
+  publicNewsroomBasePath: string,
+): string[] {
+  const origin = originOf(currentOrigin);
+  const newsroomPath = publicNewsroomBasePath.replace(/\/+$/, "");
+  const head = urls.filter((value) => originOf(value) === origin);
+  if (head.length === 0) return [...urls];
+  const tail = urls.filter((value) => originOf(value) !== origin);
+  const newsroomFirst =
+    newsroomPath === ""
+      ? head
+      : [...head.filter((value) => pathOf(value) === newsroomPath), ...head.filter((value) => pathOf(value) !== newsroomPath)];
+  return [...newsroomFirst, ...tail];
+}

package/lib/reference-policy.ts

@@ -17,6 +17,11 @@ export type ReferenceRejectionReasonCode = typeof REFERENCE_REJECTION_REASON_COD
 const REFERENCE_REJECTION_REASON_CODE_SET = new Set<string>(REFERENCE_REJECTION_REASON_CODES);
 const SCOPE_TRAINING_NEGATIVE_REASON_CODE_SET = new Set<string>(["out_of_scope", "policy_exclusion"]);
 
+/** Rejection reasons that say the source is not relevant (scope-training negatives). */
+export function isScopeTrainingNegativeReason(code: string): boolean {
+  return SCOPE_TRAINING_NEGATIVE_REASON_CODE_SET.has(code);
+}
+
 export function normalizeReferenceCurationStatus(value: unknown, defaultStatus: ReferenceCurationStatus = "pending"): ReferenceCurationStatus {
   const normalized = normalizePolicyToken(value ?? defaultStatus);
   if (normalized === "accepted" || normalized === "accept" || normalized === "ready" || normalized === "trusted") return "accepted";

package/lib/relevance-decisions.ts

@@ -0,0 +1,103 @@
+import type { SemanticRelationRecord } from "./category-repository";
+
+export const RELEVANCE_RELATION = "relevance_decision_is";
+
+/** The relevance cyclotron's current decision about one reference, as the References tab shows it. */
+export type RelevanceDecisionView = {
+  decisionRelationId: string;
+  decisionId: string;
+  label: string;
+  confidence: number | null;
+  version: number | null;
+  /** True when the cyclotron sent this decision to review. */
+  reviewRecommended: boolean;
+  reviewReason: "program" | "audit" | null;
+  reviewDetail: string | null;
+  classes: string[];
+  positiveLabel: string | null;
+  question: string | null;
+  /** Thumbs for a two-class decision with a positive label; per-class buttons otherwise. */
+  reviewControl: "thumbs" | "labels";
+  cyclotronId: string | null;
+};
+
+/** What an editor submits from the review control. */
+export type RelevanceReview = {
+  label: string | null;
+  reasonCode: string | null;
+  explanation: string | null;
+  shareable: boolean;
+};
+
+/** The existing curation action an editor's review becomes. */
+export type RelevanceCuration = {
+  action: "accept" | "reject";
+  reasonCode: string | null;
+  note: string | null;
+  decisionRelationId: string;
+  shareable: boolean;
+};
+
+function parseMetadata(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 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;
+    const metadata = parseMetadata(relation.metadata);
+    const probabilities = parseMetadata(metadata.probabilities);
+    const reason = metadata.reviewReason === "program" || metadata.reviewReason === "audit" ? metadata.reviewReason : null;
+    const version = Number(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,
+      reviewRecommended: Boolean(relation.reviewRecommended),
+      reviewReason: reason,
+      reviewDetail: typeof metadata.reviewDetail === "string" ? metadata.reviewDetail : null,
+      classes: Array.isArray(metadata.labels) && metadata.labels.length
+        ? metadata.labels.map(String)
+        : Object.keys(probabilities),
+      positiveLabel: typeof metadata.positiveLabel === "string" ? metadata.positiveLabel : null,
+      question: typeof metadata.question === "string" ? metadata.question : null,
+      reviewControl: metadata.reviewControl === "thumbs" ? "thumbs" : "labels",
+      cyclotronId: typeof metadata.cyclotronId === "string" ? metadata.cyclotronId : null,
+    });
+  }
+  return decisions;
+}
+
+/**
+ * Map a review to the existing curation mutation. The positive label accepts;
+ * any other label, or a review without a label, rejects with the reason code,
+ * which the existing scope-training rule turns back into a cyclotron label
+ * (out_of_scope and policy_exclusion) or none.
+ */
+export function curationForRelevanceReview(decision: RelevanceDecisionView, review: RelevanceReview): RelevanceCuration {
+  const accepted = review.label !== null && review.label === decision.positiveLabel;
+  if (!accepted && !review.reasonCode) {
+    throw new Error("A review that does not accept the reference needs a reason code.");
+  }
+  return {
+    action: accepted ? "accept" : "reject",
+    reasonCode: accepted ? null : review.reasonCode,
+    note: review.explanation?.trim() || null,
+    decisionRelationId: decision.decisionRelationId,
+    shareable: review.shareable,
+  };
+}

package/lib/relevance-status.ts

@@ -0,0 +1,63 @@
+import type { CyclotronStatus } from "cyclotron/cyclotron-status";
+import { isCyclotronStatus } from "cyclotron/cyclotron-status";
+
+/** The KnowledgeRawPayload the decide-relevance sweep writes the status snapshot to. */
+export function cyclotronStatusPayloadId(cyclotronId: string): string {
+  return `knowledge-raw-payload-cyclotron-status-${safeId(cyclotronId)}`;
+}
+
+/** The KnowledgeRawPayload an editor writes to ask for a manual review rate. */
+export function reviewRateRequestPayloadId(cyclotronId: string): string {
+  return `knowledge-raw-payload-cyclotron-review-rate-request-${safeId(cyclotronId)}`;
+}
+
+/** Mirrors Python's ids.safe_id so both sides name the same record. */
+export function safeId(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 140);
+}
+
+export type ReviewRateRequest =
+  | { rate: number; expiresAt: string; setBy: string; requestedAt: string }
+  | { clear: true; setBy: string; requestedAt: string };
+
+export function buildReviewRateRequest(
+  choice: { rate: number; days: number } | { clear: true },
+  setBy: string,
+  now: Date = new Date(),
+): ReviewRateRequest {
+  const requestedAt = now.toISOString();
+  if ("clear" in choice) return { clear: true, setBy, requestedAt };
+  if (!(choice.rate >= 0 && choice.rate <= 1)) throw new Error("A review rate is between 0% and 100%.");
+  if (!(choice.days >= 1)) throw new Error("A manual rate lasts at least one day.");
+  const expiresAt = new Date(now.getTime() + choice.days * 24 * 60 * 60 * 1000).toISOString();
+  return { rate: choice.rate, expiresAt, setBy, requestedAt };
+}
+
+/** The newest valid snapshot among a payload's attachments. */
+export function latestCyclotronStatus(payloads: Array<{ json: unknown; updatedAt?: string | null }>): CyclotronStatus | null {
+  const valid = payloads
+    .filter((payload) => isCyclotronStatus(payload.json))
+    .sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")));
+  return valid.length ? (valid[0].json as CyclotronStatus) : null;
+}
+
+/** What demo mode shows: an onboarding cyclotron that has made one decision. */
+export const DEMO_CYCLOTRON_STATUS: CyclotronStatus = {
+  schema: "cyclotron-status/v1",
+  cyclotron: { id: "papyrus-relevance", classifier: "relevant", version: 1, refits: 0, fingerprint: "demo" },
+  asOf: "2026-05-16T12:00:00.000Z",
+  alignment: {
+    window: 200, labels: 0, accuracy: null, precision: null, recall: null,
+    positiveLabel: "include", measuredOn: "reviews selected by the cyclotron",
+  },
+  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.",
+    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.",
+    expectedReviewsPerWeek: 1,
+  },
+  lastChange: null,
+  pending: { decisionsAwaitingReview: 1, staleSince: null },
+};

package/lib/semantic-graph.ts

@@ -32,6 +32,7 @@ export type SemanticObjectKind = typeof SEMANTIC_OBJECT_KINDS[number];
 export type SemanticPredicateId =
   | "classified_as"
   | "quality_rating_is"
+  | "relevance_decision_is"
   | "reference_summary_100_tokens"
   | "reference_summary_200_tokens"
   | "reference_summary_500_tokens"
@@ -80,6 +81,7 @@ export const SEMANTIC_PREDICATES: SemanticPredicateDefinition[] = [
   { id: "about", label: "about", group: "commentary", inverseLabel: "commentary" },
   { id: "comment", label: "comments on", group: "commentary", inverseLabel: "commented on by", contextPackTags: ["reference_curation", "editing", "research", "assignment_context"] },
   { id: "ingestion_rationale", label: "ingestion rationale for", group: "commentary", inverseLabel: "ingestion rationale", contextPackTags: ["reference_curation", "editing", "research", "assignment_context"] },
+  { id: "relevance_decision_is", label: "relevance decision is", group: "workflow", inverseLabel: "relevance decision for", contextPackTags: ["reference_curation"] },
   { id: "requests_work_on", label: "requests work on", group: "workflow", inverseLabel: "requested work", contextPackTags: ["assignment_context", "editing"] },
   { id: "uses_evidence", label: "uses evidence", group: "evidence", inverseLabel: "used as evidence by", contextPackTags: ["assignment_context", "research", "reference_graph"] },
   { id: "uses_signal", label: "uses signal", group: "evidence", inverseLabel: "signal for", contextPackTags: ["assignment_context", "research", "reference_graph"] },