logseq-graph-living-atlas 0.1.0

package/server/contracts.mjs

@@ -0,0 +1,346 @@
+export const SNAPSHOT_VERSION = 1;
+export const CACHE_VERSION = 1;
+
+export function validateSnapshot(snapshot, context = "snapshot") {
+  assertObject(snapshot, context);
+  assertEqual(snapshot.version, SNAPSHOT_VERSION, `${context}.version`);
+  assertString(snapshot.generatedAt, `${context}.generatedAt`);
+  assertObject(snapshot.totals, `${context}.totals`);
+  for (const key of ["pages", "nodes", "links", "dangling", "clusters", "active24h", "active7d"]) {
+    assertNumber(snapshot.totals[key], `${context}.totals.${key}`);
+  }
+  assertArray(snapshot.nodes, `${context}.nodes`);
+  assertArray(snapshot.links, `${context}.links`);
+  assertArray(snapshot.clusters, `${context}.clusters`);
+  assertArray(snapshot.insights, `${context}.insights`);
+  assertObject(snapshot.health, `${context}.health`);
+  for (const [index, node] of snapshot.nodes.entries()) validateNode(node, `${context}.nodes[${index}]`);
+  for (const [index, link] of snapshot.links.entries()) validateLink(link, `${context}.links[${index}]`);
+  for (const [index, cluster] of snapshot.clusters.entries()) validateCluster(cluster, `${context}.clusters[${index}]`);
+  for (const [index, insight] of snapshot.insights.entries()) validateInsight(insight, `${context}.insights[${index}]`);
+  return snapshot;
+}
+
+export function validateApiSnapshot(snapshot, context = "api.snapshot") {
+  validateSnapshot(snapshot, context);
+  assertObject(snapshot.graph, `${context}.graph`);
+  assertString(snapshot.graph.id, `${context}.graph.id`);
+  assertString(snapshot.graph.fingerprint, `${context}.graph.fingerprint`);
+  assertNumber(snapshot.graph.pages, `${context}.graph.pages`);
+  return snapshot;
+}
+
+export function validateHealth(payload, context = "health") {
+  assertObject(payload, context);
+  assertBoolean(payload.ok, `${context}.ok`);
+  assertString(payload.generatedAt, `${context}.generatedAt`);
+  assertObject(payload.totals, `${context}.totals`);
+  assertObject(payload.cache, `${context}.cache`);
+  assertBoolean(payload.cache.configured, `${context}.cache.configured`);
+  assertBoolean(payload.cache.hit, `${context}.cache.hit`);
+  validateManifest(payload.manifest, `${context}.manifest`);
+  assertBoolean(payload.watch, `${context}.watch`);
+  assertString(payload.bindHost, `${context}.bindHost`);
+  assertBoolean(payload.localOnly, `${context}.localOnly`);
+  if (payload.requireToken !== undefined) assertBoolean(payload.requireToken, `${context}.requireToken`);
+  return payload;
+}
+
+export function validateDelta(delta, context = "delta") {
+  assertObject(delta, context);
+  assertEqual(delta.type, "graph_delta", `${context}.type`);
+  assertString(delta.generatedAt, `${context}.generatedAt`);
+  for (const key of ["addedNodes", "changedNodes", "removedNodes"]) {
+    assertArray(delta[key], `${context}.${key}`);
+    delta[key].forEach((node, index) => validateNode(node, `${context}.${key}[${index}]`));
+  }
+  for (const key of ["addedLinks", "removedLinks"]) {
+    assertArray(delta[key], `${context}.${key}`);
+    delta[key].forEach((link, index) => validateLink(link, `${context}.${key}[${index}]`));
+  }
+  assertArray(delta.insights, `${context}.insights`);
+  assertObject(delta.totals, `${context}.totals`);
+  if (delta.changeCounts !== undefined) {
+    assertObject(delta.changeCounts, `${context}.changeCounts`);
+    for (const key of ["addedNodes", "changedNodes", "removedNodes", "addedLinks", "removedLinks"]) {
+      assertNumber(delta.changeCounts[key], `${context}.changeCounts.${key}`);
+    }
+  }
+  if (delta.events !== undefined) {
+    assertArray(delta.events, `${context}.events`);
+    delta.events.forEach((event, index) => validateLiveEvent(event, `${context}.events[${index}]`));
+  }
+  if (delta.eventSeq !== undefined) assertNumber(delta.eventSeq, `${context}.eventSeq`);
+  if (delta.eventsOmitted !== undefined) assertNumber(delta.eventsOmitted, `${context}.eventsOmitted`);
+  if (delta.reason !== undefined) assertString(delta.reason, `${context}.reason`);
+  return delta;
+}
+
+export function validateFocusResult(result, context = "focus") {
+  assertObject(result, context);
+  assertBoolean(result.ok, `${context}.ok`);
+  if (!result.ok) {
+    assertString(result.error, `${context}.error`);
+    assertString(result.query, `${context}.query`);
+    return result;
+  }
+  assertString(result.focusKind, `${context}.focusKind`);
+  if (result.seed !== null) validateNode(result.seed, `${context}.seed`);
+  if (result.cluster !== undefined) validateCluster(result.cluster, `${context}.cluster`);
+  assertNumber(result.radius, `${context}.radius`);
+  assertArray(result.nodes, `${context}.nodes`);
+  assertArray(result.links, `${context}.links`);
+  assertBoolean(result.limited, `${context}.limited`);
+  assertNumber(result.totalMatches, `${context}.totalMatches`);
+  assertArray(result.insights, `${context}.insights`);
+  result.nodes.forEach((node, index) => validateNode(node, `${context}.nodes[${index}]`));
+  result.links.forEach((link, index) => validateLink(link, `${context}.links[${index}]`));
+  return result;
+}
+
+export function validatePathResult(result, context = "path") {
+  assertObject(result, context);
+  assertBoolean(result.ok, `${context}.ok`);
+  if (!result.ok) {
+    assertString(result.error, `${context}.error`);
+    if (result.missing !== undefined) assertArray(result.missing, `${context}.missing`);
+    if (result.maxDepth !== undefined) assertNumber(result.maxDepth, `${context}.maxDepth`);
+    if (result.explored !== undefined) assertNumber(result.explored, `${context}.explored`);
+    return result;
+  }
+  validateNode(result.from, `${context}.from`);
+  validateNode(result.to, `${context}.to`);
+  assertNumber(result.depth, `${context}.depth`);
+  assertArray(result.nodes, `${context}.nodes`);
+  assertArray(result.links, `${context}.links`);
+  assertArray(result.steps, `${context}.steps`);
+  assertString(result.summary, `${context}.summary`);
+  result.nodes.forEach((node, index) => validateNode(node, `${context}.nodes[${index}]`));
+  result.links.forEach((link, index) => validateLink(link, `${context}.links[${index}]`));
+  result.steps.forEach((step, index) => validatePathStep(step, `${context}.steps[${index}]`));
+  if (result.routeScore !== undefined) validateRouteScore(result.routeScore, `${context}.routeScore`);
+  if (result.alternateRoutes !== undefined) assertArray(result.alternateRoutes, `${context}.alternateRoutes`);
+  return result;
+}
+
+export function validateNodeDetail(result, context = "nodeDetail") {
+  assertObject(result, context);
+  assertBoolean(result.ok, `${context}.ok`);
+  if (!result.ok) {
+    assertString(result.error, `${context}.error`);
+    assertString(result.query, `${context}.query`);
+    return result;
+  }
+  validateNode(result.node, `${context}.node`);
+  assertObject(result.source, `${context}.source`);
+  assertString(result.source.relativePath, `${context}.source.relativePath`);
+  assertString(result.source.updatedAt, `${context}.source.updatedAt`);
+  assertObject(result.source.properties, `${context}.source.properties`);
+  assertString(result.source.preview, `${context}.source.preview`);
+  for (const key of ["backlinks", "outlinks"]) {
+    assertArray(result[key], `${context}.${key}`);
+    result[key].forEach((entry, index) => validateNodeEdge(entry, `${context}.${key}[${index}]`));
+  }
+  for (const key of ["backlinksTotal", "outlinksTotal", "edgeLimit"]) {
+    if (result[key] !== undefined) assertNumber(result[key], `${context}.${key}`);
+  }
+  assertArray(result.insights, `${context}.insights`);
+  assertObject(result.xray, `${context}.xray`);
+  assertString(result.xray.kind, `${context}.xray.kind`);
+  if (result.xray.parent !== null) assertObject(result.xray.parent, `${context}.xray.parent`);
+  if (result.xray.cluster !== null) validateCluster(result.xray.cluster, `${context}.xray.cluster`);
+  assertNumber(result.xray.staleDays, `${context}.xray.staleDays`);
+  assertArray(result.xray.proofDebt, `${context}.xray.proofDebt`);
+  assertArray(result.xray.strongest, `${context}.xray.strongest`);
+  assertArray(result.xray.signalSummary, `${context}.xray.signalSummary`);
+  return result;
+}
+
+export function validateConnectorResult(result, context = "connectors") {
+  assertObject(result, context);
+  assertBoolean(result.ok, `${context}.ok`);
+  assertString(result.generatedAt, `${context}.generatedAt`);
+  assertArray(result.candidates, `${context}.candidates`);
+  result.candidates.forEach((candidate, index) => validateConnectorCandidate(candidate, `${context}.candidates[${index}]`));
+  return result;
+}
+
+export function validateSearchResult(result, context = "search") {
+  assertObject(result, context);
+  assertBoolean(result.ok, `${context}.ok`);
+  assertString(result.generatedAt, `${context}.generatedAt`);
+  assertString(result.query, `${context}.query`);
+  assertNumber(result.totalMatches, `${context}.totalMatches`);
+  assertNumber(result.omitted, `${context}.omitted`);
+  assertArray(result.results, `${context}.results`);
+  result.results.forEach((node, index) => validateNode(node, `${context}.results[${index}]`));
+  return result;
+}
+
+export function validateRecords(records, context = "records") {
+  assertArray(records, context);
+  for (const [index, record] of records.entries()) {
+    const pointer = `${context}[${index}]`;
+    assertObject(record, pointer);
+    assertString(record.id, `${pointer}.id`);
+    assertString(record.name, `${pointer}.name`);
+    assertString(record.path, `${pointer}.path`);
+    assertArray(record.out, `${pointer}.out`);
+    assertObject(record.props, `${pointer}.props`);
+  }
+  return records;
+}
+
+export function validateManifest(manifest, context = "manifest") {
+  assertObject(manifest, context);
+  assertNumber(manifest.pages, `${context}.pages`);
+  if (manifest.graphId !== undefined) assertString(manifest.graphId, `${context}.graphId`);
+  assertString(manifest.fingerprint, `${context}.fingerprint`);
+  assertNumber(manifest.maxMtimeMs, `${context}.maxMtimeMs`);
+  return manifest;
+}
+
+export function validateCacheEnvelope(envelope, expectedManifest = null) {
+  assertObject(envelope, "cache");
+  assertEqual(envelope.version, CACHE_VERSION, "cache.version");
+  assertString(envelope.writtenAt, "cache.writtenAt");
+  validateManifest(envelope.manifest, "cache.manifest");
+  if (expectedManifest && envelope.manifest.fingerprint !== expectedManifest.fingerprint) {
+    throw new ContractError("cache.manifest.fingerprint does not match current graph fingerprint");
+  }
+  validateSnapshot(envelope.snapshot, "cache.snapshot");
+  validateRecords(envelope.records, "cache.records");
+  return envelope;
+}
+
+export function createCacheEnvelope(payload) {
+  validateManifest(payload.manifest);
+  validateSnapshot(payload.snapshot);
+  validateRecords(payload.records);
+  return {
+    version: CACHE_VERSION,
+    writtenAt: new Date().toISOString(),
+    manifest: payload.manifest,
+    snapshot: payload.snapshot,
+    records: payload.records
+  };
+}
+
+export class ContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractError";
+  }
+}
+
+function validateNode(node, context) {
+  assertObject(node, context);
+  for (const key of ["id", "name", "type", "status", "source", "confidence", "updatedAt", "cluster", "clusterLabel", "color"]) {
+    assertString(node[key], `${context}.${key}`);
+  }
+  for (const key of ["in", "out", "total", "x", "y", "z", "size", "heat"]) {
+    assertNumber(node[key], `${context}.${key}`);
+  }
+  assertArray(node.tags, `${context}.tags`);
+}
+
+function validateLink(link, context) {
+  assertObject(link, context);
+  for (const key of ["id", "source", "target", "kind"]) assertString(link[key], `${context}.${key}`);
+  if (link.weight !== undefined) assertNumber(link.weight, `${context}.weight`);
+}
+
+function validateCluster(cluster, context) {
+  assertObject(cluster, context);
+  for (const key of ["id", "label"]) assertString(cluster[key], `${context}.${key}`);
+  for (const key of ["count", "degree", "bridges", "heat"]) assertNumber(cluster[key], `${context}.${key}`);
+}
+
+function validateConnectorCandidate(candidate, context) {
+  assertObject(candidate, context);
+  assertString(candidate.id, `${context}.id`);
+  validateCluster(candidate.fromCluster, `${context}.fromCluster`);
+  validateCluster(candidate.toCluster, `${context}.toCluster`);
+  for (const key of ["linkCount", "expected", "score"]) assertNumber(candidate[key], `${context}.${key}`);
+  assertString(candidate.rationale, `${context}.rationale`);
+  assertArray(candidate.nodeIds, `${context}.nodeIds`);
+  assertArray(candidate.anchors, `${context}.anchors`);
+  candidate.anchors.forEach((anchor, index) => {
+    const pointer = `${context}.anchors[${index}]`;
+    assertObject(anchor, pointer);
+    for (const key of ["id", "name", "cluster"]) assertString(anchor[key], `${pointer}.${key}`);
+    for (const key of ["degree", "heat", "debt"]) assertNumber(anchor[key], `${pointer}.${key}`);
+  });
+}
+
+function validateInsight(insight, context) {
+  assertObject(insight, context);
+  for (const key of ["id", "severity", "title", "detail"]) assertString(insight[key], `${context}.${key}`);
+  assertNumber(insight.metric, `${context}.metric`);
+  assertArray(insight.nodeIds, `${context}.nodeIds`);
+  assertArray(insight.provenance, `${context}.provenance`);
+  if (insight.action !== undefined) {
+    assertObject(insight.action, `${context}.action`);
+    for (const key of ["kind", "label", "target", "rationale", "nextStep"]) assertString(insight.action[key], `${context}.action.${key}`);
+  }
+}
+
+function validateLiveEvent(event, context) {
+  assertObject(event, context);
+  assertString(event.id, `${context}.id`);
+  assertNumber(event.seq, `${context}.seq`);
+  assertString(event.kind, `${context}.kind`);
+  assertString(event.reason, `${context}.reason`);
+  assertString(event.observedAt, `${context}.observedAt`);
+  assertString(event.actor, `${context}.actor`);
+  for (const key of ["nodeId", "nodeName", "sourceId", "targetId", "linkId", "cluster", "color"]) {
+    if (event[key] !== undefined) assertString(event[key], `${context}.${key}`);
+  }
+  for (const key of ["x", "y", "z", "weight"]) {
+    if (event[key] !== undefined) assertNumber(event[key], `${context}.${key}`);
+  }
+}
+
+function validateNodeEdge(entry, context) {
+  assertObject(entry, context);
+  assertString(entry.linkId, `${context}.linkId`);
+  if (entry.weight !== undefined) assertNumber(entry.weight, `${context}.weight`);
+  validateNode(entry.node, `${context}.node`);
+}
+
+function validatePathStep(step, context) {
+  assertObject(step, context);
+  for (const key of ["from", "to", "linkId", "direction", "evidence"]) assertString(step[key], `${context}.${key}`);
+}
+
+function validateRouteScore(score, context) {
+  assertObject(score, context);
+  assertString(score.label, `${context}.label`);
+  for (const key of ["score", "hops", "clusters", "freshness", "proofDebt", "linkEvidence"]) {
+    assertNumber(score[key], `${context}.${key}`);
+  }
+}
+
+function assertObject(value, context) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ContractError(`${context} must be an object`);
+}
+
+function assertArray(value, context) {
+  if (!Array.isArray(value)) throw new ContractError(`${context} must be an array`);
+}
+
+function assertString(value, context) {
+  if (typeof value !== "string") throw new ContractError(`${context} must be a string`);
+}
+
+function assertNumber(value, context) {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new ContractError(`${context} must be a finite number`);
+}
+
+function assertBoolean(value, context) {
+  if (typeof value !== "boolean") throw new ContractError(`${context} must be a boolean`);
+}
+
+function assertEqual(value, expected, context) {
+  if (value !== expected) throw new ContractError(`${context} must be ${expected}`);
+}

