@anthusai/papyrus 1.0.0-next.61 → 1.0.0-next.62

package/app/api/cyclotron/priming-proof/route.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from "next/server";
+import { approvedPrimingProofReport } from "../../../../lib/priming-proof-report";
+import { SITE_BRAND } from "../../../../lib/site-brand";
+
+export function GET() {
+  const report = approvedPrimingProofReport(SITE_BRAND.id);
+  if (report === null) {
+    return NextResponse.json({ error: "No approved priming proof report for this publication yet." }, { status: 404 });
+  }
+  return NextResponse.json(report);
+}

package/app/cyclotron/page.tsx

@@ -0,0 +1,13 @@
+import type { Metadata } from "next";
+import { PrimingProofPage } from "../../components/priming-proof-page";
+import { approvedPrimingProofReport } from "../../lib/priming-proof-report";
+import { SITE_BRAND } from "../../lib/site-brand";
+
+export const metadata: Metadata = {
+  title: `Cyclotron proof | ${SITE_BRAND.articleTitleSuffix}`,
+  description: "How often the relevance classifier agrees with editors on a fixed held-out set, before and after editor labels.",
+};
+
+export default function CyclotronProof() {
+  return <PrimingProofPage report={approvedPrimingProofReport(SITE_BRAND.id)} />;
+}

package/components/priming-proof-page.tsx

@@ -0,0 +1,92 @@
+import {
+  formatProofPercentage,
+  primingProofHeadline,
+  type PrimingProofReport,
+} from "../lib/priming-proof-report";
+
+function ProofMethod({ heldOutSize }: { heldOutSize: number | null }) {
+  return (
+    <section aria-labelledby="priming-proof-method" className="space-y-2 text-sm leading-relaxed">
+      <h2 id="priming-proof-method" className="text-base font-semibold uppercase tracking-wide">How the number is made</h2>
+      <p>
+        Editors already decided which candidate sources belong in this publication. A fixed, balanced sample of those
+        decisions{heldOutSize === null ? "" : ` (${heldOutSize} sources)`} is frozen as the held-out set and never used
+        for teaching. A classifier that always gives the same answer agrees on half of it.
+      </p>
+      <p>
+        Editors teach the classifier by pasting a source URL, reviewing what Papyrus extracted, and choosing publish or
+        reject. Each point below starts a fresh classifier that sees only the first N of those labels, then decides
+        every held-out source once. Nothing else changes between points: the same decision model, the publication&apos;s
+        mission and policies as the only rubric, and no automatic rubric rewriting.
+      </p>
+    </section>
+  );
+}
+
+export function PrimingProofPage({ report }: { report: PrimingProofReport | null }) {
+  if (report === null) {
+    return (
+      <main className="mx-auto max-w-3xl space-y-6 px-4 py-10" data-priming-proof="pending">
+        <header className="space-y-2 border-b pb-4">
+          <h1 className="text-3xl font-bold">Does teaching the classifier work?</h1>
+          <p className="text-muted-foreground">No approved proof run has been published for this publication yet.</p>
+        </header>
+        <ProofMethod heldOutSize={null} />
+      </main>
+    );
+  }
+  const { baseline, latest, agreementChangeInPoints } = primingProofHeadline(report);
+  const [positiveLabel, negativeLabel] = [report.positiveLabel, report.labels.find((label) => label !== report.positiveLabel)];
+  return (
+    <main className="mx-auto max-w-3xl space-y-8 px-4 py-10" data-priming-proof="published">
+      <header className="space-y-3 border-b pb-4">
+        <h1 className="text-3xl font-bold">Does teaching the classifier work?</h1>
+        <p className="text-lg" data-priming-proof-headline>
+          Agreement with editors went from <strong>{formatProofPercentage(baseline.agreement)}</strong> with no labels to{" "}
+          <strong>{formatProofPercentage(latest.agreement)}</strong> after {latest.labels} labels
+          {agreementChangeInPoints === null ? "" : ` (${agreementChangeInPoints >= 0 ? "+" : ""}${agreementChangeInPoints} points)`}.
+        </p>
+        <p className="text-sm text-muted-foreground">
+          {report.publication} · question: “{report.question}” · held-out set of {report.heldOut.size} sources frozen{" "}
+          {report.heldOut.frozenAt.slice(0, 10)} · run {report.ranAt.slice(0, 10)}
+          {report.decisionModel ? ` · decision model ${report.decisionModel}` : ""}
+        </p>
+      </header>
+      <section aria-labelledby="priming-proof-points" className="space-y-2">
+        <h2 id="priming-proof-points" className="text-base font-semibold uppercase tracking-wide">Before and after</h2>
+        <div className="overflow-x-auto">
+          <table className="w-full text-left text-sm tabular-nums">
+            <thead>
+              <tr className="border-b">
+                <th scope="col" className="py-2 pr-4">Editor labels</th>
+                <th scope="col" className="py-2 pr-4">Agreement</th>
+                <th scope="col" className="py-2 pr-4">Precision ({positiveLabel})</th>
+                <th scope="col" className="py-2 pr-4">Recall ({positiveLabel})</th>
+                <th scope="col" className="py-2">Labels used</th>
+              </tr>
+            </thead>
+            <tbody>
+              {report.points.map((point) => (
+                <tr key={point.labels} className="border-b" data-priming-proof-point={point.labels}>
+                  <td className="py-2 pr-4">{point.labels}</td>
+                  <td className="py-2 pr-4">{formatProofPercentage(point.agreement)}</td>
+                  <td className="py-2 pr-4">{formatProofPercentage(point.precision)}</td>
+                  <td className="py-2 pr-4">{formatProofPercentage(point.recall)}</td>
+                  <td className="py-2">
+                    {point.labelsByClass[positiveLabel] ?? 0} {positiveLabel}
+                    {negativeLabel ? `, ${point.labelsByClass[negativeLabel] ?? 0} ${negativeLabel}` : ""}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </section>
+      <ProofMethod heldOutSize={report.heldOut.size} />
+      <p className="break-all text-xs text-muted-foreground">
+        Held-out fingerprint {report.heldOut.fingerprint}
+        {report.priming.fingerprint ? ` · labels fingerprint ${report.priming.fingerprint}` : ""}
+      </p>
+    </main>
+  );
+}

package/infra/amplify-app-shell.js

@@ -3,7 +3,7 @@ import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider.js";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs.js";
-import { hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
+import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveProspectusAccountsEndpoint, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
 function environmentVariables(variables) {
     return Object.entries(variables).map(([name, value]) => ({ name, value }));
 }
@@ -85,6 +85,17 @@ export class AmplifyAppShellStack extends Stack {
                 ],
             }));
         }
