emdash-plugin-sitegraph 0.0.0-stage → 0.1.0

package/src/domain/graph.ts

@@ -0,0 +1,95 @@
+// Platform-neutral graph model. No EmDash, React or storage imports in src/domain/.
+
+export const NODE_TYPES = ["CONTENT", "URL", "FORM", "SERVICE", "WORKFLOW", "TEAM_MEMBER"] as const;
+export type NodeType = (typeof NODE_TYPES)[number];
+
+/** Node types a person can create; CONTENT and URL only come from scans. */
+export const DOCUMENTED_NODE_TYPES = ["FORM", "SERVICE", "WORKFLOW", "TEAM_MEMBER"] as const;
+
+export const RELATION_TYPES = [
+	"PUBLISHES_AS",
+	"LINKS_TO",
+	"SUBMITS_TO",
+	"DEPENDS_ON",
+	"PART_OF",
+	"OWNED_BY",
+	"RELATED_TO",
+] as const;
+export type RelationType = (typeof RELATION_TYPES)[number];
+
+/** Relations a person can document; PUBLISHES_AS and LINKS_TO only come from scans. */
+export const DOCUMENTED_RELATION_TYPES = [
+	"SUBMITS_TO",
+	"DEPENDS_ON",
+	"PART_OF",
+	"OWNED_BY",
+	"RELATED_TO",
+] as const;
+
+// INFERRED is reserved: nothing produces it yet (SPEC D5).
+export type Provenance = "DISCOVERED" | "DOCUMENTED" | "INFERRED";
+
+export const CRITICALITIES = ["LOW", "MEDIUM", "HIGH", "CRITICAL"] as const;
+export type Criticality = (typeof CRITICALITIES)[number];
+
+export const SCHEMA_VERSION = 1;
+
+/** Human context that scans must never overwrite. */
+export interface Annotation {
+	description?: string;
+	criticality?: Criticality;
+	notes?: string;
+	docUrl?: string;
+	lastVerifiedAt?: string;
+}
+
+export interface GraphNode extends Annotation {
+	type: NodeType;
+	label: string;
+	/** Lowercased label, indexed for prefix search. */
+	search: string;
+	/** Stable outside reference: "posts/<id>" for content, the path for URLs. */
+	ref: string;
+	provenance: Provenance;
+	/** URL nodes: true when a published entry lives at this path. */
+	resolved?: boolean;
+	active: boolean;
+	firstSeenAt: string;
+	lastSeenAt: string;
+	schemaVersion: number;
+}
+
+export interface Evidence {
+	sourceId?: string;
+	fieldPath?: string;
+	href?: string;
+	observedAt?: string;
+}
+
+export interface GraphEdge {
+	sourceNodeId: string;
+	targetNodeId: string;
+	relation: RelationType;
+	/** Required for RELATED_TO. */
+	label?: string;
+	provenance: Provenance;
+	evidence?: Evidence;
+	active: boolean;
+	/** Scan that last saw a discovered edge; reconciliation retires the rest. */
+	scanId?: string;
+	firstSeenAt: string;
+	lastSeenAt: string;
+	schemaVersion: number;
+}
+
+export const contentNodeId = (collection: string, entryId: string): string =>
+	`content:${collection}:${entryId}`;
+
+export const urlNodeId = (path: string): string => `url:${path}`;
+
+export const edgeId = (
+	source: string,
+	relation: RelationType,
+	target: string,
+	fieldPath = "",
+): string => `${source}|${relation}|${target}|${fieldPath}`;

package/src/domain/impact.ts

