@anthusai/papyrus 5.19.1 → 5.20.0

package/amplify/plugins/reader-steering/papyrus.plugin.js

@@ -0,0 +1,139 @@
+import { ArnPrincipal, Effect, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Duration, Stack } from "aws-cdk-lib";
+import { Rule, RuleTargetInput, Schedule } from "aws-cdk-lib/aws-events";
+import { LambdaFunction as LambdaFunctionTarget } from "aws-cdk-lib/aws-events-targets";
+import { resolveReaderSteeringConfig } from "./config.js";
+import { readerActions } from "./function/resource.js";
+import { readerSteeringSchemaDefinitions } from "./schema.js";
+export { resolveReaderSteeringConfig };
+export const READER_STEERING_OUTPUT_KEY = "readerSteering";
+export const SNAPSHOT_SCHEDULE_PREFIX = "papyrus-reader-snapshot-";
+export const READER_SNAPSHOT_TASK = { projectionTask: { task: "reader-snapshot" } };
+export const READER_SCHEDULED_SNAPSHOT_TASK = { projectionTask: { task: "reader-snapshot", retirementPoll: true } };
+export const READER_POLL_SECRET_PARAMETER_ENV = "PAPYRUS_READER_POLL_SECRET_PARAMETER";
+export const readerSteeringManifest = {
+    name: "reader-steering",
+    contract: 1,
+    models: ["ReaderProfile", "ReaderHandle", "ReaderVote"],
+    mutations: [],
+    guest: { mutations: [] },
+    newsroomPanels: [],
+    staticAssets: ["_plugins/papyrus-reader@1.js", "_plugins/papyrus-reader@1.css"],
+};
+/** What the reader-actions function reads from `PAPYRUS_READER_SETTINGS`. */
+export function readerActionsSettings(config, allowInterimSubjects) {
+    return {
+        dimensions: config.dimensions,
+        limits: config.limits,
+        reservedHandles: config.reservedHandles,
+        allowInterimSubjects,
+        snapshotDebounceSeconds: 60,
+    };
+}
+/** What the `reader-snapshot` projection task reads from `PAPYRUS_READER_SNAPSHOT_SETTINGS`. */
+export function readerSnapshotSettings(config) {
+    return {
+        dimensions: config.dimensions,
+        karma: config.karma,
+        ranking: config.ranking,
+        hypeMinimum: config.snapshot.hypeMinimum,
+        ...(config.hypeGap ? { hypeGap: config.hypeGap } : {}),
+        retirementPoll: config.retirementPoll,
+    };
+}
+export function interimSubjectsAllowedAtSynth(environment = process.env) {
+    return ["development", "test"].includes((environment.SITE_ENV ?? "").trim()) && environment.NODE_ENV !== "production";
+}
+/**
+ * The scheduled run polls Prospectus through the CMS route /api/reader/retired (docs/reader-steering.md), so it needs the
+ * site origin and the poll secret parameter that the app-shell stack generates (`cms.readerRetirementPoll`); both reach the
+ * backend build as branch variables. It also deletes and re-keys rows, and keeps its cursor in the rate table.
+ */
+function wireRetirementPoll(readerLambda, contentActions, tables) {
+    const origin = (process.env.PAPYRUS_SITE_ORIGIN ?? "").trim();
+    const parameterName = (process.env[READER_POLL_SECRET_PARAMETER_ENV] ?? "").trim();
+    if (!origin.startsWith("https://") || !parameterName.startsWith("/")) {
+        throw new Error("reader-steering retirementPoll needs PAPYRUS_SITE_ORIGIN (an https origin) and PAPYRUS_READER_POLL_SECRET_PARAMETER (an SSM parameter name). The app-shell template sets both on the production branch when site.json has cms.readerRetirementPoll: true; see docs/reader-steering.md.");
+    }
+    const rateTable = readerLambda.node.scope?.node.tryFindChild("PapyrusReaderRateWindows");
+    if (!rateTable)
+        throw new Error("reader-steering retirementPoll could not find the reader-actions rate table to keep its cursor in");
+    tables.ReaderVote.grantReadWriteData(contentActions);
+    tables.ReaderHandle.grantReadWriteData(contentActions);
+    rateTable.grantReadWriteData(contentActions);
+    contentActions.addEnvironment("PAPYRUS_READER_RATE_TABLE", rateTable.tableName);
+    contentActions.addEnvironment("PAPYRUS_READER_POLL_URL", origin);
+    contentActions.addEnvironment(READER_POLL_SECRET_PARAMETER_ENV, parameterName);
+    const stack = Stack.of(contentActions);
+    contentActions.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["ssm:GetParameter"],
+        resources: [`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${parameterName}`],
+    }));
+}
+export const readerSteeringPlugin = {
+    manifest: readerSteeringManifest,
+    resolveConfig: resolveReaderSteeringConfig,
+    functions: () => ({ readerActions }),
+    schemaDefinitions: readerSteeringSchemaDefinitions,
+    publicSettings: (config) => ({ contract: readerSteeringManifest.contract, dimensions: config.dimensions }),
+    wire(backend, config, context) {
+        const lambda = backend.readerActions.resources.lambda;
+        const tables = backend.data.resources.tables;
+        const contentActions = context.contentActionsLambda;
+        for (const [variable, model] of [
+            ["PAPYRUS_READER_PROFILE_TABLE", "ReaderProfile"],
+            ["PAPYRUS_READER_HANDLE_TABLE", "ReaderHandle"],
+            ["PAPYRUS_READER_VOTE_TABLE", "ReaderVote"],
+        ]) {
+            tables[model].grantReadWriteData(lambda);
+            lambda.addEnvironment(variable, tables[model].tableName);
+            contentActions.addEnvironment(variable, tables[model].tableName);
+        }
+        tables.PublishedItem.grantReadData(lambda);
+        lambda.addEnvironment("PAPYRUS_READER_PUBLISHED_ITEM_TABLE", tables.PublishedItem.tableName);
+        tables.ReaderVote.grantReadData(contentActions);
+        tables.ReaderProfile.grantReadWriteData(contentActions);
+        lambda.addEnvironment("PAPYRUS_READER_SETTINGS", JSON.stringify(readerActionsSettings(config, interimSubjectsAllowedAtSynth())));
+        if (config.reservedConcurrency !== undefined) {
+            lambda.node.defaultChild.addPropertyOverride("ReservedConcurrentExecutions", config.reservedConcurrency);
+        }
+        // Trailing-edge debounce: the first write in a window creates a one-off EventBridge Scheduler schedule at the end of
+        // the window (docs/reader-steering.md). The schedule invokes content-actions as this role; reader-actions may create
+        // schedules named for this feature, and pass exactly this role.
+        const schedulerRole = new Role(Stack.of(lambda), "ReaderSnapshotSchedulerRole", {
+            assumedBy: new ServicePrincipal("scheduler.amazonaws.com"),
+            description: "Lets one-off schedules created by reader-actions invoke the reader-snapshot run.",
+        });
+        contentActions.grantInvoke(schedulerRole);
+        const stack = Stack.of(lambda); // the role lives with the function, so the stacks keep their existing one-way dependency
+        lambda.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["scheduler:CreateSchedule"],
+            resources: [`arn:${stack.partition}:scheduler:${stack.region}:${stack.account}:schedule/default/${SNAPSHOT_SCHEDULE_PREFIX}*`],
+        }));
+        lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["iam:PassRole"], resources: [schedulerRole.roleArn] }));
+        lambda.addEnvironment("PAPYRUS_READER_SNAPSHOT_FUNCTION_ARN", contentActions.functionArn);
+        lambda.addEnvironment("PAPYRUS_READER_SCHEDULER_ROLE_ARN", schedulerRole.roleArn);
+        contentActions.addEnvironment("PAPYRUS_READER_SNAPSHOT_SETTINGS", JSON.stringify(readerSnapshotSettings(config)));
+        lambda.addPermission("InvokeFromCmsCompute", {
+            principal: new ArnPrincipal(config.computeRoleArn),
+            action: "lambda:InvokeFunction",
+        });
+        if (config.retirementPoll)
+            wireRetirementPoll(lambda, contentActions, tables);
+        if (config.snapshot.schedule) {
+            new Rule(context.createStack("reader-steering-schedule"), "ReaderSnapshotSchedule", {
+                description: "Rebuilds the reader snapshot (time decay, Rising) and, when enabled, applies Prospectus subject retirements.",
+                schedule: Schedule.rate(Duration.hours(config.snapshot.intervalHours)),
+                targets: [
+                    new LambdaFunctionTarget(contentActions, {
+                        event: RuleTargetInput.fromObject(config.retirementPoll ? READER_SCHEDULED_SNAPSHOT_TASK : READER_SNAPSHOT_TASK),
+                        retryAttempts: 0,
+                    }),
+                ],
+            });
+        }
+        backend.addOutput({ custom: { [READER_STEERING_OUTPUT_KEY]: { actionsFunction: lambda.functionName } } });
+    },
+};

