@shivaedev/work-fleet 0.0.0 → 0.1.1

package/package.json

@@ -1,11 +1,86 @@
 {
   "name": "@shivaedev/work-fleet",
-  "version": "0.0.0",
-  "description": "Placeholder to reserve the package name.",
-  "license": "MIT",
+  "version": "0.1.1",
+  "description": "Optional Board-backed execution, review and authorized delivery",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/work-fleet#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShivaeDev/platform.git",
     "directory": "packages/work-fleet"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "source": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "work-fleet": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "@effect/sql-pg": "4.0.4",
+    "@shivaedev/effect-contract": "0.5.0",
+    "@shivaedev/effect-service": "0.3.0",
+    "@shivaedev/effect-sql": "0.3.0",
+    "@shivaedev/platform": "0.10.0",
+    "@shivaedev/work-board": "0.14.0",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.4",
+    "@effect/platform-node-shared": "4.0.4",
+    "@effect/vitest": "4.0.4",
+    "@shivaedev/effect-test": "0.4.0",
+    "@shivaedev/effect-test-sql": "0.3.0",
+    "@shivaedev/quality": "0.21.0",
+    "@types/node": "24.19.1",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "effect": "4.0.4",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@effect/platform-node": "4.0.4",
+    "@effect/platform-node-shared": "4.0.4",
+    "effect": "4.0.4"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/DecisionCode.ts

@@ -0,0 +1,50 @@
+import { Schema } from "effect";
+
+export const DecisionCode = Schema.Literals([
+	"approval-required",
+	"board-failure",
+	"checks-repair-exhausted",
+	"checks-result-invalid",
+	"delivery-head-mismatch",
+	"delivery-pr-required",
+	"duplicate-turns",
+	"empty-report",
+	"fleet-denied",
+	"fleet-integration",
+	"fleet-invalid",
+	"fleet-missing",
+	"fleet-stale",
+	"foreign-pr",
+	"incomplete-context",
+	"incomplete-observation",
+	"integration-failure",
+	"no-change-checks-unconfigured",
+	"not-ancestor",
+	"pr-conflicting",
+	"pr-head-moved",
+	"provider-quota-unavailable",
+	"relevant-change",
+	"report-published",
+	"report-too-large",
+	"result-identity-changed",
+	"reviewed-pr-ready",
+	"reviewer-terminal",
+	"session-active-turn",
+	"session-active-turn-exhausted",
+	"session-ambiguous",
+	"session-persistence",
+	"session-protocol",
+	"session-queue-full",
+	"session-rejected",
+	"session-stalled",
+	"session-turn-missing",
+	"session-unavailable",
+	"worker-question",
+	"worker-receipt-missing",
+	"worker-report-head-invalid",
+	"worker-report-head-moved",
+	"worker-report-merged-head-mismatch",
+	"worker-report-pr-invalid",
+	"worker-terminal",
+]);
+export type DecisionCode = typeof DecisionCode.Type;

package/src/admit.ts

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import { Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
+import { withFailureContext } from "#engine/failureContext.ts";
+import { allAttempts, type FleetRecord } from "#model.ts";
+import type { BoardFailure, BoardWork, FleetConfiguration } from "#policy.ts";
+import { qualifyDependencies } from "#qualifyDependencies.ts";
+export const admit = Effect.fn("Fleet.admit")(function* (
+	work: BoardWork,
+	records: readonly FleetRecord[],
+	policy: FleetConfiguration,
+	get: (workId: string) => Effect.Effect<BoardWork, BoardFailure>,
+) {
+	if (!work.approved) {
+		return yield* Effect.fail(
+			withFailureContext(new Forbidden({ message: "Current Board revision needs maintainer approval" }), { code: "approval-required" }),
+		);
+	}
+	yield* qualifyDependencies(work.dependsOn, records, get);
+	const quota = policy.quota;
+	const submitted = records.flatMap(allAttempts).filter((attempt) => attempt.submittedAt >= quota.observedAt).length;
+	if (
+		!(Number.isFinite(quota.observedAt) && Number.isFinite(quota.expiresAt))
+		|| quota.observedAt > policy.now()
+		|| quota.expiresAt <= quota.observedAt
+		|| quota.available === undefined
+		|| !Number.isFinite(quota.available)
+		|| !Number.isInteger(quota.available)
+		|| quota.available < 0
+		|| quota.expiresAt <= policy.now()
+		|| quota.available <= submitted
+	) {
+		return yield* Effect.fail(
+			withFailureContext(new Forbidden({ message: "Fresh available provider quota is required" }), {
+				attentionOwner: "automation",
+				code: "provider-quota-unavailable",
+			}),
+		);
+	}
+});

package/src/attention.ts

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+
+export const AttentionOwner = Schema.Literals(["maintainer", "orchestrator", "automation"]);
+export type AttentionOwner = typeof AttentionOwner.Type;
+
+export function waitingOwner(record: {
+	readonly attentionOwner?: AttentionOwner | undefined;
+	readonly blocker?: string | undefined;
+	readonly checks?: { readonly pending?: boolean | undefined } | undefined;
+	readonly decision?: { readonly attentionOwner?: AttentionOwner | undefined } | undefined;
+	readonly launchRetry?: { readonly retryAt: number } | undefined;
+	readonly stage: string;
+}): AttentionOwner | undefined {
+	if (record.launchRetry !== undefined || (record.stage === "prepared" && record.blocker?.startsWith("waiting for dependency "))) {
+		return "automation";
+	}
+	if (record.stage === "needs-human") {
+		return record.attentionOwner ?? record.decision?.attentionOwner ?? "orchestrator";
+	}
+	if (record.blocker !== undefined) {
+		return record.attentionOwner ?? "orchestrator";
+	}
+	return record.stage === "validating" && record.checks?.pending ? "automation" : undefined;
+}

package/src/board/acknowledgeDecision.ts

@@ -0,0 +1,51 @@
+import { Effect } from "effect";
+import { attention } from "@shivaedev/work-board/integration/attention.ts";
+import { board as boardApi } from "@shivaedev/work-board/integration/board.ts";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import { type BoardSnapshot, recordBoardSource } from "#board/readPass.ts";
+import { BoardAcknowledgementStale, type BoardDecisionAcknowledgement } from "#board/schema.ts";
+import { BoardFailure } from "#policy.ts";
+
+const { managedRequestReceipt } = attention;
+const { metadataModel } = boardApi;
+const { publish, revisionOf } = responses;
+
+export function acknowledgeDecision(root: string, realRoot: string, snapshot: Effect.Effect<BoardSnapshot, BoardFailure>) {
+	return Effect.fn("FleetBoard.acknowledgeDecision")(function* (input: BoardDecisionAcknowledgement) {
+		const current = yield* snapshot;
+		const incomplete = Array.from(current.problems.values()).find((problem) => problem.code === "incomplete-observation");
+		if (incomplete !== undefined) {
+			return yield* Effect.fail(incomplete);
+		}
+		const all = current.documents.filter((document) => !current.problems.has(document.file));
+		const decision = input.decision;
+		const source = all.find((document) => document.file === decision.sourcePath);
+		if (!source || source.parsed.fields.id !== decision.itemId || revisionOf(source.source) !== decision.revision) {
+			return yield* Effect.fail(
+				new BoardAcknowledgementStale({ message: "The decision source changed or moved; its request cannot be acknowledged." }),
+			);
+		}
+		const request = source.parsed.fields.attention?.find((candidate) => candidate.id === decision.request);
+		const requestReceipt = {
+			disposition: input.disposition,
+			question: decision.questionId,
+			recordedAt: input.recordedAt,
+			reviewedRevision: decision.revision,
+			...(input.responseId === undefined ? {} : { response: input.responseId }),
+		};
+		const id = `request-receipt.${revisionOf(JSON.stringify(requestReceipt))}`;
+		const content = `---\n${JSON.stringify({ id, kind: "result", "request_receipt": requestReceipt })}\n---\n# Managed request acknowledgement\n\nThis immutable receipt acknowledges request handling; it grants no execution, acceptance or delivery authority.\n`;
+		const file = `responses/${id}.md`;
+		const receiptDocument = { file, parsed: boardApi.metadataParse(content) };
+		const model = metadataModel([...all.filter((document) => document.file !== file), receiptDocument]);
+		if (!request || managedRequestReceipt(source, request, model) === undefined) {
+			return yield* Effect.fail(
+				new BoardAcknowledgementStale({ message: "The exact managed question and applicable response cannot be qualified for acknowledgement." }),
+			);
+		}
+		yield* publish(root, realRoot, id, content).pipe(
+			Effect.mapError(() => new BoardFailure({ message: "The managed request acknowledgement could not be recorded on Board." })),
+		);
+		yield* recordBoardSource(realRoot, file, content, receiptDocument.parsed);
+	});
+}

package/src/board/briefRevision.ts

@@ -0,0 +1,17 @@
+import type { ParsedMetadata } from "@shivaedev/work-board/integration/board.ts";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import { fleetDeliverable } from "#board/fleetField.ts";
+
+const { revisionOf } = responses;
+
+export function briefRevision(parsed: ParsedMetadata): string {
+	return revisionOf(
+		JSON.stringify({
+			body: parsed.body,
+			criteria: (parsed.fields.criteria ?? []).map(({ id, text }) => ({ id, text })),
+			deliverable: fleetDeliverable(parsed) ?? "change",
+			kind: parsed.fields.kind,
+			relationships: (parsed.fields.relationships ?? []).map(({ kind, target }) => ({ kind, target })),
+		}),
+	);
+}

package/src/board/completionFields.ts

@@ -0,0 +1,65 @@
+import { isAlias, isMap, isScalar, parseDocument } from "yaml";
+
+interface Edit {
+	readonly end: number;
+	readonly start: number;
+	readonly text: string;
+}
+
+function scalarEdit(header: string, node: unknown, value: string, encoded: string): Edit | false | undefined {
+	if (!(isScalar(node) || isAlias(node)) || node.range === undefined || node.range === null) {
+		return false;
+	}
+	if (isScalar(node) && node.value === value) {
+		return;
+	}
+	const [start, end] = node.range;
+	const token = node.srcToken;
+	const ending =
+		token?.type === "block-scalar"
+			? token.props
+					.slice(1)
+					.map((part) => ("source" in part ? part.source : ""))
+					.join("")
+			: "";
+	const spacing = header[start - 1] === ":" ? " " : "";
+	return { end, start, text: `${spacing}${encoded}${ending}` };
+}
+
+export function completionFields(header: string, nextAction: string, newline: string): readonly Edit[] | undefined {
+	const document = parseDocument(header, { keepSourceTokens: true });
+	const mapping = document.contents;
+	if (document.errors.length > 0 || document.warnings.length > 0 || !isMap(mapping) || mapping.range === undefined) {
+		return;
+	}
+	const edits: Edit[] = [];
+	const missing: string[] = [];
+	for (const [key, value, encoded] of [
+		["status", "done", "done"],
+		["next_action", nextAction, JSON.stringify(nextAction)],
+	] as const) {
+		const pair = mapping.items.find((item) => isScalar(item.key) && item.key.value === key);
+		if (pair === undefined) {
+			missing.push(`${key}: ${encoded}`);
+			continue;
+		}
+		const edit = scalarEdit(header, pair.value, value, encoded);
+		if (edit === false) {
+			return;
+		}
+		if (edit !== undefined) {
+			edits.push(edit);
+		}
+	}
+	if (missing.length > 0) {
+		edits.push(missingEdit(header, mapping.flow === true, mapping.range[1], mapping.items.length, missing, newline));
+	}
+	return edits;
+}
+
+function missingEdit(header: string, flow: boolean, end: number, count: number, missing: readonly string[], newline: string): Edit {
+	const start = flow ? end - 1 : header.length;
+	const separator = count > 0 && !header.slice(0, start).trimEnd().endsWith(",") ? ", " : "";
+	const text = flow ? `${separator}${missing.join(", ")}` : `${missing.join(newline)}${newline}`;
+	return { end: start, start, text };
+}

package/src/board/completionMarkdown.ts

@@ -0,0 +1,24 @@
+import { completionFields } from "#board/completionFields.ts";
+
+export function completionMarkdown(source: string, nextAction: string): string | undefined {
+	const opening = /^\uFEFF?---[ \t]*\r?\n/u.exec(source);
+	if (opening === null) {
+		return;
+	}
+	const offset = opening[0].length;
+	const closing = /^---[ \t]*\r?$/mu.exec(source.slice(offset));
+	if (closing === null) {
+		return;
+	}
+	const header = source.slice(offset, offset + closing.index);
+	const newline = opening[0].endsWith("\r\n") ? "\r\n" : "\n";
+	const edits = completionFields(header, nextAction, newline);
+	if (edits === undefined) {
+		return;
+	}
+	let result = source;
+	for (const edit of [...edits].sort((left, right) => right.start - left.start)) {
+		result = result.slice(0, offset + edit.start) + edit.text + result.slice(offset + edit.end);
+	}
+	return result;
+}

package/src/board/decisionAnswer.ts

@@ -0,0 +1,12 @@
+import { releaseOnly } from "#engine/releaseOnly.ts";
+import type { Decision } from "#policy.ts";
+
+export function decisionAnswer(input: Decision) {
+	if (input.worker !== undefined) {
+		return "Record your answer on this item’s answer card to continue the worker in its existing thread. Use a guided release answer or the release command to free terminal ownership instead.";
+	}
+	const explanation = releaseOnly(input.code);
+	const retryText = "### Request changes\nFleet keeps the branch and PR and works on your answer";
+	const retry = explanation === undefined ? `:::option{id="retry"}\n${retryText}\n:::\n\n` : "";
+	return `${explanation === undefined ? "" : `${explanation}\n\n`}::::question{id="fleet-action" select="one"}\n### How should Fleet proceed?\n\n${retry}:::option{id="release"}\n### Release\nFleet stops and hands the work back\n:::\n::::`;
+}

package/src/board/decisionReading.ts

@@ -0,0 +1,54 @@
+import { Effect } from "effect";
+import { board } from "@shivaedev/work-board/integration/board.ts";
+import type { Reading } from "@shivaedev/work-board/integration/responses.ts";
+import { responses } from "@shivaedev/work-board/integration/responses.ts";
+import type { BoardDocument } from "#board/documents.ts";
+import type { BoardDecision, BoardDecisionReading } from "#board/schema.ts";
+import { BoardFailure } from "#policy.ts";
+
+const { metadataModel } = board;
+const { currentResponses, questionId, readResponses, revisionOf } = responses;
+
+function currentResponse(reading: Reading): BoardDecisionReading {
+	const current = currentResponses(reading.responses);
+	if (current.length === 0 && reading.responses.length === 0) {
+		return { _tag: "Pending" };
+	}
+	if (current.length !== 1 || !current[0]) {
+		return { _tag: "Ambiguous", responseIds: current.map((response) => response.id) };
+	}
+	return { _tag: "Response", response: current[0] };
+}
+
+export function decisionReading(documents: Effect.Effect<readonly BoardDocument[], BoardFailure>) {
+	return Effect.fn("FleetBoard.readDecision")(function* (receipt: BoardDecision): Effect.fn.Return<BoardDecisionReading, BoardFailure> {
+		const all = yield* documents;
+		const model = metadataModel(all);
+		const matches = model.ids.get(receipt.itemId);
+		const document = matches?.length === 1 ? all.find((entry) => entry.file === matches[0]?.file) : undefined;
+		if (!document || document.file !== receipt.sourcePath || revisionOf(document.source) !== receipt.revision) {
+			return { _tag: "Stale", reason: "The decision source changed, moved or became ambiguous." };
+		}
+		if (
+			document.parsed.fields.kind !== "decision"
+			|| document.parsed.fields.attention?.filter((request) => request.id === receipt.request && request.state === "open").length !== 1
+			|| questionId(receipt.itemId, receipt.request, receipt.revision, receipt.sourcePath) !== receipt.questionId
+		) {
+			return { _tag: "Stale", reason: "The exact open decision request is unavailable." };
+		}
+		const snapshot = Effect.succeed({ documents: all, entries: [], model, modified: new Map<string, number>(), revision: 0, unavailable: [] });
+		const reading = yield* readResponses(snapshot)(receipt.questionId).pipe(
+			Effect.mapError(() => new BoardFailure({ message: "Fleet decision response history is incomplete or ambiguous." })),
+		);
+		if (
+			reading.question.question.item !== receipt.itemId
+			|| reading.question.question.request !== receipt.request
+			|| reading.question.question.source !== receipt.sourcePath
+			|| reading.question.question.reviewedRevision !== receipt.revision
+			|| reading.question.context !== document.source
+		) {
+			return { _tag: "Stale", reason: "The registered question does not match the reviewed decision context." };
+		}
+		return currentResponse(reading);
+	});
+}

package/src/board/documents.ts

@@ -0,0 +1,89 @@
+import { Effect, FileSystem, Path } from "effect";
+import type { MetadataDocument } from "@shivaedev/work-board/integration/board.ts";
+import { board as boardApi } from "@shivaedev/work-board/integration/board.ts";
+import { readDocument } from "#board/readDocument.ts";
+import { BoardSnapshot, readSnapshot } from "#board/readPass.ts";
+import { BoardFailure } from "#policy.ts";
+
+const { listMarkdown } = boardApi;
+
+export type BoardDocument = MetadataDocument & { readonly source: string };
+
+export const snapshotDocument = Effect.fn("FleetBoard.snapshotDocument")(function* (snapshot: BoardSnapshot, workId: string) {
+	const matches = snapshot.model.ids.get(workId);
+	const found = matches?.length === 1 ? snapshot.files.get(matches[0]?.file ?? "") : undefined;
+	if (found === undefined) {
+		const message = [
+			`Board identity is missing or ambiguous: ${workId}`,
+			...Array.from(snapshot.problems.values(), (failure) => failure.message),
+		].join("; ");
+		const incomplete = Array.from(snapshot.problems.values()).some((failure) => failure.code === "incomplete-observation");
+		return yield* Effect.fail(new BoardFailure({ code: incomplete ? "incomplete-observation" : undefined, message }));
+	}
+	const problem = snapshot.problems.get(found.file);
+	return yield* problem === undefined ? Effect.succeed(found) : Effect.fail(problem);
+});
+
+const readDocuments = Effect.fn("FleetBoard.readDocuments")(function* (root: string, realRoot: string) {
+	const files = yield* listMarkdown(root, realRoot).pipe(
+		Effect.mapError(
+			(error) => new BoardFailure({ code: "incomplete-observation", message: `Board sources could not be listed: ${root} (${error.message})` }),
+		),
+	);
+	const problems = new Map<string, BoardFailure>();
+	const documents = yield* Effect.forEach(files, (file) =>
+		readDocument(root, realRoot, file.path).pipe(
+			Effect.map(({ document, problem }) => {
+				if (problem !== undefined) {
+					problems.set(file.path, problem);
+				}
+				return document;
+			}),
+			Effect.catch((error) => {
+				problems.set(file.path, error);
+				return Effect.succeed(undefined);
+			}),
+		),
+	);
+	for (const problem of problems.values()) {
+		yield* Effect.logWarning(problem.message);
+	}
+	return new BoardSnapshot(
+		documents.filter((document) => document !== undefined),
+		problems,
+	);
+});
+
+export const refreshSnapshotDocument = Effect.fn("FleetBoard.refreshSnapshotDocument")(function* (
+	root: string,
+	realRoot: string,
+	snapshot: BoardSnapshot,
+	workId: string,
+) {
+	const previous = yield* snapshotDocument(snapshot, workId);
+	const { document, problem } = yield* readDocument(root, realRoot, previous.file);
+	if (problem !== undefined) {
+		return yield* Effect.fail(problem);
+	}
+	if (document === undefined) {
+		return yield* Effect.fail(new BoardFailure({ code: "incomplete-observation", message: `Board source is unavailable: ${previous.file}` }));
+	}
+	snapshot.record(document);
+	return yield* snapshotDocument(snapshot, workId);
+});
+
+export function boardSnapshot(root: string, realRoot: string) {
+	return readSnapshot(realRoot, readDocuments(root, realRoot));
+}
+
+export function boardDocuments(root: string, realRoot: string) {
+	return boardSnapshot(root, realRoot).pipe(Effect.map((snapshot) => snapshot.documents.filter((document) => !snapshot.problems.has(document.file))));
+}
+
+export function boundSnapshot(root: string, realRoot: string, fs: FileSystem.FileSystem, path: Path.Path) {
+	return boardSnapshot(root, realRoot).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+}
+
+export function boundDocuments(root: string, realRoot: string, fs: FileSystem.FileSystem, path: Path.Path) {
+	return boardDocuments(root, realRoot).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+}

package/src/board/fleetField.ts

@@ -0,0 +1,35 @@
+import { parse } from "yaml";
+import type { ParsedMetadata } from "@shivaedev/work-board/integration/board.ts";
+
+const APPROVAL = "fleet";
+const LAUNCH = "fleet-launch";
+const DELIVERABLE = "fleet-deliverable";
+const parsedFields = new WeakMap<ParsedMetadata, ReadonlyMap<string, unknown>>();
+
+function fleetField(parsed: ParsedMetadata, field: string): unknown {
+	if (parsed.raw === undefined || parsed.lines[field] === undefined || parsed.diagnostics.some((diagnostic) => diagnostic.field === undefined)) {
+		return undefined;
+	}
+	const cached = parsedFields.get(parsed);
+	if (cached !== undefined) {
+		return cached.get(field);
+	}
+	const lines = parsed.raw.split(/\r?\n/u);
+	const closing = lines.findLastIndex((line) => line.trimEnd() === "---");
+	const data: unknown = parse(lines.slice(1, closing).join("\n"));
+	const values = new Map(typeof data === "object" && data !== null ? Object.entries(data) : []);
+	parsedFields.set(parsed, values);
+	return values.get(field);
+}
+
+export function fleetApproved(parsed: ParsedMetadata): boolean {
+	return fleetField(parsed, APPROVAL) === "approved";
+}
+
+export function fleetLaunch(parsed: ParsedMetadata): unknown {
+	return fleetField(parsed, LAUNCH);
+}
+
+export function fleetDeliverable(parsed: ParsedMetadata): unknown {
+	return fleetField(parsed, DELIVERABLE);
+}

package/src/board/markdown.ts

@@ -0,0 +1,103 @@
+import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+import { defineService } from "@shivaedev/effect-service/define-service.ts";
+import { board as boardApi } from "@shivaedev/work-board/integration/board.ts";
+import { acknowledgeDecision } from "#board/acknowledgeDecision.ts";
+import { briefRevision } from "#board/briefRevision.ts";
+import { completionMarkdown } from "#board/completionMarkdown.ts";
+import { decisionReading } from "#board/decisionReading.ts";
+import { boundDocuments, boundSnapshot, refreshSnapshotDocument, snapshotDocument } from "#board/documents.ts";
+import { fleetApproved, fleetDeliverable } from "#board/fleetField.ts";
+import { publishBoard } from "#board/publish.ts";
+import { publishReport } from "#board/publishReport.ts";
+import { workMetadata } from "#board/readPass.ts";
+import { workRevision } from "#board/workRevision.ts";
+import { writeCompletion } from "#board/writeCompletion.ts";
+import { BoardFailure, BoardGateway } from "#policy.ts";
+import { RepositoryPath } from "#preparation/schema.ts";
+
+class BoardRoot extends Context.Service<BoardRoot, string>()("Fleet/BoardRoot") {}
+
+const MarkdownBoard = defineService({
+	id: "Fleet/MarkdownBoard",
+	initialize: Effect.gen(function* () {
+		const root = yield* BoardRoot;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const realRoot = yield* fs.realPath(root);
+		const documents = boundDocuments(root, realRoot, fs, path);
+		const snapshot = boundSnapshot(root, realRoot, fs, path);
+		const get = Effect.fn("FleetBoard.get")(function* (workId: string, options?: { readonly fresh?: boolean }) {
+			const current = yield* snapshot;
+			const found = yield* options?.fresh
+				? refreshSnapshotDocument(root, realRoot, current, workId).pipe(
+						Effect.provideService(FileSystem.FileSystem, fs),
+						Effect.provideService(Path.Path, path),
+					)
+				: snapshotDocument(current, workId);
+			const deliverable = fleetDeliverable(found.parsed);
+			if (deliverable !== undefined && deliverable !== "report") {
+				return yield* Effect.fail(new BoardFailure({ message: "Invalid fleet-deliverable; use report or omit the field for pull requests." }));
+			}
+			return {
+				approved: fleetApproved(found.parsed),
+				areas: found.parsed.fields.areas,
+				status: found.parsed.fields.status,
+				...(deliverable === "report" ? { deliverable: "report" as const } : {}),
+				context: found.source,
+				dependsOn: (found.parsed.fields.relationships ?? []).filter((relation) => relation.kind === "depends_on").map((relation) => relation.target),
+				revision: briefRevision(found.parsed),
+				sourcePath: path.join(realRoot, found.file),
+				workId,
+			};
+		});
+		const publish = publishBoard(root, realRoot, documents);
+		return { documents, get, path, publish, realRoot, root, snapshot };
+	}),
+	methods: ({ root, realRoot, documents, get, publish, path, snapshot }) =>
+		BoardGateway.of({
+			acknowledgeDecision: acknowledgeDecision(root, realRoot, snapshot),
+			complete: Effect.fn("FleetBoard.complete")(function* (workId, sourcePath, nextAction) {
+				const work = yield* get(workId);
+				if (work.sourcePath !== sourcePath) {
+					return;
+				}
+				const content = completionMarkdown(work.context, nextAction);
+				if (content === undefined) {
+					return;
+				}
+				const parsed = boardApi.metadataParse(content);
+				if (parsed.fields.id !== workId || parsed.diagnostics.length > 0 || briefRevision(parsed) !== work.revision) {
+					return yield* Effect.fail(new BoardFailure({ message: "Completion bookkeeping would change authored Board context or identity." }));
+				}
+				yield* writeCompletion(root, realRoot, path.relative(realRoot, sourcePath), work.context, content).pipe(
+					Effect.mapError((error) => new BoardFailure({ message: error.message })),
+				);
+			}),
+			decision: Effect.fn("FleetBoard.decision")(function* (workId, input, originalContext) {
+				const work = originalContext ?? (yield* get(workId));
+				const parsed = yield* workMetadata(work);
+				const relativeSource = path.relative(realRoot, work.sourcePath);
+				if (
+					work.workId !== workId
+					|| workRevision(work.revision, work.context) !== briefRevision(parsed)
+					|| parsed.fields.id !== workId
+					|| parsed.diagnostics.length > 0
+					|| relativeSource === "."
+					|| !Schema.is(RepositoryPath)(relativeSource)
+				) {
+					return yield* Effect.fail(
+						new BoardFailure({ message: "The original Board publication context does not match its identity, revision or source boundary." }),
+					);
+				}
+				return yield* publish(work, input);
+			}),
+			get,
+			readDecision: decisionReading(documents),
+			report: publishReport(root, realRoot, documents),
+		}),
+	requires: [BoardRoot, FileSystem.FileSystem, Path.Path],
+});
+
+export function markdownBoard(root: string) {
+	return Layer.effect(BoardGateway)(MarkdownBoard).pipe(Layer.provide(MarkdownBoard.layer.pipe(Layer.provide(Layer.succeed(BoardRoot, root)))));
+}