@kindgi/guardrails 0.0.0-bootstrap.0 → 0.1.0

package/src/define.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { createSpecRegistry } from '@kindgi/schema';
+import type { SpecRegistry } from '@kindgi/schema';
+import type { Result } from '@kindgi/types';
+
+import type {
+  InvalidCheckConfigError,
+  InvalidGuardrailError,
+  UnknownCheckError,
+} from './errors.js';
+import guardrailSchema from './guardrail.schema.json' with { type: 'json' };
+import type { CheckRegistry, Guardrail } from './types.js';
+
+const GUARDRAIL_SCHEMA_ID = 'https://kindgi.com/schemas/v1/guardrail.schema.json';
+
+let cachedRegistry: SpecRegistry | undefined;
+function schemaRegistry(): SpecRegistry {
+  if (cachedRegistry !== undefined) return cachedRegistry;
+  const built = createSpecRegistry([guardrailSchema]);
+  if (built.kind === 'err') {
+    throw new Error(`@kindgi/guardrails: bundled schema failed to compile: ${built.error.message}`);
+  }
+  cachedRegistry = built.value;
+  return cachedRegistry;
+}
+
+/**
+ * Validate a guardrail declaration + resolve its check.
+ *
+ * Fails if:
+ *   1. The declaration doesn't match `@kindgi/specs/guardrail.schema.json`.
+ *   2. The `check` id isn't in the registry.
+ *   3. The registered check's `kind` differs from the guardrail's `kind`.
+ *   4. The check has a config validator and `guardrail.config` fails it.
+ *
+ * Every failure surfaces at pack-init — before any run touches the guardrail.
+ */
+export function defineGuardrail(
+  spec: Guardrail,
+  checks: CheckRegistry,
+): Result<Guardrail, InvalidGuardrailError | UnknownCheckError | InvalidCheckConfigError> {
+  const r = schemaRegistry().validate<Guardrail>(GUARDRAIL_SCHEMA_ID, spec);
+  if (r.kind === 'err') {
+    const err = r.error;
+    if (err.code !== 'validation-error') {
+      throw new Error(`@kindgi/guardrails: unexpected schema error ${err.code}: ${err.message}`);
+    }
+    const issues = err.errors.map((e) => {
+      const ajv = e as { instancePath?: unknown; message?: unknown };
+      return {
+        path: typeof ajv.instancePath === 'string' ? ajv.instancePath : '',
+        message: typeof ajv.message === 'string' ? ajv.message : 'validation failed',
+      };
+    });
+    return {
+      kind: 'err',
+      error: { code: 'invalid-guardrail', message: err.message, issues },
+    };
+  }
+
+  const check = checks.get(spec.check);
+  if (check === undefined) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'unknown-check',
+        message: `Guardrail "${spec.id}" references unregistered check "${spec.check}"`,
+        guardrailId: spec.id,
+        checkId: spec.check,
+      },
+    };
+  }
+
+  if (check.kind !== spec.kind) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'invalid-guardrail',
+        message: `Guardrail "${spec.id}" kind "${spec.kind}" does not match check "${spec.check}" kind "${check.kind}"`,
+        issues: [{ path: '/kind', message: `expected "${check.kind}"` }],
+      },
+    };
+  }
+
+  if (check.validateConfig !== undefined && spec.config !== undefined) {
+    const reason = check.validateConfig(spec.config);
+    if (reason !== undefined) {
+      return {
+        kind: 'err',
+        error: {
+          code: 'invalid-check-config',
+          message: `Guardrail "${spec.id}" config invalid: ${reason}`,
+          guardrailId: spec.id,
+          reason,
+        },
+      };
+    }
+  }
+
+  return { kind: 'ok', value: spec };
+}
+
+/**
+ * Validate an arbitrary wire spec against `@kindgi/specs/guardrail.schema.json`.
+ * Unlike `defineGuardrail`, this does NOT resolve the `check` reference
+ * against a `CheckRegistry` — used by transport layers (e.g. the
+ * `@kindgi/api` guardrail routes) that accept metadata-only guardrail
+ * registrations. The check implementation must already be available to
+ * the server that evaluates the guardrail.
+ */
+export function validateGuardrailSpec(spec: unknown): Result<Guardrail, InvalidGuardrailError> {
+  if (spec === null || typeof spec !== 'object') {
+    return {
+      kind: 'err',
+      error: {
+        code: 'invalid-guardrail',
+        message: 'Guardrail spec must be an object',
+        issues: [{ path: '', message: 'must be an object' }],
+      },
+    };
+  }
+  const r = schemaRegistry().validate<Guardrail>(GUARDRAIL_SCHEMA_ID, spec);
+  if (r.kind === 'err') {
+    const err = r.error;
+    if (err.code !== 'validation-error') {
+      throw new Error(`@kindgi/guardrails: unexpected schema error ${err.code}: ${err.message}`);
+    }
+    const issues = err.errors.map((e) => {
+      const ajv = e as { instancePath?: unknown; message?: unknown };
+      return {
+        path: typeof ajv.instancePath === 'string' ? ajv.instancePath : '',
+        message: typeof ajv.message === 'string' ? ajv.message : 'validation failed',
+      };
+    });
+    return {
+      kind: 'err',
+      error: { code: 'invalid-guardrail', message: err.message, issues },
+    };
+  }
+  return { kind: 'ok', value: spec as Guardrail };
+}
+
+/** The `$id` of the JSON Schema this loader validates against. */
+export const GUARDRAIL_SCHEMA_URI = GUARDRAIL_SCHEMA_ID;