package/server/fixture/create-fixture-graph.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "../..");
+const FIXTURE_MARKER = ".living-atlas-fixture";
+
+export function createFixtureGraph(options = {}) {
+  const root = path.resolve(options.out || fs.mkdtempSync(path.join(os.tmpdir(), "living-atlas-fixture-")));
+  prepareFixtureDirectory(root);
+  const pages = path.join(root, "pages");
+  const journals = path.join(root, "journals");
+  fs.mkdirSync(pages, { recursive: true });
+  fs.mkdirSync(journals, { recursive: true });
+  fs.writeFileSync(path.join(root, FIXTURE_MARKER), "Generated by logseq-graph-living-atlas.\n", "utf8");
+
+  const writePage = (name, body, mtimeOffsetHours = 0) => {
+    const filePath = path.join(pages, `${name}.md`);
+    fs.writeFileSync(filePath, body, "utf8");
+    touch(filePath, mtimeOffsetHours);
+  };
+
+  const writeJournal = (name, body, mtimeOffsetHours = 0) => {
+    const filePath = path.join(journals, `${name}.md`);
+    fs.writeFileSync(filePath, body, "utf8");
+    touch(filePath, mtimeOffsetHours);
+  };
+
+  writePage("Nexus", "type:: organization\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Atlas]] [[Project Orion]] [[Signal Desk]]\n", 1);
+  writePage("Atlas", "type:: project\ncompany:: [[Nexus]]\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Nexus]] [[Signal Desk]] [[Data Pipeline]]\n", 2);
+  writePage("Project Orion", "type:: project\ncompany:: [[Nexus]]\nstatus:: active\nsource:: fixture\nconfidence:: medium\n- [[Nexus]] [[Field Study]] [[Signal Desk]]\n", 3);
+  writePage("Field Study", "type:: project\nstatus:: active\nsource:: fixture\nconfidence:: medium\n- [[Project Orion]] [[Atlas]]\n", 8);
+  writePage("Signal Desk", "type:: infrastructure\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Atlas]] [[Nexus]] [[Data Pipeline]]\n", 5);
+  writePage("Data Pipeline", "type:: infrastructure\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Signal Desk]] [[Atlas]]\n", 9);
+  writePage("Person One", "type:: person\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Nexus]] [[Atlas]]\n", 18);
+  writePage("Person Two", "type:: person\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Nexus]] [[Project Orion]]\n", 28);
+  writePage("Operations Hub", "type:: service\nstatus:: active\nsource:: fixture\nconfidence:: high\n- [[Signal Desk]] [[Data Pipeline]]\n", 12);
+  writePage("Unresolved Target Note", "type:: note\nstatus:: draft\n- [[Missing Reference]]\n", 200);
+
+  for (let index = 0; index < 34; index += 1) {
+    const anchor = index % 3 === 0 ? "Atlas" : index % 3 === 1 ? "Nexus" : "Project Orion";
+    const previous = index > 0 ? `[[Research Note ${index - 1}]]` : `[[${anchor}]]`;
+    writePage(
+      `Research Note ${index}`,
+      `type:: project\ntags:: [[${anchor}]]\nstatus:: ${index % 4 === 0 ? "draft" : "active"}\nsource:: fixture\nconfidence:: ${index % 5 === 0 ? "low" : "medium"}\n- [[${anchor}]] ${previous}\n`,
+      24 + index * 8
+    );
+  }
+
+  for (let index = 0; index < 18; index += 1) {
+    writePage(
+      `Operations Log ${index}`,
+      `type:: service\ntags:: [[Operations Hub]]\nstatus:: active\nsource:: fixture\nconfidence:: medium\n- [[Operations Hub]] [[Signal Desk]]\n`,
+      72 + index * 12
+    );
+  }
+
+  writeJournal("2026_05_30", "- Fixture journal for Living Atlas tests.\n- [[Atlas]] reviewed [[Signal Desk]].\n", 6);
+  writeJournal("2026_05_31", "- [[Project Orion]] generated a new [[Field Study]] follow-up.\n", 4);
+
+  return root;
+}
+
+function prepareFixtureDirectory(root) {
+  assertSafeFixtureOutput(root);
+  if (!fs.existsSync(root)) return;
+  if (isDirectoryEmpty(root)) {
+    fs.rmSync(root, { recursive: true, force: true });
+    return;
+  }
+  const markerPath = path.join(root, FIXTURE_MARKER);
+  if (!fs.existsSync(markerPath)) {
+    throw new Error(`Refusing to overwrite ${root}; missing ${FIXTURE_MARKER} marker.`);
+  }
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+function assertSafeFixtureOutput(root) {
+  const parsed = path.parse(root);
+  const dangerous = new Set([parsed.root, os.homedir(), repoRoot, path.dirname(repoRoot)]);
+  if (dangerous.has(root)) {
+    throw new Error(`Refusing dangerous fixture output path: ${root}`);
+  }
+}
+
+function isDirectoryEmpty(root) {
+  return fs.statSync(root).isDirectory() && fs.readdirSync(root).length === 0;
+}
+
+function touch(filePath, mtimeOffsetHours) {
+  const time = new Date(Date.now() - mtimeOffsetHours * 36e5);
+  fs.utimesSync(filePath, time, time);
+}
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--out") {
+      parsed.out = argv[index + 1];
+      index += 1;
+    }
+  }
+  return parsed;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const args = parseArgs(process.argv.slice(2));
+  const out = args.out ? path.resolve(repoRoot, args.out) : undefined;
+  const root = createFixtureGraph({ out });
+  console.log(root);
+}

