@shivaedev/work-fleet 0.0.0 → 0.1.1

package/src/board/publish.ts

@@ -0,0 +1,99 @@
+import { relative } from "node:path";
+import { Clock, Effect } from "effect";
+import { board as boardApi } from "@shivaedev/work-board/integration/board.ts";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import { decisionAnswer } from "#board/decisionAnswer.ts";
+import type { BoardDocument } from "#board/documents.ts";
+import { recordBoardSource } from "#board/readPass.ts";
+import type { BoardDecision } from "#board/schema.ts";
+import { BoardFailure, type BoardWork, type Decision } from "#policy.ts";
+
+const { publish, questionFrom, questionId, questionMarkdown, revisionOf } = responses;
+
+function quoted(text: string): string {
+	const fence = "~".repeat(Math.max(3, ...Array.from(text.matchAll(/~+/gu), (match) => match[0].length + 1)));
+	return `${fence}\n${text}\n${fence}`;
+}
+
+function linked(text: string): string {
+	if (!URL.canParse(text)) {
+		return quoted(text);
+	}
+	const url = new URL(text);
+	return url.protocol === "https:" || url.protocol === "http:" ? `<${url.href.replaceAll("<", "%3C").replaceAll(">", "%3E")}>` : quoted(text);
+}
+
+function decisionSource(itemId: string, work: BoardWork, input: Decision): string {
+	const metadata = {
+		attention: [
+			{
+				id: input.id,
+				kind: "decision",
+				managed: true,
+				reason: input.reason,
+				"response_from": [input.attentionOwner ?? "orchestrator"],
+				state: "open",
+				unblocks: [work.workId],
+			},
+		],
+		id: itemId,
+		kind: "decision",
+		relationships: [{ kind: "relates_to", target: work.workId }],
+	};
+	const answer = decisionAnswer(input);
+	return `---\n${JSON.stringify(metadata)}\n---\n# Fleet decision for ${work.workId}\n\n## Decision\n\n${quoted(input.reason)}\n\n## Recommendation\n\n${quoted(input.recommendation)}\n\n## Relevant links\n\n${input.links.map(linked).join("\n\n")}\n\n${answer}\n\n## Reviewed Board work\n\n${quoted(work.context)}\n`;
+}
+
+export function publishBoard(root: string, realRoot: string, documents: Effect.Effect<readonly BoardDocument[], BoardFailure>) {
+	return Effect.fn("FleetBoard.decision")(function* (work: BoardWork, input: Decision): Effect.fn.Return<BoardDecision, BoardFailure> {
+		const workSourcePath = relative(realRoot, work.sourcePath);
+		const itemId = `decision.${revisionOf(JSON.stringify([work.workId, work.revision, workSourcePath, input.id, input.reason, input.recommendation, input.links, ...(input.worker === undefined ? [] : [input.worker])]))}`;
+		const existing = input.published === undefined ? undefined : (yield* documents).find((document) => document.file === input.published?.sourcePath);
+		const context = existing?.parsed.fields.id === itemId ? existing.source : decisionSource(itemId, work, input);
+		const parsed = boardApi.metadataParse(context);
+		if (new TextEncoder().encode(context).length > 256 * 1024 || parsed.diagnostics.length > 0) {
+			return yield* Effect.fail(new BoardFailure({ message: "Fleet decision context exceeds Board limits or contains invalid attention metadata." }));
+		}
+		const sourcePath = `responses/${itemId}.md`;
+		const revision = revisionOf(context);
+		const id = questionId(itemId, input.id, revision, sourcePath);
+		const receipt = {
+			itemId,
+			questionId: id,
+			request: input.id,
+			revision,
+			sourcePath,
+			workId: work.workId,
+			workRevision: work.revision,
+			workSourcePath,
+		};
+		yield* publish(root, realRoot, itemId, context).pipe(
+			Effect.mapError(() => new BoardFailure({ message: "Fleet decision source could not be recorded on Board." })),
+		);
+		yield* recordBoardSource(realRoot, sourcePath, context, parsed);
+		const all = yield* documents;
+		if (all.some((document) => questionFrom(document)?.id === id)) {
+			return receipt;
+		}
+		const registeredAt = yield* Clock.currentTimeMillis;
+		const question = {
+			context,
+			id,
+			question: {
+				deadline: registeredAt + 48 * 60 * 60 * 1000,
+				item: itemId,
+				reason: input.reason,
+				registeredAt,
+				request: input.id,
+				reviewedRevision: revision,
+				source: sourcePath,
+			},
+		};
+		const questionSource = questionMarkdown(question);
+		yield* publish(root, realRoot, id, questionSource).pipe(
+			Effect.mapError(() => new BoardFailure({ message: "Fleet decision question could not be registered on Board." })),
+		);
+		yield* recordBoardSource(realRoot, `responses/${id}.md`, questionSource);
+		return receipt;
+	});
+}

