structured-context 0.17.1 → 0.19.0

package/dist/commands/dump.d.ts

@@ -10,8 +10,8 @@ export interface DumpOptions {
 /**
  * Build the dump payload: every parsed node, or only nodes matched by a filter.
  *
- * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
- * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ * Unfiltered dumps include nodes of an unknown type, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of nodes with a known type.
  */
 export declare function buildDump(context: SpaceContext, options?: DumpOptions): Promise<ReadSpaceResult>;
 export declare function dump(context: SpaceContext, options?: DumpOptions): Promise<void>;

package/dist/commands/dump.js

@@ -4,8 +4,8 @@ import { exportSpaceGraph } from '../space-graph-data';
 /**
  * Build the dump payload: every parsed node, or only nodes matched by a filter.
  *
- * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
- * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ * Unfiltered dumps include nodes of an unknown type, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of nodes with a known type.
  */
 export async function buildDump(context, options = {}) {
     const readResult = await readSpace(context);

package/dist/commands/validate.js

@@ -5,9 +5,8 @@ import { judgeForRun } from '../judge/factory';
 import { resolveSpacePluginSchemas } from '../plugins/util';
 import { parseRuleFilter } from '../schema/rule-filter';
 import { bundledSchemasDir } from '../schema/schema';
-import { formatErrors, ruleViolationMessage, validateSpace } from '../validate';
+import { formatSource, ruleViolationMessage, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
-    const { schema, schemaRefRegistry } = context;
     const result = await validateSpace(context, {
         depth: options.depth,
         includeGated: options.includeGated,
@@ -25,29 +24,26 @@ export async function validate(context, options = {}) {
                 errorsByFile[file] = {};
             errorsByFile[file][key] = severity ? { kind, message, severity } : { kind, message };
         };
-        for (const { file, errors: ajvErrors, nodeData } of result.nodeErrors) {
-            const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, nodeData);
-            for (const { message, dedupeKey } of formatted) {
-                addError(file, `schema:${dedupeKey}`, 'schema', message);
+        for (const { nodeId, issues } of result.nodeErrors) {
+            for (const { message, dedupeKey } of issues) {
+                addError(nodeId, `schema:${dedupeKey}`, 'schema', message);
             }
         }
-        for (const { file, parent, error } of result.refErrors) {
-            addError(file, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
+        for (const { nodeId, parent, error } of result.refErrors) {
+            addError(nodeId, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
         }
-        for (const { id, files } of result.duplicateErrors) {
-            for (const file of files) {
-                const others = files.filter((f) => f !== file);
-                addError(file, `duplicate:${id}`, 'duplicate', `Duplicate id "${id}" also exists in: ${others.join(', ')}`);
-            }
+        for (const { id, sources } of result.duplicateErrors) {
+            const where = sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : '';
+            addError(id, `duplicate:${id}`, 'duplicate', `Duplicate id "${id}" is used by ${sources.length} nodes${where}`);
         }
         for (const v of result.ruleViolations) {
-            if (v.file && v.severity === 'error') {
-                addError(v.file, `rule:${v.ruleId}`, 'rule', ruleViolationMessage(v), v.severity);
+            if (v.nodeId && v.severity === 'error') {
+                addError(v.nodeId, `rule:${v.ruleId}`, 'rule', ruleViolationMessage(v), v.severity);
             }
         }
-        const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.file && v.severity === 'error').length;
+        const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.nodeId && v.severity === 'error').length;
         for (const v of result.hierarchyViolations) {
-            addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
+            addError(v.nodeId, `hierarchy:${v.description}`, 'hierarchy', v.description);
         }
         const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
         const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) +
@@ -100,13 +96,13 @@ export async function validate(context, options = {}) {
     if (result.unresolvedContentLinks.length > 0) {
         console.log(`\nUnresolved content links (may be outside-space or broken):`);
         const byFile = new Map();
-        for (const { file, target } of result.unresolvedContentLinks) {
-            if (!byFile.has(file))
-                byFile.set(file, []);
-            byFile.get(file).push(target);
+        for (const { nodeId, target } of result.unresolvedContentLinks) {
+            if (!byFile.has(nodeId))
+                byFile.set(nodeId, []);
+            byFile.get(nodeId).push(target);
         }
-        for (const [file, targets] of byFile) {
-            console.log(`   ${file}:`);
+        for (const [nodeId, targets] of byFile) {
+            console.log(`   ${nodeId}:`);
             for (const target of targets)
                 console.log(`      ${target}`);
         }
@@ -121,28 +117,25 @@ export async function validate(context, options = {}) {
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
-        result.nodeErrors.forEach(({ file, line, errors, nodeData }) => {
-            const loc = line !== undefined ? `:${line}` : '';
-            console.log(`\n   ${file}${loc}:`);
-            const formatted = formatErrors(errors, schema, schemaRefRegistry, nodeData);
-            formatted.forEach(({ message }) => {
+        result.nodeErrors.forEach(({ nodeId, source, issues }) => {
+            console.log(`\n   ${source ? formatSource(source) : nodeId}:`);
+            issues.forEach(({ message }) => {
                 console.log(`      ${message}`);
             });
         });
     }
     if (result.refErrors.length > 0) {
         console.log(`\nBroken links:`);
-        result.refErrors.forEach(({ file, line, parent, error }) => {
-            const loc = line !== undefined ? `:${line}` : '';
-            console.log(`   ${file}${loc}: ${parent} → ${error}`);
+        result.refErrors.forEach(({ nodeId, source, parent, error }) => {
+            console.log(`   ${source ? formatSource(source) : nodeId}: ${parent} → ${error}`);
         });
     }
     if (result.duplicateErrors.length > 0) {
         console.log(`\nDuplicate ids (same id on multiple nodes):`);
-        result.duplicateErrors.forEach(({ id, files }) => {
+        result.duplicateErrors.forEach(({ id, sources }) => {
             console.log(`   "${id}":`);
-            for (const f of files) {
-                console.log(`      ${f}`);
+            for (const source of sources) {
+                console.log(`      ${formatSource(source)}`);
             }
         });
     }
@@ -155,7 +148,7 @@ export async function validate(context, options = {}) {
                 continue;
             console.log(`  ${severityColor[severity]}${severity.toUpperCase()}${reset} (${violations.length}):`);
             for (const v of violations) {
-                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`);
+                console.log(`    ${v.nodeId ? `${v.nodeId}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`);
                 if (v.evidence) {
                     console.log(`      Evidence: ${v.evidence}`);
                 }
@@ -168,22 +161,22 @@ export async function validate(context, options = {}) {
     if (result.hierarchyViolations.length > 0) {
         console.log(`\nHierarchy violations:`);
         for (const v of result.hierarchyViolations) {
-            console.log(`   ${v.file}: ${v.description}`);
+            console.log(`   ${v.nodeId}: ${v.description}`);
         }
     }
     if (result.coverageGates.length > 0) {
         console.log(`\nCoverage — rule checks gated by cascade (use --include-gated to evaluate anyway):`);
         for (const gate of result.coverageGates) {
             const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
-            console.log(`   ${gate.file} (${gate.nodeId}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
-            for (const file of gate.gatedFiles)
-                console.log(`      ${file}`);
+            console.log(`   ${gate.nodeId} — ${cause} gated ${gate.gatedNodeIds.length} node(s):`);
+            for (const nodeId of gate.gatedNodeIds)
+                console.log(`      ${nodeId}`);
         }
     }
     if (result.skippedByDepth.length > 0) {
         console.log(`\nSkipped by depth limit (--depth ${result.depthLimit}):`);
-        for (const { file } of result.skippedByDepth)
-            console.log(`   ${file}`);
+        for (const { nodeId } of result.skippedByDepth)
+            console.log(`   ${nodeId}`);
     }
     if (result.contextTrimmed.nodeCount > 0) {
         console.log(`\nContext trimmed for ${result.contextTrimmed.nodeCount} node(s) across rules ${result.contextTrimmed.ruleIds.join(', ')}.`);
@@ -206,7 +199,7 @@ export async function validate(context, options = {}) {
     if (result.depthLimit !== undefined) {
         console.log(fmt('  Skipped by depth limit', result.skippedByDepth.length, true, true));
     }
-    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0);
+    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedNodeIds.length, 0);
     console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     console.log(`\n`);
     if (result.nodeErrorCount > 0 ||

package/dist/load-space-graph.d.ts

@@ -10,14 +10,14 @@ export interface AssembleSpaceGraphOptions {
     readResult?: ReadSpaceResult;
 }
 /**
- * Assemble a SpaceGraph from a space context: read the space, drop nodes that
- * fail schema validation, build the graph for the selected hierarchy (the main
- * hierarchy by default), and apply an optional view/filter expression.
+ * Assemble a SpaceGraph from a space context: read the space, drop nodes whose type the schema
+ * does not define, build the graph for the selected hierarchy (the main hierarchy by default),
+ * and apply an optional view/filter expression.
  *
- * Nodes that fail schema validation are silently excluded so the graph is
- * well-formed enough to render and traverse. This is NOT a validation pass —
- * schema-valid nodes may still have broken references, rule violations, or
- * duplicates. Use validateSpace for a full validation report.
+ * A node with schema field errors (for example an invalid enum value) stays in the graph, since
+ * it still has a type and a place in the hierarchy. Only nodes that cannot be placed are left
+ * out. This is NOT a validation pass — nodes may have field errors, broken references, rule
+ * violations, or duplicates. Use validateSpace for a full validation report.
  *
  * Shared by the render pipeline and the public loadSpaceGraph API so their
  * graph-assembly behaviour cannot drift.

package/dist/load-space-graph.js

@@ -1,25 +1,29 @@
 import { filterNodes } from './filter/filter-nodes';
 import { readSpace } from './read/read-space';
+import { extractSchemaTypeNames } from './schema/schema';
 import { createSpaceContext } from './space-context';
 import { buildSpaceGraph, selectHierarchy } from './space-graph';
 /**
- * Assemble a SpaceGraph from a space context: read the space, drop nodes that
- * fail schema validation, build the graph for the selected hierarchy (the main
- * hierarchy by default), and apply an optional view/filter expression.
+ * Assemble a SpaceGraph from a space context: read the space, drop nodes whose type the schema
+ * does not define, build the graph for the selected hierarchy (the main hierarchy by default),
+ * and apply an optional view/filter expression.
  *
- * Nodes that fail schema validation are silently excluded so the graph is
- * well-formed enough to render and traverse. This is NOT a validation pass —
- * schema-valid nodes may still have broken references, rule violations, or
- * duplicates. Use validateSpace for a full validation report.
+ * A node with schema field errors (for example an invalid enum value) stays in the graph, since
+ * it still has a type and a place in the hierarchy. Only nodes that cannot be placed are left
+ * out. This is NOT a validation pass — nodes may have field errors, broken references, rule
+ * violations, or duplicates. Use validateSpace for a full validation report.
  *
  * Shared by the render pipeline and the public loadSpaceGraph API so their
  * graph-assembly behaviour cannot drift.
  */
 export async function assembleSpaceGraph(context, options = {}) {
     const { nodes: allNodes } = options.readResult ?? (await readSpace(context));
-    const { schemaValidator } = context;
-    const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
-    let graph = buildSpaceGraph(validNodes, selectHierarchy(context.schema.metadata, options.hierarchy));
+    const { schema, schemaRefRegistry } = context;
+    const schemaTypes = Array.isArray(schema.oneOf) ? extractSchemaTypeNames(schema, schemaRefRegistry) : undefined;
+    const placeableNodes = schemaTypes
+        ? allNodes.filter((node) => schemaTypes.has(String(node.schemaData.type)))
+        : allNodes;
+    let graph = buildSpaceGraph(placeableNodes, selectHierarchy(context.schema.metadata, options.hierarchy));
     if (options.filter) {
         const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
         graph = await filterNodes(expression, graph);

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

@@ -442,8 +442,15 @@ export function extractEmbeddedNodes(body, options) {
         }
         return undefined;
     }
+    // Ids must be unique, but headings on one page may repeat: the second and later get a ` (2)`, ` (3)` suffix.
+    const usedIds = new Set();
     function makeId(title) {
-        return (page ? `${page.id}#${title}` : title);
+        const base = page ? `${page.id}#${title}` : title;
+        let id = base;
+        for (let n = 2; usedIds.has(id); n++)
+            id = `${base} (${n})`;
+        usedIds.add(id);
+        return id;
     }
     /**
      * Walk the stack backwards to find the deepest typed node entry (nodeType !== '').

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

@@ -42,7 +42,7 @@ export declare function tryEvaluateExpression(expr: string, context: 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;
+export declare function expressionErrorViolation(rule: Rule, nodeId: NodeId | null, error: string): RuleViolation;
 /** The outcome of a rule's `expression` on one node. */
 export type ExpressionRuleResult = {
     passed: true;
@@ -54,8 +54,8 @@ export type ExpressionRuleResult = {
     failed: boolean;
 };
 /**
- * Evaluate a rule's `expression` against a node (`file` empty and `node` a sentinel for a global rule). A failure
+ * Evaluate a rule's `expression` against a node (`nodeId` null and `node` a sentinel for a global rule). A failure
  * 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<NodeId, SpaceNode>, file?: string): Promise<ExpressionRuleResult>;
+export declare function evaluateRuleExpression(rule: Rule, node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<NodeId, SpaceNode>, nodeId?: NodeId | null): Promise<ExpressionRuleResult>;

package/dist/schema/evaluate-rule.js

@@ -104,9 +104,9 @@ export function buildEvalContext(node, allNodes, nodeIndex) {
     };
 }
 /** The violation reported when a rule's `expression` or `when` cannot be evaluated: an authoring error, so always `error`. */
-export function expressionErrorViolation(rule, file, error) {
+export function expressionErrorViolation(rule, nodeId, error) {
     return {
-        file,
+        ...(nodeId !== null && { nodeId }),
         ruleId: rule.id,
         category: rule.category,
         severity: 'error',
@@ -114,15 +114,15 @@ export function expressionErrorViolation(rule, file, error) {
     };
 }
 /**
- * Evaluate a rule's `expression` against a node (`file` empty and `node` a sentinel for a global rule). A failure
+ * Evaluate a rule's `expression` against a node (`nodeId` null and `node` a sentinel for a global rule). A failure
  * 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.id) {
+export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, nodeId = node.id) {
     const expression = rule.expression;
     const outcome = await tryEvaluateExpression(expression, buildEvalContext(node, allNodes, nodeIndex));
     if ('error' in outcome) {
-        return { passed: false, failed: false, violation: expressionErrorViolation(rule, file, outcome.error) };
+        return { passed: false, failed: false, violation: expressionErrorViolation(rule, nodeId, outcome.error) };
     }
     if (outcome.value === true)
         return { passed: true };
@@ -130,7 +130,7 @@ export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, fi
         passed: false,
         failed: true,
         violation: {
-            file,
+            ...(nodeId !== null && { nodeId }),
             ruleId: rule.id,
             category: rule.category,
             severity: ruleSeverity(rule),

package/dist/schema/gating.d.ts

@@ -12,8 +12,6 @@ export declare function ruleGatesDescendants(rule: Rule, severity?: RuleSeverity
  * (schema validation or hierarchy structure) that failed on a specific node.
  */
 export type GatingSeed = {
-    /** Id (file) of the failing node. */
-    file: string;
     /** Id of the failing node. */
     id: NodeId;
     /** Which always-run layer produced the failure. */
@@ -24,16 +22,14 @@ export type GatingSeed = {
  * rule evaluation for itself (if schema/hierarchy caused it) and/or its hierarchy subtree.
  */
 export type CoverageGate = {
-    /** Id (file) of the node whose failure triggered this gate. */
-    file: 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'`. */
     ruleId?: string;
-    /** Labels of nodes whose rule evaluation was suppressed as a result of this gate. */
-    gatedFiles: string[];
+    /** Ids of nodes whose rule evaluation was suppressed as a result of this gate. */
+    gatedNodeIds: NodeId[];
 };
 export type GatedRuleEvaluation = {
     violations: RuleViolation[];

package/dist/schema/gating.js

@@ -64,7 +64,7 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     function originFor(id, seed) {
         let origin = gateOrigins.get(id);
         if (!origin) {
-            origin = { file: seed.file, nodeId: id, reason: seed.reason, ruleId: seed.ruleId, gatedFiles: [] };
+            origin = { nodeId: id, reason: seed.reason, ruleId: seed.ruleId, gatedNodeIds: [] };
             gateOrigins.set(id, origin);
         }
         return origin;
@@ -73,7 +73,7 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     const sentinel = nodes[0];
     if (sentinel) {
         for (const rule of globalRules) {
-            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, '');
+            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, null);
             if (!result.passed)
                 violations.push(result.violation);
         }
@@ -129,7 +129,7 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
         function report(rule, detail = {}) {
             const severity = detail.severity ?? ruleSeverities(rule)[0] ?? ruleSeverity(rule);
             local.push({
-                file: node.id,
+                nodeId: node.id,
                 ruleId: rule.id,
                 category: rule.category,
                 severity,
@@ -227,15 +227,15 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
             const blockingRuleId = blockingById.get(node.id);
             let childOrigin = ancestorOrigin;
             if (isGatedByAncestor) {
-                gateOrigins.get(ancestorOrigin).gatedFiles.push(node.id);
+                gateOrigins.get(ancestorOrigin).gatedNodeIds.push(node.id);
             }
             else if (isSelfBlocked) {
-                const origin = originFor(node.id, { file: selfSeed.file, reason: selfSeed.reason });
-                origin.gatedFiles.push(node.id);
+                const origin = originFor(node.id, { reason: selfSeed.reason });
+                origin.gatedNodeIds.push(node.id);
                 childOrigin = node.id;
             }
             else if (blockingRuleId) {
-                originFor(node.id, { file: node.id, reason: 'rule', ruleId: blockingRuleId });
+                originFor(node.id, { reason: 'rule', ruleId: blockingRuleId });
                 childOrigin = node.id;
             }
             else {
@@ -249,6 +249,6 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     }
     return {
         violations,
-        gates: [...gateOrigins.values()].filter((g) => g.gatedFiles.length > 0),
+        gates: [...gateOrigins.values()].filter((g) => g.gatedNodeIds.length > 0),
     };
 }

package/dist/schema/schema.d.ts

@@ -17,6 +17,12 @@ export type PluginSchemaSource = {
  * Throws if a lower-precedence schema collides with a reserved $id or violates namespace rules.
  */
 export declare function buildFullRegistry(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): Map<string, AnySchemaObject>;
+/**
+ * Validator for one node type: the schema's shared `allOf` plus only that type's `oneOf` branch.
+ * Errors then come only from the node's own type, not from every branch that did not match.
+ * Returns undefined when the schema has no such branch, so callers fall back to the full validator.
+ */
+export declare function typeValidatorFor(fullValidator: ValidateFunction, type: string): ValidateFunction | undefined;
 export declare function createValidator(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): ValidateFunction;
 export declare function resolveNodeType(type: string, typeAliases: Record<string, string> | undefined): string;
 export interface EntityInfo {

package/dist/schema/schema.js

@@ -234,7 +234,68 @@ function compileValidator(targetSchema, schemaRefRegistry) {
             continue;
         ajv.addSchema(schema);
     }
-    return ajv.compile(targetSchema);
+    const validator = ajv.compile(targetSchema);
+    typeValidators.set(validator, createTypeValidatorLookup(ajv, targetSchema, schemaRefRegistry));
+    return validator;
+}
+/** Root keywords that do not constrain a node: a root with any other keyword cannot be split into per-type checks. */
+const NON_CONSTRAINING_ROOT_KEYWORDS = new Set([
+    '$schema',
+    '$id',
+    '$metadata',
+    '$defs',
+    'title',
+    'description',
+    'allOf',
+    'oneOf',
+]);
+/** Per-type lookups, keyed by the full-schema validator they were compiled alongside. */
+const typeValidators = new WeakMap();
+/**
+ * Validator for one node type: the schema's shared `allOf` plus only that type's `oneOf` branch.
+ * Errors then come only from the node's own type, not from every branch that did not match.
+ * Returns undefined when the schema has no such branch, so callers fall back to the full validator.
+ */
+export function typeValidatorFor(fullValidator, type) {
+    return typeValidators.get(fullValidator)?.(type);
+}
+/**
+ * Compiled on first use. The wrapper references the branches inside the already-compiled root,
+ * so a branch's relative `$ref`s still resolve against the root.
+ */
+function createTypeValidatorLookup(ajv, rootSchema, schemaRefRegistry) {
+    const rootId = rootSchema.$id;
+    if (typeof rootId !== 'string' ||
+        !Array.isArray(rootSchema.oneOf) ||
+        !Object.keys(rootSchema).every((k) => NON_CONSTRAINING_ROOT_KEYWORDS.has(k))) {
+        return () => undefined;
+    }
+    const branchByType = new Map();
+    rootSchema.oneOf.forEach((branch, index) => {
+        const typeDef = mergeVariantProperties(branch, rootSchema, schemaRefRegistry).properties.type;
+        const types = typeDef?.const !== undefined ? [typeDef.const] : Array.isArray(typeDef?.enum) ? typeDef.enum : [];
+        for (const t of types)
+            if (!branchByType.has(String(t)))
+                branchByType.set(String(t), index);
+    });
+    const shared = Array.isArray(rootSchema.allOf)
+        ? rootSchema.allOf.map((_, i) => ({ $ref: `${rootId}#/allOf/${i}` }))
+        : [];
+    const compiled = new Map();
+    return (type) => {
+        const index = branchByType.get(type);
+        if (index === undefined)
+            return undefined;
+        let validator = compiled.get(index);
+        if (!validator) {
+            validator = ajv.compile({
+                $id: `${rootId}/__type/${index}`,
+                allOf: [...shared, { $ref: `${rootId}#/oneOf/${index}` }],
+            });
+            compiled.set(index, validator);
+        }
+        return validator;
+    };
 }
 export function createValidator(schemaPath, pluginSchemas) {
     return compileValidator(readRawSchema(schemaPath), buildFullRegistry(schemaPath, pluginSchemas));

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

@@ -1,9 +1,9 @@
-import type { GraphViolation, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types';
+import type { GraphViolation, NodeId, SchemaMetadata, SourceLocation, SpaceNode, UnresolvedRef } from '../types';
 export interface GraphValidationResult {
     violations: GraphViolation[];
     refErrors: Array<{
-        file: string;
-        line?: number;
+        nodeId: NodeId;
+        source?: SourceLocation;
         parent: string;
         error: string;
     }>;

package/dist/schema/validate-graph.js

@@ -5,8 +5,8 @@ import { resolveNodeType } from '../schema/schema';
  */
 export function validateGraph(nodes, metadata, unresolvedRefs = []) {
     const refErrors = unresolvedRefs.map((u) => ({
-        file: u.source?.file ?? u.id,
-        ...(u.source?.line !== undefined ? { line: u.source.line } : {}),
+        nodeId: u.id,
+        ...(u.source !== undefined && { source: u.source }),
         parent: u.ref,
         error: u.message,
     }));
@@ -87,7 +87,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 if (allowedChildTypes && !allowedChildTypes.has(nodeType)) {
                     const expected = [...allowedChildTypes].join(' or ');
                     violations.push({
-                        file: parentNode.id,
+                        nodeId: parentNode.id,
                         nodeType: parentType,
                         nodeTitle: parentTitle,
                         parentType: nodeType,
@@ -102,7 +102,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 if (allowedTypes && !allowedTypes.has(parentType)) {
                     const expected = [...allowedTypes].join(' or ');
                     violations.push({
-                        file: node.id,
+                        nodeId: node.id,
                         nodeType,
                         nodeTitle,
                         parentType,
@@ -140,7 +140,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 }
                 if (!isValidHierarchy) {
                     violations.push({
-                        file: node.id,
+                        nodeId: node.id,
                         nodeType,
                         nodeTitle,
                         parentType,

package/dist/schema/validate-rules.js

@@ -55,7 +55,7 @@ export async function validateRules(nodes, rules, options = {}) {
         if (rule.global) {
             if (!sentinel)
                 continue;
-            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, '');
+            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, null);
             if (!result.passed)
                 violations.push(result.violation);
             continue;
@@ -93,7 +93,7 @@ export async function validateRules(nodes, rules, options = {}) {
                 if (!j.violated)
                     continue;
                 found.push({
-                    file: node.id,
+                    nodeId: node.id,
                     ruleId: j.rule.id,
                     category: j.rule.category,
                     severity: j.severity ?? ruleSeverities(j.rule)[0] ?? ruleSeverity(j.rule),

package/dist/types.d.ts

@@ -178,8 +178,8 @@ export type RuleSeverity = 'error' | 'warning' | 'info';
 export type { CoverageGate, GatingSeed } from './schema/gating';
 export type { Rule } from './schema/metadata-contract';
 export type RuleViolation = {
-    /** Node id, or empty string for global-scope rules. */
-    file: string;
+    /** Id of the violating node. Absent for global-scope rules. */
+    nodeId?: NodeId;
     ruleId: string;
     category: RuleCategory;
     severity: RuleSeverity;
@@ -192,7 +192,8 @@ export type RuleViolation = {
     guidance?: string;
 };
 export type GraphViolation = {
-    file: string;
+    /** Id of the node whose parent link breaks the hierarchy. */
+    nodeId: NodeId;
     nodeType: string;
     nodeTitle: string;
     parentType: string;

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, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -12,20 +12,21 @@ export interface ValidationResult {
     validCount: number;
     nodeErrorCount: number;
     nodeErrors: Array<{
-        file: string;
-        line?: number;
-        errors: ErrorObject[];
-        nodeData: Record<string, unknown>;
+        nodeId: NodeId;
+        source?: SourceLocation;
+        /** Formatted, deduplicated schema problems for the node, one per field problem. */
+        issues: FormattedError[];
     }>;
     refErrors: Array<{
-        file: string;
-        line?: number;
+        nodeId: NodeId;
+        source?: SourceLocation;
         parent: string;
         error: string;
     }>;
+    /** Nodes that share an id; `sources` lists where each is defined (a node without a source adds no entry). */
     duplicateErrors: Array<{
         id: NodeId;
-        files: string[];
+        sources: SourceLocation[];
     }>;
     /** All rule violations with their effective severity. Only `error` severity fails validation. */
     ruleViolations: RuleViolation[];
@@ -34,7 +35,7 @@ export interface ValidationResult {
     parseIssues: ParseIssue[];
     /** Content links that could not be resolved to a space node. Warning only — not counted in errors. */
     unresolvedContentLinks: Array<{
-        file: string;
+        nodeId: NodeId;
         target: string;
     }>;
     /**
@@ -50,7 +51,7 @@ export interface ValidationResult {
     };
     /** Nodes excluded from validation entirely by a `depth` limit (breadth-first from hierarchy roots). */
     skippedByDepth: Array<{
-        file: string;
+        nodeId: NodeId;
         title: string;
     }>;
     /** The depth limit applied, if any (undefined means the full space was validated). */
@@ -72,8 +73,15 @@ export interface ValidateSpaceOptions {
     /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
     judge?: SemanticJudgeProvider;
 }
+/** `file`, `file:line` or `file:line:column`, for messages. */
+export declare function formatSource({ file, line, column }: SourceLocation): string;
 /** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
 export declare function ruleViolationMessage(v: RuleViolation): string;
+/**
+ * Nodes that share an id, with where each is defined. A plugin should keep ids unique, so this guards that contract.
+ * Display titles may repeat.
+ */
+export declare function findDuplicateIds(nodes: SpaceNode[]): ValidationResult['duplicateErrors'];
 /**
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.

package/dist/validate.js

@@ -2,7 +2,7 @@ import { isAbsolute, relative, resolve } from 'node:path';
 import { readSpace } from './read/read-space';
 import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating';
 import { filterRules } from './schema/rule-filter';
-import { extractEntityInfo } from './schema/schema';
+import { extractEntityInfo, typeValidatorFor } from './schema/schema';
 import { validateGraph } from './schema/validate-graph';
 import { validateRules } from './schema/validate-rules';
 import { createSpaceContext } from './space-context';
@@ -94,6 +94,10 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
     }
     return formatted;
 }
+/** `file`, `file:line` or `file:line:column`, for messages. */
+export function formatSource({ file, line, column }) {
+    return line === undefined ? file : `${file}:${line}${column === undefined ? '' : `:${column}`}`;
+}
 /** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
 export function ruleViolationMessage(v) {
     const evidence = v.evidence ? ` (Evidence: ${v.evidence})` : '';
@@ -131,6 +135,24 @@ async function evaluateSpaceRules(nodes, metadata, seeds, options = {}) {
         trimReport: options.trimReport,
     });
 }
+/**
+ * Nodes that share an id, with where each is defined. A plugin should keep ids unique, so this guards that contract.
+ * Display titles may repeat.
+ */
+export function findDuplicateIds(nodes) {
+    const idToNodes = new Map();
+    for (const node of nodes) {
+        if (!idToNodes.has(node.id))
+            idToNodes.set(node.id, []);
+        idToNodes.get(node.id).push(node);
+    }
+    const duplicates = [];
+    for (const [id, sameId] of idToNodes) {
+        if (sameId.length > 1)
+            duplicates.push({ id, sources: sameId.flatMap((n) => (n.source ? [n.source] : [])) });
+    }
+    return duplicates;
+}
 /**
  * The one validation pipeline: type and schema checks, duplicate titles, reference and hierarchy
  * checks, cascade-gated rules, and unresolved content links. Returns every entry; `validateSpace`
@@ -155,46 +177,34 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
         contextTrimmed: { nodeCount: 0, ruleIds: [] },
     };
     for (const node of nodes) {
-        // Early type validation - check before full AJV validation to prevent cascading errors
+        // Check the type first: an unknown type reports one error instead of one per oneOf branch.
         const nodeType = node.schemaData.type;
         if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
             const sortedTypes = [...validTypes].sort();
             result.nodeFailures.push({
                 node,
-                invalidType: { validTypes },
-                errors: [
+                issues: [
                     {
-                        instancePath: '/type',
-                        keyword: 'enum',
                         message: `Invalid type "${nodeType}". Valid types are: ${sortedTypes.join(', ')}`,
-                        params: { allowedValues: sortedTypes },
-                        schemaPath: '#/oneOf',
-                        data: nodeType,
+                        dedupeKey: `type:${sortedTypes.join(',')}`,
                     },
                 ],
             });
             continue;
         }
-        if (schemaValidator(node.schemaData)) {
+        // A valid type is checked against its own branch only, so errors come from that type alone.
+        const validate = (nodeType !== undefined && typeValidatorFor(schemaValidator, nodeType)) || schemaValidator;
+        if (validate(node.schemaData)) {
             result.validCount++;
         }
         else {
-            result.nodeFailures.push({ node, errors: schemaValidator.errors || [] });
-        }
-    }
-    // Detect duplicate node ids. Display titles may repeat.
-    const idToFiles = new Map();
-    for (const node of nodes) {
-        if (!idToFiles.has(node.id)) {
-            idToFiles.set(node.id, []);
-        }
-        idToFiles.get(node.id).push(node.id);
-    }
-    for (const [id, files] of idToFiles) {
-        if (files.length > 1) {
-            result.duplicateErrors.push({ id, files });
+            result.nodeFailures.push({
+                node,
+                issues: formatErrors(validate.errors || [], schema, schemaRefRegistry, node.schemaData),
+            });
         }
     }
+    result.duplicateErrors.push(...findDuplicateIds(nodes));
     // Validate all hierarchy constraints (field references and structure)
     const hierarchyValidation = validateGraph(nodes, metadata, unresolvedRefs);
     result.refErrors.push(...hierarchyValidation.refErrors);
@@ -207,9 +217,9 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     if (metadata.rules) {
         const seeds = [
             ...result.nodeFailures.map(({ node }) => {
-                return { file: node.source?.file ?? node.id, id: node.id, reason: 'schema' };
+                return { id: node.id, reason: 'schema' };
             }),
-            ...result.hierarchyViolations.map((v) => ({ file: v.file, id: v.file, reason: 'hierarchy' })),
+            ...result.hierarchyViolations.map((v) => ({ id: v.nodeId, reason: 'hierarchy' })),
         ];
         const trimReport = { nodes: new Set(), ruleIds: new Set() };
         const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { ...options, trimReport });
@@ -225,7 +235,7 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
                 const key = `${node.id}::${link.target}`;
                 if (!seen.has(key)) {
                     seen.add(key);
-                    result.unresolvedContentLinks.push({ file: node.id, target: link.target });
+                    result.unresolvedContentLinks.push({ nodeId: node.id, target: link.target });
                 }
             }
         }
@@ -250,7 +260,7 @@ export async function validateSpace(context, options = {}) {
         for (const node of nodes) {
             const nodeDepth = depths.get(node.id);
             if (nodeDepth !== undefined && nodeDepth > options.depth) {
-                skippedByDepth.push({ file: node.id, title: node.title });
+                skippedByDepth.push({ nodeId: node.id, title: node.title });
             }
             else {
                 included.push(node);
@@ -266,11 +276,10 @@ export async function validateSpace(context, options = {}) {
     return {
         validCount: result.validCount,
         nodeErrorCount: result.nodeFailures.length,
-        nodeErrors: result.nodeFailures.map(({ node, errors }) => ({
-            file: node.source?.file ?? node.id,
-            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
-            errors,
-            nodeData: node.schemaData,
+        nodeErrors: result.nodeFailures.map(({ node, issues }) => ({
+            nodeId: node.id,
+            ...(node.source !== undefined && { source: node.source }),
+            issues,
         })),
         refErrors: result.refErrors,
         duplicateErrors: result.duplicateErrors,
@@ -302,54 +311,43 @@ export function resolveFileSpace(filePath, config) {
  * Select one file's entries from a space's validation result: issues keyed and formatted, errors split from warnings.
  * Pure — a file's entries are exactly its slice of the result.
  */
-function issuesForFile(result, label, context, includeGated) {
-    const { schema, schemaRefRegistry } = context;
+function issuesForFile(result, label, includeGated) {
     const errors = {};
     const warnings = {};
-    for (const { node, errors: ajvErrors, invalidType } of result.nodeFailures) {
+    for (const { node, issues } of result.nodeFailures) {
         if (node.id !== label)
             continue;
         const position = {
             ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
             ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
         };
-        if (invalidType) {
-            errors[`schema:type:${invalidType.validTypes.join(',')}`] = {
-                kind: 'schema',
-                message: ajvErrors[0].message,
-                ...position,
-            };
-            continue;
-        }
-        const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, node.schemaData);
-        for (const { message, dedupeKey } of formatted) {
+        for (const { message, dedupeKey } of issues) {
             errors[`schema:${dedupeKey}`] = { kind: 'schema', message, ...position };
         }
     }
-    // Duplicate key errors — include if this file is one of the duplicates
-    for (const { id, files } of result.duplicateErrors) {
-        if (!files.includes(label))
+    // Duplicate id errors — include if this node's id is duplicated
+    for (const { id, sources } of result.duplicateErrors) {
+        if (id !== label)
             continue;
-        const others = files.filter((f) => f !== label);
         errors[`duplicate:${id}`] = {
             kind: 'duplicate',
-            message: `Duplicate id "${id}" also exists in: ${others.join(', ')}`,
+            message: `Duplicate id "${id}" is used by ${sources.length} nodes${sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : ''}`,
         };
     }
     // Broken links and hierarchy violations from this file
-    for (const { file, parent, error } of result.refErrors) {
-        if (file === label) {
+    for (const { nodeId, parent, error } of result.refErrors) {
+        if (nodeId === label) {
             errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
         }
     }
     for (const v of result.hierarchyViolations) {
-        if (v.file === label) {
+        if (v.nodeId === label) {
             errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
         }
     }
     // Rule violations — only error severity counts as an error.
     for (const v of result.ruleViolations) {
-        if (v.file === label) {
+        if (v.nodeId === label) {
             const target = v.severity === 'error' ? errors : warnings;
             target[`rule:${v.ruleId}`] = {
                 kind: 'rule',
@@ -360,18 +358,18 @@ function issuesForFile(result, label, context, includeGated) {
     }
     // A gated file with no violations would otherwise look clean — say that its rules were not checked.
     for (const gate of result.coverageGates) {
-        if (!gate.gatedFiles.includes(label))
+        if (!gate.gatedNodeIds.some((id) => id === label))
             continue;
         const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
-        warnings[`gated:${gate.file}`] = {
+        warnings[`gated:${gate.nodeId}`] = {
             kind: 'gated',
-            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.file}`,
+            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.nodeId}`,
             severity: 'info',
         };
     }
     // Unresolved content links (warnings — do not affect errorCount)
     for (const link of result.unresolvedContentLinks) {
-        if (link.file === label) {
+        if (link.nodeId === label) {
             warnings[`content-link:${link.target}`] = {
                 kind: 'content-link',
                 message: `Unresolved content link: ${link.target}`,
@@ -400,7 +398,7 @@ export async function validateResolvedFile(filePath, label, context, options = {
         judge: options.judge,
         judgeTarget: label,
     });
-    const { errors, warnings } = issuesForFile(result, label, context, options.includeGated);
+    const { errors, warnings } = issuesForFile(result, label, options.includeGated);
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,

package/docs/concepts.md

@@ -111,12 +111,18 @@ Three values on every node do separate jobs:
 
 | Value | Job | Unique? | Markdown source |
 |---|---|---|---|
-| `id` | Identifies the node: graph key, parent lookup, gating, duplicate detection, and the file shown in messages | Yes. Two nodes with the same `id` are a duplicate error | Path relative to the space root, with extension (`projects/alpha/Overview.md`). Embedded nodes use `<page id>#<heading>` |
+| `id` | Identifies the node: graph key, parent lookup, gating, duplicate detection, and the file shown in messages | Yes. Two nodes with the same `id` are a duplicate error | Path relative to the space root, with extension (`projects/alpha/Overview.md`). Embedded nodes use `<page id>#<heading>`, with ` (2)`, ` (3)` added to repeated headings on one page |
 | `title` | Display name in `show`, rendered output and judge prompts | No | `title:` frontmatter, else the containing folder's name for a [folder index](#folder-index), else the file's basename |
 | `linkTargets` | The names a wikilink may use to reach the node | Per name. A name shared by several nodes is reported as ambiguous where a link uses it | The explicit `title:`, the basename, and every path suffix without `.md` |
 
 A wikilink is looked up in `linkTargets`, and the result is stored as the target node's `id`. Other values hold the rest of the picture: `source` is where the node is defined, `resolvedParents` lists parents by `id`, and `resolvedLinks` classifies content links. A parent field resolves exactly as a link does.
 
+### Validation results and nodes
+
+A validation result refers to a node by its `id`, in a `nodeId` field. Where the node is defined is a separate `source` (`file`, and `line` / `column` where available). A result may copy a node's identity and location, but not its content. A node can lack a `source` (for example when a plugin reads from a service rather than files), so treat `source` as optional.
+
+Rule violations on a global rule have no `nodeId`.
+
 ### Folder index
 
 A **folder index** is a page that stands for its folder: `Overview.md` or `index.md` inside `projects/alpha/`. Obsidian has no container pages, so a node with child pages is a folder plus an index page. Listing the index basenames in the markdown plugin's [`folderIndex`](config.md#folderindex) config gives each folder index the folder's name as its `title`. The derived title is for display only and never a link target.

package/docs/rules.md

@@ -193,7 +193,7 @@ A rule has one `gatesDescendants` setting. It applies to whichever part reported
 ### Coverage output
 
 `sctx validate` reports gating as **coverage gates**: which node's violation (schema,
-hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the list of files gated
+hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the ids of the nodes gated
 as a result. This makes the validation "edge" visible — e.g. "this blocked goal means all
 opportunities beneath it were not evaluated" — for both human reading and agent consumption
 (JSON output via `--json`, under `coverageGates`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",