@shivaedev/work-board 0.2.1 → 0.3.0

package/src/http/assets.ts

@@ -1,15 +1,30 @@
 import { createRequire } from "node:module";
 import { Data, Effect, FileSystem, Path } from "effect";
 import type { HttpRouter, HttpServerRequest } from "effect/unstable/http";
-import { client } from "#page/client.ts";
+import { client, preferences } from "#page/client.ts";
 import { diagrams } from "#page/diagrams.ts";
+import { libraryScript } from "#page/libraryScript.ts";
+import { navigationScript } from "#page/navigationScript.ts";
+import { readingStateScript } from "#page/readingStateScript.ts";
+import { searchResultsScript } from "#page/searchResultsScript.ts";
+import { searchScript } from "#page/searchScript.ts";
+import { pageStateScript } from "#page/stateScript.ts";
 import { style } from "#page/style.ts";
 import { swap } from "#page/swap.ts";
+import { savedScript } from "#views/savedScript.ts";
 import { respond } from "./respond.ts";
 
 export const ASSETS: ReadonlyArray<readonly [HttpRouter.PathInput, string, string]> = [
 	["/_board/style.css", style, "text/css"],
+	["/_board/saved-views.js", savedScript(), "text/javascript"],
 	["/_board/client.js", client, "text/javascript"],
+	["/_board/preferences.js", preferences, "text/javascript"],
+	["/_board/search.js", searchScript(), "text/javascript"],
+	["/_board/search-results.js", searchResultsScript(), "text/javascript"],
+	["/_board/library.js", libraryScript(), "text/javascript"],
+	["/_board/navigation.js", navigationScript(), "text/javascript"],
+	["/_board/page-state.js", pageStateScript(), "text/javascript"],
+	["/_board/reading-state.js", readingStateScript(), "text/javascript"],
 	["/_board/diagrams.js", diagrams, "text/javascript"],
 	["/_board/swap.js", swap, "text/javascript"],
 ];

package/src/http/identity.ts

@@ -0,0 +1,62 @@
+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 { escapeHtml } from "#page/escape.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import type { page } from "./page.ts";
+import { respond } from "./respond.ts";
+
+function requestedIdentity(pathname: string): string {
+	try {
+		return decodeURIComponent(pathname.slice("/_board/item/".length).replace(/\/$/u, ""));
+	} catch {
+		return "";
+	}
+}
+
+export function identity(
+	index: Effect.Success<ReturnType<typeof searchSnapshot>>,
+	pages: ReturnType<typeof page>,
+	changes: Changes,
+	home: string | undefined,
+) {
+	return Effect.fn("WorkBoard.identity")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const pathname = new URL(request.url, "http://127.0.0.1").pathname;
+		const id = requestedIdentity(pathname);
+		if (!pathname.endsWith("/") && /\.md$/iu.exec(id) !== null) {
+			return yield* pages(request);
+		}
+		const snapshot = yield* index;
+		const matches = snapshot.model.ids.get(id) ?? [];
+		if (snapshot.unavailable.length > 0) {
+			return respond(
+				shell(
+					`Item ${id}`,
+					"",
+					`<p class="empty">The workspace index is incomplete. Could not read ${escapeHtml(snapshot.unavailable.join(", "))}; item identity could not be validated. Retry when the files are readable.</p>`,
+					changes.realRoot,
+					false,
+				),
+				"text/html",
+				503,
+			);
+		}
+		if (matches.length === 1 && matches[0]) {
+			return yield* pages(request, matches[0].file, id);
+		}
+		const text =
+			matches.length > 0
+				? `The ID ${id} is duplicated. No document was selected.`
+				: `No item with ID ${id} is available. It may be missing, renamed, or invalid.`;
+		const choices = matches.map((document) => `<li><a href="${escapeHtml(fileUrl(document.file))}">${escapeHtml(document.file)}</a></li>`).join("");
+		const nav = navHtml(yield* changes.files, "", home);
+		return respond(
+			shell(`Item ${id}`, nav, `<p class="empty">${escapeHtml(text)}</p>${choices ? `<ul>${choices}</ul>` : ""}`, changes.realRoot, false),
+			"text/html",
+			matches.length > 0 ? 409 : 404,
+		);
+	});
+}

