@treeseed/sdk 0.1.2 → 0.3.1

package/dist/graph/build.js

@@ -0,0 +1,949 @@
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import GithubSlugger from "github-slugger";
+import { toString } from "mdast-util-to-string";
+import { unified } from "unified";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { parseFrontmatterDocument } from "../frontmatter.js";
+import { resolveModelDefinition } from "../model-registry.js";
+import { readCanonicalFieldValue } from "../sdk-fields.js";
+import {
+  AUTHORED_GRAPH_EDGE_TYPES,
+  computeEdgeId,
+  computeModelSignature,
+  createEntityNodeId,
+  createFileNodeId,
+  emptyGraphMetrics,
+  emptyGraphValidation,
+  ensureArray,
+  graphSnapshotRoot,
+  normalizeText,
+  resolveGraphModelConfig,
+  GRAPH_SNAPSHOT_VERSION,
+  sha1
+} from "./schema.js";
+const markdownProcessor = unified().use(remarkParse).use(remarkMdx);
+async function walkMarkdownFiles(root) {
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    const children = await Promise.all(entries.map(async (entry) => {
+      const fullPath = path.join(root, entry.name);
+      if (entry.isDirectory()) {
+        return walkMarkdownFiles(fullPath);
+      }
+      if (entry.isFile() && /\.(md|mdx)$/iu.test(entry.name)) {
+        return [fullPath];
+      }
+      return [];
+    }));
+    return children.flat();
+  } catch {
+    return [];
+  }
+}
+function stripMarkdownExtension(value) {
+  return value.replace(/\.(md|mdx)$/iu, "");
+}
+function inferSlug(filePath, root) {
+  return stripMarkdownExtension(path.relative(root, filePath).replace(/\\/gu, "/"));
+}
+function readGraphField(definition, frontmatter, field) {
+  const binding = definition.fields[field];
+  if (binding) {
+    const value = readCanonicalFieldValue(definition, { frontmatter }, field);
+    if (value !== void 0) {
+      return value;
+    }
+  }
+  const keys = /* @__PURE__ */ new Set([field]);
+  if (binding) {
+    for (const alias of binding.aliases ?? []) keys.add(alias);
+    for (const key of binding.contentKeys ?? []) keys.add(key);
+  }
+  for (const key of keys) {
+    if (key in frontmatter) {
+      return frontmatter[key];
+    }
+  }
+  return void 0;
+}
+function walkTree(node, visit) {
+  visit(node);
+  for (const child of node.children ?? []) {
+    walkTree(child, visit);
+  }
+}
+function extractMarkdownArtifacts(body) {
+  const tree = markdownProcessor.parse(body);
+  const slugger = new GithubSlugger();
+  const headings = [];
+  const links = [];
+  const mdxImports = [];
+  walkTree(tree, (node) => {
+    const startOffset = node.position?.start?.offset ?? 0;
+    const endOffset = node.position?.end?.offset ?? startOffset;
+    if (node.type === "heading" && typeof node.depth === "number") {
+      headings.push({
+        text: toString(node).trim(),
+        slug: slugger.slug(toString(node).trim() || "section"),
+        level: node.depth,
+        startOffset,
+        endOffset
+      });
+    }
+    if (node.type === "link" && typeof node.url === "string") {
+      links.push({
+        url: node.url,
+        text: toString(node).trim(),
+        startOffset,
+        endOffset
+      });
+    }
+    if (node.type === "mdxjsEsm" && typeof node.value === "string") {
+      const matches = node.value.matchAll(/(?:import|export)\s+(?:[^'"]+?\s+from\s+)?['"]([^'"]+)['"]/gu);
+      for (const match of matches) {
+        if (match[1]) {
+          mdxImports.push(match[1]);
+        }
+      }
+    }
+  });
+  return { headings, links, mdxImports };
+}
+function buildSections(fileId, body, headings, links) {
+  const sections = [];
+  const lines = body.length;
+  const nonWhitespace = /\S/u.test(body);
+  const headingOrdinals = /* @__PURE__ */ new Map();
+  const headingPathStack = [];
+  const sectionEndForHeading = (index) => {
+    const current = headings[index];
+    for (let pointer = index + 1; pointer < headings.length; pointer += 1) {
+      if (headings[pointer].level <= current.level) {
+        return headings[pointer].startOffset;
+      }
+    }
+    return lines;
+  };
+  if (headings.length === 0) {
+    if (!nonWhitespace) {
+      return sections;
+    }
+    sections.push({
+      id: `section:${fileId}:__intro:0`,
+      fileId,
+      heading: null,
+      headingSlug: "__intro",
+      headingPath: "__intro",
+      level: 0,
+      ordinal: 0,
+      startOffset: 0,
+      endOffset: lines,
+      rawText: body,
+      normalizedText: normalizeText(body),
+      outboundLinks: links,
+      referencedEntityIds: []
+    });
+    return sections;
+  }
+  const introEnd = headings[0]?.startOffset ?? 0;
+  if (introEnd > 0 && /\S/u.test(body.slice(0, introEnd))) {
+    sections.push({
+      id: `section:${fileId}:__intro:0`,
+      fileId,
+      heading: null,
+      headingSlug: "__intro",
+      headingPath: "__intro",
+      level: 0,
+      ordinal: 0,
+      startOffset: 0,
+      endOffset: introEnd,
+      rawText: body.slice(0, introEnd),
+      normalizedText: normalizeText(body.slice(0, introEnd)),
+      outboundLinks: links.filter((link) => link.startOffset >= 0 && link.startOffset < introEnd),
+      referencedEntityIds: []
+    });
+  }
+  for (let index = 0; index < headings.length; index += 1) {
+    const heading = headings[index];
+    while ((headingPathStack.at(-1)?.level ?? 0) >= heading.level) {
+      headingPathStack.pop();
+    }
+    const parentPath = headingPathStack.at(-1)?.path;
+    const headingPath = parentPath ? `${parentPath}/${heading.slug}` : heading.slug;
+    headingPathStack.push({ level: heading.level, path: headingPath });
+    const ordinal = headingOrdinals.get(headingPath) ?? 0;
+    headingOrdinals.set(headingPath, ordinal + 1);
+    const endOffset = sectionEndForHeading(index);
+    const rawText = body.slice(heading.startOffset, endOffset);
+    sections.push({
+      id: `section:${fileId}:${headingPath}:${ordinal}`,
+      fileId,
+      heading: heading.text,
+      headingSlug: heading.slug,
+      headingPath,
+      level: heading.level,
+      ordinal,
+      startOffset: heading.startOffset,
+      endOffset,
+      rawText,
+      normalizedText: normalizeText(rawText),
+      outboundLinks: links.filter((link) => link.startOffset >= heading.startOffset && link.startOffset < endOffset),
+      referencedEntityIds: []
+    });
+  }
+  return sections;
+}
+function normalizeReferenceValue(value) {
+  return value.trim().replace(/^\.\/+/u, "").replace(/\\/gu, "/");
+}
+const GRAPH_FRONTMATTER_RELATION_FIELDS = [
+  { field: "related", edgeType: "RELATES_TO", multiple: true },
+  { field: "references", edgeType: "REFERENCES", multiple: true },
+  { field: "dependsOn", edgeType: "DEPENDS_ON", multiple: true },
+  { field: "implements", edgeType: "IMPLEMENTS", multiple: true },
+  { field: "extends", edgeType: "EXTENDS", multiple: true },
+  { field: "supersedes", edgeType: "SUPERSEDES", multiple: true },
+  { field: "belongsTo", edgeType: "BELONGS_TO", multiple: true },
+  { field: "about", edgeType: "ABOUT", multiple: true },
+  { field: "usedBy", edgeType: "USED_BY", multiple: true },
+  { field: "generatedFrom", edgeType: "GENERATED_FROM", multiple: true }
+];
+function parseGraphDocument(definition, filePath, source) {
+  const parsed = parseFrontmatterDocument(source);
+  const graphConfig = resolveGraphModelConfig(definition);
+  const slug = inferSlug(filePath, definition.contentDir);
+  const fileId = createFileNodeId(definition.name, slug);
+  const entityId = createEntityNodeId(definition, slug, parsed.frontmatter);
+  const titleValue = readGraphField(definition, parsed.frontmatter, graphConfig.titleField);
+  const title = typeof titleValue === "string" && titleValue.trim() ? titleValue.trim() : slug;
+  const tags = graphConfig.tagField ? ensureArray(readGraphField(definition, parsed.frontmatter, graphConfig.tagField)) : [];
+  const seriesValue = graphConfig.seriesField ? readGraphField(definition, parsed.frontmatter, graphConfig.seriesField) : void 0;
+  const series = typeof seriesValue === "string" && seriesValue.trim() ? seriesValue.trim() : null;
+  const explicitId = typeof parsed.frontmatter.id === "string" && parsed.frontmatter.id.trim() ? parsed.frontmatter.id.trim() : null;
+  const status = typeof parsed.frontmatter.status === "string" && parsed.frontmatter.status.trim() ? parsed.frontmatter.status.trim() : null;
+  const canonical = parsed.frontmatter.canonical === true;
+  const canonicalRef = typeof parsed.frontmatter.canonical === "string" && parsed.frontmatter.canonical.trim() ? normalizeReferenceValue(parsed.frontmatter.canonical.trim()) : null;
+  const version = typeof parsed.frontmatter.version === "string" && parsed.frontmatter.version.trim() ? parsed.frontmatter.version.trim() : null;
+  const domain = typeof parsed.frontmatter.domain === "string" && parsed.frontmatter.domain.trim() ? parsed.frontmatter.domain.trim() : null;
+  const audience = ensureArray(parsed.frontmatter.audience);
+  const updatedAtValue = readGraphField(definition, parsed.frontmatter, "updated_at") ?? parsed.frontmatter.updatedAt ?? parsed.frontmatter.updated_at;
+  const updatedAt = typeof updatedAtValue === "string" && updatedAtValue.trim() ? updatedAtValue.trim() : null;
+  const body = parsed.body;
+  const { headings, links, mdxImports } = extractMarkdownArtifacts(body);
+  const sections = graphConfig.enableSections ? buildSections(fileId, body, headings, links) : [];
+  const configuredReferences = graphConfig.referenceFields.flatMap((referenceField) => {
+    const rawValue = readGraphField(definition, parsed.frontmatter, referenceField.field);
+    return ensureArray(rawValue).map((value) => ({
+      field: referenceField.field,
+      value: normalizeReferenceValue(value),
+      targetModels: referenceField.targetModels,
+      edgeType: referenceField.edgeType ?? "REFERENCES"
+    }));
+  });
+  const inferredRelationshipReferences = GRAPH_FRONTMATTER_RELATION_FIELDS.flatMap(
+    (entry) => ensureArray(parsed.frontmatter[entry.field]).map((value) => ({
+      field: entry.field,
+      value: normalizeReferenceValue(value),
+      edgeType: entry.edgeType
+    }))
+  );
+  const canonicalReference = canonicalRef ? [{ field: "canonical", value: canonicalRef, edgeType: "REFERENCES" }] : [];
+  const explicitReferences = [...configuredReferences, ...inferredRelationshipReferences, ...canonicalReference];
+  return {
+    fileId,
+    entityId,
+    model: definition.name,
+    entityType: graphConfig.entityType,
+    slug,
+    title,
+    path: filePath,
+    relativePath: path.relative(definition.contentDir, filePath).replace(/\\/gu, "/"),
+    dirname: path.dirname(path.relative(definition.contentDir, filePath).replace(/\\/gu, "/")),
+    body,
+    normalizedBody: normalizeText(body),
+    frontmatter: parsed.frontmatter,
+    explicitId,
+    tags,
+    series,
+    status,
+    canonical,
+    canonicalRef,
+    version,
+    domain,
+    audience,
+    updatedAt,
+    sections,
+    headings,
+    links,
+    mdxImports,
+    explicitReferences
+  };
+}
+function catalogForDocument(document, hash) {
+  return {
+    path: document.path,
+    relativePath: document.relativePath,
+    model: document.model,
+    slug: document.slug,
+    fileId: document.fileId,
+    hash
+  };
+}
+function buildReferenceMaps(documents, models) {
+  const entityById = /* @__PURE__ */ new Map();
+  const fileById = /* @__PURE__ */ new Map();
+  const fileByPath = /* @__PURE__ */ new Map();
+  const fileByRelativePath = /* @__PURE__ */ new Map();
+  const entityByModelAndSlug = /* @__PURE__ */ new Map();
+  const sectionById = /* @__PURE__ */ new Map();
+  const sectionByAnchor = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    entityById.set(document.entityId, document);
+    fileById.set(document.fileId, document);
+    fileByPath.set(path.resolve(document.path), document);
+    fileByRelativePath.set(stripMarkdownExtension(document.relativePath), document);
+    entityByModelAndSlug.set(`${document.model}:${document.slug}`, document);
+    for (const section of document.sections) {
+      sectionById.set(section.id, section);
+      sectionByAnchor.set(`${document.fileId}#${section.headingSlug}`, section);
+      sectionByAnchor.set(`${document.fileId}#${section.headingPath}`, section);
+    }
+  }
+  const resolveReferenceString = (reference, sourceDocument) => {
+    const trimmed = reference.trim();
+    if (!trimmed) {
+      return { kind: "unresolved" };
+    }
+    const [pathPart, hashPart = ""] = trimmed.split("#");
+    if (entityById.has(trimmed)) {
+      const entity = entityById.get(trimmed);
+      return { kind: "entity", targetId: entity.entityId, fileId: entity.fileId };
+    }
+    if (pathPart.includes("/")) {
+      const [modelPrefix, ...slugParts] = pathPart.split("/");
+      if (slugParts.length > 0) {
+        try {
+          const model = resolveModelDefinition(modelPrefix, models).name;
+          const slug = slugParts.join("/");
+          const target = entityByModelAndSlug.get(`${model}:${slug}`);
+          if (target) {
+            if (hashPart) {
+              const section = sectionByAnchor.get(`${target.fileId}#${hashPart}`);
+              if (section) {
+                return { kind: "section", targetId: section.id, fileId: target.fileId };
+              }
+            }
+            return { kind: "entity", targetId: target.entityId, fileId: target.fileId };
+          }
+        } catch {
+        }
+      }
+    }
+    if (sourceDocument && !pathPart.includes("/")) {
+      const sameModel = entityByModelAndSlug.get(`${sourceDocument.model}:${pathPart}`);
+      if (sameModel) {
+        return { kind: "entity", targetId: sameModel.entityId, fileId: sameModel.fileId };
+      }
+    }
+    if (sourceDocument && pathPart) {
+      const absolute = path.resolve(path.dirname(sourceDocument.path), pathPart);
+      const normalized = stripMarkdownExtension(absolute);
+      for (const [filePath, document] of fileByPath.entries()) {
+        if (stripMarkdownExtension(filePath) === normalized) {
+          if (hashPart) {
+            const section = sectionByAnchor.get(`${document.fileId}#${hashPart}`);
+            if (section) {
+              return { kind: "section", targetId: section.id, fileId: document.fileId };
+            }
+          }
+          return { kind: "file", targetId: document.fileId, fileId: document.fileId };
+        }
+      }
+    }
+    if (pathPart.startsWith("/")) {
+      const normalizedRelative = stripMarkdownExtension(pathPart.replace(/^\/+/u, ""));
+      const direct = fileByRelativePath.get(normalizedRelative);
+      if (direct) {
+        if (hashPart) {
+          const section = sectionByAnchor.get(`${direct.fileId}#${hashPart}`);
+          if (section) {
+            return { kind: "section", targetId: section.id, fileId: direct.fileId };
+          }
+        }
+        return { kind: "file", targetId: direct.fileId, fileId: direct.fileId };
+      }
+      for (const document of documents) {
+        const routeLike = `${document.model}/${document.slug}`.replace(/^knowledge\//u, "knowledge/");
+        if (routeLike === normalizedRelative || document.slug === normalizedRelative) {
+          return { kind: "file", targetId: document.fileId, fileId: document.fileId };
+        }
+      }
+    }
+    if (hashPart && sourceDocument) {
+      const section = sectionByAnchor.get(`${sourceDocument.fileId}#${hashPart}`);
+      if (section) {
+        return { kind: "section", targetId: section.id, fileId: sourceDocument.fileId };
+      }
+    }
+    return { kind: "unresolved" };
+  };
+  return {
+    entityById,
+    fileById,
+    fileByPath,
+    fileByRelativePath,
+    entityByModelAndSlug,
+    sectionById,
+    sectionByAnchor,
+    resolveReferenceString
+  };
+}
+function buildGraphFromDocuments(documents, models, priorMetrics, delta) {
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = /* @__PURE__ */ new Map();
+  const referenceNodes = /* @__PURE__ */ new Map();
+  const fileTargets = /* @__PURE__ */ new Map();
+  const maps = buildReferenceMaps(documents, models);
+  const validation = emptyGraphValidation();
+  const seenExplicitIds = /* @__PURE__ */ new Set();
+  for (const document of documents) {
+    if (!document.explicitId) {
+      validation.missingIds.push(document.fileId);
+    } else if (seenExplicitIds.has(document.explicitId)) {
+      validation.duplicateIds.push(document.explicitId);
+    } else {
+      seenExplicitIds.add(document.explicitId);
+    }
+  }
+  const addNode = (node) => {
+    nodes.set(node.id, node);
+  };
+  const addEdge = (edge) => {
+    edges.set(edge.id, edge);
+    if (["LINKS_TO", "REFERENCES"].includes(edge.type)) {
+      const targets = fileTargets.get(edge.ownerFileId ?? "") ?? /* @__PURE__ */ new Set();
+      targets.add(edge.targetId);
+      fileTargets.set(edge.ownerFileId ?? "", targets);
+    }
+  };
+  const unresolvedNodeFor = (ownerFileId, value) => {
+    const id = `reference:${sha1(`${ownerFileId}|${value}`)}`;
+    const node = referenceNodes.get(id) ?? {
+      id,
+      nodeType: "Reference",
+      ownerFileId,
+      title: value,
+      data: { reference: value, resolved: false }
+    };
+    referenceNodes.set(id, node);
+    addNode(node);
+    return node;
+  };
+  for (const document of documents) {
+    addNode({
+      id: document.fileId,
+      nodeType: "File",
+      sourceModel: document.model,
+      ownerFileId: document.fileId,
+      path: document.path,
+      slug: document.slug,
+      title: document.title,
+      tags: document.tags,
+      series: document.series,
+      status: document.status,
+      canonical: document.canonical,
+      canonicalId: document.canonicalRef,
+      version: document.version,
+      domain: document.domain,
+      audience: document.audience,
+      updatedAt: document.updatedAt,
+      text: document.body,
+      data: { relativePath: document.relativePath, explicitId: document.explicitId, frontmatter: document.frontmatter }
+    });
+    addNode({
+      id: document.entityId,
+      nodeType: document.entityType,
+      entityType: document.entityType,
+      sourceModel: document.model,
+      ownerFileId: document.fileId,
+      path: document.path,
+      slug: document.slug,
+      title: document.title,
+      tags: document.tags,
+      series: document.series,
+      fileId: document.fileId,
+      status: document.status,
+      canonical: document.canonical,
+      canonicalId: document.canonicalRef,
+      version: document.version,
+      domain: document.domain,
+      audience: document.audience,
+      updatedAt: document.updatedAt,
+      text: document.body,
+      data: { frontmatter: document.frontmatter }
+    });
+    addEdge({
+      id: computeEdgeId(document.fileId, "DEFINES", document.entityId, document.fileId),
+      type: "DEFINES",
+      sourceId: document.fileId,
+      targetId: document.entityId,
+      ownerFileId: document.fileId
+    });
+    addEdge({
+      id: computeEdgeId(document.entityId, "DEFINED_BY", document.fileId, document.fileId),
+      type: "DEFINED_BY",
+      sourceId: document.entityId,
+      targetId: document.fileId,
+      ownerFileId: document.fileId
+    });
+    for (const [index, section] of document.sections.entries()) {
+      addNode({
+        id: section.id,
+        nodeType: "Section",
+        sourceModel: document.model,
+        ownerFileId: document.fileId,
+        path: document.path,
+        fileId: document.fileId,
+        entityId: document.entityId,
+        slug: `${document.slug}#${section.headingSlug}`,
+        title: section.heading ?? document.title,
+        heading: section.heading,
+        headingPath: section.headingPath,
+        level: section.level,
+        tags: document.tags,
+        status: document.status,
+        canonical: document.canonical,
+        canonicalId: document.canonicalRef,
+        version: document.version,
+        domain: document.domain,
+        audience: document.audience,
+        updatedAt: document.updatedAt,
+        text: section.rawText,
+        data: {
+          ordinal: section.ordinal,
+          startOffset: section.startOffset,
+          endOffset: section.endOffset,
+          textLength: section.rawText.length,
+          linkDensity: section.outboundLinks.length,
+          ownerTitle: document.title
+        }
+      });
+      addEdge({
+        id: computeEdgeId(document.fileId, "HAS_SECTION", section.id, `${document.fileId}:${section.id}`),
+        type: "HAS_SECTION",
+        sourceId: document.fileId,
+        targetId: section.id,
+        ownerFileId: document.fileId
+      });
+      addEdge({
+        id: computeEdgeId(section.id, "BELONGS_TO_FILE", document.fileId, `${section.id}:${document.fileId}`),
+        type: "BELONGS_TO_FILE",
+        sourceId: section.id,
+        targetId: document.fileId,
+        ownerFileId: document.fileId
+      });
+      if (index > 0) {
+        const previous = document.sections[index - 1];
+        addEdge({
+          id: computeEdgeId(previous.id, "NEXT_SECTION", section.id, `${previous.id}:${section.id}`),
+          type: "NEXT_SECTION",
+          sourceId: previous.id,
+          targetId: section.id,
+          ownerFileId: document.fileId
+        });
+        addEdge({
+          id: computeEdgeId(section.id, "PREV_SECTION", previous.id, `${section.id}:${previous.id}`),
+          type: "PREV_SECTION",
+          sourceId: section.id,
+          targetId: previous.id,
+          ownerFileId: document.fileId
+        });
+      }
+    }
+    const stack = [];
+    for (const section of document.sections) {
+      if (section.level <= 0) {
+        continue;
+      }
+      while ((stack.at(-1)?.level ?? 0) >= section.level) {
+        stack.pop();
+      }
+      const parent = stack.at(-1);
+      if (parent) {
+        addEdge({
+          id: computeEdgeId(section.id, "PARENT_SECTION", parent.id, `${section.id}:${parent.id}`),
+          type: "PARENT_SECTION",
+          sourceId: section.id,
+          targetId: parent.id,
+          ownerFileId: document.fileId
+        });
+        addEdge({
+          id: computeEdgeId(parent.id, "CHILD_SECTION", section.id, `${parent.id}:${section.id}`),
+          type: "CHILD_SECTION",
+          sourceId: parent.id,
+          targetId: section.id,
+          ownerFileId: document.fileId
+        });
+      }
+      stack.push(section);
+    }
+    for (const tag of document.tags) {
+      const tagId = `tag:${normalizeText(tag)}`;
+      addNode({
+        id: tagId,
+        nodeType: "Tag",
+        title: tag,
+        slug: normalizeText(tag)
+      });
+      for (const sourceId of [document.fileId, document.entityId]) {
+        addEdge({
+          id: computeEdgeId(sourceId, "HAS_TAG", tagId, `${sourceId}:${tagId}`),
+          type: "HAS_TAG",
+          sourceId,
+          targetId: tagId,
+          ownerFileId: document.fileId
+        });
+      }
+    }
+    if (document.series) {
+      const seriesId = `series:${normalizeText(document.series)}`;
+      addNode({
+        id: seriesId,
+        nodeType: "Series",
+        title: document.series,
+        slug: normalizeText(document.series)
+      });
+      for (const sourceId of [document.fileId, document.entityId]) {
+        addEdge({
+          id: computeEdgeId(sourceId, "IN_SERIES", seriesId, `${sourceId}:${seriesId}`),
+          type: "IN_SERIES",
+          sourceId,
+          targetId: seriesId,
+          ownerFileId: document.fileId
+        });
+      }
+    }
+    for (const reference of document.explicitReferences) {
+      if (!AUTHORED_GRAPH_EDGE_TYPES.includes(reference.edgeType)) {
+        validation.invalidEdgeTypes.push({ ownerFileId: document.fileId, field: reference.field, edgeType: reference.edgeType });
+        continue;
+      }
+      const resolved = maps.resolveReferenceString(reference.value, document);
+      const targetId = resolved.kind === "unresolved" ? unresolvedNodeFor(document.fileId, reference.value).id : resolved.targetId;
+      if (resolved.kind === "unresolved") {
+        validation.brokenReferences.push({ ownerFileId: document.fileId, value: reference.value, edgeType: reference.edgeType });
+      }
+      if (reference.field === "canonical" && (resolved.kind === "unresolved" || resolved.targetId === document.entityId || resolved.targetId === document.fileId)) {
+        validation.invalidCanonicalRefs.push({ ownerFileId: document.fileId, value: reference.value });
+      }
+      if (reference.edgeType === "SUPERSEDES" && resolved.kind === "unresolved") {
+        validation.invalidSupersedesRefs.push({ ownerFileId: document.fileId, value: reference.value });
+      }
+      for (const sourceId of [document.entityId, document.fileId]) {
+        addEdge({
+          id: computeEdgeId(sourceId, reference.edgeType, targetId, `${reference.field}:${reference.value}:${sourceId}`),
+          type: reference.edgeType,
+          sourceId,
+          targetId,
+          ownerFileId: document.fileId,
+          data: { field: reference.field, value: reference.value }
+        });
+      }
+    }
+    for (const section of document.sections) {
+      for (const link of [...section.outboundLinks, ...document.mdxImports.map((entry) => ({
+        url: entry,
+        text: entry,
+        startOffset: section.startOffset,
+        endOffset: section.startOffset
+      }))]) {
+        const resolved = maps.resolveReferenceString(link.url, document);
+        const targetId = resolved.kind === "unresolved" ? unresolvedNodeFor(document.fileId, link.url).id : resolved.targetId;
+        addEdge({
+          id: computeEdgeId(section.id, "LINKS_TO", targetId, `${section.id}:${link.url}`),
+          type: "LINKS_TO",
+          sourceId: section.id,
+          targetId,
+          ownerFileId: document.fileId,
+          data: { url: link.url, text: link.text }
+        });
+        if (resolved.kind === "entity" || resolved.kind === "section") {
+          section.referencedEntityIds.push(targetId);
+        }
+      }
+    }
+  }
+  for (const document of documents) {
+    const candidateTargetIds = [...fileTargets.get(document.fileId) ?? /* @__PURE__ */ new Set()];
+    for (const section of document.sections) {
+      const text = normalizeText(section.rawText);
+      for (const targetId of candidateTargetIds) {
+        if (edges.has(computeEdgeId(section.id, "LINKS_TO", targetId, `${section.id}:${targetId}`)) || edges.has(computeEdgeId(section.id, "REFERENCES", targetId, `${section.id}:${targetId}`))) {
+          continue;
+        }
+        const target = nodes.get(targetId);
+        if (!target?.title) {
+          continue;
+        }
+        const variants = [target.title, target.slug ?? ""].map((entry) => normalizeText(entry)).filter((entry) => entry.length >= 4);
+        if (variants.some((variant) => variant && text.includes(variant))) {
+          addEdge({
+            id: computeEdgeId(section.id, "MENTIONS", targetId, `${section.id}:${targetId}`),
+            type: "MENTIONS",
+            sourceId: section.id,
+            targetId,
+            ownerFileId: document.fileId
+          });
+        }
+      }
+    }
+  }
+  const groupBy = (items, fn) => {
+    const grouped = /* @__PURE__ */ new Map();
+    for (const document of items) {
+      const key = fn(document);
+      if (!key) continue;
+      const bucket = grouped.get(key) ?? [];
+      bucket.push(document);
+      grouped.set(key, bucket);
+    }
+    return grouped;
+  };
+  for (const [, group] of groupBy(documents, (document) => document.model)) {
+    for (let i = 0; i < group.length; i += 1) {
+      for (let j = i + 1; j < group.length; j += 1) {
+        for (const [leftId, rightId] of [
+          [group[i].fileId, group[j].fileId],
+          [group[i].entityId, group[j].entityId]
+        ]) {
+          addEdge({
+            id: computeEdgeId(leftId, "SAME_COLLECTION", rightId, `${leftId}:${rightId}`),
+            type: "SAME_COLLECTION",
+            sourceId: leftId,
+            targetId: rightId,
+            ownerFileId: group[i].fileId
+          });
+          addEdge({
+            id: computeEdgeId(rightId, "SAME_COLLECTION", leftId, `${rightId}:${leftId}`),
+            type: "SAME_COLLECTION",
+            sourceId: rightId,
+            targetId: leftId,
+            ownerFileId: group[j].fileId
+          });
+        }
+      }
+    }
+  }
+  for (const [, group] of groupBy(documents, (document) => document.dirname && document.dirname !== "." ? document.dirname : null)) {
+    for (let i = 0; i < group.length; i += 1) {
+      for (let j = i + 1; j < group.length; j += 1) {
+        for (const [leftId, rightId] of [
+          [group[i].fileId, group[j].fileId],
+          [group[i].entityId, group[j].entityId]
+        ]) {
+          addEdge({
+            id: computeEdgeId(leftId, "SAME_DIRECTORY", rightId, `${leftId}:${rightId}`),
+            type: "SAME_DIRECTORY",
+            sourceId: leftId,
+            targetId: rightId,
+            ownerFileId: group[i].fileId
+          });
+          addEdge({
+            id: computeEdgeId(rightId, "SAME_DIRECTORY", leftId, `${rightId}:${leftId}`),
+            type: "SAME_DIRECTORY",
+            sourceId: rightId,
+            targetId: leftId,
+            ownerFileId: group[j].fileId
+          });
+        }
+      }
+    }
+  }
+  const metrics = {
+    ...priorMetrics ?? emptyGraphMetrics(),
+    totalFiles: documents.length,
+    totalSections: documents.reduce((sum, document) => sum + document.sections.length, 0),
+    totalEntities: documents.length,
+    totalEdges: edges.size,
+    unresolvedReferences: [...nodes.values()].filter((node) => node.nodeType === "Reference").length,
+    validation: {
+      missingIds: validation.missingIds.length,
+      duplicateIds: validation.duplicateIds.length,
+      brokenReferences: validation.brokenReferences.length,
+      invalidEdgeTypes: validation.invalidEdgeTypes.length,
+      invalidCanonicalRefs: validation.invalidCanonicalRefs.length,
+      invalidSupersedesRefs: validation.invalidSupersedesRefs.length
+    },
+    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    nodes: [...nodes.values()],
+    edges: [...edges.values()],
+    metrics,
+    validation,
+    delta: delta ?? { added: [], modified: [], removed: [] }
+  };
+}
+async function readSnapshotFile(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function loadGraphSnapshot(repoRoot, models) {
+  const snapshotRoot = graphSnapshotRoot(repoRoot);
+  const graph = await readSnapshotFile(
+    path.join(snapshotRoot, "graph.json")
+  );
+  const catalog = await readSnapshotFile(path.join(snapshotRoot, "catalog.json"));
+  const metrics = await readSnapshotFile(path.join(snapshotRoot, "metrics.json"));
+  const delta = await readSnapshotFile(path.join(snapshotRoot, "deltas.json"));
+  const currentSignature = computeModelSignature(models);
+  if (!graph || graph.version !== GRAPH_SNAPSHOT_VERSION || graph.modelSignature !== currentSignature || !catalog) {
+    return null;
+  }
+  return {
+    modelSignature: graph.modelSignature,
+    documents: graph.documents,
+    nodes: graph.nodes,
+    edges: graph.edges,
+    catalog: catalog.catalog,
+    metrics: metrics ?? emptyGraphMetrics(),
+    validation: graph.validation ?? emptyGraphValidation(),
+    delta: delta ?? { added: [], modified: [], removed: [] },
+    snapshotRoot
+  };
+}
+async function saveGraphSnapshot(state) {
+  await mkdir(state.snapshotRoot, { recursive: true });
+  const graphPayload = {
+    version: GRAPH_SNAPSHOT_VERSION,
+    modelSignature: state.modelSignature,
+    documents: state.documents,
+    nodes: state.nodes,
+    edges: state.edges,
+    validation: state.validation
+  };
+  await Promise.all([
+    writeFile(path.join(state.snapshotRoot, "graph.json"), `${JSON.stringify(graphPayload, null, 2)}
+`, "utf8"),
+    writeFile(path.join(state.snapshotRoot, "catalog.json"), `${JSON.stringify({ catalog: state.catalog }, null, 2)}
+`, "utf8"),
+    writeFile(path.join(state.snapshotRoot, "metrics.json"), `${JSON.stringify(state.metrics, null, 2)}
+`, "utf8"),
+    writeFile(path.join(state.snapshotRoot, "deltas.json"), `${JSON.stringify(state.delta, null, 2)}
+`, "utf8"),
+    writeFile(
+      path.join(state.snapshotRoot, "indexes.json"),
+      `${JSON.stringify({ files: [], sections: [], entities: [] }, null, 2)}
+`,
+      "utf8"
+    )
+  ]);
+}
+async function hashFile(filePath) {
+  const source = await readFile(filePath, "utf8");
+  return {
+    source,
+    hash: sha1(source)
+  };
+}
+function contentDefinitions(models) {
+  return Object.values(models).filter((definition) => definition.storage === "content" && Boolean(definition.contentDir)).sort((left, right) => left.name.localeCompare(right.name));
+}
+async function refreshGraphBuildState(repoRoot, models, request, priorState) {
+  const snapshotRoot = graphSnapshotRoot(repoRoot);
+  const modelSignature = computeModelSignature(models);
+  const priorDocuments = new Map((priorState?.documents ?? []).map((document) => [document.fileId, document]));
+  const priorCatalog = new Map((priorState?.catalog ?? []).map((entry) => [path.resolve(entry.path), entry]));
+  const nextDocuments = new Map(priorDocuments);
+  const nextCatalog = new Map(priorCatalog);
+  const requestedPaths = request?.paths?.map((entry) => path.resolve(repoRoot, entry)).filter(Boolean);
+  const changed = { added: [], modified: [], removed: [] };
+  const trackedPaths = /* @__PURE__ */ new Set();
+  const definitions = contentDefinitions(models);
+  if (requestedPaths && requestedPaths.length > 0) {
+    for (const requestedPath of requestedPaths) {
+      const matchingDefinition = definitions.find((definition) => requestedPath.startsWith(path.resolve(definition.contentDir)));
+      if (!matchingDefinition) {
+        continue;
+      }
+      trackedPaths.add(requestedPath);
+      try {
+        const fileStats = await stat(requestedPath);
+        if (!fileStats.isFile()) continue;
+        const { source, hash } = await hashFile(requestedPath);
+        const parsed = parseGraphDocument(matchingDefinition, requestedPath, source);
+        const existing = priorCatalog.get(requestedPath);
+        nextDocuments.set(parsed.fileId, parsed);
+        nextCatalog.set(requestedPath, catalogForDocument(parsed, hash));
+        if (!existing) {
+          changed.added.push(parsed.fileId);
+        } else if (existing.hash !== hash) {
+          changed.modified.push(parsed.fileId);
+        }
+      } catch {
+        const existing = priorCatalog.get(requestedPath);
+        if (existing) {
+          changed.removed.push(existing.fileId);
+          nextCatalog.delete(requestedPath);
+          nextDocuments.delete(existing.fileId);
+        }
+      }
+    }
+  } else {
+    for (const definition of definitions) {
+      const files = await walkMarkdownFiles(definition.contentDir);
+      for (const filePath of files) {
+        const resolvedPath = path.resolve(filePath);
+        trackedPaths.add(resolvedPath);
+        const { source, hash } = await hashFile(resolvedPath);
+        const parsed = parseGraphDocument(definition, resolvedPath, source);
+        const existing = priorCatalog.get(resolvedPath);
+        nextDocuments.set(parsed.fileId, parsed);
+        nextCatalog.set(resolvedPath, catalogForDocument(parsed, hash));
+        if (!existing) {
+          changed.added.push(parsed.fileId);
+        } else if (existing.hash !== hash) {
+          changed.modified.push(parsed.fileId);
+        }
+      }
+    }
+    for (const [existingPath, existing] of priorCatalog.entries()) {
+      if (!trackedPaths.has(existingPath)) {
+        changed.removed.push(existing.fileId);
+        nextCatalog.delete(existingPath);
+        nextDocuments.delete(existing.fileId);
+      }
+    }
+  }
+  const built = buildGraphFromDocuments(
+    [...nextDocuments.values()].sort((left, right) => left.fileId.localeCompare(right.fileId)),
+    models,
+    priorState?.metrics,
+    changed
+  );
+  return {
+    modelSignature,
+    documents: [...nextDocuments.values()].sort((left, right) => left.fileId.localeCompare(right.fileId)),
+    nodes: built.nodes,
+    edges: built.edges,
+    catalog: [...nextCatalog.values()].sort((left, right) => left.fileId.localeCompare(right.fileId)),
+    metrics: built.metrics,
+    validation: built.validation,
+    delta: changed,
+    snapshotRoot
+  };
+}
+async function clearGraphSnapshot(repoRoot) {
+  await rm(graphSnapshotRoot(repoRoot), { recursive: true, force: true });
+}
+export {
+  clearGraphSnapshot,
+  loadGraphSnapshot,
+  refreshGraphBuildState,
+  saveGraphSnapshot
+};