@anthusai/papyrus 5.43.0 → 5.45.0

package/lib/monitoring-paging.ts

@@ -0,0 +1,58 @@
+/** Merging loaded pages into the Monitoring lists. Kept free of other imports so the panel's tests can load it alone. */
+import type {
+  MonitoringCursors,
+  MonitoringItem,
+  MonitoringListName,
+  MonitoringListRows,
+  MonitoringOverview,
+} from "./monitoring-overview";
+
+/** Rows the editor has loaded beyond the first page of each list, and where each list continues. */
+export type MonitoringLoadedPages = Partial<{ [L in MonitoringListName]: { rows: MonitoringListRows[L][]; cursor: string | null } }>;
+
+const ROW_KEYS: { [L in MonitoringListName]: (row: MonitoringListRows[L]) => string } = {
+  runs: (row) => `${row.runId}`,
+  routerRuns: (row) => `${row.runId}`,
+  items: (row) => `${row.monitorId ?? ""}|${row.sourceId}`,
+  emailSubmissions: (row) => row.receiptId,
+};
+
+/**
+ * The first page followed by loaded pages, with a row seen twice kept once. The refresh re-reads the first page, so
+ * a row that moved onto it from a later page must not be listed again; for items the highest revision wins.
+ */
+export function mergeListPages<L extends MonitoringListName>(list: L, first: MonitoringListRows[L][], loaded: MonitoringListRows[L][]): MonitoringListRows[L][] {
+  const keyOf = ROW_KEYS[list] as (row: MonitoringListRows[L]) => string;
+  const seen = new Map<string, number>();
+  const merged: MonitoringListRows[L][] = [];
+  for (const row of [...first, ...loaded]) {
+    const key = keyOf(row);
+    const at = seen.get(key);
+    if (at === undefined) {
+      seen.set(key, merged.length);
+      merged.push(row);
+    } else if (list === "items" && (row as MonitoringItem).revision > (merged[at] as MonitoringItem).revision) {
+      merged[at] = row;
+    }
+  }
+  return merged;
+}
+
+/**
+ * What the page shows: the refreshed first page of every list plus whatever the editor loaded, with each list's
+ * cursor. With `held` the email list is replaced by the held-for-review list (its own pages).
+ */
+export function withLoadedPages(overview: MonitoringOverview, loaded: MonitoringLoadedPages, held: MonitoringLoadedPages["emailSubmissions"] | null): MonitoringOverview {
+  const cursors: MonitoringCursors = {};
+  const lists: Partial<Record<MonitoringListName, unknown[]>> = {};
+  for (const list of ["runs", "routerRuns", "items", "emailSubmissions"] as const) {
+    const extra = loaded[list];
+    lists[list] = mergeListPages(list, (overview[list] ?? []) as never[], (extra?.rows ?? []) as never[]) as unknown[];
+    cursors[list] = extra ? extra.cursor : overview.cursors?.[list] ?? null;
+  }
+  if (held) {
+    lists.emailSubmissions = held.rows;
+    cursors.emailSubmissions = held.cursor;
+  }
+  return { ...overview, ...(lists as Pick<MonitoringOverview, MonitoringListName>), cursors };
+}

package/lib/newsroom-chat-identity.ts

@@ -2,6 +2,7 @@ import { CognitoJwtVerifier } from "aws-jwt-verify";
 import type { JwksCache } from "aws-jwt-verify/jwk";
 import type { NextRequest } from "next/server";
 import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+import { STAFF_GROUPS } from "./staff-groups";
 
 export type NewsroomChatIdentity = { subject: string; issuer: string; clientId: string; expiresAt: number };
 export type NewsroomChatIdentityResolver = (request: NextRequest) => Promise<NewsroomChatIdentity | null>;
