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

package/infra/chat.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { App } from "aws-cdk-lib";
+import { AmplifyAppShellStack } from "./amplify-app-shell";
+import { PapyrusChatStack } from "./chat-stack";
+import { parseSiteConfig, resolveChatLogGroupPrefix, resolveChatStackName, resolveStackName } from "./site-config";
+
+// Executes infra/amplify-app-shell/features/per-site-private-chat.feature (run through scripts/test-infra-chat.ts).
+const examples = path.resolve(__dirname, "../examples");
+const example = (name: string, change: (config: any) => void = () => {}): any => {
+  const config = JSON.parse(fs.readFileSync(path.join(examples, `${name}.site.json`), "utf8"));
+  change(config);
+  return config;
+};
+const siteNames = fs.readdirSync(examples).filter((name) => name.endsWith(".site.json")).map((name) => name.replace(/\.site\.json$/, ""));
+const lambdaDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "papyrus-chat-test-"));
+for (const file of ["run-worker.js", "probe-worker.js"]) fs.writeFileSync(path.join(lambdaDirectory, file), "exports.handler = async () => ({});\n");
+
+const resourcesOf = (template: any, type: string): any[] => Object.values<any>(template.Resources).filter((resource) => resource.Type === type);
+function shellTemplate(raw: unknown): any {
+  const config = parseSiteConfig(raw);
+  const stack = new AmplifyAppShellStack(new App(), "Shell", config, { env: { account: "712236451410", region: "us-east-1" }, stackName: resolveStackName(config) });
+  return JSON.parse(JSON.stringify((App.of(stack) as App).synth().getStackByName(stack.stackName).template));
+}
+function chatTemplate(raw: unknown): any {
+  const config = parseSiteConfig(raw);
+  const app = new App();
+  const stack = new PapyrusChatStack(app, { config, env: { account: "712236451410", region: "us-east-1" }, lambdaAssetDirectory: lambdaDirectory });
+  return JSON.parse(JSON.stringify(app.synth().getStackByName(stack.stackName).template));
+}
+const branchEnvironment = (template: any, branchName: string): Record<string, unknown> => {
+  const branch = resourcesOf(template, "AWS::Amplify::Branch").find((resource) => resource.Properties.BranchName === branchName);
+  return Object.fromEntries(branch.Properties.EnvironmentVariables.map((variable: any) => [variable.Name, variable.Value]));
+};
+const CHAT_NAMES = ["PAPYRUS_CHAT_MESSAGING_TABLE", "PAPYRUS_CHAT_CONVERSATIONS_TABLE", "PAPYRUS_CHAT_SESSION_BUCKET", "PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL", "PAPYRUS_CHAT_TURN_PROBES_QUEUE_URL", "PAPYRUS_CHAT_PRIVATE_BOT_ID", "PAPYRUS_CHAT_PRIVATE_BOT_NAME"];
+
+// Scenario: a site with chat enabled gets the chat environment and a data stack
+{
+  const raw = example("anth-us");
+  assert.equal(raw.chat.modelKeyParameter, "/papyrus/shipped/openai-api-key");
+  const config = parseSiteConfig(raw);
+  assert.equal(resolveChatStackName(config), "papyrus-chat-anth-us");
+  const production = branchEnvironment(shellTemplate(raw), "main");
+  assert.equal(production.PAPYRUS_PRIVATE_CHAT_ENABLED, "true");
+  assert.deepEqual(production.PAPYRUS_CHAT_MESSAGING_TABLE, { "Fn::ImportValue": "papyrus-chat-anth-us:MessagingTableName" });
+  assert.deepEqual(production.PAPYRUS_CHAT_SESSION_BUCKET, { "Fn::ImportValue": "papyrus-chat-anth-us:SessionBucketName" });
+  assert.deepEqual(production.PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL, { "Fn::ImportValue": "papyrus-chat-anth-us:TurnRunsQueueUrl" });
+  assert.equal(production.PAPYRUS_CHAT_PRIVATE_BOT_ID, "papyrus-private-assistant");
+
+  const chat = chatTemplate(raw);
+  assert.equal(resourcesOf(chat, "AWS::DynamoDB::Table").length, 2);
+  const [bucket] = resourcesOf(chat, "AWS::S3::Bucket");
+  assert.equal(bucket.Properties.VersioningConfiguration.Status, "Enabled");
+  assert.equal(bucket.Properties.PublicAccessBlockConfiguration.BlockPublicPolicy, true);
+  assert.equal(resourcesOf(chat, "AWS::SQS::Queue").length, 4);
+  assert.equal(resourcesOf(chat, "AWS::Lambda::Function").length, 2);
+  const mappings = resourcesOf(chat, "AWS::Lambda::EventSourceMapping");
+  assert.equal(mappings.length, 2);
+  assert.ok(mappings.every((mapping) => mapping.Properties.Enabled === true));
+  for (const key of ["MessagingTableName", "ConversationIndexTableName", "SessionBucketName", "TurnRunsQueueUrl", "TurnProbesQueueUrl"]) {
+    assert.equal(chat.Outputs[key].Export.Name, `papyrus-chat-anth-us:${key}`);
+  }
+  assert.deepEqual(Object.keys(chat.Parameters).filter((name) => name !== "BootstrapVersion").sort(), ["GatewayRoleArn", "PrivateAssistantBotId", "PrivateAssistantBotName"]);
+
+  // Only the run worker may read the model key parameter; the gateway policy never names it.
+  const parameterGrants = resourcesOf(chat, "AWS::IAM::Policy").filter((policy) => JSON.stringify(policy.Properties.PolicyDocument).includes("openai-api-key"));
+  assert.equal(parameterGrants.length, 1);
+  assert.ok(parameterGrants[0].Properties.Roles.some((role: any) => JSON.stringify(role).includes("RunWorkerRole")));
+  assert.equal(JSON.stringify(chat).split("/papyrus/shipped/openai-api-key").length - 1, 3, "the parameter appears in the run worker grant, the run worker environment and one output only");
+  const gateway = resourcesOf(chat, "AWS::IAM::Policy").find((policy) => policy.Properties.Roles.some((role: any) => JSON.stringify(role).includes("GatewayRoleArn")));
+  assert.ok(gateway, "the gateway policy attaches to the role named by GatewayRoleArn");
+  const gatewayActions = gateway.Properties.PolicyDocument.Statement.flatMap((statement: any) => [statement.Action].flat());
+  assert.ok(!gatewayActions.some((action: string) => action.startsWith("ssm:") || action.endsWith("*")), "the gateway has no SSM access and no wildcard action");
+}
+
+// Scenario: the staging branch never gets private chat
+{
+  const staging = branchEnvironment(shellTemplate(example("p-apyr-us")), "staging");
+  assert.equal(staging.PAPYRUS_PRIVATE_CHAT_ENABLED, "false");
+  assert.deepEqual(CHAT_NAMES.filter((name) => name in staging), []);
+}
+
+// Scenario: a site without chat gets neither
+{
+  const withoutBlock = example("anth-us", (config) => delete config.chat);
+  const disabled = example("anth-us", (config) => (config.chat.enabled = false));
+  for (const raw of [withoutBlock, disabled]) {
+    const production = branchEnvironment(shellTemplate(raw), "main");
+    assert.equal(production.PAPYRUS_PRIVATE_CHAT_ENABLED, "false");
+    assert.deepEqual(CHAT_NAMES.filter((name) => name in production), []);
+    assert.equal(resolveChatStackName(parseSiteConfig(raw)), undefined);
+    assert.throws(() => chatTemplate(raw), /does not enable chat/);
+  }
+}
+
+// Scenario: the chat block cannot be contradicted by hand-set variables
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED = "false"))), /cms\.environment\.PAPYRUS_PRIVATE_CHAT_ENABLED/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.cms.environment.PAPYRUS_CHAT_SESSION_BUCKET = "x"))), /cms\.environment\.PAPYRUS_CHAT_SESSION_BUCKET/);
+// Without chat, the existing hand-managed flag keeps working.
+assert.equal(branchEnvironment(shellTemplate(example("anth-us", (config) => { delete config.chat; config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED = "true"; })), "main").PAPYRUS_PRIVATE_CHAT_ENABLED, "true");
+
+// Scenario: chat needs a CMS and a model key parameter
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => delete config.chat.modelKeyParameter)), /chat\.modelKeyParameter/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.modelKeyParameter = "not-a-path"))), /chat\.modelKeyParameter/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.enabled = "yes"))), /chat\.enabled/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.extra = 1))), /chat\.extra/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.workerCodeS3Key = "abc"))), /chat\.workerCodeS3Key/);
+assert.throws(() => parseSiteConfig({ siteId: "reader-only", repository: "https://github.com/example/x", brand: "x", frontend: "markus-static", papyrusVersion: "5.42.1", hostedZoneId: "Z10285921B1G7MVRV06W9", reader: { domainName: "x.example.test", buildCommand: "npm run build", baseDirectory: "out" }, chat: { enabled: true, modelKeyParameter: "/papyrus/x/openai-api-key" } }), /chat\.enabled.*requires cms/);
+assert.throws(() => new PapyrusChatStack(new App(), { config: parseSiteConfig(example("p-apyr-us", (config) => delete config.chat.workerCodeS3Key)), env: { account: "712236451410", region: "us-east-1" } }), /bundle the chat workers first/);
+
+// Scenario: two sites in one account do not share chat storage or log groups
+{
+  const enabled = siteNames.map((name) => parseSiteConfig(example(name))).filter((config) => config.chat?.enabled);
+  assert.deepEqual(enabled.map((config) => config.siteId).sort(), ["anth-us", "dataparade", "distinctive", "p-apyr-us", "pilobol-us", "shipped", "threat-intelligence"], "every Papyrus site example enables chat");
+  const names = enabled.map((config) => resolveChatStackName(config));
+  const prefixes = enabled.map((config) => resolveChatLogGroupPrefix(config));
+  assert.equal(new Set(names).size, names.length, "stack names are unique");
+  assert.equal(new Set(prefixes).size, prefixes.length, "worker log group prefixes are unique");
+  for (const config of enabled) {
+    assert.ok(/^\/(papyrus\/[a-z0-9-]+\/openai-api-key|amplify\/shared\/[a-z0-9]+\/OPENAI_API_KEY)$/.test(config.chat!.modelKeyParameter), `${config.siteId} reuses an existing model key parameter`);
+  }
+}
+
+// Scenario: the activated p.apyr.us stack is adopted without replacing anything
+{
+  const activated = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../shared-chat-runtime/cdk/PapyrusChatDataCandidate.template.json"), "utf8"));
+  const generated = chatTemplate(example("p-apyr-us"));
+  assert.equal(resolveChatStackName(parseSiteConfig(example("p-apyr-us"))), "PapyrusChatDataCandidate");
+  const normalize = (resource: any) => {
+    const copy = JSON.parse(JSON.stringify(resource));
+    delete copy.Metadata;
+    const statements = copy.Properties?.PolicyDocument?.Statement;
+    if (statements) copy.Properties.PolicyDocument.Statement = [...statements].sort((a: any, b: any) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    return copy;
+  };
+  assert.deepEqual(Object.keys(generated.Resources).sort(), Object.keys(activated.Resources).sort(), "no resource is added, removed or renamed (a changed logical id would replace it)");
+  for (const [logicalId, resource] of Object.entries<any>(activated.Resources)) {
+    const expected = normalize(resource);
+    // The activated template is the reviewed candidate; the queue mappings were enabled live afterwards.
+    if (resource.Type === "AWS::Lambda::EventSourceMapping") expected.Properties.Enabled = true;
+    assert.deepEqual(normalize(generated.Resources[logicalId]), expected, `${logicalId} is unchanged`);
+  }
+  for (const key of Object.keys(activated.Outputs)) {
+    assert.deepEqual({ ...generated.Outputs[key], Export: undefined }, { ...activated.Outputs[key], Export: undefined, ...(key === "FeatureDefault" ? { Value: generated.Outputs[key].Value } : {}) }, `output ${key} keeps its value`);
+  }
+  assert.deepEqual(Object.keys(generated.Outputs).sort(), Object.keys(activated.Outputs).sort());
+}
+
+console.log("per-site private chat infra tests passed");

package/infra/index.js

@@ -10,6 +10,7 @@ try {
   );
 }
 export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export const { PapyrusChatStack } = await import("./chat-stack.js");
 export const { SecureStringParameter } = await import("./secure-string-parameter.js");
 export const { GithubOidcProviderStack } = await import("./github-oidc-provider.js");
 export { parseSiteConfig } from "./site-config.js";