package/src/board/publishReport.ts

@@ -0,0 +1,43 @@
+import { relative } from "node:path";
+import { Effect } from "effect";
+import { board } from "@shivaedev/work-board/integration/board.ts";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import { briefRevision } from "#board/briefRevision.ts";
+import type { BoardDocument } from "#board/documents.ts";
+import { recordBoardSource, workMetadata } from "#board/readPass.ts";
+import { reportContent } from "#board/reportContent.ts";
+import { reportIdentity } from "#board/reportIdentity.ts";
+import { workRevision } from "#board/workRevision.ts";
+import { BoardFailure, type BoardWork } from "#policy.ts";
+import type { SessionObservation } from "#session/schema.ts";
+
+const { metadataModel } = board;
+const { publish, revisionOf } = responses;
+
+export function publishReport(root: string, realRoot: string, documents: Effect.Effect<readonly BoardDocument[], BoardFailure>) {
+	return Effect.fn("FleetBoard.report")(function* (work: BoardWork, observation: SessionObservation) {
+		const all = yield* documents;
+		const matches = metadataModel(all).ids.get(work.workId);
+		const source = all.find((document) => document.file === relative(realRoot, work.sourcePath));
+		const parsed = yield* workMetadata(work);
+		if (
+			matches?.length !== 1
+			|| source?.parsed.fields.id !== work.workId
+			|| parsed.fields.id !== work.workId
+			|| parsed.diagnostics.length > 0
+			|| briefRevision(source.parsed) !== workRevision(work.revision, work.context)
+			|| workRevision(work.revision, work.context) !== briefRevision(parsed)
+			|| observation.execution !== "completed"
+			|| !observation.output.trim()
+		) {
+			return yield* Effect.fail(new BoardFailure({ message: "Report needs nonempty completed output and the exact current Board context." }));
+		}
+		const { itemId } = reportIdentity(work, observation.receipt);
+		const content = yield* reportContent(work, observation);
+		yield* publish(root, realRoot, itemId, content).pipe(
+			Effect.mapError(() => new BoardFailure({ message: "The worker report could not be recorded on Board; retry the same completed attempt." })),
+		);
+		yield* recordBoardSource(realRoot, `responses/${itemId}.md`, content);
+		return { itemId, receipt: observation.receipt, revision: revisionOf(content), sourcePath: `responses/${itemId}.md`, workRevision: work.revision };
+	});
+}

package/src/board/readDocument.ts