@@ -0,0 +1,102 @@
+import type { GraphEdge } from "./graph.js";
+
+export type Direction = "inbound" | "outbound" | "both";
+
+export const MAX_DEPTH = 3;
+export const MAX_NODES = 500;
+export const MAX_EDGES = 1000;
+
+export interface EdgeRecord extends GraphEdge {
+	id: string;
+}
+
+/** Fetch active edges touching any of the given nodes, in the given direction. */
+export type EdgeFetcher = (nodeIds: string[], direction: "inbound" | "outbound") => Promise<EdgeRecord[]>;
+
+export interface ImpactHit {
+	nodeId: string;
+	depth: number;
+	/** Edges from the start node to this one, in order. */
+	path: EdgeRecord[];
+	/** True when every edge on the path is DISCOVERED or DOCUMENTED. */
+	confirmed: boolean;
+}
+
+export interface ImpactResult {
+	start: string;
+	hits: ImpactHit[];
+	edges: EdgeRecord[];
+	truncated: boolean;
+}
+
+/**
+ * Most relations read "source depends on target" (a page links to a URL, a form submits to a
+ * CRM). PART_OF reads the other way: the workflow depends on its parts. RELATED_TO has no
+ * direction. So "inbound" (what depends on this) walks edges backwards, except PART_OF.
+ */
+function follows(relation: EdgeRecord["relation"], dir: "inbound" | "outbound", direction: "inbound" | "outbound"): boolean {
+	if (relation === "RELATED_TO") return true;
+	const dependencyDir = relation === "PART_OF" ? (dir === "inbound" ? "outbound" : "inbound") : dir;
+	return dependencyDir === direction;
+}
+
+/**
+ * Bounded breadth-first search. "inbound" finds what depends on the start node (what could
+ * break if it changes); "outbound" finds what it depends on. Each node is
+ * reached once, by its shortest path, so cycles end the walk. Reachability is potential
+ * impact, never proof of it.
+ */
+export async function impact(
+	start: string,
+	direction: Direction,
+	depth: number,
+	fetchEdges: EdgeFetcher,
+): Promise<ImpactResult> {
+	const maxDepth = Math.max(1, Math.min(MAX_DEPTH, Math.floor(depth)));
+	const reached = new Map<string, ImpactHit>([[start, { nodeId: start, depth: 0, path: [], confirmed: true }]]);
+	const edges = new Map<string, EdgeRecord>();
+	let frontier = [start];
+	let truncated = false;
+
+	for (let level = 1; level <= maxDepth && frontier.length > 0 && !truncated; level++) {
+		const next: string[] = [];
+		// An entry and its URL are one page: PUBLISHES_AS is walked both ways and costs no
+		// depth, otherwise "inbound from an entry" would spend a hop before reaching linkers.
+		let batch = frontier;
+		while (batch.length > 0 && !truncated) {
+			const samePage: string[] = [];
+			for (const dir of ["outbound", "inbound"] as const) {
+				for (const edge of await fetchEdges(batch, dir)) {
+					const free = edge.relation === "PUBLISHES_AS";
+					if (direction !== "both" && !free && !follows(edge.relation, dir, direction)) continue;
+					const from = dir === "outbound" ? edge.sourceNodeId : edge.targetNodeId;
+					const to = dir === "outbound" ? edge.targetNodeId : edge.sourceNodeId;
+					const parent = reached.get(from);
+					if (!parent) continue;
+					if (edges.size >= MAX_EDGES) {
+						truncated = true;
+						break;
+					}
+					edges.set(edge.id, edge);
+					if (reached.has(to)) continue;
+					if (reached.size >= MAX_NODES) {
+						truncated = true;
+						break;
+					}
+					reached.set(to, {
+						nodeId: to,
+						depth: free ? parent.depth : level,
+						path: [...parent.path, edge],
+						confirmed: parent.confirmed && edge.provenance !== "INFERRED",
+					});
+					(free ? samePage : next).push(to);
+				}
+			}
+			batch = samePage;
+		}
+		frontier = next;
+	}
+
+	reached.delete(start);
+	return { start, hits: [...reached.values()], edges: [...edges.values()], truncated };
+}

package/src/domain/links.ts