package/infra/site-config.js

@@ -28,6 +28,9 @@ const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
 const SITE_ORIGIN_PATTERN = /^https:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(:\d{1,5})?$/;
 const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
+const CHAT_MODEL_KEY_PARAMETER_PATTERN = /^\/[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)+$/;
+const CHAT_LOG_GROUP_PREFIX_PATTERN = /^\/aws\/lambda\/[A-Za-z0-9_.-]{1,100}$/;
+const CHAT_WORKER_CODE_KEY_PATTERN = /^[0-9a-f]{64}\.zip$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
 const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
@@ -211,6 +214,58 @@ export function resolveStagingDomainName(config) {
 export function resolveStackName(config) {
     return config.stackName ?? `amplify-app-shell-${config.siteId}`;
 }
+/** The chat data stack of a site; its construct id and CloudFormation name. Nothing when chat is not enabled. */
+export function resolveChatStackName(config) {
+    if (!config.chat?.enabled)
+        return undefined;
+    return config.chat.stackName ?? `papyrus-chat-${config.siteId}`;
+}
+export function resolveChatLogGroupPrefix(config) {
+    return config.chat?.logGroupPrefix ?? `/aws/lambda/papyrus-chat-${config.siteId}`;
+}
+/** CloudFormation export names the chat stack publishes and the app shell imports (no stack ever references the other directly). */
+export const CHAT_EXPORTED_RESOURCES = ["MessagingTableName", "ConversationIndexTableName", "SessionBucketName", "TurnRunsQueueUrl", "TurnProbesQueueUrl"];
+export const CHAT_ENVIRONMENT_NAMES = {
+    MessagingTableName: "PAPYRUS_CHAT_MESSAGING_TABLE",
+    ConversationIndexTableName: "PAPYRUS_CHAT_CONVERSATIONS_TABLE",
+    SessionBucketName: "PAPYRUS_CHAT_SESSION_BUCKET",
+    TurnRunsQueueUrl: "PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL",
+    TurnProbesQueueUrl: "PAPYRUS_CHAT_TURN_PROBES_QUEUE_URL",
+};
+export const CHAT_PRIVATE_ASSISTANT_ID = "papyrus-private-assistant";
+export const CHAT_PRIVATE_ASSISTANT_NAME = "Papyrus Assistant";
+export function chatExportName(stackName, resource) {
+    return `${stackName}:${resource}`;
+}
+function parseChat(value, cms) {
+    if (value === undefined)
+        return undefined;
+    const record = requireObject(value, "chat");
+    rejectUnknownKeys(record, ["enabled", "modelKeyParameter", "stackName", "logGroupPrefix", "workerCodeS3Key"], "chat");
+    if (typeof record.enabled !== "boolean")
+        fail("chat.enabled", "must be a boolean");
+    const chat = {
+        enabled: record.enabled,
+        modelKeyParameter: requireString(record.modelKeyParameter, "chat.modelKeyParameter", CHAT_MODEL_KEY_PARAMETER_PATTERN, "SSM parameter name such as /papyrus/<site>/openai-api-key"),
+        stackName: optionalString(record.stackName, "chat.stackName", STACK_NAME_PATTERN, "CloudFormation stack name"),
+        logGroupPrefix: optionalString(record.logGroupPrefix, "chat.logGroupPrefix", CHAT_LOG_GROUP_PREFIX_PATTERN, "/aws/lambda/<name>"),
+        workerCodeS3Key: optionalString(record.workerCodeS3Key, "chat.workerCodeS3Key", CHAT_WORKER_CODE_KEY_PATTERN, "<64 hex>.zip CDK asset key"),
+    };
+    for (const key of ["stackName", "logGroupPrefix", "workerCodeS3Key"]) {
+        if (chat[key] === undefined)
+            delete chat[key];
+    }
+    if (chat.enabled && cms === undefined)
+        fail("chat.enabled", "requires cms (the chat gateway runs in the CMS compute role)");
+    if (chat.enabled && cms) {
+        for (const key of Object.keys(cms.environment)) {
+            if (key === "PAPYRUS_PRIVATE_CHAT_ENABLED" || key.startsWith("PAPYRUS_CHAT_")) {
+                fail(`cms.environment.${key}`, "is managed by the chat block when chat is enabled: remove it and use chat.enabled");
+            }
+        }
+    }
+    return chat;
+}
 export function resolveStoragePreviewPrefix(config) {
     return config.storagePreviewPrefix ?? "preview/";
 }
@@ -355,7 +410,7 @@ function parseAws(value) {
 }
 export function parseSiteConfig(raw) {
     const record = requireObject(raw, "site");
-    rejectUnknownKeys(record, ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "knowledgeRun", "autoDeploy", "github"], "site");
+    rejectUnknownKeys(record, ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "chat", "knowledgeRun", "autoDeploy", "github"], "site");
     const siteId = requireString(record.siteId, "siteId", SITE_ID_PATTERN, "kebab-case");
     const repository = requireString(record.repository, "repository", REPOSITORY_PATTERN, "https://github.com/<org>/<repo>");
     const repositoryAccessTokenSecretArn = record.repositoryAccessTokenSecretArn === undefined