package/src/http/page.ts

@@ -2,12 +2,16 @@ import { Effect, FileSystem, Option, Path } from "effect";
 import type { HttpServerRequest } from "effect/unstable/http";
 import type { Changes } from "#files/changes.ts";
 import { type MarkdownFile, within } from "#files/list.ts";
+import { metadataModel } from "#metadata/model.ts";
+import { metadataParse } from "#metadata/parse.ts";
 import { boardHtml } from "#page/board.ts";
 import { documentHtml } from "#page/document.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 { boardOf } from "#render/board.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
 import { respond } from "./respond.ts";
 
 export interface PageOptions {
@@ -26,8 +30,8 @@ const requestedPath = (url: string): string => {
 
 const message = (text: string): string => `<p class="empty">${escapeHtml(text)}</p>`;
 
-export const page = (options: PageOptions, changes: Changes) => {
-	const body = Effect.fn("WorkBoard.pageBody")(function* (file: MarkdownFile) {
+export const page = (options: PageOptions, changes: Changes, index: Effect.Success<ReturnType<typeof searchSnapshot>>) => {
+	const body = Effect.fn("WorkBoard.pageBody")(function* (file: MarkdownFile, expectedIdentity?: string) {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
 		const real = yield* Effect.option(fs.realPath(path.join(options.root, file.path)));
@@ -35,20 +39,53 @@ export const page = (options: PageOptions, changes: Changes) => {
 			return Option.none();
 		}
 		const source = yield* fs.readFileString(real.value);
-		return Option.some(file.path === options.home ? yield* boardHtml(boardOf(source), file.path, file.modified) : yield* documentHtml(source, file));
+		const parsed = metadataParse(source);
+		let identity: string | undefined;
+		const snapshot = yield* index;
+		const model = metadataModel(
+			[...snapshot.documents.filter((document) => document.file !== file.path), { file: file.path, parsed }],
+			snapshot.unavailable,
+			options.home ?? (yield* changes.files)[0]?.path,
+		);
+		const metadata = metadataHtml(parsed, file.path, model);
+		if (snapshot.unavailable.length === 0 && parsed.fields.id && model.ids.get(parsed.fields.id)?.length === 1) {
+			identity = parsed.fields.id;
+		}
+		if (expectedIdentity && identity !== expectedIdentity) {
+			return Option.none();
+		}
+		const html =
+			file.path === options.home
+				? yield* boardHtml(boardOf(parsed.body), file.path, file.modified, metadata)
+				: yield* documentHtml(parsed.body, file, metadata);
+		return Option.some({ html, identity });
 	});
-	return Effect.fn("WorkBoard.page")(function* (request: HttpServerRequest.HttpServerRequest) {
+	return Effect.fn("WorkBoard.page")(function* (request: HttpServerRequest.HttpServerRequest, resolved?: string, expectedIdentity?: string) {
 		const files = yield* changes.files;
-		const requested = requestedPath(request.url) || options.home || files[0]?.path || "";
+		const requested = resolved ?? (requestedPath(request.url) || options.home || files[0]?.path || "");
 		const file = files.find((candidate) => candidate.path === requested);
 		const nav = navHtml(files, requested, options.home);
-		const missing = () => respond(shell(requested, nav, message(`No markdown file at ${requested || options.root}.`)), "text/html", 404);
+		function layout(content: string, identity?: string) {
+			return shell(requested, nav, content, changes.realRoot, requested === options.home, identity);
+		}
+		const missing = () =>
+			respond(
+				layout(
+					message(
+						expectedIdentity
+							? `No item with ID ${expectedIdentity} at ${requested}; its source identity changed or is invalid.`
+							: `No markdown file at ${requested || options.root}.`,
+					),
+				),
+				"text/html",
+				404,
+			);
 		if (file === undefined) {
 			return missing();
 		}
-		return yield* body(file).pipe(
-			Effect.map(Option.match({ onNone: missing, onSome: (main) => respond(shell(file.path, nav, main), "text/html") })),
-			Effect.catch(() => Effect.succeed(respond(shell(file.path, nav, message(`${file.path} could not be read.`)), "text/html", 500))),
+		return yield* body(file, expectedIdentity).pipe(
+			Effect.map(Option.match({ onNone: missing, onSome: (main) => respond(layout(main.html, main.identity), "text/html") })),
+			Effect.catch(() => Effect.succeed(respond(layout(message(`${file.path} could not be read.`)), "text/html", 500))),
 		);
 	});
 };

package/src/http/search.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { searchMatch } from "#search/match.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function search(index: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	return Effect.fn("WorkBoard.search")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const query = new URL(request.url, "http://127.0.0.1").searchParams.get("q") ?? "";
+		const snapshot = yield* index;
+		return respond(JSON.stringify({ ...searchMatch(snapshot.entries, query), unavailable: snapshot.unavailable }), "application/json");
+	});
+}

package/src/http/work.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import { stateOf } from "#views/state.ts";
+import { workHtml } from "#views/workHtml.ts";
+import { respond } from "./respond.ts";
+
+export function work(index: Effect.Success<ReturnType<typeof searchSnapshot>>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.work")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const snapshot = yield* index;
+		const nav = navHtml(yield* changes.files, "", home);
+		if (snapshot.unavailable.length > 0) {
+			return respond(
+				shell(
+					"Work",
+					nav,
+					`<h1>Workspace incomplete</h1><p class="empty">Could not read ${escapeHtml(snapshot.unavailable.join(", "))}. Work identity and view counts cannot be validated. Read available source files or retry when the workspace is readable.</p>`,
+					changes.realRoot,
+					true,
+					undefined,
+					true,
+				),
+				"text/html",
+				503,
+			);
+		}
+		const result = yield* workHtml(snapshot, stateOf(request.url)).pipe(
+			Effect.catch(() =>
+				Effect.succeed({
+					html: '<h1>Work unavailable</h1><p class="empty">The selected source could not be rendered. Read its Markdown file or retry.</p>',
+					status: 500,
+				}),
+			),
+		);
+		return respond(shell("Work", nav, result.html, changes.realRoot, true, undefined, true), "text/html", result.status);
+	});
+}

package/src/metadata/backlinks.ts

@@ -0,0 +1,39 @@
+import type { MetadataDocument, MetadataModel } from "./model.ts";
+import { referenceFile, sourceFile } from "./sourceLinks.ts";
+
+export interface Backlink {
+	readonly file: string;
+	readonly kind: string;
+	readonly line?: number;
+}
+
+function references(document: MetadataDocument, model: MetadataModel) {
+	const { fields, lines } = document.parsed;
+	return [
+		...(fields.relationships?.map((link, index) => ({
+			kind: link.kind,
+			line: lines[`relationships.${index}.target`],
+			target: referenceFile(link.target, model),
+		})) ?? []),
+		...(fields.items?.map((item, index) => ({ kind: "board member", line: lines[`items.${index}`], target: referenceFile(item, model) })) ?? []),
+		...(fields.evidence?.flatMap((evidence, index) => [
+			{ kind: "evidence source", line: lines[`evidence.${index}.source`], target: sourceFile(evidence.source, document.file, model) },
+			{
+				kind: "criterion evidence",
+				line: lines[`evidence.${index}.criterion`],
+				target: evidence.criterion ? referenceFile(evidence.criterion, model) : undefined,
+			},
+		]) ?? []),
+		...(document.links?.map((link) => ({ kind: "Markdown link", line: undefined, target: sourceFile(link, document.file, model) })) ?? []),
+	];
+}
+
+export function backlinksOf(file: string, model: MetadataModel): readonly Backlink[] {
+	return model.documents.flatMap((document) =>
+		document.file === file
+			? []
+			: references(document, model)
+					.filter((reference) => reference.target === file)
+					.map((reference) => ({ file: document.file, kind: reference.kind, ...(reference.line === undefined ? {} : { line: reference.line }) })),
+	);
+}

package/src/metadata/fields.ts

@@ -0,0 +1,26 @@
+import { Option, Schema } from "effect";
+import type { Diagnostic } from "./parse.ts";
+import { Metadata } from "./schema.ts";
+
+const schemas: ReadonlyMap<string, Schema.ConstraintDecoder<unknown, never>> = new Map(Object.entries(Metadata.to.fields));
+const sourceKeys = new Map([["next_action", "nextAction"]]);
+
+export function metadataFields(data: object, lines: Readonly<Record<string, number>>) {
+	const fields: Record<string, unknown> = {};
+	const diagnostics: Diagnostic[] = [];
+	for (const [field, value] of Object.entries(data)) {
+		const key = sourceKeys.get(field) ?? field;
+		const schema = field === "nextAction" ? undefined : schemas.get(key);
+		if (!schema) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Unknown field ${field}; kept in the original frontmatter.` });
+			continue;
+		}
+		const decoded = Schema.decodeUnknownOption(schema, { onExcessProperty: "error" })(value);
+		if (Option.isNone(decoded)) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Invalid ${field}; kept in the original frontmatter and not interpreted.` });
+		} else {
+			fields[key] = decoded.value;
+		}
+	}
+	return { diagnostics, fields: Schema.decodeUnknownSync(Schema.toType(Metadata))(fields) };
+}

