@shivaedev/work-board 0.11.0 → 0.12.0

package/src/server/responses/composerHtml.ts

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { QuestionPreview, RecordedResponse } from "#browser/responses/schema.ts";
+import { fileUrl } from "#files/url.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { historyHtml } from "./historyHtml.ts";
+import { templateHtml } from "./templateHtml.ts";
+
+export const composerHtml = Effect.fn("WorkBoard.composerHtml")(function* (
+	q: QuestionPreview,
+	records: readonly RecordedResponse[],
+	enabled: boolean,
+) {
+	const template = yield* templateHtml(q.context, q.request, q.source);
+	const standalone = metadataParse(q.context).fields.kind === "question";
+	const prior = records
+		.map(
+			(record) =>
+				`<option value="${escapeHtml(record.id)}">${escapeHtml(record.id)} · ${escapeHtml(record.response.author)} · ${record.response.reviewedRevision.slice(0, 12)}</option>`,
+		)
+		.join("");
+	const body = `<label>${template.hasPrompts ? "Overall response / next action (optional)" : "Your response"}<textarea name="body" rows="4" maxlength="32768" ${template.hasPrompts ? "" : "required"}></textarea></label>`;
+	const details = `<details data-key="response-details"><summary>Response details</summary><label>Response kind <select name="type"><option value="answer">Answer (including no)</option><option value="clarify">Ask back / clarify</option><option value="not_now">Not now</option></select></label>${standalone && template.hasPrompts ? body : ""}<label>Supersedes an earlier response (optional)<select name="supersedes"><option value="">Adds feedback; does not supersede</option>${prior}</select></label></details>`;
+	return `<section class="response-panel"><h${standalone ? "2" : "1"}>${standalone ? "Answer this question" : `Respond to ${escapeHtml(q.item)} / ${escapeHtml(q.request)}`}</h${standalone ? "2" : "1"}><p>${escapeHtml(q.reason)}</p><p><a href="${fileUrl(q.source)}">Source: ${escapeHtml(q.source)}</a> · Reviewed SHA-256: <code>${q.reviewedRevision}</code></p><p>${standalone ? "An answer removes this question from the Inbox for this source revision." : "Saved replies are authored feedback. They do not close the request or establish acceptance."}</p>${standalone ? "" : `<section class="response-context">${template.background}</section>`}<details><summary>Exact source being reviewed</summary><pre>${escapeHtml(q.context)}</pre></details><form novalidate id="response-form" data-question="${q.id}" data-writable="${enabled}" data-item="${escapeHtml(q.item)}" data-request="${escapeHtml(q.request)}" data-revision="${q.reviewedRevision}"><label>Local author label <input name="author" maxlength="200" required autocomplete="nickname"></label>${template.controls}${standalone && template.hasPrompts ? "" : body}${details}<pre id="response-draft-recovery" hidden></pre><p>Submit the whole packet together. Drafts stay in this browser for 30 days after the last edit, with a 2 MiB workspace limit. Saved responses are Markdown files in responses/.</p><button id="response-preview" type="button" disabled>Preview Markdown</button><pre id="response-preview-content" hidden></pre><button id="response-submit" type="submit" disabled>Record response</button><button id="response-clear" type="button" disabled>Clear workspace drafts</button><p id="response-status" role="status">${enabled ? "JavaScript is required to record a response." : "Read-only mode. Restart with --responses to explicitly enable local writes."}</p></form>${yield* historyHtml(q, records)}</section>`;
+});

package/src/server/responses/flags.ts

@@ -0,0 +1,23 @@
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+export function flags(args: readonly string[]) {
+	const values = new Map<string, string>();
+	for (let index = 0; index < args.length; index += 2) {
+		const name = args[index];
+		const value = args[index + 1];
+		if (!(name && value && ["--port", "--url", "--revision", "--after"].includes(name))) {
+			throw new BadRequest({ message: "Use --port, --url, --revision or --after, each with a value." });
+		}
+		if (values.has(name)) {
+			throw new BadRequest({ message: `Repeated option ${name}. Supply each option once.` });
+		}
+		values.set(name, value);
+	}
+	const port = values.get("--port") ?? "4747";
+	if (/^\d{1,5}$/u.exec(port) === null || Number(port) > 65_535 || Number(port) < 1) {
+		throw new BadRequest({ message: "Invalid port. Use an integer from 1 to 65535." });
+	}
+	if (values.has("--url") && values.has("--port")) {
+		throw new BadRequest({ message: "Choose --url or --port." });
+	}
+	return { after: values.get("--after"), revision: values.get("--revision"), url: values.get("--url") ?? `http://127.0.0.1:${port}` };
+}