@@ -448,6 +503,7 @@ export function parseSiteConfig(raw) {
             fail("github", "ownerId and repoId must be set together");
         github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra, ...(ownerId !== undefined ? { ownerId, repoId } : {}) };
     }
+    const chat = parseChat(record.chat, cms);
     const hasDomain = cms?.domainName !== undefined || reader?.domainName !== undefined;
     if (hasDomain && hostedZoneId === undefined) {
         fail("hostedZoneId", "is required when cms.domainName or reader.domainName is set");
@@ -469,6 +525,7 @@ export function parseSiteConfig(raw) {
         reader,
         papyrusVersion,
         storagePreviewPrefix,
+        ...(chat ? { chat } : {}),
         autoDeploy: autoDeploy,
         github,
         ...(record.knowledgeRun !== undefined ? { knowledgeRun: record.knowledgeRun } : {}),

package/infra/site-config.ts

@@ -55,6 +55,21 @@ export type CmsConfig = {
   deployStackInBuild?: boolean;
 };
 
+export type ChatConfig = {
+  enabled: boolean;
+  /** SSM SecureString parameter holding the site's OpenAI key; only the chat run worker may read it. */
+  modelKeyParameter: string;
+  /** Chat data stack name (also its CDK construct id). Default `papyrus-chat-<siteId>`. */
+  stackName?: string;
+  /** CloudWatch log group prefix of the two workers (`<prefix>-run-worker`, `<prefix>-probe-worker`). Default `/aws/lambda/papyrus-chat-<siteId>`. */
+  logGroupPrefix?: string;
+  /**
+   * Pins the worker code to an already uploaded CDK asset object (key in the CDK assets bucket) instead of
+   * bundling and uploading new bytes. Only for adopting a stack whose workers are already verified live.
+   */
+  workerCodeS3Key?: string;
+};
+
 export type AmplifyAppShellSiteConfig = {
   siteId: string;
   repository: string;
@@ -82,6 +97,11 @@ export type AmplifyAppShellSiteConfig = {
   };
   papyrusVersion: string;
   storagePreviewPrefix?: string;
+  /**
+   * Private newsroom chat for this publication (docs/private-newsroom-chat-per-site.md). Absent or
+   * `enabled: false` means the site gets neither the chat data stack nor the chat environment on its CMS.
+   */
+  chat?: ChatConfig;
   /**
    * The scheduled cloud knowledge run for this publication. The app-shell stack ignores it; it is validated by
    * infra/scheduled-jobs/lib/knowledge-run-config.ts, which owns the schema.
@@ -153,6 +173,9 @@ const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
 const SITE_ORIGIN_PATTERN = /^https:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(:\d{1,5})?$/;
 const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
+const CHAT_MODEL_KEY_PARAMETER_PATTERN = /^\/[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)+$/;
+const CHAT_LOG_GROUP_PREFIX_PATTERN = /^\/aws\/lambda\/[A-Za-z0-9_.-]{1,100}$/;
+const CHAT_WORKER_CODE_KEY_PATTERN = /^[0-9a-f]{64}\.zip$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
 const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
@@ -339,6 +362,57 @@ export function resolveStackName(config: Pick<AmplifyAppShellSiteConfig, "siteId
   return config.stackName ?? `amplify-app-shell-${config.siteId}`;
 }
 
+/** The chat data stack of a site; its construct id and CloudFormation name. Nothing when chat is not enabled. */
+export function resolveChatStackName(config: Pick<AmplifyAppShellSiteConfig, "siteId" | "chat">): string | undefined {
+  if (!config.chat?.enabled) return undefined;
+  return config.chat.stackName ?? `papyrus-chat-${config.siteId}`;
+}
+
+export function resolveChatLogGroupPrefix(config: Pick<AmplifyAppShellSiteConfig, "siteId" | "chat">): string {
+  return config.chat?.logGroupPrefix ?? `/aws/lambda/papyrus-chat-${config.siteId}`;
+}
+
+/** CloudFormation export names the chat stack publishes and the app shell imports (no stack ever references the other directly). */
+export const CHAT_EXPORTED_RESOURCES = ["MessagingTableName", "ConversationIndexTableName", "SessionBucketName", "TurnRunsQueueUrl", "TurnProbesQueueUrl"] as const;
+export const CHAT_ENVIRONMENT_NAMES: Record<(typeof CHAT_EXPORTED_RESOURCES)[number], string> = {
+  MessagingTableName: "PAPYRUS_CHAT_MESSAGING_TABLE",
+  ConversationIndexTableName: "PAPYRUS_CHAT_CONVERSATIONS_TABLE",
+  SessionBucketName: "PAPYRUS_CHAT_SESSION_BUCKET",
+  TurnRunsQueueUrl: "PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL",
+  TurnProbesQueueUrl: "PAPYRUS_CHAT_TURN_PROBES_QUEUE_URL",
+};
+export const CHAT_PRIVATE_ASSISTANT_ID = "papyrus-private-assistant";
+export const CHAT_PRIVATE_ASSISTANT_NAME = "Papyrus Assistant";
+export function chatExportName(stackName: string, resource: (typeof CHAT_EXPORTED_RESOURCES)[number]): string {
+  return `${stackName}:${resource}`;
+}
+
+function parseChat(value: unknown, cms: CmsConfig | undefined): ChatConfig | undefined {
+  if (value === undefined) return undefined;
+  const record = requireObject(value, "chat");
+  rejectUnknownKeys(record, ["enabled", "modelKeyParameter", "stackName", "logGroupPrefix", "workerCodeS3Key"], "chat");
+  if (typeof record.enabled !== "boolean") fail("chat.enabled", "must be a boolean");
+  const chat: ChatConfig = {
+    enabled: record.enabled,
+    modelKeyParameter: requireString(record.modelKeyParameter, "chat.modelKeyParameter", CHAT_MODEL_KEY_PARAMETER_PATTERN, "SSM parameter name such as /papyrus/<site>/openai-api-key"),
+    stackName: optionalString(record.stackName, "chat.stackName", STACK_NAME_PATTERN, "CloudFormation stack name"),
+    logGroupPrefix: optionalString(record.logGroupPrefix, "chat.logGroupPrefix", CHAT_LOG_GROUP_PREFIX_PATTERN, "/aws/lambda/<name>"),
+    workerCodeS3Key: optionalString(record.workerCodeS3Key, "chat.workerCodeS3Key", CHAT_WORKER_CODE_KEY_PATTERN, "<64 hex>.zip CDK asset key"),
+  };
+  for (const key of ["stackName", "logGroupPrefix", "workerCodeS3Key"] as const) {
+    if (chat[key] === undefined) delete chat[key];
+  }
+  if (chat.enabled && cms === undefined) fail("chat.enabled", "requires cms (the chat gateway runs in the CMS compute role)");
+  if (chat.enabled && cms) {
+    for (const key of Object.keys(cms.environment)) {
+      if (key === "PAPYRUS_PRIVATE_CHAT_ENABLED" || key.startsWith("PAPYRUS_CHAT_")) {
+        fail(`cms.environment.${key}`, "is managed by the chat block when chat is enabled: remove it and use chat.enabled");
+      }
+    }
+  }
+  return chat;
+}
+
 export function resolveStoragePreviewPrefix(config: Pick<AmplifyAppShellSiteConfig, "storagePreviewPrefix">): string {
   return config.storagePreviewPrefix ?? "preview/";
 }
@@ -498,7 +572,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   const record = requireObject(raw, "site");
   rejectUnknownKeys(
     record,
-    ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "knowledgeRun", "autoDeploy", "github"],
+    ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "chat", "knowledgeRun", "autoDeploy", "github"],
     "site",
   );
 
@@ -590,6 +664,8 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra as boolean, ...(ownerId !== undefined ? { ownerId, repoId } : {}) };
   }
 
