@anthusai/papyrus 1.0.0-next.53 → 1.0.0-next.55

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

@@ -7,6 +7,7 @@ from typing import Any
 from papyrus_content.edge_invalidation import distribution_ids_from_environment, invalidate_revalidated_paths
 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.projection.runtime import (
     DEAD_LETTER_QUEUE_ENV,
@@ -146,6 +147,18 @@ def schedule_unpurged_invalidation(keys: list[str]) -> None:
     schedule_projection_task({"task": "invalidate", "keys": keys}, "edge invalidation failed")
 
 
+def run_deploy_render_task(client) -> dict:
+    """Render every published page after a backend deploy, then report drift (a dry run: nothing is deleted)."""
+    context = projection_context(client)
+    report = deploy_render(context)
+    print(drift_metric_line(report))
+    if report.render.unpurged:
+        schedule_unpurged_invalidation(report.render.unpurged)
+    if not report.ok:
+        raise ProjectionTaskFailed("; ".join([*report.render.errors, *report.drift.errors]))
+    return report.to_dict()
+
+
 def run_projection_task(task: dict) -> dict:
     """An asynchronous projection task. Raising makes Lambda retry it, then send the event to the dead letter queue."""
     client, _claims = create_authoring_client()
@@ -157,8 +170,8 @@ def run_projection_task(task: dict) -> dict:
             schedule_projection_task({"task": "item-pages", "exceptItemId": task["itemId"]}, "follow-up")
     elif task.get("task") == "all":
         report = project_all(projection_context(client))
-    elif task.get("task") == "all":
-        report = project_all(projection_context(client))
+    elif task.get("task") == "deploy-render":
+        return run_deploy_render_task(client)
     elif task.get("task") == "invalidate":
         invalidate = projection_context(client).invalidate
         if invalidate is None:

package/amplify/publication/reproject-on-deploy.js

@@ -1,31 +1,73 @@
+import { CustomResource, Duration } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
 import { PolicyStatement } from "aws-cdk-lib/aws-iam";
-import { AwsCustomResource, AwsCustomResourcePolicy, PhysicalResourceId } from "aws-cdk-lib/custom-resources";
-export const REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS = 300;
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import { Provider } from "aws-cdk-lib/custom-resources";
+export const REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS = 900;
+export const DEPLOY_RENDER_METRIC_NAMESPACE = "Papyrus/Projection";
+export const DEPLOY_RENDER_DRIFT_METRIC_NAME = "DeployRenderDrift";
+export const DEPLOY_RENDER_TASK = "deploy-render";
+const FAILURE_MESSAGE_LIMIT = 600;
+const RESULT_SUMMARY_LIMIT = 900;
 export function reprojectDeployToken(environment, now = Date.now) {
     const buildJobId = (environment.AWS_JOB_ID ?? "").trim();
     return buildJobId !== "" ? `job-${buildJobId}` : `time-${now()}`;
 }
 /**
- * Starts the content-actions `all` projection task (asynchronously) every time the stack deploys.
- * The token is in the request, so CloudFormation sees a changed property on each deploy.
+ * Runs inside the deploy: invokes the content-actions Lambda synchronously, so a render that fails fails the
+ * stack update (and with it the Amplify build) with the failure in the build log. The Lambda's result, which
+ * includes the drift check, is written to its log and returned as the resource's data.
+ */
+export const DEPLOY_RENDER_HANDLER_SOURCE = `
+const { LambdaClient, InvokeCommand } = require("@aws-sdk/client-lambda");
+
+exports.handler = async (event) => {
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  const properties = event.ResourceProperties;
+  const client = new LambdaClient({ maxAttempts: 1 });
+  const response = await client.send(new InvokeCommand({
+    FunctionName: properties.FunctionName,
+    InvocationType: "RequestResponse",
+    Payload: JSON.stringify({ projectionTask: { task: properties.Task, deployToken: properties.DeployToken } }),
+  }));
+  const text = Buffer.from(response.Payload || []).toString("utf8");
+  console.log("deploy render result: " + text);
+  if (response.FunctionError) {
+    throw new Error("The post-deploy render failed (" + response.FunctionError + "): " + text.slice(0, ${FAILURE_MESSAGE_LIMIT}));
+  }
+  return { PhysicalResourceId: "reproject-" + properties.DeployToken, Data: { Result: text.slice(0, ${RESULT_SUMMARY_LIMIT}) } };
+};
+`;
+/**
+ * Renders every published page after each backend deploy and checks the site store for drift (a dry run:
+ * nothing is deleted). The token is a property, so CloudFormation runs the resource again on every deploy.
  */
 export function addReprojectOnDeploy(stack, contentActions, deployToken) {
-    const invocation = {
-        service: "Lambda",
-        action: "invoke",
-        parameters: {
-            FunctionName: contentActions.functionName,
-            InvocationType: "Event",
-            Payload: JSON.stringify({ projectionTask: { task: "all", deployToken } }),
-        },
-        physicalResourceId: PhysicalResourceId.of(`reproject-${deployToken}`),
-    };
-    return new AwsCustomResource(stack, "ReprojectOnDeploy", {
-        onCreate: invocation,
-        onUpdate: invocation,
-        installLatestAwsSdk: false,
-        policy: AwsCustomResourcePolicy.fromStatements([
-            new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [contentActions.functionArn] }),
-        ]),
+    const handler = new lambda.Function(stack, "DeployRenderHandler", {
+        runtime: lambda.Runtime.NODEJS_20_X,
+        handler: "index.handler",
+        code: lambda.Code.fromInline(DEPLOY_RENDER_HANDLER_SOURCE),
+        timeout: Duration.seconds(REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS),
+        description: "Starts the post-deploy render of the site and fails the deploy if it cannot finish.",
+    });
+    handler.addToRolePolicy(new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [contentActions.functionArn] }));
+    const provider = new Provider(stack, "DeployRenderProvider", { onEventHandler: handler });
+    new cloudwatch.Alarm(stack, "DeployRenderDriftAlarm", {
+        metric: new cloudwatch.Metric({
+            namespace: DEPLOY_RENDER_METRIC_NAMESPACE,
+            metricName: DEPLOY_RENDER_DRIFT_METRIC_NAME,
+            dimensionsMap: { FunctionName: contentActions.functionName },
+            statistic: "Maximum",
+            period: Duration.days(1),
+        }),
+        evaluationPeriods: 1,
+        threshold: 1,
+        comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+        alarmDescription: "The last post-deploy render found drift between the published content and the site store (stale pages, orphan pages or redirects). Nothing was deleted; run papyrus ops content project --reconcile to repair.",
+    });
+    return new CustomResource(stack, "ReprojectOnDeploy", {
+        serviceToken: provider.serviceToken,
+        properties: { FunctionName: contentActions.functionName, Task: DEPLOY_RENDER_TASK, DeployToken: deployToken },
     });
 }

