@shivaedev/work-board 0.10.0 → 0.12.0

package/src/rpc/rejections.ts

@@ -0,0 +1,30 @@
+import { Schema } from "effect";
+import {
+	BadRequest,
+	Conflict,
+	Forbidden,
+	InternalServerError,
+	NotFound,
+	PreconditionFailed,
+	ServiceUnavailable,
+} from "@shivaedev/platform/errors/taxonomy.ts";
+
+export class PublicationUncertain extends Schema.TaggedError<PublicationUncertain>()("PublicationUncertain", { message: Schema.String }) {}
+export class Unanswered extends Schema.TaggedError<Unanswered>()("Unanswered", { message: Schema.String }) {}
+
+export const responseRejections = {
+	BadRequest,
+	Conflict,
+	Forbidden,
+	InternalServerError,
+	NotFound,
+	PreconditionFailed,
+	PublicationUncertain,
+	ServiceUnavailable,
+	Unanswered,
+};
+export const ResponseRejection = Schema.Union(Object.values(responseRejections));
+export type ResponseRejection = typeof ResponseRejection.Type;
+
+export const documentRejections = { Conflict, InternalServerError, NotFound, ServiceUnavailable };
+export const DocumentRejection = Schema.Union(Object.values(documentRejections));

package/src/rpc/responseContract.ts

@@ -1,46 +1,41 @@
 import { Schema } from "effect";
 import { contract } from "@shivaedev/effect-contract/contract.ts";
 import { command, query } from "@shivaedev/effect-contract/operation.ts";
-import {
-	DraftInput,
-	Question,
-	QuestionPreview,
-	Reading,
-	RecordedResponse,
-	ResponseFailed,
-	Revision,
-	WaitReading,
-} from "#browser/responses/schema.ts";
+import { RequestTracing } from "@shivaedev/platform/rpc/middleware.ts";
+import { DraftInput, Question, QuestionPreview, Reading, RecordedResponse, Revision, WaitReading } from "#browser/responses/schema.ts";
 import { index, workspace } from "#rpc/keys.ts";
+import { responseRejections } from "#rpc/rejections.ts";
 
 const locate = query("question", {
 	payload: { item: Schema.String, request: Schema.String },
 	reads: () => [workspace.list, index.list],
-	rejections: { ResponseFailed },
+	rejections: responseRejections,
 	success: QuestionPreview,
 });
 const awaitResponse = query("awaitResponse", {
 	payload: { after: Schema.optional(Schema.String), question: Schema.String },
 	reads: () => [workspace.list, index.list],
-	rejections: { ResponseFailed },
+	rejections: responseRejections,
 	success: WaitReading,
 });
 const read = query("responses", {
 	payload: { question: Schema.String },
 	reads: () => [workspace.list, index.list],
-	rejections: { ResponseFailed },
+	rejections: responseRejections,
 	success: Reading,
 });
 const register = command("registerQuestion", {
 	invalidates: () => [workspace.list, index.list],
 	payload: { item: Schema.String, request: Schema.String, revision: Revision },
-	rejections: { ResponseFailed },
+	rejections: responseRejections,
 	success: Question,
 });
 const respond = command("recordResponse", {
 	invalidates: () => [workspace.list, index.list],
 	payload: DraftInput,
-	rejections: { ResponseFailed },
+	rejections: responseRejections,
 	success: RecordedResponse,
 });
-export const responseContract = contract("work-board", { commands: [register, respond], queries: [locate, read, awaitResponse] });
+export const responseContract = contract("work-board", { commands: [register, respond], queries: [locate, read, awaitResponse] }).middleware(
+	RequestTracing,
+);

package/src/server/attention/inbox.ts

