@anthusai/papyrus 1.4.0-next.5 → 1.4.0-next.7

package/components/reference-cyclotron-suggestion.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import {
+  curationForSuggestionChoice,
+  type DelegatedCuration,
+  provenanceSummary,
+  suggestionConfidenceWords,
+  type SuggestionChoice,
+} from "../lib/cyclotron-suggestions";
+import type { RelevanceCuration, RelevanceDecisionView } from "../lib/relevance-decisions";
+
+const RULE_BUTTON_CLASS =
+  "border border-foreground px-3 py-1 text-sm font-semibold text-foreground underline-offset-4 hover:underline disabled:cursor-not-allowed disabled:opacity-100 disabled:line-through";
+
+/** UTC and fixed-format so server and browser render the same words. */
+export function formatSuggestionTime(instant: string | null): string {
+  if (!instant) return "time not recorded";
+  const parsed = new Date(instant);
+  if (Number.isNaN(parsed.getTime())) return "time not recorded";
+  return `${parsed.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+
+/** The one-line suggestion in a queue row. Never worded as a decision. */
+export function ReferenceSuggestionRowLine({
+  decision,
+  referenceLineageId,
+}: {
+  decision: RelevanceDecisionView;
+  referenceLineageId: string;
+}) {
+  return (
+    <p className="mt-1 text-xs text-foreground" data-reference-suggestion-row={referenceLineageId}>
+      <span className="font-semibold">Suggestion:</span> {decision.label}, {suggestionConfidenceWords(decision)}
+    </p>
+  );
+}
+
+/**
+ * The detail's Suggestion block. Agree and Overrule go through the ordinary
+ * accept and reject actions; nothing changes until an editor clicks.
+ */
+export function ReferenceSuggestionBlock({
+  decision,
+  disabled,
+  onCurate,
+  referenceLineageId,
+  statusLabel,
+  settled,
+}: {
+  decision: RelevanceDecisionView;
+  disabled?: boolean;
+  onCurate?: (curation: RelevanceCuration) => void;
+  referenceLineageId: string;
+  statusLabel: string;
+  settled: boolean;
+}) {
+  const choose = (choice: SuggestionChoice) => onCurate?.(curationForSuggestionChoice(decision, choice));
+  const suggestsAccept = decision.positiveLabel !== null && decision.label === decision.positiveLabel;
+  return (
+    <section aria-label="Suggestion" className="space-y-2 border-y border-foreground py-3" data-reference-suggestion={referenceLineageId}>
+      <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground">Suggestion</h3>
+      <p className="text-sm text-foreground">
+        The cyclotron suggests <span className="font-semibold">{decision.label}</span> ({suggestionConfidenceWords(decision)}).
+      </p>
+      <p className="text-xs text-foreground" data-reference-suggestion-notice>
+        A suggestion never changes the status until an editor acts. This reference is {statusLabel.toLowerCase()}.
+      </p>
+      {!settled && onCurate ? (
+        <div className="flex flex-wrap gap-2">
+          <button
+            className={RULE_BUTTON_CLASS}
+            data-reference-suggestion-agree
+            disabled={disabled}
+            onClick={() => choose("agree")}
+            type="button"
+          >
+            Agree ({suggestsAccept ? "accept" : "reject"})
+          </button>
+          <button
+            className={RULE_BUTTON_CLASS}
+            data-reference-suggestion-overrule
+            disabled={disabled}
+            onClick={() => choose("overrule")}
+            type="button"
+          >
+            Overrule ({suggestsAccept ? "reject" : "accept"})
+          </button>
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+/** The expandable "How this suggestion was made" block, from the recorded provenance. */
+export function ReferenceSuggestionProvenance({ decision }: { decision: RelevanceDecisionView }) {
+  const summary = provenanceSummary(decision);
+  return (
+    <details className="text-sm text-foreground" data-reference-suggestion-provenance>
+      <summary className="cursor-pointer font-semibold underline-offset-4 hover:underline">How this suggestion was made</summary>
+      {summary ? (
+        <ul className="mt-2 space-y-1">
+          <li>{summary.teachingLabelsSentence}.</li>
+          <li>{summary.primingExamplesSentence}.</li>
+          <li>Doctrine fingerprint {summary.doctrineShortHash ?? "not recorded"}.</li>
+          <li>Model {summary.modelVersion ?? "version not recorded"}.</li>
+          <li>Decided {formatSuggestionTime(summary.decidedAt)}.</li>
+        </ul>
+      ) : (
+        <p className="mt-2">This suggestion was made before the cyclotron recorded how. Only its model version and confidence are known.</p>
+      )}
+    </details>
+  );
+}
+
+/** Shown only when the latest curation of the reference was made by a signed-in person. */
+export function CountsAsTrainingLabelNote({ referenceLineageId }: { referenceLineageId: string }) {
+  return (
+    <p className="border-l-2 border-foreground pl-2 text-xs font-semibold text-foreground" data-reference-training-label={referenceLineageId}>
+      Counts as a training label: an editor made this decision, so the cyclotron learns from it.
+    </p>
+  );
+}
+
+/**
+ * Shown on a record an agent decided for a person under a delegation. The
+ * backend stamps it human, so it counts as that person's training label.
+ */
+export function DelegatedCurationNote({ delegated, referenceLineageId }: { delegated: DelegatedCuration; referenceLineageId: string }) {
+  return (
+    <section aria-label="Delegated decision" className="space-y-1 border-l-2 border-foreground pl-2 text-sm text-foreground" data-reference-delegated-curation={referenceLineageId}>
+      <p className="font-semibold">
+        Decided by {delegated.agent} on behalf of {delegated.person ?? "a person"}
+      </p>
+      {delegated.instruction ? <blockquote className="italic">&ldquo;{delegated.instruction}&rdquo;</blockquote> : null}
+      <p className="text-xs">Delegation {delegated.delegationShortId || "id not recorded"}.</p>
+      <p className="text-xs font-semibold" data-reference-training-label={referenceLineageId}>
+        {delegated.countsAsTrainingLabel
+          ? `Counts as a training label: the record is stamped as ${delegated.person ?? "the person"}'s own decision, so the cyclotron learns from it.`
+          : "Does not count as a training label."}
+      </p>
+    </section>
+  );
+}