package/amplify/publication/reproject-on-deploy.ts

@@ -1,9 +1,15 @@
-import { Stack } from "aws-cdk-lib";
+import { CustomResource, Duration, Stack } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
 import { PolicyStatement } from "aws-cdk-lib/aws-iam";
-import type { IFunction } from "aws-cdk-lib/aws-lambda";
-import { AwsCustomResource, AwsCustomResourcePolicy, PhysicalResourceId } from "aws-cdk-lib/custom-resources";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import { Provider } from "aws-cdk-lib/custom-resources";
 
-export const REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS = 300;
+export const REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS = 900;
+export const DEPLOY_RENDER_METRIC_NAMESPACE = "Papyrus/Projection";
+export const DEPLOY_RENDER_DRIFT_METRIC_NAME = "DeployRenderDrift";
+export const DEPLOY_RENDER_TASK = "deploy-render";
+const FAILURE_MESSAGE_LIMIT = 600;
+const RESULT_SUMMARY_LIMIT = 900;
 
 export function reprojectDeployToken(environment: Record<string, string | undefined>, now: () => number = Date.now): string {
   const buildJobId = (environment.AWS_JOB_ID ?? "").trim();
@@ -11,26 +17,62 @@ export function reprojectDeployToken(environment: Record<string, string | undefi
 }
 
 /**
- * Starts the content-actions `all` projection task (asynchronously) every time the stack deploys.
- * The token is in the request, so CloudFormation sees a changed property on each deploy.
+ * Runs inside the deploy: invokes the content-actions Lambda synchronously, so a render that fails fails the
+ * stack update (and with it the Amplify build) with the failure in the build log. The Lambda's result, which
+ * includes the drift check, is written to its log and returned as the resource's data.
  */
-export function addReprojectOnDeploy(stack: Stack, contentActions: IFunction, deployToken: string): AwsCustomResource {
-  const invocation = {
-    service: "Lambda",
-    action: "invoke",
-    parameters: {
-      FunctionName: contentActions.functionName,
-      InvocationType: "Event",
-      Payload: JSON.stringify({ projectionTask: { task: "all", deployToken } }),
-    },
-    physicalResourceId: PhysicalResourceId.of(`reproject-${deployToken}`),
-  };
-  return new AwsCustomResource(stack, "ReprojectOnDeploy", {
-    onCreate: invocation,
-    onUpdate: invocation,
-    installLatestAwsSdk: false,
-    policy: AwsCustomResourcePolicy.fromStatements([
-      new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [contentActions.functionArn] }),
-    ]),
+export const DEPLOY_RENDER_HANDLER_SOURCE = `
+const { LambdaClient, InvokeCommand } = require("@aws-sdk/client-lambda");
+
+exports.handler = async (event) => {
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  const properties = event.ResourceProperties;
+  const client = new LambdaClient({ maxAttempts: 1 });
+  const response = await client.send(new InvokeCommand({
+    FunctionName: properties.FunctionName,
+    InvocationType: "RequestResponse",
+    Payload: JSON.stringify({ projectionTask: { task: properties.Task, deployToken: properties.DeployToken } }),
+  }));
+  const text = Buffer.from(response.Payload || []).toString("utf8");
+  console.log("deploy render result: " + text);
+  if (response.FunctionError) {
+    throw new Error("The post-deploy render failed (" + response.FunctionError + "): " + text.slice(0, ${FAILURE_MESSAGE_LIMIT}));
+  }
+  return { PhysicalResourceId: "reproject-" + properties.DeployToken, Data: { Result: text.slice(0, ${RESULT_SUMMARY_LIMIT}) } };
+};
+`;
+
+/**
+ * Renders every published page after each backend deploy and checks the site store for drift (a dry run:
+ * nothing is deleted). The token is a property, so CloudFormation runs the resource again on every deploy.
+ */
+export function addReprojectOnDeploy(stack: Stack, contentActions: lambda.IFunction, deployToken: string): CustomResource {
+  const handler = new lambda.Function(stack, "DeployRenderHandler", {
+    runtime: lambda.Runtime.NODEJS_20_X,
+    handler: "index.handler",
+    code: lambda.Code.fromInline(DEPLOY_RENDER_HANDLER_SOURCE),
+    timeout: Duration.seconds(REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS),
+    description: "Starts the post-deploy render of the site and fails the deploy if it cannot finish.",
+  });
+  handler.addToRolePolicy(new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [contentActions.functionArn] }));
+  const provider = new Provider(stack, "DeployRenderProvider", { onEventHandler: handler });
+  new cloudwatch.Alarm(stack, "DeployRenderDriftAlarm", {
+    metric: new cloudwatch.Metric({
+      namespace: DEPLOY_RENDER_METRIC_NAMESPACE,
+      metricName: DEPLOY_RENDER_DRIFT_METRIC_NAME,
+      dimensionsMap: { FunctionName: contentActions.functionName },
+      statistic: "Maximum",
+      period: Duration.days(1),
+    }),
+    evaluationPeriods: 1,
+    threshold: 1,
+    comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+    treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+    alarmDescription:
+      "The last post-deploy render found drift between the published content and the site store (stale pages, orphan pages or redirects). Nothing was deleted; run papyrus ops content project --reconcile to repair.",
+  });
+  return new CustomResource(stack, "ReprojectOnDeploy", {
+    serviceToken: provider.serviceToken,
+    properties: { FunctionName: contentActions.functionName, Task: DEPLOY_RENDER_TASK, DeployToken: deployToken },
   });
 }