@@ -0,0 +1,124 @@
+import { fileUrl } from "#files/url.ts";
+import { responseUrl } from "#responses/url.ts";
+import { identityUrl } from "#server/metadata/links.ts";
+import type { MetadataDocument, MetadataModel } from "#server/metadata/model.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { answeredQuestion, pendingQuestions } from "./questionState.ts";
+import { attentionRequests, isMaintainerRequest } from "./requests.ts";
+
+const closed = new Set(["closed", "done", "completed", "cancelled", "canceled", "resolved", "released"]);
+const automation = /^(?:codex|claude|fleet|agent|automation|bot|copilot)(?:$|[-_. /])/iu;
+
+export function openItem(document: MetadataDocument): boolean {
+	return !closed.has(document.parsed.fields.status?.trim().toLowerCase() ?? "");
+}
+
+export function authoredQuestion(document: MetadataDocument): boolean {
+	return document.parsed.fields.kind === "question" && document.parsed.fields.question === undefined;
+}
+
+function addressedElsewhere(document: MetadataDocument, maintainer: string): boolean {
+	const open = document.parsed.fields.attention?.filter((request) => request.state === "open") ?? [];
+	return open.length > 0 && !open.some((request) => isMaintainerRequest(request, maintainer));
+}
+
+export function waitingReason(document: MetadataDocument, model: MetadataModel, maintainer = "maintainer"): string | undefined {
+	const fields = document.parsed.fields;
+	if (!openItem(document) || fields.kind === "response" || fields.kind === "handoff" || fields.question) {
+		return undefined;
+	}
+	if (addressedElsewhere(document, maintainer)) {
+		return undefined;
+	}
+	if (authoredQuestion(document) && answeredQuestion(document, model)) {
+		return undefined;
+	}
+	if (fields.status?.toLowerCase() === "needs-human") {
+		const source = /^fleet(?:$|[-_. /])/iu.test(fields.owner?.trim() ?? "") ? "Fleet needs a person" : "Needs a person";
+		return `${source}: ${fields.nextAction ?? "Review the blocked work"}`;
+	}
+	if (authoredQuestion(document)) {
+		return fields.nextAction ?? "A question needs your answer";
+	}
+	if (fields.owner && fields.nextAction && !automation.test(fields.owner.trim())) {
+		return `${fields.owner}: ${fields.nextAction}`;
+	}
+	return undefined;
+}
+
+function identityProblem(document: MetadataDocument, model: MetadataModel): string | undefined {
+	const id = document.parsed.fields.id;
+	if (!id) {
+		return "Missing or invalid item ID";
+	}
+	return model.ids.get(id)?.length === 1 ? undefined : `Duplicate item ID: ${id}`;
+}
+
+function unresolvedReason(document: MetadataDocument, problem: string | undefined, maintainer: string | undefined): string | undefined {
+	if (!problem) {
+		return undefined;
+	}
+	const requests =
+		document.parsed.fields.attention?.filter((request) => request.managed && request.state === "open" && isMaintainerRequest(request, maintainer))
+		?? [];
+	return requests.length > 0 ? `Managed decision: ${requests.map((request) => request.reason).join("; ")}` : undefined;
+}
+
+function inboxTarget(document: MetadataDocument, problem: string | undefined, request: string | undefined): string {
+	if (problem) {
+		return fileUrl(document.file);
+	}
+	const item = document.parsed.fields.id ?? "";
+	const answer = request ?? (authoredQuestion(document) ? "answer" : undefined);
+	return answer ? responseUrl(item, answer) : identityUrl(item);
+}
+
+export function inboxItems(snapshot: Snapshot) {
+	if (snapshot.unavailable.length > 0) {
+		return [];
+	}
+	const titles = new Map(snapshot.entries.filter((entry) => entry.kind === "document").map((entry) => [entry.file, entry.title]));
+	const managed = attentionRequests(snapshot).entries.filter(
+		(entry) => entry.request.managed && isMaintainerRequest(entry.request, snapshot.maintainer),
+	);
+	const pending = pendingQuestions(snapshot);
+	const pendingLinks = new Map(pending.map((item) => [item.document.file, item.href]));
+	const direct = snapshot.documents.flatMap((document) => {
+		const id = document.parsed.fields.id;
+		const problem = identityProblem(document, snapshot.model);
+		const requests = managed.filter((entry) => entry.document.file === document.file);
+		const reason =
+			waitingReason(document, snapshot.model, snapshot.maintainer)
+			?? (requests.length > 0 ? `Managed decision: ${requests.map((entry) => entry.request.reason).join("; ")}` : undefined)
+			?? unresolvedReason(document, problem, snapshot.maintainer);
+		return reason
+			? [
+					{
+						document,
+						href: pendingLinks.get(document.file) ?? inboxTarget(document, problem, requests[0]?.request.id),
+						id: id ?? document.file,
+						problem,
+						reason,
+						title: titles.get(document.file) ?? document.file,
+					},
+				]
+			: [];
+	});
+	return [...new Map([...pending.map((item) => ({ ...item, problem: undefined })), ...direct].map((item) => [item.document.file, item])).values()]
+		.map((item) => ({ ...item, modified: snapshot.modified.get(item.document.file) }))
+		.sort((left, right) => (left.modified ?? 0) - (right.modified ?? 0) || left.id.localeCompare(right.id));
+}
+
+export function fleetRecords(model: MetadataModel): ReadonlySet<string> {
+	const decisions = model.documents.filter((document) => document.parsed.fields.attention?.some((request) => request.managed));
+	const ids = new Set(decisions.map((document) => document.parsed.fields.id));
+	const questions = model.documents.filter((document) => document.parsed.fields.question && ids.has(document.parsed.fields.question.item));
+	const questionIds = new Set(questions.map((document) => document.parsed.fields.id));
+	return new Set(
+		[
+			...decisions,
+			...questions,
+			...model.documents.filter((document) => document.parsed.fields.response && questionIds.has(document.parsed.fields.response.question)),
+		].map((document) => document.file),
+	);
+}

