patram 0.11.0 → 0.12.0

package/lib/graph/build-graph.js

@@ -2,8 +2,7 @@
 /**
  * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
  * @import { PatramClaim } from '../parse/parse-claims.types.ts';
- * @import { MetadataFieldConfig } from '../config/load-patram-config.types.ts';
- * @import { MappingDefinition, PatramConfig } from '../config/patram-config.types.ts';
+ * @import { MetadataFieldConfig, PatramRepoConfig } from '../config/load-patram-config.types.ts';
  */
 
 import { posix } from 'node:path';
@@ -12,74 +11,60 @@ import {
   collectDocumentEntityKeys,
   collectDocumentNodeReferences,
   normalizeRepoRelativePath,
-  resolveNodeKey,
   resolveTargetReference,
   setCanonicalPath,
 } from './build-graph-identity.js';
 
-/**
- * Claim-to-graph materialization.
- *
- * Maps parsed claims into document nodes and relations using the resolved
- * Patram graph config.
- *
- * Kind: graph
- * Status: active
- * Uses Term: ../../docs/reference/terms/claim.md
- * Uses Term: ../../docs/reference/terms/document.md
- * Uses Term: ../../docs/reference/terms/graph.md
- * Uses Term: ../../docs/reference/terms/mapping.md
- * Uses Term: ../../docs/reference/terms/relation.md
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/graph-materialization.md
- * Implements: ../../docs/tasks/v0/materialize-graph.md
- * @patram
- * @see {@link ./load-project-graph.js}
- * @see {@link ../../docs/decisions/graph-materialization.md}
- */
-
-const STRUCTURAL_FIELD_NAMES = new Set(['$class', '$id', '$path']);
-const DETERMINISTIC_LOCALE = 'en';
+const DERIVED_DESCRIPTION_PRIORITY = 1;
 const DERIVED_TITLE_PRIORITY = 1;
+const EXPLICIT_DESCRIPTION_PRIORITY = 2;
 const EXPLICIT_TITLE_PRIORITY = 2;
 
 /**
- * Build a Patram graph from semantic config and parsed claims.
+ * Build a Patram graph from repo config and parsed claims.
  *
- * @param {PatramConfig} patram_config
+ * kind: graph
+ * status: active
+ * uses_term: ../../docs/reference/terms/graph.md
+ * tracked_in: ../../docs/plans/v2/types-and-fields-config.md
+ * decided_by: ../../docs/decisions/types-and-fields-config.md
+ * @patram
+ * @see {@link ./build-graph-identity.js}
+ * @see {@link ../../docs/decisions/types-and-fields-config.md}
+ *
+ * @param {PatramRepoConfig} repo_config
  * @param {PatramClaim[]} claims
  * @returns {BuildGraphResult}
  */