@@ -0,0 +1,33 @@
+import { Effect, FileSystem } from "effect";
+import { board as boardApi } from "@shivaedev/work-board/integration/board.ts";
+import { STATUS_MARKER } from "#board/statusMarkdown.ts";
+import { BoardFailure } from "#policy.ts";
+
+export const readDocument = Effect.fn("FleetBoard.readDocument")(function* (root: string, realRoot: string, file: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const real = yield* boardApi.markdownPath(root, realRoot, file);
+	if (!real) {
+		return yield* Effect.fail(new BoardFailure({ code: "incomplete-observation", message: `Board source is unavailable: ${file}` }));
+	}
+	const source = yield* fs
+		.readFileString(real)
+		.pipe(
+			Effect.mapError(
+				(error) => new BoardFailure({ code: "incomplete-observation", message: `Board source could not be read: ${file} (${error.message})` }),
+			),
+		);
+	if (file === "fleet/status.md" && source.startsWith(`${STATUS_MARKER}\n`)) {
+		return { document: undefined, problem: undefined };
+	}
+	const parsed = boardApi.metadataParse(source);
+	const diagnostics = parsed.diagnostics;
+	return {
+		document: { file, parsed, source },
+		problem:
+			diagnostics.length === 0
+				? undefined
+				: new BoardFailure({
+						message: `Board metadata is invalid: ${file} (${diagnostics.map((diagnostic) => `line ${diagnostic.line}: ${diagnostic.message}`).join("; ")})`,
+					}),
+	};
+});

package/src/board/readPass.ts

@@ -0,0 +1,115 @@
+import { join } from "node:path";
+import { Context, Effect, type FileSystem, type Path } from "effect";
+import type { MetadataModel, ParsedMetadata } from "@shivaedev/work-board/integration/board.ts";
+import { board as boardApi } from "@shivaedev/work-board/integration/board.ts";
+import type { BoardDocument } from "#board/documents.ts";
+import type { BoardFailure, BoardWork } from "#policy.ts";
+
+const { metadataModel } = boardApi;
+
+export class BoardSnapshot {
+	documents: readonly BoardDocument[];
+	model: MetadataModel;
+	files: ReadonlyMap<string, BoardDocument>;
+	readonly problems: Map<string, BoardFailure>;
+
+	constructor(documents: readonly BoardDocument[], problems: Map<string, BoardFailure> = new Map()) {
+		this.problems = problems;
+		this.documents = documents;
+		this.model = metadataModel(documents);
+		this.files = new Map(documents.map((document) => [document.file, document]));
+	}
+
+	record(document: BoardDocument) {
+		this.problems.delete(document.file);
+		this.documents = [...this.documents.filter((entry) => entry.file !== document.file), document];
+		this.model = metadataModel(this.documents);
+		this.files = new Map(this.documents.map((entry) => [entry.file, entry]));
+	}
+}
+
+type Read = Effect.Effect<BoardSnapshot, BoardFailure>;
+interface Pass {
+	active: boolean;
+	readonly publications: Set<Effect.Effect<void>>;
+	readonly reads: Map<string, Read>;
+}
+const ReadPass = Context.Reference<Pass | undefined>("@shivaedev/work-fleet/board/ReadPass", { defaultValue: () => undefined });
+
+export function withBoardReadPass<A, E, R>(effect: Effect.Effect<A, E, R>) {
+	return Effect.suspend(() => {
+		const pass: Pass = { active: true, publications: new Set(), reads: new Map() };
+		return effect.pipe(
+			Effect.provideService(ReadPass, pass),
+			Effect.ensuring(
+				Effect.gen(function* () {
+					pass.active = false;
+					for (const publication of pass.publications) {
+						yield* publication;
+					}
+				}),
+			),
+		);
+	});
+}
+
+export const inBoardReadPass = Effect.fnUntraced(function* <A, E, R>(effect: Effect.Effect<A, E, R>) {
+	return yield* (yield* ReadPass)?.active === true ? effect : withBoardReadPass(effect);
+});
+
+export const readSnapshot = Effect.fn("FleetBoard.readSnapshot")(function* (
+	realRoot: string,
+	read: Effect.Effect<BoardSnapshot, BoardFailure, FileSystem.FileSystem | Path.Path>,
+) {
+	const pass = yield* ReadPass;
+	if (pass?.active !== true) {
+		return yield* read;
+	}
+	let cached = pass.reads.get(realRoot);
+	if (cached === undefined) {
+		const services = yield* Effect.context<FileSystem.FileSystem | Path.Path>();
+		const next = yield* Effect.cached(read.pipe(Effect.provideContext(services)));
+		cached = pass.reads.get(realRoot) ?? next;
+		pass.reads.set(realRoot, cached);
+	}
+	return yield* cached;
+});
+
+export const recordBoardSource = Effect.fn("FleetBoard.recordBoardSource")(function* (
+	realRoot: string,
+	file: string,
+	source: string,
+	parsed?: ParsedMetadata,
+) {
+	const pass = yield* ReadPass;
+	const read = pass?.active === true ? pass.reads.get(realRoot) : undefined;
+	if (read !== undefined) {
+		const snapshot = yield* read;
+		const existing = snapshot.files.get(file);
+		if (existing?.source !== source) {
+			snapshot.record({ file, parsed: parsed ?? boardApi.metadataParse(source), source });
+		}
+	}
+});
+
+export const workMetadata = Effect.fn("FleetBoard.workMetadata")(function* (work: BoardWork): Effect.fn.Return<ParsedMetadata, BoardFailure> {
+	const pass = yield* ReadPass;
+	for (const [root, read] of pass?.active === true ? pass.reads : []) {
+		const snapshot = yield* read;
+		const matches = snapshot.model.ids.get(work.workId);
+		const document = matches?.length === 1 ? snapshot.files.get(matches[0]?.file ?? "") : undefined;
+		if (document?.source === work.context && join(root, document.file) === work.sourcePath) {
+			return document.parsed;
+		}
+	}
+	return boardApi.metadataParse(work.context);
+});
+
+export const publishAfterBoardPass = Effect.fn("FleetBoard.publishAfterBoardPass")(function* (publication: Effect.Effect<void>) {
+	const pass = yield* ReadPass;
+	if (pass?.active === true) {
+		pass.publications.add(publication);
+	} else {
+		yield* publication;
+	}
+});