package/src/server/attention/inboxHtml.ts

@@ -0,0 +1,56 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { inboxItems } from "./inbox.ts";
+
+export function inboxHtml(snapshot: Snapshot, compact = false, now?: number): string {
+	const items = inboxItems(snapshot);
+	const total = snapshot.unavailable.length > 0 ? "Count unavailable" : `${items.length} waiting`;
+	const rows = items
+		.map(
+			(item) =>
+				`<article class="inbox-row" data-key="inbox:${escapeHtml(item.document.file)}"><div><h3><a href="${escapeHtml(item.href)}">${escapeHtml(item.title)}</a></h3><p>${escapeHtml(item.reason)}</p>${item.problem ? `<p class="inbox-problem" role="status">${escapeHtml(item.problem)} — open the source to resolve it.</p>` : ""}</div><p class="inbox-age">${item.modified === undefined ? "Age unavailable" : sourceAge(item.modified, now)}</p></article>`,
+		)
+		.join("");
+	const content =
+		snapshot.unavailable.length > 0
+			? '<p role="status">Workspace incomplete. Inbox membership and count are unavailable.</p>'
+			: rows
+				|| (snapshot.model.documents.some((document) => (snapshot.model.diagnostics.get(document.file)?.length ?? 0) > 0)
+					? '<p class="empty">No classified waiting items. Check source issues in Overview.</p>'
+					: '<p class="empty">All quiet — nothing is waiting on a person.</p>');
+	return compact
+		? `<section aria-label="Inbox summary"><h2>Inbox</h2><p>${total} · <a href="/_board/inbox">Open Inbox</a></p></section>`
+		: `<header class="work-head"><p class="work-eyebrow">WORKSPACE · INBOX</p><h1>Inbox</h1><p>Questions and work waiting on a person. Oldest changed source first.</p></header><p class="work-total" role="status">${total}</p><section class="inbox-list" aria-label="Waiting on you"><h2>Waiting on you</h2>${content}</section>`;
+}
+
+export const inboxStyle = `
+.inbox-row{display:flex;justify-content:space-between;gap:1rem;padding:1.2rem;margin:.75rem 0;border:1px solid var(--border);border-radius:10px;background:var(--card);overflow-wrap:anywhere}
+.inbox-row h3{margin:0 0 .5rem}.inbox-row p{margin:.4rem 0}.inbox-row>div{min-width:0}.inbox-age{flex-shrink:0}.waiting-badge{display:inline-block;font-size:.75rem;font-weight:600;border:1px solid var(--border);border-radius:1rem;padding:.1rem .5rem;color:var(--muted);background:var(--surface)}
+.inbox-link{display:flex;justify-content:space-between;gap:1rem;padding:12px;color:var(--sidebar-text);text-decoration:none}.inbox-count{border-radius:1rem;padding:0 .6rem;background:#385242}
+.question-choice{display:grid;grid-template-rows:subgrid;grid-row:span 2;align-content:start;align-items:start;gap:.4rem;text-align:left;padding:1rem;border:1px solid var(--border);border-radius:8px;color:var(--text);background:var(--card);font:inherit}.question-choice[aria-pressed=true]{border-color:var(--link);background:var(--surface)}.question-choice small{font:inherit;color:var(--muted)}
+.response-panel [data-clear-choices]{margin-bottom:1rem}
+.question-choices{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:.75rem;margin:1rem 0}.question-choice{width:100%;overflow-wrap:anywhere}.inbox-problem{color:var(--danger)}
+.bar .inbox-count{background:var(--surface);color:var(--text)}.bar .inbox-link{padding:0;flex-shrink:0;text-decoration:underline;text-underline-offset:4px;color:var(--link);white-space:nowrap;gap:.4rem}
+.bar .inbox-link[aria-current="page"]{font-weight:700}
+@media(max-width:600px){.inbox-row{flex-direction:column}.response-panel{padding:0}}
+@media(max-width:600px){.question-choices{grid-template-columns:minmax(0,1fr)}}
+`;
+
+function sourceAge(modified: number, now: number | undefined): string {
+	if (now === undefined) {
+		return `<span class="age" data-modified="${modified}">updated ${new Date(modified).toISOString()}</span>`;
+	}
+	const minutes = Math.max(0, Math.floor((now - modified) / 60_000));
+	const age = elapsedAge(minutes);
+	return `<span class="age" data-modified="${modified}">updated ${age} ago</span>`;
+}
+
+function elapsedAge(minutes: number): string {
+	if (minutes < 60) {
+		return `${minutes}m`;
+	}
+	if (minutes < 48 * 60) {
+		return `${Math.floor(minutes / 60)}h`;
+	}
+	return `${Math.round(minutes / (24 * 60))}d`;
+}

