structured-context 0.11.0 → 0.13.0

package/dist/index.js

@@ -1,21 +1,28 @@
 #!/usr/bin/env bun
 import { createRequire } from 'node:module';
+import { format } from 'node:util';
 import { Command } from 'commander';
-import { diagram } from './commands/diagram';
-import { docs } from './commands/docs';
-import { dump } from './commands/dump';
-import { miroSyncCommand } from './commands/miro-sync';
-import { listPlugins } from './commands/plugins';
-import { render, renderList } from './commands/render';
-import { listSchemas, showSchema } from './commands/schemas';
-import { show } from './commands/show';
-import { listSpaces } from './commands/spaces';
-import { templateSync } from './commands/template-sync';
-import { validate, watchValidate } from './commands/validate';
-import { validateFileCommand } from './commands/validate-file';
-import { loadConfig, setConfigPath } from './config';
-import { CLI_NAME } from './constants';
-import { createSpaceContext, SpaceNotFoundError } from './space-context';
+import { diagram } from './commands/diagram.js';
+import { docs } from './commands/docs.js';
+import { dump } from './commands/dump.js';
+import { miroSyncCommand } from './commands/miro-sync.js';
+import { listPlugins } from './commands/plugins.js';
+import { render, renderList } from './commands/render.js';
+import { listSchemas, showSchema } from './commands/schemas.js';
+import { show } from './commands/show.js';
+import { listSpaces } from './commands/spaces.js';
+import { templateSync } from './commands/template-sync.js';
+import { validate, watchValidate } from './commands/validate.js';
+import { validateFileCommand } from './commands/validate-file.js';
+import { loadConfig, setConfigPath } from './config.js';
+import { CLI_NAME } from './constants.js';
+import { JudgeConfigError } from './judge/factory.js';
+import { createSpaceContext, SpaceNotFoundError } from './space-context.js';
+// 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.
+console.log = (...args) => {
+    process.stdout.write(`${format(...args)}\n`);
+};
 export function buildSpaceContext(spaceName) {
     try {
         return createSpaceContext(spaceName, loadConfig());
@@ -28,6 +35,18 @@ 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();
@@ -44,9 +63,16 @@ program
     .description('Validate a single file within its space')
     .argument('<path>', 'Path to the file to validate')
     .option('--json', 'Output results as JSON (machine-readable, for hooks)')
+    .option('--include-gated', 'Evaluate rules even when the file is gated by an upstream schema/hierarchy/rule failure (still reported as gated)')
+    .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) => {
-    const exitCode = await validateFileCommand(filePath, { json: options.json });
-    process.exit(exitCode);
+    process.exitCode = await reportJudgeConfigErrors(() => validateFileCommand(filePath, {
+        json: options.json,
+        includeGated: options.includeGated,
+        semantic: options.semantic,
+        ruleFilter: options.ruleFilter,
+    }));
 });
 program
     .command('validate')
@@ -54,14 +80,24 @@ program
     .argument('<space-name>', 'Space name')
     .option('-w, --watch', 'Watch for changes and re-run validation')
     .option('--json', 'Output results as JSON')
+    .option('--depth <n>', 'Evaluate only hierarchy nodes within N breadth-first levels from the top (e.g. 1 = root level only)', (v) => parseInt(v, 10))
+    .option('--include-gated', 'Evaluate rules even on nodes gated by an upstream schema/hierarchy/rule failure (still reported as gated)')
+    .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 (spaceName, options) => {
     const context = buildSpaceContext(spaceName);
     if (options.watch) {
         await watchValidate(context);
     }
     else {
-        const exitCode = await validate(context, { json: options.json });
-        process.exit(exitCode);
+        // exitCode rather than process.exit(): exiting straight away can cut off large piped output
+        process.exitCode = await reportJudgeConfigErrors(() => validate(context, {
+            json: options.json,
+            depth: options.depth,
+            includeGated: options.includeGated,
+            semantic: options.semantic,
+            ruleFilter: options.ruleFilter,
+        }));
     }
 });
 program
@@ -69,19 +105,23 @@ program
     .description('Generate mermaid diagram from space')
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
     .option('-o, --output <path>', 'Output file path (default: stdout)')
