structured-context 0.18.0 → 0.20.0

package/dist/api.d.ts

@@ -23,6 +23,7 @@ export type { Config, SpaceConfig } from './config';
 export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { addSpace } from './config/write';
 export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
+export { SctxError, type SctxErrorCode } from './errors';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFormat, RenderHook, RenderMultiFileOutput, RenderOptions, RenderResult, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';

package/dist/api.js

@@ -22,6 +22,7 @@ export { spaceGraphFrom } from './browser';
 export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { addSpace } from './config/write';
 export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
+export { SctxError } from './errors';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';

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-file.d.ts

@@ -1,3 +1,4 @@
+import { type ValidateFileOptions } from '../validate';
 export { validateFile } from '../validate';
 /**
  * CLI command: validate a file and print results to stdout.
@@ -6,7 +7,4 @@ export { validateFile } from '../validate';
  */
 export declare function validateFileCommand(filePath: string, options?: {
     json?: boolean;
-    includeGated?: boolean;
-    semantic?: boolean | string;
-    ruleFilter?: string[];
-}): Promise<number>;
+} & Omit<ValidateFileOptions, 'configDir'>): Promise<number>;

package/dist/commands/validate-file.js

@@ -1,6 +1,4 @@
 import { loadConfig } from '../config';
-import { judgeForRun } from '../judge/factory';
-import { parseRuleFilter } from '../schema/rule-filter';
 import { createSpaceContext } from '../space-context';
 import { fileNotInSpace, resolveFileSpace, validateResolvedFile } from '../validate';
 export { validateFile } from '../validate';
@@ -14,12 +12,7 @@ export async function validateFileCommand(filePath, options = {}) {
     const resolved = resolveFileSpace(filePath, config);
     let result;
     if (resolved) {
-        const judge = judgeForRun(config, resolved.space, options.semantic);
-        result = await validateResolvedFile(filePath, resolved.label, createSpaceContext(resolved.space.name, config), {
-            includeGated: options.includeGated,
-            judge,
-            ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
-        });
+        result = await validateResolvedFile(filePath, resolved.label, createSpaceContext(resolved.space.name, config), options);
     }
     else {
         result = fileNotInSpace(filePath);

package/dist/commands/validate.d.ts

@@ -1,9 +1,6 @@
 import type { SpaceContext } from '../types';
+import { type ValidateSpaceOptions } from '../validate';
 export declare function validate(context: SpaceContext, options?: {
     json?: boolean;
-    depth?: number;
-    includeGated?: boolean;
-    semantic?: boolean | string;
-    ruleFilter?: string[];
-}): Promise<number>;
+} & ValidateSpaceOptions): Promise<number>;
 export declare function watchValidate(context: SpaceContext): Promise<never>;

package/dist/commands/validate.js

@@ -1,19 +1,11 @@
 import { dirname } from 'node:path';
 import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
-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,
-        judge: judgeForRun(context.config, context.space, options.semantic),
-        ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
-    });
+    const result = await validateSpace(context, options);
     const ruleCounts = { error: 0, warning: 0, info: 0 };
     for (const v of result.ruleViolations)
         ruleCounts[v.severity]++;
@@ -25,9 +17,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 +110,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/errors.d.ts

@@ -2,7 +2,7 @@
  * Stable codes for configuration and environment problems. Hooks and agent skills map a code to a
  * fix, so the message wording can change without breaking them.
  */
-export type SctxErrorCode = 'E_CONFIG_NOT_FOUND' | 'E_CONFIG_INVALID' | 'E_INCLUDE_NOT_FOUND' | 'E_NO_SPACES' | 'E_SPACE_PATH_MISSING' | 'E_SCHEMA_MISSING' | 'E_SCHEMA_NOT_FOUND' | 'E_SCHEMA_INVALID' | 'E_SPACE_EXISTS' | 'E_TARGET_REQUIRED' | 'E_CONFIG_NEEDS_MANUAL_EDIT';
+export type SctxErrorCode = 'E_CONFIG_NOT_FOUND' | 'E_CONFIG_INVALID' | 'E_INCLUDE_NOT_FOUND' | 'E_NO_SPACES' | 'E_SPACE_PATH_MISSING' | 'E_SCHEMA_MISSING' | 'E_SCHEMA_NOT_FOUND' | 'E_SCHEMA_INVALID' | 'E_SPACE_EXISTS' | 'E_TARGET_REQUIRED' | 'E_CONFIG_NEEDS_MANUAL_EDIT' | 'E_MODEL_PROVIDER_INVALID';
 export declare class SctxError extends Error {
     readonly code: SctxErrorCode;
     constructor(code: SctxErrorCode, message: string);

package/dist/index.js

@@ -17,7 +17,6 @@ import { validateFileCommand } from './commands/validate-file';
 import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
 import { SctxError } from './errors';
-import { JudgeConfigError } from './judge/factory';
 import { createSpaceContext, SpaceNotFoundError } from './space-context';
 // Once node:process is loaded (vfile, via unified, loads it), Bun's console.log drops piped output
 // past 64KB when the reader is slow. process.stdout.write delivers all of it before exit.
@@ -36,18 +35,6 @@ export function buildSpaceContext(spaceName) {
         throw err;
     }
 }