package/src/server/attention/managedRequestReceipt.ts

@@ -0,0 +1,91 @@
+import type { RequestReceipt } from "#attention/RequestReceipt.ts";
+import type { Metadata } from "#metadata/schema.ts";
+import { currentResponses } from "#responses/current.ts";
+import type { MetadataDocument, MetadataModel } from "#server/metadata/model.ts";
+import { malformedResponse, questionFrom, questionId, responseFrom, responsesFor, revisionOf } from "#server/responses/records.ts";
+
+type Request = NonNullable<Metadata["attention"]>[number];
+
+function uniqueDocument(id: string, model: MetadataModel): MetadataDocument | undefined {
+	const matches = model.ids.get(id);
+	return matches?.length === 1 ? matches[0] : undefined;
+}
+
+function appliedAnswer(question: string, revision: string, responseId: string | undefined, model: MetadataModel): boolean {
+	if (responseId === undefined) {
+		return false;
+	}
+	const matches = model.ids.get(responseId);
+	const answer = matches?.length === 1 && matches[0] ? responseFrom(matches[0]) : undefined;
+	if (answer?.response.type !== "answer" || answer.response.question !== question || answer.response.reviewedRevision !== revision) {
+		return false;
+	}
+	const registered = model.ids.get(question)?.[0];
+	const context = registered && questionFrom(registered);
+	if (!context || model.documents.some(malformedResponse)) {
+		return false;
+	}
+	const responses = responsesFor(model.documents, context).responses;
+	if (responses.some((response) => model.ids.get(response.id)?.length !== 1)) {
+		return false;
+	}
+	const current = currentResponses(responses);
+	return current.length === 1 && current[0]?.id === responseId;
+}
+
+export function managedRequestReceipt(document: MetadataDocument, request: Request, model: MetadataModel): RequestReceipt | undefined {
+	const item = document.parsed.fields.id;
+	if (
+		request.managed !== true
+		|| request.kind !== "decision"
+		|| request.state !== "open"
+		|| !item
+		|| document.parsed.fields.kind !== "decision"
+		|| document.parsed.diagnostics.length > 0
+		|| document.parsed.fields.attention?.filter((candidate) => candidate.id === request.id).length !== 1
+		|| model.unavailable.length > 0
+		|| model.ids.get(item)?.length !== 1
+	) {
+		return undefined;
+	}
+	const source = `${document.parsed.raw ?? ""}${document.parsed.body}`;
+	const revision = revisionOf(source);
+	const id = questionId(item, request.id, revision, document.file);
+	const archived = uniqueDocument(id, model);
+	const question = archived && questionFrom(archived);
+	if (
+		archived?.parsed.diagnostics.length !== 0
+		|| !question
+		|| question.context !== source
+		|| question.question.source !== document.file
+		|| question.question.item !== item
+		|| question.question.request !== request.id
+		|| question.question.reviewedRevision !== revision
+	) {
+		return undefined;
+	}
+	if (
+		model.documents.some((entry) =>
+			entry.parsed.diagnostics.some((problem) => problem.field === "request_receipt" || problem.field === "requestReceipt"),
+		)
+	) {
+		return undefined;
+	}
+	const receipts = model.documents.filter((entry) => entry.parsed.fields.requestReceipt?.question === id);
+	const saved = receipts.length === 1 ? receipts[0] : undefined;
+	const receipt = saved?.parsed.fields.requestReceipt;
+	if (
+		!(saved && receipt)
+		|| saved.parsed.fields.kind !== "result"
+		|| saved.parsed.diagnostics.length > 0
+		|| !saved.parsed.fields.id
+		|| model.ids.get(saved.parsed.fields.id)?.length !== 1
+		|| receipt.reviewedRevision !== revision
+	) {
+		return undefined;
+	}
+	if (receipt.disposition === "superseded") {
+		return receipt.response === undefined ? receipt : undefined;
+	}
+	return appliedAnswer(id, revision, receipt.response, model) ? receipt : undefined;
+}

