@shivaedev/work-board 0.9.1 → 0.11.0

package/src/responses/publish.ts

@@ -9,20 +9,20 @@ function failure(cause: unknown): ResponseFailed {
 		? cause
 		: new ResponseFailed({
 				code: "Unavailable",
-				message: "The response could not be recorded. Keep the draft and retry after checking local filesystem access.",
+				message: "The local record 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) {
+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 ResponseFailed({ code: "Conflict", message: "Invalid response identity." });
+				throw new ResponseFailed({ code: "Conflict", message: "Invalid record identity." });
 			}
 			if (process.platform !== "linux") {
 				throw new ResponseFailed({
 					code: "Unsupported",
-					message: "Safe response publication currently requires Linux directory descriptors. Reading remains available.",
+					message: "Local record publication currently requires Linux directory descriptors. Reading remains available.",
 				});
 			}
 			const directory = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
@@ -32,16 +32,16 @@ export function publish(root: string, realRoot: string, id: string, content: str
 					throw new ResponseFailed({ code: "Conflict", message: "The workspace root changed. Restart against the intended root." });
 				}
 				try {
-					await mkdir(`${base}/responses`);
+					await mkdir(`${base}/${namespace}`);
 				} 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);
+				const target = await open(`${base}/${namespace}`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
 				try {
-					await publishIn(target, root, realRoot, id, content);
+					await publishIn(target, root, realRoot, id, content, namespace);
 				} finally {
 					await target.close();
 				}

package/src/responses/publishIn.ts

@@ -4,7 +4,7 @@ import { type FileHandle, link, open, readFile, realpath, unlink } from "node:fs
 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." });
+	return new ResponseFailed({ cause, code: "Uncertain", message: "Publication may have completed. Re-read the record identity before retrying." });
 }
 function exists(cause: unknown) {
 	return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
@@ -28,9 +28,16 @@ async function linkOrReconcile(temporary: string, name: string, content: string)
 	}
 	return false;
 }
