@anthusai/papyrus 2.0.0-next.4 → 2.0.0-next.41

package/amplify/functions/public-forms/resource.js

@@ -0,0 +1,9 @@
+import { defineFunction } from "@aws-amplify/backend";
+/** The public form receiving endpoint. Wired (table, Function URL, origins, output) by `wire.ts`. */
+export const publicForms = defineFunction({
+    name: "papyrus-public-forms",
+    entry: "./handler.ts",
+    timeoutSeconds: 10,
+    memoryMB: 256,
+    resourceGroupName: "data",
+});

package/amplify/functions/public-forms/resource.ts

@@ -0,0 +1,10 @@
+import { defineFunction } from "@aws-amplify/backend";
+
+/** The public form receiving endpoint. Wired (table, Function URL, origins, output) by `wire.ts`. */
+export const publicForms = defineFunction({
+  name: "papyrus-public-forms",
+  entry: "./handler.ts",
+  timeoutSeconds: 10,
+  memoryMB: 256,
+  resourceGroupName: "data",
+});

package/amplify/functions/public-forms/wire.js

@@ -0,0 +1,25 @@
+import { RemovalPolicy, Stack } from "aws-cdk-lib";
+import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { FunctionUrlAuthType } from "aws-cdk-lib/aws-lambda";
+export const PUBLIC_FORMS_OUTPUT_KEY = "publicForms";
+/**
+ * Wires the endpoint: the rate-limit counter table (TTL), the Function URL and the function's settings, and returns
+ * the URL for the `custom.publicForms.endpoint` output. Everything lives in the function's own stack.
+ */
+export function wirePublicForms(backend, wiring) {
+    const lambda = backend.publicForms.resources.lambda;
+    const stack = Stack.of(lambda);
+    const table = new dynamodb.Table(stack, "PublicFormsLimits", {
+        partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
+        billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+        timeToLiveAttribute: "expiresAt",
+        removalPolicy: RemovalPolicy.DESTROY,
+    });
+    lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["dynamodb:UpdateItem"], resources: [table.tableArn] }));
+    backend.publicForms.addEnvironment("PAPYRUS_PUBLIC_FORMS_TABLE", table.tableName);
+    backend.publicForms.addEnvironment("PAPYRUS_PUBLIC_FORMS_ORIGINS", wiring.allowedOrigins.join(","));
+    backend.publicForms.addEnvironment("PAPYRUS_PUBLIC_FORMS_HONEYPOTS", (wiring.honeypotFields ?? []).join(","));
+    // CORS is answered by the handler (it must echo exactly one allowed origin), so the URL carries no CORS block.
+    return lambda.addFunctionUrl({ authType: FunctionUrlAuthType.NONE }).url;
+}

package/amplify/functions/public-forms/wire.ts

@@ -0,0 +1,32 @@
+import { RemovalPolicy, Stack } from "aws-cdk-lib";
+import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { type Function as LambdaFunction, FunctionUrlAuthType } from "aws-cdk-lib/aws-lambda";
+
+export const PUBLIC_FORMS_OUTPUT_KEY = "publicForms";
+
+export type PublicFormsWiring = {
+  allowedOrigins: string[];
+  honeypotFields?: string[];
+};
+
+/**
+ * Wires the endpoint: the rate-limit counter table (TTL), the Function URL and the function's settings, and returns
+ * the URL for the `custom.publicForms.endpoint` output. Everything lives in the function's own stack.
+ */
+export function wirePublicForms(backend: { publicForms: { resources: { lambda: unknown }; addEnvironment: (name: string, value: string) => void } }, wiring: PublicFormsWiring): string {
+  const lambda = backend.publicForms.resources.lambda as LambdaFunction;
+  const stack = Stack.of(lambda);
+  const table = new dynamodb.Table(stack, "PublicFormsLimits", {
+    partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
+    billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+    timeToLiveAttribute: "expiresAt",
+    removalPolicy: RemovalPolicy.DESTROY,
+  });
+  lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["dynamodb:UpdateItem"], resources: [table.tableArn] }));
+  backend.publicForms.addEnvironment("PAPYRUS_PUBLIC_FORMS_TABLE", table.tableName);
+  backend.publicForms.addEnvironment("PAPYRUS_PUBLIC_FORMS_ORIGINS", wiring.allowedOrigins.join(","));
+  backend.publicForms.addEnvironment("PAPYRUS_PUBLIC_FORMS_HONEYPOTS", (wiring.honeypotFields ?? []).join(","));
+  // CORS is answered by the handler (it must echo exactly one allowed origin), so the URL carries no CORS block.
+  return lambda.addFunctionUrl({ authType: FunctionUrlAuthType.NONE }).url;
+}