package/src/server/attention/overviewHtml.ts

@@ -0,0 +1,46 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { fileUrl } from "#files/url.ts";
+import { referenceHtml } from "#server/page/metadataLinks.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { inboxItems } from "./inbox.ts";
+import { inboxHtml } from "./inboxHtml.ts";
+import { type AttentionEntry, attentionRequests } from "./requests.ts";
+
+function card(entry: AttentionEntry, snapshot: Snapshot): string {
+	const { request } = entry;
+	return `<article class="attention-card" data-key="attention:${escapeHtml(entry.itemId)}:${escapeHtml(request.id)}" data-attention-item="${escapeHtml(entry.itemId)}" data-request="${escapeHtml(request.id)}">
+<p class="work-kind">${escapeHtml(request.kind)} request</p><h3><a href="${escapeHtml(entry.href)}">${escapeHtml(entry.title)}</a></h3>
+<p class="work-id">${escapeHtml(entry.itemId)} / ${escapeHtml(request.id)}</p><p class="attention-reason">${escapeHtml(request.reason)}</p>
+<dl><dt>Response needed from</dt><dd>${request.responseFrom.map(escapeHtml).join(", ")}</dd><dt>Recorded to unblock</dt><dd>${request.unblocks.map((target) => referenceHtml(target, target, snapshot.model)).join(", ")}</dd></dl>
+<a class="attention-source" href="${escapeHtml(fileUrl(entry.document.file))}#attention-request-${encodeURIComponent(request.id)}">Source: ${escapeHtml(entry.document.file)}:${entry.line}</a></article>`;
+}
+
+export function overviewHtml(snapshot: Snapshot): string {
+	const projection = attentionRequests(snapshot);
+	const header =
+		'<header class="work-head"><p class="work-eyebrow">WORKSPACE · OVERVIEW</p><h1>What needs a response?</h1><p>Choose a recorded request to read its context, reasoning and evidence.</p><a href="/_board/work?view=board">Browse all work</a></header>';
+	const issues =
+		projection.issues.length > 0
+			? `<details class="view-issues" data-key="attention-issues"><summary>Unclassified requests and source issues (${projection.issues.length})</summary><p>Ambiguous or invalid requests stay outside the queues. Read their original sources.</p><ul>${projection.issues.map((issue) => `<li><a href="${escapeHtml(fileUrl(issue.file))}">${escapeHtml(issue.file)}:${issue.line}</a> — ${escapeHtml(issue.message)}</li>`).join("")}</ul></details>`
+			: "";
+	if (!projection.complete) {
+		return `${header}<p class="attention-incomplete" role="status">Workspace incomplete. Could not read ${snapshot.unavailable.map(escapeHtml).join(", ")}. Requests are not counted or classified until the index is complete.</p>${issues}`;
+	}
+	let summary = inboxItems(snapshot).length > 0 ? "No explicit open attention requests recorded." : "All quiet — no explicit open requests recorded.";
+	if (projection.entries.length > 0) {
+		summary = `${projection.entries.length} validated open request${projection.entries.length === 1 ? "" : "s"}`;
+	} else if (projection.issues.length > 0) {
+		summary = "No validated open requests. Check unresolved source issues before treating this workspace as quiet.";
+	}
+	const groups = [
+		{ empty: "No open decision requests.", kind: "decision", title: "Decisions" },
+		{ empty: "No open review requests.", kind: "review", title: "Reviews" },
+		{ empty: "No open blocker requests.", kind: "blocker", title: "Blockers" },
+	]
+		.map((group) => {
+			const entries = projection.entries.filter((entry) => entry.request.kind === group.kind);
+			return `<section class="attention-group" aria-labelledby="attention-${group.kind}"><h2 id="attention-${group.kind}" tabindex="-1">${group.title}<span>${entries.length}</span></h2>${entries.length > 0 ? entries.map((entry) => card(entry, snapshot)).join("") : `<p class="empty">${group.empty}</p>`}</section>`;
+		})
+		.join("");
+	return `${header}${inboxHtml(snapshot, true)}<p class="attention-total" role="status">${summary}</p><p class="attention-order">Decisions, reviews, then blockers. Within each group: source title, item ID, request ID. Recipients are recorded labels.</p>${issues}<div class="attention-groups">${groups}</div><p class="attention-footnote">These are authored requests. Closing one does not verify evidence or record an answer. The Inbox also shows human-owned next actions and questions; file activity and finished runs do not create requests.</p>`;
+}