-/** Run a validate command, reporting a misconfigured model provider as a plain error rather than a stack trace. */
-async function reportJudgeConfigErrors(run) {
-    try {
-        return await run();
-    }
-    catch (err) {
-        if (!(err instanceof JudgeConfigError))
-            throw err;
-        console.error(`Error: ${err.message}`);
-        return 1;
-    }
-}
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 const program = new Command();
@@ -68,12 +55,12 @@ program
     .option('--rule-filter <dimension=values>', 'Evaluate only matching rules; dimensions: category, severity, type, id (repeatable, e.g. severity=error)', (v, prev = []) => [...prev, v])
     .option('--semantic [provider]', 'Evaluate semantic rules, with the configured model provider or the one named')
     .action(async (filePath, options) => {
-    process.exitCode = await reportJudgeConfigErrors(() => validateFileCommand(filePath, {
+    process.exitCode = await validateFileCommand(filePath, {
         json: options.json,
         includeGated: options.includeGated,
         semantic: options.semantic,
         ruleFilter: options.ruleFilter,
-    }));
+    });
 });
 program
     .command('validate')
@@ -92,13 +79,13 @@ program
     }
     else {
         // exitCode rather than process.exit(): exiting straight away can cut off large piped output
-        process.exitCode = await reportJudgeConfigErrors(() => validate(context, {
+        process.exitCode = await validate(context, {
             json: options.json,
             depth: options.depth,
             includeGated: options.includeGated,
             semantic: options.semantic,
             ruleFilter: options.ruleFilter,
-        }));
+        });
     }
 });
 program

package/dist/judge/factory.d.ts

@@ -7,8 +7,6 @@ type Env = Record<string, string | undefined>;
  */
 export declare const BUNDLED_PROVIDERS: Record<string, ModelProviderConfig>;
 /** Semantic evaluation is misconfigured (no provider, unknown provider, missing key). Reported as a plain CLI error. */
