@kindgi/guardrails 0.0.0-bootstrap.0 → 0.1.0

package/dist/checks.js

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Built-in check library. Every entry is `kind: 'zero-llm'` — pure
+ * functions over the run trace, no external calls, deterministic. See
+ * `judge.ts` for LLM-judge evaluation.
+ *
+ * Adding a new built-in check: implement the function, add it to
+ * `BUILT_IN_CHECKS`, document its `config` schema in the JSDoc block.
+ */
+/**
+ * `must-cite`: assistant output must include at least N matches of the
+ * citation pattern. Config:
+ *   `{ minCitations?: number /* default 1 *\/, sourcePattern?: string /* regex *\/ }`
+ *
+ * Default `sourcePattern` matches `[<name>]`-style citations; override for
+ * verticals with different citation conventions.
+ */
+const mustCite = async (config, trace) => {
+    const minCitations = typeof config.minCitations === 'number' ? config.minCitations : 1;
+    const sourcePattern = typeof config.sourcePattern === 'string' ? config.sourcePattern : '\\[[^\\]]+\\]';
+    if (trace.output === undefined || trace.output.length === 0) {
+        return { passed: false, reason: 'output empty; nothing to cite' };
+    }
+    const re = new RegExp(sourcePattern, 'g');
+    const matches = trace.output.match(re) ?? [];
+    if (matches.length >= minCitations) {
+        return { passed: true, attributes: { citationCount: matches.length } };
+    }
+    return {
+        passed: false,
+        reason: `expected >= ${minCitations} citations, found ${matches.length}`,
+        attributes: { citationCount: matches.length },
+    };
+};
+/**
+ * `never-call-tool`: fail if any of the listed tools were invoked.
+ * Config: `{ tools: string[] }` — tool ids or names to forbid.
+ */
+const neverCallTool = async (config, trace) => {
+    // Accept both tool id / name strings and ToolRef objects
+    // ({ id, version }) — pack config authors may use either.
+    const rawTools = Array.isArray(config.tools) ? config.tools : [];
+    const forbidden = new Set();
+    for (const entry of rawTools) {
+        if (typeof entry === 'string') {
+            forbidden.add(entry);
+        }
+        else if (entry !== null &&
+            typeof entry === 'object' &&
+            'id' in entry &&
+            typeof entry.id === 'string') {
+            forbidden.add(entry.id);
+        }
+    }
+    const violations = [];
+    for (const call of trace.toolCalls) {
+        if (forbidden.has(call.toolId) || forbidden.has(call.toolName)) {
+            violations.push(call.toolName);
+        }
+    }
+    if (violations.length === 0)
+        return { passed: true };
+    return {
+        passed: false,
+        reason: `forbidden tool(s) invoked: ${[...new Set(violations)].join(', ')}`,
+        attributes: { violatingTools: [...new Set(violations)] },
+    };
+};
+/**
+ * `max-tool-calls`: cap total tool invocations. Config: `{ max?: number }` (default 10).
+ * Guards against runaway agents.
+ */
+const maxToolCalls = async (config, trace) => {
+    const max = typeof config.max === 'number' ? config.max : 10;
+    if (trace.toolCalls.length <= max) {
+        return { passed: true, attributes: { toolCallCount: trace.toolCalls.length } };
+    }
+    return {
+        passed: false,
+        reason: `expected <= ${max} tool calls, saw ${trace.toolCalls.length}`,
+        attributes: { toolCallCount: trace.toolCalls.length },
+    };
+};
+/**
+ * `output-matches`: final assistant output must match a regex (or fail
+ * if `negate: true`). Config: `{ pattern: string, flags?: string, negate?: boolean }`.
+ */
+const outputMatches = async (config, trace) => {
+    const pattern = typeof config.pattern === 'string' ? config.pattern : '';
+    const flags = typeof config.flags === 'string' ? config.flags : '';
+    const negate = config.negate === true;
+    if (pattern.length === 0) {
+        return { passed: false, reason: 'pattern config is required' };
+    }
+    const re = new RegExp(pattern, flags);
+    const output = trace.output ?? '';
+    const matched = re.test(output);
+    const passed = negate ? !matched : matched;
+    return passed
+        ? { passed: true }
+        : {
+            passed: false,
+            reason: negate
+                ? `output matched forbidden pattern /${pattern}/`
+                : `output did not match /${pattern}/`,
+        };
+};
+/**
+ * `tool-order`: tool calls must appear in a specified order. Config:
+ *   `{ sequence: string[] }` — tool names in expected order (subsequence).
+ * Non-listed tools are allowed to appear anywhere; the sequence must exist
+ * as a subsequence of the actual call order.
+ */
+const toolOrder = async (config, trace) => {
+    const sequence = Array.isArray(config.sequence) ? config.sequence : [];
+    if (sequence.length === 0)
+        return { passed: true };
+    let seqIndex = 0;
+    for (const call of trace.toolCalls) {
+        if (call.toolName === sequence[seqIndex])
+            seqIndex += 1;
+        if (seqIndex === sequence.length)
+            return { passed: true };
+    }
+    return {
+        passed: false,
+        reason: `expected tool-call subsequence [${sequence.join(', ')}] not observed`,
+        attributes: { matchedPrefix: sequence.slice(0, seqIndex) },
+    };
+};
+/**
+ * `required-substring`: `trace.output` must contain EVERY listed pattern.
+ * Config: `{ patterns: string[], caseSensitive?: boolean }`.
+ *
+ * Mirror of `forbidden-substring` — enables "output must include the
+ * standard legal disclaimer / required attribution / policy footer"
+ * without needing an llm-judge.
+ *
+ * Empty `patterns` array passes vacuously. Missing `output` on the
+ * trace fails (nothing can contain the required text).
+ */
+const requiredSubstring = async (config, trace) => {
+    const patternsRaw = Array.isArray(config.patterns) ? config.patterns : [];
+    const patterns = patternsRaw.filter((p) => typeof p === 'string' && p.length > 0);
+    if (patterns.length === 0)
+        return { passed: true };
+    if (trace.output === undefined || trace.output.length === 0) {
+        return {
+            passed: false,
+            reason: `output empty; ${patterns.length} required pattern(s) not satisfied`,
+            attributes: { missing: patterns },
+        };
+    }
+    const caseSensitive = config.caseSensitive === true;
+    const haystack = caseSensitive ? trace.output : trace.output.toLowerCase();
+    const missing = [];
+    for (const p of patterns) {
+        const needle = caseSensitive ? p : p.toLowerCase();
+        if (!haystack.includes(needle))
+            missing.push(p);
+    }
+    if (missing.length === 0)
+        return { passed: true };
+    return {
+        passed: false,
+        reason: `output missing required pattern(s): ${missing.join(', ')}`,
+        attributes: { missing },
+    };
+};
+/**
+ * `forbidden-substring`: `trace.output` must NOT contain any listed pattern.
+ * Config: `{ patterns: string[], caseSensitive?: boolean }`.
+ *
+ * Symmetric to `required-substring`. Enables "output must not contain
+ * PII markers / off-limits phrases / policy trigger words" without an
+ * llm-judge.
+ */
+const forbiddenSubstring = async (config, trace) => {
+    const patternsRaw = Array.isArray(config.patterns) ? config.patterns : [];
+    const patterns = patternsRaw.filter((p) => typeof p === 'string' && p.length > 0);
+    if (patterns.length === 0)
+        return { passed: true };
+    if (trace.output === undefined || trace.output.length === 0)
+        return { passed: true };
+    const caseSensitive = config.caseSensitive === true;
+    const haystack = caseSensitive ? trace.output : trace.output.toLowerCase();
+    const violated = [];
+    for (const p of patterns) {
+        const needle = caseSensitive ? p : p.toLowerCase();
+        if (haystack.includes(needle))
+            violated.push(p);
+    }
+    if (violated.length === 0)
+        return { passed: true };
+    return {
+        passed: false,
+        reason: `output contains forbidden pattern(s): ${violated.join(', ')}`,
+        attributes: { violated },
+    };
+};
+const BUILT_IN_CHECKS = [
+    { id: 'must-cite', kind: 'zero-llm', evaluate: mustCite },
+    { id: 'never-call-tool', kind: 'zero-llm', evaluate: neverCallTool },
+    { id: 'max-tool-calls', kind: 'zero-llm', evaluate: maxToolCalls },
+    { id: 'output-matches', kind: 'zero-llm', evaluate: outputMatches },
+    { id: 'tool-order', kind: 'zero-llm', evaluate: toolOrder },
+    { id: 'required-substring', kind: 'zero-llm', evaluate: requiredSubstring },
+    { id: 'forbidden-substring', kind: 'zero-llm', evaluate: forbiddenSubstring },
+];
+/**
+ * Create a fresh CheckRegistry pre-populated with built-in checks.
+ * Consumers register custom checks at pack init.
+ */
+export function createCheckRegistry(seed = []) {
+    const checks = new Map();
+    for (const c of BUILT_IN_CHECKS)
+        checks.set(c.id, c);
+    for (const c of seed)
+        checks.set(c.id, c);
+    return {
+        register(check) {
+            checks.set(check.id, check);
+        },
+        get(id) {
+            return checks.get(id);
+        },
+        list() {
+            return [...checks.values()];
+        },
+    };
+}
+/** Exported for tests + downstream introspection. */
+export const BUILT_IN_CHECK_IDS = BUILT_IN_CHECKS.map((c) => c.id);
+//# sourceMappingURL=checks.js.map