package/server/graph/pathfinding.mjs

@@ -0,0 +1,155 @@
+import { buildAdjacency, findNode, round } from "./utils.mjs";
+import { proofDebtFor } from "./quality.mjs";
+
+export function pathSnapshot(snapshot, fromQuery, toQuery, maxDepth = 7, runtime = null) {
+  const from = findNode(snapshot.nodes, fromQuery);
+  const to = findNode(snapshot.nodes, toQuery);
+  if (!from || !to) {
+    return {
+      ok: false,
+      error: "endpoint not found",
+      from: fromQuery,
+      to: toQuery,
+      missing: [!from ? "from" : null, !to ? "to" : null].filter(Boolean)
+    };
+  }
+  if (from.id === to.id) {
+    return { ok: true, from, to, depth: 0, nodes: [from], links: [], steps: [], summary: `${from.name} is the same page.` };
+  }
+
+  const { adjacency, edgeLookup } = runtime?.adjacency && runtime?.edgeLookup
+    ? runtime
+    : buildAdjacency(snapshot.links);
+  const paths = findBoundedPaths(adjacency, from.id, to.id, maxDepth, 4);
+  const nodeMap = runtime?.nodeById || new Map(snapshot.nodes.map((node) => [node.id, node]));
+  const rankedRoutes = paths
+    .map((path, index) => ({ index, path, payload: pathPayload(path, nodeMap, edgeLookup) }))
+    .sort((a, b) => b.payload.routeScore.score - a.payload.routeScore.score || a.payload.routeScore.hops - b.payload.routeScore.hops || a.index - b.index);
+  const primaryRoute = rankedRoutes[0] || null;
+  const resolved = primaryRoute?.path || null;
+
+  if (!resolved) {
+    return {
+      ok: false,
+      error: "no path within depth",
+      from,
+      to,
+      maxDepth,
+      explored: countReachable(adjacency, from.id, maxDepth)
+    };
+  }
+
+  const primary = primaryRoute.payload;
+  const alternateRoutes = rankedRoutes
+    .slice(1)
+    .map((route, index) => {
+      const { path, payload } = route;
+      return {
+        id: `alt-${index + 1}-${path.join("-")}`,
+        nodes: payload.nodes.map((node) => node.name),
+        score: payload.routeScore
+      };
+    });
+
+  return {
+    ok: true,
+    from,
+    to,
+    depth: resolved.length - 1,
+    nodes: primary.nodes,
+    links: primary.links,
+    steps: primary.steps,
+    routeScore: primary.routeScore,
+    alternateRoutes,
+    summary: `${from.name} connects to ${to.name} through ${resolved.length - 1} graph hop${resolved.length === 2 ? "" : "s"}.`
+  };
+}
+
+function pathPayload(resolved, nodeMap, edgeLookup) {
+  const nodes = resolved.map((id) => nodeMap.get(id)).filter(Boolean);
+  const links = [];
+  const steps = [];
+  for (let index = 0; index < resolved.length - 1; index += 1) {
+    const a = resolved[index];
+    const b = resolved[index + 1];
+    const edge = edgeLookup.get(`${a}|${b}`);
+    if (edge) links.push(edge);
+    const source = nodeMap.get(a);
+    const target = nodeMap.get(b);
+    steps.push({
+      from: source?.name || a,
+      to: target?.name || b,
+      linkId: edge?.id || `${a}->${b}`,
+      direction: edge?.source === a ? "outbound" : "backlink",
+      evidence: edge?.source === a
+        ? `${source?.name || a} links to ${target?.name || b}`
+        : `${target?.name || b} links back to ${source?.name || a}`
+    });
+  }
+  return {
+    nodes,
+    links,
+    steps,
+    routeScore: scoreRoute(nodes, links)
+  };
+}
+
+function findBoundedPaths(adjacency, fromId, toId, maxDepth, limit = 4) {
+  const maxHops = Math.max(1, Math.floor(Number(maxDepth || 7)));
+  const maxPaths = Math.max(1, Math.floor(Number(limit || 4)));
+  const queue = [[fromId]];
+  const paths = [];
+  let expansions = 0;
+  while (queue.length && paths.length < maxPaths && expansions < 6000) {
+    const path = queue.shift();
+    const current = path[path.length - 1];
+    expansions += 1;
+    if (path.length - 1 >= maxHops) continue;
+    const neighbors = [...(adjacency.get(current) || [])].sort();
+    for (const neighbor of neighbors) {
+      if (path.includes(neighbor)) continue;
+      const nextPath = [...path, neighbor];
+      if (neighbor === toId) {
+        paths.push(nextPath);
+        if (paths.length >= maxPaths) break;
+        continue;
+      }
+      queue.push(nextPath);
+    }
+  }
+  return paths;
+}
+
+function countReachable(adjacency, fromId, maxDepth) {
+  const maxHops = Math.max(1, Math.floor(Number(maxDepth || 7)));
+  const queue = [{ id: fromId, depth: 0 }];
+  const visited = new Set([fromId]);
+  while (queue.length) {
+    const current = queue.shift();
+    if (current.depth >= maxHops) continue;
+    for (const neighbor of adjacency.get(current.id) || []) {
+      if (visited.has(neighbor)) continue;
+      visited.add(neighbor);
+      queue.push({ id: neighbor, depth: current.depth + 1 });
+    }
+  }
+  return visited.size;
+}
+
+function scoreRoute(nodes, links) {
+  const avgHeat = nodes.length ? nodes.reduce((sum, node) => sum + node.heat, 0) / nodes.length : 0;
+  const avgDegree = nodes.length ? nodes.reduce((sum, node) => sum + node.total, 0) / nodes.length : 0;
+  const clusterCount = new Set(nodes.map((node) => node.cluster)).size;
+  const proofDebt = nodes.reduce((sum, node) => sum + proofDebtFor(node).length, 0);
+  const hopPenalty = Math.max(0, nodes.length - 2) * 4;
+  const score = Math.round(Math.max(1, Math.min(100, 34 + avgHeat * 26 + Math.sqrt(avgDegree) * 7 + clusterCount * 4 - proofDebt * 3 - hopPenalty)));
+  return {
+    score,
+    label: score >= 78 ? "strong path" : score >= 56 ? "usable path" : "thin path",
+    hops: Math.max(0, nodes.length - 1),
+    clusters: clusterCount,
+    freshness: round(avgHeat),
+    proofDebt,
+    linkEvidence: links.length
+  };
+}