-export declare class JudgeConfigError extends Error {
-}
 /**
  * Hydrate a provider definition into concrete values, in one place. Per field: the explicit value
  * wins, then the named environment variable if it is set (a set-but-empty variable is an error, not
@@ -29,7 +27,7 @@ export declare function judgeForRun(config: Parameters<typeof createJudge>[0], s
 /**
  * The provider for a run: the one named by `name` (the `--semantic <provider>` override), else the space's
  * `semantic.provider`, else the top-level one. The name resolves against `modelProviders` first, then
- * the bundled providers. Throws {@link JudgeConfigError} when it cannot be built.
+ * the bundled providers. Throws {@link SctxError} `E_MODEL_PROVIDER_INVALID` when it cannot be built.
  */
 export declare function createJudge(config: {
     modelProviders?: Record<string, ModelProviderConfig>;

package/dist/judge/factory.js

@@ -1,3 +1,4 @@
+import { SctxError } from '../errors';
 import { AnthropicJudgeProvider, RECOMMENDED_ANTHROPIC_MODEL } from './provider/anthropic';
 import { FakeJudgeProvider } from './provider/fake';
 import { JEV_LATEST, JevJudgeProvider } from './provider/jev';
@@ -66,8 +67,6 @@ const DEFAULT_KEY_ENV = {
     'typesafe-systemone': 'TYPESAFE_API_KEY',
 };
 /** Semantic evaluation is misconfigured (no provider, unknown provider, missing key). Reported as a plain CLI error. */
-export class JudgeConfigError extends Error {
-}
 /**
  * Hydrate a provider definition into concrete values, in one place. Per field: the explicit value
  * wins, then the named environment variable if it is set (a set-but-empty variable is an error, not
@@ -75,7 +74,7 @@ export class JudgeConfigError extends Error {
  */
 export function hydrateProvider(name, def, env = process.env) {
     if (!MODEL_PROVIDER_APIS.includes(def.api)) {
-        throw new JudgeConfigError(`Model provider "${name}" has unknown api "${def.api}". Use one of: ${MODEL_PROVIDER_APIS.join(', ')}.`);
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${name}" has unknown api "${def.api}". Use one of: ${MODEL_PROVIDER_APIS.join(', ')}.`);
     }
     const fromEnv = (value, envName) => {
         if (value !== undefined)
@@ -84,7 +83,7 @@ export function hydrateProvider(name, def, env = process.env) {
             return undefined;
         const envValue = env[envName];
         if (envValue !== undefined && envValue.trim() === '') {
-            throw new JudgeConfigError(`Model provider "${name}" has ${envName} set but empty; set a value or unset the variable.`);
+            throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${name}" has ${envName} set but empty; set a value or unset the variable.`);
         }
         return envValue;
     };
@@ -104,7 +103,7 @@ export function createModelProvider(name, def, env = process.env) {
     // OpenAI-compatible endpoints (Ollama, vLLM, ...) may need no key; the others must resolve one.
     // A key never borrows another provider's variable: only the named apiKeyEnv (or literal apiKey) counts.
     if (!h.apiKey && h.api !== 'openai-completions' && h.api !== 'fake') {
-        throw new JudgeConfigError(`Model provider "${name}" (${h.api}) has no API key. Set ${h.keyEnv} in the environment, or "apiKey" / "apiKeyEnv" on the provider.`);
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${name}" (${h.api}) has no API key. Set ${h.keyEnv} in the environment, or "apiKey" / "apiKeyEnv" on the provider.`);
     }
     switch (h.api) {
         case 'fake':
@@ -132,17 +131,17 @@ export function judgeForRun(config, space, semantic) {
 /**
  * The provider for a run: the one named by `name` (the `--semantic <provider>` override), else the space's
  * `semantic.provider`, else the top-level one. The name resolves against `modelProviders` first, then
- * the bundled providers. Throws {@link JudgeConfigError} when it cannot be built.
+ * the bundled providers. Throws {@link SctxError} `E_MODEL_PROVIDER_INVALID` when it cannot be built.
  */
 export function createJudge(config, space = {}, name, env = process.env) {
     const chosen = name ?? space.semantic?.provider ?? config.semantic?.provider;
     if (!chosen) {
-        throw new JudgeConfigError('--semantic needs a model provider. Set "semantic.provider" in config.json, or pass --semantic <provider>.');
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', '--semantic needs a model provider. Set "semantic.provider" in config.json, or pass --semantic <provider>.');
     }
     const def = config.modelProviders?.[chosen] ?? BUNDLED_PROVIDERS[chosen];
     if (!def) {
         const known = [...Object.keys(BUNDLED_PROVIDERS), ...Object.keys(config.modelProviders ?? {})];
-        throw new JudgeConfigError(`Model provider "${chosen}" is not configured.${known.length ? ` Known providers: ${known.join(', ')}.` : ''}`);
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${chosen}" is not configured.${known.length ? ` Known providers: ${known.join(', ')}.` : ''}`);
     }
     return createModelProvider(chosen, def, env);
 }

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;
@@ -62,26 +62,64 @@ export interface ValidationResult {
  * Groups related errors and extracts helpful context like allowed values.
  */
 export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMetadata, schemaRefRegistry: Parameters<typeof extractEntityInfo>[1], nodeData: Record<string, unknown>): FormattedError[];
-export interface ValidateSpaceOptions {
-    readResult?: ReadSpaceResult;
-    /** Limit validation to hierarchy nodes within N breadth-first levels from the top. */
-    depth?: number;
+interface CommonValidateOptions {
     /** Evaluate rules on gated nodes anyway (gates are still reported). */
     includeGated?: boolean;
-    /** Evaluate only rules matching this filter (see `parseRuleFilter`). */
+    /** Evaluate only rules matching these `dimension=values` filters (category, severity, type, id). */
+    ruleFilter?: string[];
+    /**
+     * Evaluate `semantic` rules with the model provider named here, or with the configured one for `true`.
+     * Without it, a rule runs only its `expression`, and a semantic-only rule is skipped.
+     */
+    semantic?: boolean | string;
+}
+/** What a run evaluates with: the public options after the filter is parsed and the judge is built. */
+export interface RunOptions {
+    includeGated?: boolean;
     ruleFilter?: RuleFilter;
-    /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
     judge?: SemanticJudgeProvider;
+    /** Limit judging to one file (and the ancestors that can gate it). */
+    judgeTarget?: string;
+}
+export interface ValidateSpaceOptions extends CommonValidateOptions {
+    readResult?: ReadSpaceResult;
+    /** Limit validation to hierarchy nodes within N breadth-first levels from the top. */
+    depth?: number;
 }
 /** `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;
+/** A node that failed type or schema validation. */
+interface NodeValidationFailure {
+    node: SpaceNode;
+    issues: FormattedError[];
+}
+/** The outcome of validating a set of nodes, before either view shapes it. */
+export interface SpaceValidationResult {
+    validCount: number;
+    nodeFailures: NodeValidationFailure[];
+    refErrors: ValidationResult['refErrors'];
+    duplicateErrors: ValidationResult['duplicateErrors'];
+    ruleViolations: RuleViolation[];
+    hierarchyViolations: GraphViolation[];
+    orphans: SpaceNode[];
+    unresolvedContentLinks: ValidationResult['unresolvedContentLinks'];
+    coverageGates: CoverageGate[];
+    contextTrimmed: ValidationResult['contextTrimmed'];
+}
 /**
  * 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'];
+/**
+ * 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`
+ * and `validateFile` are views over it, so a file's results match its entry in a full run.
+ * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
+ */
+export declare function validateNodes(context: SpaceContext, nodes: SpaceNode[], unresolvedRefs: ReadSpaceResult['unresolvedRefs'], options?: RunOptions): Promise<SpaceValidationResult>;
 /**
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.
@@ -92,14 +130,8 @@ export declare function resolveFileSpace(filePath: string, config: Config): {
     space: SpaceConfig;
     label: string;
 } | null;
-export interface ValidateFileOptions {
+export interface ValidateFileOptions extends CommonValidateOptions {
     configDir?: string;
-    /** Evaluate rules on gated nodes anyway (gates are still reported). */
-    includeGated?: boolean;
-    /** Evaluate only rules matching this filter (see `parseRuleFilter`). */
-    ruleFilter?: RuleFilter;
-    /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
-    judge?: SemanticJudgeProvider;
 }
 /** The result for a file that belongs to no configured space. */
 export declare function fileNotInSpace(filePath: string): FileNotInSpaceResult;
@@ -108,6 +140,8 @@ export declare function fileNotInSpace(filePath: string): FileNotInSpaceResult;
  * correctness), judging only the file, then selects the file's issues from the result.
  */
 export declare function validateResolvedFile(filePath: string, label: string, context: SpaceContext, options?: Omit<ValidateFileOptions, 'configDir'>): Promise<FileValidationResult>;
+/** `validateResolvedFile` with the options already resolved, so a caller can supply its own judge. */
+export declare function validateResolvedFileWith(filePath: string, label: string, context: SpaceContext, runOptions: RunOptions): Promise<FileValidationResult>;
 /**
  * Validate a single file within its space.
  *
@@ -118,3 +152,4 @@ export declare function validateResolvedFile(filePath: string, label: string, co
  * If the file is not in any configured space, returns a result with `inSpace: false`.
  */
 export declare function validateFile(filePath: string, config: Config, options?: ValidateFileOptions): Promise<ValidateFileOutput>;
+export {};

package/dist/validate.js

@@ -1,8 +1,9 @@
 import { isAbsolute, relative, resolve } from 'node:path';
+import { judgeForRun } from './judge/factory';
 import { readSpace } from './read/read-space';
 import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating';
-import { filterRules } from './schema/rule-filter';
-import { extractEntityInfo } from './schema/schema';
+import { filterRules, parseRuleFilter } from './schema/rule-filter';
+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 +95,14 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
     }
     return formatted;
 }
+/** Throws `SctxError` `E_MODEL_PROVIDER_INVALID` when `semantic` names a provider that cannot be built. */
+function runOptionsFrom(context, options) {
+    return {
+        includeGated: options.includeGated,
+        ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
+        judge: judgeForRun(context.config, context.space, options.semantic),
+    };
+}
 /** `file`, `file:line` or `file:line:column`, for messages. */
 export function formatSource({ file, line, column }) {
     return line === undefined ? file : `${file}:${line}${column === undefined ? '' : `:${column}`}`;
@@ -159,7 +168,7 @@ export function findDuplicateIds(nodes) {
  * and `validateFile` are views over it, so a file's results match its entry in a full run.
  * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
  */
-async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
+export async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
     // Pre-extract valid types for early type validation
@@ -177,31 +186,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));
@@ -248,6 +257,7 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
  */
 export async function validateSpace(context, options = {}) {
     const metadata = context.schema.metadata;
+    const runOptions = runOptionsFrom(context, options);
     const readResult = options.readResult ?? (await readSpace(context));
     let nodes = readResult.nodes;
     // Depth limiting: evaluate only hierarchy nodes within N breadth-first levels from the
@@ -268,19 +278,14 @@ export async function validateSpace(context, options = {}) {
         }
         nodes = included;
     }
-    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, {
-        includeGated: options.includeGated,
-        ruleFilter: options.ruleFilter,
-        judge: options.judge,
-    });
+    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, runOptions);
     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 +317,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 };
         }
     }
