@anthusai/papyrus 2.0.0-next.8 → 2.0.0-next.80

package/amplify/plugins/newsletter/sending.js

@@ -0,0 +1,140 @@
+import { Duration, Stack } from "aws-cdk-lib";
+import { Effect, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Architecture, Function as LambdaFunction, Runtime } from "aws-cdk-lib/aws-lambda";
+import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
+import { CfnSchedule } from "aws-cdk-lib/aws-scheduler";
+import { Queue, QueueEncryption } from "aws-cdk-lib/aws-sqs";
+export const NEWSLETTER_WORKER_HANDLER = "papyrus_content.newsletter.worker.handler";
+/** The worker mails up to 50 subscribers per message at the SES send rate; the visibility timeout is six times this. */
+export const WORKER_TIMEOUT_SECONDS = 180;
+export const SEND_MAX_RECEIVE_COUNT = 3;
+/** The schedule names the function may manage at run time: `papyrus-nl-<siteId>-<issue8>`. */
+export const SCHEDULE_NAME_PREFIX = "papyrus-nl-";
+export const newsletterFunctionName = (siteId) => `papyrus-newsletter-${siteId}`;
+export const newsletterWorkerName = (siteId) => `papyrus-newsletter-send-${siteId}`;
+export const newsletterSendQueueName = (siteId) => `papyrus-newsletter-send-${siteId}`;
+/** The AppSync fields the `newsletter` function reads and writes through the content API (the roundup draft, the issue's Item, and the published item an alert is about). */
+export const NEWSLETTER_APPSYNC_FIELDS = [
+    "Query/fields/getItem",
+    "Query/fields/getPublishedItem",
+    "Query/fields/listPublishedItems",
+    "Mutation/fields/createItem",
+    "Mutation/fields/updateItem",
+];
+/** The only two SSM parameters that hold the postal address: the site's override and the shared default. */
+export function postalAddressParameterArns(stack, siteId) {
+    return [`/papyrus/${siteId}/email/postal-address`, "/papyrus/email/postal-address"].map((name) => `arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${name}`);
+}
+export function scheduleArnPattern(stack, siteId) {
+    return `arn:${stack.partition}:scheduler:${stack.region}:${stack.account}:schedule/default/${SCHEDULE_NAME_PREFIX}${siteId}-*`;
+}
+export function functionArn(stack, name) {
+    return `arn:${stack.partition}:lambda:${stack.region}:${stack.account}:function:${name}`;
+}
+/**
+ * Everything that sends: the queue and its dead letter queue, the send worker, the scheduler role and the per-list
+ * draft schedules, and the IAM they need. Nothing here lets the function reach anything but its own queue, its own
+ * schedules (`papyrus-nl-<siteId>-*`), two postal address parameters and five content API fields.
+ */
+export function wireSending(inputs) {
+    const { stack, config, context, backend, table, lambda, environment, keyParameterArn, sesResources, code } = inputs;
+    const deadLetterQueue = new Queue(stack, "SendDeadLetterQueue", {
+        queueName: `${newsletterSendQueueName(config.siteId)}-dlq`,
+        retentionPeriod: Duration.days(14),
+        encryption: QueueEncryption.SQS_MANAGED,
+        enforceSSL: true,
+    });
+    const queue = new Queue(stack, "SendQueue", {
+        queueName: newsletterSendQueueName(config.siteId),
+        visibilityTimeout: Duration.seconds(WORKER_TIMEOUT_SECONDS * 6),
+        encryption: QueueEncryption.SQS_MANAGED,
+        enforceSSL: true,
+        deadLetterQueue: { queue: deadLetterQueue, maxReceiveCount: SEND_MAX_RECEIVE_COUNT },
+    });
+    // The role EventBridge Scheduler assumes to invoke the function, for the draft schedules and the one-time send schedules.
+    const schedulerRole = new Role(stack, "SchedulerRole", {
+        assumedBy: new ServicePrincipal("scheduler.amazonaws.com", { conditions: { StringEquals: { "aws:SourceAccount": stack.account } } }),
+        description: `Lets EventBridge Scheduler invoke the ${config.siteId} newsletter function`,
+    });
+    lambda.grantInvoke(schedulerRole);
+    const contentActions = context.contentActionsLambda;
+    lambda.addEnvironment("FUNCTION_ARN", functionArn(stack, newsletterFunctionName(config.siteId)));
+    lambda.addEnvironment("SCHEDULER_ROLE_ARN", schedulerRole.roleArn);
+    lambda.addEnvironment("QUEUE_URL", queue.queueUrl);
+    lambda.addEnvironment("CONTENT_ACTIONS_FUNCTION", contentActions.functionName);
+    lambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", context.graphqlEndpoint);
+    queue.grantSendMessages(lambda);
+    contentActions.grantInvoke(lambda);
+    lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: postalAddressParameterArns(stack, config.siteId) }));
+    lambda.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["scheduler:CreateSchedule", "scheduler:UpdateSchedule", "scheduler:DeleteSchedule"],
+        resources: [scheduleArnPattern(stack, config.siteId)],
+    }));
+    lambda.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["iam:PassRole"],
+        resources: [schedulerRole.roleArn],
+        conditions: { StringEquals: { "iam:PassedToService": "scheduler.amazonaws.com" } },
+    }));
+    lambda.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["appsync:GraphQL"],
+        resources: NEWSLETTER_APPSYNC_FIELDS.map((field) => `arn:${stack.partition}:appsync:${stack.region}:${stack.account}:apis/${context.graphqlApiId}/types/${field}`),
+    }));
+    const worker = new LambdaFunction(stack, "SendWorkerFunction", {
+        functionName: newsletterWorkerName(config.siteId),
+        runtime: Runtime.PYTHON_3_12,
+        architecture: Architecture.ARM_64,
+        handler: NEWSLETTER_WORKER_HANDLER,
+        timeout: Duration.seconds(WORKER_TIMEOUT_SECONDS),
+        memorySize: 512,
+        // One message at a time, so the send rate is the account's SES rate, never a multiple of it.
+        reservedConcurrentExecutions: 1,
+        description: `Mails queued newsletter batches for ${config.siteId}, paced under the SES send rate`,
+        environment: { ...environment, QUEUE_URL: queue.queueUrl, CONTENT_ACTIONS_FUNCTION: contentActions.functionName },
+        code,
+    });
+    worker.addEventSource(new SqsEventSource(queue, { batchSize: 1 }));
+    table.grantReadWriteData(worker);
+    queue.grantSendMessages(worker);
+    contentActions.grantInvoke(worker);
+    worker.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: [keyParameterArn] }));
+    worker.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["ses:SendEmail", "ses:SendRawEmail"],
+        resources: sesResources,
+        conditions: { StringEquals: { "ses:FromAddress": config.fromAddress } },
+    }));
+    // GetAccount (the send rate) does not support resource-level permissions.
+    worker.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["sesv2:GetAccount"], resources: ["*"] }));
+    // A roundup list drafts itself on its schedule, in the schedule's own time zone.
+    const roundups = config.lists.filter((list) => list.kind === "roundup");
+    for (const list of roundups) {
+        new CfnSchedule(stack, `Draft${list.id.replace(/(^|-)([a-z0-9])/g, (_match, _dash, letter) => letter.toUpperCase())}`, {
+            description: `Draft the ${list.id} roundup for ${config.siteId}`,
+            scheduleExpression: list.schedule.draft,
+            scheduleExpressionTimezone: list.schedule.timezone,
+            flexibleTimeWindow: { mode: "OFF" },
+            state: "ENABLED",
+            target: {
+                arn: lambda.functionArn,
+                roleArn: schedulerRole.roleArn,
+                input: JSON.stringify({ task: "assemble-roundup", listId: list.id }),
+                retryPolicy: { maximumRetryAttempts: 2, maximumEventAgeInSeconds: 3600 },
+            },
+        });
+    }
+    // The newsroom operations reach the function through the thin AppSync function the plugin defines.
+    const operations = backend.newsletterOps?.resources.lambda;
+    if (operations) {
+        const operationsStack = Stack.of(operations);
+        operations.addEnvironment("NEWSLETTER_FUNCTION_NAME", newsletterFunctionName(config.siteId));
+        operations.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["lambda:InvokeFunction"],
+            resources: [functionArn(operationsStack, newsletterFunctionName(config.siteId))],
+        }));
+    }
+    return { queue, deadLetterQueue, worker, schedulerRole };
+}

