@shivaedev/work-board 0.11.0 → 0.13.0

package/src/server/responses/agent.ts

@@ -0,0 +1,74 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as RpcClient from "effect/rpc/RpcClient";
+import * as RpcSerialization from "effect/rpc/RpcSerialization";
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+import { responseContract } from "#rpc/responseContract.ts";
+import { waitForResponse } from "./waitFor.ts";
+
+export interface AgentOptions {
+	readonly after?: string | undefined;
+	readonly request: string;
+	readonly revision?: string | undefined;
+	readonly url: string;
+}
+function protocol(url: string) {
+	return RpcClient.layerProtocolHttp({ url: `${url}/_board/rpc` }).pipe(Layer.provide([NodeHttpClient.layerNodeHttp, RpcSerialization.layerNdjson]));
+}
+function validate(url: string) {
+	const parsed = new URL(url);
+	if (
+		parsed.protocol !== "http:"
+		|| !["127.0.0.1", "localhost", "[::1]"].includes(parsed.hostname)
+		|| parsed.username
+		|| parsed.password
+		|| parsed.pathname !== "/"
+		|| parsed.search
+		|| parsed.hash
+	) {
+		throw new BadRequest({ message: "Use a loopback Work Board URL, such as http://127.0.0.1:4747." });
+	}
+	return parsed.origin;
+}
+const requestFrom = Effect.fn("WorkBoard.requestFrom")(function* (
+	action: "question" | "response" | "wait",
+	options: AgentOptions,
+	diagnostic: (text: string) => void,
+) {
+	const client = yield* RpcClient.make(responseContract, { flatten: true });
+	const [item, request, extra] = options.request.split("/");
+	if (action === "question") {
+		if (!(item && request) || extra) {
+			return yield* Effect.fail(new BadRequest({ message: "Use question <item>/<request>." }));
+		}
+		return yield* client("work-board.question", { item, request });
+	}
+	let id = options.request;
+	if (request !== undefined) {
+		if (action !== "wait" || !item || !request || extra || !options.revision) {
+			return yield* Effect.fail(
+				new BadRequest({ message: "Use wait <item>/<request> --revision <reviewed SHA-256>, or wait <registered-question-id>." }),
+			);
+		}
+		const question = yield* client("work-board.registerQuestion", { item, request, revision: options.revision });
+		id = question.id;
+		diagnostic(`Registered ${id}; reattach with work-board wait ${id}. Deadline: ${new Date(question.question.deadline).toISOString()}`);
+	}
+	if (action === "response") {
+		return yield* client("work-board.responses", { question: id });
+	}
+	return yield* waitForResponse(() => client("work-board.awaitResponse", { after: options.after, question: id }), diagnostic);
+});
+
+export const agentRequest = Effect.fn("WorkBoard.agentRequest")(function* (
+	action: "question" | "response" | "wait",
+	options: AgentOptions,
+	diagnostic: (text: string) => void = () => undefined,
+) {
+	const url = yield* Effect.try({
+		catch: () => new BadRequest({ message: "Use a loopback Work Board URL, such as http://127.0.0.1:4747." }),
+		try: () => validate(options.url),
+	});
+	return yield* Effect.scoped(requestFrom(action, options, diagnostic)).pipe(Effect.provide(protocol(url)));
+});

package/src/server/responses/authoredQuestionHtml.ts

@@ -0,0 +1,46 @@
+import { Effect, type FileSystem, type Path } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { QuestionPreview } from "#browser/responses/schema.ts";
+import type { RenderFailed } from "#render/failed.ts";
+import { openItem } from "#server/attention/inbox.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import type { Highlighter } from "#server/render/Highlighter.ts";
+import { composerHtml } from "./composerHtml.ts";
+import { historyHtml } from "./historyHtml.ts";
+import { questionId, revisionOf } from "./records.ts";
+import { Responses } from "./service.ts";
+
+export const authoredQuestionHtml = Effect.fn("WorkBoard.authoredQuestionHtml")(function* (
+	document: MetadataDocument,
+	source: string,
+	enabled: boolean,
+): Effect.fn.Return<string, RenderFailed, Highlighter | FileSystem.FileSystem | Path.Path | Responses> {
+	const service = yield* Responses;
+	const item = document.parsed.fields.id ?? "";
+	const revision = revisionOf(source);
+	const preview: QuestionPreview = {
+		context: source,
+		id: questionId(item, "answer", revision, document.file),
+		item,
+		reason: document.parsed.fields.nextAction ?? "A question needs your answer",
+		request: "answer",
+		reviewedRevision: revision,
+		source: document.file,
+	};
+	const records = yield* service.history(preview).pipe(Effect.result);
+	const history =
+		records._tag === "Success"
+			? yield* historyHtml(preview, records.success)
+			: '<p role="status">Recorded responses are unavailable. Check the workspace source issues and retry.</p>';
+	if (!openItem(document)) {
+		return `<section class="response-panel"><h2>Question closed</h2><p role="status">This question is closed. Recorded answers remain below.</p>${history}</section>`;
+	}
+	return yield* service.locate(item, "answer").pipe(
+		Effect.flatMap((question) => (records._tag === "Success" ? composerHtml(question, records.success, enabled) : Effect.succeed(history))),
+		Effect.catch((error) =>
+			Effect.succeed(
+				`<section class="response-panel"><h2>Answer unavailable</h2><p role="status">${escapeHtml(error.message)}</p>${history}</section>`,
+			),
+		),
+	);
+});

package/src/server/responses/await.ts

@@ -0,0 +1,23 @@
+import { Clock, Effect } from "effect";
+import { NotFound } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { Reading } from "#browser/responses/schema.ts";
+import type { ResponseRejection } from "#rpc/rejections.ts";
+import { outcome } from "./outcome.ts";
+
+export function awaitResponse(read: (id: string) => Effect.Effect<Reading, ResponseRejection>) {
+	return Effect.fn("WorkBoard.awaitResponse")(function* (input: { readonly question: string; readonly after?: string | undefined }) {
+		const lease = (yield* Clock.currentTimeMillis) + 30_000;
+		while (true) {
+			const result = yield* read(input.question);
+			const now = yield* Clock.currentTimeMillis;
+			const state = outcome(result, input.after, now);
+			if (state.kind === "missing_cursor") {
+				return yield* Effect.fail(new NotFound({ message: "The next-response cursor is not recorded for this question." }));
+			}
+			if (state.kind !== "pending" || now >= lease) {
+				return { expired: state.kind === "unanswered", question: result.question, response: state.kind === "response" ? state.response : undefined };
+			}
+			yield* Effect.sleep("1 second");
+		}
+	});
+}

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 seven days after the last edit, with a 256 KiB limit per draft. 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 draft</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/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;
+});