-export function buildGraph(patram_config, claims) {
+export function buildGraph(repo_config, claims) {
   /** @type {Map<string, GraphNode>} */
   const graph_nodes = new Map();
   const document_node_references = collectDocumentNodeReferences(
-    patram_config.mappings,
-    claims,
-  );
-  const document_entity_keys = collectDocumentEntityKeys(
-    patram_config.mappings,
+    repo_config,
     claims,
   );
+  const document_entity_keys = collectDocumentEntityKeys(repo_config, claims);
   /** @type {Set<string>} */
   const document_paths = new Set(
     claims.map((claim) => normalizeRepoRelativePath(claim.origin.path)),
   );
   /** @type {Map<string, number>} */
+  const description_priorities = new Map();
+  /** @type {Map<string, number>} */
   const title_priorities = new Map();
 
   createDocumentNodes(graph_nodes, document_node_references);
-  applyNodeMappings(
+  applyMetadataClaims(
     graph_nodes,
-    patram_config,
+    repo_config,
     claims,
-    document_entity_keys,
     document_node_references,
     title_priorities,
+    description_priorities,
   );
   const graph_edges = createGraphEdges(
     graph_nodes,
-    patram_config.mappings,
+    repo_config,
     claims,
     document_entity_keys,
     document_node_references,
@@ -97,39 +82,13 @@ export function buildGraph(patram_config, claims) {
   attachDocumentNodeAliases(graph_result.nodes, document_node_references);
   Object.defineProperty(
     graph_result,
-    'document_node_ids',
-    createDocumentNodeIdsProperty(document_node_references),
+    'document_path_ids',
+    createDocumentPathIdsProperty(document_node_references),
   );
 
   return graph_result;
 }
 
-/**
- * @param {Record<string, MappingDefinition>} mappings
- * @param {PatramClaim} claim
- * @returns {MappingDefinition | null}
- */
-function resolveMappingDefinition(mappings, claim) {
-  if (claim.type === 'directive') {
-    return resolveDirectiveMapping(mappings, claim);
-  }
-
-  return mappings[claim.type] ?? null;
-}
-
-/**
- * @param {Record<string, MappingDefinition>} mappings
- * @param {PatramClaim} claim
- * @returns {MappingDefinition | null}
- */
-function resolveDirectiveMapping(mappings, claim) {
-  if (!claim.parser || !claim.name) {
-    return null;
-  }
-
-  return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
-}
-
 /**
  * @param {Map<string, GraphNode>} graph_nodes
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
@@ -148,45 +107,67 @@ function createDocumentNodes(graph_nodes, document_node_references) {
 
 /**
  * @param {Map<string, GraphNode>} graph_nodes
- * @param {PatramConfig} patram_config
+ * @param {PatramRepoConfig} repo_config
  * @param {PatramClaim[]} claims
- * @param {Map<string, string>} document_entity_keys
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Map<string, number>} title_priorities
+ * @param {Map<string, number>} description_priorities
  */
-function applyNodeMappings(
+function applyMetadataClaims(
   graph_nodes,
-  patram_config,
+  repo_config,
   claims,
-  document_entity_keys,
   document_node_references,
   title_priorities,
+  description_priorities,
 ) {
   for (const claim of claims) {
-    const mapping_definition = resolveMappingDefinition(
-      patram_config.mappings,
+    const source_graph_node = getSourceGraphNode(
+      graph_nodes,
+      document_node_references,
       claim,
     );
 
-    if (!mapping_definition?.node) {
+    if (
+      applyDerivedMetadataClaim(
+        source_graph_node,
+        claim,
+        title_priorities,
+        description_priorities,
+      )
+    ) {
       continue;
     }
 
-    applyNodeMapping(
-      graph_nodes,
-      patram_config,
-      mapping_definition.node,
-      claim,
-      document_entity_keys,
-      document_node_references,
+    if (claim.type !== 'directive' || !claim.name) {
+      continue;
+    }
+
+    const field_context = resolveScalarFieldContext(
+      repo_config,
+      source_graph_node,
+      claim.name,
+    );
+
+    if (!field_context) {
+      continue;
+    }
+
+    const field_value = getScalarClaimValue(claim);
+    assignExplicitMetadataValue(
+      source_graph_node,
+      claim.name,
+      field_value,
+      field_context.is_many,
       title_priorities,
+      description_priorities,
     );
   }
 }
 
 /**
  * @param {Map<string, GraphNode>} graph_nodes
- * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
  * @param {PatramClaim[]} claims
  * @param {Map<string, string>} document_entity_keys
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
@@ -195,7 +176,7 @@ function applyNodeMappings(
  */
 function createGraphEdges(
   graph_nodes,
-  mappings,
+  repo_config,
   claims,
   document_entity_keys,
   document_node_references,
@@ -206,20 +187,20 @@ function createGraphEdges(
   let edge_number = 0;
 
   for (const claim of claims) {
-    const mapping_definition = resolveMappingDefinition(mappings, claim);
+    const edge_definition = resolveEdgeDefinition(repo_config, claim);
 
-    if (!mapping_definition?.emit) {
+    if (!edge_definition) {
       continue;
     }
 
-    const source_document_node = getDocumentGraphNode(
+    const source_document_node = getSourceGraphNode(
       graph_nodes,
       document_node_references,
       claim,
     );
     const target_reference = resolveTargetReference(
-      mapping_definition.emit.target_class,
-      mapping_definition.emit.target,
+      edge_definition.target_class,
+      'path',
       claim,
       document_entity_keys,
       document_node_references,
@@ -235,11 +216,11 @@ function createGraphEdges(
 
     edge_number += 1;
     graph_edges.push({
-      from: source_document_node.id,
+      from: source_document_node.identity.id,
       id: `edge:${edge_number}`,
       origin: claim.origin,
-      relation: mapping_definition.emit.relation,
-      to: target_node.id,
+      relation: edge_definition.relation_name,
+      to: target_node.identity.id,
     });
   }
 
@@ -247,220 +228,31 @@ function createGraphEdges(
 }
 
 /**
- * @param {Map<string, GraphNode>} graph_nodes
- * @param {PatramConfig} patram_config
- * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
+ * @param {PatramRepoConfig} repo_config
  * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
- * @param {Map<string, number>} title_priorities
- */
-function applyNodeMapping(
-  graph_nodes,
-  patram_config,
-  node_mapping,
-  claim,
-  document_entity_keys,
-  document_node_references,
-  title_priorities,
-) {
-  const source_key = normalizeRepoRelativePath(claim.origin.path);
-  const graph_node = resolveGraphNode(
-    graph_nodes,
-    node_mapping,
-    claim,
-    document_entity_keys,
-    document_node_references,
-  );
-  const field_value = resolveNodeFieldValue(
-    graph_node,
-    node_mapping,
-    claim,
-    source_key,
-  );
-
-  setCanonicalPath(graph_node, source_key);
-  validateNodeFieldMapping(
-    patram_config,
-    node_mapping.class,
-    node_mapping.field,
-  );
-
-  if (node_mapping.field === 'title') {
-    setNodeTitle(
-      graph_node,
-      title_priorities,
-      field_value,
-      claim.type === 'document.title'
-        ? DERIVED_TITLE_PRIORITY
-        : EXPLICIT_TITLE_PRIORITY,
-    );
-    return;
-  }
-
-  setNodeFieldValue(
-    graph_node,
-    node_mapping.field,
-    field_value,
-    getFieldDefinition(patram_config, node_mapping.field),
-  );
-}
-
-/**
- * Validate one mapped node field against the configured field model.
- *
- * @param {PatramConfig} patram_config
- * @param {string} node_class
- * @param {string} field_name
- */
-function validateNodeFieldMapping(patram_config, node_class, field_name) {
-  const validation_error = getNodeFieldValidationError(
-    patram_config,
-    node_class,
-    field_name,
-  );
-
-  if (validation_error) {
-    throw new Error(validation_error);
-  }
-}
-
-/**
- * @param {PatramConfig} patram_config
- * @param {string} node_class
- * @param {string} field_name
- * @returns {string | null}
+ * @returns {{ relation_name: string, target_class: string } | null}
  */
-function getNodeFieldValidationError(patram_config, node_class, field_name) {
-  if (isStructuralFieldName(field_name) || field_name === 'title') {
-    return null;
-  }
-
-  const field_definition = getFieldDefinition(patram_config, field_name);
-
-  if (!field_definition) {
-    return `Node class "${node_class}" maps to unknown field "${field_name}".`;
-  }
-
-  const class_schema = getClassSchema(patram_config, node_class);
-  const class_field_rule = class_schema?.fields?.[field_name];
-
-  if (isForbiddenClassField(class_field_rule)) {
-    return `Field "${field_name}" is forbidden for class "${node_class}".`;
-  }
-
-  if (isUndeclaredClassField(class_schema, class_field_rule)) {
-    return `Field "${field_name}" is not declared for class "${node_class}".`;
-  }
-
-  return null;
-}
-
-/**
- * @param {{ presence: 'required' | 'optional' | 'forbidden' } | undefined} class_field_rule
- * @returns {boolean}
- */
-function isForbiddenClassField(class_field_rule) {
-  return class_field_rule?.presence === 'forbidden';
-}
-
-/**
- * @param {{ fields?: Record<string, { presence: 'required' | 'optional' | 'forbidden' }>, unknown_fields?: 'ignore' | 'error' } | undefined} class_schema
- * @param {{ presence: 'required' | 'optional' | 'forbidden' } | undefined} class_field_rule
- * @returns {boolean}
- */
-function isUndeclaredClassField(class_schema, class_field_rule) {
-  return class_schema?.unknown_fields === 'error' && !class_field_rule;
-}
-
-/**
- * @param {Map<string, GraphNode>} graph_nodes
- * @param {string} kind_name
- * @param {string} node_key
- * @returns {GraphNode}
- */
-function upsertNode(graph_nodes, kind_name, node_key) {
-  const node_id = getNodeId(kind_name, node_key);
-  const existing_node = graph_nodes.get(node_id);
-
-  if (existing_node) {
-    return existing_node;
-  }
-
-  const graph_node = createNode(node_id, kind_name, node_key);
-
-  graph_nodes.set(node_id, graph_node);
-
-  return graph_node;
-}
-
-/**
- * @param {string} node_id
- * @param {string} class_name
- * @param {string} node_key
- * @returns {GraphNode}
- */
-function createNode(node_id, class_name, node_key) {
-  if (class_name === 'document') {
+function resolveEdgeDefinition(repo_config, claim) {
+  if (claim.type === 'markdown.link' || claim.type === 'jsdoc.link') {
     return {
-      $class: class_name,
-      $id: node_id,
-      $path: node_key,
-      id: node_id,
-      path: node_key,
+      relation_name: 'links_to',
+      target_class: 'document',
     };
   }
 
-  return {
-    $class: class_name,
-    $id: node_id,
-    id: node_id,
-    key: node_key,
-  };
-}
-
-/**
- * @param {string} kind_name
- * @param {string} node_key
- * @returns {string}
- */
-function getNodeId(kind_name, node_key) {
-  if (kind_name === 'document') {
-    return `doc:${node_key}`;
+  if (claim.type !== 'directive' || !claim.name) {
+    return null;
   }
 
-  return `${kind_name}:${node_key}`;
-}
+  const field_definition = repo_config.fields?.[claim.name];
 
-/**
- * @param {PatramClaim} claim
- * @returns {string}
- */
-function getNodeFieldValue(claim) {
-  if (typeof claim.value === 'string') {
-    return claim.value;
+  if (field_definition?.type !== 'ref') {
+    return null;
   }
 
-  throw new Error(`Claim "${claim.id}" does not carry a string value.`);
-}
-
-/**
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
- * @returns {{ configurable: false, enumerable: false, value: Record<string, string>, writable: false }}
- */
-function createDocumentNodeIdsProperty(document_node_references) {
   return {
-    configurable: false,
-    enumerable: false,
-    value: Object.fromEntries(
-      [...document_node_references.entries()].map(
-        ([document_path, document_node_reference]) => [
-          document_path,
-          document_node_reference.id,
-        ],
-      ),
-    ),
-    writable: false,
+    relation_name: claim.name,
+    target_class: field_definition.to,
   };
 }
 
@@ -470,12 +262,12 @@ function createDocumentNodeIdsProperty(document_node_references) {
  * @param {PatramClaim} claim
  * @returns {GraphNode}
  */
-function getDocumentGraphNode(graph_nodes, document_node_references, claim) {
-  const document_path = normalizeRepoRelativePath(claim.origin.path);
-  const document_node_reference = document_node_references.get(document_path);
+function getSourceGraphNode(graph_nodes, document_node_references, claim) {
+  const source_path = normalizeRepoRelativePath(claim.origin.path);
+  const document_node_reference = document_node_references.get(source_path);
 
   if (!document_node_reference) {
-    throw new Error(`Missing document node reference for "${document_path}".`);
+    return upsertNode(graph_nodes, 'document', source_path);
   }
 
   const graph_node = upsertNode(
@@ -485,305 +277,354 @@ function getDocumentGraphNode(graph_nodes, document_node_references, claim) {
   );
 
   setCanonicalPath(graph_node, document_node_reference.path);
-
   return graph_node;
 }
 
 /**
- * @param {Map<string, GraphNode>} graph_nodes
- * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
- * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
- * @returns {GraphNode}
+ * @param {MetadataFieldConfig} field_definition
+ * @param {GraphNode} graph_node
+ * @returns {boolean}
  */
-function resolveGraphNode(
-  graph_nodes,
-  node_mapping,
-  claim,
-  document_entity_keys,
-  document_node_references,
-) {
-  if (node_mapping.class === 'document') {
-    return getDocumentGraphNode(graph_nodes, document_node_references, claim);
+function fieldAppliesToNode(field_definition, graph_node) {
+  if (!field_definition.on || field_definition.on.length === 0) {
+    return true;
   }
 
-  const node_key = resolveNodeKey(node_mapping, claim, document_entity_keys);
-
-  return upsertNode(graph_nodes, node_mapping.class, node_key);
+  return field_definition.on.includes(graph_node.identity.class_name);
 }
 
 /**
- * @param {GraphNode} graph_node
- * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
  * @param {PatramClaim} claim
- * @param {string} source_path
  * @returns {string}
  */
-function resolveNodeFieldValue(graph_node, node_mapping, claim, source_path) {
-  if (node_mapping.field === '$id') {
-    return graph_node.id;
-  }
-
-  if (node_mapping.field === '$class') {
-    return graph_node.$class ?? graph_node.kind ?? node_mapping.class;
-  }
-
-  if (node_mapping.field === '$path') {
-    return source_path;
+function getScalarClaimValue(claim) {
+  if (typeof claim.value === 'string') {
+    return claim.value;
   }
 
-  return getNodeFieldValue(claim);
+  throw new Error(`Claim "${claim.id}" does not carry a string value.`);
 }
 
 /**
- * @param {Record<string, GraphNode>} graph_nodes
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {GraphNode} source_graph_node
+ * @param {PatramClaim} claim
+ * @param {Map<string, number>} title_priorities
+ * @param {Map<string, number>} description_priorities
+ * @returns {boolean}
  */
-function attachDocumentNodeAliases(graph_nodes, document_node_references) {
-  for (const [
-    document_path,
-    document_node_reference,
-  ] of document_node_references) {
-    const document_node_id = `doc:${document_path}`;
-
-    if (document_node_id === document_node_reference.id) {
-      continue;
-    }
+function applyDerivedMetadataClaim(
+  source_graph_node,
+  claim,
+  title_priorities,
+  description_priorities,
+) {
+  if (claim.type === 'document.title' && typeof claim.value === 'string') {
+    assignMetadataValue(
+      source_graph_node,
+      'title',
+      claim.value,
+      false,
+      title_priorities,
+      DERIVED_TITLE_PRIORITY,
+    );
+    return true;
+  }
 
-    Object.defineProperty(graph_nodes, document_node_id, {
-      configurable: false,
-      enumerable: false,
-      value: graph_nodes[document_node_reference.id],
-      writable: false,
-    });
+  if (
+    claim.type === 'document.description' &&
+    typeof claim.value === 'string'
+  ) {
+    assignMetadataValue(
+      source_graph_node,
+      'description',
+      claim.value,
+      false,
+      description_priorities,
+      DERIVED_DESCRIPTION_PRIORITY,
+    );
+    return true;
   }
+
+  return false;
 }
 
 /**
- * @param {Map<string, GraphNode>} graph_nodes
- * @param {Map<string, number>} title_priorities
+ * @param {PatramRepoConfig} repo_config
+ * @param {GraphNode} source_graph_node
+ * @param {string} field_name
+ * @returns {{ is_many: boolean } | null}
  */
-function applyFallbackTitles(graph_nodes, title_priorities) {
-  for (const graph_node of graph_nodes.values()) {
-    if (graph_node.title !== undefined) {
-      continue;
-    }
-
-    const fallback_title = getFallbackTitle(graph_node);
+function resolveScalarFieldContext(repo_config, source_graph_node, field_name) {
+  const field_definition = repo_config.fields?.[field_name];
 
-    graph_node.title = fallback_title;
-    title_priorities.set(graph_node.id, 0);
+  if (
+    field_name !== 'title' &&
+    field_name !== 'description' &&
+    (!field_definition || field_definition.type === 'ref')
+  ) {
+    return null;
   }
-}
 
-/**
- * @param {GraphNode} graph_node
- * @returns {string}
- */
-function getFallbackTitle(graph_node) {
-  if (graph_node.$path) {
-    return posix.basename(graph_node.$path);
+  if (
+    field_definition &&
+    !fieldAppliesToNode(field_definition, source_graph_node)
+  ) {
+    return null;
   }
 
-  return getNodeIdKey(graph_node.$id ?? graph_node.id);
+  return {
+    is_many: field_definition?.many === true,
+  };
 }
 
 /**
  * @param {GraphNode} graph_node
+ * @param {string} field_name
+ * @param {string} field_value
+ * @param {boolean} is_many
  * @param {Map<string, number>} title_priorities
- * @param {string} title_value
- * @param {number} source_priority
+ * @param {Map<string, number>} description_priorities
  */
-function setNodeTitle(
+function assignExplicitMetadataValue(
   graph_node,
+  field_name,
+  field_value,
+  is_many,
   title_priorities,
-  title_value,
-  source_priority,
+  description_priorities,
 ) {
-  const current_priority = title_priorities.get(graph_node.id);
-
-  if (current_priority === undefined) {
-    graph_node.title = title_value;
-    title_priorities.set(graph_node.id, source_priority);
+  if (field_name === 'title') {
+    assignMetadataValue(
+      graph_node,
+      'title',
+      field_value,
+      is_many,
+      title_priorities,
+      EXPLICIT_TITLE_PRIORITY,
+    );
     return;
   }
 
-  if (source_priority > current_priority) {
-    graph_node.title = title_value;
-    title_priorities.set(graph_node.id, source_priority);
+  if (field_name === 'description') {
+    assignMetadataValue(
+      graph_node,
+      'description',
+      field_value,
+      is_many,
+      description_priorities,
+      EXPLICIT_DESCRIPTION_PRIORITY,
+    );
     return;
   }
 
-  if (
-    source_priority === current_priority &&
-    graph_node.title !== title_value
-  ) {
-    throw new Error(
-      `Node "${graph_node.id}" has conflicting title values "${graph_node.title}" and "${title_value}".`,
-    );
-  }
+  assignMetadataValue(graph_node, field_name, field_value, is_many);
 }
 
 /**
  * @param {GraphNode} graph_node
  * @param {string} field_name
  * @param {string} field_value
- * @param {MetadataFieldConfig | undefined} field_definition
+ * @param {boolean} multiple
+ * @param {Map<string, number>} [field_priorities]
+ * @param {number} [field_priority]
  */
-function setNodeFieldValue(
+function assignMetadataValue(
   graph_node,
   field_name,
   field_value,
-  field_definition,
+  multiple,
+  field_priorities,
+  field_priority,
 ) {
   if (
-    field_name === '$id' ||
-    field_name === '$class' ||
-    field_name === '$path'
+    shouldSkipLowerPriorityValue(
+      graph_node,
+      field_name,
+      field_priorities,
+      field_priority,
+    )
   ) {
-    setStructuralFieldValue(graph_node, field_name, field_value);
     return;
   }
 
-  if (!field_definition || field_definition.multiple !== true) {
-    setSingleValueField(graph_node, field_name, field_value);
+  const existing_value = graph_node.metadata[field_name];
+
+  if (multiple) {
+    graph_node.metadata[field_name] = appendMetadataValue(
+      existing_value,
+      field_value,
+    );
     return;
   }
 
-  setMultiValueField(graph_node, field_name, field_value);
+  assignSingleMetadataValue(
+    graph_node,
+    field_name,
+    field_value,
+    existing_value,
+  );
 }
 
 /**
  * @param {GraphNode} graph_node
- * @param {'$id' | '$class' | '$path'} field_name
- * @param {string} field_value
+ * @param {string} field_name
+ * @param {Map<string, number> | undefined} field_priorities
+ * @param {number | undefined} field_priority
+ * @returns {boolean}
  */
-function setStructuralFieldValue(graph_node, field_name, field_value) {
-  const current_value = graph_node[field_name];
-
-  if (current_value === undefined) {
-    assignStructuralFieldValue(graph_node, field_name, field_value);
-    return;
+function shouldSkipLowerPriorityValue(
+  graph_node,
+  field_name,
+  field_priorities,
+  field_priority,
+) {
+  if (!field_priorities || field_priority === undefined) {
+    return false;
   }
 
-  if (
-    field_name === '$class' &&
-    graph_node.id.startsWith('doc:') &&
-    current_value === 'document'
-  ) {
-    assignStructuralFieldValue(graph_node, field_name, field_value);
-    return;
+  const priority_key = `${graph_node.identity.id}:${field_name}`;
+  const previous_priority = field_priorities.get(priority_key) ?? 0;
+
+  if (field_priority < previous_priority) {
+    return true;
   }
 
-  if (current_value !== field_value) {
-    throw new Error(
-      `Node "${graph_node.id}" has conflicting structural values for "${field_name}".`,
-    );
+  if (field_priority <= previous_priority) {
+    return false;
   }
+
+  graph_node.metadata[field_name] = undefined;
+  field_priorities.set(priority_key, field_priority);
+  return false;
 }
 
 /**
- * Keep legacy mirrors in sync while the rest of the codebase still reads them.
- *
- * @param {GraphNode} graph_node
- * @param {'$id' | '$class' | '$path'} field_name
+ * @param {GraphNode['metadata'][string]} existing_value
  * @param {string} field_value
- */
-function assignStructuralFieldValue(graph_node, field_name, field_value) {
-  graph_node[field_name] = field_value;
+ * @returns {string[]}
+ */
+function appendMetadataValue(existing_value, field_value) {
+  const next_values = new Set(
+    Array.isArray(existing_value)
+      ? existing_value
+      : existing_value
+        ? [existing_value]
+        : [],
+  );
 
-  if (field_name === '$path') {
-    graph_node.path = field_value;
-  }
+  next_values.add(field_value);
+  return [...next_values].sort();
 }
 
 /**
  * @param {GraphNode} graph_node
  * @param {string} field_name
  * @param {string} field_value
+ * @param {GraphNode['metadata'][string]} existing_value
  */
-function setSingleValueField(graph_node, field_name, field_value) {
-  const current_value = graph_node[field_name];
-
-  if (current_value === undefined) {
-    graph_node[field_name] = field_value;
+function assignSingleMetadataValue(
+  graph_node,
+  field_name,
+  field_value,
+  existing_value,
+) {
+  if (existing_value === undefined) {
+    graph_node.metadata[field_name] = field_value;
     return;
   }
 
-  if (current_value !== field_value) {
-    const current_value_text = Array.isArray(current_value)
-      ? current_value.join(', ')
-      : current_value;
-
+  if (Array.isArray(existing_value)) {
     throw new Error(
-      `Node "${graph_node.id}" has conflicting values for field "${field_name}": "${current_value_text}" and "${field_value}".`,
+      `Node "${graph_node.identity.id}" has conflicting values for field "${field_name}".`,
     );
   }
+
+  if (existing_value === field_value) {
+    return;
+  }
+
+  throw new Error(
+    `Node "${graph_node.identity.id}" has conflicting values for field "${field_name}": "${existing_value}" and "${field_value}".`,
+  );
 }
 
 /**
- * @param {GraphNode} graph_node
- * @param {string} field_name
- * @param {string} field_value
+ * @param {Map<string, GraphNode>} graph_nodes
+ * @param {Map<string, number>} title_priorities
  */
-function setMultiValueField(graph_node, field_name, field_value) {
-  const current_value = graph_node[field_name];
+function applyFallbackTitles(graph_nodes, title_priorities) {
+  for (const graph_node of graph_nodes.values()) {
+    if (graph_node.metadata.title !== undefined) {
+      continue;
+    }
 
-  if (current_value === undefined) {
-    graph_node[field_name] = [field_value];
-    return;
-  }
+    const fallback_title = resolveFallbackTitle(graph_node);
 
-  if (Array.isArray(current_value)) {
-    if (current_value.includes(field_value)) {
-      return;
+    if (!fallback_title) {
+      continue;
     }
 
-    graph_node[field_name] = [...current_value, field_value].sort(
-      compareFieldValues,
+    assignMetadataValue(
+      graph_node,
+      'title',
+      fallback_title,
+      false,
+      title_priorities,
+      DERIVED_TITLE_PRIORITY,
     );
-    return;
   }
-
-  graph_node[field_name] = [current_value, field_value].sort(
-    compareFieldValues,
-  );
 }
 
 /**
- * @param {string} left_value
- * @param {string} right_value
- * @returns {number}
+ * @param {GraphNode} graph_node
+ * @returns {string | null}
  */
-function compareFieldValues(left_value, right_value) {
-  return left_value.localeCompare(right_value, DETERMINISTIC_LOCALE);
-}
+function resolveFallbackTitle(graph_node) {
+  if (graph_node.identity.path) {
+    return posix.basename(graph_node.identity.path);
+  }
 
-/**
- * @param {PatramConfig} patram_config
- * @param {string} field_name
- * @returns {MetadataFieldConfig | undefined}
- */
-function getFieldDefinition(patram_config, field_name) {
-  return patram_config.fields?.[field_name];
+  return graph_node.key ?? null;
 }
 
 /**
- * @param {PatramConfig} patram_config
+ * @param {Map<string, GraphNode>} graph_nodes
  * @param {string} class_name
- * @returns {{ fields?: Record<string, { presence: 'required' | 'optional' | 'forbidden' }>, unknown_fields?: 'ignore' | 'error' } | undefined}
+ * @param {string} node_key
+ * @returns {GraphNode}
  */
-function getClassSchema(patram_config, class_name) {
-  return patram_config.classes[class_name]?.schema;
+function upsertNode(graph_nodes, class_name, node_key) {
+  const node_id = getNodeId(class_name, node_key);
+  const existing_node = graph_nodes.get(node_id);
+
+  if (existing_node) {
+    return existing_node;
+  }
+
+  const graph_node = {
+    identity: {
+      class_name,
+      id: node_id,
+    },
+    key: node_key,
+    metadata: {},
+  };
+
+  graph_nodes.set(node_id, graph_node);
+  return graph_node;
 }
 
 /**
- * @param {string} field_name
- * @returns {field_name is '$class' | '$id' | '$path'}
+ * @param {string} class_name
+ * @param {string} node_key
+ * @returns {string}
  */
-function isStructuralFieldName(field_name) {
-  return STRUCTURAL_FIELD_NAMES.has(field_name);
+function getNodeId(class_name, node_key) {
+  if (class_name === 'document') {
+    return `doc:${node_key}`;
+  }
+
+  return `${class_name}:${node_key}`;
 }
 
 /**
@@ -792,19 +633,37 @@ function isStructuralFieldName(field_name) {
  * @returns {number}
  */
 function compareNodeEntries(left_entry, right_entry) {
-  return left_entry[0].localeCompare(right_entry[0], DETERMINISTIC_LOCALE);
+  return left_entry[0].localeCompare(right_entry[0]);
 }
 
 /**
- * @param {string} node_id
- * @returns {string}
+ * @param {Record<string, GraphNode>} graph_nodes
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  */
-function getNodeIdKey(node_id) {
-  const separator_index = node_id.indexOf(':');
+function attachDocumentNodeAliases(graph_nodes, document_node_references) {
+  for (const document_node_reference of document_node_references.values()) {
+    const document_id = `doc:${document_node_reference.path}`;
 
-  if (separator_index < 0) {
-    return node_id;
+    if (graph_nodes[document_id]) {
+      continue;
+    }
+
+    graph_nodes[document_id] = graph_nodes[document_node_reference.id];
   }
+}
 
-  return node_id.slice(separator_index + 1);
+/**
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @returns {PropertyDescriptor}
+ */
+function createDocumentPathIdsProperty(document_node_references) {
+  return {
+    enumerable: false,
+    value: Object.fromEntries(
+      [...document_node_references.entries()].map(
+        ([document_path, node_reference]) => [document_path, node_reference.id],
+      ),
+    ),
+    writable: false,
+  };
 }