package/src/server/responses/history.ts

@@ -0,0 +1,21 @@
+import { ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { QuestionPreview } from "#browser/responses/schema.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { malformedResponse, questionFrom, responsesFor } from "./records.ts";
+
+export function responseHistory(data: Snapshot, preview: QuestionPreview) {
+	if (data.unavailable.length > 0 || data.documents.some(malformedResponse)) {
+		throw new ServiceUnavailable({ message: "Response history is incomplete or malformed. Check the source diagnostics and retry." });
+	}
+	const questions = data.documents.flatMap((document) => {
+		const question = questionFrom(document);
+		return question && question.question.item === preview.item && question.question.request === preview.request ? [question] : [];
+	});
+	const responses = questions.flatMap((question) => responsesFor(data.documents, question).responses);
+	if ([...questions, ...responses].some((record) => data.model.ids.get(record.id)?.length !== 1)) {
+		throw new ServiceUnavailable({
+			message: "Response history includes ambiguous identities. Give each recorded question and response a unique ID, then retry.",
+		});
+	}
+	return responses.sort((a, b) => b.response.recordedAt - a.response.recordedAt);
+}

package/src/server/responses/historyHtml.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { QuestionPreview, RecordedResponse } from "#browser/responses/schema.ts";
+import type { RenderFailed } from "#render/failed.ts";
+import type { Highlighter } from "#server/render/Highlighter.ts";
+import { renderMarkdown } from "#server/render/markdown.ts";
+
+export const historyHtml = Effect.fn("WorkBoard.historyHtml")(function* (
+	q: QuestionPreview,
+	records: readonly RecordedResponse[],
+): Effect.fn.Return<string, RenderFailed, Highlighter> {
+	const history = yield* Effect.forEach(records, (record) =>
+		Effect.map(
+			renderMarkdown(record.body, { file: `responses/${record.id}.md`, safe: true }),
+			(html) =>
+				`<article id="${escapeHtml(record.id)}"><h3><a href="/responses/${record.id}.md">${escapeHtml(record.response.author)} · ${record.response.type}</a></h3><p>${record.response.question === q.id ? "This reviewed revision" : "Earlier reviewed context — does not approve the current source"} · <code>${record.response.reviewedRevision}</code></p>${record.response.supersedes ? `<p>Explicitly supersedes <a href="/responses/${escapeHtml(record.response.supersedes)}.md">${escapeHtml(record.response.supersedes)}</a>.</p>` : ""}${html}</article>`,
+		),
+	);
+	return `<section id="response-history"><h2>Recorded responses</h2>${history.join("") || "<p>No response is recorded for this source revision.</p>"}</section>`;
+});

package/src/server/responses/locate.ts

@@ -0,0 +1,60 @@
+import { Effect, type FileSystem } from "effect";
+import { BadRequest, NotFound, PreconditionFailed, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { rpcBoundary } from "@shivaedev/platform/rpc-server/boundary.ts";
+import type { QuestionPreview } from "#browser/responses/schema.ts";
+import type { ResponseRejection } from "#rpc/rejections.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import { metadataModel } from "#server/metadata/model.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { questionId, revisionOf } from "./records.ts";
+import { requestSource } from "./requestSource.ts";
+import { questionTemplate } from "./template.ts";
+
+export function locate(root: string, realRoot: string, snapshot: Effect.Effect<Snapshot, ResponseRejection>, fs: FileSystem.FileSystem) {
+	return Effect.fn("WorkBoard.locate")(function* (item: string, request: string) {
+		const data = yield* snapshot;
+		const entry = requestSource(data, item, request);
+		if (!entry) {
+			return yield* Effect.fail(new NotFound({ message: "The exact open attention request is missing, ambiguous or unavailable." }));
+		}
+		const real = yield* markdownPath(root, realRoot, entry.document.file);
+		if (!real) {
+			return yield* Effect.fail(new NotFound({ message: "The reviewed source moved or disappeared." }));
+		}
+		const source = yield* fs
+			.readFileString(real)
+			.pipe(
+				rpcBoundary(ServiceUnavailable, { message: "The source could not be read.", unexpected: (message) => new ServiceUnavailable({ message }) }),
+			);
+		if (new TextEncoder().encode(source).length > 256 * 1024) {
+			return yield* Effect.fail(new BadRequest({ message: "Question context is limited to 256 KiB; use a focused source document." }));
+		}
+		const parsed = metadataParse(source);
+		const documents = [...data.documents.filter((document) => document.file !== entry.document.file), { file: entry.document.file, parsed }];
+		const model = metadataModel(documents, data.unavailable, data.model.rootFile);
+		const fresh = requestSource({ ...data, documents, model }, item, request);
+		if (!fresh) {
+			return yield* Effect.fail(
+				new PreconditionFailed({
+					message: "The current request or its references are invalid. Review the source diagnostics before registering it.",
+				}),
+			);
+		}
+		const revision = revisionOf(source);
+		yield* Effect.try({
+			catch: (cause) => new BadRequest({ message: `Invalid response template: ${cause instanceof Error ? cause.message : String(cause)}` }),
+			try: () => questionTemplate(source, request),
+		});
+		const question: QuestionPreview = {
+			context: source,
+			id: questionId(item, request, revision, entry.document.file),
+			item,
+			reason: fresh.reason,
+			request,
+			reviewedRevision: revision,
+			source: entry.document.file,
+		};
+		return question;
+	});
+}

package/src/server/responses/optionControls.ts

@@ -0,0 +1,13 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import type { Metadata } from "#metadata/schema.ts";
+
+export function optionControls(prompt: Prompt, fields: Metadata): string {
+	const options = prompt.options
+		.map((option, index) => {
+			const source = fields.options?.[index];
+			return `<input type="radio" name="choice-answer" value="${option.id}" data-option-source="${escapeHtml(option.source)}" hidden><button type="button" class="question-choice" data-choice="${option.id}" aria-pressed="false"><strong>${escapeHtml(source?.label ?? "")}${source?.label === fields.recommended ? " · Recommended" : ""}</strong><small>${escapeHtml(source?.description ?? "")}</small></button>`;
+		})
+		.join("");
+	return `<fieldset data-prompt="answer" data-mode="one" data-source="${escapeHtml(prompt.source)}"><legend>Your answer</legend><p>Choose an option or write another answer. Nothing is selected for you.</p><div class="question-choices">${options}</div><button type="button" data-clear-choices>Clear selection</button><label>Another answer / additional text<textarea data-answer-text maxlength="8192" rows="4"></textarea></label></fieldset>`;
+}

package/src/server/responses/optionPrompt.ts

@@ -0,0 +1,21 @@
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import type { Metadata } from "#metadata/schema.ts";
+
+export function optionPrompt(fields: Metadata): Prompt | undefined {
+	if (fields.kind !== "question" || fields.question || fields.options === undefined) {
+		return undefined;
+	}
+	if (new Set(fields.options.map((option) => option.label)).size !== fields.options.length) {
+		throw new BadRequest({ message: "Question option labels must be unique. Rename the repeated labels in the source." });
+	}
+	if (fields.recommended && !fields.options.some((option) => option.label === fields.recommended)) {
+		throw new BadRequest({ message: "The recommended option must name an option label." });
+	}
+	return {
+		id: "answer",
+		mode: "one",
+		options: fields.options.map((option, index) => ({ id: `option-${index + 1}`, source: `${option.label}\n\n${option.description}` })),
+		source: "Your answer",
+	};
+}

package/src/server/responses/page.ts

@@ -0,0 +1,37 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { respond } from "#server/http/respond.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { composerHtml } from "./composerHtml.ts";
+import { Responses } from "./service.ts";
+
+export function responsePage(
+	changes: Changes,
+	home: string | undefined,
+	enabled: boolean,
+	index?: Effect.Success<ReturnType<typeof searchSnapshot>>,
+) {
+	return Effect.fn("WorkBoard.responsePage")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const service = yield* Responses;
+		const params = new URL(request.url, "http://127.0.0.1").searchParams;
+		const files = yield* changes.files;
+		const snapshot = index ? yield* index : undefined;
+		function layout(body: string, status = 200) {
+			return respond(
+				shell("Respond", navHtml(files, "", home, snapshot), body, changes.realRoot, false, undefined, "response", snapshot),
+				"text/html",
+				status,
+			);
+		}
+		return yield* Effect.gen(function* () {
+			const question = yield* service.locate(params.get("item") ?? "", params.get("request") ?? "");
+			yield* service.read(question.id).pipe(Effect.catch((error) => (error._tag === "NotFound" ? Effect.void : Effect.fail(error))));
+			const records = yield* service.history(question);
+			return layout(yield* composerHtml(question, records, enabled));
+		}).pipe(Effect.catch((error) => Effect.succeed(layout(`<h1>Response unavailable</h1><p>${escapeHtml(error.message)}</p>`, 409))));
+	});
+}

