@agenttrail/guardrails 0.0.1-rc.1

package/dist/schema.d.cts

@@ -0,0 +1,944 @@
+import { z } from 'zod';
+
+/**
+ * The guardrails rule format — self-contained, and deliberately so.
+ *
+ * ── Why this file imports nothing from the monorepo ──────────────────────────
+ *
+ * `@agenttrail/shared` and `@agenttrail/policy-engine` are both `private: true`.
+ * A public package whose source reads `import { … } from "@agenttrail/shared"`
+ * does not build for anyone outside this repo, and open source whose source does
+ * not compile is the first thing this audience checks
+ * (AGENTTRAIL-GUARD-SPEC.md 2.1).
+ *
+ * So this file mirrors the engine's `MatchCondition` / `Match` rather than
+ * importing them, and `@agenttrail/guardrails` declares NO dependency on either
+ * package — not even a dev one. That is not a convention anyone has to remember:
+ * pnpm does not hoist workspace packages, so a stray import here fails to
+ * resolve at typecheck and build time. A `MODULE_NOT_FOUND` cannot be argued
+ * with, and a lint rule over source text can — this repo has already had comment
+ * prose parsed as an import.
+ *
+ * The price of owning a second copy is drift, so a parity test that lives with
+ * the policy engine pins this schema to the engine's own:
+ * `guardrails-schema-parity.test.ts`.
+ * It is not optional and not redundant. Read it before changing anything here.
+ *
+ * ── What this is NOT ─────────────────────────────────────────────────────────
+ *
+ * This is not the engine's `PolicyPredicate`. That schema is `.strict()` with a
+ * required `version` and `action`, so it rejects 100% of this rule format — it
+ * is the schema of the `match` SUB-OBJECT, not of a rule. A rule carries
+ * `defaultAction` (what the guard does when it matches) and no `version`; the
+ * package version is the corpus version.
+ */
+
+/**
+ * All five product severities, in order, most→least severe.
+ *
+ * This tuple mirrors `shared/src/types/common.ts` `Severity` and `risk.ts`
+ * `RISK_SEVERITIES` exactly, and the parity test pins them together so they
+ * cannot drift. Matching the product means the hosted catalog layers its own
+ * metadata by rule id with no translation table in between (spec 8.3).
+ *
+ * `info` earns its place: five of the eight packs default to `ask`/`warn`, and a
+ * warn-only rule labelled `low` overstates itself.
+ *
+ * ── Sharing a vocabulary with a pricing table is not permission to price ─────
+ *
+ * These same five values key `DEFAULT_PER_INCIDENT_CENTS` in the private
+ * `risk.ts` — `critical` is $160,000. Because the tuples now line up perfectly,
+ * joining severity to money is one line. **Do not.** The guard prints no
+ * currency anywhere (Appendix 0 #12, spec 9.1), and this package therefore ships
+ * NO mapping from severity to money. The reason is on the record: a slightly
+ * loose rule once produced the headline "rm -rf seen 17 times, $5,070,000",
+ * built entirely out of a test suite deleting its own scratch folders.
+ */
+declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+/** How dangerous the thing a rule catches is. An authoring signal, not a price. */
+declare const SeveritySchema: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
+/**
+ * What the guard does when a rule matches.
+ *
+ * The guard maps these onto Claude Code's `PreToolUse` verdicts:
+ * `block` → deny, `require_approval` → ask, `warn` → allow-but-recorded.
+ */
+declare const ACTIONS: readonly ["block", "require_approval", "warn"];
+/** The action a rule takes by default, before any user override. */
+declare const ActionSchema: z.ZodEnum<["block", "require_approval", "warn"]>;
+/** Longest accepted `detail_matches` pattern. Long enough for any real rule. */
+declare const DETAIL_MATCHES_MAX_PATTERN_LENGTH = 200;
+/** Most `detail_matches` patterns allowed on one condition (they are ORed). */
+declare const DETAIL_MATCHES_MAX_PATTERNS = 10;
+/**
+ * Reject a regex that can backtrack catastrophically, at PARSE time.
+ *
+ * Mirrored from the engine's `hasNestedUnboundedQuantifier`, and pinned to it by
+ * the parity test — including behavior over a shared pattern corpus, not just
+ * the fact that a function exists.
+ *
+ * Node has no regex timeout, so the only real bounds are a non-backtracking
+ * engine (RE2 — a runtime dependency deliberately not taken) or a syntactic
+ * restriction. This is the syntactic one: it rejects **star height >= 2**, an
+ * unbounded quantifier applied to a group that itself contains an unbounded
+ * quantifier — `(a+)+`, `(a*)*`, `(\s+x?)+` — the shape behind essentially every
+ * practical ReDoS.
+ *
+ * This matters more here than it does on the server. The guard's hook has a 10s
+ * Claude Code timeout, no internal watchdog, and it **fails open**: a pattern
+ * that backtracks does not merely make enforcement slow, it lets the action
+ * through. A slow rule on the hosted PDP is a slow rule; a slow rule in the
+ * guard is a disabled rule.
+ *
+ * HONEST LIMIT: this is a bound, not a proof. Star height 1 can still be
+ * quadratic (`(a|a)*`), which is slow but not exponential, and is acceptable
+ * against the length cap above. A hard guarantee needs RE2.
+ *
+ * @param source - The regex body (no delimiters, no flags).
+ * @returns `true` when the pattern nests unbounded quantifiers.
+ */
+declare function hasNestedUnboundedQuantifier(source: string): boolean;
+/**
+ * One condition matched against a tool call.
+ *
+ * - `kind`: required. The span kind, e.g. `execute_tool`. Case-insensitive.
+ * - `label`: optional. The tool name — a case-insensitive GLOB, so
+ *   `mcp__chrome__*` and `{Bash,PowerShell}` are one condition rather than a
+ *   list that rots. A plain label has no glob character and matches exactly.
+ * - `detail_contains`: optional. Substrings that must ALL appear (AND).
+ *   **CASE-SENSITIVE**, and deliberately: `AKIA`, `ghp_`, `sk_live_` and the
+ *   upper-case `TRUNCATE` arm are rules where case IS the signal. Author
+ *   case-insensitive text matches with `detail_matches` instead.
+ * - `detail_matches`: optional. Regex patterns against the same text; at least
+ *   one must match (OR, unlike `detail_contains`). Case-insensitive.
+ * - `file_glob`: optional. Case-insensitive glob against the file path.
+ *
+ * ── Two engine fields are deliberately absent ────────────────────────────────
+ *
+ * `numeric` is BANNED (spec 7.4). At guard decision time `tokens`,
+ * `cachedTokens` and `durationMs` are all 0, because the action has not run yet.
+ * `gt` is therefore always false — the rule can never fire — and, worse, **`lt`
+ * is always true, so the rule fires on every single command.** Omitting the key
+ * from a `.strict()` object makes that a parse error rather than a lint finding.
+ *
+ * `scope` is BANNED for the same class of reason and is absent from the rule
+ * envelope below: `agent_in` compares literally against an agent id that is
+ * always a UUID, never the string `"claude-code"`, so a scoped rule matches
+ * nothing, forever, silently.
+ *
+ * ── The third ban needs an actual check ──────────────────────────────────────
+ *
+ * A command matcher (`detail_contains` / `detail_matches`) and a file matcher
+ * (`file_glob`) in ONE condition can never both be satisfied: the guard's mapper
+ * is an if/else chain, so no real tool call ever carries both a command and a
+ * file path. The engine's schema permits the combination; this one refuses it,
+ * which is a deliberate divergence the parity test knows about.
+ */
+declare const MatchConditionSchema: z.ZodEffects<z.ZodObject<{
+    kind: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    file_glob: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: string;
+    label?: string | undefined;
+    detail_contains?: string[] | undefined;
+    detail_matches?: string[] | undefined;
+    file_glob?: string | undefined;
+}, {
+    kind: string;
+    label?: string | undefined;
+    detail_contains?: string[] | undefined;
+    detail_matches?: string[] | undefined;
+    file_glob?: string | undefined;
+}>, {
+    kind: string;
+    label?: string | undefined;
+    detail_contains?: string[] | undefined;
+    detail_matches?: string[] | undefined;
+    file_glob?: string | undefined;
+}, {
+    kind: string;
+    label?: string | undefined;
+    detail_contains?: string[] | undefined;
+    detail_matches?: string[] | undefined;
+    file_glob?: string | undefined;
+}>;
+/**
+ * Match composition — conditions combined with `any_of` (OR), `all_of` (AND)
+ * and/or `none_of` (negation).
+ *
+ * At least one of `any_of` or `all_of` must be present. `none_of` is an optional
+ * refinement that CANNOT stand alone: a match must positively select calls
+ * before excluding some. A pure-negation match is satisfied by every
+ * non-matching call and, at `block`, would deny everything the agent does.
+ */
+declare const MatchSchema: z.ZodEffects<z.ZodObject<{
+    any_of: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        kind: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        file_glob: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }>, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }>, "many">>;
+    all_of: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        kind: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        file_glob: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }>, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }>, "many">>;
+    none_of: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        kind: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        file_glob: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }>, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }, {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    any_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    all_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    none_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+}, {
+    any_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    all_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    none_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+}>, {
+    any_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    all_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    none_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+}, {
+    any_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    all_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+    none_of?: {
+        kind: string;
+        label?: string | undefined;
+        detail_contains?: string[] | undefined;
+        detail_matches?: string[] | undefined;
+        file_glob?: string | undefined;
+    }[] | undefined;
+}>;
+/**
+ * One fixture: a tool call this rule must match, or must not.
+ *
+ * A bare string is shorthand for `{ tool: "Bash", command: "<string>" }`, which
+ * covers most rules and keeps them terse. Anything else is an object with a
+ * `tool` plus **exactly one** of `command` or `file_path` — the two channels in
+ * spec 4.1. `.strict()` on each variant is what makes "exactly one" true: a
+ * `command` object carrying a `file_path` matches neither variant.
+ *
+ * The parse output is always normalized to the object form, so the harness has
+ * exactly one shape to feed the evaluator.
+ *
+ * ── There is no `url` channel, and that is load-bearing ──────────────────────
+ *
+ * Spec 7.2 permitted `{ tool: "WebFetch", url: … }` until 2026-09-07. It was
+ * removed (PR #532) because **the engine cannot see a URL**: the only two
+ * attribute keys any matcher reads are `detail` and `file_path`, and there is no
+ * `url` field in the condition schema. A value written to `url` is read by
+ * nothing, so a `WebFetch` rule would have matched nothing, forever, silently —
+ * exactly the failure `scope` is banned for.
+ *
+ * Aliasing the URL onto the command channel (which the paid PEP does) was
+ * rejected: it ships a channel whose rules read as commands, and the guard's
+ * honesty about its own coverage is the product. **v1 ships no website rules**,
+ * `WebFetch` is not intercepted, and the README says so rather than papering
+ * over it. `WebSearch` stays, because its query really is text on the command
+ * channel.
+ *
+ * A `url` key therefore fails to parse — it does not silently become a fixture
+ * that tests nothing. `__tests__/schema.test.ts` pins that, because someone
+ * working from a cached reading of the old spec will write exactly it.
+ */
+declare const FixtureSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, {
+    tool: "Bash";
+    command: string;
+}, string>, z.ZodObject<{
+    tool: z.ZodString;
+    command: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    tool: string;
+    command: string;
+}, {
+    tool: string;
+    command: string;
+}>, z.ZodObject<{
+    tool: z.ZodString;
+    file_path: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    tool: string;
+    file_path: string;
+}, {
+    tool: string;
+    file_path: string;
+}>]>;
+/**
+ * The two directions every rule must prove, through the real evaluator.
+ *
+ * **`block` means "this rule MUST match"; `allow` means "this rule MUST NOT
+ * match".** They are not verdicts. Five of the eight packs default to `ask` or
+ * `warn`, and `warn` folds into an allow verdict, so reading `block` as "the
+ * guard denies" would fail every `warn` rule and make the negative fixture
+ * vacuous for them.
+ *
+ * Both are `.min(1)`: the spec only requires CI to fail on a rule missing a
+ * negative fixture, but requiring it here moves that failure to authoring time,
+ * where it costs a keystroke instead of a pull-request round trip.
+ */
+declare const FixturesSchema: z.ZodObject<{
+    block: z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodString, {
+        tool: "Bash";
+        command: string;
+    }, string>, z.ZodObject<{
+        tool: z.ZodString;
+        command: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        tool: string;
+        command: string;
+    }, {
+        tool: string;
+        command: string;
+    }>, z.ZodObject<{
+        tool: z.ZodString;
+        file_path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        tool: string;
+        file_path: string;
+    }, {
+        tool: string;
+        file_path: string;
+    }>]>, "many">;
+    allow: z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodString, {
+        tool: "Bash";
+        command: string;
+    }, string>, z.ZodObject<{
+        tool: z.ZodString;
+        command: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        tool: string;
+        command: string;
+    }, {
+        tool: string;
+        command: string;
+    }>, z.ZodObject<{
+        tool: z.ZodString;
+        file_path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        tool: string;
+        file_path: string;
+    }, {
+        tool: string;
+        file_path: string;
+    }>]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    block: ({
+        tool: string;
+        command: string;
+    } | {
+        tool: string;
+        file_path: string;
+    } | {
+        tool: "Bash";
+        command: string;
+    })[];
+    allow: ({
+        tool: string;
+        command: string;
+    } | {
+        tool: string;
+        file_path: string;
+    } | {
+        tool: "Bash";
+        command: string;
+    })[];
+}, {
+    block: (string | {
+        tool: string;
+        command: string;
+    } | {
+        tool: string;
+        file_path: string;
+    })[];
+    allow: (string | {
+        tool: string;
+        command: string;
+    } | {
+        tool: string;
+        file_path: string;
+    })[];
+}>;
+/**
+ * One published rule.
+ *
+ * `minTier` and `installCount` are absent on purpose. Both are hosted-only
+ * metadata, layered on by rule id at serve time, and `installCount` is authored
+ * fiction by its own docstring — shipping invented adoption numbers in an
+ * open-source security tool becomes the story. `.strict()` turns either one into
+ * a parse error rather than a field that quietly rides along into the public
+ * package.
+ *
+ * `description` carries the rule's HONEST COVERAGE LIMITS, verbatim — e.g. that
+ * an `rm -rf` rule misses `rm -fr`. That is the difference between a credible
+ * rule set and a marketing one, and it is the first thing a technical evaluator
+ * checks. It is a convention rather than a schema constraint, because no
+ * validator can tell an honest limit from a sentence shaped like one.
+ */
+declare const RuleSchema: z.ZodObject<{
+    /** Stable forever. Never renamed — it is the join key for hosted metadata. */
+    id: z.ZodString;
+    /** The pack this rule belongs to. Validated against `PACKS` by the registry. */
+    category: z.ZodString;
+    severity: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
+    defaultAction: z.ZodEnum<["block", "require_approval", "warn"]>;
+    title: z.ZodString;
+    description: z.ZodString;
+    match: z.ZodEffects<z.ZodObject<{
+        any_of: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+            kind: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+            file_glob: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }>, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }>, "many">>;
+        all_of: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+            kind: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+            file_glob: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }>, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }>, "many">>;
+        none_of: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+            kind: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            detail_contains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            detail_matches: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+            file_glob: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }>, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }, {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        any_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        all_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        none_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+    }, {
+        any_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        all_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        none_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+    }>, {
+        any_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        all_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        none_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+    }, {
+        any_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        all_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        none_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+    }>;
+    fixtures: z.ZodObject<{
+        block: z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodString, {
+            tool: "Bash";
+            command: string;
+        }, string>, z.ZodObject<{
+            tool: z.ZodString;
+            command: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            tool: string;
+            command: string;
+        }, {
+            tool: string;
+            command: string;
+        }>, z.ZodObject<{
+            tool: z.ZodString;
+            file_path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            tool: string;
+            file_path: string;
+        }, {
+            tool: string;
+            file_path: string;
+        }>]>, "many">;
+        allow: z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodString, {
+            tool: "Bash";
+            command: string;
+        }, string>, z.ZodObject<{
+            tool: z.ZodString;
+            command: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            tool: string;
+            command: string;
+        }, {
+            tool: string;
+            command: string;
+        }>, z.ZodObject<{
+            tool: z.ZodString;
+            file_path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            tool: string;
+            file_path: string;
+        }, {
+            tool: string;
+            file_path: string;
+        }>]>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        block: ({
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        } | {
+            tool: "Bash";
+            command: string;
+        })[];
+        allow: ({
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        } | {
+            tool: "Bash";
+            command: string;
+        })[];
+    }, {
+        block: (string | {
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        })[];
+        allow: (string | {
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        })[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    category: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    defaultAction: "block" | "require_approval" | "warn";
+    title: string;
+    description: string;
+    match: {
+        any_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        all_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        none_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+    };
+    fixtures: {
+        block: ({
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        } | {
+            tool: "Bash";
+            command: string;
+        })[];
+        allow: ({
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        } | {
+            tool: "Bash";
+            command: string;
+        })[];
+    };
+}, {
+    id: string;
+    category: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    defaultAction: "block" | "require_approval" | "warn";
+    title: string;
+    description: string;
+    match: {
+        any_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        all_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+        none_of?: {
+            kind: string;
+            label?: string | undefined;
+            detail_contains?: string[] | undefined;
+            detail_matches?: string[] | undefined;
+            file_glob?: string | undefined;
+        }[] | undefined;
+    };
+    fixtures: {
+        block: (string | {
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        })[];
+        allow: (string | {
+            tool: string;
+            command: string;
+        } | {
+            tool: string;
+            file_path: string;
+        })[];
+    };
+}>;
+/** How dangerous the caught action is. Never a price. */
+type Severity = (typeof SEVERITIES)[number];
+/** What the guard does on a match. */
+type Action = (typeof ACTIONS)[number];
+/** One condition matched against a tool call. */
+type MatchCondition = z.infer<typeof MatchConditionSchema>;
+/** A composed match — `any_of` / `all_of` / `none_of`. */
+type Match = z.infer<typeof MatchSchema>;
+/** A fixture as authored: a bare command string, or a tagged single-channel object. */
+type FixtureInput = z.input<typeof FixtureSchema>;
+/** A fixture after parsing — always the tagged object form. */
+type Fixture = z.output<typeof FixtureSchema>;
+/** The must-match / must-not-match pair every rule ships. */
+type Fixtures = z.infer<typeof FixturesSchema>;
+/** One published rule, as authored. */
+type RuleInput = z.input<typeof RuleSchema>;
+/** One published rule, parsed and normalized. */
+type Rule = z.output<typeof RuleSchema>;
+/**
+ * Validate a rule from unknown input.
+ *
+ * This is the entry point a contributor gets locally. It answers "is this a
+ * well-formed rule?" — it does NOT answer "does this rule actually fire on the
+ * command you think it does." That needs the real evaluator, which lives in a
+ * private package, so it runs in our CI on the pull request. A contributor gets
+ * the schema here and the real answer there, which is where it has to run to be
+ * trusted anyway.
+ *
+ * @param input - Unknown input, e.g. parsed JSON or a rule module's default export.
+ * @returns A Zod SafeParseReturnType — check `.success` before reading `.data`.
+ */
+declare function parseRule(input: unknown): z.SafeParseReturnType<unknown, Rule>;
+/**
+ * Parse a rule, or throw with the reason.
+ *
+ * Used by rule modules themselves via {@link defineRule}, so an authoring
+ * mistake fails at import — which is to say, at test time — rather than
+ * surviving into a corpus that only validates what it remembers to check.
+ */
+declare function parseRuleOrThrow(input: unknown): Rule;
+/**
+ * Declare a rule. Validates at module load, so a malformed rule cannot reach the
+ * registry — the corpus is only as trustworthy as its weakest unvalidated entry.
+ */
+declare function defineRule(rule: RuleInput): Rule;
+
+export { ACTIONS, type Action, ActionSchema, DETAIL_MATCHES_MAX_PATTERNS, DETAIL_MATCHES_MAX_PATTERN_LENGTH, type Fixture, type FixtureInput, FixtureSchema, type Fixtures, FixturesSchema, type Match, type MatchCondition, MatchConditionSchema, MatchSchema, type Rule, type RuleInput, RuleSchema, SEVERITIES, type Severity, SeveritySchema, defineRule, hasNestedUnboundedQuantifier, parseRule, parseRuleOrThrow };