@@ -0,0 +1,107 @@
+// Link discovery over stored content. Parses only; never fetches anything (SPEC D3).
+
+export interface FoundLink {
+	href: string;
+	/** Top-level field the link lives in; part of the edge identity. */
+	field: string;
+	/** Full JSON path, kept as evidence. */
+	path: string;
+}
+
+const MAX_DEPTH = 32;
+const UNSAFE_SCHEME = /^\s*(javascript|data|vbscript|file|mailto|tel):/i;
+
+/**
+ * Find links in an entry's data: Portable Text link marks (`{_type: "link", href}`)
+ * anywhere in the tree, plus the values of the given `url`-type fields.
+ * Plain strings that merely look like URLs are ignored on purpose.
+ */
+export function extractLinks(
+	data: Record<string, unknown>,
+	urlFields: readonly string[] = [],
+): FoundLink[] {
+	const found: FoundLink[] = [];
+
+	for (const field of urlFields) {
+		const value = data[field];
+		if (typeof value === "string" && value.trim()) found.push({ href: value.trim(), field, path: field });
+	}
+
+	const walk = (value: unknown, field: string, path: string, depth: number): void => {
+		if (depth > MAX_DEPTH || value === null || typeof value !== "object") return;
+		if (Array.isArray(value)) {
+			value.forEach((item, i) => walk(item, field, `${path}[${i}]`, depth + 1));
+			return;
+		}
+		const obj = value as Record<string, unknown>;
+		if (obj._type === "link" && typeof obj.href === "string" && obj.href.trim()) {
+			found.push({ href: obj.href.trim(), field, path });
+		}
+		for (const [key, child] of Object.entries(obj)) walk(child, field, `${path}.${key}`, depth + 1);
+	};
+	for (const [field, value] of Object.entries(data)) walk(value, field, field, 0);
+
+	return found;
+}
+
+/**
+ * Turn an href into the site-relative path that identifies a page, or null when the
+ * link is external, unsafe or not a page link. Fragments and query strings are dropped
+ * (`/pricing?plan=pro` is the pricing page; the raw href stays in the edge evidence) and
+ * trailing slashes are ignored so "/a/" and "/a" are the same page.
+ */
+export function internalPath(href: string, sourcePath: string, siteUrl: string): string | null {
+	if (UNSAFE_SCHEME.test(href) || href.trim().startsWith("#")) return null;
+	// Relative links resolve against the source page; a placeholder origin stands in when
+	// the site URL isn't configured, and then only relative links can be internal.
+	const origin = siteUrl ? new URL(siteUrl).origin : "http://sitegraph.invalid";
+	let url: URL;
+	try {
+		url = new URL(href, new URL(sourcePath || "/", origin));
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	if (url.origin !== origin) return null;
+	let path = url.pathname.replace(/\/{2,}/g, "/");
+	if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+	return path;
+}
+
+/**
+ * The public path of an entry from its collection's URL pattern, mirroring EmDash's
+ * `interpolateUrlPattern` for `{slug}` and `{id}`. Returns null for patterns using
+ * tokens we don't resolve (dates, locales), so we never invent a wrong URL.
+ */
+export function entryPath(
+	pattern: string | null,
+	collection: string,
+	slug: string,
+	id: string,
+): string | null {
+	const base = pattern ?? `/${encodeURIComponent(collection)}/{slug}`;
+	let path = base.replaceAll("{slug}", encodeURIComponent(slug)).replaceAll("{id}", encodeURIComponent(id));
+	if (path.includes("{")) return null;
+	path = path.replace(/\/{2,}/g, "/");
+	if (!path.startsWith("/")) path = `/${path}`;
+	if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+	return path;
+}
+
+/**
+ * A matcher for paths an entry of this collection could live at, or null when the pattern
+ * uses tokens we don't resolve. Used to tell a broken link (looks like an entry, none is
+ * there) from a link to some other page of the site (home, listings, feeds).
+ */
+export function entryPathMatcher(pattern: string | null, collection: string): RegExp | null {
+	let base = pattern ?? `/${encodeURIComponent(collection)}/{slug}`;
+	if (/\{(?!slug\}|id\})[^}]*\}/.test(base)) return null;
+	base = base.replace(/\/{2,}/g, "/");
+	if (!base.startsWith("/")) base = `/${base}`;
+	if (base.length > 1 && base.endsWith("/")) base = base.slice(0, -1);
+	const source = base
+		.split(/(\{slug\}|\{id\})/)
+		.map((part) => (part === "{slug}" || part === "{id}" ? "[^/]+" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
+		.join("");
+	return new RegExp(`^${source}$`);
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import type { PluginDescriptor, ResolvedPlugin } from "emdash";
+import { definePlugin } from "emdash";
+
+import { routes } from "./routes.js";
+import { refreshFromHook, retireFromHook } from "./scan.js";
+import { STORAGE } from "./store.js";
+
+const ID = "sitegraph";
+const VERSION = "0.1.0";
+const PACKAGE = "emdash-plugin-sitegraph";
+const ADMIN_ENTRY = `${PACKAGE}/admin`;
+
+const PAGES = [{ path: "/", label: "SiteGraph", icon: "graph" }];
+const WIDGETS = [{ id: "overview", title: "SiteGraph", size: "half" as const }];
+
+/** Build-time descriptor: register with `emdash({ plugins: [siteGraph()] })`. */
+export function siteGraph(): PluginDescriptor {
+	return {
+		id: ID,
+		version: VERSION,
+		format: "native",
+		entrypoint: PACKAGE,
+		adminEntry: ADMIN_ENTRY,
+		adminPages: PAGES,
+		adminWidgets: WIDGETS,
+	};
+}
+
+const entryId = (content: Record<string, unknown>): string | null =>
+	typeof content.id === "string" ? content.id : null;
+
+/** Runtime entry. EmDash imports this by name. */
+export function createPlugin(): ResolvedPlugin {
+	return definePlugin({
+		id: ID,
+		version: VERSION,
+		// Read-only by design (SPEC D3): no content writes, no network.
+		capabilities: ["content:read", "schema:read"],
+		storage: STORAGE,
+		admin: { entry: ADMIN_ENTRY, pages: PAGES, widgets: WIDGETS },
+		// Hooks refresh only the one entry that changed (SPEC D8). They run after the
+		// response, so a failure is logged and the next full scan repairs it.
+		hooks: {
+			"content:afterSave": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await refreshFromHook(ctx, event.collection, id);
+			},
+			"content:afterPublish": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await refreshFromHook(ctx, event.collection, id);
+			},
+			"content:afterRestore": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await refreshFromHook(ctx, event.collection, id);
+			},
+			"content:afterUnpublish": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await retireFromHook(ctx, event.collection, id);
+			},
+			"content:afterDelete": async (event, ctx) => {
+				await retireFromHook(ctx, event.collection, event.id);
+			},
+		},
+		routes,
+	});
+}
+
+export default siteGraph;