package/amplify/functions/shared/editorial-context.ts

@@ -13,6 +13,9 @@ export type EditorialOptions = {
   storyLineageId?: string | null;
   assignmentId?: string | null;
   maxCharacters?: number | null;
+  /** A publication without a current mission or policy record yields missingPublicationDoctrine instead of an error.
+   * Only the editorial check asks for this (its rule lane needs no doctrine); more than one current record is still an error. */
+  optionalPublicationDoctrine?: boolean | null;
   readAttachment: (attachment: EditorialRecord) => Promise<string>;
 };
 
@@ -55,7 +58,7 @@ function entry(scope: string, kind: string, text: string, record: EditorialRecor
   } };
 }
 
-export function buildEditorialContext(publication: EditorialRecord, scope: EditorialRecord, entries: EditorialRecord[], warnings: string[], maxCharacters = 0) {
+export function buildEditorialContext(publication: EditorialRecord, scope: EditorialRecord, entries: EditorialRecord[], warnings: string[], maxCharacters = 0, missingPublicationDoctrine: string[] = []) {
   const lines = [`Editorial context: ${publication.key}`, "Source: cloud",
     "Precedence: publication > section > assignment. Surface conflicts; narrower instructions do not silently override publication policy.",
     "Private operating guidance; not evidence or reader-facing copy."];
@@ -65,7 +68,8 @@ export function buildEditorialContext(publication: EditorialRecord, scope: Edito
   if (!Number.isInteger(maxCharacters) || maxCharacters < 0) throw new Error("Editorial context budget must be nonnegative.");
   if (maxCharacters && totalCharacters > maxCharacters) throw new Error(`Editorial context budget ${maxCharacters} cannot hold ${totalCharacters} required characters; policy was not truncated.`);
   const payload = { schemaVersion: 1, rendererVersion: "editorial-context/v1", publication, scope, sourceMode: "cloud",
-    precedence: ["publication", "section", "assignment"], entries, sources: entries.map(value => value.source), warnings, text, totalCharacters };
+    precedence: ["publication", "section", "assignment"], entries, sources: entries.map(value => value.source), warnings, text, totalCharacters,
+    ...(missingPublicationDoctrine.length ? { missingPublicationDoctrine } : {}) };
   return { ...payload, contextHash: digest(JSON.stringify(canonical(payload))), resolvedAt: new Date().toISOString() };
 }
 
@@ -83,6 +87,7 @@ export async function resolveEditorialContext(client: EditorialClient, options:
     corpusId: corpora[0].id, tenantId: options.tenantId ?? null, endpoint: options.endpoint };
   const entries: EditorialRecord[] = [];
   const warnings: string[] = [];
+  const missingPublicationDoctrine: string[] = [];
   let sectionId = options.sectionId || null;
   let storyLineageId = options.storyLineageId || null;
   const assignmentId = options.assignmentId || null;
@@ -110,6 +115,7 @@ export async function resolveEditorialContext(client: EditorialClient, options:
     const rows = await pages(client, "Item", options.tenantId ? "itemByTenantSlug" : "itemBySlug",
       options.tenantId ? { tenantSlug: tenantScopedValue(options.tenantId, slug) } : { slug });
     const current = rows.filter(row => row.type === "doctrine" && row.status === "private" && row.versionState === "current");
+    if (current.length === 0 && options.optionalPublicationDoctrine) { missingPublicationDoctrine.push(kind); continue; }
     if (current.length !== 1) throw new Error(`Publication ${kind}: expected exactly one current record, found ${current.length}.`);
     const record = current[0];
     tenant(record, options.tenantId);
@@ -147,7 +153,7 @@ export async function resolveEditorialContext(client: EditorialClient, options:
       warnings.push("No assignment brief attachment exists; the Assignment summary is supplied as its brief.");
     }
   }
-  return buildEditorialContext(publication, { sectionId, storyLineageId, assignmentId }, entries, warnings, options.maxCharacters ?? 0);
+  return buildEditorialContext(publication, { sectionId, storyLineageId, assignmentId }, entries, warnings, options.maxCharacters ?? 0, missingPublicationDoctrine);
 }
 
 export function assignmentDoctrine(pack: Awaited<ReturnType<typeof resolveEditorialContext>>) {

package/amplify/functions/shared/python-bundle.js

@@ -78,23 +78,29 @@ export function siteFilesContentHash(siteFiles) {
 function pipSpec() {
     return (process.env.PAPYRUS_PIP_SPEC ?? "").trim() || `papyrus-newsroom==${toPep440(papyrusVersion())}`;
 }
+/** What the first pip install gets: `papyrus-newsroom` with its dependencies, plus the function's own requirements. Empty means skip it. */
+export function firstPipRequirements(options) {
+    return [...(options.noDeps ? [] : [pipSpec()]), ...(options.requirements ?? [])];
+}
 function bundleFromPip(outputDir, options) {
     const extra = (process.env.PAPYRUS_PIP_EXTRA_ARGS ?? "").trim().split(/\s+/).filter(Boolean);
     const python = (process.env.PAPYRUS_PIP_PYTHON ?? "python3").trim();
-    execFileSync(python, [
-        "-m", "pip", "install",
-        "--target", outputDir,
-        "--no-cache-dir",
-        "--platform", "manylinux2014_aarch64",
-        "--implementation", "cp",
-        "--python-version", "3.12",
-        "--only-binary=:all:",
-        // Older pip (e.g. a Python 3.9 build image) checks Requires-Python against the host interpreter, not --python-version.
-        "--ignore-requires-python",
-        ...extra,
-        ...(options.noDeps ? [] : [pipSpec()]),
-        ...(options.requirements ?? []),
-    ], { stdio: "inherit" });
+    const requirements = firstPipRequirements(options);
+    if (requirements.length > 0) {
+        execFileSync(python, [
+            "-m", "pip", "install",
+            "--target", outputDir,
+            "--no-cache-dir",
+            "--platform", "manylinux2014_aarch64",
+            "--implementation", "cp",
+            "--python-version", "3.12",
+            "--only-binary=:all:",
+            // Older pip (e.g. a Python 3.9 build image) checks Requires-Python against the host interpreter, not --python-version.
+            "--ignore-requires-python",
+            ...extra,
+            ...requirements,
+        ], { stdio: "inherit" });
+    }
     if (options.noDeps) {
         execFileSync(python, [
             "-m", "pip", "install",

package/amplify/functions/shared/python-bundle.ts

@@ -102,27 +102,34 @@ function pipSpec(): string {
   return (process.env.PAPYRUS_PIP_SPEC ?? "").trim() || `papyrus-newsroom==${toPep440(papyrusVersion())}`;
 }
 
+/** What the first pip install gets: `papyrus-newsroom` with its dependencies, plus the function's own requirements. Empty means skip it. */
+export function firstPipRequirements(options: Pick<PythonBundleOptions, "noDeps" | "requirements">): string[] {
+  return [...(options.noDeps ? [] : [pipSpec()]), ...(options.requirements ?? [])];
+}
+
 function bundleFromPip(outputDir: string, options: PythonBundleOptions): void {
   const extra = (process.env.PAPYRUS_PIP_EXTRA_ARGS ?? "").trim().split(/\s+/).filter(Boolean);
   const python = (process.env.PAPYRUS_PIP_PYTHON ?? "python3").trim();
-  execFileSync(
-    python,
-    [
-      "-m", "pip", "install",
-      "--target", outputDir,
-      "--no-cache-dir",
-      "--platform", "manylinux2014_aarch64",
-      "--implementation", "cp",
-      "--python-version", "3.12",
-      "--only-binary=:all:",
-      // Older pip (e.g. a Python 3.9 build image) checks Requires-Python against the host interpreter, not --python-version.
-      "--ignore-requires-python",
-      ...extra,
-      ...(options.noDeps ? [] : [pipSpec()]),
-      ...(options.requirements ?? []),
-    ],
-    { stdio: "inherit" },
-  );
+  const requirements = firstPipRequirements(options);
+  if (requirements.length > 0) {
+    execFileSync(
+      python,
+      [
+        "-m", "pip", "install",
+        "--target", outputDir,
+        "--no-cache-dir",
+        "--platform", "manylinux2014_aarch64",
+        "--implementation", "cp",
+        "--python-version", "3.12",
+        "--only-binary=:all:",
+        // Older pip (e.g. a Python 3.9 build image) checks Requires-Python against the host interpreter, not --python-version.
+        "--ignore-requires-python",
+        ...extra,
+        ...requirements,
+      ],
+      { stdio: "inherit" },
+    );
+  }
   if (options.noDeps) {
     execFileSync(
       python,

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

@@ -0,0 +1,110 @@
+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 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"]);
+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 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"]);
+    const snapshot = object(raw.snapshot, "snapshot", ["schedule", "intervalHours", "hypeMinimum"]);
+    const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
+    const retirementPoll = flag(raw.retirementPoll, "retirementPoll");
+    if (retirementPoll)
+        throw new Error("reader-steering plugin retirementPoll is not available yet: Prospectus does not serve the retired-subject route");
+    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),
+        },
+        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),
+        },
+        retirementPoll,
+        ...(hypeGap ? { hypeGap } : {}),
+        ...(raw.reservedConcurrency === undefined ? {} : { reservedConcurrency: integer(raw.reservedConcurrency, "reservedConcurrency", 1, 1, 1000) }),
+    };
+}

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

@@ -0,0 +1,153 @@
+import type { PluginRequest } from "../types";
+
+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 COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
+
+export type ReaderSteeringConfig = {
+  /** The IAM role of the CMS app's server runtime (the `CmsComputeRoleArn` output of the app-shell stack): the only caller of reader-actions. */
+  computeRoleArn: string;
+  /** Rating dimensions of the publication, such as `real` and `useful`. `up` and `used-it` are always available. */
+  dimensions: string[];
+  limits: {
+    /** Votes and ratings one reader may make in a clock hour. */
+    actionsPerHour: number;
+    /** Readers whose profile is younger than this many hours get `actionsPerHour / newAccountDivisor`. */
+    newAccountHours: number;
+    newAccountDivisor: number;
+  };
+  /** Handles nobody may take, on top of the built-in list. Lowercase. */
+  reservedHandles: string[];
+  karma: { upvoteWeight: number; usedItWeight: number };
+  ranking: {
+    /** Front: the editor composite loses half its weight every this many hours. */
+    halfLifeHours: number;
+    /** Rising counts upvotes in this window. */
+    risingWindowHours: number;
+    /** Reader ratings per item needed before the reader composite counts in Front. */
+    readerMinimum: number;
+    /** Weight of the editor composite in Front once readers have rated (the reader composite gets the rest). */
+    editorWeight: number;
+  };
+  snapshot: {
+    /** An EventBridge rule runs the snapshot every `intervalHours`. Off by default. */
+    schedule: boolean;
+    intervalHours: number;
+    /** A hype gap needs at least this many ratings on every dimension involved. */
+    hypeMinimum: number;
+  };
+  /**
+   * The hype gap is `mean(plus dimensions) - mean(minus dimensions)`, computed for reader means and for editor scores.
+   * Absent means no hype gap is published. Shipped sets plus = notable, novel and minus = real, useful.
+   */
+  hypeGap?: { plus: string[]; minus: string[] };
+  /**
+   * Reserved concurrency for reader-actions. Unset by default, which reserves nothing: an account with a small total
+   * Lambda concurrency quota (papyrus-production has 10) cannot reserve any without dropping below its unreserved minimum.
+   */
+  reservedConcurrency?: number;
+  /** The Prospectus retired-subject poll is not live: this flag stays false and the run's step is a no-op. */
+  retirementPoll: boolean;
+};
+
+const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap"]);
+
+function object(raw: unknown, label: string, known: string[]): Record<string, unknown> {
+  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 as Record<string, unknown>;
+}
+
+function integer(raw: unknown, label: string, fallback: number, minimum: number, maximum: number): number {
+  const value = raw === undefined ? fallback : raw;
+  if (!Number.isInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new Error(`reader-steering plugin ${label} must be an integer from ${minimum} to ${maximum}`);
+  }
+  return value as number;
+}
+
+function number(raw: unknown, label: string, fallback: number, minimum: number, maximum: number): number {
+  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: unknown, label: string): boolean {
+  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: unknown, label: string, pattern: RegExp): string[] {
+  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 as string[])];
+}
+
+function resolveHypeGap(raw: unknown, dimensions: string[]): { plus: string[]; minus: string[] } | undefined {
+  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: PluginRequest): ReaderSteeringConfig {
+  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"]);
+  const snapshot = object(raw.snapshot, "snapshot", ["schedule", "intervalHours", "hypeMinimum"]);
+  const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
+  const retirementPoll = flag(raw.retirementPoll, "retirementPoll");
+  if (retirementPoll) throw new Error("reader-steering plugin retirementPoll is not available yet: Prospectus does not serve the retired-subject route");
+  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),
+    },
+    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),
+    },
+    retirementPoll,
+    ...(hypeGap ? { hypeGap } : {}),
+    ...(raw.reservedConcurrency === undefined ? {} : { reservedConcurrency: integer(raw.reservedConcurrency, "reservedConcurrency", 1, 1, 1000) }),
+  };
+}