@anthusai/papyrus 2.0.0-next.1 → 2.0.0-next.100

package/lib/review-client.ts

@@ -0,0 +1,120 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import { getCurrentUser } from "aws-amplify/auth";
+import {
+  answerUpdate, isDue, normalizeReviewRow, timeoutUpdate,
+  type AnswerInput, type ReviewRequest,
+} from "./review-requests";
+
+/**
+ * Review requests through the site's own authenticated API (user pool; editors and admins). The condition `state = open`
+ * on every change means two people answering at once, or an answer racing the deadline, cannot both win.
+ */
+
+const FIELDS = "id subject mode reason ask raisedBy raisedAt deadline state answer links history appliedIn updatedAt";
+const MAX_PAGES = 10;
+
+type GraphQLResult = { data?: Record<string, any>; errors?: { message?: string; errorType?: string }[] };
+
+async function run(query: string, variables: Record<string, unknown>): Promise<GraphQLResult> {
+  const client = generateClient({ authMode: "userPool" });
+  try {
+    return (await client.graphql({ query, variables })) as GraphQLResult;
+  } catch (error) {
+    // Amplify throws the response when AppSync returns errors.
+    return (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+}
+
+export type ReviewLoad = { state: "ready"; requests: ReviewRequest[]; readIds: string[]; userKey: string } | { state: "forbidden" } | { state: "unavailable" };
+
+export async function currentUserKey(): Promise<string> {
+  return (await getCurrentUser()).userId;
+}
+
+/** Loads every request (newest pages first), marks due soft reviews as timed out ("proceeded without review"), and reads this user's marks. */
+export async function loadReviews(now: Date = new Date()): Promise<ReviewLoad> {
+  let userKey: string;
+  try {
+    userKey = await currentUserKey();
+  } catch {
+    return { state: "unavailable" };
+  }
+  const rows: Record<string, unknown>[] = [];
+  let nextToken: string | null = null;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const result = await run(
+      `query ListReviews($limit: Int, $nextToken: String) { listReviewRequests(limit: $limit, nextToken: $nextToken) { items { ${FIELDS} } nextToken } }`,
+      { limit: 500, nextToken },
+    );
+    if (result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) return { state: "forbidden" };
+    const connection = result.data?.listReviewRequests;
+    if (result.errors?.length || !connection) return { state: "unavailable" };
+    rows.push(...connection.items.filter(Boolean));
+    nextToken = connection.nextToken ?? null;
+    if (!nextToken) break;
+  }
+  const requests = rows.map(normalizeReviewRow);
+  for (const [index, request] of requests.entries()) {
+    if (!isDue(request, now)) continue;
+    const update = timeoutUpdate(request, now);
+    const written = await run(
+      `mutation Expire($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+      { input: update, condition: { state: { eq: "open" } } },
+    );
+    const row = written.data?.updateReviewRequest;
+    requests[index] = row ? normalizeReviewRow(row) : { ...request, state: "timed_out", updatedAt: String(update.updatedAt), history: JSON.parse(String(update.history)) };
+  }
+  const marks = await run(
+    `query Marks($filter: ModelReviewReadMarkFilterInput, $limit: Int) { listReviewReadMarks(filter: $filter, limit: $limit) { items { requestId } } }`,
+    { filter: { userKey: { eq: userKey } }, limit: 5000 },
+  );
+  const readIds = (marks.data?.listReviewReadMarks?.items ?? []).filter(Boolean).map((mark: { requestId: string }) => mark.requestId);
+  return { state: "ready", requests, readIds, userKey };
+}
+
+/** Records an answer. Throws an Error with a sentence for the page when the request is closed or the write loses a race. */
+export async function answerReviewRequest(request: ReviewRequest, input: AnswerInput, by: string, now: Date = new Date()): Promise<ReviewRequest> {
+  const update = answerUpdate(request, input, by, now);
+  const result = await run(
+    `mutation Answer($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+    { input: update, condition: { state: { eq: "open" } } },
+  );
+  if (result.errors?.some((entry) => /conditional/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) {
+    throw new Error("Someone else answered this, or it proceeded at its deadline. Refresh to see the result.");
+  }
+  if (result.errors?.length || !result.data?.updateReviewRequest) throw new Error("Could not save the answer. Nothing was changed.");
+  return normalizeReviewRow(result.data.updateReviewRequest);
+}
+
+/** This user has seen the request. Create the mark; if it exists, refresh it. */
+export async function markReviewRead(userKey: string, requestId: string, now: Date = new Date()): Promise<void> {
+  const input = { id: `${userKey}#${requestId}`, requestId, userKey, readAt: now.toISOString() };
+  const created = await run(
+    `mutation Mark($input: CreateReviewReadMarkInput!) { createReviewReadMark(input: $input) { id } }`, { input });
+  if (created.errors?.length) {
+    await run(`mutation Mark($input: UpdateReviewReadMarkInput!) { updateReviewReadMark(input: $input) { id } }`, { input });
+  }
+}
+
+const MAX_TITLE_LOOKUPS = 40;
+
+/** Titles of the stories that review requests are about, by lineage id, and the ids of stories that no longer exist (no version of the lineage remains). A story that cannot be read simply has no entry (the card falls back to the id). */
+export async function loadStoryTitles(ids: string[]): Promise<{ titles: Record<string, string>; deleted: string[] }> {
+  const titles: Record<string, string> = {};
+  const deleted: string[] = [];
+  await Promise.all([...new Set(ids)].slice(0, MAX_TITLE_LOOKUPS).map(async (id) => {
+    const result = await run(
+      `query StoryTitle($lineageId: ID!) { listItemsByLineageAndVersion(lineageId: $lineageId, limit: 50) { items { versionNumber headline title } } }`,
+      { lineageId: id },
+    );
+    // Only a clean, empty answer means the story is gone; a failed lookup says nothing.
+    if (!result.errors?.length && result.data?.listItemsByLineageAndVersion && !(result.data.listItemsByLineageAndVersion.items ?? []).filter(Boolean).length) deleted.push(id);
+    const items = (result.data?.listItemsByLineageAndVersion?.items ?? []).filter(Boolean) as { versionNumber?: number; headline?: string; title?: string }[];
+    const newest = items.sort((a, b) => (b.versionNumber ?? 0) - (a.versionNumber ?? 0))[0];
+    const title = newest?.headline || newest?.title;
+    if (title) titles[id] = title;
+  }));
+  return { titles, deleted };
+}

package/lib/review-fixture.ts

@@ -0,0 +1,45 @@
+import type { ReviewRequest } from "./review-requests";
+
+/** Demo and test data: one of each mode, a timed-out soft review, and an answered one whose steering was applied. */
+export const FIXTURE_REVIEW_REQUESTS: ReviewRequest[] = [
+  {
+    id: "rr-hard-1", subject: { type: "story", id: "story-ruling-1" }, mode: "hard_gate", reason: "Approve this ruling summary before it is published",
+    ask: "Check the holding and the quoted passages.", raisedBy: "distinctive.ttab.ruling-analysis", raisedAt: "2026-10-23T08:00:00Z", deadline: null,
+    state: "open", answer: null, links: [], history: [{ at: "2026-10-23T08:00:00Z", event: "raised", by: "distinctive.ttab.ruling-analysis", note: "hard_gate" }],
+    appliedIn: null, updatedAt: "2026-10-23T08:00:00Z",
+  },
+  {
+    id: "rr-soft-2", subject: { type: "batch", id: "2026-W43" }, mode: "soft_review", reason: "3 new story ideas to review",
+    ask: "Approve to keep them all, reject to drop the batch, or steer with a note.", raisedBy: "idea-pipeline", raisedAt: "2026-10-23T07:00:00Z",
+    deadline: "2026-10-30T07:00:00Z", state: "open", answer: null,
+    links: [{ type: "proposal", id: "proposal-1", label: "story idea 1" }, { type: "proposal", id: "proposal-2", label: "story idea 2" }, { type: "proposal", id: "proposal-3", label: "story idea 3" }],
+    history: [], appliedIn: null, updatedAt: "2026-10-23T07:00:00Z",
+  },
+  {
+    id: "rr-soft-1", subject: { type: "proposal", id: "proposal-9" }, mode: "soft_review", reason: "A trend story draft is ready",
+    ask: null, raisedBy: "trend-pipeline", raisedAt: "2026-10-22T07:00:00Z", deadline: "2026-10-25T07:00:00Z", state: "open", answer: null,
+    links: [], history: [], appliedIn: null, updatedAt: "2026-10-22T07:00:00Z",
+  },
+  {
+    id: "rr-flag-1", subject: { type: "reference", id: "ref-1" }, mode: "flag", reason: "Two sources disagree about the filing date",
+    ask: null, raisedBy: "reference-intake", raisedAt: "2026-10-22T10:00:00Z", deadline: null, state: "open", answer: null, links: [], history: [],
+    appliedIn: null, updatedAt: "2026-10-22T10:00:00Z",
+  },
+  {
+    id: "rr-late-1", subject: { type: "story", id: "story-old" }, mode: "soft_review", reason: "Check the headline", ask: null, raisedBy: "copy-editor",
+    raisedAt: "2026-10-10T07:00:00Z", deadline: "2026-10-17T07:00:00Z", state: "timed_out", answer: null, links: [],
+    history: [{ at: "2026-10-17T07:00:00Z", event: "timed_out", by: "system", note: "proceeded without review" }], appliedIn: null, updatedAt: "2026-10-17T07:00:00Z",
+  },
+  {
+    id: "rr-done-1", subject: { type: "batch", id: "2026-W42" }, mode: "soft_review", reason: "4 new story ideas to review", ask: null, raisedBy: "idea-pipeline",
+    raisedAt: "2026-10-16T07:00:00Z", deadline: "2026-10-23T07:00:00Z", state: "answered",
+    answer: { decision: "feedback", feedback: "Fewer listicles", steer: "not_this_kind", by: "Ed Itor", at: "2026-10-17T09:00:00Z" },
+    links: [], history: [], appliedIn: { runId: "run-w43", by: "idea-pipeline", at: "2026-10-20T07:00:00Z" }, updatedAt: "2026-10-17T09:00:00Z",
+  },
+  {
+    id: "rr-done-2", subject: { type: "proposal", id: "proposal-4" }, mode: "soft_review", reason: "A concept rename was proposed", ask: null, raisedBy: "concept-bot",
+    raisedAt: "2026-10-18T07:00:00Z", deadline: "2026-10-25T07:00:00Z", state: "answered",
+    answer: { decision: "feedback", feedback: "Keep the old name for sports", steer: "adjust", by: "Ed Itor", at: "2026-10-19T09:00:00Z" },
+    links: [], history: [], appliedIn: null, updatedAt: "2026-10-19T09:00:00Z",
+  },
+];

package/lib/review-requests.ts

@@ -0,0 +1,246 @@
+/**
+ * The Notification Center's model (PPY-1cd261, PPY-ab6a50): review requests, the Cyclotron items that wait for a person,
+ * the auto-decided stream, and the words the page says about each. Pure functions only, so the page and its tests share them.
+ *
+ * Principle (docs/notification-center.md): everything except a hard gate keeps moving if nobody acts. Each entry says in words
+ * what happens next without the reader, and only a hard gate says "Waiting for you".
+ */
+import type { ReferenceRecord } from "./category-repository";
+import { getNewsroomNavHref } from "./newsroom-nav";
+import { referenceDisplayTitle, referenceLineageId } from "./newsroom-references";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+
+export type ReviewMode = "flag" | "soft_review" | "hard_gate";
+export type ReviewState = "open" | "answered" | "timed_out" | "withdrawn";
+export type ReviewDecision = "approve" | "acknowledge" | "reject" | "feedback";
+export type ReviewSteer = "adjust" | "not_this_kind";
+
+export type ReviewAnswer = { decision: ReviewDecision; feedback: string | null; steer: ReviewSteer | null; by: string; at: string };
+export type ReviewHistoryEntry = { at: string; event: string; by?: string; note?: string };
+export type ReviewLink = { label?: string; url?: string; type?: string; id?: string };
+
+export type ReviewRequest = {
+  id: string;
+  subject: { type: string; id: string };
+  mode: ReviewMode;
+  reason: string;
+  ask: string | null;
+  raisedBy: string;
+  raisedAt: string;
+  deadline: string | null;
+  state: ReviewState;
+  answer: ReviewAnswer | null;
+  links: ReviewLink[];
+  history: ReviewHistoryEntry[];
+  appliedIn: { runId: string; by: string; at: string; note?: string | null } | null;
+  updatedAt: string;
+};
+
+export const PROCEEDED_WITHOUT_REVIEW = "proceeded without review";
+const MAX_HISTORY = 50;
+
+function parseJson<T>(value: unknown, fallback: T): T {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return fallback;
+    }
+  }
+  return value === null || value === undefined ? fallback : (value as T);
+}
+
+/** A row from the API (JSON fields arrive as strings) as a request. */
+export function normalizeReviewRow(row: Record<string, unknown>): ReviewRequest {
+  return {
+    id: String(row.id),
+    subject: parseJson(row.subject, { type: "unknown", id: "" }),
+    mode: row.mode as ReviewMode,
+    reason: String(row.reason ?? ""),
+    ask: typeof row.ask === "string" ? row.ask : null,
+    raisedBy: String(row.raisedBy ?? ""),
+    raisedAt: String(row.raisedAt ?? ""),
+    deadline: typeof row.deadline === "string" ? row.deadline : null,
+    state: row.state as ReviewState,
+    answer: parseJson<ReviewAnswer | null>(row.answer, null),
+    links: parseJson<ReviewLink[]>(row.links, []),
+    history: parseJson<ReviewHistoryEntry[]>(row.history, []),
+    appliedIn: parseJson(row.appliedIn, null),
+    updatedAt: String(row.updatedAt ?? row.raisedAt ?? ""),
+  };
+}
+
+// --- the deadline (checked on read) ---------------------------------------------------------------------
+
+export function isDue(request: ReviewRequest, now: Date): boolean {
+  return request.mode === "soft_review" && request.state === "open" && request.deadline !== null && new Date(request.deadline).getTime() <= now.getTime();
+}
+
+/** The update that marks a due soft review as timed out, "proceeded without review". Applied with the condition state = open. */
+export function timeoutUpdate(request: ReviewRequest, now: Date): Record<string, unknown> {
+  const at = now.toISOString();
+  const history = [...request.history, { at, event: "timed_out", by: "system", note: PROCEEDED_WITHOUT_REVIEW }].slice(-MAX_HISTORY);
+  return { id: request.id, state: "timed_out", updatedAt: at, history: JSON.stringify(history) };
+}
+
+export type AnswerInput = { decision: ReviewDecision; feedback?: string | null; steer?: ReviewSteer | null };
+
+/** The update for an answer, or an Error saying why it is refused. Applied with the condition state = open. */
+export function answerUpdate(request: ReviewRequest, input: AnswerInput, by: string, now: Date): Record<string, unknown> {
+  if (request.state !== "open") throw new Error(`This request is ${request.state.replace("_", " ")}${request.state === "timed_out" ? ` (${PROCEEDED_WITHOUT_REVIEW})` : ""} and can no longer be answered.`);
+  if (input.decision === "acknowledge" && request.mode !== "flag") throw new Error("Only a flag is acknowledged; approve or reject this one.");
+  const feedback = input.feedback?.trim() || null;
+  const steer = input.steer ?? null;
+  if (input.decision === "feedback" && !feedback && !steer) throw new Error("Write a note, or choose \"Not this kind of thing\".");
+  const at = now.toISOString();
+  const answer: ReviewAnswer = { decision: input.decision, feedback, steer, by, at };
+  const history = [...request.history, { at, event: "answered", by, note: input.decision }].slice(-MAX_HISTORY);
+  return { id: request.id, state: "answered", answer: JSON.stringify(answer), updatedAt: at, history: JSON.stringify(history) };
+}
+
+// --- words ------------------------------------------------------------------------------------------------
+
+export function formatWhen(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "";
+  return `${date.toISOString().slice(0, 10)} ${date.toISOString().slice(11, 16)} UTC`;
+}
+
+export function modeLabel(mode: ReviewMode): string {
+  return mode === "hard_gate" ? "Hard gate" : mode === "soft_review" ? "Soft review" : "Flag";
+}
+
+/** A mark and the words, never colour alone. */
+export function modeMark(mode: ReviewMode): string {
+  return mode === "hard_gate" ? "■" : mode === "soft_review" ? "◐" : "⚑";
+}
+
+/** What happens next without the reader. Only a hard gate says "Waiting for you". */
+export function nextText(request: ReviewRequest): string {
+  if (request.state === "open") {
+    if (request.mode === "hard_gate") return "Waiting for you. Nothing continues until you approve or reject.";
+    if (request.mode === "soft_review") return `Proceeds automatically on ${formatWhen(request.deadline)} unless you steer it.`;
+    return "Nothing is waiting on this. It stays here until you acknowledge it.";
+  }
+  if (request.state === "timed_out") return `Proceeded without review on ${formatWhen(request.updatedAt)}.`;
+  if (request.state === "withdrawn") return "Withdrawn by the step that raised it.";
+  const answer = request.answer;
+  return answer ? `${answerWords(answer, request)} by ${answer.by} on ${formatWhen(answer.at)}.` : "Answered.";
+}
+
+export function answerWords(answer: ReviewAnswer, request?: Pick<ReviewRequest, "mode">): string {
+  if (answer.steer === "not_this_kind") return "Steered: not this kind of thing";
+  if (answer.decision === "acknowledge") return "Acknowledged";
+  if (answer.decision === "approve") return request?.mode === "flag" ? "Acknowledged" : "Approved";
+  if (answer.decision === "reject") return "Rejected";
+  return "Steered with a note";
+}
+
+/** "You steered X, applied in run Y": what became of a person's input. */
+export function steeringText(request: ReviewRequest): string | null {
+  const answer = request.answer;
+  if (request.state !== "answered" || !answer || !(answer.feedback || answer.steer || answer.decision === "reject")) return null;
+  const said = answer.feedback ? `"${answer.feedback}"` : answerWords(answer).toLowerCase();
+  if (request.appliedIn) return `You steered ${said}. Applied in run ${request.appliedIn.runId} on ${formatWhen(request.appliedIn.at)}.`;
+  return `You steered ${said}. ${request.raisedBy} has not used it yet; it will on its next run.`;
+}
+
+/** What a request is about, in words: a story shows its title (the id when the title is not known), anything else its type and id. */
+export function subjectLabel(subject: { type: string; id: string }, titles: Readonly<Record<string, string>> = {}, deleted: ReadonlySet<string> = new Set()): string {
+  if (subject.type === "story") return deleted.has(subject.id) ? `story ${subject.id} (story deleted)` : titles[subject.id] ?? `story ${subject.id}`;
+  return `${subject.type.replace("_", " ")} ${subject.id}`;
+}
+
+export function subjectHref(subject: { type: string; id: string }, demo = false): string | null {
+  const id = encodeURIComponent(subject.id);
+  if (subject.type === "story") return getNewsroomNavHref(`/newsroom/articles/${id}`, demo);
+  if (subject.type === "reference" || subject.type === "cyclotron_decision") return getNewsroomNavHref(`/newsroom/references/${id}`, demo);
+  if (subject.type === "proposal") return getNewsroomNavHref(`/newsroom/topics?proposal=${id}`, demo);
+  if (subject.type === "automation_run") return getNewsroomNavHref("/newsroom/administration/automations", demo);
+  return null;
+}
+
+// --- Cyclotron items ---------------------------------------------------------------------------------------
+
+export type CyclotronEntry = {
+  lineageId: string;
+  title: string;
+  label: string;
+  confidence: number | null;
+  decidedAt: string | null;
+  reviewDetail: string | null;
+  reviewedByPerson: boolean;
+  href: string;
+};
+
+function cyclotronEntry(reference: ReferenceRecord, decision: RelevanceDecisionView, reviewed: ReadonlySet<string>, demo: boolean): CyclotronEntry {
+  const lineageId = referenceLineageId(reference);
+  return {
+    lineageId, title: referenceDisplayTitle(reference), label: decision.label, confidence: decision.confidence,
+    decidedAt: decision.decidedAt, reviewDetail: decision.reviewDetail, reviewedByPerson: reviewed.has(lineageId),
+    href: getNewsroomNavHref(`/newsroom/references/${encodeURIComponent(lineageId)}`, demo),
+  };
+}
+
+/** Items the Cyclotron routed to a person (the References tab's own rule: review recommended and still pending). Least confident first. */
+export function cyclotronHeldForReview(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView>, demo = false): CyclotronEntry[] {
+  const entries: CyclotronEntry[] = [];
+  for (const reference of references) {
+    const decision = decisions.get(referenceLineageId(reference));
+    if (decision?.reviewRecommended && normalizeReferenceCurationStatus(reference.curationStatus) === "pending") {
+      entries.push(cyclotronEntry(reference, decision, new Set(), demo));
+    }
+  }
+  return entries.sort((a, b) => (a.confidence ?? 1) - (b.confidence ?? 1));
+}
+
+/** Recent classifications the Cyclotron made on its own confidence. Read only here; correcting happens on the reference. Newest first. */
+export function cyclotronAutoDecided(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView>, reviewed: ReadonlySet<string>, demo = false, limit = 20): CyclotronEntry[] {
+  const entries: CyclotronEntry[] = [];
+  for (const reference of references) {
+    const decision = decisions.get(referenceLineageId(reference));
+    if (decision && !decision.reviewRecommended) entries.push(cyclotronEntry(reference, decision, reviewed, demo));
+  }
+  return entries.sort((a, b) => (b.decidedAt ?? "").localeCompare(a.decidedAt ?? "")).slice(0, limit);
+}
+
+// --- the page's shape -------------------------------------------------------------------------------------------
+
+export type NotificationSections = {
+  hardGates: ReviewRequest[];
+  softReviews: ReviewRequest[];
+  flags: ReviewRequest[];
+  /** Answered, timed out or withdrawn, newest first: what people said and what became of it. */
+  decided: ReviewRequest[];
+};
+
+export function sectionReviews(requests: ReviewRequest[]): NotificationSections {
+  const open = requests.filter((request) => request.state === "open");
+  const byRaised = (a: ReviewRequest, b: ReviewRequest) => a.raisedAt.localeCompare(b.raisedAt);
+  return {
+    hardGates: open.filter((request) => request.mode === "hard_gate").sort(byRaised),
+    softReviews: open.filter((request) => request.mode === "soft_review").sort((a, b) => (a.deadline ?? "").localeCompare(b.deadline ?? "")),
+    flags: open.filter((request) => request.mode === "flag").sort((a, b) => b.raisedAt.localeCompare(a.raisedAt)),
+    decided: requests.filter((request) => request.state !== "open").sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)),
+  };
+}
+
+export type NotificationSummary = { waiting: number; proceedingSoon: number; decidedBySystem: number; unread: number };
+
+/**
+ * "N waiting for you · N proceeding soon · N recently decided by the system".
+ * Waiting = hard gates plus Cyclotron items held for review (both stay put until a person acts). Proceeding soon = open soft reviews.
+ */
+export function summarize(sections: NotificationSections, held: CyclotronEntry[], autoDecided: CyclotronEntry[], unread: number): NotificationSummary {
+  return { waiting: sections.hardGates.length + held.length, proceedingSoon: sections.softReviews.length, decidedBySystem: autoDecided.length, unread };
+}
+
+export function summaryText(summary: NotificationSummary): string {
+  return `${summary.waiting} waiting for you · ${summary.proceedingSoon} proceeding soon · ${summary.decidedBySystem} recently decided by the system`;
+}
+
+export function isUnread(request: ReviewRequest, readIds: ReadonlySet<string>): boolean {
+  return !readIds.has(request.id);
+}

