@camox/api-contract 0.63.0 → 0.65.1

package/dist/threads.d.ts

@@ -35,7 +35,8 @@ export declare const RECONCILE_ENTRY = "camox.reconcile";
 /**
  * The kind of the transcript entry opening a draft's thread a Live thread handed a request off
  * to: the Brief, which the model reads and editors see as from Camox, ahead of the editor's
- * messages.
+ * messages. In a draft Camox opened, such as its Patrol Draft, Camox's own messages are Briefs
+ * too, with their `operationId` as data, and start the agent's run, which acts for Camox.
  */
 export declare const BRIEF_ENTRY = "camox.brief";
 /**
@@ -53,8 +54,8 @@ export declare const PUSH_ENTRY = "camox.push";
 /** How a pushed head's build ended: built, built with type errors, or built but not previewed. */
 export declare const pushOutcomeSchema: z.ZodEnum<{
   built: "built";
-  typeErrors: "typeErrors";
   notPreviewed: "notPreviewed";
+  typeErrors: "typeErrors";
 }>;
 export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
 /**
@@ -64,6 +65,8 @@ export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
 export declare const START_DRAFT_TOOL = "startDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 export declare const BUILD_TOOL = "build";
+/** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
+export declare const LOOK_TOOL = "look";
 /**
  * The tools whose calls change a draft: the content tools that write, and the code tools that
  * write files. The model calls the code tools, and code mode scripts call both. A test in the API
@@ -147,8 +150,8 @@ export declare const pushDataSchema: z.ZodObject<{
   subjects: z.ZodArray<z.ZodString>;
   outcome: z.ZodEnum<{
     built: "built";
-    typeErrors: "typeErrors";
     notPreviewed: "notPreviewed";
+    typeErrors: "typeErrors";
   }>;
 }, z.core.$strip>;
 export type PushData = z.infer<typeof pushDataSchema>;
@@ -176,18 +179,18 @@ export type StartedDraft = z.infer<typeof startedDraftSchema>;
 /** How a write touched what it names. */
 export declare const touchKindSchema: z.ZodEnum<{
   created: "created";
+  deleted: "deleted";
   edited: "edited";
   moved: "moved";
-  deleted: "deleted";
   settings: "settings";
 }>;
 export type TouchKind = z.infer<typeof touchKindSchema>;
 export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   kind: z.ZodEnum<{
     created: "created";
+    deleted: "deleted";
     edited: "edited";
     moved: "moved";
-    deleted: "deleted";
     settings: "settings";
   }>;
   locale: z.ZodOptional<z.ZodString>;
@@ -197,9 +200,9 @@ export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
   kind: z.ZodEnum<{
     created: "created";
+    deleted: "deleted";
     edited: "edited";
     moved: "moved";
-    deleted: "deleted";
     settings: "settings";
   }>;
   locale: z.ZodOptional<z.ZodString>;
@@ -208,9 +211,9 @@ export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
   kind: z.ZodEnum<{
     created: "created";
+    deleted: "deleted";
     edited: "edited";
     moved: "moved";
-    deleted: "deleted";
     settings: "settings";
   }>;
   locale: z.ZodOptional<z.ZodString>;