package/src/metadata/links.ts

@@ -0,0 +1,19 @@
+import type { MetadataModel } from "./model.ts";
+
+export function identityUrl(id: string): string {
+	return `/_board/item/${encodeURIComponent(id)}/`;
+}
+export function referenceTarget(reference: string, model: MetadataModel): string | undefined {
+	if (model.unavailable.length > 0) {
+		return undefined;
+	}
+	const [id = "", criterion] = reference.split("#");
+	const targets = model.ids.get(id);
+	if (targets?.length !== 1) {
+		return undefined;
+	}
+	if (criterion && targets[0]?.parsed.fields.criteria?.filter((item) => item.id === criterion).length !== 1) {
+		return undefined;
+	}
+	return identityUrl(id) + (criterion ? `#criterion-${encodeURIComponent(criterion)}` : "");
+}

package/src/metadata/locations.ts

@@ -0,0 +1,34 @@
+import { isMap, isNode, isScalar, isSeq, type LineCounter, type Node, type YAMLMap } from "yaml";
+
+function recordMap(node: YAMLMap, field: string, counter: LineCounter, lines: Record<string, number>) {
+	for (const pair of node.items) {
+		if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
+			continue;
+		}
+		const key = field ? `${field}.${pair.key.value}` : pair.key.value;
+		visit(pair.value, key, counter, lines);
+		if (pair.key.range) {
+			lines[key] = counter.linePos(pair.key.range[0]).line + 1;
+		}
+	}
+}
+function visit(value: unknown, field: string, counter: LineCounter, lines: Record<string, number>) {
+	if (!isNode(value)) {
+		return;
+	}
+	if (value.range && field) {
+		lines[field] = counter.linePos(value.range[0]).line + 1;
+	}
+	if (isMap(value)) {
+		recordMap(value, field, counter, lines);
+	} else if (isSeq(value)) {
+		value.items.forEach((item, index) => {
+			visit(item, `${field}.${index}`, counter, lines);
+		});
+	}
+}
+export function metadataLocations(node: Node | null, counter: LineCounter): Readonly<Record<string, number>> {
+	const lines: Record<string, number> = {};
+	visit(node, "", counter, lines);
+	return lines;
+}