package/src/board/reportContent.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { reportIdentity } from "#board/reportIdentity.ts";
+import { BoardFailure, type BoardWork } from "#policy.ts";
+import type { SessionObservation } from "#session/schema.ts";
+
+export function reportContent(work: BoardWork, observation: SessionObservation) {
+	const { provenance, itemId } = reportIdentity(work, observation.receipt);
+	const metadata = { id: itemId, kind: "result", relationships: [{ kind: "informs", target: work.workId }] };
+	const content = `---\n${JSON.stringify(metadata)}\n---\n# Fleet report\n\n## Worker receipt\n\n\`\`\`json\n${JSON.stringify(provenance)}\n\`\`\`\n\n## Report\n\n${observation.output}`;
+	return new TextEncoder().encode(content).length > 256 * 1024
+		? Effect.fail(
+				new BoardFailure({
+					code: "report-too-large",
+					message: "Worker report exceeds Board’s 256 KiB context limit, including metadata and receipt; request a shorter report before retrying.",
+				}),
+			)
+		: Effect.succeed(content);
+}

package/src/board/reportFiles.ts

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { type FileHandle, link, mkdir, open, realpath, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect } from "effect";
+import { reportFileName, reportLinks } from "#board/reportLinks.ts";
+import type { ReportFile } from "#reportAttachments.ts";
+import { type ReportDirectory, validateReportDirectory, withReportDirectory } from "#reportFileDirectory.ts";
+import { hasFileCode, ReportFileFailure, reportFileIo, withReportFile } from "#reportFileFailure.ts";
+
+function ensureDirectory(path: string, label: string) {
+	return reportFileIo(label, () => mkdir(path, { mode: 0o700 })).pipe(
+		Effect.catchTag("ReportFileFailure", (error) => (hasFileCode(error.cause, "EEXIST") ? Effect.void : Effect.fail(error))),
+	);
+}
+function existingFile(path: string, bytes: Uint8Array, label: string) {
+	return withReportFile(
+		label,
+		() => open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK),
+		(existing) =>
+			Effect.gen(function* () {
+				if (
+					!(
+						(yield* reportFileIo(label, () => existing.stat())).isFile()
+						&& Buffer.from(bytes).equals(yield* reportFileIo(label, () => existing.readFile()))
+					)
+				) {
+					return yield* Effect.fail(new ReportFileFailure({ path: label, reason: "Attachment identity already contains different bytes" }));
+				}
+				yield* reportFileIo(label, () => existing.sync());
+			}),
+	);
+}
+const publishFile = Effect.fnUntraced(function* (directory: FileHandle, folder: string, name: string, bytes: Uint8Array, label: string) {
+	const temporary = `${folder}/.${randomUUID()}.tmp`;
+	yield* Effect.acquireUseRelease(
+		reportFileIo(label, () => open(temporary, "wx", 0o600)),
+		(file) =>
+			Effect.gen(function* () {
+				yield* reportFileIo(label, () => file.writeFile(bytes));
+				yield* reportFileIo(label, () => file.sync());
+				yield* reportFileIo(label, () => link(temporary, `${folder}/${name}`)).pipe(
+					Effect.catchTag("ReportFileFailure", (error) =>
+						hasFileCode(error.cause, "EEXIST") ? existingFile(`${folder}/${name}`, bytes, label) : Effect.fail(error),
+					),
+				);
+				yield* reportFileIo(label, () => directory.sync());
+			}),
+		(file) => reportFileIo(label, () => file.close()).pipe(Effect.onExit(() => reportFileIo(label, () => unlink(temporary)))),
+	);
+});
+
+function publishAttachments(workspace: ReportDirectory, responses: ReportDirectory, itemId: string, files: readonly ReportFile[], label: string) {
+	const folderName = `${itemId}.attachments`;
+	return Effect.gen(function* () {
+		yield* ensureDirectory(`${responses.folder}/${folderName}`, label);
+		yield* reportFileIo(label, () => responses.file.sync());
+		return yield* withReportDirectory(label, `${responses.folder}/${folderName}`, join(responses.expected, folderName), (directory) =>
+			Effect.gen(function* () {
+				for (const file of files) {
+					yield* validateReportDirectory(file.path, workspace);
+					yield* validateReportDirectory(file.path, responses);
+					yield* validateReportDirectory(file.path, directory);
+					yield* publishFile(directory.file, directory.folder, reportFileName(file.path), file.bytes, file.path);
+				}
+				yield* validateReportDirectory(label, directory);
+				yield* validateReportDirectory(label, workspace);
+				yield* validateReportDirectory(label, responses);
+				return reportLinks(itemId, files);
+			}),
+		);
+	});
+}
+
+export const reportFiles = Effect.fn("Fleet.reportFiles")(function* (root: string, itemId: string, files: readonly ReportFile[]) {
+	if (files.length === 0) {
+		return "";
+	}
+	const label = `responses/${itemId}.attachments`;
+	if (!/^fleet-report\.[a-f\d]+$/u.test(itemId)) {
+		return yield* Effect.fail(new ReportFileFailure({ path: label, reason: "Invalid report identity" }));
+	}
+	const realRoot = yield* reportFileIo(label, () => realpath(root));
+	return yield* withReportDirectory(label, root, realRoot, (workspace) =>
+		Effect.gen(function* () {
+			yield* ensureDirectory(`${workspace.folder}/responses`, label);
+			yield* reportFileIo(label, () => workspace.file.sync());
+			return yield* withReportDirectory(label, `${workspace.folder}/responses`, join(realRoot, "responses"), (responses) =>
+				publishAttachments(workspace, responses, itemId, files, label),
+			);
+		}),
+	);
+});

