structured-context 0.12.0 → 0.13.0

package/dist/commands/validate.js

@@ -1,12 +1,19 @@
 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, validateSpace } from '../validate';
+import { formatErrors, ruleViolationMessage, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry } = context;
-    const result = await validateSpace(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 ruleCounts = { error: 0, warning: 0, info: 0 };
     for (const v of result.ruleViolations)
         ruleCounts[v.severity]++;
@@ -35,7 +42,7 @@ export async function validate(context, options = {}) {
         }
         for (const v of result.ruleViolations) {
             if (v.file && v.severity === 'error') {
-                addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`, v.severity);
+                addError(v.file, `rule:${v.ruleId}`, 'rule', ruleViolationMessage(v), v.severity);
             }
         }
         const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.file && v.severity === 'error').length;
@@ -56,6 +63,10 @@ export async function validate(context, options = {}) {
             orphanCount: result.orphans.length,
             parseIssues: result.parseIssues,
             unresolvedContentLinks: result.unresolvedContentLinks,
+            coverageGates: result.coverageGates,
+            contextTrimmed: result.contextTrimmed,
+            skippedByDepth: result.skippedByDepth,
+            depthLimit: result.depthLimit,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
@@ -95,6 +106,11 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Unresolved content links', result.unresolvedContentLinks.length, true, true));
     const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
     console.log(fmt('  Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
+    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);
+    console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
         for (const node of result.orphans)
@@ -159,6 +175,12 @@ export async function validate(context, options = {}) {
             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}]`);
+                if (v.evidence) {
+                    console.log(`      Evidence: ${v.evidence}`);
+                }
+                if (v.guidance) {
+                    console.log(`      Guidance: ${v.guidance}`);
+                }
             }
         }
     }
@@ -168,6 +190,23 @@ export async function validate(context, options = {}) {
             console.log(`   ${v.file}: ${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.nodeTitle}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
+            for (const file of gate.gatedFiles)
+                console.log(`      ${file}`);
+        }
+    }
+    if (result.skippedByDepth.length > 0) {
+        console.log(`\nSkipped by depth limit (--depth ${result.depthLimit}):`);
+        for (const { file } of result.skippedByDepth)
+            console.log(`   ${file}`);
+    }
+    if (result.contextTrimmed.nodeCount > 0) {
+        console.log(`\nContext trimmed for ${result.contextTrimmed.nodeCount} node(s) across rules ${result.contextTrimmed.ruleIds.join(', ')}.`);
+    }
     console.log(`\n`);
     if (result.nodeErrorCount > 0 ||
         result.refErrors.length > 0 ||

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import { type JudgeConfig, type ModelProviderConfig } from './judge/types.js';
 export type SpaceConfig = {
     name: string;
     path: string;
@@ -8,6 +9,8 @@ export type SpaceConfig = {
     views?: Record<string, {
         expression: string;
     }>;
+    /** Model provider for this space's semantic rules; overrides the top-level `semantic`. */
+    semantic?: JudgeConfig;
     /**
      * Directory of the config file that defined this space, used to anchor relative plugin-config
      * paths. Set by loadConfig; absent for a hand-assembled Config, whose callers must pass an
@@ -19,6 +22,10 @@ export type Config = {
     spaces: SpaceConfig[];
     schema?: string;
     includeSpacesFrom?: string[];
+    /** Model providers by name: how to reach each model. */
+    modelProviders?: Record<string, ModelProviderConfig>;
+    /** Model provider for semantic rules (a provider name). A space's `semantic` overrides it. */
+    semantic?: JudgeConfig;
 };
 /** Override the config file path used by loadConfig/updateSpaceField. */
 export declare function setConfigPath(path: string | undefined): void;

package/dist/config.js

@@ -3,9 +3,29 @@ import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020';
 import JSON5 from 'json5';
-import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
-import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from './plugins/util';
-import { bundledSchemasDir } from './schema/schema';
+import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants.js';
+import { MODEL_PROVIDER_APIS } from './judge/types.js';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from './plugins/util.js';
+import { bundledSchemasDir } from './schema/schema.js';
+const MODEL_PROVIDER_SCHEMA = {
+    type: 'object',
+    properties: {
+        api: { type: 'string', enum: MODEL_PROVIDER_APIS },
+        model: { type: 'string' },
+        modelEnv: { type: 'string' },
+        endpoint: { type: 'string' },
+        endpointEnv: { type: 'string' },
+        apiKey: { type: 'string' },
+        apiKeyEnv: { type: 'string' },
+    },
+    required: ['api'],
+    additionalProperties: false,
+};
+const SEMANTIC_CONFIG_SCHEMA = {
+    type: 'object',
+    properties: { provider: { type: 'string', minLength: 1 } },
+    additionalProperties: false,
+};
 const CONFIG_SCHEMA = {
     type: 'object',
     properties: {
@@ -27,6 +47,7 @@ const CONFIG_SCHEMA = {
                             additionalProperties: false,
                         },
                     },
+                    semantic: SEMANTIC_CONFIG_SCHEMA,
                 },
                 required: ['name', 'path'],
                 additionalProperties: false,
@@ -34,6 +55,8 @@ const CONFIG_SCHEMA = {
         },
         schema: { type: 'string' },
         includeSpacesFrom: { type: 'array', items: { type: 'string' } },
+        modelProviders: { type: 'object', additionalProperties: MODEL_PROVIDER_SCHEMA },
+        semantic: SEMANTIC_CONFIG_SCHEMA,
     },
     anyOf: [{ required: ['spaces'] }, { required: ['includeSpacesFrom'] }],
     additionalProperties: false,

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
-import type { SpaceContext } from './types';
+import type { SpaceContext } from './types.js';
 export declare function buildSpaceContext(spaceName: string): SpaceContext;

package/dist/index.js

@@ -2,21 +2,22 @@
 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) => {
@@ -34,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();
@@ -50,8 +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) => {
-    process.exitCode = await validateFileCommand(filePath, { json: options.json });
+    process.exitCode = await reportJudgeConfigErrors(() => validateFileCommand(filePath, {
+        json: options.json,
+        includeGated: options.includeGated,
+        semantic: options.semantic,
+        ruleFilter: options.ruleFilter,
+    }));
 });
 program
     .command('validate')
@@ -59,6 +80,10 @@ 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) {
@@ -66,7 +91,13 @@ program
     }
     else {
         // exitCode rather than process.exit(): exiting straight away can cut off large piped output
-        process.exitCode = await validate(context, { json: options.json });
+        process.exitCode = await reportJudgeConfigErrors(() => validate(context, {
+            json: options.json,
+            depth: options.depth,
+            includeGated: options.includeGated,
+            semantic: options.semantic,
+            ruleFilter: options.ruleFilter,
+        }));
     }
 });
 program
@@ -120,6 +151,16 @@ spacesCmd
     .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 })
@@ -140,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

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';