package/src/metadata/model.ts

@@ -0,0 +1,27 @@
+import type { Diagnostic, ParsedMetadata } from "./parse.ts";
+import { metadataProblems } from "./problems.ts";
+
+export interface MetadataDocument {
+	readonly file: string;
+	readonly links?: readonly string[];
+	readonly parsed: ParsedMetadata;
+}
+export interface MetadataModel {
+	readonly diagnostics: ReadonlyMap<string, readonly Diagnostic[]>;
+	readonly documents: readonly MetadataDocument[];
+	readonly ids: ReadonlyMap<string, readonly MetadataDocument[]>;
+	readonly rootFile: string | undefined;
+	readonly unavailable: readonly string[];
+}
+
+export function metadataModel(documents: readonly MetadataDocument[], unavailable: readonly string[] = [], rootFile?: string): MetadataModel {
+	const ids = new Map<string, MetadataDocument[]>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			ids.set(id, [...(ids.get(id) ?? []), document]);
+		}
+	}
+	const diagnostics = new Map(documents.map((document) => [document.file, metadataProblems(document, ids, unavailable)]));
+	return { diagnostics, documents, ids, rootFile, unavailable };
+}

package/src/metadata/parse.ts

@@ -0,0 +1,62 @@
+import { LineCounter, parseDocument } from "yaml";
+import { metadataFields } from "./fields.ts";
+import { metadataLocations } from "./locations.ts";
+import type { Metadata } from "./schema.ts";
+
+export interface Diagnostic {
+	readonly field?: string;
+	readonly line: number;
+	readonly message: string;
+}
+export interface ParsedMetadata {
+	readonly body: string;
+	readonly bodyLine: number;
+	readonly diagnostics: readonly Diagnostic[];
+	readonly fields: Metadata;
+	readonly lines: Readonly<Record<string, number>>;
+	readonly raw?: string;
+}
+
+export function metadataParse(source: string): ParsedMetadata {
+	const plain: ParsedMetadata = { body: source, bodyLine: 1, diagnostics: [], fields: {}, lines: {} };
+	const opening = /^\uFEFF?---[ \t]*\r?\n/u.exec(source);
+	if (!opening) {
+		return plain;
+	}
+	const remainder = source.slice(opening[0].length);
+	const closing = /^---[ \t]*\r?$/mu.exec(remainder);
+	if (!closing) {
+		return { ...plain, diagnostics: [{ line: 1, message: "Unterminated frontmatter; the original Markdown is shown." }] };
+	}
+	let end = opening[0].length + closing.index + closing[0].length;
+	if (source[end] === "\n") {
+		end += 1;
+	}
+	const raw = source.slice(0, end);
+	const body = source.slice(end);
+	const bodyLine = raw.split("\n").length;
+	const counter = new LineCounter();
+	const doc = parseDocument(remainder.slice(0, closing.index), { lineCounter: counter });
+	const lines = metadataLocations(doc.contents, counter);
+	const diagnostics: Diagnostic[] = [...doc.errors, ...doc.warnings].map((error) => ({
+		line: (error.linePos?.[0].line ?? 1) + 1,
+		message: error.message,
+	}));
+	const result = { body, bodyLine, diagnostics, fields: {}, lines, raw };
+	if (doc.errors.length > 0 || doc.warnings.length > 0) {
+		return result;
+	}
+	let data: unknown;
+	try {
+		data = doc.toJS({ maxAliasCount: 50 });
+	} catch {
+		return { ...result, diagnostics: [...diagnostics, { line: 2, message: "Frontmatter aliases could not be expanded safely." }] };
+	}
+	if (data === null) {
+		return result;
+	}
+	if (typeof data !== "object" || Array.isArray(data)) {
+		return { ...plain, diagnostics: [{ line: 2, message: "Frontmatter must be a mapping; the original Markdown is shown." }] };
+	}
+	return { ...result, ...metadataFields(data, lines) };
+}