package/src/server/attention/questionState.ts

@@ -0,0 +1,71 @@
+import type { Question } from "#browser/responses/schema.ts";
+import { responseUrl } from "#responses/url.ts";
+import type { MetadataDocument, MetadataModel } from "#server/metadata/model.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { questionFrom, responseFrom } from "#server/responses/records.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { attentionRequests, isMaintainerRequest } from "./requests.ts";
+
+function currentSource(question: Question, document: MetadataDocument): boolean {
+	const captured = metadataParse(question.context);
+	return question.question.source === document.file && captured.raw === document.parsed.raw && captured.body === document.parsed.body;
+}
+
+function hasAnswer(question: Question, model: MetadataModel): boolean {
+	return model.documents.some((source) => {
+		const response = responseFrom(source);
+		return (
+			response?.response.question === question.id
+			&& response.response.type === "answer"
+			&& response.response.reviewedRevision === question.question.reviewedRevision
+			&& model.ids.get(response.id)?.length === 1
+		);
+	});
+}
+
+export function answeredQuestion(document: MetadataDocument, model: MetadataModel): boolean {
+	return model.documents.some((candidate) => {
+		const question = questionFrom(candidate);
+		return (
+			question !== undefined
+			&& question.question.item === document.parsed.fields.id
+			&& model.ids.get(question.id)?.length === 1
+			&& currentSource(question, document)
+			&& hasAnswer(question, model)
+		);
+	});
+}
+
+export function pendingQuestions(snapshot: Snapshot) {
+	const open = attentionRequests(snapshot).entries.filter((entry) => isMaintainerRequest(entry.request, snapshot.maintainer));
+	const titles = new Map(snapshot.entries.filter((entry) => entry.kind === "document").map((entry) => [entry.file, entry.title]));
+	return snapshot.documents.flatMap((captured) => {
+		const question = questionFrom(captured);
+		if (!question || modelAmbiguous(question, snapshot.model) || hasAnswer(question, snapshot.model)) {
+			return [];
+		}
+		const source = snapshot.model.ids.get(question.question.item)?.[0];
+		if (
+			!(
+				source
+				&& currentSource(question, source)
+				&& open.some((entry) => entry.itemId === question.question.item && entry.request.id === question.question.request)
+			)
+		) {
+			return [];
+		}
+		return [
+			{
+				document: source,
+				href: responseUrl(question.question.item, question.question.request),
+				id: question.question.item,
+				reason: question.question.reason,
+				title: titles.get(source.file) ?? source.file,
+			},
+		];
+	});
+}
+
+function modelAmbiguous(question: Question, model: MetadataModel): boolean {
+	return model.ids.get(question.id)?.length !== 1 || model.ids.get(question.question.item)?.length !== 1;
+}