package/components/reference-live-agreement.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import {
+  agreementStripState,
+  formatPercentage,
+  dailyCapWords,
+  loopStateWords,
+  type AgreementStripMeasurement,
+  type ShadowAgreement,
+} from "../lib/cyclotron-suggestions";
+import { formatSuggestionTime } from "./reference-cyclotron-suggestion";
+
+function MeasurementFigures({ measurement }: { measurement: AgreementStripMeasurement }) {
+  const figures: Array<[string, string]> = [
+    ["Agreement", formatPercentage(measurement.agreement)],
+    ["Precision", formatPercentage(measurement.precision)],
+    ["Recall", formatPercentage(measurement.recall)],
+    ["Comparisons", String(measurement.comparisons)],
+  ];
+  return (
+    <dl className="flex flex-wrap gap-x-6 gap-y-1">
+      {figures.map(([name, value]) => (
+        <div key={name}>
+          <dt className="text-xs font-semibold uppercase tracking-wide text-foreground">{name}</dt>
+          <dd className="text-base font-semibold text-foreground">{value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/**
+ * Live agreement at the top of References: how often the cyclotron's
+ * suggestions matched what editors then decided. Hidden without a payload.
+ */
+export function ReferenceLiveAgreement({ agreement }: { agreement: ShadowAgreement | null }) {
+  const state = agreementStripState(agreement);
+  if (state.kind === "hidden") return null;
+  return (
+    <section aria-label="Live agreement" className="shrink-0 space-y-2 border-y border-foreground py-3" data-reference-live-agreement={state.kind}>
+      <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground">Live agreement</h3>
+      {state.loop ? (
+        <p className="text-sm text-foreground" data-reference-live-agreement-loop>
+          <span className="font-semibold">{loopStateWords(state.loop)}</span>
+          {" · "}Last sweep {formatSuggestionTime(state.loop.lastSweepAt)}
+          {" · "}{dailyCapWords(state.loop)}
+        </p>
+      ) : null}
+      {state.stopReasonSentence ? (
+        <p className="text-sm font-semibold text-foreground" data-reference-live-agreement-stopped>{state.stopReasonSentence}</p>
+      ) : null}
+      {state.kind === "not_enough" ? (
+        <p className="text-sm text-foreground" data-reference-live-agreement-not-enough>
+          Not enough comparisons yet: {state.measurement.comparisons} of {state.needed} editor decisions have followed a suggestion. Figures appear at {state.needed}.
+        </p>
+      ) : <MeasurementFigures measurement={state.measurement} />}
+      <p className="text-xs text-foreground">
+        Suggestions compared with the decisions editors made afterwards. Computed {formatSuggestionTime(agreement?.computedAt ?? null)}.
+      </p>
+    </section>
+  );
+}

package/components/topic-steering-workspace.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { AdministrationDelegationsPanel } from "./administration-delegations-panel";
 import { WikiConceptsView } from "./wiki-concepts-view";
 import { Hub } from "aws-amplify/utils";
 import { fetchAuthSession } from "aws-amplify/auth";
@@ -54,6 +55,7 @@ import {
   type KnowledgeQueryResponse,
   type NewsroomRecordPage,
   loadCyclotronStatus,
+  loadCyclotronShadowAgreement,
   requestCyclotronPriming,
   loadCyclotronPrimingRequests,
   requestCyclotronReviewRate,
@@ -156,7 +158,10 @@ import {
   REFERENCE_REJECTION_REASON_CODES,
   referenceCurationStatusForAction,
 } from "../lib/reference-policy";
+import { isLocalPreviewEnabled } from "../lib/local-preview";
 import { currentRelevanceDecisions } from "../lib/relevance-decisions";
+import { delegatedCurationsByReference, referencesWithHumanLatestCuration, type ShadowAgreement } from "../lib/cyclotron-suggestions";
+import { createLocalPreviewCyclotronFixtures } from "../lib/local-preview-seed";
 import {
   buildPrimingRequest,
   buildReviewRateRequest,
@@ -238,7 +243,7 @@ type AssignmentAction = "claim" | "release" | "complete" | "cancel" | "reopen" |
 type ReportingPacketReviewDecision = "select" | "merge" | "brief" | "hold" | "kill";
 type AssignmentDeskViewMode = "queue" | "budget";
 type UserRoleAction = "grant" | "revoke";
-type AdministrationPanel = "users" | "policies" | "sections" | "procedures" | "signups";
+type AdministrationPanel = "users" | "policies" | "sections" | "procedures" | "delegations" | "signups";
 export type NewsDeskTab = "overview" | "desks" | "topics" | "concepts" | "references" | "messages" | "assignments" | "administration" | "search";
 type LexicalRuleScope = "publication" | "corpus" | "classifier" | "category";
 type AnalysisReindexMode = "online-update" | "classifier-retrain" | "scoped-topic-rebuild" | "entity-graph-rebuild" | "generated-analysis-rebuild";
@@ -784,7 +789,22 @@ 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 cyclotronPreviewFixtures = useMemo(
+    () => (isLocalPreviewEnabled() ? createLocalPreviewCyclotronFixtures(references) : null),
+    [references],
+  );
+  const relevanceDecisions = useMemo(
+    () => currentRelevanceDecisions(cyclotronPreviewFixtures ? [...semanticRelations, ...cyclotronPreviewFixtures.relations] : semanticRelations),
+    [cyclotronPreviewFixtures, semanticRelations],
+  );
+  const delegatedCurations = useMemo(
+    () => delegatedCurationsByReference(cyclotronPreviewFixtures ? [...messages, ...cyclotronPreviewFixtures.messages] : messages),
+    [cyclotronPreviewFixtures, messages],
+  );
+  const humanCuratedReferenceLineageIds = useMemo(
+    () => referencesWithHumanLatestCuration(cyclotronPreviewFixtures ? [...messages, ...cyclotronPreviewFixtures.messages] : messages),
+    [cyclotronPreviewFixtures, messages],
+  );
   const relevanceCyclotronId = useMemo(
     () => [...relevanceDecisions.values()].find((decision) => decision.cyclotronId)?.cyclotronId ?? null,
     [relevanceDecisions],
@@ -819,6 +839,19 @@ function NewsDeskDashboard({
       .catch(() => { if (!cancelled) setCyclotronStatus(null); });
     return () => { cancelled = true; };
   }, [dashboard.isDemo, relevanceCyclotronId]);
+  const [shadowAgreement, setShadowAgreement] = useState<ShadowAgreement | null>(null);
+  useEffect(() => {
+    if (cyclotronPreviewFixtures) {
+      setShadowAgreement(cyclotronPreviewFixtures.shadowAgreement);
+      return;
+    }
+    if (!relevanceCyclotronId || dashboard.isDemo) return;
+    let cancelled = false;
+    loadCyclotronShadowAgreement(relevanceCyclotronId)
+      .then((loaded) => { if (!cancelled) setShadowAgreement(loaded); })
+      .catch(() => { if (!cancelled) setShadowAgreement(null); });
+    return () => { cancelled = true; };
+  }, [cyclotronPreviewFixtures, dashboard.isDemo, relevanceCyclotronId]);
   const [semanticNodes, setSemanticNodes] = useState(dashboard.semanticNodes);
   const [assignments, setAssignments] = useState(dashboard.assignments);
   const [assignmentEvents, setAssignmentEvents] = useState(dashboard.assignmentEvents);
@@ -3217,6 +3250,9 @@ function NewsDeskDashboard({
               },
             }}
             decisions={relevanceDecisions}
+            humanCuratedReferenceLineageIds={humanCuratedReferenceLineageIds}
+            delegatedCurations={delegatedCurations}
+            shadowAgreement={shadowAgreement}
             onRequestReviewRate={relevanceCyclotronId ? async (choice) => {
               const request = buildReviewRateRequest(choice, authState.label);
               if (dashboard.isDemo) return;
@@ -4463,6 +4499,15 @@ function AdministrationDeskView({
                 <strong>Procedures</strong>
                 <span>Procedure registry and versioned Tactus code</span>
               </Link>
+              <Link
+                href={administrationPanelHref("delegations", isDemo)}
+                data-news-desk-admin-nav="delegations"
+                data-active={administrationPanel === "delegations" || undefined}
+                onClick={() => onPanelChange("delegations")}
+              >
+                <strong>Agent delegations</strong>
+                <span>Let an agent curate References for you</span>
+              </Link>
               {signupPluginEnabled() ? (
                 <Link
                   href={administrationPanelHref("signups", isDemo)}
@@ -4477,6 +4522,7 @@ function AdministrationDeskView({
             </nav>}
             <div className="news-desk-settings-panel">
               {administrationPanel === "signups" ? <SignupEntriesPanel /> : null}
+              {administrationPanel === "delegations" ? <AdministrationDelegationsPanel disabled={disabled} /> : null}
               {administrationPanel === "users" ? (
                 <AdministrationUsersPanel
                   canManageUsers={canManageUsers}
@@ -13181,7 +13227,7 @@ function signupPluginEnabled(): boolean {
 }
 
 function normalizeAdministrationPanel(value: string | null | undefined): AdministrationPanel {
-  if (value === "policies" || value === "sections" || value === "procedures") return value;
+  if (value === "policies" || value === "sections" || value === "procedures" || value === "delegations") return value;
   if (value === "signups" && signupPluginEnabled()) return value;
   return "users";
 }

package/lib/content-source-context.ts

@@ -1,10 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getContentSource, type ContentSource } from "./site-env";
+import { tenantIdFromEnvironment } from "./tenant-keys";
 
 export type ContentSourceContext = {
   source: ContentSource;
   /** Request-scoped data client (drafts mode: carries the visitor's session cookies). */
   client?: unknown;
+  /** Tenant of the selected Prospectus account; falls back to PAPYRUS_TENANT_ID. */
+  tenantId?: string;
 };
 
 const contentSourceStorage = new AsyncLocalStorage<ContentSourceContext>();
@@ -13,8 +16,13 @@ export function runWithContentSource<T>(
   source: ContentSource,
   operation: () => Promise<T>,
   client?: unknown,
+  tenantId?: string,
 ): Promise<T> {
-  return contentSourceStorage.run({ source, client }, operation);
+  return contentSourceStorage.run({ source, client, tenantId }, operation);
+}
+
+export function currentTenantId(): string | undefined {
+  return contentSourceStorage.getStore()?.tenantId ?? tenantIdFromEnvironment();
 }
 
 export function currentRequestClient<T>(): T | undefined {

package/lib/curation-delegation-helpers.ts

@@ -0,0 +1,59 @@
+export const DEFAULT_DELEGATION_HOURS = 8;
+export const MINIMUM_DELEGATION_HOURS = 1;
+export const MAXIMUM_DELEGATION_HOURS = 72;
+
+export type CurationDelegationRecord = {
+  delegationId: string;
+  agentLabel: string;
+  grantorLabel: string | null;
+  expiresAt: string;
+  revokedAt: string | null;
+};
+
+export type DelegationInputValidation =
+  | { ok: true; agentLabel: string; hours: number }
+  | { ok: false; message: string };
+
+export function validateDelegationInput(agentLabelText: string, hoursText: string): DelegationInputValidation {
+  const agentLabel = agentLabelText.trim();
+  if (!agentLabel) return { ok: false, message: "Enter the name of the agent you are trusting." };
+  if (/\s/.test(agentLabel)) return { ok: false, message: "The agent name cannot contain spaces. Use the name the agent passes as --agent." };
+  const trimmedHours = hoursText.trim();
+  if (!/^\d+$/.test(trimmedHours)) return { ok: false, message: `Enter a whole number of hours from ${MINIMUM_DELEGATION_HOURS} to ${MAXIMUM_DELEGATION_HOURS}.` };
+  const hours = Number(trimmedHours);
+  if (hours < MINIMUM_DELEGATION_HOURS || hours > MAXIMUM_DELEGATION_HOURS) {
+    return { ok: false, message: `A delegation lasts from ${MINIMUM_DELEGATION_HOURS} to ${MAXIMUM_DELEGATION_HOURS} hours.` };
+  }
+  return { ok: true, agentLabel, hours };
+}
+
+export function delegationExpiryText(expiresAt: string, revokedAt: string | null, nowMilliseconds: number): string {
+  if (revokedAt) return "Revoked";
+  const remaining = Date.parse(expiresAt) - nowMilliseconds;
+  if (!Number.isFinite(remaining) || remaining <= 0) return "Expired";
+  const minutes = Math.ceil(remaining / 60_000);
+  if (minutes < 60) return `Expires in ${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+  const hours = Math.round(remaining / 3_600_000);
+  return `Expires in ${hours} ${hours === 1 ? "hour" : "hours"}`;
+}
+
+export function isDelegationActive(record: CurationDelegationRecord, nowMilliseconds: number): boolean {
+  return !record.revokedAt && Date.parse(record.expiresAt) > nowMilliseconds;
+}
+
+export function buildDelegatedCommandLine(input: { email: string; agentLabel: string; token: string; action?: "approve" | "reject" }): string {
+  const email = input.email.trim() || "<your-email>";
+  return `papyrus references ${input.action ?? "approve"} <reference-id> --on-behalf-of ${email} --agent ${input.agentLabel} --instruction "<the person's own words>" --delegation-token ${input.token}`;
+}
+
+export function describeDelegationError(error: unknown): string {
+  const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  const graphql = (error as { errors?: Array<{ message?: string }> } | null)?.errors?.[0]?.message ?? "";
+  const text = `${raw} ${graphql}`.toLowerCase();
+  if (text.includes("not authorized") || text.includes("unauthorized")) return "Your account is not allowed to manage delegations. Only editors and administrators can.";
+  if (text.includes("not found")) return "That delegation no longer exists.";
+  if (text.includes("only the person who granted")) return "Only the person who granted a delegation, or an administrator, can revoke it.";
+  if (text.includes("network") || text.includes("failed to fetch")) return "Could not reach the server. Check your connection and try again.";
+  const detail = (graphql || raw).trim();
+  return detail ? `The server refused the request: ${detail}` : "Something went wrong. Nothing was changed.";
+}

package/lib/cyclotron-suggestions.ts

@@ -0,0 +1,263 @@
+import type { MessageRecord } from "./category-repository";
+import type { RelevanceCuration, RelevanceDecisionView } from "./relevance-decisions";
+import { safeId } from "./relevance-status";
+
+export const SHADOW_AGREEMENT_SCHEMA = "cyclotron-shadow-agreement/v1";
+export const MINIMUM_COMPARISONS_FOR_AGREEMENT = 10;
+
+/** What the sweep recorded about the loop itself: whether it is on, when it last ran, why it stopped. */
+export type CyclotronLoopState = {
+  enabled: boolean;
+  stoppedBecause: string | null;
+  lastSweepAt: string | null;
+  maxDecisionsPerDay: number | null;
+};
+
+/** The live-agreement payload the sweep writes: suggestions compared with later human decisions. */
+export type ShadowAgreement = {
+  schema: typeof SHADOW_AGREEMENT_SCHEMA;
+  comparisons: number;
+  agreement: number | null;
+  precision: number | null;
+  recall: number | null;
+  confusion: Record<string, unknown> | null;
+  computedAt: string | null;
+  positiveLabel: string | null;
+  loop: CyclotronLoopState | null;
+};
+
+export type AgreementStripMeasurement = {
+  comparisons: number;
+  agreement: number | null;
+  precision: number | null;
+  recall: number | null;
+  computedAt: string | null;
+};
+
+export type AgreementStripState =
+  | { kind: "hidden" }
+  | {
+    kind: "not_enough" | "measured";
+    measurement: AgreementStripMeasurement;
+    needed: number;
+    loop: CyclotronLoopState | null;
+    stopReasonSentence: string | null;
+  };
+
+export function shadowAgreementPayloadId(cyclotronId: string): string {
+  return `knowledge-raw-payload-cyclotron-shadow-agreement-${safeId(cyclotronId)}`;
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseLoop(value: unknown): CyclotronLoopState | null {
+  if (!value || typeof value !== "object") return null;
+  const loop = value as Record<string, unknown>;
+  if (typeof loop.enabled !== "boolean") return null;
+  return {
+    enabled: loop.enabled,
+    stoppedBecause: typeof loop.stoppedBecause === "string" && loop.stoppedBecause ? loop.stoppedBecause : null,
+    lastSweepAt: typeof loop.lastSweepAt === "string" ? loop.lastSweepAt : null,
+    maxDecisionsPerDay: numberOrNull(loop.maxDecisionsPerDay),
+  };
+}
+
+/** A shadow-agreement payload, or null for any other JSON. */
+export function parseShadowAgreement(json: unknown): ShadowAgreement | null {
+  if (!json || typeof json !== "object") return null;
+  const record = json as Record<string, unknown>;
+  if (record.schema !== SHADOW_AGREEMENT_SCHEMA) return null;
+  return {
+    schema: SHADOW_AGREEMENT_SCHEMA,
+    comparisons: numberOrNull(record.comparisons) ?? 0,
+    agreement: numberOrNull(record.agreement),
+    precision: numberOrNull(record.precision),
+    recall: numberOrNull(record.recall),
+    confusion: record.confusion && typeof record.confusion === "object" ? (record.confusion as Record<string, unknown>) : null,
+    computedAt: typeof record.computedAt === "string" ? record.computedAt : null,
+    positiveLabel: typeof record.positiveLabel === "string" ? record.positiveLabel : null,
+    loop: parseLoop(record.loop),
+  };
+}
+
+/** The newest valid payload among a payload owner's attachments. */
+export function latestShadowAgreement(payloads: Array<{ json: unknown; updatedAt?: string | null }>): ShadowAgreement | null {
+  const valid = payloads
+    .map((payload) => ({ agreement: parseShadowAgreement(payload.json), updatedAt: payload.updatedAt }))
+    .filter((entry): entry is { agreement: ShadowAgreement; updatedAt: string | null | undefined } => entry.agreement !== null)
+    .sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")));
+  return valid.length ? valid[0].agreement : null;
+}
+
+const STOP_REASON_WORDS: Record<string, string> = {
+  disabled: "The relevance cyclotron is switched off in the steering config, so it is making no suggestions.",
+  "daily decision cap": "The last sweep stopped at the daily decision cap, so some references have no suggestion yet.",
+};
+
+/** The sentence an editor reads for a stop reason; unknown reasons are shown as given. */
+export function stopReasonSentence(reason: string): string {
+  return STOP_REASON_WORDS[reason] ?? `The last sweep stopped early: ${reason}.`;
+}
+
+/**
+ * What the Live agreement strip shows. No payload hides it; under ten
+ * comparisons the figures are withheld; a stop reason is always put in words.
+ */
+export function agreementStripState(agreement: ShadowAgreement | null): AgreementStripState {
+  if (!agreement) return { kind: "hidden" };
+  const loop = agreement.loop;
+  return {
+    kind: agreement.comparisons < MINIMUM_COMPARISONS_FOR_AGREEMENT ? "not_enough" : "measured",
+    measurement: {
+      comparisons: agreement.comparisons,
+      agreement: agreement.agreement,
+      precision: agreement.precision,
+      recall: agreement.recall,
+      computedAt: agreement.computedAt,
+    },
+    needed: MINIMUM_COMPARISONS_FOR_AGREEMENT,
+    loop,
+    stopReasonSentence: loop?.stoppedBecause ? stopReasonSentence(loop.stoppedBecause) : null,
+  };
+}
+
+/** "Loop on" or "Loop off", the word the strip leads with. */
+export function loopStateWords(loop: CyclotronLoopState): string {
+  return loop.enabled ? "Loop on" : "Loop off";
+}
+
+/** The daily cap in words; no cap is said plainly. */
+export function dailyCapWords(loop: CyclotronLoopState): string {
+  return loop.maxDecisionsPerDay === null ? "No daily decision cap" : `Daily cap ${loop.maxDecisionsPerDay} decisions`;
+}
+
+export function formatPercentage(fraction: number | null): string {
+  return fraction === null ? "not measured" : `${Math.round(fraction * 100)}%`;
+}
+
+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 {};
+  }
+}
+
+/**
+ * Reference lineage ids whose latest curation Message was made by a signed-in
+ * person. Agent and classifier status changes never appear here, and neither
+ * does a reference a person decided before a later non-human change.
+ */
+export function referencesWithHumanLatestCuration(messages: MessageRecord[]): Set<string> {
+  const latestByReference = new Map<string, { createdAt: string; human: boolean }>();
+  for (const message of messages) {
+    if (message.messageKind !== "reference_curation") continue;
+    const metadata = parseMetadata(message.metadata);
+    const lineageId = typeof metadata.referenceLineageId === "string" ? metadata.referenceLineageId : "";
+    if (!lineageId) continue;
+    const seen = latestByReference.get(lineageId);
+    if (seen && seen.createdAt >= message.createdAt) continue;
+    latestByReference.set(lineageId, { createdAt: message.createdAt, human: metadata.actorKind === "human" });
+  }
+  return new Set([...latestByReference].filter(([, entry]) => entry.human).map(([lineageId]) => lineageId));
+}
+
+export type SuggestionChoice = "agree" | "overrule";
+
+/**
+ * The accept or reject an editor's click becomes. Agreeing does what the
+ * suggestion implies; overruling does the opposite. Both are the ordinary
+ * curation actions, tied to the suggestion they answered.
+ */
+export function curationForSuggestionChoice(decision: RelevanceDecisionView, choice: SuggestionChoice): RelevanceCuration {
+  const suggestsAccept = decision.positiveLabel !== null && decision.label === decision.positiveLabel;
+  const accept = choice === "agree" ? suggestsAccept : !suggestsAccept;
+  return {
+    action: accept ? "accept" : "reject",
+    reasonCode: null,
+    note: null,
+    decisionRelationId: decision.decisionRelationId,
+    shareable: false,
+  };
+}
+
+export type ProvenanceSummary = {
+  teachingLabelsSentence: string;
+  primingExamplesSentence: string;
+  doctrineShortHash: string | null;
+  modelVersion: string | null;
+  decidedAt: string | null;
+};
+
+const SHORT_HASH_LENGTH = 8;
+
+/** The facts the "How this suggestion was made" block lists; null when the decision recorded no provenance. */
+export function provenanceSummary(decision: RelevanceDecisionView): ProvenanceSummary | null {
+  const provenance = decision.provenance;
+  if (!provenance) return null;
+  const plural = (count: number, singular: string) => `${count} ${singular}${count === 1 ? "" : "s"}`;
+  return {
+    teachingLabelsSentence: `Taught by ${plural(provenance.teachingLabels, "label")} that editors set themselves`,
+    primingExamplesSentence: `${plural(provenance.primingExamples, "priming example")} supplied as starting examples`,
+    doctrineShortHash: provenance.doctrineFingerprint ? provenance.doctrineFingerprint.slice(0, SHORT_HASH_LENGTH) : null,
+    modelVersion: decision.version === null ? null : `version ${decision.version}`,
+    decidedAt: decision.decidedAt,
+  };
+}
+
+export function suggestionConfidenceWords(decision: RelevanceDecisionView): string {
+  return decision.confidence === null ? "confidence unknown" : `${Math.round(decision.confidence * 100)}% sure`;
+}
+
+/** A curation recorded by an agent using a delegation a person granted. */
+export type DelegatedCuration = {
+  agent: string;
+  person: string | null;
+  instruction: string;
+  delegationId: string;
+  delegationShortId: string;
+  /** What the backend does: a delegated curation is stamped human, so the person's label trains the cyclotron. */
+  countsAsTrainingLabel: boolean;
+};
+
+const DELEGATION_ID_PREFIX = "curation-delegation-";
+const DELEGATION_SHORT_ID_LENGTH = 8;
+
+export function delegationShortId(delegationId: string): string {
+  return delegationId.replace(DELEGATION_ID_PREFIX, "").slice(0, DELEGATION_SHORT_ID_LENGTH);
+}
+
+/**
+ * Delegated curations by reference lineage, from each reference's latest
+ * curation Message only. The person is the Message author; the agent is relayedBy.
+ */
+export function delegatedCurationsByReference(messages: MessageRecord[]): Map<string, DelegatedCuration> {
+  const latest = new Map<string, MessageRecord>();
+  for (const message of messages) {
+    if (message.messageKind !== "reference_curation") continue;
+    const lineageId = parseMetadata(message.metadata).referenceLineageId;
+    if (typeof lineageId !== "string" || !lineageId) continue;
+    const seen = latest.get(lineageId);
+    if (!seen || seen.createdAt < message.createdAt) latest.set(lineageId, message);
+  }
+  const delegated = new Map<string, DelegatedCuration>();
+  for (const [lineageId, message] of latest) {
+    const metadata = parseMetadata(message.metadata);
+    if (metadata.attestation !== "delegated") continue;
+    const delegationId = typeof metadata.delegationId === "string" ? metadata.delegationId : "";
+    delegated.set(lineageId, {
+      agent: typeof metadata.relayedBy === "string" && metadata.relayedBy ? metadata.relayedBy : "an agent",
+      person: message.authorLabel?.trim() || null,
+      instruction: typeof metadata.instruction === "string" ? metadata.instruction : "",
+      delegationId,
+      delegationShortId: delegationShortId(delegationId),
+      countsAsTrainingLabel: metadata.actorKind === "human",
+    });
+  }
+  return delegated;
+}