package/src/server/responses/publicationDirectory.ts

@@ -0,0 +1,42 @@
+import { type FileHandle, lstat, realpath } from "node:fs/promises";
+import process from "node:process";
+import { Conflict } from "@shivaedev/platform/errors/taxonomy.ts";
+import { PublicationUncertain } from "#rpc/rejections.ts";
+
+export function directoryPath(directory: FileHandle, expected: string): string {
+	return process.platform === "linux" ? `/proc/self/fd/${directory.fd}` : expected;
+}
+
+function boundaryChanged(cause?: unknown) {
+	return Object.defineProperty(new Conflict({ message: "The write boundary changed." }), "cause", { value: cause });
+}
+function missing(cause: unknown) {
+	return cause instanceof Error && "code" in cause && (cause.code === "ENOENT" || cause.code === "ENOTDIR" || cause.code === "ELOOP");
+}
+
+// Sequential on purpose: the path is observed after the handle, so a swap that lands while the handle is being read is still seen.
+export async function validateDirectory(directory: FileHandle, path: string, expected: string) {
+	const opened = await directory.stat();
+	try {
+		const current = await lstat(expected);
+		if (!current.isDirectory() || current.dev !== opened.dev || current.ino !== opened.ino || (await realpath(path)) !== expected) {
+			throw boundaryChanged();
+		}
+	} catch (cause) {
+		throw missing(cause) ? boundaryChanged(cause) : cause;
+	}
+}
+
+export function uncertain(cause: unknown) {
+	return cause instanceof PublicationUncertain
+		? cause
+		: Object.defineProperty(
+				new PublicationUncertain({ message: "Publication may have completed. Re-read the record identity before retrying." }),
+				"cause",
+				{ value: cause },
+			);
+}
+
+export function publicationFailure(cause: unknown, published: boolean): never {
+	throw published ? uncertain(cause) : cause;
+}