package/amplify/plugins/reader-steering/papyrus.plugin.ts

@@ -0,0 +1,162 @@
+import { ArnPrincipal, Effect, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Duration, Stack } from "aws-cdk-lib";
+import type { ITable } from "aws-cdk-lib/aws-dynamodb";
+import { Rule, RuleTargetInput, Schedule } from "aws-cdk-lib/aws-events";
+import { LambdaFunction as LambdaFunctionTarget } from "aws-cdk-lib/aws-events-targets";
+import { CfnFunction, type Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+import type { PapyrusPlugin, PluginManifest, PluginWiringContext } from "../types";
+import { resolveReaderSteeringConfig, type ReaderSteeringConfig } from "./config";
+import { readerActions } from "./function/resource";
+import { readerSteeringSchemaDefinitions } from "./schema";
+
+export { resolveReaderSteeringConfig };
+export type { ReaderSteeringConfig };
+
+export const READER_STEERING_OUTPUT_KEY = "readerSteering";
+export const SNAPSHOT_SCHEDULE_PREFIX = "papyrus-reader-snapshot-";
+export const READER_SNAPSHOT_TASK = { projectionTask: { task: "reader-snapshot" } };
+export const READER_SCHEDULED_SNAPSHOT_TASK = { projectionTask: { task: "reader-snapshot", retirementPoll: true } };
+export const READER_POLL_SECRET_PARAMETER_ENV = "PAPYRUS_READER_POLL_SECRET_PARAMETER";
+
+export const readerSteeringManifest: PluginManifest = {
+  name: "reader-steering",
+  contract: 1,
+  models: ["ReaderProfile", "ReaderHandle", "ReaderVote"],
+  mutations: [],
+  guest: { mutations: [] },
+  newsroomPanels: [],
+  staticAssets: ["_plugins/papyrus-reader@1.js", "_plugins/papyrus-reader@1.css"],
+};
+
+/** What the reader-actions function reads from `PAPYRUS_READER_SETTINGS`. */
+export function readerActionsSettings(config: ReaderSteeringConfig, allowInterimSubjects: boolean) {
+  return {
+    dimensions: config.dimensions,
+    limits: config.limits,
+    reservedHandles: config.reservedHandles,
+    allowInterimSubjects,
+    snapshotDebounceSeconds: 60,
+  };
+}
+
+/** What the `reader-snapshot` projection task reads from `PAPYRUS_READER_SNAPSHOT_SETTINGS`. */
+export function readerSnapshotSettings(config: ReaderSteeringConfig) {
+  return {
+    dimensions: config.dimensions,
+    karma: config.karma,
+    ranking: config.ranking,
+    hypeMinimum: config.snapshot.hypeMinimum,
+    ...(config.hypeGap ? { hypeGap: config.hypeGap } : {}),
+    retirementPoll: config.retirementPoll,
+  };
+}
+
+export function interimSubjectsAllowedAtSynth(environment: Record<string, string | undefined> = process.env): boolean {
+  return ["development", "test"].includes((environment.SITE_ENV ?? "").trim()) && environment.NODE_ENV !== "production";
+}
+
+/**
+ * The scheduled run polls Prospectus through the CMS route /api/reader/retired (docs/reader-steering.md), so it needs the
+ * site origin and the poll secret parameter that the app-shell stack generates (`cms.readerRetirementPoll`); both reach the
+ * backend build as branch variables. It also deletes and re-keys rows, and keeps its cursor in the rate table.
+ */
+function wireRetirementPoll(readerLambda: LambdaFunction, contentActions: LambdaFunction, tables: Record<string, ITable>) {
+  const origin = (process.env.PAPYRUS_SITE_ORIGIN ?? "").trim();
+  const parameterName = (process.env[READER_POLL_SECRET_PARAMETER_ENV] ?? "").trim();
+  if (!origin.startsWith("https://") || !parameterName.startsWith("/")) {
+    throw new Error(
+      "reader-steering retirementPoll needs PAPYRUS_SITE_ORIGIN (an https origin) and PAPYRUS_READER_POLL_SECRET_PARAMETER (an SSM parameter name). The app-shell template sets both on the production branch when site.json has cms.readerRetirementPoll: true; see docs/reader-steering.md.",
+    );
+  }
+  const rateTable = readerLambda.node.scope?.node.tryFindChild("PapyrusReaderRateWindows") as ITable | undefined;
+  if (!rateTable) throw new Error("reader-steering retirementPoll could not find the reader-actions rate table to keep its cursor in");
+  tables.ReaderVote.grantReadWriteData(contentActions);
+  tables.ReaderHandle.grantReadWriteData(contentActions);
+  rateTable.grantReadWriteData(contentActions);
+  contentActions.addEnvironment("PAPYRUS_READER_RATE_TABLE", rateTable.tableName);
+  contentActions.addEnvironment("PAPYRUS_READER_POLL_URL", origin);
+  contentActions.addEnvironment(READER_POLL_SECRET_PARAMETER_ENV, parameterName);
+  const stack = Stack.of(contentActions);
+  contentActions.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["ssm:GetParameter"],
+      resources: [`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${parameterName}`],
+    }),
+  );
+}
+
+export const readerSteeringPlugin: PapyrusPlugin<ReaderSteeringConfig, { readerActions: typeof readerActions }> = {
+  manifest: readerSteeringManifest,
+  resolveConfig: resolveReaderSteeringConfig,
+  functions: () => ({ readerActions }),
+  schemaDefinitions: readerSteeringSchemaDefinitions,
+  publicSettings: (config) => ({ contract: readerSteeringManifest.contract, dimensions: config.dimensions }),
+  wire(backend, config, context: PluginWiringContext) {
+    const lambda = backend.readerActions.resources.lambda as LambdaFunction;
+    const tables = backend.data.resources.tables as Record<string, ITable>;
+    const contentActions = context.contentActionsLambda;
+
+    for (const [variable, model] of [
+      ["PAPYRUS_READER_PROFILE_TABLE", "ReaderProfile"],
+      ["PAPYRUS_READER_HANDLE_TABLE", "ReaderHandle"],
+      ["PAPYRUS_READER_VOTE_TABLE", "ReaderVote"],
+    ] as const) {
+      tables[model].grantReadWriteData(lambda);
+      lambda.addEnvironment(variable, tables[model].tableName);
+      contentActions.addEnvironment(variable, tables[model].tableName);
+    }
+    tables.PublishedItem.grantReadData(lambda);
+    lambda.addEnvironment("PAPYRUS_READER_PUBLISHED_ITEM_TABLE", tables.PublishedItem.tableName);
+    tables.ReaderVote.grantReadData(contentActions);
+    tables.ReaderProfile.grantReadWriteData(contentActions);
+
+    lambda.addEnvironment("PAPYRUS_READER_SETTINGS", JSON.stringify(readerActionsSettings(config, interimSubjectsAllowedAtSynth())));
+    if (config.reservedConcurrency !== undefined) {
+      (lambda.node.defaultChild as CfnFunction).addPropertyOverride("ReservedConcurrentExecutions", config.reservedConcurrency);
+    }
+
+    // Trailing-edge debounce: the first write in a window creates a one-off EventBridge Scheduler schedule at the end of
+    // the window (docs/reader-steering.md). The schedule invokes content-actions as this role; reader-actions may create
+    // schedules named for this feature, and pass exactly this role.
+    const schedulerRole = new Role(Stack.of(lambda), "ReaderSnapshotSchedulerRole", {
+      assumedBy: new ServicePrincipal("scheduler.amazonaws.com"),
+      description: "Lets one-off schedules created by reader-actions invoke the reader-snapshot run.",
+    });
+    contentActions.grantInvoke(schedulerRole);
+    const stack = Stack.of(lambda); // the role lives with the function, so the stacks keep their existing one-way dependency
+    lambda.addToRolePolicy(
+      new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["scheduler:CreateSchedule"],
+        resources: [`arn:${stack.partition}:scheduler:${stack.region}:${stack.account}:schedule/default/${SNAPSHOT_SCHEDULE_PREFIX}*`],
+      }),
+    );
+    lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["iam:PassRole"], resources: [schedulerRole.roleArn] }));
+    lambda.addEnvironment("PAPYRUS_READER_SNAPSHOT_FUNCTION_ARN", contentActions.functionArn);
+    lambda.addEnvironment("PAPYRUS_READER_SCHEDULER_ROLE_ARN", schedulerRole.roleArn);
+    contentActions.addEnvironment("PAPYRUS_READER_SNAPSHOT_SETTINGS", JSON.stringify(readerSnapshotSettings(config)));
+
+    lambda.addPermission("InvokeFromCmsCompute", {
+      principal: new ArnPrincipal(config.computeRoleArn),
+      action: "lambda:InvokeFunction",
+    });
+
+    if (config.retirementPoll) wireRetirementPoll(lambda, contentActions, tables);
+
+    if (config.snapshot.schedule) {
+      new Rule(context.createStack("reader-steering-schedule"), "ReaderSnapshotSchedule", {
+        description: "Rebuilds the reader snapshot (time decay, Rising) and, when enabled, applies Prospectus subject retirements.",
+        schedule: Schedule.rate(Duration.hours(config.snapshot.intervalHours)),
+        targets: [
+          new LambdaFunctionTarget(contentActions, {
+            event: RuleTargetInput.fromObject(config.retirementPoll ? READER_SCHEDULED_SNAPSHOT_TASK : READER_SNAPSHOT_TASK),
+            retryAttempts: 0,
+          }),
+        ],
+      });
+    }
+
+    backend.addOutput({ custom: { [READER_STEERING_OUTPUT_KEY]: { actionsFunction: lambda.functionName } } });
+  },
+};