+  const chat = parseChat(record.chat, cms);
+
   const hasDomain = cms?.domainName !== undefined || reader?.domainName !== undefined;
   if (hasDomain && hostedZoneId === undefined) {
     fail("hostedZoneId", "is required when cms.domainName or reader.domainName is set");
@@ -612,6 +688,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     reader,
     papyrusVersion,
     storagePreviewPrefix,
+    ...(chat ? { chat } : {}),
     autoDeploy: autoDeploy as boolean,
     github,
     ...(record.knowledgeRun !== undefined ? { knowledgeRun: record.knowledgeRun } : {}),

package/lib/category-repository.ts

@@ -656,6 +656,10 @@ export type NewsroomSummaryFacets = {
 
 export type CategorySteeringDashboard = {
   isDemo?: boolean;
+  /** Local preview only: the demo newsroom is showing a real export (scripts/export-reference-feed-fixture.py), so it must not say "synthetic". */
+  realDataPreview?: boolean;
+  /** Local preview only: review requests and their drafts from scripts/export-notification-center-fixture.py. */
+  notificationFixture?: { requests: import("./review-requests").ReviewRequest[]; drafts: import("./review-drafts").DraftRow[] } | null;
   isPublicSkeleton?: boolean;
   summaryStatus?: "loading" | "missing" | "ready";
   summary?: NewsroomSummaryRecord | null;
@@ -820,7 +824,8 @@ function sortCategorys(categorys: CategorySteeringCategory[]): CategorySteeringC
 }
 
 function defaultNewsroomSections(importedAt: string, sectionsConfigPath?: string): NewsroomSectionRecord[] {
-  if (!sectionsConfigPath) return [];
+  // A data-driven site names a seed file it does not ship: its Sections live in the backend, so there is nothing to seed.
+  if (!sectionsConfigPath || !fs.existsSync(sectionsConfigPath)) return [];
   return loadNewsroomSectionSeedRows(sectionsConfigPath).map((row, index) => ({
     ...row,
     enabledStatus: "enabled",

package/lib/content-actions-client.ts

@@ -30,6 +30,20 @@ export type SaveItemDraftResult = { ok: true; item: SavedItemSummary };
 export type PublishItemResult = { ok: true; changed: boolean; publishedId: string; versionNumber: number | null };
 export type UnpublishItemResult = { ok: true; changed: boolean };
 
+export type CaptureAssessment = "complete" | "incomplete" | "incorrect";
+export type CorrectReferenceCaptureInput = {
+  referenceId: string;
+  /** The full corrected or pasted text. */
+  text?: string;
+  /** The id of a PDF the editor uploaded to this Reference (a ModelAttachment); the server reads its text. Sent instead of `text`. */
+  pdfAttachmentId?: string;
+  grobid?: Record<string, unknown>;
+  /** Required with text; alone it is just a label on the capture. */
+  assessment?: CaptureAssessment;
+  note?: string;
+};
+export type CorrectReferenceCaptureResult = { ok: true; referenceId: string; status: string; edits: Array<{ sortKey?: string; via?: string }>; label: unknown; summaryStale: boolean };
+
 export class ContentActionFailure extends Error {
   readonly errors: ContentActionError[];
 
@@ -48,6 +62,7 @@ export type ContentActionsTransport = {
     saveItemDraft: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
     publishItem: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
     unpublishItem: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
+    correctReferenceCapture: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
   };
 };
 
@@ -80,6 +95,9 @@ export function createContentActionsClient(transport: ContentActionsTransport) {
     async publishItem(id: string): Promise<PublishItemResult> {
       return parseActionResponse(await transport.mutations.publishItem({ input: JSON.stringify({ id }) }, USER_POOL));
     },
+    async correctReferenceCapture(input: CorrectReferenceCaptureInput): Promise<CorrectReferenceCaptureResult> {
+      return parseActionResponse(await transport.mutations.correctReferenceCapture({ input: JSON.stringify(input) }, USER_POOL));
+    },
     async unpublishItem(id: string): Promise<UnpublishItemResult> {
       return parseActionResponse(await transport.mutations.unpublishItem({ input: JSON.stringify({ id }) }, USER_POOL));
     },
@@ -99,3 +117,5 @@ export const deriveMarkus = (input: DeriveMarkusInput) => contentActionsClient()
 export const saveItemDraft = (input: SaveItemDraftInput) => contentActionsClient().saveItemDraft(input);
 export const publishItem = (id: string) => contentActionsClient().publishItem(id);
 export const unpublishItem = (id: string) => contentActionsClient().unpublishItem(id);
+
+export const correctReferenceCapture = (input: CorrectReferenceCaptureInput) => contentActionsClient().correctReferenceCapture(input);

package/lib/conversation.ts

@@ -0,0 +1,154 @@
+/**
+ * Conversations: Messages written about a Reference (later a Story, or nothing at all). One conversation per thing, held in one
+ * MessageThread found by its anchor key. Pure helpers only, so the browser and the tests share them.
+ */
+
+export const CONVERSATION_FEED_KEY = "conversations";
+export const REFERENCE_CONVERSATION_KIND = "reference_conversation";
+export const STORY_CONVERSATION_KIND = "story_conversation";
+export const GENERAL_CONVERSATION_KIND = "conversation";
+
+/** What a conversation is about. `none` is a conversation that is about nothing but itself. */
+export type ConversationAnchor =
+  | { kind: "reference" | "item"; lineageId: string; /** The version id when it differs from the lineage id. */ id?: string; title?: string }
+  | { kind: "none"; lineageId?: undefined; title?: string };
+
+/** A Message as the conversation shows it. */
+export type ConversationMessage = {
+  id: string;
+  parentMessageId: string | null;
+  authorLabel: string;
+  content: string;
+  createdAt: string;
+  sequenceNumber: number;
+  /** True while an optimistic Message waits for the save. */
+  pending?: boolean;
+};
+
+export type ConversationReply = { message: ConversationMessage; answers: string | null };
+export type ConversationRoot = { message: ConversationMessage; replies: ConversationReply[] };
+
+function slug(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "thing";
+}
+
+/** `reference#<lineageId>`, `item#<lineageId>`, or null when the conversation is anchored to nothing. */
+export function conversationAnchorKey(anchor: ConversationAnchor): string | null {
+  return anchor.kind === "none" || !anchor.lineageId?.trim() ? null : `${anchor.kind}#${anchor.lineageId.trim()}`;
+}
+
+export function conversationThreadKind(anchor: ConversationAnchor): string {
+  return anchor.kind === "reference" ? REFERENCE_CONVERSATION_KIND : anchor.kind === "item" ? STORY_CONVERSATION_KIND : GENERAL_CONVERSATION_KIND;
+}
+
+/** The thread id follows the anchor, so two editors starting the same conversation at once collide on create instead of splitting it. */
+export function conversationThreadId(anchor: ConversationAnchor): string {
+  const key = conversationAnchorKey(anchor);
+  if (!key) throw new Error("A conversation without an anchor needs its own thread id.");
+  return `message-thread-conversation-${slug(key)}`;
+}
+
+export function conversationMessageId(threadId: string, sequenceNumber: number): string {
+  return `message-conversation-${slug(threadId)}-${String(sequenceNumber).padStart(4, "0")}`;
+}
+
+/** One more than the highest sequence number in use. */
+export function nextConversationSequence(existing: ReadonlyArray<{ sequenceNumber?: number | null }>): number {
+  return Math.max(0, ...existing.map((message) => Number(message.sequenceNumber || 0))) + 1;
+}
+
+/** A create that lost a race for its sequence number (the id derives from the number, so the second writer collides). */
+export function isSequenceConflict(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : typeof error === "string" ? error : JSON.stringify(error ?? "");
+  return /conditional|already exists|duplicate|ConditionalCheckFailed/i.test(text);
+}
+
+/** "ryan@example.test" is shown as "ryan"; a name stays as it is. */
+export function conversationAuthorName(label: string | null | undefined): string {
+  const text = String(label ?? "").trim();
+  if (!text) return "Someone";
+  const at = text.indexOf("@");
+  return at > 0 ? text.slice(0, at) : text;
+}
+
+/**
+ * Top-level Messages in order, each with its replies. A reply to a reply stays flat under the same root and says who it answers.
+ * A reply whose parent is missing is shown as a top-level Message rather than lost.
+ */
+export function buildConversationTree(messages: ReadonlyArray<ConversationMessage>): ConversationRoot[] {
+  const sorted = [...messages].sort((a, b) => a.sequenceNumber - b.sequenceNumber || a.createdAt.localeCompare(b.createdAt));
+  const byId = new Map(sorted.map((message) => [message.id, message]));
+  const rootOf = (message: ConversationMessage): string => {
+    let current = message;
+    const seen = new Set<string>();
+    while (current.parentMessageId && byId.has(current.parentMessageId) && !seen.has(current.id)) {
+      seen.add(current.id);
+      current = byId.get(current.parentMessageId)!;
+    }
+    return current.id;
+  };
+  const roots = new Map<string, ConversationRoot>();
+  for (const message of sorted) {
+    if (rootOf(message) === message.id) roots.set(message.id, { message, replies: [] });
+  }
+  for (const message of sorted) {
+    const root = roots.get(rootOf(message));
+    if (!root || root.message.id === message.id) continue;
+    const parent = message.parentMessageId ? byId.get(message.parentMessageId) : undefined;
+    root.replies.push({ message, answers: parent && parent.id !== root.message.id ? conversationAuthorName(parent.authorLabel) : null });
+  }
+  return [...roots.values()];
+}
+
+/** Short relative time: "now", "5m", "3h", "2d". */
+export function conversationAge(createdAt: string, now: number): string {
+  const time = Date.parse(createdAt);
+  if (!Number.isFinite(time)) return "";
+  const minutes = Math.max(0, Math.round((now - time) / 60000));
+  if (minutes < 1) return "now";
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+export function messageCountLabel(count: number): string {
+  return `${count} ${count === 1 ? "message" : "messages"}`;
+}
+
+/**
+ * Creates a Message with the next sequence number. The id derives from the number, so when another writer took it the create is
+ * refused and this tries the next number, up to `attempts` times. `list` returns the Messages already in the thread.
+ */
+export async function createWithSequenceRetry<Message>(input: {
+  list: () => Promise<ReadonlyArray<{ sequenceNumber?: number | null }>>;
+  create: (sequenceNumber: number) => Promise<Message>;
+  attempts?: number;
+}): Promise<{ created: Message; sequenceNumber: number }> {
+  const attempts = input.attempts ?? 5;
+  let sequenceNumber = nextConversationSequence(await input.list());
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return { created: await input.create(sequenceNumber), sequenceNumber };
+    } catch (error) {
+      if (!isSequenceConflict(error) || attempt >= attempts) throw error;
+      sequenceNumber = nextConversationSequence(await input.list());
+    }
+  }
+}
+
+/** Finds the conversation's thread, else creates it; a create that loses a race for the (anchor-derived) id uses the winner's thread. */
+export async function findOrCreateThread<Thread>(input: {
+  find: () => Promise<Thread | null>;
+  create: () => Promise<Thread>;
+}): Promise<Thread> {
+  const existing = await input.find();
+  if (existing) return existing;
+  try {
+    return await input.create();
+  } catch (error) {
+    const raced = isSequenceConflict(error) ? await input.find() : null;
+    if (raced) return raced;
+    throw error;
+  }
+}