@anthusai/papyrus 1.0.0-next.9 → 1.0.0

package/lib/plugin-settings.ts

@@ -0,0 +1,11 @@
+export type PluginOutputs = { custom?: { papyrusPlugins?: Record<string, Record<string, unknown>> } };
+
+/** The settings a deployed plugin published in `amplify_outputs.json`, or null when the site did not enable it. */
+export function pluginSettings(outputs: PluginOutputs | null | undefined, name: string): Record<string, unknown> | null {
+  return outputs?.custom?.papyrusPlugins?.[name] ?? null;
+}
+
+export function signupForms(outputs: PluginOutputs | null | undefined): string[] {
+  const forms = pluginSettings(outputs, "signup")?.forms;
+  return Array.isArray(forms) ? forms.filter((form): form is string => typeof form === "string") : [];
+}

package/lib/presentation-footer.ts

@@ -1,6 +1,7 @@
 import { getEditionSectionItems } from "./edition-sections";
 import type { EditionContent } from "./content-types";
 import type { PublicationItem } from "./publication-items";
+import { toPublicReaderPath } from "./reader-base-path";
 
 export type PresentationFooterEntry = {
   section: string;
@@ -43,9 +44,9 @@ export type PresentationFooterGeometry = {
 };
 
 export const PRESENTATION_FOOTER_UTILITIES: PresentationFooterUtilityEntry[] = [
-  { id: "archive", label: "Archive", href: "/archive", disabled: false },
+  { id: "archive", label: "Archive", href: toPublicReaderPath("/archive"), disabled: false },
   { id: "newsDesk", label: "Newsroom", href: "/newsroom", disabled: false },
-  { id: "settings", label: "Settings", href: "/settings", disabled: false },
+  { id: "settings", label: "Settings", href: toPublicReaderPath("/settings"), disabled: false },
   { id: "login", label: "LOGIN", disabled: true },
 ];
 

package/lib/pretext-layout.ts

@@ -1,4 +1,5 @@
 import {
+  clearCache,
   layoutNextLine,
   prepareWithSegments,
   type LayoutCursor,
@@ -78,14 +79,18 @@ export function layoutAllTextLines({
   linePaintHeight,
   fontSize,
   fontFamily,
-}: Omit<LayoutTextLinesOptions, "cursor" | "maxHeight" | "obstacles">): TextLine[] {
+  obstacles = [],
+}: Omit<LayoutTextLinesOptions, "cursor" | "maxHeight" | "obstacles"> & { obstacles?: TextObstacle[] }): TextLine[] {
   const lines: TextLine[] = [];
   let cursor: LayoutCursor = { segmentIndex: 0, graphemeIndex: 0 };
 
   for (let lineIndex = 0; lineIndex < 2000; lineIndex += 1) {
-    const line = layoutNextLine(prepared, cursor, maxWidth);
+    const y = lineIndex * lineHeight;
+    const slot = getAvailableSlot(maxWidth, y, linePaintHeight, obstacles);
+    if (!slot) continue;
+    const line = layoutNextLine(prepared, cursor, slot.width);
     if (!line) return lines;
-    lines.push(toTextLine(line, 0, lineIndex * lineHeight, fontSize, fontFamily, lineHeight, linePaintHeight));
+    lines.push(toTextLine(line, slot.x, y, fontSize, fontFamily, lineHeight, linePaintHeight));
     cursor = line.end;
   }
 
@@ -177,3 +182,7 @@ function toTextLine(line: LayoutLine, x: number, y: number, fontSize: number, fo
 function clamp(value: number, min: number, max: number): number {
   return Math.max(min, Math.min(max, value));
 }
+
+export function clearPretextMeasurementCache(): void {
+  clearCache();
+}

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/lib/publication-cyclotron.ts

@@ -0,0 +1,74 @@
+import type {CyclotronDecision,CyclotronReview} from 'cyclotron/sdk-types';
+import type {CyclotronStatus} from 'cyclotron/cyclotron-status';
+import type {ReviewControlReview} from 'cyclotron/components/review-control';
+
+export type PublicationScope={accountId:string;publicationId:string;bindingRevision:string};
+export type PublicationEnvelope=PublicationScope&{contractVersion:'cyclotron-publication/v1';publicationId:string;bindingRevision:string;features?:{frozenContext:boolean;replayExport:boolean;steering:boolean};outputs:Array<{id:string;question:string;classes:string[];positiveLabel:string|null}>};
+export type PublicationStatus=PublicationEnvelope&{classifiers:Record<string,CyclotronStatus>};
+export type PublicationRevisionRef={listId:string;itemId:string;revision:number;contentHash:string};
+export type PublicationContext={contextId:string;decisionId:string;publicationId:string;sourceRef:PublicationRevisionRef;bindingRef:PublicationRevisionRef;source:{id:string;values:Record<string,unknown>};binding:{values:{accountId:string;publicationId:string;revision:string;outputs:string[]}}};
+export type PublicationHistoryRow={decision:CyclotronDecision;item:Record<string,unknown>;state?:string;reviews:Record<string,CyclotronReview>;context?:PublicationContext;historicalContext?:boolean;provenanceUnavailable?:boolean;feedbackReconciliationRequired?:boolean};
+export type PublicationHistory=PublicationEnvelope&{history:PublicationHistoryRow[]};
+export type PublicationReviewPayload={bindingRevision:string;decisionId:string;classifier:string;predictionVersion:number;predictionFingerprint:string;requestId:string;label:string;explanation:string;reasonCode:string|null;contextId?:string};
+export type PublicationSteeringInput={requestId:string;explanation:string}&({action:'evaluate';proposal:Record<string,unknown>}|{action:'promote';trialFingerprint:string});
+export type PublicationSteeringPayload=PublicationSteeringInput&{bindingRevision:string;bindingRef:PublicationRevisionRef;classifier:string;expectedFingerprint:string};
+
+function ordered(value:unknown):unknown{
+ if(Array.isArray(value))return value.map(ordered);
+ if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).sort(([a],[b])=>a.localeCompare(b)).map(([key,item])=>[key,ordered(item)]));
+ return value;
+}
+
+/** Stable cache/component identity; length-safe even when IDs contain delimiters. */
+export function publicationScopeKey(scope:PublicationScope):string{
+ if([scope.accountId,scope.publicationId,scope.bindingRevision].some(value=>typeof value!=='string'||!value.trim()))throw new Error('Complete publication account scope required');
+ return JSON.stringify([scope.accountId,scope.publicationId,scope.bindingRevision]);
+}
+
+export function assertPublicationScope(status:PublicationStatus,history:PublicationHistory){
+ if(status.contractVersion!=='cyclotron-publication/v1'||history.contractVersion!==status.contractVersion||publicationScopeKey(status)!==publicationScopeKey(history)||status.publicationId!==history.publicationId||status.bindingRevision!==history.bindingRevision)throw new Error('Publication snapshot binding mismatch');
+ const outputs=new Set(status.outputs.map(output=>output.id));
+ if(!outputs.size||outputs.size!==status.outputs.length||status.outputs.some(output=>status.classifiers[output.id]?.cyclotron.classifier!==output.id)||JSON.stringify(history.outputs)!==JSON.stringify(status.outputs))throw new Error('Publication snapshot is incomplete');
+ if(Object.keys(status.classifiers).some(id=>!outputs.has(id))||history.outputs.some(output=>!outputs.has(output.id))||history.history.some(row=>[...Object.keys(row.decision.classifiers),...Object.keys(row.reviews)].some(id=>!outputs.has(id))))throw new Error('Snapshot includes an output outside this publication');
+ if(history.history.some(row=>row.context&&(row.context.binding.values.accountId!==status.accountId||row.context.publicationId!==status.publicationId||row.context.decisionId!==row.decision.decisionId||JSON.stringify(ordered(row.context.source.values))!==JSON.stringify(ordered(row.item)))))throw new Error('Historical source context mismatch');
+}
+
+/** Explicit output target and incumbent pin; never a global review-rate mutation. */
+export function publicationSteeringPayload(status:PublicationStatus,classifier:string,bindingRef:PublicationRevisionRef,command:PublicationSteeringInput):PublicationSteeringPayload{
+ if(!status.outputs.some(output=>output.id===classifier)||!status.classifiers[classifier])throw new Error('Steering output is outside this publication');
+ if(!command.requestId.trim()||!command.explanation.trim())throw new Error('Steering needs a stable identity and explicit explanation');
+ const fingerprint=status.classifiers[classifier].cyclotron.fingerprint;
+ if(!fingerprint)throw new Error('Active classifier fingerprint unavailable');
+ if(command.action==='evaluate'){
+  if(!Object.keys(command.proposal).length||Object.keys(command.proposal).some(key=>!['rubric','tasks','example_ids','dynamic_elements'].includes(key)))throw new Error('Native proposal fields required');
+ }else if(command.action!=='promote'||!command.trialFingerprint.trim())throw new Error('An explicitly evaluated trial is required');
+ return {...command,explanation:command.explanation.trim(),bindingRevision:status.bindingRevision,bindingRef,classifier,expectedFingerprint:fingerprint};
+}
+
+export function publicationReviewPayload(binding:PublicationEnvelope,row:PublicationHistoryRow,classifier:string,review:ReviewControlReview,requestId:string):PublicationReviewPayload{
+ if(row.context&&row.context.binding.values.accountId!==binding.accountId)throw new Error('Review account context mismatch');
+ if(row.historicalContext||row.provenanceUnavailable||row.feedbackReconciliationRequired||row.context&&row.context.binding.values.revision!==binding.bindingRevision)throw new Error('Historical source or binding revision is read-only');
+ const output=binding.outputs.find(output=>output.id===classifier);const prediction=row.decision.classifiers[classifier];
+ if(!output||!prediction||review.decisionId!==row.decision.decisionId||review.itemId!==row.decision.itemId)throw new Error('Review does not match the displayed publication decision');
+ if(!review.label||!output.classes.includes(review.label))throw new Error('Choose an explicit classification label');
+ if(!requestId.trim())throw new Error('A stable review request identity is required');
+ return {bindingRevision:binding.bindingRevision,decisionId:row.decision.decisionId,classifier,predictionVersion:prediction.version,predictionFingerprint:prediction.fingerprint,requestId,label:review.label,explanation:review.explanation?.trim()??'',reasonCode:review.reasonCode,...(row.context?{contextId:row.context.contextId}:{})};
+}
+
+/** Host chooses an authenticated same-origin BFF; storage mode never changes UI semantics. */
+export function createPublicationClient(scope:PublicationScope,request:(operation:string,payload:Record<string,unknown>,scope:Readonly<PublicationScope>)=>Promise<PublicationEnvelope&Record<string,unknown>>,currentScope:()=>PublicationScope|null){
+ const pinned=Object.freeze({accountId:scope.accountId,publicationId:scope.publicationId,bindingRevision:scope.bindingRevision});
+ const key=publicationScopeKey(pinned);
+ const assertSelected=()=>{const current=currentScope();if(!current||publicationScopeKey(current)!==key)throw new Error('Publication account selection changed; refresh context');};
+ const command=async(operation:string,payload:Record<string,unknown>)=>{
+  assertSelected();
+  if('bindingRevision' in payload&&payload.bindingRevision!==pinned.bindingRevision)throw new Error('Publication binding changed; refresh context');
+  const value=await request(operation,payload,pinned);
+  assertSelected();
+  if(value.contractVersion!=='cyclotron-publication/v1'||publicationScopeKey(value)!==key)throw new Error('Publication response contract mismatch');
+  return value;
+ };
+ return {scope:pinned,cacheKey:key,command,status:async()=>await command('status',{}) as PublicationStatus,history:async()=>await command('history',{}) as PublicationHistory,
+  review:async(payload:PublicationReviewPayload)=>command('review',payload),
+  steer:async(payload:PublicationSteeringPayload)=>command('steer',payload),replayRecords:async()=>command('replay',{})};
+}

package/lib/rate-limit-retry.ts

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

package/lib/reader-base-path.ts

@@ -0,0 +1,24 @@
+import { SITE_BRAND } from "./site-brand";
+
+export function normalizeReaderBasePath(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim().replace(/\/+$/, "");
+  if (!trimmed) return "";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+export function getReaderBasePath(): string {
+  return normalizeReaderBasePath(SITE_BRAND.readerBasePath);
+}
+
+export function toPublicReaderPath(path: string, readerBasePath: string = getReaderBasePath()): string {
+  if (!readerBasePath) return path;
+  if (path === "/" || path === "") return readerBasePath;
+  return `${readerBasePath}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+export function toInternalReaderPath(path: string, readerBasePath: string = getReaderBasePath()): string {
+  if (!readerBasePath) return path;
+  if (path === readerBasePath || path === `${readerBasePath}/`) return "/";
+  if (path.startsWith(`${readerBasePath}/`)) return path.slice(readerBasePath.length);
+  return path;
+}

package/lib/reader-cache-lifetime.ts

@@ -0,0 +1,5 @@
+/**
+ * Seconds a Pretext reader page may be served from a shared cache (Next sends `s-maxage` equal to its `revalidate`).
+ * Next needs a literal in each route's `export const revalidate`, so scripts/test-reader-cache-lifetime.ts keeps them equal to this.
+ */
+export const READER_PAGE_REVALIDATE_SECONDS = 60;