-    .action((spaceName, options) => diagram(buildSpaceContext(spaceName), options));
+    .action(async (spaceName, options) => diagram(buildSpaceContext(spaceName), options));
 program
     .command('show')
     .description('Print space graph as a bullet list')
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
-    .action((spaceName, options) => show(buildSpaceContext(spaceName), options));
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
+    .action(async (spaceName, options) => show(buildSpaceContext(spaceName), options));
 program
     .command('dump')
     .description('Dump parsed space nodes as JSON')
     .argument('<space-name>', 'Space name')
-    .action((spaceName) => dump(buildSpaceContext(spaceName)));
+    .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('--hierarchy <name>', 'Hierarchy used to evaluate --filter (default: the main hierarchy)')
+    .action(async (spaceName, options) => dump(buildSpaceContext(spaceName), options));
 program
     .command('miro-sync')
     .description('Sync space to a Miro board')
@@ -89,16 +129,16 @@ program
     .option('--new-frame <title>', 'Create a new frame on the board and sync into it')
     .option('--dry-run', 'Show what would change without touching Miro')
     .option('-v, --verbose', 'Detailed output')
-    .action((spaceName, options) => miroSyncCommand(buildSpaceContext(spaceName), options));
+    .action(async (spaceName, options) => miroSyncCommand(buildSpaceContext(spaceName), options));
 program
     .command('template-sync')
     .description('Sync schema examples to templates')
     .argument('<space-name>', 'Space name')
     .option('--create-missing', 'Create missing template files for schema types')
     .option('--dry-run', 'Preview changes without writing files')
-    .action((spaceName, options) => {
+    .action(async (spaceName, options) => {
     const context = buildSpaceContext(spaceName);
-    templateSync(context, options);
+    await templateSync(context, options);
 });
 program
     .command('plugins')
@@ -108,13 +148,24 @@ const spacesCmd = new Command('spaces').description('List configured spaces');
 spacesCmd
     .command('list', { isDefault: true })
     .description('List all configured spaces and their paths')
-    .action(listSpaces);
+    .option('--json', 'Output as JSON: config files, and each space with its path and schema')
+    .action((options) => listSpaces(options));
 program.addCommand(spacesCmd);
+const providersCmd = new Command('providers').description('List model providers (bundled and configured) with their effective config');
+providersCmd
+    .command('list', { isDefault: true })
+    .description('List bundled and configured model providers; keys are never shown')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    const { listProviders } = await import('./commands/providers.js');
+    listProviders(options);
+});
+program.addCommand(providersCmd);
 const schemasCmd = new Command('schemas').alias('schema').description('List and inspect schemas');
 schemasCmd
     .command('list', { isDefault: true })
     .description('List available schemas')
-    .action(() => listSchemas());
+    .action(async () => await listSchemas());
 schemasCmd
     .command('show')
     .description('Show schema structure (or raw JSON with --raw, or Mermaid ERD with --mermaid-erd)')
@@ -122,7 +173,7 @@ schemasCmd
     .option('--space <name>', 'Resolve schema from space config')
     .option('--raw', 'Output raw JSON file content')
     .option('--mermaid-erd', 'Output Mermaid Entity Relationship Diagram')