+        const prospectusAccountsApiStageArn = config.cms.prospectusAccountsApiStageArn;
+        const prospectusEnvironment = prospectusAccountsApiStageArn
+            ? { PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT: resolveProspectusAccountsEndpoint(prospectusAccountsApiStageArn) }
+            : {};
+        if (prospectusAccountsApiStageArn) {
+            computeRole.addToPolicy(new iam.PolicyStatement({
+                sid: "InvokeProspectusAccountsAsRegisteredSite",
+                actions: ["execute-api:Invoke"],
+                resources: PROSPECTUS_PAPYRUS_SITE_ROUTES.map((route) => `${prospectusAccountsApiStageArn}/${route}`),
+            }));
+        }
         const cmsApp = new amplify.CfnApp(this, "App", {
             name: cmsAppName,
             description: `Papyrus newsroom CMS for ${config.siteId} (WEB_COMPUTE)`,
@@ -134,6 +145,7 @@ export class AmplifyAppShellStack extends Stack {
                 SITE_ENV: "production",
                 PAPYRUS_CONTENT_SOURCE: "published",
                 ...(revalidateSecretParameterName ? { PAPYRUS_REVALIDATE_SECRET_PARAMETER: revalidateSecretParameterName } : {}),
+                ...prospectusEnvironment,
             }),
         });
         let stagingBranch;
@@ -153,6 +165,7 @@ export class AmplifyAppShellStack extends Stack {
                     PAPYRUS_SITE_BRAND: config.brand,
                     SITE_ENV: "staging",
                     ...stagingMode,
+                    ...prospectusEnvironment,
                     NEXT_PUBLIC_PAPYRUS_STAGING_URL: stagingDomainName
                         ? `https://${stagingDomainName}`
                         : Fn.join("", ["https://staging.", cmsApp.attrDefaultDomain]),
@@ -191,6 +204,10 @@ export class AmplifyAppShellStack extends Stack {
         this.cmsAppId = cmsApp.attrAppId;
         new CfnOutput(this, "CmsAppId", { value: cmsApp.attrAppId, description: `Amplify app id for ${cmsAppName}` });
         new CfnOutput(this, "CmsOrigin", { value: productionOrigin });
+        new CfnOutput(this, "CmsComputeRoleArn", {
+            value: computeRole.roleArn,
+            description: `SSR compute role for ${cmsAppName}; the roleArn of its Prospectus site registration`,
+        });
         if (stagingEnabled) {
             new CfnOutput(this, "StagingOrigin", { value: stagingOrigin });
         }

package/infra/amplify-app-shell.ts

@@ -4,7 +4,7 @@ import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs";
-import { AmplifyAppShellSiteConfig, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
+import { AmplifyAppShellSiteConfig, PROSPECTUS_PAPYRUS_SITE_ROUTES, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveProspectusAccountsEndpoint, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
 
 function environmentVariables(variables: Record<string, string>): amplify.CfnBranch.EnvironmentVariableProperty[] {
   return Object.entries(variables).map(([name, value]) => ({ name, value }));
@@ -96,6 +96,20 @@ export class AmplifyAppShellStack extends Stack {
       );
     }
 
+    const prospectusAccountsApiStageArn = config.cms.prospectusAccountsApiStageArn;
+    const prospectusEnvironment = prospectusAccountsApiStageArn
+      ? { PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT: resolveProspectusAccountsEndpoint(prospectusAccountsApiStageArn) }
+      : {};
+    if (prospectusAccountsApiStageArn) {
+      computeRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "InvokeProspectusAccountsAsRegisteredSite",
+          actions: ["execute-api:Invoke"],
+          resources: PROSPECTUS_PAPYRUS_SITE_ROUTES.map((route) => `${prospectusAccountsApiStageArn}/${route}`),
+        }),
+      );
+    }
+
     const cmsApp = new amplify.CfnApp(this, "App", {
       name: cmsAppName,
       description: `Papyrus newsroom CMS for ${config.siteId} (WEB_COMPUTE)`,
@@ -148,6 +162,7 @@ export class AmplifyAppShellStack extends Stack {
         SITE_ENV: "production",
         PAPYRUS_CONTENT_SOURCE: "published",
         ...(revalidateSecretParameterName ? { PAPYRUS_REVALIDATE_SECRET_PARAMETER: revalidateSecretParameterName } : {}),
+        ...prospectusEnvironment,
       }),
     });
 