package/src/server/responses/publish.ts

@@ -0,0 +1,72 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath } from "node:fs/promises";
+import process from "node:process";
+import { Effect, Schema } from "effect";
+import { BadRequest, Conflict, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { PublicationUncertain, ResponseRejection } from "#rpc/rejections.ts";
+import { directoryPath, publicationFailure, validateDirectory } from "./publicationDirectory.ts";
+import { publishIn } from "./publishIn.ts";
+
+function failure(cause: unknown): ResponseRejection {
+	return Schema.is(ResponseRejection)(cause)
+		? cause
+		: Object.defineProperty(
+				new ServiceUnavailable({
+					message: "The local record could not be recorded. Keep the draft and retry after checking local filesystem access.",
+				}),
+				"cause",
+				{ value: cause },
+			);
+}
+async function createDirectory(path: string) {
+	try {
+		await mkdir(path);
+	} catch (cause) {
+		if (!(cause instanceof Error && "code" in cause && cause.code === "EEXIST")) {
+			throw cause;
+		}
+	}
+}
+export function publish(root: string, realRoot: string, id: string, content: string, namespace: "responses" | "handoffs" = "responses") {
+	return Effect.tryPromise({
+		catch: failure,
+		try: async () => {
+			if (/^[a-zA-Z\d][a-zA-Z\d._-]*$/u.exec(id) === null) {
+				throw new Conflict({ message: "Invalid record identity." });
+			}
+			if (process.platform !== "linux" && process.platform !== "darwin") {
+				throw new BadRequest({
+					message: "Local record publication requires Linux or macOS. Reading remains available.",
+				});
+			}
+			let published = false;
+			const directory = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+			try {
+				const base = directoryPath(directory, realRoot);
+				await validateDirectory(directory, base, realRoot);
+				if ((await realpath(root)) !== realRoot) {
+					throw new Conflict({ message: "The workspace root changed. Restart against the intended root." });
+				}
+				await createDirectory(`${base}/${namespace}`);
+				await validateDirectory(directory, base, realRoot);
+				await directory.sync();
+				const target = await open(`${base}/${namespace}`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+				try {
+					await validateDirectory(directory, base, realRoot);
+					await publishIn(target, root, realRoot, id, content, namespace).catch((cause: unknown) => {
+						published = cause instanceof PublicationUncertain;
+						throw cause;
+					});
+					published = true;
+					await validateDirectory(directory, base, realRoot);
+				} finally {
+					await target.close();
+				}
+			} catch (cause) {
+				publicationFailure(cause, published);
+			} finally {
+				await directory.close().catch((cause: unknown) => publicationFailure(cause, published));
+			}
+		},
+	});
+}

package/src/server/responses/publishIn.ts

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { type FileHandle, link, lstat, open, readFile, realpath, unlink } from "node:fs/promises";
+import { Conflict } from "@shivaedev/platform/errors/taxonomy.ts";
+import { PublicationUncertain } from "#rpc/rejections.ts";
+import { directoryPath, publicationFailure, uncertain, validateDirectory } from "./publicationDirectory.ts";
+
+function exists(cause: unknown) {
+	return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+}
+async function linkOrReconcile(temporary: string, name: string, content: string): Promise<boolean> {
+	try {
+		await link(temporary, name);
+		return true;
+	} catch (cause) {
+		if (!exists(cause)) {
+			throw cause;
+		}
+	}
+	const existing = await open(name, constants.O_RDONLY | constants.O_NOFOLLOW);
+	let matched = false;
+	try {
+		if ((await readFile(existing, "utf8")) !== content) {
+			throw new Conflict({ message: "This identity already records different content; no file was replaced." });
+		}
+		matched = true;
+		await existing.sync();
+	} catch (cause) {
+		if (matched) {
+			throw uncertain(cause);
+		}
+		throw cause;
+	} finally {
+		await existing.close().catch((cause: unknown) => {
+			if (matched) {
+				throw uncertain(cause);
+			}
+			throw cause;
+		});
+	}
+	return false;
+}
+export async function publishIn(
+	target: FileHandle,
+	root: string,
+	realRoot: string,
+	id: string,
+	content: string,
+	namespace: "responses" | "handoffs" = "responses",
+) {
+	const expected = `${realRoot}/${namespace}`;
+	const folder = directoryPath(target, expected);
+	const originalRoot = await lstat(root);
+	async function validate() {
+		await validateDirectory(target, folder, expected);
+		const currentRoot = await lstat(root);
+		if (
+			!currentRoot.isDirectory()
+			|| currentRoot.dev !== originalRoot.dev
+			|| currentRoot.ino !== originalRoot.ino
+			|| (await realpath(root)) !== realRoot
+		) {
+			throw new Conflict({ message: "The write boundary changed." });
+		}
+	}
+	await validate();
+	const name = `${folder}/${id}.md`;
+	const temporary = `${folder}/.${randomUUID()}.tmp`;
+	let published = false;
+	try {
+		const file = await open(temporary, "wx", 0o600);
+		try {
+			await file.writeFile(content, "utf8");
+			await file.sync();
+		} finally {
+			await file.close();
+		}
+		await validate();
+		await linkOrReconcile(temporary, name, content);
+		published = true;
+		await target.sync();
+		await validate();
+	} catch (cause) {
+		published ||= cause instanceof PublicationUncertain;
+		publicationFailure(cause, published);
+	} finally {
+		await validate().catch((cause: unknown) => publicationFailure(cause, published));
+		await unlink(temporary).catch(() => undefined);
+	}
+}

package/src/server/responses/read.ts

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { BadRequest, Conflict, NotFound, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { ResponseRejection } from "#rpc/rejections.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { malformedResponse, questionFrom, responsesFor } from "./records.ts";
+
+const registeredQuestion = Effect.fn("WorkBoard.registeredQuestion")(function* (matches: readonly MetadataDocument[] | undefined) {
+	if (!matches?.length) {
+		return yield* Effect.fail(new NotFound({ message: "The registered question is missing." }));
+	}
+	if (matches.length !== 1) {
+		return yield* Effect.fail(new Conflict({ message: "The registered question identity is ambiguous; response history is unknown." }));
+	}
+	const question = matches[0] && questionFrom(matches[0]);
+	if (!question) {
+		return yield* Effect.fail(new Conflict({ message: "This identity is not a valid registered question; response history is unknown." }));
+	}
+	return question;
+});
+export function readResponses(snapshot: Effect.Effect<Snapshot, ResponseRejection>) {
+	return Effect.fn("WorkBoard.read")(function* (id: string) {
+		const data = yield* snapshot;
+		if (data.unavailable.length > 0) {
+			return yield* Effect.fail(new ServiceUnavailable({ message: "The workspace index is incomplete; no response can be selected safely." }));
+		}
+		const question = yield* registeredQuestion(data.model.ids.get(id));
+		if (new TextEncoder().encode(question.context).length > 256 * 1024) {
+			return yield* Effect.fail(new BadRequest({ message: "The registered context exceeds the 256 KiB limit." }));
+		}
+		if (data.documents.some(malformedResponse)) {
+			return yield* Effect.fail(
+				new ServiceUnavailable({ message: "A response record is malformed; response history cannot be established safely." }),
+			);
+		}
+		const result = responsesFor(data.documents, question);
+		if (result.responses.some((candidate) => candidate.body.length > 32_768)) {
+			return yield* Effect.fail(new BadRequest({ message: "A recorded response exceeds the supported text limit; read its source file directly." }));
+		}
+		if (result.responses.some((candidate) => data.model.ids.get(candidate.id)?.length !== 1)) {
+			return yield* Effect.fail(new Conflict({ message: "A response identity is duplicated; no answer is selected." }));
+		}
+		return result;
+	});
+}

package/src/server/responses/readingActions.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect";
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+import { responseUrl } from "#responses/url.ts";
+import { authoredQuestion } from "#server/attention/inbox.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import { Responses } from "./service.ts";
+import { questionTemplate } from "./template.ts";
+
+export const readingActions = Effect.fn("WorkBoard.readingActions")(function* (
+	document: MetadataDocument,
+	source: string,
+	enabled: boolean,
+	identity: string | undefined,
+) {
+	if (!(enabled && identity)) {
+		return undefined;
+	}
+	const service = yield* Responses;
+	const item = identity;
+	const requests = authoredQuestion(document) ? ["answer"] : (document.parsed.fields.attention ?? []).map((request) => request.id);
+	const actions = new Map<string, string>();
+	for (const request of requests) {
+		const question = yield* service.locate(item, request).pipe(Effect.option);
+		if (question._tag === "Some" && question.value.context === source) {
+			const template = yield* Effect.try({
+				catch: (cause) => new BadRequest({ message: cause instanceof Error ? cause.message : "Review the question template and retry." }),
+				try: () => questionTemplate(source, request),
+			}).pipe(Effect.option);
+			for (const prompt of template._tag === "Some" ? template.value.prompts : []) {
+				actions.set(`${request}/${prompt.id}`, responseUrl(item, request));
+				actions.set(`/${prompt.id}`, responseUrl(item, request));
+			}
+		}
+	}
+	return actions;
+});

package/src/server/responses/records.ts

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { stringify } from "yaml";
+import type { DraftInput, Question, Reading, RecordedResponse } from "#browser/responses/schema.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+
+export function revisionOf(source: string) {
+	return createHash("sha256").update(source).digest("hex");
+}
+export function questionId(item: string, request: string, revision: string, source: string) {
+	return `question.${revisionOf(JSON.stringify([item, request, revision, source]))}`;
+}
+export function questionMarkdown(record: Question): string {
+	return `---\n${stringify({ id: record.id, kind: "question", question: record.question })}---\n${record.context}`;
+}
+export function responseMarkdown(record: RecordedResponse): string {
+	return `---\n${stringify({ id: record.id, kind: "response", response: record.response })}---\n${record.body}`;
+}
+export function questionFrom(document: MetadataDocument): Question | undefined {
+	const { id, kind, question } = document.parsed.fields;
+	return id
+		&& kind === "question"
+		&& question
+		&& question.reviewedRevision === revisionOf(document.parsed.body)
+		&& id === questionId(question.item, question.request, question.reviewedRevision, question.source)
+		? { context: document.parsed.body, id, question }
+		: undefined;
+}
+export function responseFrom(document: MetadataDocument): RecordedResponse | undefined {
+	const { id, kind, response } = document.parsed.fields;
+	return id && kind === "response" && response ? { body: document.parsed.body, id, response } : undefined;
+}
+export function responsesFor(documents: readonly MetadataDocument[], question: Question): Reading {
+	const responses = documents.flatMap((document) => {
+		const record = responseFrom(document);
+		return record?.response.question === question.id && record.response.reviewedRevision === question.question.reviewedRevision ? [record] : [];
+	});
+	responses.sort((a, b) => a.response.recordedAt - b.response.recordedAt || a.id.localeCompare(b.id));
+	return { question, responses };
+}
+
+export function matchesResponse(record: RecordedResponse, input: DraftInput) {
+	return (
+		record.body === input.body
+		&& JSON.stringify(record.response.answers) === JSON.stringify(input.answers)
+		&& record.response.supersedes === input.supersedes
+		&& record.response.author === input.author
+		&& record.response.type === input.type
+		&& record.response.question === input.question
+	);
+}
+
+export function malformedResponse(document: MetadataDocument) {
+	const fields = document.parsed.fields;
+	return (
+		(fields.kind === "response" && !(fields.id && fields.response))
+		|| (document.file.startsWith("responses/") && document.parsed.diagnostics.some((problem) => problem.field === undefined))
+	);
+}

package/src/server/responses/registerQuestion.ts

@@ -0,0 +1,57 @@
+import { Clock, Effect } from "effect";
+import { Conflict, Forbidden, PreconditionFailed, type ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { Question } from "#browser/responses/schema.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import type { locate as locateQuestion } from "./locate.ts";
+import { publish } from "./publish.ts";
+import type { readResponses } from "./read.ts";
+import { questionMarkdown } from "./records.ts";
+import type { ResponseOptions } from "./service.ts";
+
+const HOURS_48 = 48 * 60 * 60 * 1000;
+export function registerQuestion(
+	options: ResponseOptions,
+	snapshot: Effect.Effect<Snapshot, ServiceUnavailable>,
+	locate: ReturnType<typeof locateQuestion>,
+	read: ReturnType<typeof readResponses>,
+) {
+	return Effect.fn("WorkBoard.registerQuestion")(function* (input: { readonly item: string; readonly request: string; readonly revision: string }) {
+		if (!options.enabled) {
+			return yield* Effect.fail(new Forbidden({ message: "Start with --responses to explicitly enable local question/response writes." }));
+		}
+		const preview = yield* locate(input.item, input.request);
+		if (preview.reviewedRevision !== input.revision) {
+			return yield* Effect.fail(new PreconditionFailed({ message: "Source changed since review. Read it again before registering this question." }));
+		}
+		const data = yield* snapshot;
+		const matches = data.model.ids.get(preview.id);
+		if (matches?.length) {
+			if (matches.length !== 1 || matches[0]?.file !== `responses/${preview.id}.md`) {
+				return yield* Effect.fail(
+					new Conflict({ message: "The registered identity moved or is duplicated. Read the existing record instead of retrying a write." }),
+				);
+			}
+			const saved = (yield* read(preview.id)).question;
+			yield* publish(options.root, options.changes.realRoot, saved.id, questionMarkdown(saved));
+			return saved;
+		}
+		const now = yield* Clock.currentTimeMillis;
+		const question: Question = {
+			context: preview.context,
+			id: preview.id,
+			question: {
+				deadline: now + HOURS_48,
+				item: preview.item,
+				reason: preview.reason,
+				registeredAt: now,
+				request: preview.request,
+				reviewedRevision: preview.reviewedRevision,
+				source: preview.source,
+			},
+		};
+		yield* publish(options.root, options.changes.realRoot, question.id, questionMarkdown(question)).pipe(
+			Effect.ensuring(options.changes.refresh ?? Effect.void),
+		);
+		return question;
+	});
+}