package/lib/semantic-graph.ts

@@ -57,6 +57,7 @@ export type SemanticPredicateId =
   | "related_to"
   | "broader_than"
   | "narrower_than"
+  | "member_of"
   | "supports"
   | "contradicts";
 
@@ -96,6 +97,7 @@ export const SEMANTIC_PREDICATES: SemanticPredicateDefinition[] = [
   { id: "related_to", label: "related to", group: "generic", inverseLabel: "related from" },
   { id: "broader_than", label: "broader than", group: "ontology", inverseLabel: "narrower concept" },
   { id: "narrower_than", label: "narrower than", group: "ontology", inverseLabel: "broader concept" },
+  { id: "member_of", label: "member of", group: "ontology", inverseLabel: "members" },
   { id: "supports", label: "supports", group: "evidence", inverseLabel: "supported by" },
   { id: "contradicts", label: "contradicts", group: "evidence", inverseLabel: "contradicted by" },
 ];

package/lib/shared-chat-admission.ts

@@ -0,0 +1,182 @@
+/**
+ * Code-local trust contract for a site-hosted shared chat adapter.
+ *
+ * This module does not verify JWT signatures and is not an HTTP endpoint. The
+ * hosting server must inject a real verifier and authoritative membership
+ * resolver. Never construct VerifiedChatCredential from request JSON.
+ */
+
+export type TokenUse = string;
+
+/** Claims returned only after the injected host verifier has validated the JWT. */
+export interface VerifiedChatCredential {
+  subject: string;
+  issuer: string;
+  audiences: readonly string[];
+  clientId?: string;
+  tokenUse?: TokenUse;
+  expiresAtEpochSeconds: number;
+  notBeforeEpochSeconds?: number;
+  issuedAtEpochSeconds?: number;
+}
+
+export interface AudienceRule {
+  /** Explicitly choose which JWT claim is authoritative for this host. */
+  claim: "aud" | "client_id";
+  expectedValue: string;
+}
+
+export interface ChatHostTrustProfile {
+  issuer: string;
+  audienceRule: AudienceRule;
+  /** Must be configured by the host after verifying its actual token contract. */
+  acceptedTokenUses: readonly TokenUse[];
+  configuredSiteId: string;
+  clockSkewSeconds?: number;
+}
+
+export interface ChatRequest {
+  authorization?: string;
+  channelId: string;
+  idempotencyKey: string;
+  message: { text: string; authorSub?: string; accountId?: string; siteId?: string };
+}
+
+export interface ChatMembership {
+  accountId: string;
+  siteId: string;
+  editorSub: string;
+  active: boolean;
+  /** Host-derived authorization for the editorial chat surface (editor/admin policy). */
+  canUseEditorialChat: boolean;
+}
+
+export interface TranscriptOwner {
+  accountId: string;
+  siteId: string;
+  editorSub: string;
+  channelId: string;
+}
+
+export interface SharedChatAdmissionDependencies {
+  trust: ChatHostTrustProfile;
+  nowEpochSeconds?: () => number;
+  verifyCredential: (rawCredential: string) => Promise<VerifiedChatCredential | null>;
+  resolveMembership: (subject: string, configuredSiteId: string) => Promise<ChatMembership | null>;
+  resolveTranscriptOwner: (channelId: string) => Promise<TranscriptOwner | null>;
+}
+
+export interface AdmittedChatMessage {
+  owner: TranscriptOwner;
+  idempotencyKey: string;
+  /** Stable canonical representation used for payload-reuse detection. */
+  payloadFingerprint: string;
+}
+
+export class ChatAdmissionError extends Error {
+  readonly code: "unauthorized" | "forbidden" | "invalid_request" | "idempotency_conflict";
+
+  constructor(code: ChatAdmissionError["code"]) {
+    super(code);
+    this.name = "ChatAdmissionError";
+    this.code = code;
+  }
+}
+
+const reject = (code: ChatAdmissionError["code"]): never => { throw new ChatAdmissionError(code); };
+
+function bearerToken(value: string | undefined): string {
+  const match = value?.match(/^Bearer ([^\s]+)$/i);
+  if (!match) return reject("unauthorized");
+  return match[1];
+}
+
+function assertCredential(credential: VerifiedChatCredential, trust: ChatHostTrustProfile, now: number): void {
+  const skew = Math.max(0, trust.clockSkewSeconds ?? 0);
+  if (!trust.issuer || credential.issuer !== trust.issuer) reject("unauthorized");
+  if (!trust.acceptedTokenUses.length || !credential.tokenUse || !trust.acceptedTokenUses.includes(credential.tokenUse)) reject("unauthorized");
+  if (!Number.isFinite(credential.expiresAtEpochSeconds) || now - skew >= credential.expiresAtEpochSeconds) reject("unauthorized");
+  if (credential.notBeforeEpochSeconds !== undefined && now + skew < credential.notBeforeEpochSeconds) reject("unauthorized");
+  if (credential.issuedAtEpochSeconds !== undefined && now + skew < credential.issuedAtEpochSeconds) reject("unauthorized");
+
+  const audienceMatches = trust.audienceRule.claim === "aud"
+    ? credential.audiences.includes(trust.audienceRule.expectedValue)
+    : credential.clientId === trust.audienceRule.expectedValue;
+  if (!audienceMatches) reject("unauthorized");
+}
+
+/** Authenticate, derive the current host membership, and enforce private channel ownership. */
+export async function admitSharedChatMessage(
+  request: ChatRequest,
+  dependencies: SharedChatAdmissionDependencies,
+): Promise<AdmittedChatMessage> {
+  if (!request.channelId || !request.message.text.trim() || !/^[A-Za-z0-9._~-]{16,128}$/.test(request.idempotencyKey)) {
+    return reject("invalid_request");
+  }
+
+  const rawCredential = bearerToken(request.authorization);
+  const credential = await dependencies.verifyCredential(rawCredential);
+  if (!credential) return reject("unauthorized");
+  const now = (dependencies.nowEpochSeconds ?? (() => Date.now() / 1000))();
+  assertCredential(credential, dependencies.trust, now);
+
+  const membership = await dependencies.resolveMembership(credential.subject, dependencies.trust.configuredSiteId);
+  if (!membership || !membership.active || !membership.canUseEditorialChat
+    || membership.editorSub !== credential.subject || membership.siteId !== dependencies.trust.configuredSiteId) {
+    return reject("forbidden");
+  }
+  if ((request.message.authorSub && request.message.authorSub !== membership.editorSub)
+    || (request.message.accountId && request.message.accountId !== membership.accountId)
+    || (request.message.siteId && request.message.siteId !== membership.siteId)) {
+    return reject("forbidden");
+  }
+
+  const expectedOwner: TranscriptOwner = {
+    accountId: membership.accountId,
+    siteId: membership.siteId,
+    editorSub: membership.editorSub,
+    channelId: request.channelId,
+  };
+  const actualOwner = await dependencies.resolveTranscriptOwner(request.channelId);
+  if (!actualOwner || actualOwner.accountId !== expectedOwner.accountId || actualOwner.siteId !== expectedOwner.siteId
+    || actualOwner.editorSub !== expectedOwner.editorSub || actualOwner.channelId !== expectedOwner.channelId) {
+    return reject("forbidden");
+  }
+
+  return {
+    owner: expectedOwner,
+    idempotencyKey: request.idempotencyKey,
+    payloadFingerprint: JSON.stringify([request.channelId, request.message.text]),
+  };
+}
+
+export interface IdempotencyRequest<T> {
+  /** Storage must atomically scope key by the derived owner and operation. */
+  scope: string;
+  key: string;
+  payloadFingerprint: string;
+  run: () => Promise<T>;
+}
+
+/**
+ * Store contract for replay-safe writes. Production implementations must be
+ * atomic/durable (for example conditional put + canonical result); this module
+ * deliberately supplies no in-memory production store.
+ */
+export interface ChatIdempotencyStore {
+  executeOnce<T>(request: IdempotencyRequest<T>): Promise<T>;
+}
+
+export function runAdmittedChatMessage<T>(
+  admission: AdmittedChatMessage,
+  store: ChatIdempotencyStore,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const { accountId, siteId, editorSub, channelId } = admission.owner;
+  return store.executeOnce({
+    scope: JSON.stringify(["chat-message", accountId, siteId, editorSub, channelId]),
+    key: admission.idempotencyKey,
+    payloadFingerprint: admission.payloadFingerprint,
+    run: operation,
+  });
+}