package/components/amplify-client-provider.tsx

@@ -15,6 +15,7 @@ let configured = false;
 
 export function configureAmplifyClient() {
   if (configured) return;
+  if (typeof window === "undefined") return;
   assertSandboxAmplifyOutputsForDev(amplifyOutputs as Record<string, unknown>);
   Amplify.configure(prioritizeCurrentOrigin(amplifyOutputs as ResourcesConfig), { ssr: true });
   applyClientTokenStorageForCurrentProtocol();

package/lib/amplify-server-runtime.ts

@@ -1,6 +1,13 @@
 import fs from "node:fs";
 import { createServerRunner } from "@aws-amplify/adapter-nextjs";
 import { Amplify, type ResourcesConfig } from "aws-amplify";
+import {
+  createAWSCredentialsAndIdentityIdProvider,
+  createUserPoolsTokenProvider,
+  runWithAmplifyServerContext as runWithAmplifyContext,
+} from "aws-amplify/adapter-core";
+import { sharedInMemoryStorage } from "aws-amplify/utils";
+import { createSharedCredentialsProvider } from "./shared-credentials-provider";
 import { assertSandboxAmplifyOutputsForDev } from "./amplify-outputs-guard";
 import { getAmplifyOutputsPath } from "./amplify-outputs-path";
 
@@ -14,14 +21,42 @@ export function getAmplifyServerRuntime(): AmplifyServerRuntime {
   if (cachedRuntime) return cachedRuntime;
 
   const config = loadAmplifyOutputs();
-  Amplify.configure(config, { ssr: true });
   cachedRuntime = {
     ...createServerRunner({ config }),
     config,
   };
+  Amplify.configure(config, config.Auth ? { ssr: true, Auth: getGuestProviders(config) } : { ssr: true });
   return cachedRuntime;
 }
 
+type GuestProviders = {
+  credentialsProvider: ReturnType<typeof createAWSCredentialsAndIdentityIdProvider>;
+  tokenProvider: ReturnType<typeof createUserPoolsTokenProvider>;
+};
+
+const GUEST_PROVIDERS_KEY = Symbol.for("papyrus.guestAmplifyProviders");
+
+function getGuestProviders(config: ResourcesConfig): GuestProviders {
+  const holder = globalThis as unknown as Record<symbol, GuestProviders | undefined>;
+  const existing = holder[GUEST_PROVIDERS_KEY];
+  if (existing) return existing;
+  const auth = config.Auth as NonNullable<ResourcesConfig["Auth"]>;
+  const created: GuestProviders = {
+    credentialsProvider: createSharedCredentialsProvider(
+      createAWSCredentialsAndIdentityIdProvider(auth, sharedInMemoryStorage),
+    ),
+    tokenProvider: createUserPoolsTokenProvider(auth, sharedInMemoryStorage),
+  };
+  holder[GUEST_PROVIDERS_KEY] = created;
+  return created;
+}
+
+export function runWithGuestAmplifyContext<T>(operation: (contextSpec: Parameters<Parameters<typeof runWithAmplifyContext>[2]>[0]) => Promise<T>): Promise<T> {
+  const { config } = getAmplifyServerRuntime();
+  if (!config.Auth) return runWithAmplifyContext(config, {}, operation) as Promise<T>;
+  return runWithAmplifyContext(config, { Auth: getGuestProviders(config) }, operation) as Promise<T>;
+}
+
 export function hasAmplifyOutputs(): boolean {
   return fs.existsSync(getAmplifyOutputsPath());
 }

package/lib/graphql-content-repository.ts

@@ -3,7 +3,7 @@ import { generateClient } from "aws-amplify/data";
 import type { Schema } from "../amplify/data/resource";
 import type { Article, ArticleImage, ArticleImageAsset, ArticleImageLayout, ArticleImageThemeVariants, ArticleVideoAsset, ArticleVideoThemeVariants } from "./articles";
 import { withContentLoadTiming } from "./content-load-timing";
-import { getAmplifyServerRuntime } from "./amplify-server-runtime";
+import { getAmplifyServerRuntime, runWithGuestAmplifyContext } from "./amplify-server-runtime";
 import { resolveReaderStorageUrl, signStorageUrl } from "./reader-storage-url";
 import type { ContentRepository, EditionContent, EditionRouteSummary, ListPublishedEditionsOptions, LoadEditionContentOptions } from "./content-types";
 import { isDemoAmplifyOutputs } from "./demo-amplify-outputs";
@@ -21,6 +21,7 @@ import { SITE_BRAND } from "./site-brand";
 import { shouldFetchVideoScripts } from "./video-mode";
 import { collectVideoScriptTargets, parseVideoScriptRef, videomlItemSlug, type VideoScriptRef } from "./video-script";
 import { currentContentSource, currentRequestClient, runWithContentSource } from "./content-source-context";
+import { withRateLimitRetry } from "./rate-limit-retry";
 import { getContentSource } from "./site-env";
 
 const DEFAULT_EDITION_SLUG = "current";
@@ -133,10 +134,9 @@ const IMAGE_ROLES: NonNullable<ArticleImageAsset["roles"]> = [
   "thumbnail",
 ];
 
-let readerContextClient: DataClient | null = null;
 let buildTimeClient: DataClient | null = null;
 
-function authMode(): "userPool" | "identityPool" {
+export function authMode(): "userPool" | "identityPool" {
   return currentContentSource() === "drafts" ? "userPool" : "identityPool";
 }
 
@@ -146,7 +146,7 @@ function isVisibleItemStatus(status: string): boolean {
 }
 
 async function withReaderGraphQLContext<T>(operation: () => Promise<T>): Promise<T> {
-  const { runWithAmplifyServerContext, config } = getAmplifyServerRuntime();
+  const { config } = getAmplifyServerRuntime();
   const source = getContentSource();
   if (source === "drafts") {
     // Drafts are read as the signed-in visitor: the client reads the session from the request cookies, and it is
@@ -156,18 +156,10 @@ async function withReaderGraphQLContext<T>(operation: () => Promise<T>): Promise
     const client = generateServerClientUsingCookies<Schema>({ config, cookies, authMode: "userPool" });
     return runWithContentSource(source, operation, client);
   }
-  return runWithContentSource(source, () =>
-    runWithAmplifyServerContext({
-      nextServerContext: null,
-      operation: async () => {
-        readerContextClient = generateClient<Schema>({ authMode: authMode() });
-        try {
-          return await operation();
-        } finally {
-          readerContextClient = null;
-        }
-      },
-    }),
+  return withRateLimitRetry(() =>
+    runWithGuestAmplifyContext(() =>
+      runWithContentSource(source, operation, generateClient<Schema>({ authMode: authMode() })),
+    ),
   );
 }
 
@@ -257,7 +249,6 @@ export const graphqlContentRepository: ContentRepository = {
 function getClient(): DataClient {
   const requestClient = currentRequestClient<DataClient>();
   if (requestClient) return requestClient;
-  if (readerContextClient) return readerContextClient;
 
   if (!buildTimeClient) {
     getAmplifyServerRuntime();

package/lib/rate-limit-retry.ts

@@ -0,0 +1,55 @@
+export const RATE_LIMIT_RETRY_ATTEMPTS = 14;
+export const RATE_LIMIT_RETRY_BASE_MILLISECONDS = 500;
+export const RATE_LIMIT_RETRY_CAP_MILLISECONDS = 20_000;
+export const RATE_LIMIT_RETRY_BUDGET_MILLISECONDS = 120_000;
+
+export function isRateLimitError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const { name, message } = error as { name?: unknown; message?: unknown };
+  const text = `${typeof name === "string" ? name : ""} ${typeof message === "string" ? message : ""}`;
+  return /TooManyRequests|ThrottlingException|Rate exceeded|Unauthorized[\s\S]*set the \\?"authMode\\?"/i.test(text);
+}
+
+export type RateLimitRetryOptions = {
+  attempts?: number;
+  baseMilliseconds?: number;
+  capMilliseconds?: number;
+  budgetMilliseconds?: number;
+  sleep?: (milliseconds: number) => Promise<void>;
+  random?: () => number;
+  now?: () => number;
+};
+
+export function fullJitterDelayMilliseconds(
+  attempt: number,
+  baseMilliseconds: number,
+  capMilliseconds: number,
+  random: () => number,
+): number {
+  const ceiling = Math.min(capMilliseconds, baseMilliseconds * 2 ** (attempt - 1));
+  return random() * ceiling;
+}
+
+export async function withRateLimitRetry<T>(
+  operation: () => Promise<T>,
+  options: RateLimitRetryOptions = {},
+): Promise<T> {
+  const attempts = options.attempts ?? RATE_LIMIT_RETRY_ATTEMPTS;
+  const baseMilliseconds = options.baseMilliseconds ?? RATE_LIMIT_RETRY_BASE_MILLISECONDS;
+  const capMilliseconds = options.capMilliseconds ?? RATE_LIMIT_RETRY_CAP_MILLISECONDS;
+  const budgetMilliseconds = options.budgetMilliseconds ?? RATE_LIMIT_RETRY_BUDGET_MILLISECONDS;
+  const sleep = options.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt >= attempts || !isRateLimitError(error)) throw error;
+      const delay = fullJitterDelayMilliseconds(attempt, baseMilliseconds, capMilliseconds, random);
+      if (now() - startedAt + delay > budgetMilliseconds) throw error;
+      await sleep(delay);
+    }
+  }
+}

package/lib/reader-storage-url.ts

@@ -1,5 +1,5 @@
 import { getUrl } from "aws-amplify/storage/server";
-import { getAmplifyServerRuntime } from "./amplify-server-runtime";
+import { runWithGuestAmplifyContext } from "./amplify-server-runtime";
 
 const STORAGE_URL_EXPIRES_IN_SECONDS = 60 * 60;
 const STORAGE_URL_CACHE_TTL_MS = 55 * 60 * 1000;
@@ -43,17 +43,14 @@ export async function signStorageUrl(storagePath: string): Promise<string> {
     return cached.url;
   }
 
-  const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
-  const result = await runWithAmplifyServerContext({
-    nextServerContext: null,
-    operation: (contextSpec) =>
-      getUrl(contextSpec, {
-        path: normalized,
-        options: {
-          expiresIn: STORAGE_URL_EXPIRES_IN_SECONDS,
-        },
-      }),
-  });
+  const result = await runWithGuestAmplifyContext((contextSpec) =>
+    getUrl(contextSpec, {
+      path: normalized,
+      options: {
+        expiresIn: STORAGE_URL_EXPIRES_IN_SECONDS,
+      },
+    }),
+  );
   const url = result.url.toString();
   signedUrlCache.set(normalized, {
     expiresAt: Date.now() + STORAGE_URL_CACHE_TTL_MS,

package/lib/shared-credentials-provider.ts

@@ -0,0 +1,61 @@
+import { withRateLimitRetry, type RateLimitRetryOptions } from "./rate-limit-retry";
+
+export const CREDENTIAL_EXPIRY_SAFETY_MILLISECONDS = 5 * 60 * 1000;
+
+export type CredentialsAndIdentityIdLike = {
+  credentials: { expiration?: Date };
+};
+
+export type CredentialsProviderLike<Options, Result extends CredentialsAndIdentityIdLike> = {
+  getCredentialsAndIdentityId(options: Options): Promise<Result | undefined>;
+  clearCredentialsAndIdentityId(): void;
+};
+
+export type SharedCredentialsProviderOptions = {
+  retry?: RateLimitRetryOptions;
+  expirySafetyMilliseconds?: number;
+  now?: () => number;
+};
+
+export function createSharedCredentialsProvider<
+  Options extends { forceRefresh?: boolean },
+  Result extends CredentialsAndIdentityIdLike,
+>(
+  inner: CredentialsProviderLike<Options, Result>,
+  settings: SharedCredentialsProviderOptions = {},
+): CredentialsProviderLike<Options, Result> {
+  const now = settings.now ?? Date.now;
+  const safety = settings.expirySafetyMilliseconds ?? CREDENTIAL_EXPIRY_SAFETY_MILLISECONDS;
+  let cached: Result | undefined;
+  let inflight: Promise<Result | undefined> | undefined;
+
+  const isFresh = (value: Result | undefined): value is Result => {
+    if (!value) return false;
+    const expiration = value.credentials.expiration;
+    return !expiration || expiration.getTime() - safety > now();
+  };
+
+  return {
+    async getCredentialsAndIdentityId(options) {
+      if (!options?.forceRefresh && isFresh(cached)) return cached;
+      if (inflight) return inflight;
+      const request = withRateLimitRetry(() => inner.getCredentialsAndIdentityId(options), {
+        now,
+        ...settings.retry,
+      })
+        .then((result) => {
+          cached = result;
+          return result;
+        })
+        .finally(() => {
+          inflight = undefined;
+        });
+      inflight = request;
+      return request;
+    },
+    clearCredentialsAndIdentityId() {
+      cached = undefined;
+      inner.clearCredentialsAndIdentityId();
+    },
+  };
+}

package/package.json

@@ -197,6 +197,7 @@
     "./lib/pretext-layout": "./lib/pretext-layout.ts",
     "./lib/public-placeholder-config": "./lib/public-placeholder-config.ts",
     "./lib/publication-items": "./lib/publication-items.ts",
+    "./lib/rate-limit-retry": "./lib/rate-limit-retry.ts",
     "./lib/reader-base-path": "./lib/reader-base-path.ts",
     "./lib/reader-cache-lifetime": "./lib/reader-cache-lifetime.ts",
     "./lib/reader-route-config": "./lib/reader-route-config.ts",
@@ -215,6 +216,7 @@
     "./lib/robots-policy": "./lib/robots-policy.ts",
     "./lib/root-route-redirect": "./lib/root-route-redirect.ts",
     "./lib/semantic-graph": "./lib/semantic-graph.ts",
+    "./lib/shared-credentials-provider": "./lib/shared-credentials-provider.ts",
     "./lib/signup-csv": "./lib/signup-csv.ts",
     "./lib/site-brand-tenant": "./lib/site-brand-tenant.ts",
     "./lib/site-brand": "./lib/site-brand.ts",
@@ -309,7 +311,7 @@
       "optional": true
     }
   },
-  "version": "1.0.0-next.53",
+  "version": "1.0.0-next.55",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-sdk/client-cognito-identity-provider": "3.1045.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-next.53",
+  "version": "1.0.0-next.55",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",

package/src/with-papyrus.d.mts

@@ -1,3 +1,11 @@
 import type { NextConfig } from "next";
 export function withPapyrus(nextConfig?: NextConfig, options?: { root?: string }): NextConfig;
 export const READER_EXPIRE_TIME_SECONDS: number;
+export const DEFAULT_STATIC_GENERATION_WORKERS: number;
+export const DEFAULT_STATIC_GENERATION_CONCURRENCY: number;
+export const DEFAULT_STATIC_GENERATION_RETRY_COUNT: number;
+export function staticGenerationSettings(): {
+  cpus: number;
+  staticGenerationMaxConcurrency: number;
+  staticGenerationRetryCount: number;
+};

package/src/with-papyrus.mjs

@@ -10,6 +10,8 @@ import { fileURLToPath } from "node:url";
  *   `papyrus-site-theme` -> ./publication/theme.css when it exists, else the shipped
  *   empty lib/empty-theme.css (both webpack and turbopack),
  * - trace the corpora/ YAML and amplify_outputs.json that the reader reads via fs at runtime,
+ * - cap static generation at 2 workers x 3 pages (override with PAPYRUS_STATIC_GENERATION_WORKERS / _CONCURRENCY) and retry
+ *   failed pages 3 times, so pre-building the reader pages stays under Cognito guest-credential throttles,
  * - carry Papyrus's own server-external packages and image settings.
  */
 const SERVER_EXTERNAL = [
@@ -30,6 +32,24 @@ const SERVER_EXTERNAL = [
  */
 export const READER_EXPIRE_TIME_SECONDS = 120;
 
+export const DEFAULT_STATIC_GENERATION_WORKERS = 2;
+export const DEFAULT_STATIC_GENERATION_CONCURRENCY = 3;
+export const DEFAULT_STATIC_GENERATION_RETRY_COUNT = 3;
+
+function positiveIntegerFromEnvironment(name) {
+  const parsed = Number.parseInt(process.env[name] ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function staticGenerationSettings() {
+  return {
+    cpus: positiveIntegerFromEnvironment("PAPYRUS_STATIC_GENERATION_WORKERS") ?? DEFAULT_STATIC_GENERATION_WORKERS,
+    staticGenerationMaxConcurrency:
+      positiveIntegerFromEnvironment("PAPYRUS_STATIC_GENERATION_CONCURRENCY") ?? DEFAULT_STATIC_GENERATION_CONCURRENCY,
+    staticGenerationRetryCount: DEFAULT_STATIC_GENERATION_RETRY_COUNT,
+  };
+}
+
 export const DEFAULT_TRANSPILE_PACKAGES = ["@anthusai/papyrus", "cyclotron"];
 
 export function mergeTranspilePackages(existing = []) {
@@ -67,7 +87,7 @@ export function withPapyrus(nextConfig = {}, options = {}) {
     serverExternalPackages: [...new Set([...(nextConfig.serverExternalPackages ?? []), ...SERVER_EXTERNAL])],
     outputFileTracingIncludes: mergeOutputFileTracingIncludes(nextConfig.outputFileTracingIncludes),
     images: nextConfig.images ?? { remotePatterns: [{ protocol: "https", hostname: "**" }] },
-    experimental: { devtoolSegmentExplorer: false, ...nextConfig.experimental },
+    experimental: { devtoolSegmentExplorer: false, ...staticGenerationSettings(), ...nextConfig.experimental },
     turbopack: {
       ...nextConfig.turbopack,
       resolveAlias: {