@anthusai/papyrus 2.0.0-next.11 → 2.0.0-next.110

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

@@ -0,0 +1,187 @@
+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", "ReaderFlag", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction", "Proposal"],
+    mutations: ["moderateReader", "fileProposal", "transitionProposal", "editProposal"],
+    queries: ["listStoryDrafts"],
+    guest: { mutations: [] },
+    newsroomPanels: [{ id: "moderation", label: "Moderation" }],
+    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,
+        submissions: config.submissions,
+        subjects: config.subjects,
+        comments: config.comments,
+        moderation: config.moderation,
+        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,
+        submissions: config.submissions,
+        subjects: config.subjects,
+        karma: config.karma,
+        ranking: config.ranking,
+        limits: { newAccountHours: config.limits.newAccountHours },
+        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}`],
+    }));
+}
+/**
+ * AI moderation (`moderation.mode: ai`). The debounced run becomes a run of reader-actions itself (a one-off schedule that
+ * invokes this function), which judges the new items and then asks content-actions for the snapshot. So the scheduler role may
+ * invoke reader-actions, reader-actions may invoke content-actions (its ARN is already in the environment) and may read exactly
+ * one SSM SecureString: the API key, which the plugin never creates and never receives.
+ */
+function wireAiModeration(readerLambda, contentActions, schedulerRole, apiKeyParameter) {
+    const stack = Stack.of(readerLambda);
+    readerLambda.grantInvoke(schedulerRole);
+    contentActions.grantInvoke(readerLambda);
+    readerLambda.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["ssm:GetParameter"],
+        resources: [`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${apiKeyParameter}`],
+    }));
+}
+export const readerSteeringPlugin = {
+    manifest: readerSteeringManifest,
+    resolveConfig: resolveReaderSteeringConfig,
+    functions: () => ({ readerActions }),
+    schemaDefinitions: readerSteeringSchemaDefinitions,
+    publicSettings: (config) => ({
+        contract: readerSteeringManifest.contract,
+        dimensions: config.dimensions,
+        subjects: { types: config.subjects.types },
+        moderation: { mode: config.moderation.mode },
+    }),
+    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"],
+            ["PAPYRUS_READER_FLAG_TABLE", "ReaderFlag"],
+            ["PAPYRUS_READER_SUBMISSION_TABLE", "ReaderSubmission"],
+            ["PAPYRUS_READER_COMMENT_TABLE", "ReaderComment"],
+            ["PAPYRUS_READER_REPORT_TABLE", "ReaderReport"],
+            ["PAPYRUS_READER_ACTION_TABLE", "ModerationAction"],
+            ["PAPYRUS_READER_PROPOSAL_TABLE", "Proposal"],
+        ]) {
+            tables[model].grantReadWriteData(lambda);
+            lambda.addEnvironment(variable, tables[model].tableName);
+            contentActions.addEnvironment(variable, tables[model].tableName);
+        }
+        // Promoting a submission writes one draft Item (a version 1 draft; nothing is published by this function).
+        tables.Item.grantWriteData(lambda);
+        lambda.addEnvironment("PAPYRUS_READER_ITEM_TABLE", tables.Item.tableName);
+        tables.PublishedItem.grantReadData(lambda);
+        lambda.addEnvironment("PAPYRUS_READER_PUBLISHED_ITEM_TABLE", tables.PublishedItem.tableName);
+        tables.ReaderVote.grantReadData(contentActions);
+        tables.ReaderFlag.grantReadData(contentActions);
+        tables.ReaderProfile.grantReadWriteData(contentActions);
+        // The snapshot reads submissions, and the review step writes their signals and moderation state.
+        tables.ReaderSubmission.grantReadWriteData(contentActions);
+        tables.ReaderComment.grantReadWriteData(contentActions);
+        // The snapshot reads proposals and freezes the community result of one that reaches editor review.
+        tables.Proposal.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)));
+        // Proposals are private unless the site opts in (docs/reader-steering.md, Proposals); the snapshot reads this flag.
+        contentActions.addEnvironment("PAPYRUS_READER_PUBLISH_PROPOSALS", config.proposals.publish ? "true" : "false");
+        if (config.moderation.ai)
+            wireAiModeration(lambda, contentActions, schedulerRole, config.moderation.ai.apiKeyParameter);
+        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,213 @@
+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", "ReaderFlag", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction", "Proposal"],
+  mutations: ["moderateReader", "fileProposal", "transitionProposal", "editProposal"],
+  queries: ["listStoryDrafts"],
+  guest: { mutations: [] },
+  newsroomPanels: [{ id: "moderation", label: "Moderation" }],
+  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,
+    submissions: config.submissions,
+    subjects: config.subjects,
+    comments: config.comments,
+    moderation: config.moderation,
+    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,
+    submissions: config.submissions,
+    subjects: config.subjects,
+    karma: config.karma,
+    ranking: config.ranking,
+    limits: { newAccountHours: config.limits.newAccountHours },
+    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}`],
+    }),
+  );
+}
+
+/**
+ * AI moderation (`moderation.mode: ai`). The debounced run becomes a run of reader-actions itself (a one-off schedule that
+ * invokes this function), which judges the new items and then asks content-actions for the snapshot. So the scheduler role may
+ * invoke reader-actions, reader-actions may invoke content-actions (its ARN is already in the environment) and may read exactly
+ * one SSM SecureString: the API key, which the plugin never creates and never receives.
+ */
+function wireAiModeration(readerLambda: LambdaFunction, contentActions: LambdaFunction, schedulerRole: Role, apiKeyParameter: string) {
+  const stack = Stack.of(readerLambda);
+  readerLambda.grantInvoke(schedulerRole);
+  contentActions.grantInvoke(readerLambda);
+  readerLambda.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["ssm:GetParameter"],
+      resources: [`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${apiKeyParameter}`],
+    }),
+  );
+}
+
+export const readerSteeringPlugin: PapyrusPlugin<ReaderSteeringConfig, { readerActions: typeof readerActions }> = {
+  manifest: readerSteeringManifest,
+  resolveConfig: resolveReaderSteeringConfig,
+  functions: () => ({ readerActions }),
+  schemaDefinitions: readerSteeringSchemaDefinitions,
+  publicSettings: (config) => ({
+    contract: readerSteeringManifest.contract,
+    dimensions: config.dimensions,
+    subjects: { types: config.subjects.types },
+    moderation: { mode: config.moderation.mode },
+  }),
+  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"],
+      ["PAPYRUS_READER_FLAG_TABLE", "ReaderFlag"],
+      ["PAPYRUS_READER_SUBMISSION_TABLE", "ReaderSubmission"],
+      ["PAPYRUS_READER_COMMENT_TABLE", "ReaderComment"],
+      ["PAPYRUS_READER_REPORT_TABLE", "ReaderReport"],
+      ["PAPYRUS_READER_ACTION_TABLE", "ModerationAction"],
+      ["PAPYRUS_READER_PROPOSAL_TABLE", "Proposal"],
+    ] as const) {
+      tables[model].grantReadWriteData(lambda);
+      lambda.addEnvironment(variable, tables[model].tableName);
+      contentActions.addEnvironment(variable, tables[model].tableName);
+    }
+    // Promoting a submission writes one draft Item (a version 1 draft; nothing is published by this function).
+    tables.Item.grantWriteData(lambda);
+    lambda.addEnvironment("PAPYRUS_READER_ITEM_TABLE", tables.Item.tableName);
+    tables.PublishedItem.grantReadData(lambda);
+    lambda.addEnvironment("PAPYRUS_READER_PUBLISHED_ITEM_TABLE", tables.PublishedItem.tableName);
+    tables.ReaderVote.grantReadData(contentActions);
+    tables.ReaderFlag.grantReadData(contentActions);
+    tables.ReaderProfile.grantReadWriteData(contentActions);
+    // The snapshot reads submissions, and the review step writes their signals and moderation state.
+    tables.ReaderSubmission.grantReadWriteData(contentActions);
+    tables.ReaderComment.grantReadWriteData(contentActions);
+    // The snapshot reads proposals and freezes the community result of one that reaches editor review.
+    tables.Proposal.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)));
+    // Proposals are private unless the site opts in (docs/reader-steering.md, Proposals); the snapshot reads this flag.
+    contentActions.addEnvironment("PAPYRUS_READER_PUBLISH_PROPOSALS", config.proposals.publish ? "true" : "false");
+
+    if (config.moderation.ai) wireAiModeration(lambda, contentActions, schedulerRole, config.moderation.ai.apiKeyParameter);
+
+    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,252 @@
+import { a } from "@aws-amplify/backend";
+import { readerActions } from "./function/resource.js";
+import { functionHandler } from "../../data/function-handler.js";
+/**
+ * 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, `subjectKey#readerId#dimension` for a vote (`subjectKey#readerId#kind` for a flag; the key is the bare id for items and submissions and `type:id` for the rest) and
+ * `sub-<sha256 of the canonical URL>` for a submission (so a canonical URL is one submission).
+ */
+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"])
+            .secondaryIndexes((index) => [index("readerId").name("profilesByReader").queryField("listReaderProfilesByReader")])
+            .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(),
+            subjectType: a.string(),
+            readerId: a.string().required(),
+            dimension: a.string().required(),
+            value: a.integer().required(),
+            voterRole: a.string().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .authorization(staffOnly),
+        ReaderFlag: a
+            .model({
+            id: a.id().required(),
+            subjectKey: a.string().required(),
+            subjectType: a.string().required(),
+            readerId: a.string().required(),
+            kind: a.string().required(),
+            reason: a.string().required(),
+            targetKey: a.string(),
+            suggestedName: a.string(),
+            voterRole: a.string().required(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .authorization(staffOnly),
+        ReaderComment: a
+            .model({
+            id: a.id().required(),
+            subjectKey: a.string().required(),
+            readerId: a.string().required(),
+            body: a.string().required(),
+            parentId: a.string(),
+            ratingContext: a.json(),
+            state: a.string().required(),
+            signals: a.json(),
+            moderation: a.string().required(),
+            reportCount: a.integer(),
+            reviewedAt: a.datetime(),
+            editedAt: a.datetime(),
+            deletedAt: a.datetime(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [index("moderation").sortKeys(["createdAt"]).name("commentsByModeration").queryField("listReaderCommentsByModerationAndCreatedAt")])
+            .authorization(staffOnly),
+        ReaderSubmission: a
+            .model({
+            id: a.id().required(),
+            canonicalUrl: a.string().required(),
+            domain: a.string().required(),
+            title: a.string().required(),
+            kind: a.string().required(),
+            note: a.string(),
+            readerId: a.string().required(),
+            state: a.string().required(),
+            similar: a.string().array(),
+            signals: a.json(),
+            extractionState: a.string().required(),
+            itemId: a.string(),
+            moderation: a.string().required(),
+            reportCount: a.integer(),
+            reviewedAt: a.datetime(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [
+            index("domain").sortKeys(["createdAt"]).name("submissionsByDomain").queryField("listReaderSubmissionsByDomainAndCreatedAt"),
+            index("moderation").sortKeys(["createdAt"]).name("submissionsByModeration").queryField("listReaderSubmissionsByModerationAndCreatedAt"),
+        ])
+            .authorization(staffOnly),
+        ReaderReport: a
+            .model({
+            id: a.id().required(),
+            targetType: a.string().required(),
+            target: a.string().required(),
+            reporterReaderId: a.string().required(),
+            reason: a.string().required(),
+            state: a.string().required(),
+            closedAt: a.datetime(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [index("target").sortKeys(["createdAt"]).name("reportsByTarget").queryField("listReaderReportsByTargetAndCreatedAt")])
+            .authorization(staffOnly),
+        ModerationAction: a
+            .model({
+            id: a.id().required(),
+            by: a.string().required(),
+            actorSub: a.string().required(),
+            action: a.string().required(),
+            targetType: a.string().required(),
+            target: a.string().required(),
+            reason: a.string(),
+            fromState: a.string().required(),
+            toState: a.string().required(),
+            fromModeration: a.string(),
+            toModeration: a.string(),
+            undoOf: a.string(),
+            undoneBy: a.string(),
+            at: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [index("target").sortKeys(["at"]).name("actionsByTarget").queryField("listModerationActionsByTargetAndAt")])
+            .authorization(staffOnly),
+        Proposal: a
+            .model({
+            id: a.id().required(),
+            kind: a.string().required(),
+            title: a.string().required(),
+            summary: a.string(),
+            body: a.string().required(),
+            targets: a.json().required(),
+            evidence: a.json(),
+            proposer: a.string().required(),
+            state: a.string().required(),
+            history: a.json().required(),
+            communityResult: a.json(),
+            pinned: a.boolean(),
+            held: a.boolean(),
+            override: a.json(),
+            exclusions: a.json(),
+            editorLog: a.json(),
+            needsLook: a.json(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [index("state").sortKeys(["createdAt"]).name("proposalsByState").queryField("listProposalsByStateAndCreatedAt")])
+            .authorization(staffOnly),
+        ProposalReceipt: a.customType({
+            status: a.string().required(),
+            id: a.string(),
+            error: a.string(),
+            message: a.string(),
+        }),
+        // What an operator may read of a story draft: these six fields and nothing else (no body, evidence, history, proposer, vote or log).
+        StoryDraftSummary: a.customType({
+            id: a.string().required(),
+            title: a.string().required(),
+            summary: a.string(),
+            targets: a.json(),
+            state: a.string().required(),
+            createdAt: a.string().required(),
+        }),
+        StoryDraftList: a.customType({
+            status: a.string().required(),
+            id: a.string(),
+            error: a.string(),
+            message: a.string(),
+            drafts: a.ref("StoryDraftSummary").array(),
+        }),
+        // Editors and admins file as themselves. AppSync also admits an IAM principal whose own policy allows the field (the
+        // schema accepts IAM callers for the functions that call it); the function files an AI proposal for an IAM principal
+        // of its own account only, and refuses an identity-pool user and any other account. No IAM rule is declared here.
+        fileProposal: a
+            .mutation()
+            .arguments({
+            kind: a.string().required(),
+            title: a.string().required(),
+            body: a.string().required(),
+            summary: a.string(),
+            targets: a.json(),
+            evidence: a.json(),
+        })
+            .returns(a.ref("ProposalReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(functionHandler("readerActions", readerActions)),
+        // The same IAM rule as fileProposal, narrower: an operator may move only draft to in_steering or declined.
+        // Approving, deciding after review and overriding are refused for IAM in the function (`operator_not_allowed`).
+        transitionProposal: a
+            .mutation()
+            .arguments({
+            proposalId: a.string().required(),
+            state: a.string().required(),
+            reason: a.string(),
+            result: a.string(),
+        })
+            .returns(a.ref("ProposalReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(functionHandler("readerActions", readerActions)),
+        // Read only, and the same caller rule as fileProposal: editors and admins, or an IAM principal of the function's own account. The function
+        // answers the story drafts' id, title, summary, targets, state and createdAt so an unattended trend run can dedupe; nothing else.
+        listStoryDrafts: a
+            .query()
+            .returns(a.ref("StoryDraftList"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(functionHandler("readerActions", readerActions)),
+        // Editors and admins only, and the function refuses an IAM operator: pin, unpin, hold, release, exclude_votes and
+        // undo_exclusion. `rule` is a batch rule for exclude_votes; `exclusionId` names the exclusion undo_exclusion reverses.
+        editProposal: a
+            .mutation()
+            .arguments({
+            proposalId: a.string().required(),
+            action: a.string().required(),
+            rule: a.string(),
+            exclusionId: a.string(),
+        })
+            .returns(a.ref("ProposalReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(functionHandler("readerActions", readerActions)),
+        ModerationReceipt: a.customType({
+            status: a.string().required(),
+            id: a.string(),
+            error: a.string(),
+            message: a.string(),
+        }),
+        moderateReader: a
+            .mutation()
+            .arguments({
+            action: a.string().required(),
+            targetType: a.string().required(),
+            target: a.string().required(),
+            reason: a.string(),
+            undoOf: a.string(),
+        })
+            .returns(a.ref("ModerationReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(functionHandler("readerActions", readerActions)),
+    };
+}