package/src/engine.ts

@@ -0,0 +1,271 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Timestamp } from '@kindgi/types';
+
+import type { GuardrailError, JudgeMissingError, ScopeMismatchError } from './errors.js';
+import {
+  type ExecutionStrategy,
+  type ExecutionStrategyRegistry,
+  createExecutionStrategyRegistry,
+  externalStrategy,
+  makeLlmJudgeStrategy,
+  zeroLlmStrategy,
+} from './execution-strategy.js';
+import { type LlmJudgeConfig, invokeJudge } from './judge.js';
+import type {
+  CheckRegistry,
+  CheckResult,
+  EvaluationBindings,
+  EvaluationResult,
+  Guardrail,
+  RunTrace,
+  Scope,
+} from './types.js';
+
+/**
+ * Default strategy registry seeded with the built-ins (`zero-llm`,
+ * `llm-judge`, `external`). Cached so repeated `evaluateGuardrail`
+ * calls don't reinstantiate the registry.
+ */
+let defaultRegistry: ExecutionStrategyRegistry | undefined;
+function getDefaultStrategyRegistry(): ExecutionStrategyRegistry {
+  if (defaultRegistry === undefined) {
+    defaultRegistry = createExecutionStrategyRegistry([
+      zeroLlmStrategy,
+      makeLlmJudgeStrategy((config, capability, trace, bindings) =>
+        invokeJudge(config as LlmJudgeConfig, capability, trace, bindings),
+      ),
+      externalStrategy,
+    ]);
+  }
+  return defaultRegistry;
+}
+
+/** Expose the built-in registry so callers can extend it with adapter strategies. */
+export function builtInStrategies(): readonly ExecutionStrategy[] {
+  return getDefaultStrategyRegistry().list();
+}
+
+/**
+ * Evaluate one guardrail against a run trace. Handles:
+ *   - Scope check (mode + agent + flow + tenant filters).
+ *   - Dispatch by `kind` through `bindings.strategies` (or the built-ins):
+ *     zero-llm → check.evaluate; llm-judge → invokeJudge; external → an
+ *     `invalid-guardrail` error unless the caller registered its own
+ *     `external` strategy.
+ *   - Action derivation from `guardrail.action.on-violation`.
+ *   - Compliance evidence emission on violation (if bindings.compliance
+ *     is set and the trace carries a `projectId`).
+ *   - Action-handler invocation on violation (if bindings.actions is set);
+ *     an action with no registered handler returns `unknown-action`.
+ *
+ * Returns:
+ *   - `{ kind: 'ok', value: EvaluationResult }` — guardrail applied + evaluated.
+ *   - `{ kind: 'skip', reason }` — guardrail didn't apply (scope mismatch).
+ *   - `{ kind: 'err', error }` — evaluation failed (unknown kind or check,
+ *     judge missing or unroutable), or the violation's action has no
+ *     handler in `bindings.actions` (`unknown-action`, after the violation
+ *     was recorded).
+ */
+export type EvaluationOutcome =
+  | { readonly kind: 'ok'; readonly value: EvaluationResult }
+  | { readonly kind: 'skip'; readonly reason: ScopeMismatchError }
+  | { readonly kind: 'err'; readonly error: GuardrailError | JudgeMissingError };
+
+export async function evaluateGuardrail(
+  guardrail: Guardrail,
+  checks: CheckRegistry,
+  trace: RunTrace,
+  bindings: EvaluationBindings = {},
+): Promise<EvaluationOutcome> {
+  const scope = checkScope(guardrail, trace);
+  if (scope !== null) return { kind: 'skip', reason: scope };
+
+  // Check-registry lookup is delegated to each strategy — `zero-llm`
+  // resolves the check inside its evaluate; strategies like
+  // `sandbox-code` or `external` don't consult the CheckRegistry at
+  // all. Keeps the engine strategy-agnostic.
+
+  const strategies = bindings.strategies ?? getDefaultStrategyRegistry();
+  const strategy = strategies.get(guardrail.kind);
+  if (strategy === undefined) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'invalid-guardrail',
+        message: `Guardrail "${guardrail.id}" declares unknown kind "${guardrail.kind}" — no execution strategy registered`,
+        issues: [{ path: '/kind', message: `unknown kind: ${guardrail.kind}` }],
+      },
+    };
+  }
+  const strategyOutcome = await strategy.evaluate(guardrail, checks, trace, bindings);
+  if (strategyOutcome.kind === 'err') {
+    const err = strategyOutcome.error;
+    return {
+      kind: 'err',
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.issues !== undefined && { issues: err.issues }),
+        guardrailId: guardrail.id,
+      } as GuardrailError | JudgeMissingError,
+    };
+  }
+  const result: CheckResult = strategyOutcome.value;
+
+  const action: EvaluationResult['action'] = result.passed
+    ? 'noop'
+    : guardrail.action['on-violation'];
+  const severity = guardrail.severity ?? 'error';
+  const evaluation: EvaluationResult = {
+    guardrailId: guardrail.id,
+    result,
+    action,
+    severity,
+    at: new Date().toISOString() as Timestamp,
+  };
+
+  if (!result.passed && bindings.compliance !== undefined && trace.projectId !== undefined) {
+    // Compliance emit needs `projectId` (every evidence record is
+    // project-scoped). Skip emit when the trace carries no project
+    // scope.
+    await bindings.compliance.emit({
+      tenantId: trace.tenantId,
+      projectId: trace.projectId,
+      kind: 'guardrail-violation',
+      outcome: 'failed',
+      payload: {
+        version: 1,
+        guardrailId: guardrail.id,
+        guardrailName: guardrail.name,
+        checkId: guardrail.check,
+        checkKind: guardrail.kind,
+        severity,
+        action: guardrail.action['on-violation'],
+        reason: result.reason,
+        judgeResponse: result.judgeResponse,
+        attributes: result.attributes,
+      },
+      ...(trace.runId !== undefined && {
+        provenanceRef: { runId: trace.runId },
+      }),
+    });
+  }
+
+  // Invoke the registered action handler. Handler errors are logged into
+  // the evaluation attributes but don't roll back the evaluation itself —
+  // the violation is still recorded. `on-violation` is an open string, so
+  // an action nobody registered a handler for fails here, by name.
+  if (bindings.actions !== undefined && !result.passed) {
+    const handler = bindings.actions.get(action);
+    if (handler === undefined) {
+      return {
+        kind: 'err',
+        error: {
+          code: 'unknown-action',
+          message: `Guardrail "${guardrail.id}" fired action "${action}", but no action handler is registered for it`,
+          guardrailId: guardrail.id,
+          action,
+        },
+      };
+    }
+    const applied = await handler.apply({ guardrail, evaluation, trace });
+    if (applied.kind === 'err') {
+      // Attach handler error to the evaluation attributes; don't fail.
+      (evaluation as { result: CheckResult }).result = {
+        ...evaluation.result,
+        attributes: {
+          ...(evaluation.result.attributes ?? {}),
+          actionHandlerError: applied.error,
+        },
+      };
+    }
+  }
+
+  return { kind: 'ok', value: evaluation };
+}
+
+/**
+ * Evaluate every guardrail in the list against a trace. Order-independent —
+ * each check is a pure function over the trace. Returns one outcome per
+ * guardrail.
+ */
+export async function evaluateAll(
+  guardrails: readonly Guardrail[],
+  checks: CheckRegistry,
+  trace: RunTrace,
+  bindings: EvaluationBindings = {},
+): Promise<readonly EvaluationOutcome[]> {
+  return Promise.all(guardrails.map((inv) => evaluateGuardrail(inv, checks, trace, bindings)));
+}
+
+/**
+ * Extract only the violations from a batch of outcomes — convenience for
+ * callers that want to apply enforcement actions.
+ */
+export function violations(outcomes: readonly EvaluationOutcome[]): readonly EvaluationResult[] {
+  const out: EvaluationResult[] = [];
+  for (const o of outcomes) {
+    if (o.kind === 'ok' && !o.value.result.passed) out.push(o.value);
+  }
+  return out;
+}
+
+function checkScope(guardrail: Guardrail, trace: RunTrace): ScopeMismatchError | null {
+  const scope: Scope = guardrail.scope ?? {};
+  const when = scope.when ?? 'always';
+  if (when === 'ci-only' && trace.mode !== 'ci') {
+    return {
+      code: 'scope-mismatch',
+      message: `guardrail "${guardrail.id}" is ci-only`,
+      guardrailId: guardrail.id,
+      reason: 'wrong-mode',
+    };
+  }
+  if (when === 'runtime-only' && trace.mode !== 'runtime') {
+    return {
+      code: 'scope-mismatch',
+      message: `guardrail "${guardrail.id}" is runtime-only`,
+      guardrailId: guardrail.id,
+      reason: 'wrong-mode',
+    };
+  }
+  if (
+    scope.agents !== undefined &&
+    scope.agents.length > 0 &&
+    (trace.agentId === undefined || !scope.agents.includes(trace.agentId))
+  ) {
+    return {
+      code: 'scope-mismatch',
+      message: `guardrail "${guardrail.id}" does not apply to agent ${String(trace.agentId)}`,
+      guardrailId: guardrail.id,
+      reason: 'wrong-agent',
+    };
+  }
+  if (
+    scope.flows !== undefined &&
+    scope.flows.length > 0 &&
+    (trace.flowId === undefined || !scope.flows.includes(trace.flowId))
+  ) {
+    return {
+      code: 'scope-mismatch',
+      message: `guardrail "${guardrail.id}" does not apply to flow ${String(trace.flowId)}`,
+      guardrailId: guardrail.id,
+      reason: 'wrong-flow',
+    };
+  }
+  if (
+    scope.tenants !== undefined &&
+    scope.tenants.length > 0 &&
+    !scope.tenants.includes(trace.tenantId)
+  ) {
+    return {
+      code: 'scope-mismatch',
+      message: `guardrail "${guardrail.id}" does not apply to tenant ${trace.tenantId}`,
+      guardrailId: guardrail.id,
+      reason: 'wrong-tenant',
+    };
+  }
+  return null;
+}