-export async function publishIn(target: FileHandle, root: string, realRoot: string, id: string, content: string) {
+export async function publishIn(
+	target: FileHandle,
+	root: string,
+	realRoot: string,
+	id: string,
+	content: string,
+	namespace: "responses" | "handoffs" = "responses",
+) {
 	const folder = `/proc/self/fd/${target.fd}`;
-	const expected = `${realRoot}/responses`;
+	const expected = `${realRoot}/${namespace}`;
 	async function validate() {
 		if ((await realpath(folder)) !== expected || (await realpath(root)) !== realRoot) {
 			throw new ResponseFailed({ code: "Conflict", message: "The write boundary changed." });

package/src/results/criteria.ts

@@ -0,0 +1,37 @@
+import { referenceTarget } from "#metadata/links.ts";
+import type { MetadataDocument, MetadataModel } from "#metadata/model.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { referenceHtml, sourceHtml, valueHtml } from "#page/metadataLinks.ts";
+
+function criterionRow(reference: string, text: string, result: MetadataDocument, model: MetadataModel): string {
+	if (!referenceTarget(reference, model)) {
+		return `<li>${escapeHtml(text)} — criterion identity is ambiguous; evidence association unavailable.</li>`;
+	}
+	const claims = result.parsed.fields.evidence?.filter((claim) => claim.criterion === reference) ?? [];
+	const evidence =
+		claims.length > 0
+			? `<p>${claims.length} recorded claim(s) in this result; not verified acceptance.</p><ul>${claims.map((claim) => `<li>${sourceHtml(claim.source, result.file, model)}<dl><dt>Checked Git revision (reported)</dt><dd>${valueHtml(claim.checkedRevision)}</dd><dt>Method</dt><dd>${valueHtml(claim.method)}</dd><dt>Outcome (reported)</dt><dd>${valueHtml(claim.outcome)}</dd><dt>Observed time</dt><dd>${valueHtml(claim.observedAt)}</dd></dl></li>`).join("")}</ul>`
+			: "<p>No recorded evidence in this result naming this criterion. Acceptance is not established.</p>";
+	return `<li>${referenceHtml(text, reference, model)}${evidence}</li>`;
+}
+function targetRow(target: string, result: MetadataDocument, model: MetadataModel): string {
+	const [id, criterion] = target.split("#");
+	const document = model.ids.get(id ?? "")?.[0];
+	if (!(document && referenceTarget(target, model))) {
+		return `<li>${referenceHtml(target, target, model)} — criteria unavailable.</li>`;
+	}
+	const criteria = (document.parsed.fields.criteria ?? []).filter((item) => !criterion || item.id === criterion);
+	const rows =
+		criteria.length > 0
+			? `<ul>${criteria.map((item) => criterionRow(`${id}#${item.id}`, item.text, result, model)).join("")}</ul>`
+			: "<p>No criteria declared in this source.</p>";
+	return `<li>${referenceHtml(target, target, model)} · source status: ${valueHtml(document.parsed.fields.status)}${rows}</li>`;
+}
+export function resultCriteria(result: MetadataDocument, model: MetadataModel): string {
+	const targets = new Set(result.parsed.fields.relationships?.map((link) => link.target));
+	if (result.parsed.fields.id) {
+		targets.add(result.parsed.fields.id);
+	}
+	const rows = [...targets].map((target) => targetRow(target, result, model));
+	return `<section id="result-criteria"><h2>Criteria and this result’s claims</h2><p>Only explicit relationships and criterion references are associated. Missing provenance stays missing. Git revisions are authored records; Work Board does not compare them with the current checkout. Evidence freshness is unknown.</p>${rows.length > 0 ? `<ul>${rows.join("")}</ul>` : "<p>No explicitly linked work or criteria.</p>"}<p>${escapeHtml(result.file)} does not change the linked work’s status.</p></section>`;
+}

package/src/results/feedback.ts

@@ -0,0 +1,44 @@
+import { Effect } from "effect";
+import { fileUrl } from "#files/url.ts";
+import type { MetadataDocument } from "#metadata/model.ts";
+import { escapeHtml } from "#page/escape.ts";
+import type { RenderFailed } from "#render/failed.ts";
+import type { Highlighter } from "#render/highlighter.ts";
+import { renderMarkdown } from "#render/markdown.ts";
+import { readResponses } from "#responses/read.ts";
+import { malformedResponse, questionFrom, revisionOf } from "#responses/records.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+
+export const resultFeedback = Effect.fn("WorkBoard.resultFeedback")(function* (
+	result: MetadataDocument,
+	data: Snapshot,
+): Effect.fn.Return<string, RenderFailed, Highlighter> {
+	const unknown =
+		data.unavailable.length > 0
+		|| data.documents.some((document) => malformedResponse(document) || (document.parsed.fields.kind === "question" && !questionFrom(document)));
+	const questions = data.documents.flatMap((document) => {
+		const question = questionFrom(document);
+		return question && question.question.item === result.parsed.fields.id ? [question] : [];
+	});
+	const read = readResponses(Effect.succeed(data));
+	const readings = yield* Effect.forEach(questions, (question) => Effect.result(read(question.id)));
+	if (unknown || readings.some((reading) => reading._tag === "Failure")) {
+		return '<section id="result-feedback"><h2>Recorded human feedback</h2><p role="status">Response history is unknown or ambiguous. Unreadable records do not establish that no feedback exists. Read the source files before relying on it.</p></section>';
+	}
+	const current = revisionOf((result.parsed.raw ?? "") + result.parsed.body);
+	const records = readings.flatMap((reading) =>
+		reading._tag === "Success" ? reading.success.responses.map((response) => ({ question: reading.success.question, response })) : [],
+	);
+	records.sort((a, b) => b.response.response.recordedAt - a.response.response.recordedAt || a.response.id.localeCompare(b.response.id));
+	const bodies = yield* Effect.forEach(records, ({ question, response }) =>
+		Effect.gen(function* () {
+			const matching = question.question.reviewedRevision === current && question.question.source === result.file;
+			const responseFile = data.model.ids.get(response.id)?.[0]?.file ?? `responses/${response.id}.md`;
+			const questionFile = data.model.ids.get(question.id)?.[0]?.file ?? `responses/${question.id}.md`;
+			const body = yield* renderMarkdown(response.body, { file: responseFile, safe: true });
+			const selected = response.response.answers?.map((answer) => `${answer.prompt}: ${answer.selected.join(", ") || "text only"}`).join("; ");
+			return `<article id="${escapeHtml(response.id)}"><h3>${escapeHtml(response.response.author)} · ${escapeHtml(response.response.type)}</h3><p><b>${matching ? "Feedback on this exact result revision" : "Earlier or moved result context — does not apply automatically to this revision"}</b></p><p>Reviewed source: ${escapeHtml(question.question.source)} · SHA-256 <code>${question.question.reviewedRevision}</code></p>${selected ? `<p>Recorded option IDs: ${escapeHtml(selected)}. Labels and reasoning are recorded below.</p>` : ""}${response.response.supersedes ? `<p>Explicitly supersedes <a href="${fileUrl(data.model.ids.get(response.response.supersedes)?.[0]?.file ?? `responses/${response.response.supersedes}.md`)}">${escapeHtml(response.response.supersedes)}</a>.</p>` : ""}${body}<p><a href="${fileUrl(responseFile)}">Response source</a> · <a href="${fileUrl(questionFile)}">Registered reviewed context</a></p><details><summary>Exact reviewed result source</summary><pre>${escapeHtml(question.context)}</pre></details></article>`;
+		}),
+	);
+	return `<section id="result-feedback"><h2>Recorded human feedback</h2><p>Human direction is pinned to its reviewed report. Option IDs and authored acceptance text are not a computed verified-acceptance state. Completing a run or receiving feedback does not change work status.</p>${bodies.join("") || "<p>No readable response is recorded for this result.</p>"}</section>`;
+});

package/src/results/page.ts

@@ -0,0 +1,58 @@
+import { Effect, type FileSystem, type Path, type PlatformError } from "effect";
+import type { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { fileUrl } from "#files/url.ts";
+import { respond } from "#http/respond.ts";
+import type { MetadataDocument } from "#metadata/model.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { metadataHtml } from "#page/metadata.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { Highlighter } from "#render/highlighter.ts";
+import { renderMarkdown } from "#render/markdown.ts";
+import { revisionOf } from "#responses/records.ts";
+import { resultCriteria } from "#results/criteria.ts";
+import { resultFeedback } from "#results/feedback.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+
+function reviewActions(result: MetadataDocument) {
+	const requests = result.parsed.fields.attention ?? [];
+	const actions = requests
+		.filter(
+			(attention) => attention.kind === "review" && attention.state === "open" && requests.filter((other) => other.id === attention.id).length === 1,
+		)
+		.map(
+			(attention) =>
+				`<li><a href="/_board/respond?item=${encodeURIComponent(result.parsed.fields.id ?? "")}&amp;request=${encodeURIComponent(attention.id)}">Review ${escapeHtml(attention.id)}</a> — ${escapeHtml(attention.reason)}</li>`,
+		);
+	return `<section id="result-actions"><h2>Respond to this report</h2>${actions.length > 0 ? `<ul>${actions.join("")}</ul>` : "<p>No unique open review request is declared. The agent can add an explicit attention review and Markdown question packet with ordinary file editing. Work Board does not infer one from status.</p>"}</section>`;
+}
+
+export function resultPage(index: Effect.Effect<Snapshot, unknown, FileSystem.FileSystem | Path.Path>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.resultPage")(function* (
+		request: HttpServerRequest.HttpServerRequest,
+	): Effect.fn.Return<HttpServerResponse.HttpServerResponse, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Highlighter> {
+		const item = new URL(request.url, "http://127.0.0.1").searchParams.get("item") ?? "";
+		const files = yield* changes.files;
+		function layout(body: string, status = 200) {
+			return respond(shell("Result review", navHtml(files, "", home), body, changes.realRoot, false, undefined, "result"), "text/html", status);
+		}
+		return yield* Effect.gen(function* () {
+			const data = yield* index;
+			const matches = data.model.ids.get(item);
+			const result = matches?.length === 1 ? matches[0] : undefined;
+			if (result?.parsed.fields.kind !== "result" || data.unavailable.length > 0) {
+				return layout(
+					'<h1>Result unavailable</h1><p role="status">Choose one uniquely identified, readable result. Missing or ambiguous work is not accepted.</p>',
+					409,
+				);
+			}
+			const report = yield* renderMarkdown(result.parsed.body, { file: result.file, safe: true });
+			const feedback = yield* resultFeedback(result, data);
+			const revision = revisionOf((result.parsed.raw ?? "") + result.parsed.body);
+			return layout(
+				`<section class="response-panel"><h1>Review returned result · ${escapeHtml(item)}</h1><p>Result status (source): <b>${escapeHtml(result.parsed.fields.status ?? "Not recorded")}</b>. This is a supplied claim, not an execution receipt or work acceptance.</p><p>Current report SHA-256: <code>${revision}</code> · <a href="${fileUrl(result.file)}">Read source</a></p>${metadataHtml(result.parsed, result.file, data.model)}${reviewActions(result)}${resultCriteria(result, data.model)}<section id="result-report"><h2>Report, evidence and limitations</h2>${report}</section>${feedback}</section>`,
+			);
+		}).pipe(Effect.catch((error) => Effect.succeed(layout(`<h1>Result review unavailable</h1><p>${escapeHtml(String(error))}</p>`, 409))));
+	});
+}

package/src/rpc/contract.ts

@@ -4,6 +4,7 @@ import { contract } from "@shivaedev/effect-contract/contract.ts";
 import { LiveHint } from "@shivaedev/effect-contract/live.ts";
 import { query } from "@shivaedev/effect-contract/operation.ts";
 import { HistoryInput, HistoryOutput } from "#history/schema.ts";
+import { handoffContract } from "#rpc/handoffContract.ts";
 import { responseContract } from "#rpc/responseContract.ts";
 import { index, navigation, watcher, workspace } from "./keys.ts";
 import { pageKeys } from "./pageKeys.ts";
@@ -19,7 +20,9 @@ const PageUrl = Schema.String.check(
 			const path = new URL(value, "http://127.0.0.1").pathname;
 			return (
 				path === "/"
-				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start", "/_board/respond"].includes(path)
+				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start", "/_board/respond", "/_board/handoff", "/_board/result"].includes(
+					path,
+				)
 				|| /^\/_board\/item\/[^/]+\/$/u.exec(path) !== null
 				|| /\.md$/iu.exec(path) !== null
 				|| "Expected a local reading URL"
@@ -60,4 +63,4 @@ const ReadWatcher = query("watcher", {
 });
 export const workContract = contract("work-board", { queries: [ReadPage, ReadNavigation, ReadSearch, ReadHistory, ReadWatcher] });
 export const Subscribe = Rpc.make("work-board.subscribe", { error: ReadFailed, stream: true, success: LiveHint });
-export const workRpcs = workContract.add(Subscribe).merge(responseContract);
+export const workRpcs = workContract.add(Subscribe).merge(responseContract).merge(handoffContract);

package/src/rpc/handoffContract.ts

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+import { contract } from "@shivaedev/effect-contract/contract.ts";
+import { command, query } from "@shivaedev/effect-contract/operation.ts";
+import { Handoff, HandoffInput, HandoffPreview, HandoffReading } from "#browser/handoffs/schema.ts";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import { index, workspace } from "#rpc/keys.ts";
+
+const locate = query("handoffSource", {
+	payload: { item: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: HandoffPreview,
+});
+const read = query("handoffs", {
+	payload: { item: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: HandoffReading,
+});
+const prepare = command("prepareHandoff", {
+	invalidates: () => [workspace.list, index.list],
+	payload: HandoffInput,
+	rejections: { ResponseFailed },
+	success: Handoff,
+});
+export const handoffContract = contract("work-board", { commands: [prepare], queries: [locate, read] });

package/src/rpc/server.ts

@@ -2,6 +2,7 @@ import { Clock, Effect, Layer, Ref } from "effect";
 import { HttpIncomingMessage, HttpServerResponse } from "effect/unstable/http";
 import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
 import type { Changes } from "#files/changes.ts";
+import type { handoffService } from "#handoffs/service.ts";
 import { MAX_BYTES } from "#history/limits.ts";
 import { historyResponse } from "#history/response.ts";
 import { HEADERS } from "#http/respond.ts";
@@ -14,15 +15,18 @@ import { hints } from "./hints.ts";
 
 export interface ServerOptions {
 	readonly changes: Changes;
+	readonly handoffs: Effect.Success<ReturnType<typeof handoffService>>;
 	readonly home: string | undefined;
 	readonly index: Effect.Effect<Snapshot, unknown>;
 	readonly page: (url: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, unknown>;
 	readonly responses: Effect.Success<ReturnType<typeof responseService>>;
 }
 
-export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home, index, page, responses }: ServerOptions) {
+export const server = Effect.fn("WorkBoard.server")(function* ({ changes, handoffs, home, index, page, responses }: ServerOptions) {
 	const handlers = workRpcs.toLayer({
 		"work-board.awaitResponse": responses.awaitResponse,
+		"work-board.handoffSource": ({ item }) => handoffs.locate(item),
+		"work-board.handoffs": ({ item }) => handoffs.read(item),
 		"work-board.history": ({ action, baseline }) =>
 			Effect.gen(function* () {
 				const now = yield* Clock.currentTimeMillis;
@@ -43,6 +47,7 @@ export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home,
 				}),
 				Effect.catch((error) => Effect.fail(error instanceof ReadFailed ? error : new ReadFailed({ operation: "page", status: 500 }))),
 			),
+		"work-board.prepareHandoff": handoffs.prepare,
 		"work-board.question": ({ item, request }) => responses.locate(item, request),
 		"work-board.recordResponse": responses.record,
 		"work-board.registerQuestion": responses.register,

package/src/serve-cli.ts

@@ -4,7 +4,7 @@ import { Effect, Layer, Option, Path } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { HOST, serveBoard } from "./serve.ts";
 
-const VERSION = "0.9.1";
+const VERSION = "0.11.0";
 
 const serve = Effect.fn("WorkBoard.serve")(function* (input: {
 	readonly dir: string;
@@ -26,7 +26,7 @@ const workBoard = Command.make(
 		port: Flag.integer("port").pipe(Flag.withDefault(4747), Flag.withDescription(`The port to listen on at ${HOST}`)),
 		responses: Flag.boolean("responses").pipe(
 			Flag.withDefault(false),
-			Flag.withDescription("Explicitly enable local durable question and response writes (Linux)"),
+			Flag.withDescription("Explicitly enable local durable question, response and handoff writes (Linux)"),
 		),
 	},
 	serve,