package/src/metadata/problems.ts

@@ -0,0 +1,62 @@
+import type { MetadataDocument } from "./model.ts";
+import type { Diagnostic } from "./parse.ts";
+
+function referenceProblem(target: string, ids: ReadonlyMap<string, readonly MetadataDocument[]>): string | undefined {
+	const [id = "", criterion] = target.split("#");
+	const matches = ids.get(id);
+	if (!matches?.length) {
+		return `Unresolved reference ${target}.`;
+	}
+	if (matches.length > 1) {
+		return `Ambiguous reference ${target}; the ID is duplicated.`;
+	}
+	if (criterion && matches[0]?.parsed.fields.criteria?.filter((item) => item.id === criterion).length !== 1) {
+		return `Unresolved or duplicated criterion ${target}.`;
+	}
+	return undefined;
+}
+function criterionProblems(document: MetadataDocument): readonly Diagnostic[] {
+	const criteria = document.parsed.fields.criteria ?? [];
+	return criteria.flatMap((criterion, index) =>
+		criteria.filter((item) => item.id === criterion.id).length > 1
+			? [{ field: "criteria", line: document.parsed.lines[`criteria.${index}`] ?? 2, message: `Duplicate criterion ID ${criterion.id}.` }]
+			: [],
+	);
+}
+function referenceProblems(document: MetadataDocument, ids: ReadonlyMap<string, readonly MetadataDocument[]>): readonly Diagnostic[] {
+	const { fields, lines } = document.parsed;
+	const references = [
+		...(fields.relationships?.map((link, index) => ({ field: "relationships", key: `relationships.${index}.target`, target: link.target })) ?? []),
+		...(fields.items?.map((target, index) => ({ field: "items", key: `items.${index}`, target })) ?? []),
+		...(fields.evidence?.flatMap((item, index) =>
+			item.criterion ? [{ field: "evidence", key: `evidence.${index}.criterion`, target: item.criterion }] : [],
+		) ?? []),
+	];
+	return references.flatMap((reference) => {
+		const message = referenceProblem(reference.target, ids);
+		return message ? [{ field: reference.field, line: lines[reference.key] ?? lines[reference.field] ?? 2, message }] : [];
+	});
+}
+export function metadataProblems(document: MetadataDocument, ids: ReadonlyMap<string, readonly MetadataDocument[]>, unavailable: readonly string[]) {
+	const { parsed } = document;
+	const problems = [...parsed.diagnostics, ...criterionProblems(document)];
+	const matches = parsed.fields.id ? ids.get(parsed.fields.id) : undefined;
+	if (matches && matches.length > 1) {
+		problems.push({
+			field: "id",
+			line: parsed.lines.id ?? 2,
+			message: `Duplicate ID ${parsed.fields.id}: ${matches.map((item) => item.file).join(", ")}. No source is selected.`,
+		});
+	}
+	if (unavailable.length > 0) {
+		if (parsed.raw !== undefined) {
+			problems.push({
+				line: 1,
+				message: `Workspace index incomplete; could not read ${unavailable.join(", ")}. Identity and references cannot be validated completely.`,
+			});
+		}
+	} else {
+		problems.push(...referenceProblems(document, ids));
+	}
+	return problems;
+}