package/src/errors.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { GuardrailId } from '@kindgi/types';
+
+/**
+ * Errors emitted by @kindgi/guardrails. Every variant carries a `code`
+ * for pattern matching; messages are human-readable, not API contract.
+ */
+export type GuardrailError =
+  | InvalidGuardrailError
+  | InvalidCheckDefinitionError
+  | UnknownCheckError
+  | InvalidCheckConfigError
+  | JudgeMissingError
+  | JudgeRoutingError
+  | ScopeMismatchError
+  | UnknownActionError;
+
+/**
+ * The judge model couldn't be routed via `@kindgi/capabilities`. Wraps
+ * the underlying capability error (usually `capability-unsatisfiable` —
+ * no registered provider matches the judge's declared capability).
+ */
+export interface JudgeRoutingError {
+  readonly code: 'judge-routing-failed';
+  readonly message: string;
+  readonly guardrailId: GuardrailId;
+  readonly cause: unknown;
+}
+
+/**
+ * The declaration is invalid. From `defineGuardrail` /
+ * `validateGuardrailSpec`: it fails the schema, or (`defineGuardrail`)
+ * its registered check has another kind. From the engine: its kind has
+ * no registered strategy, it is `llm-judge` without `judgeCapabilities`,
+ * or it is `external` and only the built-in `external` strategy is
+ * registered.
+ */
+export interface InvalidGuardrailError {
+  readonly code: 'invalid-guardrail';
+  readonly message: string;
+  readonly issues: readonly { readonly path: string; readonly message: string }[];
+}
+
+/** The guardrail references a check id that isn't registered. */
+export interface UnknownCheckError {
+  readonly code: 'unknown-check';
+  readonly message: string;
+  readonly guardrailId: GuardrailId;
+  readonly checkId: string;
+}
+
+/**
+ * The guardrail fired an action that no handler in
+ * `EvaluationBindings.actions` handles. `on-violation` is an open
+ * string, so an unknown name is accepted at define time and surfaces
+ * here, when the guardrail fires. The violation itself was already
+ * recorded (and compliance evidence emitted) before the lookup.
+ */
+export interface UnknownActionError {
+  readonly code: 'unknown-action';
+  readonly message: string;
+  readonly guardrailId: GuardrailId;
+  readonly action: string;
+}
+
+/** The guardrail's `config` failed the check's own validator. */
+export interface InvalidCheckConfigError {
+  readonly code: 'invalid-check-config';
+  readonly message: string;
+  readonly guardrailId: GuardrailId;
+  readonly reason: string;
+}
+
+/**
+ * `defineCheck` couldn't build the check — either the supplied Zod
+ * schema failed to convert via `z.toJSONSchema()`, or the resulting
+ * JSON Schema failed to compile as Draft 2020-12.
+ */
+export interface InvalidCheckDefinitionError {
+  readonly code: 'invalid-check-definition';
+  readonly message: string;
+  readonly checkId: string;
+  readonly cause: unknown;
+}
+
+/**
+ * An `llm-judge` guardrail was evaluated without the required bindings
+ * (providerRegistry or judgeProvider). Runtime-only error.
+ */
+export interface JudgeMissingError {
+  readonly code: 'judge-missing';
+  readonly message: string;
+  readonly guardrailId: GuardrailId;
+}
+
+/**
+ * Not really an error — surfaced so callers can distinguish "guardrail
+ * didn't apply to this trace" from "guardrail applied and passed."
+ */
+export interface ScopeMismatchError {
+  readonly code: 'scope-mismatch';
+  readonly message: string;
+  readonly guardrailId: GuardrailId;
+  readonly reason: 'wrong-mode' | 'wrong-agent' | 'wrong-flow' | 'wrong-tenant';
+}