package/amplify/plugins/reader-steering/schema.js

@@ -0,0 +1,40 @@
+import { a } from "@aws-amplify/backend";
+/**
+ * Staff and IAM only: no guest, API key or reader rule on any model. The reader-actions function writes the
+ * tables directly with its own role, and editors may list them; admins may delete. `id` is the lookup key:
+ * the siteSubject for a profile, the lowercase handle for a claim and `subjectKey#readerId#dimension` for a vote.
+ */
+const staffOnly = (allow) => [allow.group("editor").to(["read"]), allow.group("admin").to(["read", "delete"])];
+export function readerSteeringSchemaDefinitions() {
+    return {
+        ReaderProfile: a
+            .model({
+            id: a.id().required(),
+            siteSubject: a.string().required(),
+            readerId: a.string().required(),
+            handle: a.string(),
+            state: a.string().required(),
+            karma: a.integer(),
+        })
+            .disableOperations(["subscriptions"])
+            .authorization(staffOnly),
+        ReaderHandle: a
+            .model({
+            id: a.id().required(),
+            readerId: a.string().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .authorization(staffOnly),
+        ReaderVote: a
+            .model({
+            id: a.id().required(),
+            subjectKey: a.string().required(),
+            readerId: a.string().required(),
+            dimension: a.string().required(),
+            value: a.integer().required(),
+            voterRole: a.string().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .authorization(staffOnly),
+    };
+}

package/amplify/plugins/reader-steering/schema.ts

@@ -0,0 +1,42 @@
+import { a } from "@aws-amplify/backend";
+
+/**
+ * Staff and IAM only: no guest, API key or reader rule on any model. The reader-actions function writes the
+ * tables directly with its own role, and editors may list them; admins may delete. `id` is the lookup key:
+ * the siteSubject for a profile, the lowercase handle for a claim and `subjectKey#readerId#dimension` for a vote.
+ */
+const staffOnly = (allow: any) => [allow.group("editor").to(["read"]), allow.group("admin").to(["read", "delete"])];
+
+export function readerSteeringSchemaDefinitions() {
+  return {
+    ReaderProfile: a
+      .model({
+        id: a.id().required(),
+        siteSubject: a.string().required(),
+        readerId: a.string().required(),
+        handle: a.string(),
+        state: a.string().required(),
+        karma: a.integer(),
+      })
+      .disableOperations(["subscriptions"])
+      .authorization(staffOnly),
+    ReaderHandle: a
+      .model({
+        id: a.id().required(),
+        readerId: a.string().required(),
+      })
+      .disableOperations(["subscriptions"])
+      .authorization(staffOnly),
+    ReaderVote: a
+      .model({
+        id: a.id().required(),
+        subjectKey: a.string().required(),
+        readerId: a.string().required(),
+        dimension: a.string().required(),
+        value: a.integer().required(),
+        voterRole: a.string().required(),
+      })
+      .disableOperations(["subscriptions"])
+      .authorization(staffOnly),
+  };
+}

package/amplify/plugins/registry.js

@@ -1,6 +1,8 @@
+import { readerSteeringPlugin } from "./reader-steering/papyrus.plugin.js";
 import { signupPlugin } from "./signup/papyrus.plugin.js";
 /** Plugins are packaged with Papyrus and pinned by its version: there is no registry to fetch from. */
 export const KNOWN_PLUGINS = {
+    "reader-steering": readerSteeringPlugin,
     signup: signupPlugin,
 };
 export function resolvePlugins(requests) {

package/amplify/plugins/registry.ts

@@ -1,8 +1,10 @@
 import type { PapyrusPlugin, PluginRequest } from "./types";
+import { readerSteeringPlugin } from "./reader-steering/papyrus.plugin";
 import { signupPlugin } from "./signup/papyrus.plugin";
 
 /** Plugins are packaged with Papyrus and pinned by its version: there is no registry to fetch from. */
 export const KNOWN_PLUGINS: Record<string, PapyrusPlugin<any, any>> = {
+  "reader-steering": readerSteeringPlugin,
   signup: signupPlugin,
 };
 

package/amplify/plugins/types.ts

@@ -1,3 +1,4 @@
+import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
 import type { Construct } from "constructs";
 
 /** How a site asks for a plugin in `papyrus.config.ts`: `plugins: ["signup"]` or `plugins: [{ name: "signup", forms: ["news"] }]`. */
@@ -22,6 +23,8 @@ export type PluginWiringContext = {
   createStack: (name: string) => Construct;
   graphqlApiId: string;
   graphqlEndpoint: string;
+  /** The site's `content-actions` function: it runs the projection tasks a plugin may add (for example `reader-snapshot`). */
+  contentActionsLambda: LambdaFunction;
 };
 
 export type PapyrusPlugin<Config, Functions = unknown> = {

package/amplify/plugins/wire.js

@@ -12,6 +12,7 @@ export function wirePlugins(backend, plugins, contentActionsLambda) {
         createStack: (name) => backend.createStack(name),
         graphqlApiId: graphqlApi.apiId,
         graphqlEndpoint: backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl,
+        contentActionsLambda,
     };
     for (const { plugin, config } of plugins)
         plugin.wire(backend, config, context);

package/amplify/plugins/wire.ts

@@ -15,6 +15,7 @@ export function wirePlugins(backend: any, plugins: ResolvedPlugin[], contentActi
     createStack: (name: string) => backend.createStack(name),
     graphqlApiId: graphqlApi.apiId as string,
     graphqlEndpoint: backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl as string,
+    contentActionsLambda,
   };
   for (const { plugin, config } of plugins) plugin.wire(backend, config, context);
   contentActionsLambda.addEnvironment(PLUGINS_ENVIRONMENT_VARIABLE, plugins.map(({ plugin }) => plugin.manifest.name).join(","));

package/app/api/reader/handle/route.ts

@@ -0,0 +1,9 @@
+import type { NextRequest } from "next/server";
+import { handleReaderRequest } from "../../../../lib/reader-api";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export function POST(request: NextRequest) {
+  return handleReaderRequest(request, "handle");
+}

package/app/api/reader/me/route.ts

@@ -0,0 +1,9 @@
+import type { NextRequest } from "next/server";
+import { handleReaderRequest } from "../../../../lib/reader-api";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export function GET(request: NextRequest) {
+  return handleReaderRequest(request, "me");
+}

package/app/api/reader/rating/route.ts

@@ -0,0 +1,9 @@
+import type { NextRequest } from "next/server";
+import { handleReaderRequest } from "../../../../lib/reader-api";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export function POST(request: NextRequest) {
+  return handleReaderRequest(request, "rating");
+}

package/app/api/reader/retired/route.ts

@@ -0,0 +1,9 @@
+import type { NextRequest } from "next/server";
+import { handleReaderRetiredSubjects } from "../../../../lib/reader-retirement-route";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export function GET(request: NextRequest) {
+  return handleReaderRetiredSubjects(request);
+}

package/app/api/reader/vote/route.ts

@@ -0,0 +1,9 @@
+import type { NextRequest } from "next/server";
+import { handleReaderRequest } from "../../../../lib/reader-api";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export function POST(request: NextRequest) {
+  return handleReaderRequest(request, "vote");
+}

package/components/reference-cyclotron-priming.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useId, useRef, useState, type KeyboardEvent } from "react";
 import { primingStateText, type PrimingRequestView } from "../lib/relevance-status";
 
 export type PrimingFormInput = { url: string; label: string; explanation: string };
@@ -23,6 +23,19 @@ export function ReferenceCyclotronPriming({
   const [explanation, setExplanation] = useState("");
   const [message, setMessage] = useState<string | null>(null);
 
+  const ratingLabelId = useId();
+  const buttons = useRef<Array<HTMLButtonElement | null>>([]);
+
+  function moveSelection(event: KeyboardEvent<HTMLButtonElement>, index: number) {
+    const forward = event.key === "ArrowRight" || event.key === "ArrowDown";
+    const backward = event.key === "ArrowLeft" || event.key === "ArrowUp";
+    if (!forward && !backward) return;
+    event.preventDefault();
+    const next = (index + (forward ? 1 : -1) + labels.length) % labels.length;
+    setLabel(labels[next]);
+    buttons.current[next]?.focus();
+  }
+
   async function submit() {
     setMessage("Adding…");
     try {
@@ -38,13 +51,13 @@ export function ReferenceCyclotronPriming({
   return (
     <div className="space-y-2 text-sm" data-reference-cyclotron-priming>
       <form
-        className="flex flex-wrap items-end gap-3"
+        className="flex flex-col gap-3"
         onSubmit={(event) => {
           event.preventDefault();
           void submit();
         }}
       >
-        <label className="flex min-w-64 flex-1 flex-col gap-1">
+        <label className="flex flex-col gap-1">
           <span className="text-xs text-muted-foreground">Web page address</span>
           <input
             aria-label="Reference URL"
@@ -55,20 +68,46 @@ export function ReferenceCyclotronPriming({
             value={url}
           />
         </label>
+        <div className="flex flex-col gap-1">
+          <span className="text-xs text-muted-foreground" id={ratingLabelId}>Should Papyrus include or exclude pages like this?</span>
+          <div aria-labelledby={ratingLabelId} className="flex flex-wrap gap-2" role="radiogroup">
+            {labels.map((choice, index) => {
+              const checked = choice === label;
+              return (
+                <button
+                  aria-checked={checked}
+                  className={`min-w-32 flex-1 rounded border px-4 py-3 text-base font-semibold capitalize ${checked ? "border-foreground bg-foreground text-background" : "border-border bg-transparent"}`}
+                  data-rating-choice={choice}
+                  key={choice}
+                  onClick={() => setLabel(choice)}
+                  onKeyDown={(event) => moveSelection(event, index)}
+                  ref={(node) => { buttons.current[index] = node; }}
+                  role="radio"
+                  tabIndex={checked || (!labels.includes(label) && index === 0) ? 0 : -1}
+                  type="button"
+                >
+                  {choice}
+                </button>
+              );
+            })}
+          </div>
+        </div>
         <label className="flex flex-col gap-1">
-          <span className="text-xs text-muted-foreground">Include or exclude</span>
-          <select aria-label="Include or exclude" onChange={(event) => setLabel(event.target.value)} value={label}>
-            {labels.map((choice) => (
-              <option key={choice} value={choice}>{choice}</option>
-            ))}
-          </select>
-        </label>
-        <label className="flex min-w-48 flex-1 flex-col gap-1">
-          <span className="text-xs text-muted-foreground">Why (optional)</span>
-          <input aria-label="Reason" onChange={(event) => setExplanation(event.target.value)} type="text" value={explanation} />
+          <span className="text-sm font-medium">Why?</span>
+          <textarea
+            aria-label="Reason"
+            className="w-full"
+            onChange={(event) => setExplanation(event.target.value)}
+            placeholder="Why? A sentence or two helps Papyrus learn what you want."
+            rows={4}
+            value={explanation}
+          />
+          <span className="text-xs text-muted-foreground">Optional, but a short reason helps Papyrus learn what you want.</span>
         </label>
-        <button className="cyclotron-review-secondary" type="submit">Add reference</button>
-        {message ? <p className="basis-full text-xs" role="status">{message}</p> : null}
+        <div>
+          <button className="cyclotron-review-secondary" type="submit">Add reference</button>
+        </div>
+        {message ? <p className="text-xs" role="status">{message}</p> : null}
       </form>
       {requests.length ? (
         <ul aria-label="Added references" className="space-y-1 text-xs text-muted-foreground">

package/infra/amplify-app-shell.js

@@ -4,7 +4,7 @@ import * as amplify from "aws-cdk-lib/aws-amplify";
 import { SecureStringParameter } from "./secure-string-parameter.js";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider.js";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs.js";
-import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
+import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
 function environmentVariables(variables) {
     return Object.entries(variables).map(([name, value]) => ({ name, value }));
 }
@@ -123,6 +123,20 @@ export class AmplifyAppShellStack extends Stack {
                 resources: [prospectusSessionSealing.parameterArn],
             }));
         }
+        if (prospectusAccountsApiStageArn && config.cms.readerRetirementPoll) {
+            // Prospectus admits one caller per site, this compute role, so the scheduled snapshot run reaches the retired-subject
+            // route through the CMS route /api/reader/retired, which it authenticates with this secret.
+            const readerPollSecret = new SecureStringParameter(this, "ReaderPollSecretParameter", {
+                parameterName: resolveReaderPollSecretParameterName(config),
+                description: `Authorizes the scheduled reader snapshot run to call the retired-subject route of ${cmsAppName}`,
+            });
+            prospectusEnvironment.PAPYRUS_READER_POLL_SECRET_PARAMETER = readerPollSecret.parameterName;
+            computeRole.addToPolicy(new iam.PolicyStatement({
+                sid: "ReadReaderPollSecret",
+                actions: ["ssm:GetParameter"],
+                resources: [readerPollSecret.parameterArn],
+            }));
+        }
         if (prospectusAccountsApiStageArn) {
             computeRole.addToPolicy(new iam.PolicyStatement({
                 sid: "InvokeProspectusAccountsAsRegisteredSite",