structured-context 0.13.1 → 0.14.0

package/dist/schema/gating.js

@@ -2,8 +2,8 @@ import { judgeNodes } from '../judge/judge-node';
 import { buildEvalContext, evaluateRuleExpression, expressionErrorViolation, tryEvaluateExpression, } from './evaluate-rule';
 import { ruleSeverities, ruleSeverity } from './rule-severity';
 /**
- * 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 function ruleGatesDescendants(rule, severity = ruleSeverity(rule)) {
     return rule.gatesDescendants ?? severity === 'error';
@@ -20,17 +20,17 @@ export function computeHierarchyDepths(graph) {
     const depths = new Map();
     const queue = [];
     for (const node of [...graph.hierarchyRoots, ...graph.orphans]) {
-        queue.push({ title: node.title, depth: 1 });
+        queue.push({ id: node.id, depth: 1 });
     }
     let i = 0;
     while (i < queue.length) {
-        const { title, depth } = queue[i++];
-        if (depths.has(title))
+        const { id, depth } = queue[i++];
+        if (depths.has(id))
             continue;
-        depths.set(title, depth);
-        for (const child of graph.hierarchyChildren.get(title) ?? []) {
-            if (!depths.has(child.title))
-                queue.push({ title: child.title, depth: depth + 1 });
+        depths.set(id, depth);
+        for (const child of graph.hierarchyChildren.get(id) ?? []) {
+            if (!depths.has(child.id))
+                queue.push({ id: child.id, depth: depth + 1 });
         }
     }
     return depths;
@@ -48,24 +48,24 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     const includeGated = options.includeGated ?? false;
     const nodeIndex = new Map();
     for (const node of nodes) {
-        if (node.title)
-            nodeIndex.set(node.title, node);
+        if (node.id)
+            nodeIndex.set(node.id, node);
     }
     // When a node has both a schema and hierarchy failure, report schema as the reason.
-    const seedByTitle = new Map();
+    const seedById = new Map();
     for (const seed of seeds) {
-        if (!seedByTitle.has(seed.title) || seed.reason === 'schema') {
-            seedByTitle.set(seed.title, seed);
+        if (!seedById.has(seed.id) || seed.reason === 'schema') {
+            seedById.set(seed.id, seed);
         }
     }
     const judge = options.provider;
     const violations = [];
     const gateOrigins = new Map();
-    function originFor(title, seed) {
-        let origin = gateOrigins.get(title);
+    function originFor(id, seed) {
+        let origin = gateOrigins.get(id);
         if (!origin) {
-            origin = { file: seed.file, nodeTitle: title, reason: seed.reason, ruleId: seed.ruleId, gatedFiles: [] };
-            gateOrigins.set(title, origin);
+            origin = { file: seed.file, nodeId: id, reason: seed.reason, ruleId: seed.ruleId, gatedFiles: [] };
+            gateOrigins.set(id, origin);
         }
         return origin;
     }
@@ -85,10 +85,10 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
         const parentsOf = new Map();
         for (const [parent, children] of graph.hierarchyChildren) {
             for (const child of children)
-                parentsOf.set(child.title, [...(parentsOf.get(child.title) ?? []), parent]);
+                parentsOf.set(child.id, [...(parentsOf.get(child.id) ?? []), parent]);
         }
-        const target = nodes.find((n) => n.label === options.judgeTarget);
-        const pending = target ? [target.title] : [];
+        const target = nodes.find((n) => n.id === options.judgeTarget);
+        const pending = target ? [target.id] : [];
         while (pending.length > 0) {
             for (const parent of parentsOf.get(pending.pop()) ?? []) {
                 if (!targetAncestors.has(parent)) {
@@ -104,12 +104,9 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
         for (const r of perNodeRules) {
             if (r.type && r.type !== node.resolvedType)
                 continue;
-            if (judge &&
-                r.semantic !== undefined &&
-                options.judgeTarget !== undefined &&
-                node.label !== options.judgeTarget) {
+            if (judge && r.semantic !== undefined && options.judgeTarget !== undefined && node.id !== options.judgeTarget) {
                 // Ancestors only matter through the gates they could raise.
-                if (!(targetAncestors.has(node.title) && ruleCanGate(r)))
+                if (!(targetAncestors.has(node.id) && ruleCanGate(r)))
                     continue;
             }
             if (r.when) {
@@ -128,11 +125,11 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     async function prepareNode(node) {
         const local = [];
         const prepared = { violations: local, semantic: [], judged: () => { } };
-        const applicable = await applicableRules(node, (rule, error) => local.push(expressionErrorViolation(rule, node.label, error)));
+        const applicable = await applicableRules(node, (rule, error) => local.push(expressionErrorViolation(rule, node.id, error)));
         function report(rule, detail = {}) {
             const severity = detail.severity ?? ruleSeverities(rule)[0] ?? ruleSeverity(rule);
             local.push({
-                file: node.label,
+                file: node.id,
                 ruleId: rule.id,
                 category: rule.category,
                 severity,
@@ -148,7 +145,9 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
                 prepared.blockingRuleId = rule.id;
             }
         }
-        // Cheap expressions first; a semantic part is only evaluated when its own expression passes.
+        // Cheap expressions first. A semantic part is evaluated only when its own expression passes, and not at all
+        // on a node with a gating violation.
+        const semantic = [];
         for (const rule of applicable) {
             if (rule.expression !== undefined) {
                 const result = await evaluateRuleExpression(rule, node, nodes, nodeIndex);
@@ -161,11 +160,13 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
                 }
             }
             if (rule.semantic !== undefined && judge)
-                prepared.semantic.push(rule);
+                semantic.push(rule);
         }
+        if (!prepared.blockingRuleId)
+            prepared.semantic = semantic;
         prepared.judged = (judgements) => {
             for (const j of judgements) {
-                if (j.failed) {
+                if (j.violated) {
                     report(j.rule, {
                         severity: j.severity,
                         verdict: j.verdict,
@@ -209,38 +210,38 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     while (depthNodes.length > 0) {
         const current = [];
         for (const entry of depthNodes) {
-            if (visited.has(entry.node.title))
+            if (visited.has(entry.node.id))
                 continue;
-            visited.add(entry.node.title);
+            visited.add(entry.node.id);
             current.push(entry);
         }
-        const isGated = (e) => e.ancestorOrigin !== undefined || seedByTitle.has(e.node.title);
+        const isGated = (e) => e.ancestorOrigin !== undefined || seedById.has(e.node.id);
         const toEvaluate = current.filter((e) => !isGated(e) || includeGated);
         const evaluated = await evaluateNodeSet(toEvaluate.map((e) => e.node));
-        const blockingByTitle = new Map(toEvaluate.map((e, i) => [e.node.title, evaluated[i].blockingRuleId]));
+        const blockingById = new Map(toEvaluate.map((e, i) => [e.node.id, evaluated[i].blockingRuleId]));
         const next = [];
         for (const { node, ancestorOrigin } of current) {
-            const selfSeed = seedByTitle.get(node.title);
+            const selfSeed = seedById.get(node.id);
             const isGatedByAncestor = ancestorOrigin !== undefined;
             const isSelfBlocked = selfSeed !== undefined;
-            const blockingRuleId = blockingByTitle.get(node.title);
+            const blockingRuleId = blockingById.get(node.id);
             let childOrigin = ancestorOrigin;
             if (isGatedByAncestor) {
-                gateOrigins.get(ancestorOrigin).gatedFiles.push(node.label);
+                gateOrigins.get(ancestorOrigin).gatedFiles.push(node.id);
             }
             else if (isSelfBlocked) {
-                const origin = originFor(node.title, { file: selfSeed.file, reason: selfSeed.reason });
-                origin.gatedFiles.push(node.label);
-                childOrigin = node.title;
+                const origin = originFor(node.id, { file: selfSeed.file, reason: selfSeed.reason });
+                origin.gatedFiles.push(node.id);
+                childOrigin = node.id;
             }
             else if (blockingRuleId) {
-                originFor(node.title, { file: node.label, reason: 'rule', ruleId: blockingRuleId });
-                childOrigin = node.title;
+                originFor(node.id, { file: node.id, reason: 'rule', ruleId: blockingRuleId });
+                childOrigin = node.id;
             }
             else {
                 childOrigin = undefined;
             }
-            for (const child of graph.hierarchyChildren.get(node.title) ?? []) {
+            for (const child of graph.hierarchyChildren.get(node.id) ?? []) {
                 next.push({ node: child, ancestorOrigin: childOrigin });
             }
         }

package/dist/schema/validate-graph.js

@@ -5,7 +5,7 @@ import { resolveNodeType } from '../schema/schema';
  */
 export function validateGraph(nodes, metadata, unresolvedRefs = []) {
     const refErrors = unresolvedRefs.map((u) => ({
-        file: u.source?.file ?? u.label,
+        file: u.source?.file ?? u.id,
         ...(u.source?.line !== undefined ? { line: u.source.line } : {}),
         parent: u.ref,
         error: u.message,
@@ -69,20 +69,17 @@ export function validateHierarchyStructure(nodes, metadata) {
         }
     }
     const nodeIndex = new Map();
-    for (const node of nodes) {
-        const title = node.title;
-        if (title)
-            nodeIndex.set(title, node);
-    }
+    for (const node of nodes)
+        nodeIndex.set(node.id, node);
     for (const node of nodes) {
         const nodeType = node.resolvedType;
         const nodeTitle = node.title;
         for (const parentRef of node.resolvedParents) {
-            const parentNode = nodeIndex.get(parentRef.title);
+            const parentNode = nodeIndex.get(parentRef.id);
             if (!parentNode)
                 continue;
             const parentType = parentNode.resolvedType;
-            const parentTitle = parentRef.title;
+            const parentTitle = parentNode.title;
             if (parentRef.fieldOn === 'parent') {
                 // Field is on the parent node; validate that this node's type matches the expected child type.
                 // Violation is attributed to the field-owner (parent) node.
@@ -90,7 +87,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 if (allowedChildTypes && !allowedChildTypes.has(nodeType)) {
                     const expected = [...allowedChildTypes].join(' or ');
                     violations.push({
-                        file: parentNode.label,
+                        file: parentNode.id,
                         nodeType: parentType,
                         nodeTitle: parentTitle,
                         parentType: nodeType,
@@ -105,7 +102,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 if (allowedTypes && !allowedTypes.has(parentType)) {
                     const expected = [...allowedTypes].join(' or ');
                     violations.push({
-                        file: node.label,
+                        file: node.id,
                         nodeType,
                         nodeTitle,
                         parentType,
@@ -143,7 +140,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 }
                 if (!isValidHierarchy) {
                     violations.push({
-                        file: node.label,
+                        file: node.id,
                         nodeType,
                         nodeTitle,
                         parentType,

package/dist/schema/validate-rules.d.ts

@@ -1,14 +1,14 @@
 import type { TrimReport } from '../judge/trim';
 import type { SemanticJudgeProvider } from '../judge/types';
-import type { Rule, RuleViolation, SpaceNode } from '../types';
+import type { NodeId, Rule, RuleViolation, SpaceNode } from '../types';
 export { DEFAULT_SEVERITY_BY_CATEGORY, ruleSeverity } from './rule-severity';
 export interface ValidateRulesOptions {
     /** Evaluates semantic rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
     judge?: SemanticJudgeProvider;
-    /** Label of the only node to judge (`validate-file`); other nodes' semantic rules are skipped. */
+    /** Id of the only node to judge (`validate-file`); other nodes' semantic rules are skipped. */
     judgeTarget?: string;
-    /** Set of node labels that have already failed upstream structural checks. */
-    gatedNodeLabels?: Set<string>;
+    /** Set of node ids that have already failed upstream structural checks. */
+    gatedNodeIds?: Set<NodeId>;
     trimReport?: TrimReport;
 }
 /**

package/dist/schema/validate-rules.js

@@ -1,6 +1,7 @@
 import { judgeNodes } from '../judge/judge-node';
 import { buildSpaceGraph } from '../space-graph';
 import { buildEvalContext, evaluateRuleExpression, expressionErrorViolation, tryEvaluateExpression, } from './evaluate-rule';
+import { ruleGatesDescendants } from './gating';
 import { ruleSeverities, ruleSeverity } from './rule-severity';
 export { DEFAULT_SEVERITY_BY_CATEGORY, ruleSeverity } from './rule-severity';
 /**
@@ -18,10 +19,7 @@ export async function validateRules(nodes, rules, options = {}) {
     // Build node index for efficient lookups
     const nodeIndex = new Map();
     for (const node of nodes) {
-        const title = node.title;
-        if (title) {
-            nodeIndex.set(title, node);
-        }
+        nodeIndex.set(node.id, node);
     }
     const sentinel = nodes[0];
     const runnable = rules.filter((r) => r.expression !== undefined || (r.semantic !== undefined && judge));
@@ -37,7 +35,7 @@ export async function validateRules(nodes, rules, options = {}) {
             if (rule.when) {
                 const when = await tryEvaluateExpression(rule.when, buildEvalContext(node, nodes, nodeIndex));
                 if ('error' in when) {
-                    violations.push(expressionErrorViolation(rule, node.label, when.error));
+                    violations.push(expressionErrorViolation(rule, node.id, when.error));
                     continue;
                 }
                 if (when.value !== true)
@@ -49,8 +47,8 @@ export async function validateRules(nodes, rules, options = {}) {
     }
     // 1. Expressions, in rule order. A global rule is evaluated once against the full node set; a sentinel node
     // provides the evaluation context (the nodes array is what matters).
-    const failedNodeLabels = new Set(options.gatedNodeLabels); // nodes that failed an expression (or upstream)
-    const notEvaluable = new Set(); // `${rule.id}\0${label}` whose own expression failed or errored
+    const gatedNodeIds = new Set(options.gatedNodeIds); // nodes with a gating violation (or gated upstream)
+    const notEvaluable = new Set(); // `${rule.id}\0${id}` whose own expression failed or errored
     for (const rule of runnable) {
         if (rule.expression === undefined)
             continue;
@@ -67,24 +65,24 @@ export async function validateRules(nodes, rules, options = {}) {
             if (result.passed)
                 continue;
             violations.push(result.violation);
-            notEvaluable.add(`${rule.id}\0${node.label}`);
-            if (result.failed)
-                failedNodeLabels.add(node.label);
+            notEvaluable.add(`${rule.id}\0${node.id}`);
+            if (result.failed && ruleGatesDescendants(rule, result.violation.severity))
+                gatedNodeIds.add(node.id);
         }
     }
-    // 2. Semantic parts, for nodes that passed their own expression. A node that failed an expression or
-    // upstream is left out (safe cascading default).
+    // 2. Semantic parts, for nodes that passed their own expression. A node with a gating violation, or gated
+    // upstream, is left out.
     if (judge) {
         const perNode = []; // kept in node order
         const pending = [];
         for (const node of nodes) {
-            if (options.judgeTarget !== undefined && node.label !== options.judgeTarget)
+            if (options.judgeTarget !== undefined && node.id !== options.judgeTarget)
                 continue;
             const found = [];
             perNode.push(found);
-            if (failedNodeLabels.has(node.label))
+            if (gatedNodeIds.has(node.id))
                 continue;
-            const semantic = runnable.filter((r) => r.semantic !== undefined && applicable.get(r)?.includes(node) && !notEvaluable.has(`${r.id}\0${node.label}`));
+            const semantic = runnable.filter((r) => r.semantic !== undefined && applicable.get(r)?.includes(node) && !notEvaluable.has(`${r.id}\0${node.id}`));
             if (semantic.length > 0)
                 pending.push({ node, rules: semantic, found });
         }
@@ -92,10 +90,10 @@ export async function validateRules(nodes, rules, options = {}) {
         const judged = await judgeNodes(judge, pending, buildSpaceGraph(nodes, undefined), options.trimReport);
         pending.forEach(({ node, found }, i) => {
             for (const j of judged[i] ?? []) {
-                if (!j.failed)
+                if (!j.violated)
                     continue;
                 found.push({
-                    file: node.label,
+                    file: node.id,
                     ruleId: j.rule.id,
                     category: j.rule.category,
                     severity: j.severity ?? ruleSeverities(j.rule)[0] ?? ruleSeverity(j.rule),

package/dist/schemas/_ost_strict.json

@@ -34,7 +34,7 @@
         "category": "best-practice",
         "description": "Explore multiple candidate solutions (aim for at least three) for the target opportunity",
         "type": "opportunity",
-        "expression": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) >= 3"
+        "expression": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentId=$$.current.id and resolvedType='solution']) >= 3"
       },
       {
         "id": "opportunity-customer-voice",

package/dist/space-graph.d.ts

@@ -1,4 +1,4 @@
-import type { Hierarchy, SpaceNode } from './types';
+import type { Hierarchy, NodeId, SpaceNode } from './types';
 /**
  * A navigable graph over a set of SpaceNodes.
  *
@@ -9,20 +9,20 @@ import type { Hierarchy, SpaceNode } from './types';
  * so consumers don't need to build their own indexes.
  */
 export type SpaceGraph = {
-    /** All nodes, keyed by title. Preserves insertion order. */
-    readonly nodes: ReadonlyMap<string, SpaceNode>;
+    /** All nodes, keyed by id. Preserves insertion order. */
+    readonly nodes: ReadonlyMap<NodeId, SpaceNode>;
     /** Hierarchy roots: nodes of the root type with no valid hierarchy parents. */
     readonly hierarchyRoots: readonly SpaceNode[];
     /** Orphans: hierarchy-typed nodes with no valid hierarchy parents in the node set. */
     readonly orphans: readonly SpaceNode[];
     /** Non-hierarchy nodes: type not in the hierarchy levels definition. */
     readonly nonHierarchy: readonly SpaceNode[];
-    /** Hierarchy children map: parent title → direct children connected via this hierarchy's edges only. */
-    readonly hierarchyChildren: ReadonlyMap<string, readonly SpaceNode[]>;
-    /** All-edges children map: parent title → direct children connected via any edge (hierarchy + relationship). */
-    readonly children: ReadonlyMap<string, readonly SpaceNode[]>;
-    /** Set of all node titles that are part of the hierarchy (roots + their descendants + orphans). */
-    readonly hierarchyTitles: ReadonlySet<string>;
+    /** Hierarchy children map: parent id → direct children connected via this hierarchy's edges only. */
+    readonly hierarchyChildren: ReadonlyMap<NodeId, readonly SpaceNode[]>;
+    /** All-edges children map: parent id → direct children connected via any edge (hierarchy + relationship). */
+    readonly children: ReadonlyMap<NodeId, readonly SpaceNode[]>;
+    /** Set of all node ids that are part of the hierarchy (roots + their descendants + orphans). */
+    readonly hierarchyIds: ReadonlySet<NodeId>;
     /** The hierarchy used to build this graph, if the schema has one. */
     readonly hierarchy: Hierarchy | undefined;
 };

package/dist/space-graph.js

@@ -12,22 +12,22 @@ export function buildSpaceGraph(nodes, hierarchy) {
     const nonHierarchy = [];
     // First pass: register all nodes and init adjacency lists
     for (const node of nodes) {
-        nodesMap.set(node.title, node);
-        hierarchyChildrenMap.set(node.title, []);
-        childrenMap.set(node.title, []);
+        nodesMap.set(node.id, node);
+        hierarchyChildrenMap.set(node.id, []);
+        childrenMap.set(node.id, []);
     }
     // Second pass: build children maps (inverted from resolvedParents)
     for (const node of nodes) {
         for (const parentRef of node.resolvedParents) {
             // All-edges map
-            if (!childrenMap.has(parentRef.title))
-                childrenMap.set(parentRef.title, []);
-            childrenMap.get(parentRef.title).push(node);
+            if (!childrenMap.has(parentRef.id))
+                childrenMap.set(parentRef.id, []);
+            childrenMap.get(parentRef.id).push(node);
             // Hierarchy-only map
             if (isHierarchyEdge(parentRef)) {
-                if (!hierarchyChildrenMap.has(parentRef.title))
-                    hierarchyChildrenMap.set(parentRef.title, []);
-                hierarchyChildrenMap.get(parentRef.title).push(node);
+                if (!hierarchyChildrenMap.has(parentRef.id))
+                    hierarchyChildrenMap.set(parentRef.id, []);
+                hierarchyChildrenMap.get(parentRef.id).push(node);
             }
         }
     }
@@ -50,20 +50,20 @@ export function buildSpaceGraph(nodes, hierarchy) {
         }
         else {
             // Check if at least one hierarchy parent is actually in the node set
-            const hasValidParent = hierarchyParents.some((r) => nodesMap.has(r.title));
+            const hasValidParent = hierarchyParents.some((r) => nodesMap.has(r.id));
             if (!hasValidParent) {
                 // All hierarchy parents are dangling — treat as orphan
                 orphans.push(node);
             }
         }
     }
-    // Build hierarchyTitles: BFS from roots + orphans through hierarchyChildren
-    const hierarchyTitles = new Set();
+    // Build hierarchyIds: BFS from roots + orphans through hierarchyChildren
+    const hierarchyIds = new Set();
     function addHierarchySubtree(node) {
-        if (hierarchyTitles.has(node.title))
+        if (hierarchyIds.has(node.id))
             return;
-        hierarchyTitles.add(node.title);
-        for (const child of hierarchyChildrenMap.get(node.title) ?? []) {
+        hierarchyIds.add(node.id);
+        for (const child of hierarchyChildrenMap.get(node.id) ?? []) {
             addHierarchySubtree(child);
         }
     }
@@ -78,7 +78,7 @@ export function buildSpaceGraph(nodes, hierarchy) {
         nonHierarchy,
         hierarchyChildren: hierarchyChildrenMap,
         children: childrenMap,
-        hierarchyTitles,
+        hierarchyIds,
         hierarchy,
     };
 }

package/dist/testing.d.ts

@@ -3,7 +3,7 @@ import type { BaseNode, Hierarchy, HierarchyLevel, Relationship, ResolvedParentR
  * Creates a ResolvedParentRef with sensible defaults for use in tests.
  * Override any field to represent specific edge contexts.
  */
-export declare const makeParentRef: (title: string, overrides?: Partial<ResolvedParentRef>) => ResolvedParentRef;
+export declare const makeParentRef: (id: string, overrides?: Partial<ResolvedParentRef>) => ResolvedParentRef;
 /**
  * Creates a HierarchyLevel with defaults matching schema metadata normalization.
  */

package/dist/testing.js

@@ -2,10 +2,10 @@
  * Creates a ResolvedParentRef with sensible defaults for use in tests.
  * Override any field to represent specific edge contexts.
  */
-export const makeParentRef = (title, overrides = {}) => {
+export const makeParentRef = (id, overrides = {}) => {
     const source = overrides.source ?? 'hierarchy';
     return {
-        title,
+        id: id,
         field: 'parent',
         source,
         ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}),
@@ -55,7 +55,7 @@ export const makeRelationship = (parent, type, overrides = {}) => ({
  * Creates a BaseNode with sensible defaults for use in tests.
  */
 export const makeNode = (title, type, extra = {}, linkTargets) => ({
-    label: `${title}.md`,
+    id: title,
     title,
     schemaData: { title, type, ...extra },
     linkTargets: linkTargets ?? [title],

package/dist/types.d.ts

@@ -28,14 +28,18 @@ export type Relationship = Omit<MetadataContractRelationship, 'field' | 'fieldOn
     fieldOn: 'child' | 'parent';
     multiple: boolean;
 };
+/** Unique key of a node within a space. Supplied by the plugin that produced the node. */
+export type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
 /**
- * A resolved parent reference, capturing not just the parent title but the edge context
+ * A resolved parent reference, capturing not just the parent id but the edge context
  * from which it was resolved. All hierarchy levels and relationships produce entries of
  * this type, forming a single labelled graph rather than separate structures.
  */
 export type ResolvedParentRef = {
-    /** Canonical title of the parent node. */
-    title: string;
+    /** Id of the parent node. */
+    id: NodeId;
     /** The field name that contained the wikilink (e.g. 'parent', 'key_activities', 'produces_data'). */
     field: string;
     /** Whether this edge originates from a hierarchy level or a relationship definition. */
@@ -56,8 +60,8 @@ export type SourceLocation = {
     column?: number;
 };
 export type UnresolvedRef = {
-    /** Source identifier of the node containing the broken link. */
-    label: string;
+    /** Id of the node containing the broken link. */
+    id: NodeId;
     /** Raw wikilink value (or String(rawField) for invalid_shape). */
     ref: string;
     /** Field name that contained the link. */
@@ -109,9 +113,9 @@ export type ResolvedContentLink = ContentLinkBase & {
  * Core enriches this into a SpaceNode after parsing.
  */
 export type BaseNode = {
-    /** Source identifier for error messages (filename or heading title) */
-    label: string;
-    /** Canonical title of the node (from schemaData.title). First-class accessor. */
+    /** Unique key of the node: graph key, parent lookup, gating, duplicate detection and the file in messages. Supplied by the plugin. */
+    id: NodeId;
+    /** Display title (from schemaData.title). May repeat across nodes. */
     title: string;
     /** Fields validated against the active schema. */
     schemaData: Record<string, unknown>;
@@ -138,7 +142,7 @@ export type SpaceNode = BaseNode & {
     resolvedType: string;
     /**
      * Resolved parent references derived from all edge fields (hierarchy levels + relationships).
-     * Each entry carries the parent title, the field it came from, and its edge context.
+     * Each entry carries the parent id, the field it came from, and its edge context.
      * Always present, empty if no parents resolved.
      */
     resolvedParents: ResolvedParentRef[];
@@ -174,7 +178,7 @@ export type RuleSeverity = 'error' | 'warning' | 'info';
 export type { CoverageGate, GatingSeed } from './schema/gating';
 export type { Rule } from './schema/metadata-contract';
 export type RuleViolation = {
-    /** Node label, or empty string for global-scope rules. */
+    /** Node id, or empty string for global-scope rules. */
     file: string;
     ruleId: string;
     category: RuleCategory;

package/dist/validate.d.ts

@@ -3,7 +3,7 @@ import type { Config, SpaceConfig } from './config';
 import type { SemanticJudgeProvider } from './judge/types';
 import { type RuleFilter } from './schema/rule-filter';
 import { extractEntityInfo } from './schema/schema';
-import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -24,7 +24,7 @@ export interface ValidationResult {
         error: string;
     }>;
     duplicateErrors: Array<{
-        title: string;
+        id: NodeId;
         files: string[];
     }>;
     /** All rule violations with their effective severity. Only `error` severity fails validation. */