structured-context 0.18.0 → 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, formatSource, 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,9 +24,8 @@ export async function validate(context, options = {}) {
                 errorsByFile[file] = {};
             errorsByFile[file][key] = severity ? { kind, message, severity } : { kind, message };
         };
-        for (const { nodeId, errors: ajvErrors, nodeData } of result.nodeErrors) {
-            const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, nodeData);
-            for (const { message, dedupeKey } of formatted) {
+        for (const { nodeId, issues } of result.nodeErrors) {
+            for (const { message, dedupeKey } of issues) {
                 addError(nodeId, `schema:${dedupeKey}`, 'schema', message);
             }
         }
@@ -119,10 +117,9 @@ export async function validate(context, options = {}) {
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
-        result.nodeErrors.forEach(({ nodeId, source, errors, nodeData }) => {
+        result.nodeErrors.forEach(({ nodeId, source, issues }) => {
             console.log(`\n   ${source ? formatSource(source) : nodeId}:`);
-            const formatted = formatErrors(errors, schema, schemaRefRegistry, nodeData);
-            formatted.forEach(({ message }) => {
+            issues.forEach(({ message }) => {
                 console.log(`      ${message}`);
             });
         });

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/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/validate.d.ts

@@ -14,8 +14,8 @@ export interface ValidationResult {
     nodeErrors: Array<{
         nodeId: NodeId;
         source?: SourceLocation;
-        errors: ErrorObject[];
-        nodeData: Record<string, unknown>;
+        /** Formatted, deduplicated schema problems for the node, one per field problem. */
+        issues: FormattedError[];
     }>;
     refErrors: Array<{
         nodeId: NodeId;

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';
@@ -177,31 +177,31 @@ 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 || [] });
+            result.nodeFailures.push({
+                node,
+                issues: formatErrors(validate.errors || [], schema, schemaRefRegistry, node.schemaData),
+            });
         }
     }
     result.duplicateErrors.push(...findDuplicateIds(nodes));
@@ -276,11 +276,10 @@ export async function validateSpace(context, options = {}) {
     return {
         validCount: result.validCount,
         nodeErrorCount: result.nodeFailures.length,
-        nodeErrors: result.nodeFailures.map(({ node, errors }) => ({
+        nodeErrors: result.nodeFailures.map(({ node, issues }) => ({
             nodeId: node.id,
             ...(node.source !== undefined && { source: node.source }),
-            errors,
-            nodeData: node.schemaData,
+            issues,
         })),
         refErrors: result.refErrors,
         duplicateErrors: result.duplicateErrors,
@@ -312,27 +311,17 @@ 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 };
         }
     }
@@ -409,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.18.0",
+  "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",