@anthusai/papyrus 5.19.1 → 5.20.0

package/amplify/data/resource.js

@@ -856,6 +856,7 @@ const schema = a.schema({
         storyLineageId: a.id(),
         assignmentId: a.id(),
         maxCharacters: a.integer(),
+        optionalPublicationDoctrine: a.boolean(),
     })
         .returns(a.json().required())
         .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/data/resource.ts

@@ -931,6 +931,7 @@ const schema = a.schema({
       storyLineageId: a.id(),
       assignmentId: a.id(),
       maxCharacters: a.integer(),
+      optionalPublicationDoctrine: a.boolean(),
     })
     .returns(a.json().required())
     .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/data/schema.js

@@ -781,6 +781,7 @@ function buildBaseDefinitions(includeEditions) {
             storyLineageId: a.id(),
             assignmentId: a.id(),
             maxCharacters: a.integer(),
+            optionalPublicationDoctrine: a.boolean(),
         })
             .returns(a.json().required())
             .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/data/schema.ts

@@ -854,6 +854,7 @@ const definitions = {
       storyLineageId: a.id(),
       assignmentId: a.id(),
       maxCharacters: a.integer(),
+      optionalPublicationDoctrine: a.boolean(),
     })
     .returns(a.json().required())
     .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/functions/assignment-action/data-access.js

