structured-context 0.13.1 → 0.15.0

package/dist/plugins/markdown/parse-embedded.js

@@ -42,7 +42,7 @@ function appendParentField(parentNode, field, linkRef) {
         fieldValue.push(linkRef);
     }
     else {
-        throw new Error(`Cannot append child link to field '${field}' on node '${parentNode.label}': ` +
+        throw new Error(`Cannot append child link to field '${field}' on node '${parentNode.id}': ` +
             `field exists but is not an array (found ${typeof fieldValue}). ` +
             `Child link: ${linkRef}`);
     }
@@ -219,7 +219,7 @@ function isFieldOnlyLine(line) {
         return hasBracketed;
     return /^[a-zA-Z][a-zA-Z0-9_-]*:: *.*$/.test(cleanText);
 }
-function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset, walk) {
+function processListItem(item, parentRef, contentTarget, nodes, makeId, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset, walk) {
     const itemEnd = offsetsOf(item).end;
     const firstPara = item.children.find((c) => c.type === 'paragraph');
     if (!firstPara) {
@@ -270,7 +270,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             : undefined;
         const linkTargets = buildLinkTargets(title);
         const newNode = {
-            label: makeLabel(title),
+            id: makeId(title),
             title,
             schemaData,
             linkTargets,
@@ -294,7 +294,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
                 continue;
             if (child.type === 'list') {
                 for (const subItem of child.children) {
-                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset, walk);
+                    processListItem(subItem, nestedParentRef, newNode, nodes, makeId, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset, walk);
                 }
             }
             else {
@@ -316,7 +316,7 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
  * (directory) to find embedded sub-nodes within a page's content.
  */
 export function extractEmbeddedNodes(body, options) {
-    const { pageTitle, pageType, metadata, fieldMap } = options;
+    const { page, pageType, metadata, fieldMap } = options;
     const levels = metadata.hierarchy?.levels ?? [];
     const hierarchy = levels.map((l) => l.type);
     const relationships = metadata.relationships ?? [];
@@ -325,7 +325,7 @@ export function extractEmbeddedNodes(body, options) {
     const nodes = [];
     // Preamble/root content sink - never added to nodes
     const rootNode = {
-        label: '_root_',
+        id: '_root_',
         title: '_root_',
         schemaData: { type: 'space_on_a_page' },
         linkTargets: [],
@@ -335,8 +335,8 @@ export function extractEmbeddedNodes(body, options) {
     const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
     // In typed-page mode: stack starts with the page's own virtual entry (depth 0).
     // In space_on_a_page mode: stack starts empty (first heading has no parent).
-    const stack = !isOnAPageMode && pageTitle !== undefined
-        ? [{ depth: 0, title: pageTitle, nodeType: pageType, refTarget: pageTitle }]
+    const stack = !isOnAPageMode && page !== undefined
+        ? [{ depth: 0, title: page.targets[0] ?? page.id, nodeType: pageType, refTarget: page.targets[0] ?? page.id }]
         : [];
     let parseState = isOnAPageMode ? 'preamble' : 'active';
     let preambleNodeCount = 0;
@@ -442,8 +442,8 @@ export function extractEmbeddedNodes(body, options) {
         }
         return undefined;
     }
-    function makeLabel(title) {
-        return title;
+    function makeId(title) {
+        return (page ? `${page.id}#${title}` : title);
     }
     /**
      * Walk the stack backwards to find the deepest typed node entry (nodeType !== '').
@@ -486,24 +486,26 @@ export function extractEmbeddedNodes(body, options) {
         return g.headingNode;
     }
     function buildHeadingLinkTargets(rawHeadingText, title, anchor) {
-        if (!pageTitle) {
+        if (!page) {
             return [title];
         }
         const targets = [];
         const sectionTarget = normalizeHeadingSectionTarget(rawHeadingText);
         if (sectionTarget) {
-            targets.push(`${pageTitle}#${sectionTarget}`);
+            for (const pageTarget of page.targets)
+                targets.push(`${pageTarget}#${sectionTarget}`);
         }
         if (anchor) {
-            targets.push(`${pageTitle}#^${anchor}`);
+            for (const pageTarget of page.targets)
+                targets.push(`${pageTarget}#^${anchor}`);
         }
         return targets.length > 0 ? targets : [title];
     }
     function buildListItemLinkTargets(title) {
-        if (!pageTitle)
+        if (!page)
             return [title];
         const normalized = normalizeHeadingSectionTarget(title);
-        return normalized ? [`${pageTitle}#${normalized}`] : [title];
+        return normalized ? page.targets.map((pageTarget) => `${pageTarget}#${normalized}`) : [title];
     }
     let grouping = null;
     let activeNode = rootNode;
@@ -604,7 +606,7 @@ export function extractEmbeddedNodes(body, options) {
                 : undefined;
             const linkTargets = buildHeadingLinkTargets(rawText, title, anchor);
             const headingNode = {
-                label: makeLabel(title),
+                id: makeId(title),
                 title,
                 schemaData,
                 linkTargets,
@@ -655,14 +657,14 @@ export function extractEmbeddedNodes(body, options) {
                     : undefined;
                 const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset, walk);
+                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeId, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset, walk);
                 }
                 grouping = null;
             }
             else {
                 const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset, walk);
+                    processListItem(item, parentRef, activeNode, nodes, makeId, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset, walk);
                 }
             }
         }
@@ -755,7 +757,7 @@ export function extractEmbeddedNodes(body, options) {
                             : undefined;
                         const linkTargets = buildListItemLinkTargets(title);
                         const rowNode = {
-                            label: makeLabel(title),
+                            id: makeId(title),
                             title,
                             schemaData,
                             linkTargets,
@@ -788,7 +790,7 @@ export function extractEmbeddedNodes(body, options) {
                 const { fields: unbracketedFields } = extractUnbracketedFields(afterBracketed);
                 const allFields = applyFieldMap({ ...unbracketedFields, ...bracketedFields }, fieldMap);
                 if ('type' in allFields) {
-                    throw new Error(`Type override via paragraph field is not supported at "${activeNode.schemaData.title ?? activeNode.label}". ` +
+                    throw new Error(`Type override via paragraph field is not supported at "${activeNode.schemaData.title ?? activeNode.id}". ` +
                         `Put [type:: ${allFields.type}] directly in the heading text.`);
                 }
                 Object.assign(activeNode.schemaData, allFields);
@@ -817,7 +819,7 @@ export function extractEmbeddedNodes(body, options) {
                     consumeBlock(activeNode);
                 }
                 else if (Array.isArray(parsed)) {
-                    throw new Error(`YAML block must be an object at "${activeNode.label}".`);
+                    throw new Error(`YAML block must be an object at "${activeNode.id}".`);
                 }
                 else {
                     claimBlock(activeNode);

package/dist/plugins/markdown/read-space.js

@@ -5,7 +5,7 @@ import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
 import { extractLinksFromBody, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
-import { applyFieldMap, inferTypeFromPath, MATTER_OPTIONS } from './util';
+import { applyFieldMap, defaultPageTitle, inferTypeFromPath, MATTER_OPTIONS, pathLinkTargets } from './util';
 export function readSpaceOnAPage(context) {
     const { space, resolvedSchemaPath, schema: { metadata }, } = context;
     const filePath = resolve(space.path);
@@ -20,12 +20,11 @@ export function readSpaceOnAPage(context) {
     if (!hierarchyLevels || hierarchyLevels.length === 0) {
         throw new Error(`Schema at ${resolvedSchemaPath} must define "$metadata.hierarchy.levels" to read a space_on_a_page file.`);
     }
-    const pageTitle = basename(filePath, '.md');
     const fmMatch = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
     const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
     const fileName = basename(filePath);
     const { nodes, preambleNodeCount, terminatedHeadings } = extractEmbeddedNodes(body, {
-        pageTitle,
+        page: { id: fileName, targets: pathLinkTargets(fileName) },
         pageType: 'space_on_a_page',
         metadata,
         file: fileName,
@@ -98,15 +97,18 @@ export async function readSpaceDirectory(context, options) {
             continue;
         }
         const pageType = data.type;
-        const fileBase = basename(file, '.md');
-        const title = data.title ?? fileBase;
+        // A non-string title (e.g. `title: 42`) isn't a usable name or link target; schema validation reports it.
+        const explicitTitle = typeof data.title === 'string' ? data.title : undefined;
+        const title = explicitTitle ?? defaultPageTitle(file, mdCfg.folderIndex);
+        const pathTargets = pathLinkTargets(file);
         const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
         const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
         const pageNode = {
-            label: file,
+            id: file,
             title,
             schemaData: { title, ...data },
-            linkTargets: [title, fileBase],
+            // A title derived from a folder index is display only, never a link target.
+            linkTargets: [...new Set([...(explicitTitle !== undefined ? [explicitTitle] : []), ...pathTargets])],
             type: pageType,
             source: { file, line: 1 },
             ...(data.content !== undefined ? { content: data.content } : {}),
@@ -114,7 +116,7 @@ export async function readSpaceDirectory(context, options) {
         };
         if (!ON_A_PAGE_TYPES.includes(pageType)) {
             const { nodes: embedded, preambleContent, preambleFields, terminatedHeadings, } = extractEmbeddedNodes(parsed.content, {
-                pageTitle: fileBase,
+                page: { id: file, targets: pathTargets },
                 pageType,
                 metadata,
                 fieldMap,

package/dist/plugins/markdown/render-bullets.js

@@ -6,14 +6,14 @@ export function renderBullets(graph) {
         const indent = '  '.repeat(depth);
         const type = node.resolvedType;
         const title = node.title;
-        const nodeChildren = children.get(title) ?? [];
-        if (seen.has(title)) {
+        const nodeChildren = children.get(node.id) ?? [];
+        if (seen.has(node.id)) {
             if (nodeChildren.length > 0) {
                 lines.push(`${indent}- ${type}: ${title} (*)`);
             }
             return;
         }
-        seen.add(title);
+        seen.add(node.id);
         lines.push(`${indent}- ${type}: ${title}`);
         for (const child of nodeChildren) {
             renderNode(child, depth + 1);

package/dist/plugins/markdown/util.d.ts

@@ -38,3 +38,14 @@ export declare function applyFieldMap(data: Record<string, unknown>, fieldMap: R
  * Used for write operations (e.g. template-sync) to translate back to file field names.
  */
 export declare function invertFieldMap(fieldMap: Record<string, string>): Record<string, string>;
+/**
+ * Link targets for a page, most specific first: the space-relative path without `.md` and every shorter
+ * path suffix down to the basename. Obsidian writes these when a bare name is ambiguous.
+ */
+export declare function pathLinkTargets(file: string): string[];
+/**
+ * Display title for a page without an explicit `title`: the containing folder's name when the file is a
+ * folder index (its basename is listed in `folderIndex`, case-insensitively), otherwise the basename.
+ * An index at the space root has no folder to name it and keeps its basename.
+ */
+export declare function defaultPageTitle(file: string, folderIndex: string[] | undefined): string;

package/dist/plugins/markdown/util.js

@@ -119,3 +119,24 @@ export function applyFieldMap(data, fieldMap) {
 export function invertFieldMap(fieldMap) {
     return Object.fromEntries(Object.entries(fieldMap).map(([src, canonical]) => [canonical, src]));
 }
+/**
+ * Link targets for a page, most specific first: the space-relative path without `.md` and every shorter
+ * path suffix down to the basename. Obsidian writes these when a bare name is ambiguous.
+ */
+export function pathLinkTargets(file) {
+    const segments = file.replace(/\\/g, '/').replace(/\.md$/i, '').split('/');
+    return segments.map((_, i) => segments.slice(i).join('/'));
+}
+/**
+ * Display title for a page without an explicit `title`: the containing folder's name when the file is a
+ * folder index (its basename is listed in `folderIndex`, case-insensitively), otherwise the basename.
+ * An index at the space root has no folder to name it and keeps its basename.
+ */
+export function defaultPageTitle(file, folderIndex) {
+    const segments = file.replace(/\\/g, '/').replace(/\.md$/i, '').split('/');
+    const base = segments[segments.length - 1];
+    const folder = segments[segments.length - 2];
+    if (folder !== undefined && folderIndex?.some((name) => name.toLowerCase() === base.toLowerCase()))
+        return folder;
+    return base;
+}

package/dist/plugins/mermaid/render-mermaid.js

@@ -15,7 +15,7 @@ function safeNodeId(id) {
     return id.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 export function renderMermaid(graph) {
-    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet } = graph;
+    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyIds: hierarchyNodeSet } = graph;
     const levels = graph.hierarchy?.levels ?? [];
     let mmd = 'graph TD\n';
     for (let i = 0; i < levels.length; i++) {
@@ -25,21 +25,20 @@ export function renderMermaid(graph) {
     }
     const addedNodes = new Set();
     function addNodeAndChildren(node) {
-        const nodeId = node.title;
+        const nodeId = node.id;
         if (addedNodes.has(nodeId))
             return;
         addedNodes.add(nodeId);
         const type = node.resolvedType;
         const priority = node.schemaData.priority;
-        const label = priority ? `${nodeId} (${priority})` : nodeId;
+        const label = priority ? `${node.title} (${priority})` : node.title;
         const safeId = safeNodeId(nodeId);
         const escapedLabel = escapeMermaidString(label);
         mmd += `  ${safeId}["${escapedLabel}"]:::${type}\n`;
         const nodeChildren = children.get(nodeId) ?? [];
         for (const child of nodeChildren) {
-            const childTitle = child.title;
-            if (hierarchyNodeSet.has(childTitle)) {
-                const safeChildId = safeNodeId(childTitle);
+            if (hierarchyNodeSet.has(child.id)) {
+                const safeChildId = safeNodeId(child.id);
                 mmd += `  ${safeId} --> ${safeChildId}\n`;
                 addNodeAndChildren(child);
             }

package/dist/plugins/miro/cache.js

@@ -30,7 +30,7 @@ export function computeNodeHash(node) {
         status: node.schemaData.status,
         summary: node.schemaData.summary,
         priority: node.schemaData.priority,
-        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.title),
+        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.id),
     };
     return createHash('sha256').update(JSON.stringify(relevant)).digest('hex').slice(0, 16);
 }

package/dist/plugins/miro/sync.js

@@ -17,7 +17,7 @@ export async function miroSync(context, graph, options) {
         throw new Error('No frameId in miro plugin config. Pass --new-frame "Title" to create one.');
     // 3. Filter to hierarchy nodes only (graph already built by caller)
     const levels = graph.hierarchy?.levels ?? [];
-    const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyTitles.has(n.title));
+    const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyIds.has(n.id));
     if (nodes.length === 0) {
         return 'No space nodes found.';
     }
@@ -257,9 +257,10 @@ export async function miroSync(context, graph, options) {
     const desiredEdges = new Map();
     for (const node of nodes) {
         const childTitle = node.title;
-        for (const { title: parentTitle, source, hierarchy } of node.resolvedParents) {
+        for (const { id: parentId, source, hierarchy } of node.resolvedParents) {
             if (source !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
                 continue;
+            const parentTitle = graph.nodes.get(parentId)?.title ?? parentId;
             // Both endpoints must have verified cards on the board
             if (verifiedCardIds.has(parentTitle) && verifiedCardIds.has(childTitle)) {
                 const key = `${parentTitle}\u2192${childTitle}`;

package/dist/read/resolve-graph-edges.js

@@ -31,11 +31,11 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
     const { type: rawChildType, parent: rawParentType, field, fieldOn, multiple } = edge;
     const childType = resolveNodeType(rawChildType, typeAliases);
     const parentType = resolveNodeType(rawParentType, typeAliases);
-    function pushParentRef(childNode, parentTitle) {
-        // Deduplicate by (field, title) — same parent via different fields is intentional
-        if (!childNode.resolvedParents.some((r) => r.field === field && r.title === parentTitle)) {
+    function pushParentRef(childNode, parentId) {
+        // Deduplicate by (field, id) — same parent via different fields is intentional
+        if (!childNode.resolvedParents.some((r) => r.field === field && r.id === parentId)) {
             childNode.resolvedParents.push({
-                title: parentTitle,
+                id: parentId,
                 field,
                 fieldOn,
                 source,
@@ -47,7 +47,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
     function checkShape(ownerNode, rawField) {
         if (multiple && !Array.isArray(rawField)) {
             unresolvedRefs.push({
-                label: ownerNode.label,
+                id: ownerNode.id,
                 ref: String(rawField),
                 field,
                 reason: 'invalid_shape',
@@ -57,7 +57,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
         }
         if (!multiple && typeof rawField !== 'string') {
             unresolvedRefs.push({
-                label: ownerNode.label,
+                id: ownerNode.id,
                 ref: String(rawField),
                 field,
                 reason: 'invalid_shape',
@@ -73,7 +73,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
         const resolved = targetIndex.get(target);
         if (resolved === undefined) {
             unresolvedRefs.push({
-                label: ownerNode.label,
+                id: ownerNode.id,
                 ref,
                 field,
                 reason: 'not_found',
@@ -84,7 +84,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
         }
         if (resolved === null) {
             unresolvedRefs.push({
-                label: ownerNode.label,
+                id: ownerNode.id,
                 ref,
                 field,
                 reason: 'ambiguous',
@@ -109,10 +109,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
                 const childNode = checkAndRecordRef(parentNode, ref);
                 if (!childNode)
                     continue;
-                const parentTitle = parentNode.schemaData.title;
-                if (typeof parentTitle !== 'string')
-                    continue;
-                pushParentRef(childNode, parentTitle);
+                pushParentRef(childNode, parentNode.id);
             }
         }
     }
@@ -129,10 +126,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
                 const parentNode = checkAndRecordRef(childNode, ref);
                 if (!parentNode)
                     continue;
-                const parentTitle = parentNode.schemaData.title;
-                if (typeof parentTitle !== 'string')
-                    continue;
-                pushParentRef(childNode, parentTitle);
+                pushParentRef(childNode, parentNode.id);
             }
         }
     }
@@ -237,12 +231,12 @@ export function resolveGraphEdges(nodes, metadata) {
     for (const node of spaceNodes) {
         node.resolvedLinks = (node.contentLinks ?? []).map((link) => classifyContentLink(link, targetIndex));
     }
-    // Deduplicate by (label, field, ref) — the same broken link may be encountered across
+    // Deduplicate by (id, field, ref) — the same broken link may be encountered across
     // multiple resolveEdge calls (e.g. selfRef + regular hierarchy share the same field).
     const seen = new Set();
     const deduped = [];
     for (const u of unresolvedRefs) {
-        const key = `${u.label}\0${u.field}\0${u.ref}`;
+        const key = `${u.id}\0${u.field}\0${u.ref}`;
         if (!seen.has(key)) {
             seen.add(key);
             deduped.push(u);

package/dist/schema/evaluate-rule.d.ts

@@ -1,4 +1,4 @@
-import type { Rule, RuleViolation, SpaceNode } from '../types';
+import type { NodeId, Rule, RuleViolation, SpaceNode } from '../types';
 /** Evaluation context for JSONata expressions */
 export interface EvalContext {
     /** All nodes in the space (flattened) */
@@ -37,10 +37,10 @@ export declare function tryEvaluateExpression(expr: string, context: EvalContext
  *
  * @param node - The node to build context for
  * @param allNodes - All nodes in the space
- * @param nodeIndex - Map of node titles to nodes for efficient lookup
+ * @param nodeIndex - Map of node ids to nodes for efficient lookup
  * @returns Evaluation context for the node
  */
-export declare function buildEvalContext(node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<string, SpaceNode>): EvalContext;
+export declare function buildEvalContext(node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<NodeId, SpaceNode>): EvalContext;
 /** The violation reported when a rule's `expression` or `when` cannot be evaluated: an authoring error, so always `error`. */
 export declare function expressionErrorViolation(rule: Rule, file: string, error: string): RuleViolation;
 /** The outcome of a rule's `expression` on one node. */
@@ -58,4 +58,4 @@ export type ExpressionRuleResult = {
  * reports the rule's severity; a rule with a semantic part names the expression in the evidence, so the
  * violation is not mistaken for a verdict. An evaluation error reports `error` and is not a `failed` result.
  */
-export declare function evaluateRuleExpression(rule: Rule, node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<string, SpaceNode>, file?: string): Promise<ExpressionRuleResult>;
+export declare function evaluateRuleExpression(rule: Rule, node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<NodeId, SpaceNode>, file?: string): Promise<ExpressionRuleResult>;

package/dist/schema/evaluate-rule.js

@@ -64,12 +64,16 @@ export async function tryEvaluateExpression(expr, context) {
  * @param node - The node to flatten
  * @returns Flattened node with properties directly accessible
  */
-function flattenNode(node) {
+function flattenNode(node, nodeIndex) {
+    const parentTitle = (r) => nodeIndex.get(r.id)?.title ?? r.id;
     return {
         ...node.schemaData,
+        id: node.id,
         resolvedType: node.resolvedType,
-        resolvedParentTitle: node.resolvedParents[0]?.title, // first parent or undefined, provided for convenience
-        resolvedParentTitles: node.resolvedParents.map((r) => r.title), // full array of parent titles
+        resolvedParentId: node.resolvedParents[0]?.id, // first parent or undefined, provided for convenience
+        resolvedParentIds: node.resolvedParents.map((r) => r.id), // full array of parent ids
+        resolvedParentTitle: node.resolvedParents[0] && parentTitle(node.resolvedParents[0]), // display title of the first parent
+        resolvedParentTitles: node.resolvedParents.map(parentTitle), // display titles of all parents
         resolvedLinks: node.resolvedLinks,
     };
 }
@@ -78,23 +82,23 @@ function flattenNode(node) {
  *
  * @param node - The node to build context for
  * @param allNodes - All nodes in the space
- * @param nodeIndex - Map of node titles to nodes for efficient lookup
+ * @param nodeIndex - Map of node ids to nodes for efficient lookup
  * @returns Evaluation context for the node
  */
 export function buildEvalContext(node, allNodes, nodeIndex) {
     // Flatten all nodes for JSONata access
-    const flattenedNodes = allNodes.map(flattenNode);
+    const flattenedNodes = allNodes.map((n) => flattenNode(n, nodeIndex));
     // Build all parent objects from resolvedParents array
     const flattenedParents = [];
-    for (const { title: parentTitle } of node.resolvedParents) {
-        const parentNode = nodeIndex.get(parentTitle);
+    for (const { id: parentId } of node.resolvedParents) {
+        const parentNode = nodeIndex.get(parentId);
         if (parentNode) {
-            flattenedParents.push(flattenNode(parentNode));
+            flattenedParents.push(flattenNode(parentNode, nodeIndex));
         }
     }
     return {
         nodes: flattenedNodes,
-        $$: flattenNode(node),
+        $$: flattenNode(node, nodeIndex),
         parent: flattenedParents[0],
         parents: flattenedParents.length > 0 ? flattenedParents : undefined,
     };
@@ -114,7 +118,7 @@ export function expressionErrorViolation(rule, file, error) {
  * reports the rule's severity; a rule with a semantic part names the expression in the evidence, so the
  * violation is not mistaken for a verdict. An evaluation error reports `error` and is not a `failed` result.
  */
-export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, file = node.label) {
+export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, file = node.id) {
     const expression = rule.expression;
     const outcome = await tryEvaluateExpression(expression, buildEvalContext(node, allNodes, nodeIndex));
     if ('error' in outcome) {

package/dist/schema/gating.d.ts

@@ -1,10 +1,10 @@
 import type { TrimReport } from '../judge/trim';
 import type { SemanticJudgeProvider } from '../judge/types';
 import type { SpaceGraph } from '../space-graph';
-import type { Rule, RuleSeverity, RuleViolation, SpaceNode } from '../types';
+import type { NodeId, Rule, RuleSeverity, RuleViolation, SpaceNode } from '../types';
 /**
- * Whether a failure of this rule gates its subtree: explicit `gatesDescendants`, else true only for `error` severity.
- * `severity` is that of the failure: the rule's own for an expression, the verdict's for a semantic part.
+ * Whether a violation of this rule gates its subtree: explicit `gatesDescendants`, else true only for `error` severity.
+ * `severity` is that of the violation: the rule's own for an expression, the verdict's for a semantic part.
  */
 export declare function ruleGatesDescendants(rule: Rule, severity?: RuleSeverity): boolean;
 /**
@@ -12,10 +12,10 @@ export declare function ruleGatesDescendants(rule: Rule, severity?: RuleSeverity
  * (schema validation or hierarchy structure) that failed on a specific node.
  */
 export type GatingSeed = {
-    /** Label (file) of the failing node. */
+    /** Id (file) of the failing node. */
     file: string;
-    /** Title of the failing node. */
-    title: string;
+    /** Id of the failing node. */
+    id: NodeId;
     /** Which always-run layer produced the failure. */
     reason: 'schema' | 'hierarchy';
 };
@@ -24,10 +24,10 @@ export type GatingSeed = {
  * rule evaluation for itself (if schema/hierarchy caused it) and/or its hierarchy subtree.
  */
 export type CoverageGate = {
-    /** Label (file) of the node whose failure triggered this gate. */
+    /** Id (file) of the node whose failure triggered this gate. */
     file: string;
-    /** Title of the blocking node. */
-    nodeTitle: string;
+    /** Id of the blocking node. */
+    nodeId: NodeId;
     /** What kind of check triggered the gate. */
     reason: 'schema' | 'hierarchy' | 'rule';
     /** Rule id responsible, when `reason` is `'rule'`. */
@@ -56,7 +56,7 @@ export interface GatingOptions {
  * Compute breadth-first depth (1-based, from hierarchy roots and orphans) for every
  * hierarchy-typed node in the graph. Non-hierarchy nodes are not included.
  */
-export declare function computeHierarchyDepths(graph: SpaceGraph): Map<string, number>;
+export declare function computeHierarchyDepths(graph: SpaceGraph): Map<NodeId, number>;
 /**
  * Evaluate executable rules with cascade gating: a schema, hierarchy, or blocking-rule
  * failure on a node suppresses rule evaluation for that node (when the failure is