package/dist/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"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"}

package/dist/define-check.d.ts

@@ -0,0 +1,93 @@
+import type { AnySchema, ZodLikeSchema } from '@kindgi/schema';
+import type { CheckFunction, GuardrailKind, RegisteredCheck } from './types.js';
+/**
+ * Author-time inference from a Zod schema's `_zod.output`. Non-Zod
+ * schemas fall through to `Readonly<Record<string, unknown>>` — the
+ * same type that `Guardrail.config` already carries.
+ */
+export type InferCheckConfig<T> = T extends {
+    readonly _zod: {
+        readonly output: infer O;
+    };
+} ? O : Readonly<Record<string, unknown>>;
+/**
+ * The author-facing spec accepted by `defineCheck`. Extends
+ * `RegisteredCheck` with an optional `configSchema` slot that can be
+ * either a JSON Schema object or a Zod v4 schema. When set,
+ * `defineCheck` derives `validateConfig` from the schema — authors
+ * don't have to write it separately.
+ *
+ * `evaluate` is typed against the schema-inferred config for Zod-
+ * authored checks; JSON-Schema-authored checks fall back to
+ * `Readonly<Record<string, unknown>>`.
+ */
+export interface DefineCheckSpec<TConfigSchema extends AnySchema> {
+    /**
+     * Check identifier. Referenced by `Guardrail.check` on the wire.
+     * Convention: dot-namespaced for pack-authored checks (e.g.
+     * `'acme.max-citations'`); framework-shipped checks use stable ids
+     * like `'must-cite'` / `'never-call-tool'`.
+     */
+    readonly id: string;
+    /**
+     * `'zero-llm'` — pure function over the trace (fast, deterministic,
+     * default). `'llm-judge'` — uses a model (opt-in, costs money;
+     * needs `bindings.providerRegistry` or `bindings.judgeProvider`).
+     * `'external'` — evaluated by a caller-registered strategy.
+     */
+    readonly kind: GuardrailKind;
+    /**
+     * Config schema — Zod v4 or JSON Schema. When present, `defineCheck`
+     * derives `RegisteredCheck.validateConfig` from it, and
+     * `defineGuardrail` runs that against each `Guardrail.config`.
+     * Zod authors get schema-inferred config types on `evaluate`'s first
+     * parameter.
+     */
+    readonly configSchema?: TConfigSchema;
+    /**
+     * The check function. Signature: `(config, trace, bindings) => Promise<CheckResult>`.
+     * `config` is the guardrail's declared config (typed via `configSchema`
+     * when Zod-authored). `trace` is the accumulated `RunTrace` from the
+     * agent turn. `bindings` is the `EvaluationBindings` the caller
+     * passed to the engine (`{}` when none).
+     * Return `{passed: true}` or `{passed: false, reason: string, ...}`.
+     */
+    readonly evaluate: (config: InferCheckConfig<TConfigSchema>, trace: Parameters<CheckFunction>[1], bindings: Parameters<CheckFunction>[2]) => ReturnType<CheckFunction>;
+    /**
+     * Optional custom config validator. When `configSchema` is also set,
+     * both run — `configSchema` first, then this. `undefined` return means
+     * "config is valid"; non-undefined string is the error message.
+     */
+    readonly validateConfig?: (config: unknown) => string | undefined;
+}
+/**
+ * The concrete RegisteredCheck returned by `defineCheck`. When the
+ * author provided a Zod schema at `configSchema`, `configZod` is
+ * present so TS callers can `z.infer<typeof check.configZod>` for
+ * static types.
+ */
+export type DefinedCheck<TConfigSchema extends AnySchema> = RegisteredCheck & {
+    readonly configZod: TConfigSchema extends ZodLikeSchema ? TConfigSchema : undefined;
+    readonly configJsonSchema?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Build a `RegisteredCheck` with optional schema-derived config
+ * validation. Two authoring surfaces coexist:
+ *   1. JSON Schema Draft 2020-12 objects — compiled at author time
+ *      via Ajv; the check's `validateConfig` is derived from the
+ *      compiled validator.
+ *   2. Zod v4 schemas — converted via `z.toJSONSchema()` (peer dep),
+ *      then compiled the same way. TS callers get `z.infer<typeof
+ *      check.configZod>` for static config typing.
+ *
+ * When `configSchema` is omitted, this behaves as a passthrough:
+ * returns the check with the caller's `validateConfig` (or undefined).
+ *
+ * Failures at author time (Zod conversion or Ajv compile) surface via
+ * throw — same failure mode as construction of a bad
+ * `RegisteredCheck` object literal. Consumers catch at pack-init;
+ * downstream `defineGuardrail` runs the derived `validateConfig` at
+ * spec-registration time and reports via `Result`.
+ */
+export declare function defineCheck<TConfigSchema extends AnySchema = AnySchema>(spec: DefineCheckSpec<TConfigSchema>): DefinedCheck<TConfigSchema>;
+//# sourceMappingURL=define-check.d.ts.map

package/dist/define-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-check.d.ts","sourceRoot":"","sources":["../src/define-check.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAShF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,GACvF,CAAC,GACD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe,CAAC,aAAa,SAAS,SAAS;IAC9D;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,CACjB,MAAM,EAAE,gBAAgB,CAAC,aAAa,CAAC,EACvC,KAAK,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EACnC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KACnC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,aAAa,SAAS,SAAS,IAAI,eAAe,GAAG;IAC5E,QAAQ,CAAC,SAAS,EAAE,aAAa,SAAS,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;IACpF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,aAAa,SAAS,SAAS,GAAG,SAAS,EACrE,IAAI,EAAE,eAAe,CAAC,aAAa,CAAC,GACnC,YAAY,CAAC,aAAa,CAAC,CAiE7B"}

package/dist/define-check.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import * as addFormatsModule from 'ajv-formats';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { isZodSchema, loadZodConverterSync, toJSONSchemaSync } from '@kindgi/schema';
+const addFormatsRaw = addFormatsModule;
+const addFormats = typeof addFormatsRaw === 'function'
+    ? addFormatsRaw
+    : addFormatsRaw.default;
+/**
+ * Build a `RegisteredCheck` with optional schema-derived config
+ * validation. Two authoring surfaces coexist:
+ *   1. JSON Schema Draft 2020-12 objects — compiled at author time
+ *      via Ajv; the check's `validateConfig` is derived from the
+ *      compiled validator.
+ *   2. Zod v4 schemas — converted via `z.toJSONSchema()` (peer dep),
+ *      then compiled the same way. TS callers get `z.infer<typeof
+ *      check.configZod>` for static config typing.
+ *
+ * When `configSchema` is omitted, this behaves as a passthrough:
+ * returns the check with the caller's `validateConfig` (or undefined).
+ *
+ * Failures at author time (Zod conversion or Ajv compile) surface via
+ * throw — same failure mode as construction of a bad
+ * `RegisteredCheck` object literal. Consumers catch at pack-init;
+ * downstream `defineGuardrail` runs the derived `validateConfig` at
+ * spec-registration time and reports via `Result`.
+ */
+export function defineCheck(spec) {
+    const converter = spec.configSchema !== undefined && isZodSchema(spec.configSchema)
+        ? loadZodConverterSync()
+        : undefined;
+    let derivedValidator;
+    let jsonSchema;
+    let zodSchema;
+    if (spec.configSchema !== undefined) {
+        if (isZodSchema(spec.configSchema)) {
+            zodSchema = spec.configSchema;
+            const converted = toJSONSchemaSync(spec.configSchema, converter, 'input');
+            if (converted.kind === 'err') {
+                const err = {
+                    code: 'invalid-check-definition',
+                    message: `Check "${spec.id}" configSchema Zod conversion failed: ${converted.error.message}`,
+                    checkId: spec.id,
+                    cause: converted.error.cause,
+                };
+                throw errorFromDefinition(err);
+            }
+            jsonSchema = converted.value;
+        }
+        else {
+            jsonSchema = spec.configSchema;
+        }
+        const validator = compileValidator(jsonSchema, spec.id);
+        derivedValidator = (config) => {
+            if (!validator(config)) {
+                const errors = validator.errors ?? [];
+                const first = errors[0];
+                const path = first?.instancePath ?? '';
+                const message = first?.message ?? 'invalid config';
+                return `${path} ${message}`.trim();
+            }
+            return undefined;
+        };
+    }
+    const chainValidator = (a, b) => {
+        if (a === undefined)
+            return b;
+        if (b === undefined)
+            return a;
+        return (config) => {
+            const first = a(config);
+            if (first !== undefined)
+                return first;
+            return b(config);
+        };
+    };
+    const validate = chainValidator(derivedValidator, spec.validateConfig);
+    const check = {
+        id: spec.id,
+        kind: spec.kind,
+        evaluate: spec.evaluate,
+        ...(validate !== undefined && { validateConfig: validate }),
+        ...(zodSchema !== undefined && { configZod: zodSchema }),
+        ...(jsonSchema !== undefined && { configJsonSchema: jsonSchema }),
+    };
+    return check;
+}
+function compileValidator(schema, checkId) {
+    const ajv = new Ajv2020({ strict: true, allErrors: true, allowUnionTypes: false });
+    addFormats(ajv);
+    try {
+        return ajv.compile(schema);
+    }
+    catch (cause) {
+        const err = {
+            code: 'invalid-check-definition',
+            message: `Check "${checkId}" configSchema does not compile as JSON Schema Draft 2020-12: ${cause instanceof Error ? cause.message : String(cause)}`,
+            checkId,
+            cause,
+        };
+        throw errorFromDefinition(err);
+    }
+}
+function errorFromDefinition(err) {
+    const wrapped = new Error(err.message);
+    Object.assign(wrapped, err);
+    return wrapped;
+}
+//# sourceMappingURL=define-check.js.map

package/dist/define-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-check.js","sourceRoot":"","sources":["../src/define-check.ts"],"names":[],"mappings":"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"}

package/dist/define.d.ts

@@ -0,0 +1,27 @@
+import type { Result } from '@kindgi/types';
+import type { InvalidCheckConfigError, InvalidGuardrailError, UnknownCheckError } from './errors.js';
+import type { CheckRegistry, Guardrail } from './types.js';
+/**
+ * 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 declare function defineGuardrail(spec: Guardrail, checks: CheckRegistry): Result<Guardrail, InvalidGuardrailError | UnknownCheckError | InvalidCheckConfigError>;
+/**
+ * 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 declare function validateGuardrailSpec(spec: unknown): Result<Guardrail, InvalidGuardrailError>;
+/** The `$id` of the JSON Schema this loader validates against. */
+export declare const GUARDRAIL_SCHEMA_URI = "https://kindgi.com/schemas/v1/guardrail.schema.json";
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAe3D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,aAAa,GACpB,MAAM,CAAC,SAAS,EAAE,qBAAqB,GAAG,iBAAiB,GAAG,uBAAuB,CAAC,CA4DxF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,SAAS,EAAE,qBAAqB,CAAC,CA8B7F;AAED,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,wDAAsB,CAAC"}

package/dist/define.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { createSpecRegistry } from '@kindgi/schema';
+import guardrailSchema from './guardrail.schema.json' with { type: 'json' };
+const GUARDRAIL_SCHEMA_ID = 'https://kindgi.com/schemas/v1/guardrail.schema.json';
+let cachedRegistry;
+function schemaRegistry() {
+    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, checks) {
+    const r = schemaRegistry().validate(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;
+            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) {
+    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_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;
+            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 };
+}
+/** The `$id` of the JSON Schema this loader validates against. */
+export const GUARDRAIL_SCHEMA_URI = GUARDRAIL_SCHEMA_ID;
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"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"}