@anthusai/papyrus 1.0.0-next.9 → 1.1.0

package/lib/rate-limit-retry.ts

@@ -0,0 +1,55 @@
+export const RATE_LIMIT_RETRY_ATTEMPTS = 14;
+export const RATE_LIMIT_RETRY_BASE_MILLISECONDS = 500;
+export const RATE_LIMIT_RETRY_CAP_MILLISECONDS = 20_000;
+export const RATE_LIMIT_RETRY_BUDGET_MILLISECONDS = 120_000;
+
+export function isRateLimitError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const { name, message } = error as { name?: unknown; message?: unknown };
+  const text = `${typeof name === "string" ? name : ""} ${typeof message === "string" ? message : ""}`;
+  return /TooManyRequests|ThrottlingException|Rate exceeded|Unauthorized[\s\S]*set the \\?"authMode\\?"/i.test(text);
+}
+
+export type RateLimitRetryOptions = {
+  attempts?: number;
+  baseMilliseconds?: number;
+  capMilliseconds?: number;
+  budgetMilliseconds?: number;
+  sleep?: (milliseconds: number) => Promise<void>;
+  random?: () => number;
+  now?: () => number;
+};
+
+export function fullJitterDelayMilliseconds(
+  attempt: number,
+  baseMilliseconds: number,
+  capMilliseconds: number,
+  random: () => number,
+): number {
+  const ceiling = Math.min(capMilliseconds, baseMilliseconds * 2 ** (attempt - 1));
+  return random() * ceiling;
+}
+
+export async function withRateLimitRetry<T>(
+  operation: () => Promise<T>,
+  options: RateLimitRetryOptions = {},
+): Promise<T> {
+  const attempts = options.attempts ?? RATE_LIMIT_RETRY_ATTEMPTS;
+  const baseMilliseconds = options.baseMilliseconds ?? RATE_LIMIT_RETRY_BASE_MILLISECONDS;
+  const capMilliseconds = options.capMilliseconds ?? RATE_LIMIT_RETRY_CAP_MILLISECONDS;
+  const budgetMilliseconds = options.budgetMilliseconds ?? RATE_LIMIT_RETRY_BUDGET_MILLISECONDS;
+  const sleep = options.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt >= attempts || !isRateLimitError(error)) throw error;
+      const delay = fullJitterDelayMilliseconds(attempt, baseMilliseconds, capMilliseconds, random);
+      if (now() - startedAt + delay > budgetMilliseconds) throw error;
+      await sleep(delay);
+    }
+  }
+}

package/lib/reader-base-path.ts