package/amplify/plugins/newsletter/sending.ts

@@ -0,0 +1,186 @@
+import { Duration, Stack } from "aws-cdk-lib";
+import type { Table } from "aws-cdk-lib/aws-dynamodb";
+import { Effect, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Architecture, type Code, Function as LambdaFunction, Runtime } from "aws-cdk-lib/aws-lambda";
+import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
+import { CfnSchedule } from "aws-cdk-lib/aws-scheduler";
+import { Queue, QueueEncryption } from "aws-cdk-lib/aws-sqs";
+import type { PluginWiringContext } from "../types";
+import type { NewsletterConfig, RoundupList } from "./config";
+
+export const NEWSLETTER_WORKER_HANDLER = "papyrus_content.newsletter.worker.handler";
+/** The worker mails up to 50 subscribers per message at the SES send rate; the visibility timeout is six times this. */
+export const WORKER_TIMEOUT_SECONDS = 180;
+export const SEND_MAX_RECEIVE_COUNT = 3;
+/** The schedule names the function may manage at run time: `papyrus-nl-<siteId>-<issue8>`. */
+export const SCHEDULE_NAME_PREFIX = "papyrus-nl-";
+
+export const newsletterFunctionName = (siteId: string) => `papyrus-newsletter-${siteId}`;
+export const newsletterWorkerName = (siteId: string) => `papyrus-newsletter-send-${siteId}`;
+export const newsletterSendQueueName = (siteId: string) => `papyrus-newsletter-send-${siteId}`;
+
+/** The AppSync fields the `newsletter` function reads and writes through the content API (the roundup draft, the issue's Item, and the published item an alert is about). */
+export const NEWSLETTER_APPSYNC_FIELDS = [
+  "Query/fields/getItem",
+  "Query/fields/getPublishedItem",
+  "Query/fields/listPublishedItems",
+  "Mutation/fields/createItem",
+  "Mutation/fields/updateItem",
+];
+
+/** The only two SSM parameters that hold the postal address: the site's override and the shared default. */
+export function postalAddressParameterArns(stack: Stack, siteId: string): string[] {
+  return [`/papyrus/${siteId}/email/postal-address`, "/papyrus/email/postal-address"].map(
+    (name) => `arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${name}`,
+  );
+}
+
+export function scheduleArnPattern(stack: Stack, siteId: string): string {
+  return `arn:${stack.partition}:scheduler:${stack.region}:${stack.account}:schedule/default/${SCHEDULE_NAME_PREFIX}${siteId}-*`;
+}
+
+export function functionArn(stack: Stack, name: string): string {
+  return `arn:${stack.partition}:lambda:${stack.region}:${stack.account}:function:${name}`;
+}
+
+type SendingInputs = {
+  stack: Stack;
+  config: NewsletterConfig;
+  context: PluginWiringContext;
+  backend: any;
+  table: Table;
+  lambda: LambdaFunction;
+  environment: Record<string, string>;
+  keyParameterArn: string;
+  sesResources: string[];
+  code: Code;
+};
+
+/**
+ * Everything that sends: the queue and its dead letter queue, the send worker, the scheduler role and the per-list
+ * draft schedules, and the IAM they need. Nothing here lets the function reach anything but its own queue, its own
+ * schedules (`papyrus-nl-<siteId>-*`), two postal address parameters and five content API fields.
+ */
+export function wireSending(inputs: SendingInputs): { queue: Queue; deadLetterQueue: Queue; worker: LambdaFunction; schedulerRole: Role } {
+  const { stack, config, context, backend, table, lambda, environment, keyParameterArn, sesResources, code } = inputs;
+
+  const deadLetterQueue = new Queue(stack, "SendDeadLetterQueue", {
+    queueName: `${newsletterSendQueueName(config.siteId)}-dlq`,
+    retentionPeriod: Duration.days(14),
+    encryption: QueueEncryption.SQS_MANAGED,
+    enforceSSL: true,
+  });
+  const queue = new Queue(stack, "SendQueue", {
+    queueName: newsletterSendQueueName(config.siteId),
+    visibilityTimeout: Duration.seconds(WORKER_TIMEOUT_SECONDS * 6),
+    encryption: QueueEncryption.SQS_MANAGED,
+    enforceSSL: true,
+    deadLetterQueue: { queue: deadLetterQueue, maxReceiveCount: SEND_MAX_RECEIVE_COUNT },
+  });
+
+  // The role EventBridge Scheduler assumes to invoke the function, for the draft schedules and the one-time send schedules.
+  const schedulerRole = new Role(stack, "SchedulerRole", {
+    assumedBy: new ServicePrincipal("scheduler.amazonaws.com", { conditions: { StringEquals: { "aws:SourceAccount": stack.account } } }),
+    description: `Lets EventBridge Scheduler invoke the ${config.siteId} newsletter function`,
+  });
+  lambda.grantInvoke(schedulerRole);
+
+  const contentActions = context.contentActionsLambda;
+  lambda.addEnvironment("FUNCTION_ARN", functionArn(stack, newsletterFunctionName(config.siteId)));
+  lambda.addEnvironment("SCHEDULER_ROLE_ARN", schedulerRole.roleArn);
+  lambda.addEnvironment("QUEUE_URL", queue.queueUrl);
+  lambda.addEnvironment("CONTENT_ACTIONS_FUNCTION", contentActions.functionName);
+  lambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", context.graphqlEndpoint);
+
+  queue.grantSendMessages(lambda);
+  contentActions.grantInvoke(lambda);
+  lambda.addToRolePolicy(
+    new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: postalAddressParameterArns(stack, config.siteId) }),
+  );
+  lambda.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["scheduler:CreateSchedule", "scheduler:UpdateSchedule", "scheduler:DeleteSchedule"],
+      resources: [scheduleArnPattern(stack, config.siteId)],
+    }),
+  );
+  lambda.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["iam:PassRole"],
+      resources: [schedulerRole.roleArn],
+      conditions: { StringEquals: { "iam:PassedToService": "scheduler.amazonaws.com" } },
+    }),
+  );
+  lambda.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["appsync:GraphQL"],
+      resources: NEWSLETTER_APPSYNC_FIELDS.map(
+        (field) => `arn:${stack.partition}:appsync:${stack.region}:${stack.account}:apis/${context.graphqlApiId}/types/${field}`,
+      ),
+    }),
+  );
+
+  const worker = new LambdaFunction(stack, "SendWorkerFunction", {
+    functionName: newsletterWorkerName(config.siteId),
+    runtime: Runtime.PYTHON_3_12,
+    architecture: Architecture.ARM_64,
+    handler: NEWSLETTER_WORKER_HANDLER,
+    timeout: Duration.seconds(WORKER_TIMEOUT_SECONDS),
+    memorySize: 512,
+    // One message at a time, so the send rate is the account's SES rate, never a multiple of it.
+    reservedConcurrentExecutions: 1,
+    description: `Mails queued newsletter batches for ${config.siteId}, paced under the SES send rate`,
+    environment: { ...environment, QUEUE_URL: queue.queueUrl, CONTENT_ACTIONS_FUNCTION: contentActions.functionName },
+    code,
+  });
+  worker.addEventSource(new SqsEventSource(queue, { batchSize: 1 }));
+  table.grantReadWriteData(worker);
+  queue.grantSendMessages(worker);
+  contentActions.grantInvoke(worker);
+  worker.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: [keyParameterArn] }));
+  worker.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["ses:SendEmail", "ses:SendRawEmail"],
+      resources: sesResources,
+      conditions: { StringEquals: { "ses:FromAddress": config.fromAddress } },
+    }),
+  );
+  // GetAccount (the send rate) does not support resource-level permissions.
+  worker.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["sesv2:GetAccount"], resources: ["*"] }));
+
+  // A roundup list drafts itself on its schedule, in the schedule's own time zone.
+  const roundups = config.lists.filter((list): list is RoundupList => list.kind === "roundup");
+  for (const list of roundups) {
+    new CfnSchedule(stack, `Draft${list.id.replace(/(^|-)([a-z0-9])/g, (_match, _dash, letter: string) => letter.toUpperCase())}`, {
+      description: `Draft the ${list.id} roundup for ${config.siteId}`,
+      scheduleExpression: list.schedule.draft,
+      scheduleExpressionTimezone: list.schedule.timezone,
+      flexibleTimeWindow: { mode: "OFF" },
+      state: "ENABLED",
+      target: {
+        arn: lambda.functionArn,
+        roleArn: schedulerRole.roleArn,
+        input: JSON.stringify({ task: "assemble-roundup", listId: list.id }),
+        retryPolicy: { maximumRetryAttempts: 2, maximumEventAgeInSeconds: 3600 },
+      },
+    });
+  }
+
+  // The newsroom operations reach the function through the thin AppSync function the plugin defines.
+  const operations = backend.newsletterOps?.resources.lambda as LambdaFunction | undefined;
+  if (operations) {
+    const operationsStack = Stack.of(operations);
+    operations.addEnvironment("NEWSLETTER_FUNCTION_NAME", newsletterFunctionName(config.siteId));
+    operations.addToRolePolicy(
+      new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["lambda:InvokeFunction"],
+        resources: [functionArn(operationsStack, newsletterFunctionName(config.siteId))],
+      }),
+    );
+  }
+  return { queue, deadLetterQueue, worker, schedulerRole };
+}

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