package/src/server/attention/requests.ts

@@ -0,0 +1,70 @@
+import type { Metadata } from "#metadata/schema.ts";
+import { managedRequestReceipt } from "#server/attention/managedRequestReceipt.ts";
+import { identityUrl, referenceTarget } from "#server/metadata/links.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+
+export type Request = NonNullable<Metadata["attention"]>[number];
+export interface AttentionEntry {
+	readonly document: MetadataDocument;
+	readonly href: string;
+	readonly itemId: string;
+	readonly line: number;
+	readonly request: Request;
+	readonly title: string;
+}
+export interface SourceIssue {
+	readonly file: string;
+	readonly line: number;
+	readonly message: string;
+}
+
+export function isMaintainerRequest(request: Request, maintainer = "maintainer"): boolean {
+	return request.responseFrom.includes(maintainer);
+}
+
+function requestsFor(document: MetadataDocument, snapshot: Snapshot, title: string): readonly AttentionEntry[] {
+	const { fields, lines } = document.parsed;
+	const itemId = fields.id;
+	if (!itemId || snapshot.unavailable.length > 0 || snapshot.model.ids.get(itemId)?.length !== 1) {
+		return [];
+	}
+	const requests = fields.attention ?? [];
+	return requests.flatMap((request, index) => {
+		if (
+			request.state !== "open"
+			|| requests.filter((other) => other.id === request.id).length !== 1
+			|| request.unblocks.some((target) => !referenceTarget(target, snapshot.model))
+			|| managedRequestReceipt(document, request, snapshot.model) !== undefined
+		) {
+			return [];
+		}
+		return [
+			{
+				document,
+				href: `${identityUrl(itemId)}#attention-request-${encodeURIComponent(request.id)}`,
+				itemId,
+				line: lines[`attention.${index}`] ?? lines.attention ?? 2,
+				request,
+				title,
+			},
+		];
+	});
+}
+
+export function attentionRequests(snapshot: Snapshot) {
+	const titles = new Map(snapshot.entries.filter((entry) => entry.kind === "document").map((entry) => [entry.file, entry.title]));
+	const issues: SourceIssue[] = snapshot.documents.flatMap((source) =>
+		(snapshot.model.diagnostics.get(source.file) ?? source.parsed.diagnostics).map((problem) => ({ ...problem, file: source.file })),
+	);
+	const entries = snapshot.documents.flatMap((source) => requestsFor(source, snapshot, titles.get(source.file) ?? source.file));
+	const collator = new Intl.Collator("en", { numeric: true, sensitivity: "base" });
+	entries.sort((a, b) => collator.compare(a.title, b.title) || a.itemId.localeCompare(b.itemId) || a.request.id.localeCompare(b.request.id));
+	return { complete: snapshot.unavailable.length === 0, entries, issues };
+}
+
+export function attentionSource(document: MetadataDocument, index: number): string {
+	const requests = document.parsed.fields.attention ?? [];
+	const id = requests[index]?.id;
+	return id && requests.filter((request) => request.id === id).length === 1 ? `attention-request-${id}` : `attention-record-${index}`;
+}