@@ -0,0 +1,24 @@
+import { SITE_BRAND } from "./site-brand";
+
+export function normalizeReaderBasePath(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim().replace(/\/+$/, "");
+  if (!trimmed) return "";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+export function getReaderBasePath(): string {
+  return normalizeReaderBasePath(SITE_BRAND.readerBasePath);
+}
+
+export function toPublicReaderPath(path: string, readerBasePath: string = getReaderBasePath()): string {
+  if (!readerBasePath) return path;
+  if (path === "/" || path === "") return readerBasePath;
+  return `${readerBasePath}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+export function toInternalReaderPath(path: string, readerBasePath: string = getReaderBasePath()): string {
+  if (!readerBasePath) return path;
+  if (path === readerBasePath || path === `${readerBasePath}/`) return "/";
+  if (path.startsWith(`${readerBasePath}/`)) return path.slice(readerBasePath.length);
+  return path;
+}

package/lib/reader-cache-lifetime.ts

@@ -0,0 +1,5 @@
+/**
+ * Seconds a Pretext reader page may be served from a shared cache (Next sends `s-maxage` equal to its `revalidate`).
+ * Next needs a literal in each route's `export const revalidate`, so scripts/test-reader-cache-lifetime.ts keeps them equal to this.
+ */
+export const READER_PAGE_REVALIDATE_SECONDS = 60;

package/lib/reader-static-params.ts

@@ -1,4 +1,16 @@
+import type { ContentRepository, EditionContent } from "./content-types";
 import { graphqlContentRepository } from "./graphql-content-repository";
+import { SITE_BRAND } from "./site-brand";
+import { getContentSource } from "./site-env";
+import type { RendererConfig } from "./renderer-config";
+
+export function siteEnumeratesReaderRoutesAtBuild(): boolean {
+  return siteServesNextReaderRoutes() && getContentSource() !== "drafts";
+}
+
+export function siteServesNextReaderRoutes(rendererKind: RendererConfig["kind"] = SITE_BRAND.renderer.kind): boolean {
+  return rendererKind !== "markus";
+}
 
 const MONTH_NAMES = [
   "january",
@@ -21,10 +33,23 @@ type EditionDateStaticParam = {
   day: string;
 };
 
-export async function generateEditionDateStaticParams(): Promise<EditionDateStaticParam[]> {
-  if (process.env.NODE_ENV === "development") return [];
+const PUBLISHED_EDITION_ENUMERATION_LIMIT = 100;
+const DEEP_ROUTE_EDITION_LIMIT = 10;
+const RESERVED_DATE_CHILD_SEGMENTS = new Set(["page", "section"]);
+
+type EnumerationRepository = Pick<ContentRepository, "listPublishedEditions" | "loadEditionContent">;
 
-  const { editions } = await graphqlContentRepository.listPublishedEditions({ limit: 100 });
+function shouldEnumerateAtBuild(): boolean {
+  if (process.env.NODE_ENV === "development") return false;
+  return siteEnumeratesReaderRoutesAtBuild();
+}
+
+export async function generateEditionDateStaticParams(
+  repository: EnumerationRepository = graphqlContentRepository,
+): Promise<EditionDateStaticParam[]> {
+  if (!shouldEnumerateAtBuild()) return [];
+
+  const { editions } = await repository.listPublishedEditions({ limit: PUBLISHED_EDITION_ENUMERATION_LIMIT });
   const params: EditionDateStaticParam[] = [];
   for (const edition of editions) {
     const route = editionDateToStaticParam(edition.editionDate);
@@ -33,8 +58,64 @@ export async function generateEditionDateStaticParams(): Promise<EditionDateStat
   return params;
 }
 
+async function loadRecentEditionContents(repository: EnumerationRepository): Promise<EditionContent[]> {
+  const { editions } = await repository.listPublishedEditions({ limit: PUBLISHED_EDITION_ENUMERATION_LIMIT });
+  const recent = [...editions]
+    .sort((left, right) => right.editionDate.localeCompare(left.editionDate))
+    .slice(0, DEEP_ROUTE_EDITION_LIMIT);
+  return Promise.all(recent.map((edition) => repository.loadEditionContent({ editionDate: edition.editionDate })));
+}
+
+export async function generateEditionItemStaticParams(
+  repository: EnumerationRepository = graphqlContentRepository,
+): Promise<Array<EditionDateStaticParam & { articleSlug: string }>> {
+  if (!shouldEnumerateAtBuild()) return [];
+
+  const params: Array<EditionDateStaticParam & { articleSlug: string }> = [];
+  for (const content of await loadRecentEditionContents(repository)) {
+    const date = editionDateToStaticParam(content.editionDate);
+    if (!date) continue;
+    for (const item of content.items) {
+      if (RESERVED_DATE_CHILD_SEGMENTS.has(item.slug.toLowerCase())) continue;
+      params.push({ ...date, articleSlug: item.slug });
+    }
+  }
+  return params;
+}
+
+export async function generateEditionPageStaticParams(
+  repository: EnumerationRepository = graphqlContentRepository,
+): Promise<Array<EditionDateStaticParam & { pageNumber: string }>> {
+  if (!shouldEnumerateAtBuild()) return [];
+
+  const params: Array<EditionDateStaticParam & { pageNumber: string }> = [];
+  for (const content of await loadRecentEditionContents(repository)) {
+    const date = editionDateToStaticParam(content.editionDate);
+    if (!date) continue;
+    for (let pageNumber = 2; pageNumber <= content.layoutPlan.pages.length; pageNumber += 1) {
+      params.push({ ...date, pageNumber: String(pageNumber) });
+    }
+  }
+  return params;
+}
+
+export async function generateEditionSectionStaticParams(
+  repository: EnumerationRepository = graphqlContentRepository,
+): Promise<Array<EditionDateStaticParam & { sectionKey: string }>> {
+  if (!shouldEnumerateAtBuild()) return [];
+
+  const params: Array<EditionDateStaticParam & { sectionKey: string }> = [];
+  for (const content of await loadRecentEditionContents(repository)) {
+    const date = editionDateToStaticParam(content.editionDate);
+    if (!date) continue;
+    for (const section of content.sections) params.push({ ...date, sectionKey: section.key });
+  }
+  return params;
+}
+
 export async function generateArticleStaticParams(): Promise<Array<{ slug: string }>> {
   if (process.env.NODE_ENV === "development") return [];
+  if (!siteEnumeratesReaderRoutesAtBuild()) return [];
 
   const slugs = await graphqlContentRepository.listArticleSlugs();
   return slugs.map((slug) => ({ slug }));
@@ -51,6 +132,6 @@ function editionDateToStaticParam(editionDate: string): EditionDateStaticParam |
   return {
     year: match[1],
     month: monthName,
-    day: String(Number(match[3])),
+    day: match[3],
   };
 }

package/lib/reader-storage-url.ts

@@ -1,5 +1,5 @@
 import { getUrl } from "aws-amplify/storage/server";
-import { getAmplifyServerRuntime } from "./amplify-server-runtime";
+import { runWithGuestAmplifyContext } from "./amplify-server-runtime";
 
 const STORAGE_URL_EXPIRES_IN_SECONDS = 60 * 60;
 const STORAGE_URL_CACHE_TTL_MS = 55 * 60 * 1000;
@@ -43,17 +43,14 @@ export async function signStorageUrl(storagePath: string): Promise<string> {
     return cached.url;
   }
 
-  const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
-  const result = await runWithAmplifyServerContext({
-    nextServerContext: null,
-    operation: (contextSpec) =>
-      getUrl(contextSpec, {
-        path: normalized,
-        options: {
-          expiresIn: STORAGE_URL_EXPIRES_IN_SECONDS,
-        },
-      }),
-  });
+  const result = await runWithGuestAmplifyContext((contextSpec) =>
+    getUrl(contextSpec, {
+      path: normalized,
+      options: {
+        expiresIn: STORAGE_URL_EXPIRES_IN_SECONDS,
+      },
+    }),
+  );
   const url = result.url.toString();
   signedUrlCache.set(normalized, {
     expiresAt: Date.now() + STORAGE_URL_CACHE_TTL_MS,

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/renderer.ts

@@ -4,6 +4,7 @@ import type { EditionContent } from "./content-types";
 import type { PretextLayout } from "./renderer-config";
 import type { PresentationFooterEntry } from "./presentation-footer";
 import type { PublicationItem } from "./publication-items";
+import type { VideoScriptRef } from "./video-script";
 
 /**
  * Renderer is the swappable render pipeline that turns standard content
@@ -36,6 +37,8 @@ export type RenderEditionProps = {
 export type ArticlePageEditionFooter = {
   editionBasePath: string;
   entries: PresentationFooterEntry[];
+  /** Section links for the rhythm blog layout's page header. Ignored by the classic layout. */
+  sections?: Array<{ key: string; label: string }>;
   subtitle: string;
   title?: string;
 };
@@ -46,6 +49,8 @@ export type RenderArticleProps = {
   backLabel?: string;
   editionFooter?: ArticlePageEditionFooter;
   editionDate?: string;
+  /** VideoML script for the preview player. */
+  videoScript?: VideoScriptRef | null;
 };
 
 export type RenderItemProps = {
@@ -54,6 +59,8 @@ export type RenderItemProps = {
   backLabel?: string;
   editionFooter?: ArticlePageEditionFooter;
   editionDate?: string;
+  /** VideoML script for the preview player. */
+  videoScript?: VideoScriptRef | null;
 };
 
 /**

package/lib/revalidate-prewarm.ts

@@ -0,0 +1,53 @@
+export const PREWARM_ORIGIN_ENV = "PAPYRUS_PREWARM_ORIGIN";
+export const PREWARM_CONCURRENCY = 4;
+export const PREWARM_MAX_PATHS = 40;
+export const PREWARM_TIMEOUT_MILLISECONDS = 25_000;
+export const PREWARM_REQUEST_HEADER = "x-papyrus-prewarm";
+
+export type PrewarmFetch = (url: string, init: { headers: Record<string, string>; signal: AbortSignal; redirect: "manual" }) => Promise<{ status: number }>;
+
+export type PrewarmResult = {
+  path: string;
+  status: number | null;
+  milliseconds: number;
+};
+
+export function resolvePrewarmOrigin(requestUrl: string, environment: Record<string, string | undefined> = process.env): string {
+  const configured = environment[PREWARM_ORIGIN_ENV]?.trim();
+  if (configured) return configured.replace(/\/+$/, "");
+  return new URL(requestUrl).origin;
+}
+
+export async function prewarmPaths(
+  origin: string,
+  paths: string[],
+  options: { fetchPage?: PrewarmFetch; now?: () => number } = {},
+): Promise<PrewarmResult[]> {
+  const fetchPage = options.fetchPage ?? (fetch as unknown as PrewarmFetch);
+  const now = options.now ?? Date.now;
+  const queue = [...new Set(paths)].filter((path) => path.startsWith("/")).slice(0, PREWARM_MAX_PATHS);
+  const results: PrewarmResult[] = [];
+
+  async function worker(): Promise<void> {
+    for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
+      const startedAt = now();
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), PREWARM_TIMEOUT_MILLISECONDS);
+      try {
+        const response = await fetchPage(`${origin}${path}`, {
+          headers: { [PREWARM_REQUEST_HEADER]: "1" },
+          signal: controller.signal,
+          redirect: "manual",
+        });
+        results.push({ path, status: response.status, milliseconds: now() - startedAt });
+      } catch {
+        results.push({ path, status: null, milliseconds: now() - startedAt });
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(PREWARM_CONCURRENCY, queue.length) }, worker));
+  return results;
+}

package/lib/revalidate-secret.ts

@@ -0,0 +1,59 @@
+import { timingSafeEqual } from "node:crypto";
+import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+
+export const REVALIDATE_SECRET_PARAMETER_ENV = "PAPYRUS_REVALIDATE_SECRET_PARAMETER";
+export const REVALIDATE_SECRET_CACHE_MILLISECONDS = 5 * 60 * 1000;
+
+export type RevalidateSecretReader = (parameterName: string) => Promise<string | null>;
+
+type CachedSecret = { parameterName: string; value: string; expiresAt: number };
+
+let cachedSecret: CachedSecret | null = null;
+let defaultSsmClient: SSMClient | null = null;
+
+export function resetRevalidateSecretCache(): void {
+  cachedSecret = null;
+}
+
+async function readSecretFromSsm(parameterName: string): Promise<string | null> {
+  defaultSsmClient ??= new SSMClient({});
+  const response = await defaultSsmClient.send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+  const value = response.Parameter?.Value?.trim();
+  return value ? value : null;
+}
+
+export async function loadRevalidateSecret(
+  options: { environment?: Record<string, string | undefined>; readSecret?: RevalidateSecretReader; now?: number } = {},
+): Promise<string | null> {
+  const environment = options.environment ?? process.env;
+  const parameterName = environment[REVALIDATE_SECRET_PARAMETER_ENV]?.trim();
+  if (!parameterName) return null;
+  const now = options.now ?? Date.now();
+  if (cachedSecret && cachedSecret.parameterName === parameterName && cachedSecret.expiresAt > now) {
+    return cachedSecret.value;
+  }
+  try {
+    const value = (await (options.readSecret ?? readSecretFromSsm)(parameterName))?.trim();
+    if (!value) return null;
+    cachedSecret = { parameterName, value, expiresAt: now + REVALIDATE_SECRET_CACHE_MILLISECONDS };
+    return value;
+  } catch (error) {
+    console.error(`Revalidate secret parameter could not be read (${error instanceof Error ? error.name : "error"}).`);
+    return null;
+  }
+}
+
+export function secretsMatch(provided: string | null | undefined, expected: string): boolean {
+  const providedBytes = Buffer.from((provided ?? "").trim());
+  const expectedBytes = Buffer.from(expected);
+  return providedBytes.length === expectedBytes.length && timingSafeEqual(providedBytes, expectedBytes);
+}
+
+export async function isAuthorizedRevalidateRequest(
+  providedSecret: string | null | undefined,
+  options: Parameters<typeof loadRevalidateSecret>[0] = {},
+): Promise<boolean> {
+  const expected = await loadRevalidateSecret(options);
+  if (!expected) return false;
+  return secretsMatch(providedSecret, expected);
+}

package/lib/robots-policy.ts

@@ -0,0 +1,14 @@
+import type { MetadataRoute } from "next";
+import { getRootRoute, getSiteBrand } from "./site-brand";
+import { isIndexable } from "./site-env";
+
+const DISALLOW_ALL: MetadataRoute.Robots = { rules: { userAgent: "*", disallow: "/" } };
+const ALLOW_ALL: MetadataRoute.Robots = { rules: { userAgent: "*", allow: "/" } };
+
+export function buildRobots(
+  environment: Record<string, string | undefined> = process.env,
+  brand = getSiteBrand(),
+): MetadataRoute.Robots {
+  if (getRootRoute(brand).kind === "newsroom") return DISALLOW_ALL;
+  return isIndexable(environment) ? ALLOW_ALL : DISALLOW_ALL;
+}

package/lib/root-route-redirect.ts

@@ -0,0 +1,16 @@
+export type RootSearchParams = Record<string, string | string[] | undefined>;
+
+export function buildRootRedirectTarget(destination: string, searchParams: RootSearchParams | undefined): string {
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(searchParams ?? {})) {
+    if (Array.isArray(value)) {
+      for (const entry of value) query.append(name, entry);
+    } else if (value !== undefined) {
+      query.append(name, value);
+    }
+  }
+  const serialized = query.toString();
+  if (!serialized) return destination;
+  const separator = destination.includes("?") ? "&" : "?";
+  return `${destination}${separator}${serialized}`;
+}

package/lib/semantic-graph.ts

@@ -1,3 +1,4 @@
+import { toPublicNewsroomPath } from "./newsroom-base-path";
 import type {
   AssignmentRecord,
   CategorySteeringCategory,
@@ -31,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"
@@ -79,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"] },
@@ -175,6 +178,10 @@ export function predicateLabel(predicate: string, direction: "outgoing" | "incom
 }
 
 export function newsDeskHrefForSemanticObject(kind: string, lineageId: string): string {
+  return toPublicNewsroomPath(internalNewsDeskHrefForSemanticObject(kind, lineageId));
+}
+
+function internalNewsDeskHrefForSemanticObject(kind: string, lineageId: string): string {
   const encoded = encodeURIComponent(lineageId);
   if (kind === "reference") return `/newsroom/references/${encoded}`;
   if (kind === "category") return `/newsroom/topics?category=${encoded}`;