package/server/graph/quality.mjs

@@ -0,0 +1,11 @@
+export const META_TYPES = new Set(["schema", "query", "runbook", "glossary"]);
+
+export function proofDebtFor(node) {
+  const debt = [];
+  if (!node.source) debt.push({ severity: "high", label: "missing source" });
+  if (!node.confidence || node.confidence.toLowerCase() === "low") debt.push({ severity: "medium", label: `confidence ${node.confidence || "missing"}` });
+  if (!node.status) debt.push({ severity: "medium", label: "missing status" });
+  if (node.total <= 1 && !META_TYPES.has(node.type) && node.type !== "redirect") debt.push({ severity: "medium", label: "few trusted links" });
+  if (Date.now() - Date.parse(node.updatedAt || new Date()) > 45 * 86400000) debt.push({ severity: "low", label: "cooling knowledge" });
+  return debt;
+}

package/server/graph/utils.mjs

@@ -0,0 +1,25 @@
+import { slugify } from "../logseq/parser.mjs";
+
+export function findNode(nodes, query) {
+  const q = slugify(query);
+  if (!q) return null;
+  return nodes.find((node) => node.id === q) || nodes.find((node) => node.name.toLowerCase().includes(q)) || null;
+}
+
+export function buildAdjacency(links) {
+  const adjacency = new Map();
+  const edgeLookup = new Map();
+  for (const link of links) {
+    if (!adjacency.has(link.source)) adjacency.set(link.source, new Set());
+    if (!adjacency.has(link.target)) adjacency.set(link.target, new Set());
+    adjacency.get(link.source).add(link.target);
+    adjacency.get(link.target).add(link.source);
+    edgeLookup.set(`${link.source}|${link.target}`, link);
+    edgeLookup.set(`${link.target}|${link.source}`, link);
+  }
+  return { adjacency, edgeLookup };
+}
+
+export function round(value) {
+  return Math.round(value * 1000) / 1000;
+}