@@ -228,9 +231,9 @@ export declare const touchedBatchSchema: z.ZodObject<{
   touches: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodEnum<{
       created: "created";
+      deleted: "deleted";
       edited: "edited";
       moved: "moved";
-      deleted: "deleted";
       settings: "settings";
     }>;
     locale: z.ZodOptional<z.ZodString>;
@@ -240,9 +243,9 @@ export declare const touchedBatchSchema: z.ZodObject<{
   }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodEnum<{
       created: "created";
+      deleted: "deleted";
       edited: "edited";
       moved: "moved";
-      deleted: "deleted";
       settings: "settings";
     }>;
     locale: z.ZodOptional<z.ZodString>;
@@ -251,9 +254,9 @@ export declare const touchedBatchSchema: z.ZodObject<{
   }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodEnum<{
       created: "created";
+      deleted: "deleted";
       edited: "edited";
       moved: "moved";
-      deleted: "deleted";
       settings: "settings";
     }>;
     locale: z.ZodOptional<z.ZodString>;
@@ -336,10 +339,12 @@ export type ThreadMessage = {
  * - `changing`: a call of that round changes the draft (`CHANGING_TOOLS`), as soon as it's written
  *   or, in a code mode script, as soon as the script calls one.
  * - `building`: its `build` call runs, or the end of the turn builds its code changes.
+ * - `checking`: it looks at what it designed, from writing a `look` call until the model is
+ *   called again.
  * - `fixing`: the end of the turn's build failed, and the agent fixes it.
  * - `startingDraft`: on Live, its `startDraft` call runs.
  */
-export type AgentActivity = "thinking" | "exploring" | "changing" | "building" | "fixing" | "startingDraft";
+export type AgentActivity = "thinking" | "exploring" | "changing" | "building" | "checking" | "fixing" | "startingDraft";
 /** Everything the studio shows for a thread. */
 export type ThreadView = {
   messages: readonly ThreadMessage[];
@@ -369,6 +374,8 @@ export type ThreadState = {
    * or making it until the model is called again.
    */
   changing?: boolean;
+  /** Whether the model's latest round calls `look`: from writing the call until it's called again. */
+  checking?: boolean;
   /** The drafts the thread's cards name, as the thread last looked them up. */
   drafts?: DraftCardStates;
 };
@@ -559,7 +566,7 @@ export declare const editorTextOf: (content: Message["content"]) => string;
  * run is over, or a later message started another run after its last model call came back
  * unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
  */
-export declare function threadViewOf({ steps, running, toolCalls, callingTools, changing, drafts }: ThreadState): ThreadView;
+export declare function threadViewOf({ steps, running, toolCalls, callingTools, changing, checking, drafts }: ThreadState): ThreadView;
 /** Folds one of Pi's agent events into the thread's state. */
 export declare function reduceThreadState(state: ThreadState, event: AgentEvent): ThreadState;
 /** Folds a batch of Pi's agent events into the thread's state. */

package/dist/threads.js

@@ -33,7 +33,8 @@ const RECONCILE_ENTRY = "camox.reconcile";
 /**
 * The kind of the transcript entry opening a draft's thread a Live thread handed a request off
 * to: the Brief, which the model reads and editors see as from Camox, ahead of the editor's
-* messages.
+* messages. In a draft Camox opened, such as its Patrol Draft, Camox's own messages are Briefs
+* too, with their `operationId` as data, and start the agent's run, which acts for Camox.
 */
 const BRIEF_ENTRY = "camox.brief";
 /**
@@ -61,6 +62,8 @@ const pushOutcomeSchema = z.enum([
 const START_DRAFT_TOOL = "startDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 const BUILD_TOOL = "build";
+/** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
+const LOOK_TOOL = "look";
 /**
 * The tools whose calls change a draft: the content tools that write, and the code tools that
 * write files. The model calls the code tools, and code mode scripts call both. A test in the API
@@ -69,6 +72,7 @@ const BUILD_TOOL = "build";
 const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"addBackToLocale",
 	"addLocale",
+	"applyFindingFix",
 	"createBlock",
 	"createCollectionRecord",
 	"createPage",
@@ -369,7 +373,7 @@ function threadStepOf(entry) {
 * run is over, or a later message started another run after its last model call came back
 * unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
 */
-function threadViewOf({ steps, running, toolCalls = [], callingTools = false, changing = false, drafts = {} }) {
+function threadViewOf({ steps, running, toolCalls = [], callingTools = false, changing = false, checking = false, drafts = {} }) {
 	const messages = [];
 	let waiting;
 	let unfinished = false;
@@ -507,14 +511,16 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ch
 			status,
 			toolCalls,
 			callingTools,
-			changing
+			changing,
+			checking
 		})
 	};
 }
 /** What the agent is doing during a run, from where the turn's build stands and its tool calls. */
-function activityOf({ status, toolCalls, callingTools, changing }) {
+function activityOf({ status, toolCalls, callingTools, changing, checking }) {
 	const calling = (name) => toolCalls.some((call) => call.name === name);
 	if (status === "building" || calling("build")) return "building";
+	if (checking) return "checking";
 	if (status === "fixing") return "fixing";
 	if (calling("startDraft")) return "startingDraft";
 	if (changing) return "changing";
@@ -525,6 +531,8 @@ function activityOf({ status, toolCalls, callingTools, changing }) {
 const changes = (name) => CHANGING_TOOLS.has(name);
 /** Whether a block of the model's message is a call of a tool that changes the draft. */
 const callsChangingTool = (block) => block.type === "toolCall" && changes(block.name);
+/** Whether a block of the model's message is a call of `look`. */
+const callsLook = (block) => block.type === "toolCall" && block.name === "look";
 const append = (state, entry) => {
 	const step = entry && threadStepOf(entry);
 	if (!step || state.steps.some((known) => known.id === step.id)) return state;
@@ -548,6 +556,7 @@ function reduceThreadState(state, event) {
 				running: event.run !== void 0,
 				toolCalls,
 				callingTools: generated.some((part) => part.type === "toolCall"),
+				checking: generated.some(callsLook) || toolCalls.some((call) => call.name === "look"),
 				changing: generated.some(callsChangingTool) || toolCalls.some((call) => changes(call.name)) || event.nestedTools.some((nested) => changes(nested.name) && toolCalls.some((call) => nested.parentCallId === call.callId || nested.parentCallId.startsWith(`${call.callId}/`)))
 			};
 		}
@@ -560,12 +569,14 @@ function reduceThreadState(state, event) {
 			running: false,
 			toolCalls: [],
 			callingTools: false,
-			changing: false
+			changing: false,
+			checking: false
 		};
 		case "message_start": return event.message.role === "assistant" ? {
 			...state,
 			callingTools: false,
-			changing: false
+			changing: false,
+			checking: false
 		} : state;
 		case "message_update": {
 			const calls = event.changes.flatMap((change) => change.type === "toolcall_start" || change.type === "block" ? [change.block] : change.type === "message" ? change.message.content : []);
@@ -573,7 +584,8 @@ function reduceThreadState(state, event) {
 			return {
 				...state,
 				callingTools: state.callingTools || calls.some((block) => block.type === "toolCall"),
-				changing: state.changing || calls.some(callsChangingTool)
+				changing: state.changing || calls.some(callsChangingTool),
+				checking: state.checking || calls.some(callsLook)
 			};
 		}
 		case "tool_execution_start": {
@@ -585,6 +597,7 @@ function reduceThreadState(state, event) {
 			return {
 				...state,
 				changing,
+				checking: state.checking || event.toolName === "look",
 				toolCalls: [...state.toolCalls ?? [], {
 					callId: event.toolCallId,
 					name: event.toolName
@@ -615,4 +628,4 @@ function reduceThreadFrame(state, frame) {
 }
 
 //#endregion
-export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, CONNECTED_AGENT_MESSAGE_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, PUSH_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, connectedAgentClientSchema, connectedAgentMessageDataSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, isSender, pushDataSchema, pushOutcomeSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };
+export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, CONNECTED_AGENT_MESSAGE_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, LOOK_TOOL, PUSH_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, connectedAgentClientSchema, connectedAgentMessageDataSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, isSender, pushDataSchema, pushOutcomeSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.63.0",
+  "version": "0.65.1",
   "license": "MIT",
   "files": [
     "src",
@@ -51,6 +51,10 @@
     "./router": {
       "types": "./dist/router.d.ts",
       "default": "./dist/router.js"
+    },
+    "./layout-routes": {
+      "types": "./dist/layout-routes.d.ts",
+      "default": "./dist/layout-routes.js"
     }
   },
   "dependencies": {
@@ -60,7 +64,8 @@
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
-    "@earendil-works/pi-durable": "1.3.0"
+    "@earendil-works/pi-durable": "1.3.0",
+    "tsrs": "0.20.1-ts7.1.0-beta"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
@@ -85,6 +90,7 @@
           "^production",
           "{workspaceRoot}/apps/api/src/**/*",
           "{workspaceRoot}/packages/ai-tools/src/**/*",
+          "{workspaceRoot}/tsconfig.dts.api-contract.json",
           "!{workspaceRoot}/**/*.test.ts"
         ]
       }

package/src/drafts.ts

@@ -25,6 +25,46 @@ export const PUBLISHING_DRAFT_HEADER = "x-camox-publishing-draft";
  */
 export const PUBLISHING_DRAFT_VAR = "CAMOX_PUBLISHING_DRAFT";
 
+/**
+ * Request header carrying a look token (ADR 0032): a short-lived, read-only credential the API
+ * signs for the agent's `look` tool, naming one project and one draft. A request carrying a valid
+ * one reads that draft's content, named with `DRAFT_HEADER`, as a member would, without a session.
+ * It writes nothing, reads no other draft, and reads none of Live's private data.
+ */
+export const LOOK_TOKEN_HEADER = "x-camox-look-token";
+
+/**
+ * The cookie the browser `look` drives carries the look token in, set for the website's host
+ * only, so third-party requests never see it. The website forwards it as `LOOK_TOKEN_HEADER`.
+ */
+export const LOOK_TOKEN_COOKIE = "camox_look";
+
+/**
+ * The website's lightweight document the browser `look` drives loads (the SDK runtime's
+ * `RUNTIME_ROUTE_PATHS.look`): one page of the draft `DRAFT_SEARCH_PARAM` names, at the path
+ * `LOOK_PATH_PARAM` gives in the locale `LOOK_LOCALE_PARAM` names, its Default Locale without.
+ */
+export const LOOK_DOCUMENT_PATH = "/_camox/look";
+export const LOOK_PATH_PARAM = "path";
+export const LOOK_LOCALE_PARAM = "locale";
+
+/**
+ * The look document's Block Definition mode: instead of a page, the block of the Block Definition
+ * `LOOK_BLOCK_DEFINITION_PARAM` names, alone in the site's shell, with its default content and
+ * Block Settings and the overrides `LOOK_CONTENT_PARAM` and `LOOK_SETTINGS_PARAM` give as JSON, in
+ * the shape the content tools take.
+ */
+export const LOOK_BLOCK_DEFINITION_PARAM = "blockDefinition";
+export const LOOK_CONTENT_PARAM = "content";
+export const LOOK_SETTINGS_PARAM = "settings";
+
+/**
+ * The id of a block shown without being placed, as the look document's Block Definition mode
+ * shows it: never a stored block's, which are UUIDs. Its element is
+ * `[data-camox-viewport-block="unplaced"]`.
+ */
+export const UNPLACED_BLOCK_ID = "unplaced";
+
 /**
  * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
  * exist yet. Its value is `"1"`.
@@ -87,19 +127,34 @@ export const PUBLISH_BLOCKED_ERROR = "PUBLISH_BLOCKED";
 
 /**
  * oRPC error code for a publish refused because the draft still has pending translations: every
- * locale goes live together, unless the caller publishes anyway (ADR 0017).
+ * locale goes live together, and there is no publishing anyway (ADR 0033).
  */
 export const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
 
+/**
+ * oRPC error code for a publish refused because the draft has open findings, each to fix or for a
+ * member to dismiss: there is no publishing past them (ADR 0033).
+ */
+export const FINDINGS_OPEN_ERROR = "FINDINGS_OPEN";
+
+/**
+ * oRPC error code for a publish refused because a patroller's check at publish hasn't read the
+ * draft's latest changes yet: publishing waits for it (ADR 0033).
+ */
+export const CHECKS_RUNNING_ERROR = "CHECKS_RUNNING";
+
 /**
  * Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
  * review again, by the error code of each: Live changed since the preview, the draft has blockers,
- * translations are still running, or the draft's code changed since the preview.
+ * translations are still running, the draft has open findings, a check at publish is still
+ * running, or the draft's code changed since the preview.
  */
 export const NOT_PUBLISHED_CODES = {
   conflictsChanged: CONFLICTS_CHANGED_ERROR,
   blocked: PUBLISH_BLOCKED_ERROR,
   translating: TRANSLATIONS_PENDING_ERROR,
+  findings: FINDINGS_OPEN_ERROR,
+  checking: CHECKS_RUNNING_ERROR,
   revisionChanged: REVISION_CHANGED_ERROR,
 } as const;
 
@@ -133,6 +188,7 @@ const BLOCK_WRITES: Record<keyof Router["blocks"], boolean> = {
   getUsageCounts: false,
   getPagesUsing: false,
   getSyncedContent: false,
+  getUnplaced: false,
   create: true,
   updateContent: true,
   updateSettings: true,
@@ -208,6 +264,14 @@ const LOCALE_WRITES: Record<keyof Router["locales"], boolean> = {
   addBack: true,
 };
 
+// Applying a finding's fix edits content as the member would; dismissing one is the project's,
+// never content (ADR 0034).
+const PATROL_WRITES: Record<keyof Router["patrol"], boolean> = {
+  get: false,
+  applyFix: true,
+  dismissFinding: false,
+};
+
 // `definitions` is absent: its sync is a release, never a studio content write.
 const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   blocks: BLOCK_WRITES,
@@ -215,6 +279,7 @@ const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   collectionDefinitions: COLLECTION_WRITES,
   files: FILE_WRITES,
   pages: PAGE_WRITES,
+  patrol: PATROL_WRITES,
   repeatableItems: ITEM_WRITES,
 };
 

package/src/layout-routes.ts

@@ -0,0 +1,51 @@
+/** How a layout's pages come about: authored by editors, derived from data, or one fixed page. */
+export type LayoutKind = "curated" | "derived" | "singleton";
+
+/** A layout as route matching reads it: its id, which is its file route, and its kind. */
+export type LayoutRoute = { id: string; kind: LayoutKind };
+
+/** The segments of a layout's file route, such as `blog.$slug`: `$` segments are params. */
+export function routeSegments(id: string) {
+  return id.split(".");
+}
+
+/**
+ * The singleton or derived layout whose route matches `pathname`, a path in its Locale, with its
+ * params, or null. The route with the fewest params wins, so a singleton's fixed route wins over
+ * a derived route that would match it too. The SDK renders pages and the API checks them with it.
+ */
+export function matchLayoutRoute<L>(
+  layouts: readonly L[],
+  pathname: string,
+  routeOf: (layout: L) => LayoutRoute,
+): { layout: L; params: Record<string, string> } | null {
+  const path = pathname.replace(/^\/|\/$/g, "").split("/");
+  const paramCount = (layout: L) =>
+    routeSegments(routeOf(layout).id).filter((s) => s.startsWith("$")).length;
+  const candidates = layouts
+    .filter((layout) => routeOf(layout).kind !== "curated")
+    .sort((a, b) => paramCount(a) - paramCount(b));
+  for (const layout of candidates) {
+    const segments = routeSegments(routeOf(layout).id);
+    if (segments.length !== path.length) continue;
+    const params: Record<string, string> = {};
+    let matches = true;
+    for (const [index, segment] of segments.entries()) {
+      let value: string;
+      try {
+        value = decodeURIComponent(path[index]!);
+      } catch {
+        matches = false;
+        break;
+      }
+      if (segment.startsWith("$") && value && !value.includes("/"))
+        params[segment.slice(1)] = value;
+      else if (segment !== value) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) return { layout, params };
+  }
+  return null;
+}

package/src/patrol.ts

@@ -4,8 +4,11 @@
  * Live, and names each report's subject, so the studio needs no entity loaded to show it.
  */
 
-/** A patroller's stable id. The registry in the API lists them all. */
-export type PatrollerId = "translator" | "seoManager";
+/** Every patroller's stable id. The registry in the API lists them all. */
+export const PATROLLER_IDS = ["translator", "seoManager", "linkChecker", "proofreader"] as const;
+
+/** A patroller's stable id. */
+export type PatrollerId = (typeof PATROLLER_IDS)[number];
 
 /**
  * What a structured report says was done. Each has a failed form, by the report's outcome. A
@@ -16,7 +19,10 @@ export type ReportVerb =
   | "mergedWithLive"
   | "wroteSeo"
   | "describedFile"
-  | "publishedCatchUp";
+  | "publishedCatchUp"
+  | "removedLink"
+  | "fixedLink"
+  | "fixedMistake";
 
 /** What a report can be about. */
 export type ReportEntity =
@@ -51,8 +57,11 @@ export const reportLocale = (
 /** Whether the work was done, or failed. A failure shows in its report only. */
 export type ReportOutcome = "done" | "failed";
 
-/** Whether a report needs a human. Nothing raises one yet. */
-export type AttentionLevel = "none" | "needed";
+/**
+ * Where a patroller is on duty, in drafts or on Live: it works as you go, checks when you
+ * publish, or is off there (ADR 0034).
+ */
+export type PatrollerDuty = "asYouGo" | "atPublish" | "off";
 
 /**
  * Where the studio shows a report's subject: a page on the Canvas, with the block and repeatable
@@ -68,7 +77,6 @@ export type ReportView = {
   id: string;
   summary: ReportSummary;
   outcome: ReportOutcome;
-  attention: AttentionLevel;
   /** When the work last settled, in milliseconds since the epoch. */
   at: number;
   /** Whether the report is Live's, seen from a draft or from Live. */
@@ -80,6 +88,98 @@ export type ReportView = {
   place: ReportPlace | null;
 };
 
+/**
+ * What a finding is about (ADR 0034), by its kind:
+ * - `missingPage`: a link to a page that doesn't exist, the page's name as it was last known.
+ * - `brokenLink`: an external link that failed, and how.
+ * - `misspelling`, `grammar`: the flagged text, in the sentence it's in.
+ * A link's `url` is as content stores it: a page link's is `camox:page:<id>`, and `text` is what
+ * the link reads.
+ */
+export type FindingAbout =
+  | { kind: "missingPage"; url: string; text: string; page: string | null }
+  | { kind: "brokenLink"; url: string; text: string; failure: LinkFailure }
+  | { kind: "misspelling" | "grammar"; text: string; sentence: string };
+
+/** How a link failed: an HTTP error status, no connection (DNS included), or no answer in time. */
+export type LinkFailure =
+  | { kind: "status"; status: number }
+  | { kind: "unreachable" }
+  | { kind: "timeout" };
+
+export type FindingKind = FindingAbout["kind"];
+
+/**
+ * The fix a finding suggests, which applying makes: removing the link, keeping its text, or
+ * replacing the flagged text with `replacement` in its sentence, keeping its formatting.
+ */
+export type FindingFix = { kind: "removeLink" } | { kind: "replaceText"; replacement: string };
+
+/** A finding, open, in the scope viewed. */
+export type FindingView = {
+  /** What applying or dismissing it names. */
+  id: number;
+  about: FindingAbout;
+  /** The fix it suggests, if any. */
+  fix: FindingFix | null;
+  /** The content it's in, named in its locale. */
+  subject: ReportSubject;
+  /** The locale of the content it's in, by its tag. */
+  locale: string;
+  /** The content field it's in, by name. */
+  field: string;
+  /** When it was first raised, in milliseconds since the epoch. */
+  raisedAt: number;
+  /** Whether it's Live's. Live's are fixed in the Patrol Draft. */
+  live: boolean;
+  /** Where its content shows, as for reports. */
+  place: ReportPlace | null;
+};
+
+/** What a finding is about, after where it is: "links to About, a page that no longer exists". */
+function aboutSentence(about: FindingAbout): string {
+  switch (about.kind) {
+    case "missingPage":
+      return about.page === null
+        ? "links to a page that no longer exists"
+        : `links to ${about.page}, a page that no longer exists`;
+    case "brokenLink": {
+      const { failure } = about;
+      const how =
+        failure.kind === "status"
+          ? `answers with an error (${failure.status})`
+          : failure.kind === "timeout"
+            ? "doesn't answer in time"
+            : "can't be reached";
+      return `links to ${about.url}, which ${how}`;
+    }
+    case "misspelling":
+      return "may be misspelled";
+    case "grammar":
+      return "may be a grammar mistake";
+  }
+}
+
+/**
+ * A finding as one sentence, as the studio, emails, Briefs and refusals word it: "“About us” in
+ * Footer links to About, a page that no longer exists".
+ */
+export function findingSentence(finding: Pick<FindingView, "about" | "subject">): string {
+  return `“${finding.about.text}” in ${finding.subject.name} ${aboutSentence(finding.about)}`;
+}
+
+/** A member's dismissal of what a finding was about: no finding like it is raised again. */
+export type DismissalView = {
+  id: number;
+  about: FindingAbout;
+  by: { id: string; name: string };
+  /** When it was dismissed, in milliseconds since the epoch. */
+  at: number;
+};
+
+/** What applying a finding's fix did: applied it, or found its content changed and rechecked. */
+export type ApplyResult = { applied: boolean };
+
 /** How many subjects a patroller is on in one locale, a locale's tag. */
 export type LocaleCount = { locale: string; count: number };
 
@@ -96,18 +196,38 @@ export type PatrollerView = {
   id: PatrollerId;
   /** Its role, as editors know it: "Translator", "SEO manager". */
   role: string;
+  /** Its duty in the scope viewed. Off there, it still has its reports. */
+  duty: PatrollerDuty;
   /** Null when it isn't working in the scope. */
   working: PatrollerWorking | null;
-  /** Its latest activity in the scope, or null when it never worked there. */
+  /**
+   * When it last finished a check in the scope, whether it found anything or not, or null when it
+   * never checked there.
+   */
+  lastCheckedAt: number | null;
+  /**
+   * Its latest activity in the scope: its last check, its newest report or when its pending work
+   * started, whichever is later. Null when it never worked there.
+   */
   lastActivityAt: number | null;
   /** Its newest reports, newest first. */
   reports: ReportView[];
   /** How many more reports it has than `reports` shows, per locale, the most first. */
   more: { locale: string | null; count: number }[];
+  /** Its open findings in the scope viewed, the oldest first. Their count is the row's badge. */
+  findings: FindingView[];
+  /** The project's dismissals of its findings, the newest first. */
+  dismissals: DismissalView[];
 };
 
-/** Every patroller of the registry, the latest activity first; never-worked ones last. */
-export type PatrolView = { patrollers: PatrollerView[] };
+/**
+ * Every patroller of the registry, the latest activity first; never-worked ones last. With the
+ * project's open Patrol Draft, where Live's findings are fixed, if any.
+ */
+export type PatrolView = {
+  patrollers: PatrollerView[];
+  patrolDraft: { id: string; name: string | null } | null;
+};
 
 /** How many reports the Patrol shows of each patroller; the rest are counted. */
 export const REPORTS_SHOWN = 5;