@anthusai/papyrus 5.33.1 → 5.34.0

package/components/topic-steering-workspace.tsx

@@ -40,6 +40,7 @@ import {
   loadEditorReferencesData,
   loadEditorProcedureData,
   loadEditorSemanticRelationsData,
+  loadEditorReferenceReviewDetails,
   loadEditionForumThreads,
   loadNewsroomAssignmentPage,
   loadNewsroomMessagePage,
@@ -167,6 +168,9 @@ import {
 } from "../lib/reference-policy";
 import { isLocalPreviewEnabled } from "../lib/local-preview";
 import { currentRelevanceDecisions } from "../lib/relevance-decisions";
+import { runReferenceReviewRequest } from "../lib/reference-review-request";
+import { useReferenceReviewData } from "../lib/use-reference-review-data";
+import { latestReferenceReviewReasons, latestReferenceReviewSections } from "../lib/reference-review-details";
 import { delegatedCurationsByReference, referencesWithHumanLatestCuration, type ShadowAgreement } from "../lib/cyclotron-suggestions";
 import { createLocalPreviewCyclotronFixtures } from "../lib/local-preview-seed";
 import { createLocalPreviewSectionFixtures } from "../lib/local-preview-section-fixtures";
@@ -670,7 +674,7 @@ export function NewsDeskWorkspace({
     );
   }
 
-  if (session && sessionDashboard) {
+  if (session && sessionDashboard && session.shell.phase !== "loadingDesk") {
     return (
       <NewsDeskDashboard
         analysisProfiles={analysisProfiles}
@@ -902,6 +906,11 @@ function NewsDeskDashboard({
   const [referencesRealtimeStatus, setReferencesRealtimeStatus] = useState<RealtimeSubscriptionStatus>("idle");
   const [referencesRealtimeError, setReferencesRealtimeError] = useState<string | null>(null);
   const referencesRef = useRef(references);
+  const referenceReviewsPending = useRef(new Map<string, Promise<void>>());
+  const [selectedReviewRead, setSelectedReviewRead] = useState<{ lineageId: string; state: "loading" | "ready" | "error"; error: string | null }>({ lineageId: "", state: "ready", error: null });
+  const [selectedReviewAttempt, setSelectedReviewAttempt] = useState(0);
+  const reviewReasons = useMemo(() => latestReferenceReviewReasons(messages), [messages]);
+  const reviewSectionIds = useMemo(() => latestReferenceReviewSections(messages), [messages]);
 
   useEffect(() => {
     referencesRef.current = references;
@@ -1231,17 +1240,6 @@ function NewsDeskDashboard({
     if (dashboard.isDemo) return;
     let active = true;
 
-    if (activeTab === "messages" && !loadedSections.messages) {
-      setLoadedSections((current) => ({ ...current, messages: true }));
-      void loadEditorMessagesData()
-        .then((nextMessages) => {
-          if (active) setMessages(nextMessages);
-        })
-        .catch((error) => {
-          if (active) setActionState({ id: "messages-load", message: error instanceof Error ? error.message : "messages load failed", tone: "error" });
-        });
-    }
-
     if (activeTab === "assignments" && !loadedSections.assignments) {
       setLoadedSections((current) => ({ ...current, assignments: true }));
       void loadEditorAssignmentsData()
@@ -1269,23 +1267,6 @@ function NewsDeskDashboard({
         });
     }
 
-    if ((activeTab === "assignments" || activeTab === "references" || activeTab === "messages") && !loadedSections.semanticRelations) {
-      setLoadedSections((current) => ({ ...current, semanticRelations: true }));
-      void loadEditorSemanticRelationsData()
-        .then((relations) => {
-          if (active) setSemanticRelations(relations);
-        })
-        .catch(() => {
-          if (active) setSemanticRelations([]);
-        });
-      if (!loadedSections.messages) {
-        setLoadedSections((current) => ({ ...current, messages: true }));
-        void loadEditorMessagesData().then((nextMessages) => {
-          if (active) setMessages(nextMessages);
-        }).catch(() => undefined);
-      }
-    }
-
     if ((activeTab === "topics" || activeTab === "desks" || activeTab === "concepts" || activeTab === "administration") && !loadedSections.fullDashboard) {
       setLoadedSections((current) => ({ ...current, fullDashboard: true }));
       void loadEditorFullNewsDeskDashboard({ isAdmin: Boolean(dashboard.canManageUsers) })
@@ -1340,6 +1321,37 @@ function NewsDeskDashboard({
     refreshNewsroomSections,
   ]);
 
+  const needsReferenceReviewData = activeTab === "references" || activeTab === "assignments" || activeTab === "messages";
+  const selectedReviewLineageId = pathname ? pathnameReferenceLineageId ?? "" : initialSelection.reference ?? "";
+  const referenceReviewData = useReferenceReviewData({
+    enabled: canLoadPrivateCorpus && needsReferenceReviewData && !(activeTab === "references" && selectedReviewLineageId),
+    loadRelations: loadEditorSemanticRelationsData,
+    loadMessages: loadEditorMessagesData,
+    onRelations: setSemanticRelations,
+    onMessages: setMessages,
+  });
+
+  useEffect(() => {
+    if (!canLoadPrivateCorpus || activeTab !== "references" || !selectedReviewLineageId) return;
+    let active = true;
+    setSelectedReviewRead({ lineageId: selectedReviewLineageId, state: "loading", error: null });
+    void loadEditorReferenceReviewDetails(selectedReviewLineageId).then(({ relations, messages: history }) => {
+      if (!active) return;
+      setSemanticRelations((current) => [...current.filter((relation) => relation.subjectLineageId !== selectedReviewLineageId || relation.subjectKind !== "reference"), ...relations]);
+      setMessages((current) => [...current.filter((message) => !history.some((entry) => entry.id === message.id)), ...history]);
+      setSelectedReviewRead({ lineageId: selectedReviewLineageId, state: "ready", error: null });
+    }).catch((error) => {
+      if (active) setSelectedReviewRead({ lineageId: selectedReviewLineageId, state: "error", error: error instanceof Error ? error.message : "Reference review details could not be loaded." });
+    });
+    return () => { active = false; };
+  }, [activeTab, canLoadPrivateCorpus, selectedReviewLineageId, selectedReviewAttempt]);
+  const selectedReviewIsCurrent = selectedReviewLineageId && !dashboard.isDemo;
+  const predictionState = selectedReviewIsCurrent
+    ? selectedReviewRead.lineageId === selectedReviewLineageId ? selectedReviewRead.state : "loading"
+    : referenceReviewData.state;
+  const predictionError = selectedReviewIsCurrent ? selectedReviewRead.error : referenceReviewData.error;
+  const retryReferenceReviewData = () => { referenceReviewData.retry(); setSelectedReviewAttempt((current) => current + 1); };
+
   const applyReferenceRecord = useCallback((nextReference: ReferenceRecord) => {
     const { nextRecords, nextRecord, previousRecord } = upsertReferenceRecords(referencesRef.current, nextReference);
     referencesRef.current = nextRecords;
@@ -1594,96 +1606,98 @@ function NewsDeskDashboard({
     reasonCode?: ReferenceRejectionReasonCode | null,
     relevance?: { decisionRelationId: string; shareable: boolean },
     sectionId?: string | null,
-  ) {
-    const nextStatus = referenceCurationStatusForAction(action);
-    setActionState({ id: reference.id, message: `${action} pending`, tone: "pending" });
-    if (dashboard.isDemo) {
-      const now = new Date().toISOString();
-      const messageId = `message-demo-${reference.id}-${action}-${now.replace(/[^0-9]/g, "")}`;
-      const relationId = `semantic-relation-demo-${messageId}`;
-      applyReferenceRecord(buildReviewedReferenceRecord(referencesRef.current, reference, {
-        actorLabel: authState.label,
-        nextStatus,
-        note: note ?? null,
-        now,
-      }));
-      setMessages((current) => [{
-        id: messageId,
-        messageKind: "reference_curation",
-        messageDomain: "commentary",
-        status: "active",
-        body: note?.trim() || `${authState.label} marked this reference ${nextStatus}.`,
-        summary: `${reference.title ?? reference.externalItemId}: ${nextStatus}`,
-        source: "newsroom",
-        authorLabel: authState.label,
-        createdAt: now,
-        updatedAt: now,
-        metadata: {
-          action,
-          curationStatus: nextStatus,
-          reasonCode: action === "reject" ? reasonCode ?? null : null,
-          ...(relevance ? { decisionRelationId: relevance.decisionRelationId, shareable: relevance.shareable } : {}),
-          ...(action === "accept" && sectionId ? { sectionId } : {}),
-        },
-      }, ...current]);
-      setSemanticRelations((current) => [{
-        id: relationId,
-        relationState: "current",
-        predicate: "comment",
-        relationTypeId: "semantic-relation-type-comment",
-        relationTypeKey: "comment",
-        relationDomain: "commentary",
-        subjectKind: "message",
-        subjectId: messageId,
-        subjectLineageId: messageId,
-        subjectVersionNumber: 1,
-        objectKind: "reference",
-        objectId: reference.id,
-        objectLineageId: reference.lineageId ?? reference.id,
-        objectVersionNumber: reference.versionNumber ?? null,
-        subjectStateKey: `message#${messageId}#current`,
-        objectStateKey: `reference#${reference.lineageId ?? reference.id}#current`,
-        objectSubjectStateKey: `reference#${reference.lineageId ?? reference.id}#current#message`,
-        predicateObjectStateKey: `comment#reference#${reference.lineageId ?? reference.id}#current`,
-        subjectVersionKey: `message#${messageId}`,
-        objectVersionKey: `reference#${reference.id}`,
-        rank: 1,
-        reviewRecommended: false,
-        importedAt: now,
-      }, ...current]);
-      setActionState({ id: reference.id, message: `${action} saved`, tone: "ok" });
-      return;
-    }
-    startTransition(() => {
-      void (async () => {
-        try {
-          const response = await dataClient.mutations.reviewReferenceCuration(
-            {
-              referenceId: reference.id,
-              action,
-              actorLabel: authState.label,
-              note: note?.trim() || undefined,
-              reasonCode: action === "reject" ? reasonCode ?? undefined : undefined,
-              decisionRelationId: relevance?.decisionRelationId,
-              shareable: relevance ? relevance.shareable : undefined,
-              sectionId: action === "accept" ? sectionId ?? undefined : undefined,
-            },
-            { authMode: USER_POOL_AUTH_MODE },
-          );
-          const review = assertReferenceReviewMutationSucceeded(response, reference.id);
-          const status = review.status ?? nextStatus;
-          const now = new Date().toISOString();
-          applyReferenceRecord(buildReviewedReferenceRecord(referencesRef.current, reference, {
+  ): Promise<void> {
+    return runReferenceReviewRequest(referenceReviewsPending.current, reference.lineageId ?? reference.id, async () => {
+      if (!canEdit) throw new Error("Your session does not have permission to review references.");
+      const nextStatus = referenceCurationStatusForAction(action);
+      setActionState({ id: reference.id, message: `${action} pending`, tone: "pending" });
+      if (dashboard.isDemo) {
+        const now = new Date().toISOString();
+        const messageId = `message-demo-${reference.id}-${action}-${now.replace(/[^0-9]/g, "")}`;
+        const relationId = `semantic-relation-demo-${messageId}`;
+        applyReferenceRecord(buildReviewedReferenceRecord(referencesRef.current, reference, {
+          actorLabel: authState.label,
+          nextStatus,
+          note: note ?? null,
+          now,
+        }));
+        setMessages((current) => [{
+          id: messageId,
+          messageKind: "reference_curation",
+          messageDomain: "commentary",
+          status: "active",
+          body: note?.trim() || `${authState.label} marked this reference ${nextStatus}.`,
+          summary: `${reference.title ?? reference.externalItemId}: ${nextStatus}`,
+          source: "newsroom",
+          authorLabel: authState.label,
+          createdAt: now,
+          updatedAt: now,
+          metadata: {
+            referenceLineageId: reference.lineageId ?? reference.id,
+            action,
+            curationStatus: nextStatus,
+            reasonCode: action === "reject" ? reasonCode ?? null : null,
+            ...(relevance ? { decisionRelationId: relevance.decisionRelationId, shareable: relevance.shareable } : {}),
+            ...(action === "accept" && sectionId ? { sectionId } : {}),
+          },
+        }, ...current]);
+        setSemanticRelations((current) => [{
+          id: relationId,
+          relationState: "current",
+          predicate: "comment",
+          relationTypeId: "semantic-relation-type-comment",
+          relationTypeKey: "comment",
+          relationDomain: "commentary",
+          subjectKind: "message",
+          subjectId: messageId,
+          subjectLineageId: messageId,
+          subjectVersionNumber: 1,
+          objectKind: "reference",
+          objectId: reference.id,
+          objectLineageId: reference.lineageId ?? reference.id,
+          objectVersionNumber: reference.versionNumber ?? null,
+          subjectStateKey: `message#${messageId}#current`,
+          objectStateKey: `reference#${reference.lineageId ?? reference.id}#current`,
+          objectSubjectStateKey: `reference#${reference.lineageId ?? reference.id}#current#message`,
+          predicateObjectStateKey: `comment#reference#${reference.lineageId ?? reference.id}#current`,
+          subjectVersionKey: `message#${messageId}`,
+          objectVersionKey: `reference#${reference.id}`,
+          rank: 1,
+          reviewRecommended: false,
+          importedAt: now,
+        }, ...current]);
+        setActionState({ id: reference.id, message: `${action} saved`, tone: "ok" });
+        return;
+      }
+      try {
+        const response = await dataClient.mutations.reviewReferenceCuration(
+          {
+            referenceId: reference.id,
+            action,
             actorLabel: authState.label,
-            nextStatus: status,
-            note: note?.trim() || null,
-            now,
-          }));
-          setActionState({ id: reference.id, message: `${action} saved`, tone: "ok" });
-        } catch (error) {
-          setActionState({ id: reference.id, message: error instanceof Error ? error.message : `${action} failed`, tone: "error" });
-        }
-      })();
+            note: note?.trim() || undefined,
+            reasonCode: action === "reject" ? reasonCode ?? undefined : undefined,
+            decisionRelationId: relevance?.decisionRelationId,
+            shareable: relevance ? relevance.shareable : undefined,
+            sectionId: action === "accept" ? sectionId ?? undefined : undefined,
+          },
+          { authMode: USER_POOL_AUTH_MODE },
+        );
+        const review = assertReferenceReviewMutationSucceeded(response, reference.id);
+        const status = review.status ?? nextStatus;
+        const now = new Date().toISOString();
+        applyReferenceRecord(buildReviewedReferenceRecord(referencesRef.current, reference, {
+          actorLabel: authState.label,
+          nextStatus: status,
+          note: note?.trim() || null,
+          now,
+        }));
+        setActionState({ id: reference.id, message: `${action} saved`, tone: "ok" });
+        retryReferenceReviewData();
+      } catch (error) {
+        setActionState({ id: reference.id, message: error instanceof Error ? error.message : `${action} failed`, tone: "error" });
+        throw error;
+      }
     });
   }
 
@@ -3067,7 +3081,6 @@ function NewsDeskDashboard({
             decisions={relevanceDecisions}
             demo={Boolean(dashboard.isDemo)}
             humanCuratedReferenceLineageIds={humanCuratedReferenceLineageIds}
-            messages={messages}
             newsroomSections={newsroomSections}
             references={references}
           />
@@ -3127,7 +3140,7 @@ function NewsDeskDashboard({
           <NewsroomReferencesView
             demo={Boolean(dashboard.isDemo)}
             disabled={controlsDisabled}
-            initialReferenceLineageId={initialSelection.reference ?? pathnameReferenceLineageId}
+            initialReferenceLineageId={selectedReviewLineageId}
             cyclotronStatus={cyclotronStatus}
             cyclotronPriming={{
               labels: primingLabels,
@@ -3139,8 +3152,8 @@ function NewsDeskDashboard({
               },
             }}
             decisions={relevanceDecisions}
-            humanCuratedReferenceLineageIds={humanCuratedReferenceLineageIds}
-            delegatedCurations={delegatedCurations}
+            humanCuratedReferenceLineageIds={selectedReviewIsCurrent && predictionState !== "ready" ? undefined : humanCuratedReferenceLineageIds}
+            delegatedCurations={selectedReviewIsCurrent && predictionState !== "ready" ? undefined : delegatedCurations}
             shadowAgreement={shadowAgreement}
             onRequestReviewRate={relevanceCyclotronId ? async (choice) => {
               const request = buildReviewRateRequest(choice, authState.label);
@@ -3153,11 +3166,19 @@ function NewsDeskDashboard({
               curation.note ?? undefined,
               normalizeReferenceRejectionReasonCode(curation.reasonCode),
               { decisionRelationId: curation.decisionRelationId, shareable: curation.shareable },
+              curation.sectionId,
             )}
             sections={sectionChoices}
             sectionSuggestions={sectionSuggestions}
             sectionAgreement={siteSectionAgreement}
-            onReview={(reference, action, options) => runReferenceCurationAction(reference, action, undefined, undefined, undefined, options?.sectionId)}
+            predictionState={predictionState}
+            predictionError={predictionError}
+            onRetryPredictions={retryReferenceReviewData}
+            reviewReasons={reviewReasons}
+            reviewSectionIds={reviewSectionIds}
+            onReview={(reference, action, options) => runReferenceCurationAction(reference, action, options?.note, options?.reasonCode,
+              options?.decisionRelationId ? { decisionRelationId: options.decisionRelationId, shareable: options.shareable === true } : undefined,
+              options?.sectionId)}
             referenceAttachments={referenceAttachments}
             references={references}
           />

package/infra/amplify-app-shell.js

@@ -2,6 +2,8 @@ import { ArnFormat, CfnOutput, Duration, Fn, Stack } from "aws-cdk-lib";
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
 import { SecureStringParameter } from "./secure-string-parameter.js";
+import { addCloudEmail } from "./cloud-email.js";
+import { parseCloudEmail } from "./cloud-email-config.js";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider.js";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs.js";
 import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
@@ -74,6 +76,7 @@ export class AmplifyAppShellStack extends Stack {
             return;
         }
         const cmsAppName = config.cms.appName ?? `${config.siteId}-cms`;
+        const emailEnvironment = addCloudEmail(this, parseCloudEmail(config.email, true, config.siteId));
         const stagingEnabled = isStagingEnabled(config);
         const stagingDomainName = resolveStagingDomainName(config);
         const cmsHostName = resolveCmsHostName(config);
@@ -195,6 +198,7 @@ export class AmplifyAppShellStack extends Stack {
             enablePerformanceMode: false,
             environmentVariables: environmentVariables({
                 ...config.cms.environment,
+                ...emailEnvironment,
                 PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
                 ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
                 PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,

package/infra/amplify-app-shell.ts

@@ -3,6 +3,8 @@ import { ArnFormat, CfnOutput, Duration, Fn, Stack, StackProps } from "aws-cdk-l
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
 import { SecureStringParameter } from "./secure-string-parameter";
+import { addCloudEmail } from "./cloud-email";
+import { parseCloudEmail } from "./cloud-email-config";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs";
 import { AmplifyAppShellSiteConfig, PROSPECTUS_PAPYRUS_SITE_ROUTES, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
@@ -79,6 +81,7 @@ export class AmplifyAppShellStack extends Stack {
     }
 
     const cmsAppName = config.cms.appName ?? `${config.siteId}-cms`;
+    const emailEnvironment = addCloudEmail(this, parseCloudEmail(config.email, true, config.siteId)!);
     const stagingEnabled = isStagingEnabled(config);
     const stagingDomainName = resolveStagingDomainName(config);
     const cmsHostName = resolveCmsHostName(config);
@@ -217,6 +220,7 @@ export class AmplifyAppShellStack extends Stack {
       enablePerformanceMode: false,
       environmentVariables: environmentVariables({
         ...config.cms.environment,
+        ...emailEnvironment,
         PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
         ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
         PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,

package/infra/cloud-email-config.js

@@ -0,0 +1,32 @@
+export function parseCloudEmail(raw, cloud, siteId) {
+    if (!cloud) {
+        if (raw !== undefined)
+            throw new Error("site.json: email requires a cloud cms; static-only sites do not need email resources");
+        return undefined;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("site.json: email is required for cloud sites; configure mode managed or existing and an explicit sendingDomain (see docs/email-reference-intake.md)");
+    }
+    const value = raw;
+    for (const key of Object.keys(value)) {
+        if (!["mode", "sendingDomain", "senderLocalPart", "configurationSet", "eventTopicName"].includes(key)) {
+            throw new Error(`site.json: email.${key} is not a known field`);
+        }
+    }
+    if (value.mode !== "managed" && value.mode !== "existing")
+        throw new Error("site.json: email.mode must be managed or existing");
+    const string = (key, pattern, fallback) => {
+        const result = value[key] ?? fallback;
+        if (typeof result !== "string" || !pattern.test(result))
+            throw new Error(`site.json: email.${key} is required and must be valid`);
+        return result;
+    };
+    return {
+        mode: value.mode,
+        sendingDomain: string("sendingDomain", /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/),
+        senderLocalPart: string("senderLocalPart", /^[a-z0-9][a-z0-9._+-]{0,63}$/, "notifications"),
+        configurationSet: string("configurationSet", /^[A-Za-z0-9_-]{1,64}$/, value.mode === "managed" ? `papyrus-${siteId}` : undefined),
+        // Preserve the newsletter consumer's historical default; the topic now also serves notifications.
+        eventTopicName: string("eventTopicName", /^[A-Za-z0-9_-]{1,256}$/, value.mode === "managed" ? `papyrus-newsletter-events-${siteId}` : undefined),
+    };
+}

package/infra/cloud-email-config.ts

@@ -0,0 +1,39 @@
+/** Email belongs to a cloud site, independently of any newsletter plugin. */
+export type CloudEmailConfig = {
+  mode: "managed" | "existing";
+  sendingDomain: string;
+  senderLocalPart: string;
+  configurationSet: string;
+  eventTopicName: string;
+};
+
+export function parseCloudEmail(raw: unknown, cloud: boolean, siteId: string): CloudEmailConfig | undefined {
+  if (!cloud) {
+    if (raw !== undefined) throw new Error("site.json: email requires a cloud cms; static-only sites do not need email resources");
+    return undefined;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("site.json: email is required for cloud sites; configure mode managed or existing and an explicit sendingDomain (see docs/email-reference-intake.md)");
+  }
+  const value = raw as Record<string, unknown>;
+  for (const key of Object.keys(value)) {
+    if (!["mode", "sendingDomain", "senderLocalPart", "configurationSet", "eventTopicName"].includes(key)) {
+      throw new Error(`site.json: email.${key} is not a known field`);
+    }
+  }
+  if (value.mode !== "managed" && value.mode !== "existing") throw new Error("site.json: email.mode must be managed or existing");
+  const string = (key: string, pattern: RegExp, fallback?: string) => {
+    const result = value[key] ?? fallback;
+    if (typeof result !== "string" || !pattern.test(result)) throw new Error(`site.json: email.${key} is required and must be valid`);
+    return result;
+  };
+  return {
+    mode: value.mode,
+    sendingDomain: string("sendingDomain", /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/),
+    senderLocalPart: string("senderLocalPart", /^[a-z0-9][a-z0-9._+-]{0,63}$/, "notifications"),
+    configurationSet: string("configurationSet", /^[A-Za-z0-9_-]{1,64}$/, value.mode === "managed" ? `papyrus-${siteId}` : undefined),
+    // Preserve the newsletter consumer's historical default; the topic now also serves notifications.
+    eventTopicName: string("eventTopicName", /^[A-Za-z0-9_-]{1,256}$/, value.mode === "managed" ? `papyrus-newsletter-events-${siteId}` : undefined),
+  };
+}
+

package/infra/cloud-email.js

@@ -0,0 +1,57 @@
+import { ArnFormat, CfnOutput, RemovalPolicy } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as ses from "aws-cdk-lib/aws-ses";
+import * as sns from "aws-cdk-lib/aws-sns";
+/** No DNS mutation, sending grant or receipt activation. Existing identities remain with their owner. */
+export function addCloudEmail(stack, config) {
+    if (config.mode === "managed") {
+        const configurationSet = new ses.CfnConfigurationSet(stack, "CloudEmailConfigurationSet", {
+            name: config.configurationSet,
+            reputationOptions: { reputationMetricsEnabled: true },
+            suppressionOptions: { suppressedReasons: ["BOUNCE", "COMPLAINT"] },
+            sendingOptions: { sendingEnabled: true },
+        });
+        configurationSet.applyRemovalPolicy(RemovalPolicy.RETAIN);
+        const identity = new ses.CfnEmailIdentity(stack, "CloudEmailIdentity", {
+            emailIdentity: config.sendingDomain,
+            dkimSigningAttributes: { nextSigningKeyLength: "RSA_2048_BIT" },
+            configurationSetAttributes: { configurationSetName: configurationSet.ref },
+        });
+        identity.applyRemovalPolicy(RemovalPolicy.RETAIN);
+        const topic = new sns.Topic(stack, "CloudEmailEvents", { topicName: config.eventTopicName });
+        topic.applyRemovalPolicy(RemovalPolicy.RETAIN);
+        topic.addToResourcePolicy(new iam.PolicyStatement({
+            principals: [new iam.ServicePrincipal("ses.amazonaws.com")], actions: ["sns:Publish"],
+            resources: [topic.topicArn], conditions: { StringEquals: { "aws:SourceAccount": stack.account } },
+        }));
+        const events = new ses.CfnConfigurationSetEventDestination(stack, "CloudEmailEventDestination", {
+            configurationSetName: configurationSet.ref,
+            eventDestination: { name: "delivery-events", enabled: true,
+                matchingEventTypes: ["SEND", "DELIVERY", "BOUNCE", "COMPLAINT", "REJECT", "RENDERING_FAILURE", "DELIVERY_DELAY"],
+                snsDestination: { topicArn: topic.topicArn } },
+        });
+        events.node.addDependency(topic);
+        // These dimensions also feed the newsletter consumer's existing bounce/complaint alarms.
+        new ses.CfnConfigurationSetEventDestination(stack, "CloudEmailMetrics", {
+            configurationSetName: configurationSet.ref,
+            eventDestination: { name: "cloudwatch-metrics", enabled: true,
+                matchingEventTypes: ["SEND", "BOUNCE", "COMPLAINT"],
+                cloudWatchDestination: { dimensionConfigurations: [{ dimensionName: "ses:configuration-set",
+                            dimensionValueSource: "MESSAGE_TAG", defaultDimensionValue: config.configurationSet }] } },
+        });
+        const records = [[identity.attrDkimDnsTokenName1, identity.attrDkimDnsTokenValue1],
+            [identity.attrDkimDnsTokenName2, identity.attrDkimDnsTokenValue2],
+            [identity.attrDkimDnsTokenName3, identity.attrDkimDnsTokenValue3]];
+        records.forEach(([name, value], index) => {
+            new CfnOutput(stack, `EmailDkimRecord${index + 1}Name`, { value: name, description: "CNAME name; DNS change requires separate approval" });
+            new CfnOutput(stack, `EmailDkimRecord${index + 1}Value`, { value });
+        });
+    }
+    const identityArn = stack.formatArn({ service: "ses", resource: "identity", resourceName: config.sendingDomain, arnFormat: ArnFormat.SLASH_RESOURCE_NAME });
+    new CfnOutput(stack, "EmailIdentityArn", { value: identityArn });
+    new CfnOutput(stack, "EmailConfigurationSetName", { value: config.configurationSet });
+    new CfnOutput(stack, "EmailEventTopicName", { value: config.eventTopicName });
+    return { PAPYRUS_EMAIL_FROM_ADDRESS: `${config.senderLocalPart}@${config.sendingDomain}`,
+        PAPYRUS_EMAIL_IDENTITY_ARN: identityArn, PAPYRUS_EMAIL_CONFIGURATION_SET: config.configurationSet,
+        PAPYRUS_EMAIL_EVENT_TOPIC_NAME: config.eventTopicName };
+}

package/infra/cloud-email.test.js

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { App } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+import { AmplifyAppShellStack } from "./amplify-app-shell.js";
+import { parseSiteConfig } from "./site-config.js";
+const base = () => ({
+    siteId: "example", repository: "https://github.com/example/publication", brand: "example",
+    frontend: "markus-static", papyrusVersion: "5.32.0", autoDeploy: false,
+    cms: { cognitoDomainPrefix: "example-cms", staging: false,
+        environment: { PAPYRUS_OAUTH_REDIRECT_URLS: "http://localhost:3001/" } },
+});
+function synth(raw) {
+    const app = new App();
+    return Template.fromStack(new AmplifyAppShellStack(app, "EmailTest", parseSiteConfig(raw), {
+        env: { account: "123456789012", region: "us-east-1" },
+    }));
+}
+const checks = {
+    managed() {
+        const template = synth({ ...base(), email: { mode: "managed", sendingDomain: "news.example.test" } });
+        template.resourceCountIs("AWS::SES::EmailIdentity", 1);
+        template.resourceCountIs("AWS::SES::ConfigurationSet", 1);
+        template.resourceCountIs("AWS::Route53::RecordSet", 0);
+        template.resourceCountIs("AWS::SES::ReceiptRuleSet", 0);
+        template.hasResourceProperties("AWS::SES::EmailIdentity", { EmailIdentity: "news.example.test" });
+        template.hasResourceProperties("AWS::SNS::Topic", { TopicName: "papyrus-newsletter-events-example" });
+        template.hasResourceProperties("AWS::SES::ConfigurationSetEventDestination", {
+            EventDestination: { Name: "cloudwatch-metrics", MatchingEventTypes: ["SEND", "BOUNCE", "COMPLAINT"],
+                CloudWatchDestination: { DimensionConfigurations: [{ DimensionName: "ses:configuration-set",
+                            DimensionValueSource: "MESSAGE_TAG", DefaultDimensionValue: "papyrus-example" }] } },
+        });
+        const text = JSON.stringify(template.toJSON());
+        assert.ok(text.includes("PAPYRUS_EMAIL_FROM_ADDRESS"));
+        assert.ok(text.includes("notifications@news.example.test"));
+        assert.ok(text.includes("EmailDkimRecord1Name"));
+        assert.ok(!text.includes("ses:SendEmail"), "identity setup does not grant unsolicited sending authority");
+    },
+    existing() {
+        const template = synth({ ...base(), email: { mode: "existing", sendingDomain: "news.example.test",
+                configurationSet: "already-owned", eventTopicName: "already-owned-events" } });
+        template.resourceCountIs("AWS::SES::EmailIdentity", 0);
+        template.resourceCountIs("AWS::SES::ConfigurationSet", 0);
+        template.resourceCountIs("AWS::SNS::Topic", 0);
+        assert.ok(JSON.stringify(template.toJSON()).includes("already-owned"));
+    },
+    static() {
+        const raw = { ...base(), reader: { buildCommand: "make site", baseDirectory: "dist" } };
+        delete raw.cms;
+        const template = synth(raw);
+        template.resourceCountIs("AWS::SES::EmailIdentity", 0);
+        template.resourceCountIs("AWS::SES::ConfigurationSet", 0);
+        template.resourceCountIs("AWS::SES::ReceiptRule", 0);
+    },
+    missing() {
+        assert.throws(() => parseSiteConfig(base()), /email.*required.*cloud/i);
+        assert.throws(() => parseSiteConfig({ ...base(), email: { mode: "existing", sendingDomain: "news.example.test" } }), /email.configurationSet/);
+    },
+};
+export function runCloudEmailTests(selected) {
+    if (selected) {
+        assert.ok(checks[selected], selected);
+        checks[selected]();
+    }
+    else
+        for (const check of Object.values(checks))
+            check();
+    console.log("cloud email infrastructure: ok");
+}
+runCloudEmailTests(process.argv[2]);