package/src/metadata/relationshipLabel.ts

@@ -0,0 +1,13 @@
+const labels = new Map([
+	["board member", "Board membership"],
+	["criterion evidence", "Criterion evidence"],
+	["depends_on", "Depends on"],
+	["evidence source", "Evidence source"],
+	["implements", "Implements"],
+	["informs", "Informs"],
+	["relates_to", "Related to"],
+]);
+
+export function relationshipLabel(kind: string): string {
+	return labels.get(kind) ?? kind;
+}

package/src/metadata/schema.ts

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+
+export const Identity = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*$/u));
+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 Criterion = Schema.Struct({ id: Identity, text: Text });
+const Relationship = Schema.Struct({ kind: Schema.Literals(["implements", "informs", "depends_on", "relates_to"]), target: Reference });
+const Evidence = Schema.Struct({
+	checkedRevision: Schema.optional(Schema.String.check(Schema.isPattern(/^(?:[a-f\d]{40}|[a-f\d]{64})$/iu))),
+	criterion: Schema.optional(Reference),
+	method: Schema.optional(Text),
+	observedAt: Schema.optional(
+		Text.check(
+			Schema.makeFilter(
+				(value) =>
+					(Number.isFinite(Date.parse(value)) && /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/u.exec(value) !== null)
+					|| "Expected an ISO timestamp with timezone",
+			),
+		),
+	),
+	outcome: Schema.optional(Text),
+	source: Text,
+}).pipe(Schema.encodeKeys({ checkedRevision: "checked_revision", observedAt: "observed_at" }));
+
+export const Metadata = Schema.Struct({
+	criteria: Schema.optional(Schema.Array(Criterion)),
+	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"])),
+	nextAction: Schema.optional(Text),
+	owner: Schema.optional(Text),
+	relationships: Schema.optional(Schema.Array(Relationship)),
+	status: Schema.optional(Text),
+}).pipe(Schema.encodeKeys({ nextAction: "next_action" }));
+export type Metadata = typeof Metadata.Type;