@@ -401,15 +396,17 @@ export function fileNotInSpace(filePath) {
  * Validate a file in an already-resolved space. Checks the whole space (required for graph
  * correctness), judging only the file, then selects the file's issues from the result.
  */
-export async function validateResolvedFile(filePath, label, context, options = {}) {
+export function validateResolvedFile(filePath, label, context, options = {}) {
+    return validateResolvedFileWith(filePath, label, context, runOptionsFrom(context, options));
+}
+/** `validateResolvedFile` with the options already resolved, so a caller can supply its own judge. */
+export async function validateResolvedFileWith(filePath, label, context, runOptions) {
     const readResult = await readSpace(context);
     const result = await validateNodes(context, readResult.nodes, readResult.unresolvedRefs, {
-        includeGated: options.includeGated,
-        ruleFilter: options.ruleFilter,
-        judge: options.judge,
+        ...runOptions,
         judgeTarget: label,
     });
-    const { errors, warnings } = issuesForFile(result, label, context, options.includeGated);
+    const { errors, warnings } = issuesForFile(result, label, runOptions.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.20.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",

package/dist/judge/index.d.ts

@@ -1,13 +0,0 @@
-export { createJudge, createModelProvider, JudgeConfigError } from './factory';
-export { buildJudgeSystemPrompt, buildJudgeUserPrompt, parseJudgeResponse } from './prompt';
-export type { AnthropicJudgeProviderOptions } from './provider/anthropic';
-export { AnthropicJudgeProvider } from './provider/anthropic';
-export type { FakeAnswer, FakeJudgeHandler } from './provider/fake';
-export { FakeJudgeProvider } from './provider/fake';
-export type { JevJudgeProviderOptions } from './provider/jev';
-export { JevJudgeProvider } from './provider/jev';
-export type { OpenAIJudgeProviderOptions } from './provider/openai';
-export { OpenAIJudgeProvider } from './provider/openai';
-export { PerRuleJudgeProvider } from './provider/per-rule';
-export type { JudgeConfig, ModelProviderConfig, SemanticJudgeInput, SemanticJudgeProvider, SemanticJudgeResult, SemanticJudgeVerdict, SemanticRuleSpec, } from './types';
-export { DEFAULT_VERDICTS, isJudgeError, semanticRuleSpec } from './verdicts';

package/dist/judge/index.js

@@ -1,8 +0,0 @@
-export { createJudge, createModelProvider, JudgeConfigError } from './factory';
-export { buildJudgeSystemPrompt, buildJudgeUserPrompt, parseJudgeResponse } from './prompt';
-export { AnthropicJudgeProvider } from './provider/anthropic';
-export { FakeJudgeProvider } from './provider/fake';
-export { JevJudgeProvider } from './provider/jev';
-export { OpenAIJudgeProvider } from './provider/openai';
-export { PerRuleJudgeProvider } from './provider/per-rule';
-export { DEFAULT_VERDICTS, isJudgeError, semanticRuleSpec } from './verdicts';