@@ -14,7 +15,7 @@ export function newsroomChatIdentityResolver(
     userPoolId: auth.user_pool_id,
     clientId: auth.user_pool_client_id,
     tokenUse: "access",
-    groups: ["editor", "admin"],
+    groups: [...STAFF_GROUPS],
   }, jwksCache ? { jwksCache } : undefined);
   return async (request) => {
     const token = request.headers.get("authorization")?.match(/^Bearer ([^\s]+)$/i)?.[1];

package/lib/newsroom-organizer-nav.ts

@@ -11,6 +11,7 @@ export const ORGANIZER_NAV_GROUPS: readonly { title: string; items: readonly Org
     { key: "overview", label: "Overview", description: "See notifications and work needing attention.", path: "/newsroom", primary: true },
     { key: "articles", label: getContentItemName().plural, description: `Follow ${contentItemPluralLowercase} across their stages and open one to write or revise it.`, path: `/newsroom/${contentItemBoardPathSegment()}`, alsoActiveOnPaths: ["/newsroom/articles"], primary: true },
     { key: "assignments", label: "Assignments", description: "Follow research and reporting work across its statuses and claim it.", path: "/newsroom/assignments" },
+    { key: "drafts", label: "Drafts", description: "Read the story drafts that AI proposes, then accept or reject them.", path: "/newsroom/administration/proposals" },
     { key: "messages", label: "Messages", description: "Read and reply to newsroom conversations.", path: "/newsroom/messages", primary: true },
   ] },
   { title: "Research & knowledge", items: [

package/lib/proposals-client.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import { EDIT_PROPOSAL, TRANSITION_PROPOSAL, type ProposalMove, type ProposalReceipt } from "./proposals-admin";
+
+type GraphResult = { data?: Record<string, ProposalReceipt | null>; errors?: { message?: string }[] };
+
+async function run(query: string, field: string, variables: Record<string, string | undefined>): Promise<ProposalReceipt> {
+  const client = generateClient({ authMode: "userPool" });
+  const result = (await client.graphql({ query, variables })) as GraphResult;
+  if (result.errors?.length) return { status: "refused", message: result.errors[0]?.message ?? "The action failed." };
+  return result.data?.[field] ?? { status: "refused", message: "The action did not answer." };
+}
+
+/** Moves a proposal through `path`, one `transitionProposal` call per state, stopping at the first refusal. */
+export async function transitionProposalPath(proposalId: string, path: readonly string[], reason = ""): Promise<ProposalReceipt> {
+  let receipt: ProposalReceipt = { status: "refused", message: "Nothing to do." };
+  for (const state of path) {
+    receipt = await run(TRANSITION_PROPOSAL, "transitionProposal", { proposalId, state, ...(reason ? { reason } : {}) });
+    if (receipt.status !== "ok") break;
+  }
+  return receipt;
+}
+
+/** One button of the Proposals panel: a path of states, or `editProposal` for pin and hold. */
+export async function performProposalMove(proposalId: string, move: ProposalMove, reason: string): Promise<ProposalReceipt> {
+  if (move.edit) return run(EDIT_PROPOSAL, "editProposal", { proposalId, action: move.edit });
+  return transitionProposalPath(proposalId, move.path ?? [], reason);
+}

package/lib/reader-subject.ts

@@ -1,10 +1,11 @@
 import { createHmac } from "node:crypto";
 import type { ProspectusSignedInSession } from "./prospectus-session";
+import { hasEditorRights, STAFF_GROUPS } from "./staff-groups";
 
 export const SITE_SUBJECT_PATTERN = /^ss1_[A-Za-z0-9_-]{43}$/;
 export const INTERIM_SUBJECT_PATTERN = /^ssdev_[A-Za-z0-9_-]{43}$/;
 export const READER_DEV_SECRET_ENV = "PAPYRUS_READER_DEV_SECRET";
-export const READER_STAFF_GROUPS = ["editor", "admin"] as const;
+export const READER_STAFF_GROUPS = STAFF_GROUPS;
 
 const MINIMUM_DEV_SECRET_LENGTH = 16;
 const INTERIM_SUBJECT_PREFIX = "ssdev_";
@@ -46,7 +47,7 @@ export function readerIsStaff(session: Pick<ProspectusSignedInSession, "accessTo
   try {
     const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as { "cognito:groups"?: unknown };
     const groups = claims["cognito:groups"];
-    return Array.isArray(groups) && groups.some((group) => (READER_STAFF_GROUPS as readonly unknown[]).includes(group));
+    return Array.isArray(groups) && hasEditorRights(groups);
   } catch {
     return false;
   }

package/lib/reference-feed-cache.ts

@@ -0,0 +1,133 @@
+/**
+ * Stale-while-revalidate copies of what the editor last saw, so a return visit paints cards (and the signed-in name) at once
+ * while the real reads run in the background. Display state only: the backend still authorizes every call, a cached copy never
+ * enables an action by itself, and everything here is dropped on sign-out. Every storage touch is guarded: the page renders
+ * the same, only slower, when storage is blocked or full.
+ */
+import type { ReferenceRecord } from "./category-repository";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+import type { ReferencePreview } from "./reference-preview";
+
+const FEED_PREFIX = "papyrus.references.feed.v1.";
+const SESSION_PREFIX = "papyrus.newsroom.session.v1.";
+/** A saved session summary is trusted for display only this long; the live check always still runs. */
+export const SESSION_DISPLAY_TTL_MS = 15 * 60 * 1000;
+
+export type FeedSnapshot = {
+  savedAt: number;
+  references: ReferenceRecord[];
+  previews: Array<[string, ReferencePreview]>;
+  decisions: Array<[string, RelevanceDecisionView]>;
+};
+
+export type SessionDisplay = {
+  savedAt: number;
+  label: string;
+  isAdmin: boolean;
+};
+
+function storageOf(kind: "local" | "session"): Storage | null {
+  try {
+    if (typeof window === "undefined") return null;
+    return kind === "local" ? window.localStorage : window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function read<T>(kind: "local" | "session", key: string): T | null {
+  try {
+    const raw = storageOf(kind)?.getItem(key);
+    return raw ? JSON.parse(raw) as T : null;
+  } catch {
+    return null;
+  }
+}
+
+function write(kind: "local" | "session", key: string, value: unknown): boolean {
+  try {
+    const storage = storageOf(kind);
+    if (!storage) return false;
+    storage.setItem(key, JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function remove(kind: "local" | "session", key: string) {
+  try { storageOf(kind)?.removeItem(key); } catch { /* nothing to clear */ }
+}
+
+/** The fields a card needs, and nothing else: a smaller copy that fits, and less private text at rest. */
+export function slimReference(reference: ReferenceRecord): ReferenceRecord {
+  return {
+    id: reference.id,
+    lineageId: reference.lineageId,
+    versionNumber: reference.versionNumber,
+    versionState: reference.versionState,
+    corpusId: reference.corpusId,
+    externalItemId: reference.externalItemId,
+    title: reference.title,
+    sourceUri: reference.sourceUri,
+    mediaType: reference.mediaType,
+    sourcePublishedAt: reference.sourcePublishedAt,
+    retrievedAt: reference.retrievedAt,
+    importedAt: reference.importedAt,
+    createdAt: reference.createdAt,
+    curationStatus: reference.curationStatus,
+    curationStatusUpdatedAt: reference.curationStatusUpdatedAt,
+    curationStatusReason: reference.curationStatusReason,
+  };
+}
+
+export function feedCacheKey(siteId: string): string {
+  return `${FEED_PREFIX}${siteId}`;
+}
+
+export function loadFeedSnapshot(siteId: string): FeedSnapshot | null {
+  const snapshot = read<FeedSnapshot>("local", feedCacheKey(siteId));
+  if (!snapshot || !Array.isArray(snapshot.references) || !snapshot.references.length) return null;
+  return snapshot;
+}
+
+/** Saves the newest copy. On a full store it keeps the newest half, then gives up quietly. */
+export function saveFeedSnapshot(
+  siteId: string,
+  parts: { references: ReferenceRecord[]; previews: ReadonlyMap<string, ReferencePreview>; decisions: ReadonlyMap<string, RelevanceDecisionView> },
+  now = Date.now(),
+): boolean {
+  let references = parts.references.map(slimReference);
+  for (let attempt = 0; attempt < 4 && references.length; attempt += 1) {
+    const kept = new Set(references.map((reference) => reference.lineageId ?? reference.id));
+    const snapshot: FeedSnapshot = {
+      savedAt: now,
+      references,
+      previews: [...parts.previews].filter(([lineage]) => kept.has(lineage)),
+      decisions: [...parts.decisions].filter(([lineage]) => kept.has(lineage)).map(([lineage, decision]) => [lineage, { ...decision, provenance: null }]),
+    };
+    if (write("local", feedCacheKey(siteId), snapshot)) return true;
+    references = references.slice(0, Math.ceil(references.length / 2));
+  }
+  return false;
+}
+
+export function clearFeedSnapshot(siteId: string) {
+  remove("local", feedCacheKey(siteId));
+}
+
+export function loadSessionDisplay(siteId: string, now = Date.now()): SessionDisplay | null {
+  const saved = read<SessionDisplay>("session", `${SESSION_PREFIX}${siteId}`);
+  if (!saved || typeof saved.label !== "string" || typeof saved.savedAt !== "number") return null;
+  return now - saved.savedAt <= SESSION_DISPLAY_TTL_MS ? saved : null;
+}
+
+export function saveSessionDisplay(siteId: string, display: Omit<SessionDisplay, "savedAt">, now = Date.now()) {
+  write("session", `${SESSION_PREFIX}${siteId}`, { ...display, savedAt: now });
+}
+
+/** Sign-out: nothing of the signed-in view survives in this browser. */
+export function clearSavedNewsroomDisplay(siteId: string) {
+  remove("session", `${SESSION_PREFIX}${siteId}`);
+  clearFeedSnapshot(siteId);
+}

package/lib/reference-feed-ranking.ts

@@ -0,0 +1,191 @@
+/**
+ * How the References feed is ordered, and which cards belong in which tab.
+ *
+ * Plain words, as the "How this feed is ranked" popover says them:
+ *   1. The Cyclotron's prediction becomes a probability that you will Accept (P). A prediction of Accept at 80% is
+ *      P = 0.8; a prediction of Reject at 80% is P = 0.2; no prediction is P = 0.5.
+ *   2. Old items lose their say. The score is 0.5 + (P - 0.5) * w, where w = exp(-age / tau) is a freshness weight.
+ *      Age pulls an item toward "uncertain" (0.5), never to the bottom.
+ *   3. tau is learned from how old the References you accepted were when you accepted them
+ *      (tau = median age / ln 2). With fewer than 10 accepted examples nothing is guessed: no decay.
+ *   4. Highest score first. The strongest Reject predictions end up last. Ties go to the newest item.
+ *   5. Unrated items older than 3 tau move to "Earlier" at the bottom. Nothing is deleted.
+ *
+ * The same recipe ranks monitor stories (`learn_freshness` in src/papyrus_content/ideas/monitor_stories.py).
+ */
+import type { ReferenceRecord } from "./category-repository";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import { referenceLineageId } from "./newsroom-references";
+
+/** Fewer accepted examples than this and there is no freshness weight: a constant is never guessed. */
+export const MINIMUM_FRESHNESS_EXAMPLES = 10;
+/** An unrated item whose age passes this many tau has a weight below exp(-3), about 5%, and moves to Earlier. */
+export const EARLIER_AFTER_TAUS = 3;
+/** The probability that stands for "no prediction". */
+export const UNDECIDED_PROBABILITY = 0.5;
+/** A prediction that recorded a label but no confidence is a mild lean, not a coin toss and not a certainty. */
+export const UNRECORDED_CONFIDENCE = 0.6;
+
+const DAY_MILLISECONDS = 86_400_000;
+
+export type FeedFreshness = {
+  /** Null when there were too few accepted examples to learn from: no decay at all. */
+  tauDays: number | null;
+  medianAgeDays: number | null;
+  examples: number;
+};
+
+function timeOf(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** When the item reached the newsroom. The same arrival the monitor stories use. */
+export function referenceArrivalTime(reference: ReferenceRecord): number | null {
+  return timeOf(reference.createdAt) ?? timeOf(reference.importedAt) ?? timeOf(reference.retrievedAt) ?? timeOf(reference.sourcePublishedAt);
+}
+
+/** The date a card shows: when the source says it was published, else when it arrived. */
+export function referenceDisplayTime(reference: ReferenceRecord): number | null {
+  return timeOf(reference.sourcePublishedAt) ?? timeOf(reference.sourceUpdatedAt) ?? referenceArrivalTime(reference);
+}
+
+/**
+ * tau from the age at acceptance of accepted References: median / ln 2, since the median age of an exponential
+ * exp(-age / tau) is tau * ln 2. `ignore` keeps the item an editor just rated from moving the very ranking they are looking at.
+ */
+export function learnFreshness(references: ReferenceRecord[], ignore: ReadonlySet<string> = new Set()): FeedFreshness {
+  const ages: number[] = [];
+  for (const reference of references) {
+    if (normalizeReferenceCurationStatus(reference.curationStatus) !== "accepted" || ignore.has(referenceLineageId(reference))) continue;
+    const arrived = referenceArrivalTime(reference);
+    const decided = timeOf(reference.curationStatusUpdatedAt);
+    if (arrived === null || decided === null) continue;
+    const age = (decided - arrived) / DAY_MILLISECONDS;
+    if (age > 0) ages.push(age);
+  }
+  if (ages.length < MINIMUM_FRESHNESS_EXAMPLES) return { tauDays: null, medianAgeDays: null, examples: ages.length };
+  ages.sort((left, right) => left - right);
+  const middle = Math.floor(ages.length / 2);
+  const median = ages.length % 2 ? ages[middle] : (ages[middle - 1] + ages[middle]) / 2;
+  return { tauDays: median / Math.LN2, medianAgeDays: median, examples: ages.length };
+}
+
+/** exp(-age / tau) at `now`; 1 without a learned tau or an unreadable arrival. */
+export function freshnessWeight(reference: ReferenceRecord, freshness: FeedFreshness, now: number): number {
+  const arrived = referenceArrivalTime(reference);
+  if (freshness.tauDays === null || arrived === null) return 1;
+  return Math.exp(-Math.max(now - arrived, 0) / DAY_MILLISECONDS / freshness.tauDays);
+}
+
+/** P(the editor accepts), from the Cyclotron's decision: its confidence is in the label it chose. */
+export function acceptProbability(decision: RelevanceDecisionView | undefined): number {
+  if (!decision) return UNDECIDED_PROBABILITY;
+  const confidence = decision.confidence ?? UNRECORDED_CONFIDENCE;
+  const accepts = decision.label === (decision.positiveLabel ?? "include");
+  return accepts ? confidence : 1 - confidence;
+}
+
+export type FeedItem = {
+  reference: ReferenceRecord;
+  lineageId: string;
+  decision: RelevanceDecisionView | undefined;
+  /** P(accept) before freshness. */
+  probability: number;
+  weight: number;
+  /** 0.5 + (P - 0.5) * weight. Highest is first. */
+  score: number;
+  /** True when this unrated item is older than the Earlier threshold. */
+  earlier: boolean;
+};
+
+export function scoreFeedItem(reference: ReferenceRecord, decision: RelevanceDecisionView | undefined, freshness: FeedFreshness, now: number): FeedItem {
+  const probability = acceptProbability(decision);
+  const weight = freshnessWeight(reference, freshness, now);
+  const arrived = referenceArrivalTime(reference);
+  const earlier = freshness.tauDays !== null && arrived !== null && (now - arrived) / DAY_MILLISECONDS > EARLIER_AFTER_TAUS * freshness.tauDays;
+  return {
+    reference,
+    lineageId: referenceLineageId(reference),
+    decision,
+    probability,
+    weight,
+    score: UNDECIDED_PROBABILITY + (probability - UNDECIDED_PROBABILITY) * weight,
+    earlier,
+  };
+}
+
+/** Highest score first; ties go to the newest item, then to a stable id order. */
+export function compareFeedItems(left: FeedItem, right: FeedItem): number {
+  if (right.score !== left.score) return right.score - left.score;
+  const newest = (referenceDisplayTime(right.reference) ?? 0) - (referenceDisplayTime(left.reference) ?? 0);
+  return newest || left.lineageId.localeCompare(right.lineageId);
+}
+
+export type ReferenceFeedTabKey = "feed" | "rated" | "earlier";
+
+export type ReferenceFeedPartition = {
+  freshness: FeedFreshness;
+  /** Pending items, plus the ones rated during this visit (they keep their place), best prediction first. */
+  feed: FeedItem[];
+  /** Everything an editor has answered, most recent answer first. */
+  rated: FeedItem[];
+  /** Unrated items past the freshness threshold, ranked like the feed. Still ratable. */
+  earlier: FeedItem[];
+};
+
+/**
+ * Splits canonical References into the three tabs.
+ * `visitRated` holds lineage ids rated since the page opened: they stay in Feed, in place, showing the answer.
+ */
+export function partitionReferenceFeed(
+  references: ReferenceRecord[],
+  decisions: ReadonlyMap<string, RelevanceDecisionView> | undefined,
+  options: { now: number; visitRated?: ReadonlySet<string>; tauDaysOverride?: number | null },
+): ReferenceFeedPartition {
+  const visitRated = options.visitRated ?? new Set<string>();
+  const learned = learnFreshness(references, visitRated);
+  const freshness: FeedFreshness = options.tauDaysOverride && options.tauDaysOverride > 0
+    ? { ...learned, tauDays: options.tauDaysOverride }
+    : learned;
+  const feed: FeedItem[] = [];
+  const rated: FeedItem[] = [];
+  const earlier: FeedItem[] = [];
+  for (const reference of references) {
+    const status = normalizeReferenceCurationStatus(reference.curationStatus);
+    const lineageId = referenceLineageId(reference);
+    const item = scoreFeedItem(reference, decisions?.get(lineageId), freshness, options.now);
+    if (status === "archived") continue;
+    if (status === "accepted" || status === "rejected") {
+      rated.push(item);
+      if (visitRated.has(lineageId)) (item.earlier ? earlier : feed).push(item);
+    } else if (item.earlier) earlier.push(item);
+    else feed.push(item);
+  }
+  feed.sort(compareFeedItems);
+  earlier.sort(compareFeedItems);
+  rated.sort((left, right) => (timeOf(right.reference.curationStatusUpdatedAt) ?? 0) - (timeOf(left.reference.curationStatusUpdatedAt) ?? 0)
+    || left.lineageId.localeCompare(right.lineageId));
+  return { freshness, feed, rated, earlier };
+}
+
+export type FeedGroupKey = "top" | "more" | "least";
+
+/**
+ * The feed's sections, from the ranked list (already best first). No fixed counts: Top predictions are the Accepts at least half as
+ * strong as the strongest one, Least likely are the predicted Rejects, and More for you is everything between (weaker Accepts and
+ * items with no prediction). A group with no members is absent.
+ */
+export function groupFeedItems(items: FeedItem[]): Array<{ key: FeedGroupKey; items: FeedItem[] }> {
+  const strongest = items.reduce((best, item) => Math.max(best, item.score - UNDECIDED_PROBABILITY), 0);
+  const groups: Record<FeedGroupKey, FeedItem[]> = { top: [], more: [], least: [] };
+  for (const item of items) {
+    const strength = item.score - UNDECIDED_PROBABILITY;
+    if (strength < 0) groups.least.push(item);
+    else if (strength > 0 && strength >= strongest / 2) groups.top.push(item);
+    else groups.more.push(item);
+  }
+  return (["top", "more", "least"] as const).filter((key) => groups[key].length).map((key) => ({ key, items: groups[key] }));
+}

package/lib/reference-preview.ts

@@ -0,0 +1,112 @@
+/**
+ * What a Reference card shows besides its title: the source page's preview image, a one-line dek and the site name.
+ *
+ * Storage: a `ReferenceAttachment` with role "preview" (sort key "002-preview"), no schema change. `sourceUri` is the
+ * page's og:image / twitter:image address and `metadata` holds `{ description, siteName, title, fetchedAt }`. The newsroom
+ * already loads every attachment with the References, so the feed needs no extra request. `papyrus references enrich-images`
+ * (src/papyrus_content/reference_images.py) writes them.
+ */
+import type { ReferenceAttachmentRecord, ReferenceRecord } from "./category-repository";
+
+export const REFERENCE_PREVIEW_ROLE = "preview";
+
+export type ReferencePreview = {
+  imageUrl: string | null;
+  description: string | null;
+  siteName: string | null;
+  title: string | null;
+};
+
+function record(value: unknown): Record<string, unknown> {
+  if (typeof value === "string") {
+    try { return record(JSON.parse(value)); } catch { return {}; }
+  }
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function httpAddress(value: unknown): string | null {
+  const candidate = text(value);
+  return candidate && /^https?:\/\//i.test(candidate) ? candidate : null;
+}
+
+/** The preview of each Reference lineage, from its "preview" attachment. A lineage with none has no entry. */
+export function referencePreviewsByLineage(attachments: ReferenceAttachmentRecord[] | undefined): Map<string, ReferencePreview> {
+  const previews = new Map<string, ReferencePreview>();
+  for (const attachment of attachments ?? []) {
+    if (attachment.role !== REFERENCE_PREVIEW_ROLE || !attachment.referenceLineageId) continue;
+    const metadata = record(attachment.metadata);
+    previews.set(attachment.referenceLineageId, {
+      imageUrl: httpAddress(attachment.sourceUri) ?? httpAddress(metadata.imageUrl),
+      description: text(metadata.description),
+      siteName: text(metadata.siteName),
+      title: text(metadata.title),
+    });
+  }
+  return previews;
+}
+
+/** The one-line dek: the source page's description, else a summary recorded on the Reference. */
+export function referenceDek(reference: ReferenceRecord, preview: ReferencePreview | undefined): string | null {
+  if (preview?.description) return preview.description;
+  const metadata = record(reference.metadata);
+  for (const key of ["subtitle", "summary", "abstract", "description"]) {
+    const value = text(metadata[key]);
+    if (value) return value;
+  }
+  return null;
+}
+
+/** The source's host without "www.", or null when the Reference has no web address. */
+export function referenceSourceHost(reference: ReferenceRecord): string | null {
+  const candidate = httpAddress(reference.sourceUri);
+  if (!candidate) return null;
+  try { return new URL(candidate).hostname.replace(/^www\./i, "") || null; } catch { return null; }
+}
+
+/** Short age for a card: "5m", "3h", "2d", "6w", "4mo". */
+export function formatFeedAge(time: number | null, now: number): string | null {
+  if (time === null) return null;
+  const seconds = Math.max(0, Math.round((now - time) / 1000));
+  if (seconds < 60) return "now";
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.round(hours / 24);
+  if (days < 14) return `${days}d`;
+  if (days < 60) return `${Math.round(days / 7)}w`;
+  return `${Math.round(days / 30)}mo`;
+}
+
+function words(text: string): string[] {
+  return text.toLowerCase().normalize("NFKD").replace(/[^\p{L}\p{N}]+/gu, " ").split(" ").filter((word) => word.length > 1);
+}
+
+/**
+ * Whether the dek tells the reader something the headline and picture do not. A dek that repeats the headline, or that is mostly
+ * the headline's own words, is dropped; so is the description of a GitHub repository, whose social-card picture already prints it.
+ */
+export function dekAddsInformation(title: string, dek: string | null, imageUrl: string | null): boolean {
+  if (!dek) return false;
+  let imageHost = "";
+  try { imageHost = imageUrl ? new URL(imageUrl).hostname : ""; } catch { /* no host */ }
+  if (/(^|\.)opengraph\.githubassets\.com$/i.test(imageHost)) return false;
+  const titleWords = new Set(words(title));
+  const dekWords = words(dek);
+  if (!dekWords.length) return false;
+  const shared = dekWords.filter((word) => titleWords.has(word)).length;
+  const covered = titleWords.size ? [...titleWords].filter((word) => dekWords.includes(word)).length / titleWords.size : 0;
+  return shared / dekWords.length < 0.6 && covered < 0.8;
+}
+
+/** Pictures that are a text card, not a photograph: a repository social card, or any picture whose ratio is almost exactly 2:1. Cropping cuts the words off. */
+export function isCardStyleImage(url: string | null, naturalRatio: number | null): boolean {
+  let host = "";
+  try { host = url ? new URL(url).hostname : ""; } catch { /* no host */ }
+  if (/(^|\.)(opengraph\.githubassets\.com|repository-images\.githubusercontent\.com|github\.com)$/i.test(host)) return true;
+  return naturalRatio !== null && Math.abs(naturalRatio - 2) < 0.04;
+}

package/lib/review-client.ts

@@ -2,9 +2,10 @@
 
 import { generateClient } from "aws-amplify/data";
 import { getCurrentUser } from "aws-amplify/auth";
+import { draftDecisionUpdate, draftView, type DraftRow, type DraftView } from "./review-drafts";
 import {
   answerUpdate, isDue, normalizeReviewRow, timeoutUpdate,
-  type AnswerInput, type ReviewRequest,
+  type AnswerInput, type DraftDecision, type ReviewRequest,
 } from "./review-requests";
 
 /**
@@ -118,3 +119,39 @@ export async function loadStoryTitles(ids: string[]): Promise<{ titles: Record<s
   }));
   return { titles, deleted };
 }
+
+const MAX_DRAFT_LOOKUPS = 60;
+const DRAFT_FIELDS = "id kind title summary body state held evidence history override createdAt";
+
+/** Records one draft's decision on the request while it stays open. Same condition as an answer: state = open. */
+export async function saveDraftDecision(request: ReviewRequest, draftId: string, decision: DraftDecision): Promise<ReviewRequest> {
+  const result = await run(
+    `mutation Decide($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+    { input: draftDecisionUpdate(request, draftId, decision), 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 closed at its deadline. Refresh to see the result.");
+  }
+  if (result.errors?.length || !result.data?.updateReviewRequest) throw new Error("The draft was decided, but the request could not record it. Try again.");
+  return normalizeReviewRow(result.data.updateReviewRequest);
+}
+
+export type DraftLoad = { drafts: Record<string, DraftView>; missing: string[]; failed: string[] };
+
+/**
+ * The Proposals that review requests are about, by id (editors and admins may read them). `missing` ids have no proposal (an idea kept
+ * only as JSON has no proposal to open); `failed` ids could not be read right now, which says nothing about whether they exist.
+ */
+export async function loadDrafts(ids: string[], demo = false): Promise<DraftLoad> {
+  const drafts: Record<string, DraftView> = {};
+  const missing: string[] = [];
+  const failed: string[] = [];
+  await Promise.all([...new Set(ids)].slice(0, MAX_DRAFT_LOOKUPS).map(async (id) => {
+    const result = await run(`query Draft($id: ID!) { getProposal(id: $id) { ${DRAFT_FIELDS} } }`, { id });
+    const row = result.data?.getProposal as DraftRow | null | undefined;
+    if (row) drafts[id] = draftView(row, demo);
+    else if (result.errors?.length || !result.data) failed.push(id);
+    else missing.push(id);
+  }));
+  return { drafts, missing, failed };
+}