package/src/metadata/sourceLinks.ts

@@ -0,0 +1,46 @@
+import { fileUrl } from "#files/url.ts";
+import { referenceTarget } from "./links.ts";
+import type { MetadataModel } from "./model.ts";
+
+const BASE = "http://work-board.local";
+const absolute = /^(?:[a-z][a-z\d+.-]*:|\/\/)/iu;
+
+export function sourceHref(source: string, file: string): string | undefined {
+	try {
+		const url = new URL(source, `${BASE}${fileUrl(file)}`);
+		if (!["http:", "https:"].includes(url.protocol)) {
+			return undefined;
+		}
+		return absolute.exec(source) === null ? url.pathname + url.search + url.hash : url.href;
+	} catch {
+		return undefined;
+	}
+}
+
+export function referenceFile(reference: string, model: MetadataModel): string | undefined {
+	if (!referenceTarget(reference, model)) {
+		return undefined;
+	}
+	return model.ids.get(reference.split("#")[0] ?? "")?.[0]?.file;
+}
+
+export function sourceFile(source: string, file: string, model: MetadataModel): string | undefined {
+	const href = sourceHref(source, file);
+	if (!href?.startsWith("/")) {
+		return undefined;
+	}
+	const url = new URL(href, BASE);
+	try {
+		const path = decodeURIComponent(url.pathname);
+		if (path === "/") {
+			return model.rootFile;
+		}
+		const identity = /^\/_board\/item\/(?<id>[^/]+)\/$/u.exec(path)?.groups?.id;
+		if (identity) {
+			return referenceFile(identity, model);
+		}
+		return /\.md$/iu.exec(path) === null ? undefined : path.slice(1);
+	} catch {
+		return undefined;
+	}
+}

package/src/page/backlinksHtml.ts

@@ -0,0 +1,18 @@
+import { backlinksOf } from "#metadata/backlinks.ts";
+import type { MetadataModel } from "#metadata/model.ts";
+import { relationshipLabel } from "#metadata/relationshipLabel.ts";
+import { escapeHtml } from "./escape.ts";
+import { documentReference } from "./metadataLinks.ts";
+
+export function backlinksHtml(file: string, model: MetadataModel): string {
+	const links = backlinksOf(file, model);
+	if (links.length === 0) {
+		return "";
+	}
+	const entries = [...new Map(links.map((link) => [`${link.file}:${link.kind}:${link.line ?? ""}`, link])).values()];
+	const incomplete =
+		model.unavailable.length > 0
+			? "<p>Available source references only; unreadable files prevent complete backlink and identity validation.</p>"
+			: "";
+	return `<section class="work-context" aria-label="Source backlinks"><details data-key="work-backlinks"><summary>Referenced by (${entries.length})</summary>${incomplete}<ul>${entries.map((link) => `<li>${escapeHtml(relationshipLabel(link.kind))}: <a href="${escapeHtml(documentReference(link.file, model))}">${escapeHtml(link.file)}${link.line === undefined ? "" : `:${link.line}`}</a></li>`).join("")}</ul><p>These are explicit source links, not inferred blockers or workflow rules.</p></details></section>`;
+}