@@ -168,6 +183,7 @@ export class AmplifyAppShellStack extends Stack {
           PAPYRUS_SITE_BRAND: config.brand,
           SITE_ENV: "staging",
           ...stagingMode,
+          ...prospectusEnvironment,
           NEXT_PUBLIC_PAPYRUS_STAGING_URL: stagingDomainName
             ? `https://${stagingDomainName}`
             : Fn.join("", ["https://staging.", cmsApp.attrDefaultDomain]),
@@ -209,6 +225,10 @@ export class AmplifyAppShellStack extends Stack {
     this.cmsAppId = cmsApp.attrAppId;
     new CfnOutput(this, "CmsAppId", { value: cmsApp.attrAppId, description: `Amplify app id for ${cmsAppName}` });
     new CfnOutput(this, "CmsOrigin", { value: productionOrigin });
+    new CfnOutput(this, "CmsComputeRoleArn", {
+      value: computeRole.roleArn,
+      description: `SSR compute role for ${cmsAppName}; the roleArn of its Prospectus site registration`,
+    });
     if (stagingEnabled) {
       new CfnOutput(this, "StagingOrigin", { value: stagingOrigin });
     }

package/infra/site-config.js

@@ -16,7 +16,24 @@ const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}
 const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER"];
+const PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN = /^arn:aws:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+\/api$/;
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT"];
+/** Routes Prospectus admits for a registered Papyrus site (Prospectus accounts/papyrus-sites.ts). */
+export const PROSPECTUS_PAPYRUS_SITE_ROUTES = [
+    "GET/v1/identities/me",
+    "POST/v1/identities/google/challenge",
+    "POST/v1/identities/google/resolve",
+    "GET/v1/accounts",
+    "GET/v1/accounts/*",
+    "POST/v1/accounts/*/authorize",
+    "GET/v1/account-directory",
+    "GET/v1/account-directory/*",
+];
+export function resolveProspectusAccountsEndpoint(prospectusAccountsApiStageArn) {
+    const [, , , region, , apiPath] = prospectusAccountsApiStageArn.split(":");
+    const [apiId, stageName] = apiPath.split("/");
+    return `https://${apiId}.execute-api.${region}.amazonaws.com/${stageName}/`;
+}
 function originOfRedirectUrl(value) {
     try {
         return new URL(value).origin;
@@ -181,7 +198,7 @@ function parseStagingPreview(value) {
 }
 function parseCms(value) {
     const cmsRecord = requireObject(value, "cms");
-    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix", "redirects", "stagingPreview"], "cms");
+    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn"], "cms");
     const buildComputeType = cmsRecord.buildComputeType;
     if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
         fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -205,6 +222,7 @@ function parseCms(value) {
         stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
         redirects: parseRedirects(cmsRecord.redirects),
         stagingPreview: parseStagingPreview(cmsRecord.stagingPreview),
+        prospectusAccountsApiStageArn: optionalString(cmsRecord.prospectusAccountsApiStageArn, "cms.prospectusAccountsApiStageArn", PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN, "arn:aws:execute-api:<region>:<account>:<api id>/api"),
     };
     const reservedWord = COGNITO_RESERVED_WORDS.find((word) => cms.cognitoDomainPrefix.includes(word));
     if (reservedWord) {
@@ -212,7 +230,7 @@ function parseCms(value) {
     }
     for (const key of TEMPLATE_MANAGED_ENVIRONMENT_KEYS) {
         if (key in cms.environment) {
-            fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix and the revalidation secret parameter is derived from siteId");
+            fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn");
         }
     }
     if (cms.staging === false && cms.stagingDomainName) {

package/infra/site-config.ts

@@ -41,6 +41,7 @@ export type CmsConfig = {
   stagingDomainName?: string;
   stagingDomainPrefix?: string;
   redirects?: CmsRedirect[];
+  prospectusAccountsApiStageArn?: string;
 };
 
 export type AmplifyAppShellSiteConfig = {
@@ -95,7 +96,26 @@ const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}
 const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER"];
+const PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN = /^arn:aws:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+\/api$/;
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT"];
+
+/** Routes Prospectus admits for a registered Papyrus site (Prospectus accounts/papyrus-sites.ts). */
+export const PROSPECTUS_PAPYRUS_SITE_ROUTES = [
+  "GET/v1/identities/me",
+  "POST/v1/identities/google/challenge",
+  "POST/v1/identities/google/resolve",
+  "GET/v1/accounts",
+  "GET/v1/accounts/*",
+  "POST/v1/accounts/*/authorize",
+  "GET/v1/account-directory",
+  "GET/v1/account-directory/*",
+];
+
+export function resolveProspectusAccountsEndpoint(prospectusAccountsApiStageArn: string): string {
+  const [, , , region, , apiPath] = prospectusAccountsApiStageArn.split(":");
+  const [apiId, stageName] = apiPath.split("/");
+  return `https://${apiId}.execute-api.${region}.amazonaws.com/${stageName}/`;
+}
 function originOfRedirectUrl(value: string): string {
   try {
     return new URL(value).origin;
@@ -259,7 +279,7 @@ function parseStagingPreview(value: unknown): StagingPreviewConfig | undefined {
 
 function parseCms(value: unknown): CmsConfig {
   const cmsRecord = requireObject(value, "cms");
-  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix", "redirects", "stagingPreview"], "cms");
+  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn"], "cms");
   const buildComputeType = cmsRecord.buildComputeType;
   if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
     fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -288,6 +308,12 @@ function parseCms(value: unknown): CmsConfig {
     stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
     redirects: parseRedirects(cmsRecord.redirects),
     stagingPreview: parseStagingPreview(cmsRecord.stagingPreview),
+    prospectusAccountsApiStageArn: optionalString(
+      cmsRecord.prospectusAccountsApiStageArn,
+      "cms.prospectusAccountsApiStageArn",
+      PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN,
+      "arn:aws:execute-api:<region>:<account>:<api id>/api",
+    ),
   };
 
   const reservedWord = COGNITO_RESERVED_WORDS.find((word) => cms.cognitoDomainPrefix.includes(word));
@@ -296,7 +322,7 @@ function parseCms(value: unknown): CmsConfig {
   }
   for (const key of TEMPLATE_MANAGED_ENVIRONMENT_KEYS) {
     if (key in cms.environment) {
-      fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix and the revalidation secret parameter is derived from siteId");
+      fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn");
     }
   }
 

package/lib/approved-priming-proof-reports.ts

@@ -0,0 +1,6 @@
+/**
+ * Priming proof reports a publication owner approved for visitors, keyed by site brand id.
+ * A report reaches this map only through a reviewed commit of its
+ * `publications/priming-proofs/<brand id>.json` file; see docs/priming-proof.md.
+ */
+export const APPROVED_PRIMING_PROOF_REPORTS: Record<string, unknown> = {};

package/lib/priming-proof-report.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { APPROVED_PRIMING_PROOF_REPORTS } from "./approved-priming-proof-reports";
+
+export const PRIMING_PROOF_REPORT_VERSION = "cyclotron-priming-proof/v1";
+
+const nullableRatio = z.number().min(0).max(1).nullable();
+
+const primingProofPointSchema = z.object({
+  labels: z.number().int().min(0),
+  labelsByClass: z.record(z.string(), z.number().int().min(0)),
+  decided: z.number().int().min(0),
+  agreement: nullableRatio,
+  precision: nullableRatio,
+  recall: nullableRatio,
+  confusion: z.object({
+    truePositives: z.number().int().min(0),
+    falsePositives: z.number().int().min(0),
+    trueNegatives: z.number().int().min(0),
+    falseNegatives: z.number().int().min(0),
+  }),
+});
+
+export const primingProofReportSchema = z.object({
+  version: z.literal(PRIMING_PROOF_REPORT_VERSION),
+  proofId: z.string().min(1),
+  publication: z.string().min(1),
+  cyclotronId: z.string().min(1),
+  question: z.string().min(1),
+  labels: z.array(z.string().min(1)).length(2),
+  positiveLabel: z.string().min(1),
+  decisionModel: z.string().nullable(),
+  ranAt: z.string().min(1),
+  heldOut: z.object({
+    size: z.number().int().min(1),
+    byLabel: z.record(z.string(), z.number().int().min(0)),
+    fingerprint: z.string().min(1),
+    frozenAt: z.string().min(1),
+    source: z.string().min(1),
+  }),
+  priming: z.object({
+    acceptedExamples: z.number().int().min(0),
+    excludedBecauseInHeldOut: z.number().int().min(0),
+    fingerprint: z.string().nullable(),
+    order: z.string().min(1),
+  }),
+  conditions: z.object({
+    freshStorePerPoint: z.boolean(),
+    rubric: z.string().min(1),
+    optimizer: z.boolean(),
+    reviewProgram: z.boolean(),
+  }),
+  points: z.array(primingProofPointSchema).min(1),
+});
+
+export type PrimingProofReport = z.infer<typeof primingProofReportSchema>;
+export type PrimingProofPoint = z.infer<typeof primingProofPointSchema>;
+
+export type PrimingProofHeadline = {
+  baseline: PrimingProofPoint;
+  latest: PrimingProofPoint;
+  agreementChangeInPoints: number | null;
+};
+
+export function parsePrimingProofReport(value: unknown): PrimingProofReport {
+  const report = primingProofReportSchema.parse(value);
+  if (report.points[0].labels !== 0) {
+    throw new Error("A priming proof report must start with the zero-label baseline.");
+  }
+  return report;
+}
+
+export function approvedPrimingProofReport(brandId: string): PrimingProofReport | null {
+  const approvedReport = APPROVED_PRIMING_PROOF_REPORTS[brandId];
+  return approvedReport === undefined ? null : parsePrimingProofReport(approvedReport);
+}
+
+export function primingProofHeadline(report: PrimingProofReport): PrimingProofHeadline {
+  const baseline = report.points[0];
+  const latest = report.points[report.points.length - 1];
+  const agreementChangeInPoints =
+    baseline.agreement === null || latest.agreement === null
+      ? null
+      : Math.round((latest.agreement - baseline.agreement) * 1000) / 10;
+  return { baseline, latest, agreementChangeInPoints };
+}
+
+export function formatProofPercentage(ratio: number | null): string {
+  return ratio === null ? "n/a" : `${Math.round(ratio * 1000) / 10}%`;
+}

package/lib/prospectus-site-identity.ts

@@ -0,0 +1,303 @@
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { defaultProvider } from "@aws-sdk/credential-provider-node";
+import { SignatureV4 } from "@smithy/signature-v4";
+import { HttpRequest } from "@smithy/protocol-http";
+import { Sha256 } from "@aws-crypto/sha256-js";
+import { CognitoJwtVerifier } from "aws-jwt-verify";
+import type { JwksCache } from "aws-jwt-verify/jwk";
+
+/**
+ * A Papyrus site's server-side view of Prospectus, the single account service.
+ *
+ * The site signs requests with its own runtime role (the Amplify SSR compute role
+ * registered in Prospectus). People sign in through the site's Google-only Cognito
+ * client; Prospectus binds that sign-in to a canonical person through a one-time
+ * challenge nonce. Papyrus keeps no account or membership tables: every answer here
+ * comes from Prospectus, and publication-level grants are never inferred from an
+ * account role.
+ */
+
+export type ProspectusRole = "owner" | "admin" | "member" | "viewer";
+export type ProspectusOperation = "console:read" | "console:write" | "members:read" | "members:write";
+
+export interface ProspectusPerson {
+  id: string;
+  createdAt: string;
+}
+
+export interface ProspectusAccountAuthorization {
+  allowed: true;
+  accountId: string;
+  personId: string;
+  product: string;
+  role: ProspectusRole;
+  operation: ProspectusOperation;
+  revision: number;
+}
+
+export interface ProspectusDirectoryAccount {
+  id: string;
+  name: string;
+  role: ProspectusRole;
+  products: Array<{ product: string; status: "active" | "disabled" }>;
+}
+
+export interface ProspectusRequest {
+  path: string;
+  method: "GET" | "POST";
+  body?: unknown;
+  humanAccessToken?: string;
+  identityToken?: string;
+}
+
+export type ProspectusTransport = (request: ProspectusRequest) => Promise<unknown>;
+
+export class ProspectusAccountsError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export interface TemporaryRuntimeCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  expiration?: Date;
+}
+
+export interface SignedProspectusTransportOptions {
+  endpoint: string;
+  region: string;
+  runtimeCredentials?: () => Promise<TemporaryRuntimeCredentials>;
+  fetcher?: typeof fetch;
+}
+
+export function signedProspectusTransport(options: SignedProspectusTransportOptions): ProspectusTransport {
+  const endpoint = new URL(options.endpoint);
+  if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error("Use an HTTPS Prospectus accounts endpoint.");
+  }
+  const runtimeCredentials = options.runtimeCredentials ?? defaultProvider();
+  const fetcher = options.fetcher ?? fetch;
+  return async ({ path, method, body, humanAccessToken, identityToken }) => {
+    const credentials = await runtimeCredentials();
+    if (!credentials.sessionToken || (credentials.expiration && credentials.expiration.getTime() <= Date.now())) {
+      throw new Error("Prospectus calls require the site's temporary runtime credentials; static access keys are refused.");
+    }
+    const url = new URL(`${endpoint.toString().replace(/\/$/, "")}${path}`);
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+    const headers: Record<string, string> = {
+      host: url.host,
+      ...(humanAccessToken ? { "x-prospectus-human-token": humanAccessToken } : {}),
+      ...(identityToken ? { "x-prospectus-identity-token": identityToken } : {}),
+      ...(payload ? { "content-type": "application/json" } : {}),
+    };
+    const signer = new SignatureV4({ service: "execute-api", region: options.region, credentials, sha256: Sha256 });
+    const signed = await signer.sign(
+      new HttpRequest({ protocol: url.protocol, hostname: url.hostname, path: url.pathname, method, headers, body: payload }),
+    );
+    const response = await fetcher(url, { method, headers: signed.headers, body: payload, cache: "no-store", redirect: "error" });
+    const responseBody = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new ProspectusAccountsError(response.status, responseBody.error ?? "request_failed", responseBody.message ?? "Prospectus request failed.");
+    }
+    return responseBody;
+  };
+}
+
+export class ProspectusSiteAccounts {
+  constructor(private readonly transport: ProspectusTransport) {}
+
+  requestGoogleSignInChallenge(): Promise<{ challengeId: string; nonce: string; expiresAt: number }> {
+    return this.transport({ path: "/v1/identities/google/challenge", method: "POST", body: {} }) as Promise<{
+      challengeId: string;
+      nonce: string;
+      expiresAt: number;
+    }>;
+  }
+
+  resolveGoogleSignIn(challengeId: string, humanAccessToken: string, identityToken: string): Promise<{ person: ProspectusPerson }> {
+    return this.transport({
+      path: "/v1/identities/google/resolve",
+      method: "POST",
+      body: { challengeId },
+      humanAccessToken,
+      identityToken,
+    }) as Promise<{ person: ProspectusPerson }>;
+  }
+
+  currentPerson(humanAccessToken: string): Promise<{ person: ProspectusPerson | null }> {
+    return this.transport({ path: "/v1/identities/me", method: "GET", humanAccessToken }) as Promise<{ person: ProspectusPerson | null }>;
+  }
+
+  authorizeAccountOperation(humanAccessToken: string, accountId: string, operation: ProspectusOperation): Promise<ProspectusAccountAuthorization> {
+    return this.transport({
+      path: `/v1/accounts/${encodeURIComponent(accountId)}/authorize`,
+      method: "POST",
+      body: { operation },
+      humanAccessToken,
+    }) as Promise<ProspectusAccountAuthorization>;
+  }
+
+  accountDirectory(humanAccessToken: string): Promise<{ person: ProspectusPerson | null; accounts: ProspectusDirectoryAccount[] }> {
+    return this.transport({ path: "/v1/account-directory", method: "GET", humanAccessToken }) as Promise<{
+      person: ProspectusPerson | null;
+      accounts: ProspectusDirectoryAccount[];
+    }>;
+  }
+}
+
+export interface GoogleOnlyCognitoClient {
+  hostedUiOrigin: string;
+  userPoolId: string;
+  clientId: string;
+  redirectUri: string;
+}
+
+export interface PendingProspectusSignIn {
+  challengeId: string;
+  nonce: string;
+  state: string;
+  codeVerifier: string;
+  expiresAt: number;
+}
+
+export interface CognitoTokens {
+  accessToken: string;
+  idToken: string;
+  refreshToken?: string;
+  expiresInSeconds: number;
+}
+
+export type CognitoTokenVerifier = (tokens: CognitoTokens, expectedNonce: string) => Promise<void>;
+
+function base64UrlRandom(byteLength: number): string {
+  return randomBytes(byteLength).toString("base64url");
+}
+
+function constantTimeEquals(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+
+export async function beginProspectusGoogleSignIn(
+  accounts: ProspectusSiteAccounts,
+  cognitoClient: GoogleOnlyCognitoClient,
+): Promise<{ authorizationUrl: string; pendingSignIn: PendingProspectusSignIn }> {
+  const challenge = await accounts.requestGoogleSignInChallenge();
+  const state = base64UrlRandom(32);
+  const codeVerifier = base64UrlRandom(48);
+  const authorizationUrl = new URL("/oauth2/authorize", cognitoClient.hostedUiOrigin);
+  authorizationUrl.search = new URLSearchParams({
+    response_type: "code",
+    client_id: cognitoClient.clientId,
+    redirect_uri: cognitoClient.redirectUri,
+    scope: "openid email profile",
+    identity_provider: "Google",
+    state,
+    nonce: challenge.nonce,
+    code_challenge: createHash("sha256").update(codeVerifier).digest("base64url"),
+    code_challenge_method: "S256",
+  }).toString();
+  return {
+    authorizationUrl: authorizationUrl.toString(),
+    pendingSignIn: { challengeId: challenge.challengeId, nonce: challenge.nonce, state, codeVerifier, expiresAt: challenge.expiresAt },
+  };
+}
+
+export function cognitoTokenVerifier(cognitoClient: GoogleOnlyCognitoClient, signingKeyCache?: JwksCache): CognitoTokenVerifier {
+  const verifierOptions = signingKeyCache ? { jwksCache: signingKeyCache } : undefined;
+  const accessTokenVerifier = CognitoJwtVerifier.create({ userPoolId: cognitoClient.userPoolId, tokenUse: "access", clientId: cognitoClient.clientId }, verifierOptions);
+  const identityTokenVerifier = CognitoJwtVerifier.create({ userPoolId: cognitoClient.userPoolId, tokenUse: "id", clientId: cognitoClient.clientId }, verifierOptions);
+  return async (tokens, expectedNonce) => {
+    const accessClaims = await accessTokenVerifier.verify(tokens.accessToken);
+    const identityClaims = await identityTokenVerifier.verify(tokens.idToken);
+    if (identityClaims.nonce !== expectedNonce) throw new ProspectusAccountsError(401, "nonce_mismatch", "Sign-in did not carry this site's Prospectus challenge.");
+    if (identityClaims.sub !== accessClaims.sub) throw new ProspectusAccountsError(401, "token_pair_mismatch", "Access and identity tokens describe different people.");
+  };
+}
+
+export interface CompleteProspectusGoogleSignInInput {
+  accounts: ProspectusSiteAccounts;
+  cognitoClient: GoogleOnlyCognitoClient;
+  pendingSignIn: PendingProspectusSignIn;
+  returnedState: string;
+  authorizationCode: string;
+  verifyCognitoTokens?: CognitoTokenVerifier;
+  fetcher?: typeof fetch;
+  nowInSeconds?: number;
+}
+
+export async function completeProspectusGoogleSignIn(
+  input: CompleteProspectusGoogleSignInInput,
+): Promise<{ person: ProspectusPerson; accessToken: string; refreshToken?: string; accessTokenExpiresAt: number }> {
+  const nowInSeconds = input.nowInSeconds ?? Math.floor(Date.now() / 1000);
+  if (nowInSeconds >= input.pendingSignIn.expiresAt) {
+    throw new ProspectusAccountsError(401, "sign_in_expired", "Sign-in took too long. Start again.");
+  }
+  if (!constantTimeEquals(input.returnedState, input.pendingSignIn.state)) {
+    throw new ProspectusAccountsError(401, "state_mismatch", "Sign-in response does not belong to this browser's sign-in.");
+  }
+  const tokenResponse = await (input.fetcher ?? fetch)(new URL("/oauth2/token", input.cognitoClient.hostedUiOrigin), {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: input.cognitoClient.clientId,
+      code: input.authorizationCode,
+      redirect_uri: input.cognitoClient.redirectUri,
+      code_verifier: input.pendingSignIn.codeVerifier,
+    }).toString(),
+    cache: "no-store",
+    redirect: "error",
+  });
+  const tokenBody = await tokenResponse.json().catch(() => ({}));
+  if (!tokenResponse.ok || typeof tokenBody.access_token !== "string" || typeof tokenBody.id_token !== "string") {
+    throw new ProspectusAccountsError(401, "code_exchange_failed", "Cognito did not complete the sign-in.");
+  }
+  const tokens: CognitoTokens = {
+    accessToken: tokenBody.access_token,
+    idToken: tokenBody.id_token,
+    refreshToken: typeof tokenBody.refresh_token === "string" ? tokenBody.refresh_token : undefined,
+    expiresInSeconds: Number(tokenBody.expires_in) || 0,
+  };
+  await (input.verifyCognitoTokens ?? cognitoTokenVerifier(input.cognitoClient))(tokens, input.pendingSignIn.nonce);
+  const { person } = await input.accounts.resolveGoogleSignIn(input.pendingSignIn.challengeId, tokens.accessToken, tokens.idToken);
+  return {
+    person,
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    accessTokenExpiresAt: nowInSeconds + tokens.expiresInSeconds,
+  };
+}
+
+export async function authorizeSignedInPersonForAccount(
+  accounts: ProspectusSiteAccounts,
+  humanAccessToken: string,
+  accountId: string,
+  operation: ProspectusOperation,
+): Promise<ProspectusAccountAuthorization> {
+  const { person } = await accounts.currentPerson(humanAccessToken);
+  if (!person) throw new ProspectusAccountsError(401, "unknown_person", "Sign in again: Prospectus does not recognize this session.");
+  const authorization = await accounts.authorizeAccountOperation(humanAccessToken, accountId, operation);
+  if (authorization.allowed !== true || authorization.personId !== person.id || authorization.accountId !== accountId || authorization.operation !== operation) {
+    throw new ProspectusAccountsError(403, "not_authorized", "Prospectus did not authorize this account operation.");
+  }
+  return authorization;
+}
+
+export const CYCLOTRON_LAB_PRODUCT = "cyclotron";
+
+export async function signedInPersonHasCyclotronLabAccess(accounts: ProspectusSiteAccounts, humanAccessToken: string): Promise<boolean> {
+  const directory = await accounts.accountDirectory(humanAccessToken);
+  if (!directory.person) return false;
+  return directory.accounts.some((account) =>
+    account.products.some((product) => product.product === CYCLOTRON_LAB_PRODUCT && product.status === "active"),
+  );
+}

package/package.json

@@ -99,6 +99,7 @@
     "./components/presentation-footer": "./components/presentation-footer.tsx",
     "./components/presentation-header": "./components/presentation-header.tsx",
     "./components/presentation-rhythm-hrule": "./components/presentation-rhythm-hrule.tsx",
+    "./components/priming-proof-page": "./components/priming-proof-page.tsx",
     "./components/publication-cyclotron-panel": "./components/publication-cyclotron-panel.tsx",
     "./components/reader-auth-control": "./components/reader-auth-control.tsx",
     "./components/reader-auth-state": "./components/reader-auth-state.ts",
@@ -139,6 +140,7 @@
     "./lib/amplify-outputs-guard": "./lib/amplify-outputs-guard.ts",
     "./lib/amplify-outputs-path": "./lib/amplify-outputs-path.ts",
     "./lib/amplify-server-runtime": "./lib/amplify-server-runtime.ts",
+    "./lib/approved-priming-proof-reports": "./lib/approved-priming-proof-reports.ts",
     "./lib/archive-data": "./lib/archive-data.ts",
     "./lib/archive-types": "./lib/archive-types.ts",
     "./lib/articles": "./lib/articles.ts",
@@ -205,6 +207,8 @@
     "./lib/plugin-settings": "./lib/plugin-settings.ts",
     "./lib/presentation-footer": "./lib/presentation-footer.ts",
     "./lib/pretext-layout": "./lib/pretext-layout.ts",
+    "./lib/priming-proof-report": "./lib/priming-proof-report.ts",
+    "./lib/prospectus-site-identity": "./lib/prospectus-site-identity.ts",
     "./lib/public-placeholder-config": "./lib/public-placeholder-config.ts",
     "./lib/publication-cyclotron": "./lib/publication-cyclotron.ts",
     "./lib/publication-items": "./lib/publication-items.ts",
@@ -259,10 +263,12 @@
     "./app/[year]/[month]/[day]/page/[pageNumber]/page": "./app/[year]/[month]/[day]/page/[pageNumber]/page.tsx",
     "./app/[year]/[month]/[day]/section/[sectionKey]/page": "./app/[year]/[month]/[day]/section/[sectionKey]/page.tsx",
     "./app/api/archive/editions/route": "./app/api/archive/editions/route.ts",
+    "./app/api/cyclotron/priming-proof/route": "./app/api/cyclotron/priming-proof/route.ts",
     "./app/api/media/[...path]/route": "./app/api/media/[...path]/route.ts",
     "./app/api/revalidate/route": "./app/api/revalidate/route.ts",
     "./app/archive/page": "./app/archive/page.tsx",
     "./app/articles/[slug]/page": "./app/articles/[slug]/page.tsx",
+    "./app/cyclotron/page": "./app/cyclotron/page.tsx",
     "./app/layout": "./app/layout.tsx",
     "./app/newsroom/[section]/[...selection]/page": "./app/newsroom/[section]/[...selection]/page.tsx",
     "./app/newsroom/[section]/page": "./app/newsroom/[section]/page.tsx",
@@ -325,18 +331,22 @@
       "optional": true
     }
   },
-  "version": "1.0.0-next.61",
+  "version": "1.0.0-next.62",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
+    "@aws-crypto/sha256-js": "5.2.0",
     "@aws-sdk/client-cognito-identity-provider": "3.1045.0",
     "@aws-sdk/client-lambda": "^3.1045.0",
     "@aws-sdk/client-s3": "^3.1045.0",
     "@aws-sdk/client-ssm": "^3.1045.0",
+    "@aws-sdk/credential-provider-node": "3.972.84",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
     "@base-ui/react": "^1.5.0",
     "@chenglou/pretext": "^0.0.7",
     "@kanbus/ui": "https://github.com/AnthusAI/Kanbus/releases/download/ui-v0.2.0/kanbus-ui-0.2.0.tgz",
     "@radix-ui/colors": "3.0.0",
+    "@smithy/protocol-http": "5.4.1",
+    "@smithy/signature-v4": "5.7.4",
     "@streamdown/cjk": "^1.0.3",
     "@streamdown/code": "^1.1.1",
     "@streamdown/math": "^1.0.2",
@@ -345,6 +355,7 @@
     "ai": "^6.0.191",
     "anthus-vultus": "github:AnthusAI/Vultus#af98d57",
     "aws-amplify": "^6.17.0",
+    "aws-jwt-verify": "4.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-next.61",
+  "version": "1.0.0-next.62",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",
@@ -66,6 +66,14 @@
         "revalidate": "60"
       }
     },
+    {
+      "file": "app/api/cyclotron/priming-proof/route.ts",
+      "hasDefault": false,
+      "exports": [
+        "GET"
+      ],
+      "config": {}
+    },
     {
       "file": "app/api/media/[...path]/route.ts",
       "hasDefault": false,
@@ -107,6 +115,14 @@
         "revalidate": "60"
       }
     },
+    {
+      "file": "app/cyclotron/page.tsx",
+      "hasDefault": true,
+      "exports": [
+        "metadata"
+      ],
+      "config": {}
+    },
     {
       "file": "app/layout.tsx",
       "hasDefault": true,