package/src/routes.ts

@@ -0,0 +1,294 @@
+import { z } from "astro/zod";
+import type { PluginContext, RouteContext } from "emdash";
+import { PluginRouteError } from "emdash";
+
+import {
+	CRITICALITIES,
+	DOCUMENTED_NODE_TYPES,
+	DOCUMENTED_RELATION_TYPES,
+	edgeId,
+	type GraphEdge,
+	type GraphNode,
+	NODE_TYPES,
+	SCHEMA_VERSION,
+} from "./domain/graph.js";
+import { impact, MAX_DEPTH, MAX_EDGES } from "./domain/impact.js";
+import { getScanStatus, scanStep, startScan } from "./scan.js";
+import { activeEdges, edgesOf, nodesOf, queryAll } from "./store.js";
+
+// Reads are for Editors and up (the graph can reveal unpublished structure);
+// anything that changes the graph or runs a scan is admin-only.
+const READ = "plugins:read" as const;
+const MANAGE = "plugins:manage" as const;
+
+const id = z.string().min(1).max(600);
+const text = (max: number) => z.string().trim().max(max);
+const safeUrl = z
+	.string()
+	.trim()
+	.max(2000)
+	.refine((v) => v === "" || /^https?:\/\//i.test(v), "Only http(s) links are allowed");
+
+const annotation = {
+	description: text(2000).optional(),
+	criticality: z.enum(CRITICALITIES).nullable().optional(),
+	notes: text(5000).optional(),
+	docUrl: safeUrl.optional(),
+	lastVerifiedAt: z.iso.datetime().nullable().optional(),
+};
+
+const nodeSaveInput = z.object({
+	id: id.optional(),
+	type: z.enum(DOCUMENTED_NODE_TYPES).optional(),
+	label: text(200).min(1).optional(),
+	...annotation,
+});
+
+const NEIGHBOUR_CAP = 200;
+
+type Ctx<T = unknown> = RouteContext<T>;
+
+async function nodesById(ctx: PluginContext, ids: string[]): Promise<Array<GraphNode & { id: string }>> {
+	const found = await nodesOf(ctx).getMany([...new Set(ids)]);
+	return [...found].map(([nodeId, data]) => ({ id: nodeId, ...data }));
+}
+
+async function requireNode(ctx: PluginContext, nodeId: string) {
+	const node = await nodesOf(ctx).get(nodeId);
+	if (!node || !node.active) throw PluginRouteError.notFound("That node doesn't exist (or a scan retired it).");
+	return node;
+}
+
+/** Copy only the annotation fields that were sent; empty strings and null clear a field. */
+type AnnotationInput = z.infer<z.ZodObject<typeof annotation>>;
+
+function applyAnnotation<T extends object>(target: T, input: AnnotationInput): T {
+	const out = { ...target } as Record<string, unknown>;
+	for (const key of Object.keys(annotation)) {
+		const value = input[key as keyof typeof annotation];
+		if (value === undefined) continue;
+		if (value === "" || value === null) delete out[key];
+		else out[key] = value;
+	}
+	return out as T;
+}
+
+export const routes = {
+	health: {
+		permission: READ,
+		handler: async (ctx: Ctx) => ({ plugin: ctx.plugin.id, version: ctx.plugin.version, siteUrl: ctx.site.url || null }),
+	},
+
+	overview: {
+		permission: READ,
+		handler: async (ctx: Ctx) => {
+			const nodes = nodesOf(ctx);
+			const counts = Object.fromEntries(
+				await Promise.all(NODE_TYPES.map(async (type) => [type, await nodes.count({ type, active: true })] as const)),
+			);
+			return {
+				siteUrl: ctx.site.url || null,
+				counts,
+				edges: await edgesOf(ctx).count({ active: true }),
+				brokenLinks: await nodes.count({ type: "URL", active: true, resolved: false }),
+				scan: await getScanStatus(ctx),
+			};
+		},
+	},
+
+	"scan/start": {
+		permission: MANAGE,
+		handler: async (ctx: Ctx) => ({ state: await startScan(ctx) }),
+	},
+
+	"scan/step": {
+		permission: MANAGE,
+		input: z.object({ scanId: z.string().min(1).max(100) }),
+		handler: async (ctx: Ctx<{ scanId: string }>) => scanStep(ctx, ctx.input.scanId),
+	},
+
+	"nodes/search": {
+		permission: READ,
+		input: z.object({
+			q: text(200).default(""),
+			type: z.enum(NODE_TYPES).optional(),
+			broken: z.boolean().optional(),
+			cursor: z.string().optional(),
+		}),
+		handler: async (ctx: Ctx<{ q: string; type?: GraphNode["type"]; broken?: boolean; cursor?: string }>) => {
+			const { q, type, broken, cursor } = ctx.input;
+			// ponytail: prefix match on the lowercased label (storage has no substring index);
+			// a real search index is the upgrade if people search mid-title.
+			const where: Record<string, string | boolean | { startsWith: string }> = { active: true };
+			if (q) where.search = { startsWith: q.toLowerCase() };
+			if (type) where.type = type;
+			if (broken) Object.assign(where, { type: "URL", resolved: false });
+			const page = await nodesOf(ctx).query({ where, limit: 50, cursor });
+			return { items: page.items.map((row) => ({ id: row.id, ...row.data })), cursor: page.hasMore ? page.cursor : null };
+		},
+	},
+
+	"graph/neighborhood": {
+		permission: READ,
+		input: z.object({ nodeId: id }),
+		handler: async (ctx: Ctx<{ nodeId: string }>) => {
+			const center = await requireNode(ctx, ctx.input.nodeId);
+			const cap = NEIGHBOUR_CAP + 1;
+			const [outbound, inbound] = await Promise.all([
+				activeEdges(ctx, [ctx.input.nodeId], "outbound", cap),
+				activeEdges(ctx, [ctx.input.nodeId], "inbound", cap),
+			]);
+			// An entry and its URL are one page: also show what links to the entry's URL.
+			const ownUrls = outbound.filter((e) => e.relation === "PUBLISHES_AS").map((e) => e.targetNodeId);
+			const linkers = ownUrls.length ? await activeEdges(ctx, ownUrls, "inbound", cap) : [];
+			const all = [...new Map([...outbound, ...inbound, ...linkers].map((e) => [e.id, e])).values()];
+			const edges = all.slice(0, NEIGHBOUR_CAP);
+			const nodes = await nodesById(ctx, edges.flatMap((e) => [e.sourceNodeId, e.targetNodeId]));
+			return {
+				center: { id: ctx.input.nodeId, ...center },
+				nodes,
+				edges,
+				truncated: all.length > edges.length,
+				total: all.length,
+			};
+		},
+	},
+
+	"graph/impact": {
+		permission: READ,
+		input: z.object({
+			nodeId: id,
+			direction: z.enum(["inbound", "outbound", "both"]).default("inbound"),
+			depth: z.number().int().min(1).max(MAX_DEPTH).default(2),
+		}),
+		handler: async (ctx: Ctx<{ nodeId: string; direction: "inbound" | "outbound" | "both"; depth: number }>) => {
+			await requireNode(ctx, ctx.input.nodeId);
+			const result = await impact(ctx.input.nodeId, ctx.input.direction, ctx.input.depth, (ids, dir) =>
+				activeEdges(ctx, ids, dir, MAX_EDGES),
+			);
+			const nodes = await nodesById(ctx, [result.start, ...result.hits.map((h) => h.nodeId)]);
+			return { ...result, nodes };
+		},
+	},
+
+	"nodes/save": {
+		permission: MANAGE,
+		input: nodeSaveInput,
+		handler: async (ctx: Ctx<z.infer<typeof nodeSaveInput>>) => {
+			const nodes = nodesOf(ctx);
+			const now = new Date().toISOString();
+			const { id: nodeId, type, label } = ctx.input;
+
+			if (nodeId) {
+				const existing = await requireNode(ctx, nodeId);
+				// Discovered nodes take annotations only; their type and label come from the site.
+				const renamed = existing.provenance === "DOCUMENTED" && label ? { label, search: label.toLowerCase() } : {};
+				const updated = applyAnnotation({ ...existing, ...renamed }, ctx.input);
+				await nodes.put(nodeId, updated);
+				return { id: nodeId, ...updated };
+			}
+
+			if (!type || !label) throw PluginRouteError.badRequest("A new node needs a type and a label.");
+			const created = applyAnnotation<GraphNode>(
+				{
+					type,
+					label,
+					search: label.toLowerCase(),
+					ref: label,
+					provenance: "DOCUMENTED",
+					active: true,
+					firstSeenAt: now,
+					lastSeenAt: now,
+					schemaVersion: SCHEMA_VERSION,
+				},
+				ctx.input,
+			);
+			const newId = `doc:${crypto.randomUUID()}`;
+			await nodes.put(newId, created);
+			return { id: newId, ...created };
+		},
+	},
+
+	"nodes/delete": {
+		permission: MANAGE,
+		input: z.object({ id }),
+		handler: async (ctx: Ctx<{ id: string }>) => {
+			const node = await requireNode(ctx, ctx.input.id);
+			if (node.provenance !== "DOCUMENTED") {
+				throw PluginRouteError.badRequest("Discovered nodes come from your content. Change the content instead.");
+			}
+			const touching = [
+				...(await queryAll(edgesOf(ctx), { sourceNodeId: ctx.input.id })),
+				...(await queryAll(edgesOf(ctx), { targetNodeId: ctx.input.id })),
+			];
+			await edgesOf(ctx).deleteMany(touching.map((e) => e.id));
+			await nodesOf(ctx).delete(ctx.input.id);
+			return { deleted: ctx.input.id, edgesDeleted: touching.length };
+		},
+	},
+
+	"edges/save": {
+		permission: MANAGE,
+		input: z.object({
+			sourceNodeId: id,
+			targetNodeId: id,
+			relation: z.enum(DOCUMENTED_RELATION_TYPES),
+			label: text(200).optional(),
+		}),
+		handler: async (
+			ctx: Ctx<{ sourceNodeId: string; targetNodeId: string; relation: GraphEdge["relation"]; label?: string }>,
+		) => {
+			const { sourceNodeId, targetNodeId, relation, label } = ctx.input;
+			if (sourceNodeId === targetNodeId) throw PluginRouteError.badRequest("A node can't depend on itself.");
+			if (relation === "RELATED_TO" && !label) {
+				throw PluginRouteError.badRequest("Say how they're related: RELATED_TO needs a label.");
+			}
+			await requireNode(ctx, sourceNodeId);
+			await requireNode(ctx, targetNodeId);
+			const now = new Date().toISOString();
+			const edgeKey = edgeId(sourceNodeId, relation, targetNodeId, "doc");
+			const existing = await edgesOf(ctx).get(edgeKey);
+			const edge: GraphEdge = {
+				sourceNodeId,
+				targetNodeId,
+				relation,
+				...(label ? { label } : {}),
+				provenance: "DOCUMENTED",
+				evidence: { observedAt: now, ...(ctx.user?.id ? { sourceId: `user:${ctx.user.id}` } : {}) },
+				active: true,
+				firstSeenAt: existing?.firstSeenAt ?? now,
+				lastSeenAt: now,
+				schemaVersion: SCHEMA_VERSION,
+			};
+			await edgesOf(ctx).put(edgeKey, edge);
+			return { id: edgeKey, ...edge };
+		},
+	},
+
+	"edges/delete": {
+		permission: MANAGE,
+		input: z.object({ id }),
+		handler: async (ctx: Ctx<{ id: string }>) => {
+			const edge = await edgesOf(ctx).get(ctx.input.id);
+			if (!edge) throw PluginRouteError.notFound("That relationship doesn't exist.");
+			if (edge.provenance !== "DOCUMENTED") {
+				throw PluginRouteError.badRequest("Discovered links come from your content. Edit the content instead.");
+			}
+			await edgesOf(ctx).delete(ctx.input.id);
+			return { deleted: ctx.input.id };
+		},
+	},
+
+	export: {
+		permission: READ,
+		handler: async (ctx: Ctx) => ({
+			format: "sitegraph",
+			schemaVersion: SCHEMA_VERSION,
+			plugin: { id: ctx.plugin.id, version: ctx.plugin.version },
+			site: ctx.site.url || null,
+			exportedAt: new Date().toISOString(),
+			nodes: (await queryAll(nodesOf(ctx), { active: true })).map((r) => ({ id: r.id, ...r.data })),
+			edges: (await queryAll(edgesOf(ctx), { active: true })).map((r) => ({ id: r.id, ...r.data })),
+		}),
+	},
+};