package/src/execution-strategy.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Capability } from '@kindgi/capabilities';
+
+import type {
+  CheckRegistry,
+  CheckResult,
+  EvaluationBindings,
+  Guardrail,
+  RunTrace,
+} from './types.js';
+
+/**
+ * A strategy that knows how to evaluate one `Guardrail.kind`. Registered
+ * once at boot; the engine dispatches by looking up `guardrail.kind`
+ * against the strategy registry.
+ *
+ * Built-in strategies: `zero-llm` (delegates to `CheckRegistry`),
+ * `llm-judge` (routes through capabilities + `invokeJudge`), and
+ * `external` (returns an "evaluated elsewhere" error).
+ *
+ * Adapter packages register their own strategies without touching the
+ * engine — e.g. a strategy that runs check code in a sandbox, or one
+ * that delegates to an external policy engine.
+ */
+export interface ExecutionStrategy {
+  readonly kind: string;
+  /** Human-friendly name for diagnostics. */
+  readonly name?: string;
+  /**
+   * Evaluate one guardrail against a trace. Returns the CheckResult the
+   * engine finalizes into an EvaluationResult; or an error object shaped
+   * to be surfaced directly.
+   */
+  evaluate(
+    guardrail: Guardrail,
+    checks: CheckRegistry,
+    trace: RunTrace,
+    bindings: EvaluationBindings,
+  ): Promise<StrategyResult>;
+}
+
+/**
+ * Discriminated result a strategy returns. `ok` produces a CheckResult;
+ * `err` surfaces a structured error with a JSON-Pointer-style path so
+ * the engine can attach it to the guardrail id it came from.
+ */
+export type StrategyResult =
+  | { readonly kind: 'ok'; readonly value: CheckResult }
+  | { readonly kind: 'err'; readonly error: StrategyError };
+
+export interface StrategyError {
+  /** Discriminant matching the engine's GuardrailError union or a sub-code. */
+  readonly code: string;
+  readonly message: string;
+  readonly issues?: readonly { readonly path: string; readonly message: string }[];
+  /** Filled in by the engine — the guardrail id currently evaluating. */
+  readonly guardrailId?: string;
+}
+
+/**
+ * Registry the engine consults at dispatch time. Register once; every
+ * subsequent `evaluateGuardrail` call sees the additional strategy.
+ */
+export interface ExecutionStrategyRegistry {
+  register(strategy: ExecutionStrategy): void;
+  get(kind: string): ExecutionStrategy | undefined;
+  list(): readonly ExecutionStrategy[];
+}
+
+export function createExecutionStrategyRegistry(
+  seed: readonly ExecutionStrategy[] = [],
+): ExecutionStrategyRegistry {
+  const strategies = new Map<string, ExecutionStrategy>();
+  for (const s of seed) strategies.set(s.kind, s);
+  return {
+    register(strategy): void {
+      strategies.set(strategy.kind, strategy);
+    },
+    get(kind): ExecutionStrategy | undefined {
+      return strategies.get(kind);
+    },
+    list(): readonly ExecutionStrategy[] {
+      return [...strategies.values()];
+    },
+  };
+}
+
+// ============ built-in strategies ============
+
+/** `zero-llm` — delegate to the registered `Check` via CheckRegistry. */
+export const zeroLlmStrategy: ExecutionStrategy = {
+  kind: 'zero-llm',
+  name: 'Zero-LLM check',
+  async evaluate(guardrail, checks, trace, bindings): Promise<StrategyResult> {
+    const check = checks.get(guardrail.check);
+    if (check === undefined) {
+      return {
+        kind: 'err',
+        error: {
+          code: 'unknown-check',
+          message: `Guardrail "${guardrail.id}" references unregistered check "${guardrail.check}"`,
+        },
+      };
+    }
+    const config = (guardrail.config ?? {}) as Readonly<Record<string, unknown>>;
+    const result = await check.evaluate(config, trace, bindings);
+    return { kind: 'ok', value: result };
+  },
+};
+
+/**
+ * `external` — placeholder for guardrails evaluated by an external
+ * service: it always returns an `invalid-guardrail` error. Callers that
+ * want external evaluation register their own `external` strategy that
+ * routes to their service.
+ */
+export const externalStrategy: ExecutionStrategy = {
+  kind: 'external',
+  name: 'External (not implemented at engine layer)',
+  async evaluate(): Promise<StrategyResult> {
+    return {
+      kind: 'err',
+      error: {
+        code: 'invalid-guardrail',
+        message:
+          'external-kind guardrails are evaluated outside the engine — register an execution strategy for kind `external`',
+        issues: [
+          {
+            path: '/kind',
+            message: 'external kind requires a caller-registered execution strategy',
+          },
+        ],
+      },
+    };
+  },
+};
+
+/**
+ * Factory for the built-in `llm-judge` strategy. Takes the judge
+ * function as a parameter so this module does not import judge.ts; the
+ * engine passes `invokeJudge`.
+ */
+export function makeLlmJudgeStrategy(
+  invokeJudge: (
+    config: unknown,
+    capability: Capability,
+    trace: RunTrace,
+    bindings: EvaluationBindings,
+  ) => Promise<
+    CheckResult | { readonly error: { readonly code: string; readonly message: string } }
+  >,
+): ExecutionStrategy {
+  return {
+    kind: 'llm-judge',
+    name: 'LLM judge',
+    async evaluate(guardrail, _checks, trace, bindings): Promise<StrategyResult> {
+      if (guardrail.judgeCapabilities === undefined) {
+        return {
+          kind: 'err',
+          error: {
+            code: 'invalid-guardrail',
+            message: `llm-judge guardrail "${guardrail.id}" missing judgeCapabilities`,
+            issues: [{ path: '/judgeCapabilities', message: 'required for kind=llm-judge' }],
+          },
+        };
+      }
+      const judged = await invokeJudge(
+        guardrail.config ?? {},
+        guardrail.judgeCapabilities,
+        trace,
+        bindings,
+      );
+      if ('error' in judged) {
+        return {
+          kind: 'err',
+          error: { code: judged.error.code, message: judged.error.message },
+        };
+      }
+      return { kind: 'ok', value: judged };
+    },
+  };
+}