@@ -0,0 +1,182 @@
+export const READER_DIMENSION_NAME = /^[a-z][a-z0-9-]{0,23}$/;
+export const RESERVED_DIMENSIONS = ["up", "used-it"];
+export const READER_HANDLE_NAME = /^[a-z0-9_-]{3,24}$/;
+export const MODERATION_MODES = ["off", "human", "ai"];
+export const AI_KEY_PARAMETER = /^\/papyrus\/[a-z0-9][a-z0-9-]{0,62}\/openai-api-key$/;
+export const AI_MODEL_NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+export const SUBMISSION_KIND_NAME = /^[a-z][a-z0-9-]{0,23}$/;
+export const SUBJECT_TYPES = ["item", "submission", "story", "proposal", "concept"];
+export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
+const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation", "subjects", "proposals"]);
+function object(raw, label, known) {
+    if (raw === undefined)
+        return {};
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error(`reader-steering plugin ${label} must be an object`);
+    const unknown = Object.keys(raw).filter((key) => !known.includes(key));
+    if (unknown.length > 0)
+        throw new Error(`Unknown reader-steering plugin ${label} settings: ${unknown.join(", ")}`);
+    return raw;
+}
+function integer(raw, label, fallback, minimum, maximum) {
+    const value = raw === undefined ? fallback : raw;
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`reader-steering plugin ${label} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+function number(raw, label, fallback, minimum, maximum) {
+    const value = raw === undefined ? fallback : raw;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) {
+        throw new Error(`reader-steering plugin ${label} must be a number from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+function flag(raw, label) {
+    if (raw === undefined)
+        return false;
+    if (typeof raw !== "boolean")
+        throw new Error(`reader-steering plugin ${label} must be a boolean`);
+    return raw;
+}
+function names(raw, label, pattern) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || !raw.every((entry) => typeof entry === "string" && pattern.test(entry))) {
+        throw new Error(`reader-steering plugin ${label} must be a list of lowercase names matching ${pattern}`);
+    }
+    return [...new Set(raw)];
+}
+function lowercaseName(raw, label, fallback) {
+    const value = raw === undefined ? fallback : raw;
+    if (typeof value !== "string" || !SUBMISSION_KIND_NAME.test(value))
+        throw new Error(`reader-steering plugin ${label} must be a lowercase name matching ${SUBMISSION_KIND_NAME}`);
+    return value;
+}
+function resolveHypeGap(raw, dimensions) {
+    if (raw === undefined)
+        return undefined;
+    const groups = object(raw, "hypeGap", ["plus", "minus"]);
+    const plus = names(groups.plus, "hypeGap.plus", READER_DIMENSION_NAME);
+    const minus = names(groups.minus, "hypeGap.minus", READER_DIMENSION_NAME);
+    if (plus.length === 0 || minus.length === 0)
+        throw new Error("reader-steering plugin hypeGap needs at least one plus and one minus dimension");
+    const unknown = [...plus, ...minus].filter((dimension) => !dimensions.includes(dimension));
+    if (unknown.length > 0)
+        throw new Error(`reader-steering plugin hypeGap uses dimensions the site does not rate: ${unknown.join(", ")}`);
+    const both = plus.filter((dimension) => minus.includes(dimension));
+    if (both.length > 0)
+        throw new Error(`reader-steering plugin hypeGap dimensions cannot be both plus and minus: ${both.join(", ")}`);
+    return { plus, minus };
+}
+export function resolveReaderSteeringConfig(request) {
+    const raw = typeof request === "string" ? { name: request } : request;
+    const unknown = Object.keys(raw).filter((key) => !KNOWN_KEYS.has(key));
+    if (unknown.length > 0)
+        throw new Error(`Unknown reader-steering plugin settings: ${unknown.join(", ")}`);
+    const computeRoleArn = raw.computeRoleArn;
+    if (typeof computeRoleArn !== "string" || !COMPUTE_ROLE_ARN.test(computeRoleArn)) {
+        throw new Error("reader-steering plugin computeRoleArn must be the IAM role ARN of the CMS app's compute role (the CmsComputeRoleArn output)");
+    }
+    const dimensions = names(raw.dimensions, "dimensions", READER_DIMENSION_NAME);
+    const reserved = dimensions.filter((dimension) => RESERVED_DIMENSIONS.includes(dimension));
+    if (reserved.length > 0)
+        throw new Error(`reader-steering plugin dimensions cannot use the reserved names: ${reserved.join(", ")}`);
+    const limits = object(raw.limits, "limits", ["actionsPerHour", "newAccountHours", "newAccountDivisor"]);
+    const karma = object(raw.karma, "karma", ["upvoteWeight", "usedItWeight"]);
+    const ranking = object(raw.ranking, "ranking", [
+        "halfLifeHours", "risingWindowHours", "readerMinimum", "editorWeight", "combination", "shrinkageK", "readerShareCap", "newAccountWeight", "risingMinimumAccountHours",
+    ]);
+    const combination = ranking.combination === undefined ? "blend" : ranking.combination;
+    if (combination !== "blend" && combination !== "shrinkage")
+        throw new Error("reader-steering plugin ranking.combination must be blend or shrinkage");
+    const shrinking = combination === "shrinkage";
+    const snapshot = object(raw.snapshot, "snapshot", ["schedule", "intervalHours", "hypeMinimum"]);
+    const submissions = object(raw.submissions, "submissions", ["perDay", "similarHours", "kinds", "itemType", "section"]);
+    const moderation = object(raw.moderation, "moderation", ["mode", "preModeration", "reportsPerDay", "ai"]);
+    const mode = moderation.mode === undefined ? "human" : moderation.mode;
+    if (!MODERATION_MODES.includes(mode)) {
+        throw new Error(`reader-steering plugin moderation.mode must be one of: ${MODERATION_MODES.join(", ")}`);
+    }
+    const preModeration = flag(moderation.preModeration, "moderation.preModeration");
+    if (preModeration && mode === "off")
+        throw new Error("reader-steering plugin moderation.preModeration needs a moderation.mode other than off");
+    const ai = object(moderation.ai, "moderation.ai", ["model", "apiKeyParameter"]);
+    if (mode !== "ai" && moderation.ai !== undefined)
+        throw new Error("reader-steering plugin moderation.ai needs moderation.mode: ai");
+    if (mode === "ai") {
+        if (typeof ai.apiKeyParameter !== "string" || !AI_KEY_PARAMETER.test(ai.apiKeyParameter)) {
+            throw new Error("reader-steering plugin moderation.ai.apiKeyParameter must be the SSM SecureString name /papyrus/<site>/openai-api-key");
+        }
+        if (ai.model !== undefined && (typeof ai.model !== "string" || !AI_MODEL_NAME.test(ai.model))) {
+            throw new Error(`reader-steering plugin moderation.ai.model must be a model name matching ${AI_MODEL_NAME}`);
+        }
+    }
+    const subjects = object(raw.subjects, "subjects", ["types"]);
+    const subjectTypes = subjects.types === undefined ? ["item", "submission"] : subjects.types;
+    if (!Array.isArray(subjectTypes) || subjectTypes.length === 0 || !subjectTypes.every((type) => SUBJECT_TYPES.includes(type))) {
+        throw new Error(`reader-steering plugin subjects.types must be a non-empty list of: ${SUBJECT_TYPES.join(", ")}`);
+    }
+    const proposals = object(raw.proposals, "proposals", ["publish"]);
+    const kinds = names(submissions.kinds, "submissions.kinds", SUBMISSION_KIND_NAME);
+    const comments = object(raw.comments, "comments", ["perHour", "editWindowMinutes", "maximumLength", "maximumLinks"]);
+    const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
+    const retirementPoll = flag(raw.retirementPoll, "retirementPoll");
+    if (retirementPoll && !flag(snapshot.schedule, "snapshot.schedule")) {
+        throw new Error("reader-steering plugin retirementPoll runs inside the scheduled snapshot, so it needs snapshot.schedule: true");
+    }
+    return {
+        computeRoleArn,
+        dimensions,
+        limits: {
+            actionsPerHour: integer(limits.actionsPerHour, "limits.actionsPerHour", 120, 1, 10000),
+            newAccountHours: integer(limits.newAccountHours, "limits.newAccountHours", 24, 0, 24 * 90),
+            newAccountDivisor: integer(limits.newAccountDivisor, "limits.newAccountDivisor", 3, 1, 100),
+        },
+        reservedHandles: names(raw.reservedHandles, "reservedHandles", READER_HANDLE_NAME),
+        karma: {
+            upvoteWeight: number(karma.upvoteWeight, "karma.upvoteWeight", 1, 0, 1000),
+            usedItWeight: number(karma.usedItWeight, "karma.usedItWeight", 2, 0, 1000),
+        },
+        ranking: {
+            halfLifeHours: number(ranking.halfLifeHours, "ranking.halfLifeHours", 48, 1, 24 * 365),
+            risingWindowHours: number(ranking.risingWindowHours, "ranking.risingWindowHours", 6, 1, 24 * 30),
+            readerMinimum: integer(ranking.readerMinimum, "ranking.readerMinimum", 5, 1, 10000),
+            editorWeight: number(ranking.editorWeight, "ranking.editorWeight", 0.5, 0, 1),
+            combination,
+            shrinkageK: number(ranking.shrinkageK, "ranking.shrinkageK", 20, 0.01, 10000),
+            readerShareCap: number(ranking.readerShareCap, "ranking.readerShareCap", 0.4, 0, 1),
+            newAccountWeight: number(ranking.newAccountWeight, "ranking.newAccountWeight", shrinking ? 1 / 3 : 1, 0, 1),
+            risingMinimumAccountHours: number(ranking.risingMinimumAccountHours, "ranking.risingMinimumAccountHours", shrinking ? 24 : 0, 0, 24 * 90),
+        },
+        snapshot: {
+            schedule: flag(snapshot.schedule, "snapshot.schedule"),
+            intervalHours: integer(snapshot.intervalHours, "snapshot.intervalHours", 6, 1, 24),
+            hypeMinimum: integer(snapshot.hypeMinimum, "snapshot.hypeMinimum", 5, 1, 10000),
+        },
+        submissions: {
+            perDay: integer(submissions.perDay, "submissions.perDay", 10, 1, 1000),
+            similarHours: integer(submissions.similarHours, "submissions.similarHours", 48, 1, 24 * 30),
+            kinds: kinds.length > 0 ? kinds : ["link"],
+            itemType: lowercaseName(submissions.itemType, "submissions.itemType", "brief"),
+            section: lowercaseName(submissions.section, "submissions.section", "unsectioned"),
+        },
+        subjects: { types: [...new Set(subjectTypes)] },
+        moderation: {
+            mode: mode,
+            preModeration,
+            reportsPerDay: integer(moderation.reportsPerDay, "moderation.reportsPerDay", 20, 1, 1000),
+            ...(mode === "ai" ? { ai: { model: ai.model ?? "gpt-6-luna", apiKeyParameter: ai.apiKeyParameter } } : {}),
+        },
+        comments: {
+            perHour: integer(comments.perHour, "comments.perHour", 30, 1, 1000),
+            editWindowMinutes: integer(comments.editWindowMinutes, "comments.editWindowMinutes", 10, 0, 24 * 60),
+            maximumLength: integer(comments.maximumLength, "comments.maximumLength", 2000, 1, 10000),
+            maximumLinks: integer(comments.maximumLinks, "comments.maximumLinks", 3, 0, 50),
+        },
+        proposals: { publish: flag(proposals.publish, "proposals.publish") },
+        retirementPoll,
+        ...(hypeGap ? { hypeGap } : {}),
+        ...(raw.reservedConcurrency === undefined ? {} : { reservedConcurrency: integer(raw.reservedConcurrency, "reservedConcurrency", 1, 1, 1000) }),
+    };
+}