package/src/board/reportIdentity.ts

@@ -0,0 +1,10 @@
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import type { BoardWork } from "#policy.ts";
+import type { SessionReceipt } from "#session/schema.ts";
+
+const { revisionOf } = responses;
+
+export function reportIdentity(work: BoardWork, receipt: SessionReceipt) {
+	const provenance = { ...receipt, workRevision: work.revision };
+	return { itemId: `fleet-report.${revisionOf(JSON.stringify({ workId: work.workId, ...provenance }))}`, provenance };
+}

package/src/board/reportLinks.ts

@@ -0,0 +1,24 @@
+import { basename } from "node:path";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import type { ReportFile, UnavailableAttachment } from "#reportAttachments.ts";
+
+const { revisionOf } = responses;
+
+export function reportFileName(path: string) {
+	return `${revisionOf(path)}-${basename(path)}${path.endsWith(".md") ? ".attachment" : ""}`;
+}
+
+export function reportLinks(itemId: string, files: readonly ReportFile[], unavailable: readonly UnavailableAttachment[] = []) {
+	const links = files.map(
+		(file) => `- [${file.path.replaceAll(/[[\]\\\r\n]/gu, "\\$&")}](${itemId}.attachments/${encodeURIComponent(reportFileName(file.path))})`,
+	);
+	const warnings = unavailable.map(({ path, reason }) => `- ${escapeText(path)}: ${escapeText(reason)}`);
+	return (
+		(links.length === 0 ? "" : `\n\n## Attachments\n\n${links.join("\n")}`)
+		+ (warnings.length === 0 ? "" : `\n\n## Unavailable attachments\n\n${warnings.join("\n")}`)
+	);
+}
+
+function escapeText(text: string) {
+	return text.replaceAll(/[[\]\\`*_<>\r\n]/gu, (character) => (character === "\n" || character === "\r" ? " " : `\\${character}`));
+}

package/src/board/reportPayload.ts

@@ -0,0 +1,73 @@
+import { Effect, Schema } from "effect";
+import { reportIdentity } from "#board/reportIdentity.ts";
+import { reportPayloadFile } from "#board/reportPayloadFile.ts";
+import { BoardFailure, type BoardWork } from "#policy.ts";
+import type { ReportFile } from "#reportAttachments.ts";
+import { ReportFileFailure } from "#reportFileFailure.ts";
+import { REPORT_LIMITS } from "#reportLimits.ts";
+import type { SessionObservation } from "#session/schema.ts";
+
+const Payload = Schema.Struct({
+	files: Schema.Array(Schema.Struct({ base64: Schema.String, path: Schema.String })),
+	output: Schema.String,
+});
+interface ReportPayload {
+	readonly files: readonly ReportFile[];
+	readonly output: string;
+}
+function validFile(file: (typeof Payload.Type)["files"][number]) {
+	return (
+		file.base64 === Buffer.from(file.base64, "base64").toString("base64")
+		&& !(file.path.includes("\\") || /\p{Cc}/u.test(file.path))
+		&& file.path.split("/").every((part) => part !== "" && part !== "." && part !== ".." && part !== ".git")
+	);
+}
+const decode = Effect.fnUntraced(function* (content: string, payloadPath: string) {
+	const payload = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Payload))(content).pipe(
+		Effect.mapError((cause) => new ReportFileFailure({ cause, path: payloadPath, reason: `Saved report payload is invalid: ${cause.message}` })),
+	);
+	const names = new Set<string>();
+	for (const file of payload.files) {
+		if (!validFile(file) || names.has(file.path)) {
+			return yield* Effect.fail(new ReportFileFailure({ path: file.path, reason: `Invalid or duplicate attachment in ${payloadPath}` }));
+		}
+		names.add(file.path);
+	}
+	const files = payload.files.map(({ path, base64 }) => ({ bytes: Buffer.from(base64, "base64"), path }));
+	if (files.length > REPORT_LIMITS.attachmentCount || files.reduce((size, file) => size + file.bytes.length, 0) > REPORT_LIMITS.attachmentBytes) {
+		return yield* Effect.fail(new ReportFileFailure({ path: payloadPath, reason: "Saved report payload exceeds attachment limits" }));
+	}
+	return { files, output: payload.output };
+});
+export function reportPayload(root: string, work: BoardWork, observation: SessionObservation) {
+	const { itemId } = reportIdentity(work, observation.receipt);
+	const payloadPath = `.fleet-reports/${itemId}.json`;
+	function saved(content: string | undefined) {
+		return content === undefined
+			? Effect.fail(
+					new ReportFileFailure({
+						path: payloadPath,
+						reason: "Report payload could not be recovered or persisted; retry the same completed attempt",
+					}),
+				)
+			: decode(content, payloadPath);
+	}
+	function failure(error: ReportFileFailure) {
+		return new BoardFailure({ message: error.message });
+	}
+	return {
+		read: reportPayloadFile(root, itemId).pipe(
+			Effect.flatMap((content) => (content === undefined ? Effect.succeed(undefined) : decode(content, payloadPath))),
+			Effect.mapError(failure),
+		),
+		save: (payload: ReportPayload) =>
+			reportPayloadFile(
+				root,
+				itemId,
+				JSON.stringify({
+					files: payload.files.map(({ path, bytes }) => ({ base64: Buffer.from(bytes).toString("base64"), path })),
+					output: payload.output,
+				}),
+			).pipe(Effect.flatMap(saved), Effect.mapError(failure)),
+	};
+}

package/src/board/reportPayloadFile.ts

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { type FileHandle, link, mkdir, open, realpath, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect } from "effect";
+import { type ReportDirectory, validateReportDirectory, withReportDirectory } from "#reportFileDirectory.ts";
+import { hasFileCode, ReportFileFailure, reportFileIo, withReportFile } from "#reportFileFailure.ts";
+import { REPORT_LIMITS } from "#reportLimits.ts";
+
+const MAX_BYTES = REPORT_LIMITS.attachmentBytes * 2 + 512 * 1024;
+function readPayload(path: string, label: string) {
+	return withReportFile(
+		label,
+		() => open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK),
+		(file) =>
+			Effect.gen(function* () {
+				if (!(yield* reportFileIo(label, () => file.stat())).isFile()) {
+					return yield* Effect.fail(new ReportFileFailure({ path: label, reason: "Report payload must be a regular file" }));
+				}
+				const chunks: Uint8Array[] = [];
+				let size = 0;
+				for (;;) {
+					const buffer = new Uint8Array(Math.min(64 * 1024, MAX_BYTES - size + 1));
+					const { bytesRead } = yield* reportFileIo(label, () => file.read(buffer));
+					if (bytesRead === 0) {
+						break;
+					}
+					size += bytesRead;
+					if (size > MAX_BYTES) {
+						return yield* Effect.fail(new ReportFileFailure({ path: label, reason: "Report payload exceeds size limit" }));
+					}
+					chunks.push(buffer.subarray(0, bytesRead));
+				}
+				yield* reportFileIo(label, () => file.sync());
+				return Buffer.concat(chunks).toString("utf8");
+			}),
+	).pipe(Effect.catchTag("ReportFileFailure", (error) => (hasFileCode(error.cause, "ENOENT") ? Effect.succeed(undefined) : Effect.fail(error))));
+}
+const persist = Effect.fnUntraced(function* (directory: FileHandle, folder: string, name: string, content: string, label: string) {
+	if (Buffer.byteLength(content) > MAX_BYTES) {
+		return yield* Effect.fail(new ReportFileFailure({ path: label, reason: "Report payload exceeds size limit" }));
+	}
+	const temporary = `${folder}/.${randomUUID()}.tmp`;
+	yield* Effect.acquireUseRelease(
+		reportFileIo(label, () => open(temporary, "wx", 0o600)),
+		(file) =>
+			Effect.gen(function* () {
+				yield* reportFileIo(label, () => file.writeFile(content));
+				yield* reportFileIo(label, () => file.sync());
+				yield* reportFileIo(label, () => link(temporary, `${folder}/${name}`)).pipe(
+					Effect.catchTag("ReportFileFailure", (error) => (hasFileCode(error.cause, "EEXIST") ? Effect.void : Effect.fail(error))),
+				);
+				yield* reportFileIo(label, () => directory.sync());
+			}),
+		(file) => reportFileIo(label, () => file.close()).pipe(Effect.onExit(() => reportFileIo(label, () => unlink(temporary)))),
+	);
+});
+const payloadInDirectory = Effect.fnUntraced(function* (
+	workspace: ReportDirectory,
+	directory: ReportDirectory,
+	name: string,
+	label: string,
+	content?: string,
+) {
+	yield* validateReportDirectory(label, workspace);
+	if (content !== undefined) {
+		yield* persist(directory.file, directory.folder, name, content, label);
+	}
+	const payload = yield* readPayload(`${directory.folder}/${name}`, label);
+	yield* reportFileIo(label, () => directory.file.sync());
+	yield* validateReportDirectory(label, directory);
+	yield* validateReportDirectory(label, workspace);
+	return payload;
+});
+export const reportPayloadFile = Effect.fn("Fleet.reportPayloadFile")(function* (root: string, itemId: string, content?: string) {
+	const name = `${itemId}.json`;
+	const label = `.fleet-reports/${name}`;
+	if (!/^fleet-report\.[a-f\d]+$/u.test(itemId)) {
+		return yield* Effect.fail(new ReportFileFailure({ path: label, reason: "Invalid report identity" }));
+	}
+	const realRoot = yield* reportFileIo(label, () => realpath(root));
+	return yield* withReportDirectory(label, root, realRoot, (workspace) =>
+		Effect.gen(function* () {
+			yield* reportFileIo(label, () => mkdir(`${workspace.folder}/.fleet-reports`, { mode: 0o700 })).pipe(
+				Effect.catchTag("ReportFileFailure", (error) => (hasFileCode(error.cause, "EEXIST") ? Effect.void : Effect.fail(error))),
+			);
+			yield* reportFileIo(label, () => workspace.file.sync());
+			return yield* withReportDirectory(label, `${workspace.folder}/.fleet-reports`, join(realRoot, ".fleet-reports"), (directory) =>
+				payloadInDirectory(workspace, directory, name, label, content),
+			);
+		}),
+	);
+});

package/src/board/schema.ts

@@ -0,0 +1,48 @@
+import { Schema } from "effect";
+import { attention } from "@shivaedev/work-board/integration/attention.ts";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import { SessionReceipt } from "#session/schema.ts";
+
+const { RequestReceipt } = attention;
+const { RecordedResponse } = responses;
+
+export const BoardReport = Schema.Struct({
+	itemId: Schema.String,
+	receipt: SessionReceipt,
+	revision: Schema.String,
+	sourcePath: Schema.String,
+	workRevision: Schema.String,
+});
+export type BoardReport = typeof BoardReport.Type;
+
+export const BoardDecision = Schema.Struct({
+	itemId: Schema.String,
+	questionId: Schema.String,
+	request: Schema.String,
+	revision: Schema.String,
+	sourcePath: Schema.String,
+	workId: Schema.String,
+	workRevision: Schema.String,
+	workSourcePath: Schema.String,
+});
+export type BoardDecision = typeof BoardDecision.Type;
+
+export const BoardDecisionAcknowledgement = Schema.Struct({
+	decision: BoardDecision,
+	disposition: RequestReceipt.fields.disposition,
+	recordedAt: RequestReceipt.fields.recordedAt,
+	responseId: Schema.optional(Schema.String),
+});
+export type BoardDecisionAcknowledgement = typeof BoardDecisionAcknowledgement.Type;
+
+export class BoardAcknowledgementStale extends Schema.TaggedError<BoardAcknowledgementStale>()("BoardAcknowledgementStale", {
+	message: Schema.String,
+}) {}
+
+export const BoardDecisionReading = Schema.Union([
+	Schema.Struct({ _tag: Schema.Literal("Pending") }),
+	Schema.Struct({ _tag: Schema.Literal("Stale"), reason: Schema.String }),
+	Schema.Struct({ _tag: Schema.Literal("Ambiguous"), responseIds: Schema.Array(Schema.String) }),
+	Schema.Struct({ _tag: Schema.Literal("Response"), response: RecordedResponse }),
+]);
+export type BoardDecisionReading = typeof BoardDecisionReading.Type;