package/lib/site-brand-tenant.ts

@@ -9,14 +9,19 @@ export function resolveBrandConfigPath(relativePath: string): string {
   return path.isAbsolute(relativePath) ? relativePath : path.join(process.cwd(), relativePath);
 }
 
-export function getBrandSteeringConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string {
-  return resolveBrandConfigPath(brand.steeringConfigPath);
+/** Optional repo files a brand may still name; undefined means the site keeps that configuration as backend data and nothing is looked up. */
+function optionalBrandConfigPath(relativePath: string | undefined): string | undefined {
+  return relativePath ? resolveBrandConfigPath(relativePath) : undefined;
 }
 
-export function getBrandNewsroomSectionsConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string {
-  return resolveBrandConfigPath(brand.newsroomSectionsConfigPath);
+export function getBrandSteeringConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string | undefined {
+  return optionalBrandConfigPath(brand.steeringConfigPath);
 }
 
-export function getBrandAnalysisProfilesPath(brand: SiteBrand = resolveActiveSiteBrand()): string {
-  return resolveBrandConfigPath(brand.analysisProfilesPath);
+export function getBrandNewsroomSectionsConfigPath(brand: SiteBrand = resolveActiveSiteBrand()): string | undefined {
+  return optionalBrandConfigPath(brand.newsroomSectionsConfigPath);
+}
+
+export function getBrandAnalysisProfilesPath(brand: SiteBrand = resolveActiveSiteBrand()): string | undefined {
+  return optionalBrandConfigPath(brand.analysisProfilesPath);
 }