@@ -9,6 +9,8 @@ export const ASSIGNMENT_DATA_FIELDS = [
     "Query/fields/getProcedureDefinition",
     "Query/fields/getModelAttachment",
     "Query/fields/getNewsroomSection",
+    "Query/fields/listNewsroomSections",
+    "Query/fields/listNewsroomSectionsByTenantAndSortOrder",
     "Query/fields/getKnowledgeCorpus",
     "Query/fields/getKnowledgeImportRun",
     "Query/fields/getReference",

package/amplify/functions/assignment-action/data-access.ts

@@ -11,6 +11,8 @@ export const ASSIGNMENT_DATA_FIELDS = [
   "Query/fields/getProcedureDefinition",
   "Query/fields/getModelAttachment",
   "Query/fields/getNewsroomSection",
+  "Query/fields/listNewsroomSections",
+  "Query/fields/listNewsroomSectionsByTenantAndSortOrder",
   "Query/fields/getKnowledgeCorpus",
   "Query/fields/getKnowledgeImportRun",
   "Query/fields/getReference",

package/amplify/functions/assignment-action/handler.ts

@@ -316,7 +316,7 @@ async function listAssignmentsForObject(event: Parameters<Schema["listAssignment
   return contexts;
 }
 
-async function editorialContext(client: DataClient, scope: { publicationKey?: string; sectionId?: string | null; storyLineageId?: string | null; assignmentId?: string | null; maxCharacters?: number | null }) {
+async function editorialContext(client: DataClient, scope: { publicationKey?: string; sectionId?: string | null; storyLineageId?: string | null; assignmentId?: string | null; maxCharacters?: number | null; optionalPublicationDoctrine?: boolean | null }) {
   if (!editorialEndpoint) throw new Error("Editorial context requires the configured backend endpoint.");
   return resolveEditorialContext(client as unknown as EditorialClient, {
     ...scope, endpoint: editorialEndpoint, tenantId: tenantIdFromEnvironment(), readAttachment: readEditorialAttachment,

package/amplify/functions/content-actions/handler.py

@@ -9,6 +9,7 @@ from papyrus_content.graphql_authoring import create_authoring_client
 from papyrus_content.markus_renderer.derive import derive_body
 from papyrus_content.projection.deploy_render import deploy_render, drift_metric_line
 from papyrus_content.projection.engine import project, project_all, project_item_pages
+from papyrus_content.reader_steering.task import TASK_NAME as READER_SNAPSHOT_TASK, run_reader_snapshot
 from papyrus_content.projection.runtime import (
     DEAD_LETTER_QUEUE_ENV,
     context_from_environment,
@@ -187,6 +188,8 @@ def run_projection_task(task: dict) -> dict:
         report = project_all(projection_context(client))
     elif task.get("task") == "deploy-render":
         return run_deploy_render_task(client)
+    elif task.get("task") == READER_SNAPSHOT_TASK:
+        return run_reader_snapshot(projection_context(client), client, poll_retirements=task.get("retirementPoll") is True).to_dict()
     elif task.get("task") == "invalidate":
         invalidate = projection_context(client).invalidate
         if invalidate is None:

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

@@ -13,6 +13,10 @@ 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, and a
+   * section value that matches no NewsroomSection yields missingSectionConfiguration instead of an error.
+   * Only the editorial check asks for this (its rule lane needs neither); more than one current record is still an error. */
+  optionalPublicationDoctrine?: boolean | null;
   readAttachment: (attachment: EditorialRecord) => Promise<string>;
 };
 
@@ -38,6 +42,47 @@ async function get(client: EditorialClient, model: string, id: string) {
   return row;
 }
 
+const slugOf = (value: string) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+const localPart = (id: string) => id.split("#").at(-1) ?? id;
+
+async function allSections(client: EditorialClient) {
+  const rows: EditorialRecord[] = [];
+  let nextToken: string | null | undefined;
+  do {
+    const response = checked(await client.models.NewsroomSection.list({ limit: 100, nextToken }), "read NewsroomSection list");
+    rows.push(...(response.data as EditorialRecord[] ?? []));
+    nextToken = response.nextToken;
+  } while (nextToken);
+  return rows;
+}
+
+/** An item stores its section as an id, a slug or a name; find the NewsroomSection of this publication it means.
+ * Order: id (as given, then tenant-scoped), then slug (the id's local part), then name (title or short title).
+ * Returns null when nothing matches; two sections matching at the same step is an error. */
+async function findSection(client: EditorialClient, value: string, tenantId?: string) {
+  const direct = checked(await client.models.NewsroomSection.get({ id: value }), "read NewsroomSection").data as EditorialRecord | null;
+  if (direct) return direct;
+  if (tenantId) {
+    const scoped = checked(await client.models.NewsroomSection.get({ id: tenantScopedValue(tenantId, value) }), "read NewsroomSection").data as EditorialRecord | null;
+    if (scoped) return scoped;
+  }
+  const all = tenantId
+    ? await pages(client, "NewsroomSection", "listNewsroomSectionsByTenantAndSortOrder", { tenantId })
+    : (await allSections(client)).filter(row => !row.tenantId);
+  const wanted = slugOf(value);
+  const steps: ((row: EditorialRecord) => boolean)[] = [
+    row => slugOf(localPart(String(row.id ?? ""))) === wanted,
+    row => [row.title, row.shortTitle].some(name => typeof name === "string" && name.trim().toLowerCase() === value.trim().toLowerCase()),
+    row => [row.title, row.shortTitle].some(name => typeof name === "string" && slugOf(name) === wanted),
+  ];
+  for (const step of steps) {
+    const matches = all.filter(step);
+    if (matches.length > 1) throw new Error(`Section "${value}" is ambiguous: ${matches.map(row => row.id).join(", ")}.`);
+    if (matches.length === 1) return matches[0];
+  }
+  return null;
+}
+
 function tenant(row: EditorialRecord, tenantId?: string) {
   if ((row.tenantId || null) !== (tenantId || null)) throw new Error("Editorial record tenant does not match the configured authoring scope.");
 }
@@ -55,7 +100,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[] = [], missingSectionConfiguration: 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 +110,9 @@ 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 } : {}),
+    ...(missingSectionConfiguration.length ? { missingSectionConfiguration } : {}) };
   return { ...payload, contextHash: digest(JSON.stringify(canonical(payload))), resolvedAt: new Date().toISOString() };
 }
 
@@ -83,7 +130,10 @@ 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 requestedSection: string | null = null;
+  const missingSectionConfiguration: string[] = [];
   let storyLineageId = options.storyLineageId || null;
   const assignmentId = options.assignmentId || null;
   let assignment: EditorialRecord | undefined;
@@ -110,6 +160,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);
@@ -118,13 +169,19 @@ export async function resolveEditorialContext(client: EditorialClient, options:
     entries.push(entry("publication", kind, text, record));
   }
   if (sectionId) {
-    const section = await get(client, "NewsroomSection", sectionId);
+    const section = await findSection(client, sectionId, options.tenantId);
+    if (!section && !options.optionalPublicationDoctrine) throw new Error(`NewsroomSection not found: ${sectionId}`);
+    if (!section) { missingSectionConfiguration.push(sectionId); requestedSection = sectionId; sectionId = null; }
+    else {
     tenant(section, options.tenantId);
+    if (section.id !== sectionId) requestedSection = sectionId;
+    sectionId = section.id;
     for (const [kind, key] of [["mission", "editorialMission"], ["policy", "editorialPolicy"], ["guidance", "assignmentGuidance"], ["kill criteria", "killCriteria"]]) {
       const text = String(section[key] || "").trim();
       if (text) entries.push(entry("section", kind, text, section));
       else if (kind === "mission" || kind === "policy") warnings.push(`Section ${section.id} intentionally has an empty ${kind} slot; publication doctrine still applies.`);
     }
+    }
   }
   if (assignment) {
     if (options.tenantId && !storyLineageId && !sectionId) throw new Error("A tenant assignment needs a scoped story or section to establish its publication.");
@@ -147,7 +204,9 @@ 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);
+  // requestedSection: the value the caller asked for when it was not the section's id (a slug or name, or nothing matched).
+  const scope = { sectionId, storyLineageId, assignmentId, ...(requestedSection ? { requestedSection } : {}) };
+  return buildEditorialContext(publication, scope, entries, warnings, options.maxCharacters ?? 0, missingPublicationDoctrine, missingSectionConfiguration);
 }
 
 export function assignmentDoctrine(pack: Awaited<ReturnType<typeof resolveEditorialContext>>) {

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

@@ -0,0 +1,111 @@
+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 && !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),
+        },
+        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,158 @@
+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;
+  /**
+   * Poll Prospectus for retired reader subjects in each scheduled snapshot run (requires `snapshot.schedule`, and a site
+   * whose app-shell sets `cms.readerRetirementPoll`). Off by default.
+   */
+  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 && !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),
+    },
+    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) }),
+  };
+}