-    .action((file, options) => showSchema(file, {
+    .action(async (file, options) => await showSchema(file, {
     space: options.space,
     raw: options.raw ?? false,
     mermaidErd: options.mermaidErd ?? false,
@@ -130,7 +181,7 @@ schemasCmd
 program.addCommand(schemasCmd);
 program
     .command('docs [topic]')
-    .description('Show documentation (no arg: README; topics: concepts, config, schema, rules)')
+    .description('Show documentation (no arg: README; topics: concepts, config, schema, rules, semantic-rules)')
     .action((topic) => docs(topic));
 const renderCmd = new Command('render').description('Render a space in a given format');
 renderCmd
@@ -141,11 +192,25 @@ renderCmd
     const context = spaceName ? buildSpaceContext(spaceName) : undefined;
     await renderList(context);
 });
+function parseDataOptions(val, prev = {}) {
+    const eqIdx = val.indexOf('=');
+    if (eqIdx >= 0) {
+        prev[val.slice(0, eqIdx).trim()] = val.slice(eqIdx + 1).trim();
+    }
+    else {
+        prev[val.trim()] = 'true';
+    }
+    return prev;
+}
 renderCmd
     .argument('<space-name>', 'Space name')
-    .argument('<format>', 'Render format (e.g. markdown.bullets)')
+    .argument('<format>', 'Render format (e.g. markdown.bullets, markdown.directory)')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
-    .option('-o, --output <path>', 'Output file path (default: stdout)')
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
+    .option('-o, --output <path>', 'Output file or directory path (default: stdout)')
+    .option('--out <path>', 'Output directory or file path')
+    .option('-f, --force', 'Overwrite existing files when writing to disk')
+    .option('-d, --data <key=value...>', 'Format-specific key=value options', parseDataOptions)
     .action(async (spaceName, format, options) => {
     await render(buildSpaceContext(spaceName), format, options);
 });

package/dist/judge/context.d.ts

@@ -0,0 +1,20 @@
+import { SEMANTIC_SCOPES } from '../schema/metadata-contract';
+import type { SpaceGraph } from '../space-graph';
+import type { Rule, SpaceNode } from '../types';
+import type { RelatedNode, SemanticJudgeInput } from '../types.js';
+export type SemanticScope = Exclude<(typeof SEMANTIC_SCOPES)[number], 'branch'>;
+export type ContentMode = 'none' | 'nodeOnly' | 'fullScope';
+/** What a rule asks to send besides the evaluated node's data. */
+export interface RuleContext {
+    scope: SemanticScope[];
+    content: ContentMode;
+}
+/** The related nodes and bodies a semantic rule asks for. `includeContent: true` means `fullScope`. */
+export declare function ruleContext(rule: Rule): RuleContext;
+/**
+ * The nodes a scope adds for a node, along main-hierarchy edges only. Selection reads the graph's structure and
+ * nothing else: not verdicts, not gating. Each node appears once, with every relation it has, nearest first.
+ */
+export declare function relatedNodes(graph: SpaceGraph, node: SpaceNode, context: RuleContext): RelatedNode[];
+/** The judge input context for rules that share `context`: the node view and its related nodes. */
+export declare function judgeContext(graph: SpaceGraph, node: SpaceNode, context: RuleContext): Pick<SemanticJudgeInput, 'node' | 'related'>;

package/dist/judge/context.js

@@ -0,0 +1,105 @@
+import { SEMANTIC_SCOPES } from '../schema/metadata-contract';
+import { ruleSemantic } from '../schema/rule-severity';
+/** The related nodes and bodies a semantic rule asks for. `includeContent: true` means `fullScope`. */
+export function ruleContext(rule) {
+    const semantic = ruleSemantic(rule);
+    const include = semantic?.includeContent;
+    const asked = new Set(semantic?.scope ?? []);
+    if (asked.has('branch'))
+        asked.add('ancestors').add('descendants');
+    // A wider scope implies the narrower one, so equal node sets give equal inputs and direct relations keep their label.
+    if (asked.has('ancestors'))
+        asked.add('parent');
+    if (asked.has('descendants'))
+        asked.add('children');
+    return {
+        scope: SEMANTIC_SCOPES.filter((s) => s !== 'branch' && asked.has(s)),
+        content: include === undefined ? 'none' : include === true ? 'fullScope' : include,
+    };
+}
+/** All schema data, without the body unless asked for. */
+function dataWithBody(node, withBody) {
+    if (withBody)
+        return node.schemaData;
+    const { content: _content, ...data } = node.schemaData;
+    return data;
+}
+/** The evaluated node as a judge sees it. */
+function judgeNodeView(node, withBody) {
+    return {
+        label: node.label,
+        title: node.title,
+        type: node.type,
+        resolvedType: node.resolvedType,
+        schemaData: dataWithBody(node, withBody),
+        resolvedParents: node.resolvedParents,
+    };
+}
+function relatedView(node, relation, withBody) {
+    const { title: _title, type: _type, ...data } = dataWithBody(node, withBody);
+    return { relations: [relation], title: node.title, type: node.resolvedType, data };
+}
+/**
+ * The nodes a scope adds for a node, along main-hierarchy edges only. Selection reads the graph's structure and
+ * nothing else: not verdicts, not gating. Each node appears once, with every relation it has, nearest first.
+ */
+export function relatedNodes(graph, node, context) {
+    const withBody = context.content === 'fullScope';
+    const hierarchyName = graph.hierarchy?.name;
+    const parentsOf = (n) => graph.hierarchy === undefined
+        ? []
+        : n.resolvedParents
+            .filter((p) => p.source === 'hierarchy' && p.hierarchy === hierarchyName)
+            .map((p) => graph.nodes.get(p.title))
+            .filter((p) => p !== undefined);
+    const childrenOf = (n) => graph.hierarchyChildren.get(n.title) ?? [];
+    const found = new Map();
+    const add = (other, relation) => {
+        if (other.title === node.title)
+            return;
+        const existing = found.get(other.title);
+        if (!existing)
+            found.set(other.title, relatedView(other, relation, withBody));
+        else if (!existing.relations.includes(relation))
+            existing.relations.push(relation);
+    };
+    const reach = (next, relation) => {
+        const seen = new Set([node.title]);
+        let level = next(node);
+        while (level.length > 0) {
+            const following = [];
+            for (const n of level) {
+                if (seen.has(n.title))
+                    continue;
+                seen.add(n.title);
+                add(n, relation);
+                following.push(...next(n));
+            }
+            level = following;
+        }
+    };
+    const scope = new Set(context.scope);
+    if (scope.has('parent'))
+        for (const p of parentsOf(node))
+            add(p, 'parent');
+    if (scope.has('siblings'))
+        for (const p of parentsOf(node))
+            for (const s of childrenOf(p))
+                add(s, 'sibling');
+    if (scope.has('children'))
+        for (const c of childrenOf(node))
+            add(c, 'child');
+    if (scope.has('ancestors'))
+        reach(parentsOf, 'ancestor');
+    if (scope.has('descendants'))
+        reach(childrenOf, 'descendant');
+    return [...found.values()];
+}
+/** The judge input context for rules that share `context`: the node view and its related nodes. */
+export function judgeContext(graph, node, context) {
+    const related = relatedNodes(graph, node, context);
+    return {
+        node: judgeNodeView(node, context.content !== 'none'),
+        ...(related.length > 0 && { related }),
+    };
+}

package/dist/judge/factory.d.ts

@@ -0,0 +1,44 @@
+import { type HydratedProvider, type ModelProviderConfig, type SemanticJudgeProvider } from '../types.js';
+type Env = Record<string, string | undefined>;
+/**
+ * Bundled providers: usable as a judge by name, without a `modelProviders` entry. A user entry of the
+ * same name replaces one wholesale; fields it leaves out take the type defaults in the constructors.
+ * Every value here is explicit: no bundle reads the environment.
+ */
+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
+ * a silent fall-through), then the definition's own default. The key is special: it must resolve.
+ */
+export declare function hydrateProvider(name: string, def: ModelProviderConfig, env?: Env): HydratedProvider;
+/**
+ * Instantiate one provider from a definition. The API is always explicit and is never inferred from
+ * API keys in the environment, so a key set for another tool is never spent on judging. Constructors
+ * apply their own API defaults for fields left undefined after hydration.
+ */
+export declare function createModelProvider(name: string, def: ModelProviderConfig, env?: Env): SemanticJudgeProvider;
+/**
+ * The provider a CLI run asks for: none without `--semantic`; the named one with `--semantic <provider>`;
+ * else the configured one.
+ */
+export declare function judgeForRun(config: Parameters<typeof createJudge>[0], space: Parameters<typeof createJudge>[1], semantic?: boolean | string): SemanticJudgeProvider | undefined;
+/**
+ * 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.
+ */
+export declare function createJudge(config: {
+    modelProviders?: Record<string, ModelProviderConfig>;
+    semantic?: {
+        provider?: string;
+    };
+}, space?: {
+    semantic?: {
+        provider?: string;
+    };
+}, name?: string, env?: Env): SemanticJudgeProvider;
+export {};

package/dist/judge/factory.js

@@ -0,0 +1,148 @@
+import { AnthropicJudgeProvider, RECOMMENDED_ANTHROPIC_MODEL } from './provider/anthropic';
+import { FakeJudgeProvider } from './provider/fake';
+import { JEV_LATEST, JevJudgeProvider } from './provider/jev';
+import { OpenAIJudgeProvider, RECOMMENDED_OPENAI_MODEL } from './provider/openai';
+import { OpenAIDecisionsJudgeProvider, RECOMMENDED_OPENAI_DECISIONS_MODEL } from './provider/openai-decisions';
+import { MODEL_PROVIDER_APIS, } from '../types.js';
+const OPENROUTER_COMPLETIONS_ENDPOINT = 'https://openrouter.ai/api/v1';
+const RECOMMENDED_OPENROUTER_OPENAI_DECISIONS_MODEL = `openai/${RECOMMENDED_OPENAI_DECISIONS_MODEL}-decisions`;
+const RECOMMENDED_OPENROUTER_OPENAI_MODEL = `openai/${RECOMMENDED_OPENAI_MODEL}`;
+const ANTHROPIC_KEY_ENV = 'ANTHROPIC_API_KEY';
+const OPENAI_KEY_ENV = 'OPENAI_API_KEY';
+const OPENROUTER_KEY_ENV = 'OPENROUTER_API_KEY';
+const ANTHROPIC_BASE = {
+    api: 'anthropic-messages',
+    model: RECOMMENDED_ANTHROPIC_MODEL,
+    apiKeyEnv: ANTHROPIC_KEY_ENV,
+};
+const OPENAI_BASE = {
+    api: 'openai-completions',
+    model: RECOMMENDED_OPENAI_MODEL,
+    apiKeyEnv: OPENAI_KEY_ENV,
+};
+/**
+ * Bundled providers: usable as a judge by name, without a `modelProviders` entry. A user entry of the
+ * same name replaces one wholesale; fields it leaves out take the type defaults in the constructors.
+ * Every value here is explicit: no bundle reads the environment.
+ */
+export const BUNDLED_PROVIDERS = {
+    'typesafe-jev': { api: 'typesafe-systemone', model: JEV_LATEST, apiKeyEnv: 'TYPESAFE_API_KEY' },
+    'openrouter-jev': { api: 'openrouter-decisions', model: `~typesafe/${JEV_LATEST}`, apiKeyEnv: OPENROUTER_KEY_ENV },
+    'openrouter-openai-decisions': {
+        api: 'openrouter-decisions',
+        model: RECOMMENDED_OPENROUTER_OPENAI_DECISIONS_MODEL,
+        apiKeyEnv: OPENROUTER_KEY_ENV,
+    },
+    'openai-decisions': {
+        api: 'openai-decisions',
+        model: RECOMMENDED_OPENAI_DECISIONS_MODEL,
+        apiKeyEnv: OPENAI_KEY_ENV,
+    },
+    anthropic: ANTHROPIC_BASE,
+    'anthropic-haiku-5-5': { api: 'anthropic-messages', model: 'claude-haiku-5-5', apiKeyEnv: ANTHROPIC_KEY_ENV },
+    'anthropic-env': {
+        ...ANTHROPIC_BASE,
+        modelEnv: 'ANTHROPIC_MODEL',
+    },
+    openai: OPENAI_BASE,
+    'openai-env': {
+        ...OPENAI_BASE,
+        modelEnv: 'OPENAI_MODEL',
+        endpointEnv: 'OPENAI_BASE_URL',
+    },
+    'openrouter-openai': {
+        api: 'openai-completions',
+        endpoint: OPENROUTER_COMPLETIONS_ENDPOINT,
+        model: RECOMMENDED_OPENROUTER_OPENAI_MODEL,
+        apiKeyEnv: OPENROUTER_KEY_ENV,
+    },
+};
+/** Each API reads its key from this variable unless `apiKeyEnv` names another one. Model and endpoint never read env vars. */
+const DEFAULT_KEY_ENV = {
+    'anthropic-messages': 'ANTHROPIC_API_KEY',
+    'openai-completions': 'OPENAI_API_KEY',
+    'openai-decisions': 'OPENAI_API_KEY',
+    'openrouter-decisions': 'OPENROUTER_API_KEY',
+    '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
+ * a silent fall-through), then the definition's own default. The key is special: it must resolve.
+ */
+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(', ')}.`);
+    }
+    const fromEnv = (value, envName) => {
+        if (value !== undefined)
+            return value;
+        if (!envName)
+            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.`);
+        }
+        return envValue;
+    };
+    const model = fromEnv(def.model, def.modelEnv);
+    const endpoint = fromEnv(def.endpoint, def.endpointEnv);
+    const keyEnv = def.apiKeyEnv ?? DEFAULT_KEY_ENV[def.api];
+    const apiKey = def.apiKey ?? (keyEnv ? env[keyEnv] : undefined);
+    return { api: def.api, model, endpoint, apiKey, keyEnv };
+}
+/**
+ * Instantiate one provider from a definition. The API is always explicit and is never inferred from
+ * API keys in the environment, so a key set for another tool is never spent on judging. Constructors
+ * apply their own API defaults for fields left undefined after hydration.
+ */
+export function createModelProvider(name, def, env = process.env) {
+    const h = hydrateProvider(name, def, 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.`);
+    }
+    switch (h.api) {
+        case 'fake':
+            return new FakeJudgeProvider();
+        case 'anthropic-messages':
+            return new AnthropicJudgeProvider(h);
+        case 'openrouter-decisions':
+        case 'typesafe-systemone':
+            return new JevJudgeProvider(h);
+        case 'openai-decisions':
+            return new OpenAIDecisionsJudgeProvider(h);
+        case 'openai-completions':
+            return new OpenAIJudgeProvider(h);
+    }
+}
+/**
+ * The provider a CLI run asks for: none without `--semantic`; the named one with `--semantic <provider>`;
+ * else the configured one.
+ */
+export function judgeForRun(config, space, semantic) {
+    if (!semantic)
+        return undefined;
+    return createJudge(config, space, typeof semantic === 'string' ? semantic : undefined);
+}
+/**
+ * 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.
+ */
+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>.');
+    }
+    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(', ')}.` : ''}`);
+    }
+    return createModelProvider(chosen, def, env);
+}

package/dist/judge/index.d.ts

@@ -0,0 +1,13 @@
+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.js';
+export { DEFAULT_VERDICTS, isJudgeError, semanticRuleSpec } from './verdicts';

package/dist/judge/index.js

@@ -0,0 +1,8 @@
+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';

package/dist/judge/judge-node.d.ts

@@ -0,0 +1,27 @@
+import type { SpaceGraph } from '../space-graph';
+import type { Rule, RuleSeverity, SpaceNode } from '../types';
+import { type TrimReport } from './trim';
+import type { SemanticJudgeProvider } from '../types.js';
+export type NodeJudgement = {
+    rule: Rule;
+    /** True when the verdict fails the rule (it has a severity), or the provider errored. */
+    failed: boolean;
+    /** Severity of the failing verdict; unset for a judge error, which takes the rule's own severity. */
+    severity?: RuleSeverity;
+    verdict?: string;
+    /** User-facing guidance declared for the failing verdict. */
+    guidance?: string;
+    evidence?: string;
+    /** Set when the judge could not produce a verdict for this rule. */
+    error?: string;
+};
+/**
+ * Judge several nodes at once. A judge with `evaluateNodes` gets every input in one call and may fold them into
+ * fewer requests; any other judge is called once per input. A node's rules that share a context (related nodes
+ * and bodies) form one input; an input that cannot fit the per-node input cap is not sent. Results align with
+ * `items`, in rule order. A failure marks only the affected rules as errors.
+ */
+export declare function judgeNodes(judge: SemanticJudgeProvider, items: Array<{
+    node: SpaceNode;
+    rules: Rule[];
+}>, graph: SpaceGraph, report?: TrimReport): Promise<NodeJudgement[][]>;