@shivaedev/work-board 0.7.2 → 0.8.0

package/src/metadata/problems.ts

@@ -27,6 +27,8 @@ function criterionProblems(document: MetadataDocument): readonly Diagnostic[] {
 function referenceProblems(document: MetadataDocument, ids: ReadonlyMap<string, readonly MetadataDocument[]>): readonly Diagnostic[] {
 	const { fields, lines } = document.parsed;
 	const references = [
+		...(fields.question ? [{ field: "question", key: "question.item", target: fields.question.item }] : []),
+		...(fields.response ? [{ field: "response", key: "response.question", target: fields.response.question }] : []),
 		...(fields.attention?.flatMap((request, index) =>
 			request.unblocks.map((target, targetIndex) => ({ field: "attention", key: `attention.${index}.unblocks.${targetIndex}`, target })),
 		) ?? []),

package/src/metadata/schema.ts

@@ -1,6 +1,8 @@
 import { Schema } from "effect";
+import { QuestionRecord, ResponseRecord } from "#browser/responses/schema.ts";
+import { Identity as SourceIdentity } from "#path/Identity.ts";
 
-export const Identity = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*$/u));
+export const Identity = SourceIdentity;
 export const Reference = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*(?:#[a-zA-Z\d][a-zA-Z\d._-]*)?$/u));
 const Text = Schema.String.check(Schema.isPattern(/\S/u));
 const Attention = Schema.Struct({
@@ -36,10 +38,12 @@ export const Metadata = Schema.Struct({
 	evidence: Schema.optional(Schema.Array(Evidence)),
 	id: Schema.optional(Identity),
 	items: Schema.optional(Schema.Array(Identity)),
-	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board"])),
+	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board", "question", "response"])),
 	nextAction: Schema.optional(Text),
 	owner: Schema.optional(Text),
+	question: Schema.optional(QuestionRecord),
 	relationships: Schema.optional(Schema.Array(Relationship)),
+	response: Schema.optional(ResponseRecord),
 	status: Schema.optional(Text),
 }).pipe(Schema.encodeKeys({ nextAction: "next_action" }));
 export type Metadata = typeof Metadata.Type;

package/src/page/attentionDetails.ts

@@ -1,4 +1,5 @@
 import { attentionSource } from "#attention/requests.ts";
+import { identityUrl } from "#metadata/links.ts";
 import type { MetadataModel } from "#metadata/model.ts";
 import type { ParsedMetadata } from "#metadata/parse.ts";
 import { escapeHtml } from "./escape.ts";
@@ -12,7 +13,7 @@ export function attentionDetails(parsed: ParsedMetadata, file: string, model: Me
 	return `<h3>Recorded attention requests</h3><p>Open/closed is source state. Closing a request does not establish acceptance or record an answer.</p><ul>${requests
 		.map(
 			(request, index) =>
-				`<li id="${attentionSource({ file, parsed }, index)}" tabindex="-1"><b>${escapeHtml(request.kind)} · ${escapeHtml(request.id)} · ${escapeHtml(request.state)}</b><p>${escapeHtml(request.reason)}</p><p>Response needed from: ${request.responseFrom.map(escapeHtml).join(", ")}</p><p>Recorded to unblock: ${request.unblocks.map((target) => referenceHtml(target, target, model)).join(", ")}</p><p>Source: ${escapeHtml(file)}:${parsed.lines[`attention.${index}`] ?? parsed.lines.attention ?? 2}</p></li>`,
+				`<li id="${attentionSource({ file, parsed }, index)}" tabindex="-1"><b>${escapeHtml(request.kind)} · ${escapeHtml(request.id)} · ${escapeHtml(request.state)}</b><p>${escapeHtml(request.reason)}</p><p>Response needed from: ${request.responseFrom.map(escapeHtml).join(", ")}</p><p>Recorded to unblock: ${request.unblocks.map((target) => referenceHtml(target, target, model)).join(", ")}</p><p><a href="/_board/respond?item=${encodeURIComponent(parsed.fields.id ?? "")}&amp;request=${encodeURIComponent(request.id)}">Respond to this request</a> · <a href="${identityUrl(parsed.fields.id ?? "")}">Reviewed item</a></p><p>Source: ${escapeHtml(file)}:${parsed.lines[`attention.${index}`] ?? parsed.lines.attention ?? 2}</p></li>`,
 		)
 		.join("")}</ul>`;
 }

package/src/page/metadataDetails.ts

@@ -18,6 +18,12 @@ export function metadataDetails(parsed: ParsedMetadata, file: string, model: Met
 			? `<h3>Declared board membership</h3><ul>${fields.items.map((id) => `<li>${referenceHtml(id, id, model)}</li>`).join("")}</ul>`
 			: "",
 
+		fields.question
+			? `<h3>Reviewed question</h3><p>${referenceHtml(fields.question.item, fields.question.item, model)} / ${escapeHtml(fields.question.request)} · ${escapeHtml(fields.question.reason)}</p><p>Reviewed SHA-256: <code>${fields.question.reviewedRevision}</code>. Registered: ${new Date(fields.question.registeredAt).toISOString()}. Unanswered deadline: ${new Date(fields.question.deadline).toISOString()}.</p>`
+			: "",
+		fields.response
+			? `<h3>Recorded response</h3><p>${referenceHtml(fields.response.question, fields.response.question, model)} · ${escapeHtml(fields.response.author)} · ${escapeHtml(fields.response.type)}</p><p>Reviewed SHA-256: <code>${fields.response.reviewedRevision}</code>. This is authored feedback, not verified acceptance.</p>`
+			: "",
 		criteriaEvidence(parsed, model),
 		attentionDetails(parsed, file, model),
 		recordedEvidence(parsed, file, model),

package/src/page/navigationScript.ts

@@ -88,7 +88,7 @@ document.addEventListener("click", (event) => {
   const link = event.target.closest?.("a[href]");
   if (!link || event.defaultPrevented || event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey || link.hasAttribute("download") || (link.target && link.target !== "_self")) return;
   const target = new URL(link.href, location.href);
-  if (target.origin !== location.origin || !(target.pathname === "/" || (target.pathname === "/_board/start" || target.pathname === "/_board/changes" || target.pathname === "/_board/overview" || target.pathname === "/_board/work" || target.pathname.startsWith("/_board/item/")) || /\\.md$/i.test(target.pathname))) return;
+  if (target.origin !== location.origin || !(target.pathname === "/" || (target.pathname === "/_board/respond" || target.pathname === "/_board/start" || target.pathname === "/_board/changes" || target.pathname === "/_board/overview" || target.pathname === "/_board/work" || target.pathname.startsWith("/_board/item/")) || /\\.md$/i.test(target.pathname))) return;
   event.preventDefault();
   navigate(target);
 });

package/src/page/shell.ts

@@ -17,7 +17,7 @@ export const shell = (
 	workspace: string,
 	board: boolean,
 	identity?: string,
-	view: boolean | "overview" | "changes" | "start" = false,
+	view: boolean | "overview" | "changes" | "start" | "response" = false,
 ): string =>
 	[
 		`<!doctype html><html lang="en" data-workspace="${escapeHtml(workspace)}"><head><meta charset="utf-8">`,

package/src/page/style.ts

@@ -96,4 +96,5 @@ export const style =
 	+ workStyle()
 	+ attentionStyle()
 	+ visualStyles
-	+ documents;
+	+ documents
+	+ ".response-panel { max-width: 850px; margin: auto; padding: 1.5rem; } .response-panel form { display: grid; gap: 1rem; } .response-panel label { display: grid; gap: .5rem; } .response-panel input, .response-panel textarea, .response-panel select { width: 100%; box-sizing: border-box; font: inherit; background: var(--surface); color: inherit; padding: .75rem; border: 1px solid var(--border); } .response-panel pre, .response-panel code { white-space: pre-wrap; overflow-wrap: anywhere; }";

package/src/page/swap.ts

@@ -18,6 +18,9 @@ export const remember = (element) => {
 
 const normalized = (element) => {
   const copy = element.cloneNode(true);
+  for (const form of [copy, ...copy.querySelectorAll("#response-form")]) {
+    if (form.id === "response-form") { form.replaceChildren(); delete form.dataset.bound; }
+  }
   for (const tool of copy.querySelectorAll("[data-visual-tools], [data-image-error], [data-diagram-error]")) tool.remove();
   for (const node of [copy, ...copy.querySelectorAll("*")]) {
     node.removeAttribute("data-live-change");

package/src/path/Identity.ts

@@ -0,0 +1,3 @@
+import { Schema } from "effect";
+
+export const Identity = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*$/u));

package/src/responses/agent-cli.ts

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import { agentRequest } from "./agent.ts";
+import { flags } from "./flags.ts";
+
+export async function runAgent(args: readonly string[]) {
+	const [action, request, ...options] = args;
+	if ((action !== "wait" && action !== "response" && action !== "question") || !request) {
+		throw new Error(
+			"Usage: work-board question <item>/<request> | wait <question-id> [--after <response-id>] | response <question-id> [--port 4747]",
+		);
+	}
+	const parsed = flags(options);
+	const controller = new AbortController();
+	function cancel() {
+		controller.abort();
+	}
+	process.once("SIGINT", cancel);
+	process.once("SIGTERM", cancel);
+	try {
+		const result = await Effect.runPromise(
+			agentRequest(action, { ...parsed, request }, (text) => process.stderr.write(`${text}\n`)).pipe(Effect.result),
+			{ signal: controller.signal },
+		);
+		if (result._tag === "Failure") {
+			if (result.failure instanceof Error && "code" in result.failure && result.failure.code === "Unanswered") {
+				process.exitCode = 2;
+			}
+			throw result.failure;
+		}
+		process.stdout.write(`${JSON.stringify(result.success)}\n`);
+	} finally {
+		process.removeListener("SIGINT", cancel);
+		process.removeListener("SIGTERM", cancel);
+	}
+}

package/src/responses/agent.ts

@@ -0,0 +1,59 @@
+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/unstable/rpc/RpcClient";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+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 Error("Use a loopback Work Board URL, such as http://127.0.0.1:4747.");
+	}
+	return parsed.origin;
+}
+export function agentRequest(action: "question" | "response" | "wait", options: AgentOptions, diagnostic: (text: string) => void = () => undefined) {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			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 Error("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 Error("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);
+		}),
+	).pipe(Effect.provide(protocol(validate(options.url))));
+}

package/src/responses/await.ts

@@ -0,0 +1,21 @@
+import { Clock, Effect } from "effect";
+import { type Reading, ResponseFailed } from "#browser/responses/schema.ts";
+import { outcome } from "./outcome.ts";
+
+export function awaitResponse(read: (id: string) => Effect.Effect<Reading, ResponseFailed>) {
+	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 ResponseFailed({ code: "Missing", 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/responses/flags.ts

@@ -0,0 +1,22 @@
+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 Error("Use --port, --url, --revision or --after, each with a value.");
+		}
+		if (values.has(name)) {
+			throw new Error(`Repeated option ${name}`);
+		}
+		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 Error("Invalid port.");
+	}
+	if (values.has("--url") && values.has("--port")) {
+		throw new Error("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/responses/locate.ts

@@ -0,0 +1,55 @@
+import { Effect, type FileSystem } from "effect";
+import { attentionRequests } from "#attention/requests.ts";
+import { type QuestionPreview, ResponseFailed } from "#browser/responses/schema.ts";
+import { markdownPath } from "#files/markdownPath.ts";
+import { metadataModel } from "#metadata/model.ts";
+import { metadataParse } from "#metadata/parse.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { questionId, revisionOf } from "./records.ts";
+
+function reject(code: ResponseFailed["code"], message: string) {
+	return Effect.fail(new ResponseFailed({ code, message }));
+}
+export function locate(root: string, realRoot: string, snapshot: Effect.Effect<Snapshot, ResponseFailed>, fs: FileSystem.FileSystem) {
+	return Effect.fn("WorkBoard.locate")(function* (item: string, request: string) {
+		const data = yield* snapshot;
+		const entry = attentionRequests(data).entries.find((candidate) => candidate.itemId === item && candidate.request.id === request);
+		if (!entry) {
+			return yield* reject("Missing", "The exact open attention request is missing, ambiguous or unavailable.");
+		}
+		const real = yield* markdownPath(root, realRoot, entry.document.file);
+		if (!real) {
+			return yield* reject("Missing", "The reviewed source moved or disappeared.");
+		}
+		const source = yield* fs.readFileString(real).pipe(Effect.catch(() => reject("Unavailable", "The source could not be read.")));
+		if (new TextEncoder().encode(source).length > 256 * 1024) {
+			return yield* reject("Unsupported", "Question context is limited to 256 KiB; use a focused source document.");
+		}
+		const parsed = metadataParse(source);
+		if (
+			parsed.fields.id !== item
+			|| parsed.fields.attention?.filter((candidate) => candidate.id === request && candidate.state === "open").length !== 1
+		) {
+			return yield* reject("Stale", "The source request changed. Re-read the question before proceeding.");
+		}
+		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 = attentionRequests({ ...data, documents, model }).entries.find(
+			(candidate) => candidate.itemId === item && candidate.request.id === request,
+		)?.request;
+		if (!fresh) {
+			return yield* reject("Stale", "The current request or its references are invalid. Review the source diagnostics before registering it.");
+		}
+		const revision = revisionOf(source);
+		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/responses/outcome.ts

@@ -0,0 +1,15 @@
+import type { Reading } from "#browser/responses/schema.ts";
+
+export function outcome(reading: Reading, after: string | undefined, now: number) {
+	const at = after === undefined ? -1 : reading.responses.findIndex((candidate) => candidate.id === after);
+	if (after !== undefined && at < 0) {
+		return { kind: "missing_cursor" } as const;
+	}
+	const response = reading.responses[at + 1];
+	if (response) {
+		return { kind: "response", question: reading.question, response } as const;
+	}
+	return now >= reading.question.question.deadline
+		? ({ kind: "unanswered", question: reading.question } as const)
+		: ({ kind: "pending", question: reading.question } as const);
+}

package/src/responses/page.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { fileUrl } from "#files/url.ts";
+import { respond } from "#http/respond.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { responseService } from "./service.ts";
+
+export function responsePage(
+	service: Effect.Success<ReturnType<typeof responseService>>,
+	changes: Changes,
+	home: string | undefined,
+	enabled: boolean,
+) {
+	return Effect.fn("WorkBoard.responsePage")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const params = new URL(request.url, "http://127.0.0.1").searchParams;
+		const item = params.get("item") ?? "";
+		const requestId = params.get("request") ?? "";
+		const files = yield* changes.files;
+		function layout(body: string, status = 200) {
+			return respond(shell("Respond", navHtml(files, "", home), body, changes.realRoot, false, undefined, "response"), "text/html", status);
+		}
+		return yield* service.locate(item, requestId).pipe(
+			Effect.flatMap((question) =>
+				Effect.map(
+					service
+						.read(question.id)
+						.pipe(Effect.catch((error) => (error.code === "Missing" ? Effect.succeed({ responses: [] }) : Effect.fail(error)))),
+					(recorded) => {
+						const q = question;
+						const body = `<section class="response-panel"><h1>Respond to ${escapeHtml(item)} / ${escapeHtml(requestId)}</h1><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>Saved replies are authored feedback. They do not close the request or establish acceptance.</p><details><summary>Exact source being reviewed</summary><pre>${escapeHtml(question.context)}</pre></details><form id="response-form" data-question="${question.id}" data-writable="${enabled}" data-item="${escapeHtml(item)}" data-request="${escapeHtml(requestId)}" data-revision="${q.reviewedRevision}"><label>Local author label <input name="author" maxlength="200" required></label><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><label>Your response <textarea name="body" rows="8" maxlength="32768" required></textarea></label><p>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><section id="response-history"><h2>Recorded responses</h2>${recorded.responses.map((record) => `<article><p><a href="/responses/${record.id}.md">${escapeHtml(record.response.author)} · ${escapeHtml(record.response.type)}</a></p><pre>${escapeHtml(record.body)}</pre></article>`).join("") || "<p>No response is recorded for this source revision.</p>"}</section></section>`;
+						return layout(body);
+					},
+				),
+			),
+			Effect.catch((error) => Effect.succeed(layout(`<h1>Response unavailable</h1><p>${escapeHtml(error.message)}</p>`, 409))),
+		);
+	});
+}

package/src/responses/publish.ts

@@ -0,0 +1,53 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath } from "node:fs/promises";
+import { Effect } from "effect";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import { publishIn } from "./publishIn.ts";
+
+function failure(cause: unknown): ResponseFailed {
+	return cause instanceof ResponseFailed
+		? cause
+		: new ResponseFailed({
+				code: "Unavailable",
+				message: "The response could not be recorded. Keep the draft and retry after checking local filesystem access.",
+			});
+}
+export function publish(root: string, realRoot: string, id: string, content: string) {
+	return Effect.tryPromise({
+		catch: failure,
+		try: async () => {
+			if (/^[a-zA-Z\d][a-zA-Z\d._-]*$/u.exec(id) === null) {
+				throw new ResponseFailed({ code: "Conflict", message: "Invalid response identity." });
+			}
+			if (process.platform !== "linux") {
+				throw new ResponseFailed({
+					code: "Unsupported",
+					message: "Safe response publication currently requires Linux directory descriptors. Reading remains available.",
+				});
+			}
+			const directory = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+			try {
+				const base = `/proc/self/fd/${directory.fd}`;
+				if ((await realpath(base)) !== realRoot || (await realpath(root)) !== realRoot) {
+					throw new ResponseFailed({ code: "Conflict", message: "The workspace root changed. Restart against the intended root." });
+				}
+				try {
+					await mkdir(`${base}/responses`);
+				} catch (cause) {
+					if (!(cause instanceof Error && "code" in cause && cause.code === "EEXIST")) {
+						throw cause;
+					}
+				}
+				await directory.sync();
+				const target = await open(`${base}/responses`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+				try {
+					await publishIn(target, root, realRoot, id, content);
+				} finally {
+					await target.close();
+				}
+			} finally {
+				await directory.close();
+			}
+		},
+	});
+}

package/src/responses/publishIn.ts

@@ -0,0 +1,64 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { type FileHandle, link, open, readFile, realpath, unlink } from "node:fs/promises";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+
+function uncertain(cause: unknown) {
+	return new ResponseFailed({ cause, code: "Uncertain", message: "Publication may have completed. Re-read the response identity before retrying." });
+}
+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);
+	try {
+		if ((await readFile(existing, "utf8")) !== content) {
+			throw new ResponseFailed({ code: "Conflict", message: "This identity already records different content; no file was replaced." });
+		}
+	} finally {
+		await existing.close();
+	}
+	return false;
+}
+export async function publishIn(target: FileHandle, root: string, realRoot: string, id: string, content: string) {
+	const folder = `/proc/self/fd/${target.fd}`;
+	const expected = `${realRoot}/responses`;
+	async function validate() {
+		if ((await realpath(folder)) !== expected || (await realpath(root)) !== realRoot) {
+			throw new ResponseFailed({ code: "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) {
+		if (published) {
+			throw uncertain(cause);
+		}
+		throw cause;
+	} finally {
+		await unlink(temporary).catch(() => undefined);
+	}
+}

package/src/responses/read.ts

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import type { MetadataDocument } from "#metadata/model.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { malformedResponse, questionFrom, responsesFor } from "./records.ts";
+
+function reject(code: ResponseFailed["code"], message: string) {
+	return Effect.fail(new ResponseFailed({ code, message }));
+}
+const registeredQuestion = Effect.fn("WorkBoard.registeredQuestion")(function* (matches: readonly MetadataDocument[] | undefined) {
+	if (!matches?.length) {
+		return yield* reject("Missing", "The registered question is missing.");
+	}
+	if (matches.length !== 1) {
+		return yield* reject("Conflict", "The registered question identity is ambiguous; response history is unknown.");
+	}
+	const question = matches[0] && questionFrom(matches[0]);
+	if (!question) {
+		return yield* reject("Conflict", "This identity is not a valid registered question; response history is unknown.");
+	}
+	return question;
+});
+export function readResponses(snapshot: Effect.Effect<Snapshot, ResponseFailed>) {
+	return Effect.fn("WorkBoard.read")(function* (id: string) {
+		const data = yield* snapshot;
+		if (data.unavailable.length > 0) {
+			return yield* reject("Unavailable", "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* reject("Unsupported", "The registered context exceeds the 256 KiB limit.");
+		}
+		if (data.documents.some(malformedResponse)) {
+			return yield* reject("Unavailable", "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* reject("Unsupported", "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* reject("Conflict", "A response identity is duplicated; no answer is selected.");
+		}
+		return result;
+	});
+}

package/src/responses/records.ts

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { stringify } from "yaml";
+import type { DraftInput, Question, Reading, RecordedResponse } from "#browser/responses/schema.ts";
+import type { MetadataDocument } from "#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
+		&& 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);
+}

package/src/responses/retry.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { type DraftInput, type RecordedResponse, ResponseFailed } from "#browser/responses/schema.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { publish } from "./publish.ts";
+import { matchesResponse, responseMarkdown } from "./records.ts";
+import type { ResponseOptions } from "./service.ts";
+
+export const retryResponse = Effect.fn("WorkBoard.retryResponse")(function* (
+	existing: RecordedResponse,
+	input: DraftInput,
+	snapshot: Effect.Effect<Snapshot, ResponseFailed>,
+	options: ResponseOptions,
+) {
+	if (!matchesResponse(existing, input)) {
+		return yield* Effect.fail(new ResponseFailed({ code: "Conflict", message: "The response identity already records different content." }));
+	}
+	if ((yield* snapshot).model.ids.get(input.id)?.[0]?.file !== `responses/${input.id}.md`) {
+		return yield* Effect.fail(
+			new ResponseFailed({ code: "Conflict", message: "The saved response moved. Read its existing record instead of retrying a write." }),
+		);
+	}
+	yield* publish(options.root, options.changes.realRoot, existing.id, responseMarkdown(existing));
+});