@warlock.js/ai 4.4.0 → 4.5.0

package/esm/guard/detectors/moderation.mjs

@@ -0,0 +1,134 @@
+import { OPENAI_INSTALL_INSTRUCTIONS } from "../errors.mjs";
+
+//#region ../@warlock.js/ai/src/guard/detectors/moderation.ts
+const DETECTOR_NAME = "moderation.openai";
+const DEFAULT_MODEL = "omni-moderation-latest";
+let OpenAiSdk;
+let isModuleExists;
+let loadingPromise;
+/**
+* Settle the lazy import of `openai` once, concurrency-safe. Only needed
+* when the caller did not pass a ready `client`. A bare `catch` flips the
+* flag to `false`; the curated {@link OPENAI_INSTALL_INSTRUCTIONS} surfaces
+* at first `check()`, never a raw module-resolution stack trace. Mirrors
+* ai-panoptic's `loadLangfuse`.
+*/
+function loadOpenAi() {
+	if (isModuleExists !== void 0) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			OpenAiSdk = await import("openai");
+			isModuleExists = true;
+		} catch {
+			isModuleExists = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* The optional OpenAI-backed moderation detector — the internal class behind
+* the {@link moderation} factory. Sends the inspected text to OpenAI's
+* moderation endpoint and maps the flagged categories to a verdict: any
+* category in `blockOn` → `block`; any other flagged category → `flag`;
+* nothing flagged → `allow`.
+*
+* The `openai` SDK is resolved lazily on the FIRST `check()` (not at
+* construction) so importing `@warlock.js/ai` never forces the peer to
+* be installed. When a `client` is supplied it is used verbatim and the SDK
+* is never imported.
+*/
+var OpenAiModerationDetector = class {
+	constructor(options = {}) {
+		this.name = DETECTOR_NAME;
+		this.client = options.client;
+		this.apiKey = options.apiKey;
+		this.model = options.model ?? DEFAULT_MODEL;
+		this.blockOn = new Set(options.blockOn ?? []);
+		if (!this.client) loadOpenAi();
+	}
+	/**
+	* Moderate `text` and fold the response into a verdict. `allow` when the
+	* model flags nothing; `block` when any flagged category is in `blockOn`;
+	* otherwise `flag` listing every flagged category. Resolving the client
+	* throws the curated install string when the `openai` peer is absent.
+	*/
+	async check(text) {
+		const result = (await (await this.resolveClient()).moderations.create({
+			model: this.model,
+			input: text
+		})).results[0];
+		if (result === void 0 || !result.flagged) return { type: "allow" };
+		return this.toVerdict(result);
+	}
+	/**
+	* Return the supplied client, or construct one lazily from the resolved
+	* SDK. Throws {@link OPENAI_INSTALL_INSTRUCTIONS} (a plain `Error` — a
+	* missing optional peer is an infrastructure fault, not a content
+	* violation) when `openai` could not be imported.
+	*/
+	async resolveClient() {
+		if (this.client) return this.client;
+		await loadOpenAi();
+		if (!isModuleExists) throw new Error(OPENAI_INSTALL_INSTRUCTIONS);
+		this.client = new OpenAiSdk.default({ apiKey: this.apiKey });
+		return this.client;
+	}
+	/**
+	* Fold a flagged moderation result into a `block` or `flag` verdict. Every
+	* `true` category becomes a {@link GuardrailMatch} (`moderation.<category>`);
+	* the verdict is `block` when any flagged category is in `blockOn`,
+	* otherwise `flag`.
+	*/
+	toVerdict(result) {
+		const flagged = Object.entries(result.categories).filter(([, tripped]) => tripped).map(([category]) => category);
+		const matches = flagged.map((category) => ({
+			rule: `moderation.${category}`,
+			label: category
+		}));
+		const shouldBlock = flagged.some((category) => this.blockOn.has(category));
+		const list = flagged.join(", ");
+		if (shouldBlock) return {
+			type: "block",
+			reason: `OpenAI moderation flagged blocked category(ies): ${list}.`,
+			matches
+		};
+		return {
+			type: "flag",
+			reason: `OpenAI moderation flagged category(ies): ${list}.`,
+			matches
+		};
+	}
+};
+/**
+* Build the optional `moderation` detector (surfaced as
+* `ai.guardrail.moderation(options?)`), backed by OpenAI's moderation
+* endpoint. The `openai` SDK is an **optional lazy peer**: importing
+* `@warlock.js/ai` never forces it to resolve, and the detector throws
+* a curated install string ({@link OPENAI_INSTALL_INSTRUCTIONS}) on first
+* `check()` when the peer is absent — mirroring ai-panoptic's lazy Langfuse
+* exporter.
+*
+* On a moderation hit, every flagged category becomes a
+* {@link GuardrailMatch}; the verdict is `block` when any flagged category is
+* listed in `blockOn`, otherwise `flag`. A clean result is `allow`.
+*
+* @param options - `apiKey` (defaults to `OPENAI_API_KEY`), `model`
+*   (defaults to `"omni-moderation-latest"`), `blockOn` (categories that
+*   escalate to `block`), or a pre-built `client` to bypass the lazy import.
+* @returns A {@link GuardrailDetector} for the guard's `input` / `output` / `tool` arrays.
+*
+* @example
+* const guard = ai.guardrail({
+*   output: [
+*     ai.guardrail.moderation({ blockOn: ["violence", "sexual/minors"] }),
+*   ],
+* });
+*/
+function moderation(options) {
+	return new OpenAiModerationDetector(options);
+}
+
+//#endregion
+export { moderation };
+//# sourceMappingURL=moderation.mjs.map

package/esm/guard/detectors/moderation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/moderation.ts"],"sourcesContent":["import type {\n  GuardrailDetector,\n  GuardrailMatch,\n  GuardrailVerdict,\n  OpenAiClientLike,\n  OpenAiModerationOptions,\n  OpenAiModerationResult,\n} from \"../contracts\";\nimport { OPENAI_INSTALL_INSTRUCTIONS } from \"../errors\";\n\nconst DETECTOR_NAME = \"moderation.openai\";\n\nconst DEFAULT_MODEL = \"omni-moderation-latest\";\n\n// ============================================================\n// Lazily-loaded openai SDK (OPTIONAL peer)\n// ============================================================\n\nlet OpenAiSdk: typeof import(\"openai\");\nlet isModuleExists: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\n/**\n * Settle the lazy import of `openai` once, concurrency-safe. Only needed\n * when the caller did not pass a ready `client`. A bare `catch` flips the\n * flag to `false`; the curated {@link OPENAI_INSTALL_INSTRUCTIONS} surfaces\n * at first `check()`, never a raw module-resolution stack trace. Mirrors\n * ai-panoptic's `loadLangfuse`.\n */\nfunction loadOpenAi(): Promise<void> {\n  if (isModuleExists !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      OpenAiSdk = await import(\"openai\");\n      isModuleExists = true;\n    } catch {\n      isModuleExists = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * The optional OpenAI-backed moderation detector — the internal class behind\n * the {@link moderation} factory. Sends the inspected text to OpenAI's\n * moderation endpoint and maps the flagged categories to a verdict: any\n * category in `blockOn` → `block`; any other flagged category → `flag`;\n * nothing flagged → `allow`.\n *\n * The `openai` SDK is resolved lazily on the FIRST `check()` (not at\n * construction) so importing `@warlock.js/ai` never forces the peer to\n * be installed. When a `client` is supplied it is used verbatim and the SDK\n * is never imported.\n */\nclass OpenAiModerationDetector implements GuardrailDetector {\n  public readonly name = DETECTOR_NAME;\n\n  /** A pre-built client, or `undefined` until the lazy SDK constructs one. */\n  private client: OpenAiClientLike | undefined;\n\n  private readonly apiKey: string | undefined;\n\n  private readonly model: string;\n\n  /** Categories that escalate to `block`; empty means \"flag on any\". */\n  private readonly blockOn: ReadonlySet<string>;\n\n  public constructor(options: OpenAiModerationOptions = {}) {\n    this.client = options.client;\n    this.apiKey = options.apiKey;\n    this.model = options.model ?? DEFAULT_MODEL;\n    this.blockOn = new Set(options.blockOn ?? []);\n\n    // Kick off the lazy import eagerly when no client was supplied, so the\n    // first `check()` does not pay the resolution latency. Errors are\n    // swallowed by `loadOpenAi`; the curated install string surfaces at use.\n    if (!this.client) {\n      loadOpenAi();\n    }\n  }\n\n  /**\n   * Moderate `text` and fold the response into a verdict. `allow` when the\n   * model flags nothing; `block` when any flagged category is in `blockOn`;\n   * otherwise `flag` listing every flagged category. Resolving the client\n   * throws the curated install string when the `openai` peer is absent.\n   */\n  public async check(text: string): Promise<GuardrailVerdict> {\n    const client = await this.resolveClient();\n\n    const response = await client.moderations.create({\n      model: this.model,\n      input: text,\n    });\n\n    const result = response.results[0];\n\n    if (result === undefined || !result.flagged) {\n      return { type: \"allow\" };\n    }\n\n    return this.toVerdict(result);\n  }\n\n  /**\n   * Return the supplied client, or construct one lazily from the resolved\n   * SDK. Throws {@link OPENAI_INSTALL_INSTRUCTIONS} (a plain `Error` — a\n   * missing optional peer is an infrastructure fault, not a content\n   * violation) when `openai` could not be imported.\n   */\n  private async resolveClient(): Promise<OpenAiClientLike> {\n    if (this.client) {\n      return this.client;\n    }\n\n    await loadOpenAi();\n\n    if (!isModuleExists) {\n      throw new Error(OPENAI_INSTALL_INSTRUCTIONS);\n    }\n\n    this.client = new OpenAiSdk.default({\n      apiKey: this.apiKey,\n    }) as unknown as OpenAiClientLike;\n\n    return this.client;\n  }\n\n  /**\n   * Fold a flagged moderation result into a `block` or `flag` verdict. Every\n   * `true` category becomes a {@link GuardrailMatch} (`moderation.<category>`);\n   * the verdict is `block` when any flagged category is in `blockOn`,\n   * otherwise `flag`.\n   */\n  private toVerdict(result: OpenAiModerationResult): GuardrailVerdict {\n    const flagged = Object.entries(result.categories)\n      .filter(([, tripped]) => tripped)\n      .map(([category]) => category);\n\n    const matches: GuardrailMatch[] = flagged.map((category) => ({\n      rule: `moderation.${category}`,\n      label: category,\n    }));\n\n    const shouldBlock = flagged.some((category) => this.blockOn.has(category));\n    const list = flagged.join(\", \");\n\n    if (shouldBlock) {\n      return {\n        type: \"block\",\n        reason: `OpenAI moderation flagged blocked category(ies): ${list}.`,\n        matches,\n      };\n    }\n\n    return {\n      type: \"flag\",\n      reason: `OpenAI moderation flagged category(ies): ${list}.`,\n      matches,\n    };\n  }\n}\n\n/**\n * Build the optional `moderation` detector (surfaced as\n * `ai.guardrail.moderation(options?)`), backed by OpenAI's moderation\n * endpoint. The `openai` SDK is an **optional lazy peer**: importing\n * `@warlock.js/ai` never forces it to resolve, and the detector throws\n * a curated install string ({@link OPENAI_INSTALL_INSTRUCTIONS}) on first\n * `check()` when the peer is absent — mirroring ai-panoptic's lazy Langfuse\n * exporter.\n *\n * On a moderation hit, every flagged category becomes a\n * {@link GuardrailMatch}; the verdict is `block` when any flagged category is\n * listed in `blockOn`, otherwise `flag`. A clean result is `allow`.\n *\n * @param options - `apiKey` (defaults to `OPENAI_API_KEY`), `model`\n *   (defaults to `\"omni-moderation-latest\"`), `blockOn` (categories that\n *   escalate to `block`), or a pre-built `client` to bypass the lazy import.\n * @returns A {@link GuardrailDetector} for the guard's `input` / `output` / `tool` arrays.\n *\n * @example\n * const guard = ai.guardrail({\n *   output: [\n *     ai.guardrail.moderation({ blockOn: [\"violence\", \"sexual/minors\"] }),\n *   ],\n * });\n */\nexport function moderation(\n  options?: OpenAiModerationOptions,\n): GuardrailDetector {\n  return new OpenAiModerationDetector(options);\n}\n"],"mappings":";;;AAUA,MAAM,gBAAgB;AAEtB,MAAM,gBAAgB;AAMtB,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,SAAS,aAA4B;CACnC,IAAI,mBAAmB,QACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GACF,YAAY,MAAM,OAAO;GACzB,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;;;;;;;;AAcA,IAAM,2BAAN,MAA4D;CAa1D,AAAO,YAAY,UAAmC,CAAC,GAAG;cAZnC;EAarB,KAAK,SAAS,QAAQ;EACtB,KAAK,SAAS,QAAQ;EACtB,KAAK,QAAQ,QAAQ,SAAS;EAC9B,KAAK,UAAU,IAAI,IAAI,QAAQ,WAAW,CAAC,CAAC;EAK5C,IAAI,CAAC,KAAK,QACR,WAAW;CAEf;;;;;;;CAQA,MAAa,MAAM,MAAyC;EAQ1D,MAAM,UAAS,OALQ,MAFF,KAAK,cAAc,EAEX,CAAC,YAAY,OAAO;GAC/C,OAAO,KAAK;GACZ,OAAO;EACT,CAAC,EAEsB,CAAC,QAAQ;EAEhC,IAAI,WAAW,UAAa,CAAC,OAAO,SAClC,OAAO,EAAE,MAAM,QAAQ;EAGzB,OAAO,KAAK,UAAU,MAAM;CAC9B;;;;;;;CAQA,MAAc,gBAA2C;EACvD,IAAI,KAAK,QACP,OAAO,KAAK;EAGd,MAAM,WAAW;EAEjB,IAAI,CAAC,gBACH,MAAM,IAAI,MAAM,2BAA2B;EAG7C,KAAK,SAAS,IAAI,UAAU,QAAQ,EAClC,QAAQ,KAAK,OACf,CAAC;EAED,OAAO,KAAK;CACd;;;;;;;CAQA,AAAQ,UAAU,QAAkD;EAClE,MAAM,UAAU,OAAO,QAAQ,OAAO,UAAU,CAAC,CAC9C,QAAQ,GAAG,aAAa,OAAO,CAAC,CAChC,KAAK,CAAC,cAAc,QAAQ;EAE/B,MAAM,UAA4B,QAAQ,KAAK,cAAc;GAC3D,MAAM,cAAc;GACpB,OAAO;EACT,EAAE;EAEF,MAAM,cAAc,QAAQ,MAAM,aAAa,KAAK,QAAQ,IAAI,QAAQ,CAAC;EACzE,MAAM,OAAO,QAAQ,KAAK,IAAI;EAE9B,IAAI,aACF,OAAO;GACL,MAAM;GACN,QAAQ,oDAAoD,KAAK;GACjE;EACF;EAGF,OAAO;GACL,MAAM;GACN,QAAQ,4CAA4C,KAAK;GACzD;EACF;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,WACd,SACmB;CACnB,OAAO,IAAI,yBAAyB,OAAO;AAC7C"}

package/esm/guard/detectors/pii.d.mts

@@ -0,0 +1,41 @@
+import { SyncGuardrailDetector } from "../contracts/guardrail.contract.mjs";
+import { PiiDetectorOptions } from "../contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/detectors/pii.d.ts
+/**
+ * Build the built-in **PII detector** (`ai.guardrail.pii`) — a zero-runtime-
+ * dependency {@link GuardrailDetector} that scans text for personally
+ * identifiable information via a curated set of linear regexes plus an
+ * optional exact-string dictionary.
+ *
+ * Categories (`detect`, default: all): `ssn`, `email`, `phone`,
+ * `credit-card`, `ipv4`. `dictionary` adds extra exact terms matched
+ * case-insensitively as literal strings (regex metacharacters escaped).
+ *
+ * On a hit the verdict follows `onMatch` (default `"redact"`):
+ *
+ * - **`redact`** — every matched span is replaced by the `mask` template
+ *   (`{label}` → the matched category, default `"[REDACTED]"`) and the
+ *   rewritten text is returned for the factory to substitute. Output and
+ *   tool phases honour the rewrite; on the input phase the factory treats a
+ *   `redact` verdict as a `block` (the core `trip.before` hook can only
+ *   short-circuit, not rewrite-and-continue — see {@link PiiDetectorOptions}).
+ * - **`block`** — a hard stop carrying the matches.
+ * - **`flag`**  — the content passes but the matches are recorded.
+ *
+ * Clean text returns `{ type: "allow" }`.
+ *
+ * @example
+ * ai.guardrail({ output: [ai.guardrail.pii()] }); // redact, default mask
+ *
+ * @example
+ * ai.guardrail.pii({
+ *   detect: ["ssn", "credit-card"],
+ *   onMatch: "redact",
+ *   mask: "[PII:{label}]",
+ *   dictionary: ["Project Aurora"],
+ * });
+ */
+declare function pii(options?: PiiDetectorOptions): SyncGuardrailDetector;
+//#endregion
+export { pii };
+//# sourceMappingURL=pii.d.mts.map

package/esm/guard/detectors/pii.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/pii.ts"],"mappings":";;;;;;;AAqOA;;;;;;;;AAA4E;;;;;;;;;;;;;;;;;;;;;;iBAA5D,GAAA,CAAI,OAAA,GAAS,kBAAA,GAA0B,qBAAqB"}

package/esm/guard/detectors/pii.mjs

@@ -0,0 +1,199 @@
+//#region ../@warlock.js/ai/src/guard/detectors/pii.ts
+/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
+const DETECTOR_NAME = "pii";
+/** Placeholder substituted for a matched span when the caller supplies no `mask`. */
+const DEFAULT_MASK = "[REDACTED]";
+/**
+* The built-in PII category regexes. Each is linear (anchored alternations,
+* no nested quantifiers) so it is safe against catastrophic backtracking on
+* adversarial input. All carry the global flag so a single pass over the
+* text yields every occurrence; `lastIndex` is reset per use so a shared
+* instance never leaks state across calls.
+*
+* - `ssn`         — US Social Security number, `123-45-6789` / `123 45 6789`.
+* - `email`       — a pragmatic address shape, not full RFC 5322.
+* - `phone`       — North-American style, optional `+1`, separators, parens.
+* - `credit-card` — 13–16 digit runs, optional space / hyphen grouping.
+* - `ipv4`        — four dotted octets (loosely; out-of-range octets still match).
+*/
+const CATEGORY_PATTERNS = {
+	ssn: /\b\d{3}[-\s]\d{2}[-\s]\d{4}\b/g,
+	email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+	phone: /(?:\+?1[-.\s]?)?(?:\(\d{3}\)|\d{3})[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+	"credit-card": /\b(?:\d[ -]?){13,16}\b/g,
+	ipv4: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g
+};
+/** Every built-in category, in a stable scan order. */
+const ALL_CATEGORIES = [
+	"ssn",
+	"email",
+	"phone",
+	"credit-card",
+	"ipv4"
+];
+/**
+* Escape a string for safe interpolation into a `RegExp` source, so an
+* extra dictionary term containing regex metacharacters (`.`, `+`, `(`, …)
+* matches literally rather than as a pattern.
+*/
+function escapeRegExp(term) {
+	return term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Build the `{label}` mask for a hit. The template's `{label}` token is
+* substituted with the hit's category; a template without the token is used
+* verbatim. Falls back to {@link DEFAULT_MASK} when no template is given.
+*/
+function applyMask(template, label) {
+	if (template === void 0) return DEFAULT_MASK;
+	return template.replace(/\{label\}/g, label);
+}
+/**
+* Collect every built-in-category hit in `text` for the requested
+* categories, in document order per category.
+*/
+function scanCategories(text, categories) {
+	const hits = [];
+	for (const category of categories) {
+		const pattern = CATEGORY_PATTERNS[category];
+		pattern.lastIndex = 0;
+		let match = pattern.exec(text);
+		while (match !== null) {
+			hits.push({
+				label: category,
+				start: match.index,
+				end: match.index + match[0].length - 1
+			});
+			if (match[0].length === 0) pattern.lastIndex += 1;
+			match = pattern.exec(text);
+		}
+	}
+	return hits;
+}
+/**
+* Collect every occurrence of each extra dictionary term in `text`,
+* case-insensitively, as `"dictionary"`-labelled hits.
+*/
+function scanDictionary(text, dictionary) {
+	const hits = [];
+	for (const term of dictionary) {
+		if (term.length === 0) continue;
+		const pattern = new RegExp(escapeRegExp(term), "gi");
+		let match = pattern.exec(text);
+		while (match !== null) {
+			hits.push({
+				label: "dictionary",
+				start: match.index,
+				end: match.index + match[0].length - 1
+			});
+			match = pattern.exec(text);
+		}
+	}
+	return hits;
+}
+/**
+* Sort hits by start offset, then drop any hit fully contained in (or
+* duplicating) an already-kept span. Different category regexes can overlap
+* on the same characters (e.g. a credit-card run inside a phone-shaped
+* span); keeping the earliest, widest span makes redaction deterministic
+* and avoids masking a sub-span twice.
+*/
+function dedupeHits(hits) {
+	const sorted = [...hits].sort((a, b) => {
+		if (a.start !== b.start) return a.start - b.start;
+		return b.end - a.end;
+	});
+	const kept = [];
+	for (const hit of sorted) if (!kept.some((existing) => hit.start <= existing.end && hit.end >= existing.start)) kept.push(hit);
+	return kept;
+}
+/**
+* Rewrite `text`, replacing every kept hit's span with its mask. Applied
+* right-to-left so earlier offsets stay valid as later spans are spliced.
+*/
+function redactText(text, hits, mask) {
+	const ordered = [...hits].sort((a, b) => b.start - a.start);
+	let result = text;
+	for (const hit of ordered) {
+		const replacement = applyMask(mask, hit.label);
+		result = result.slice(0, hit.start) + replacement + result.slice(hit.end + 1);
+	}
+	return result;
+}
+/** Fold a {@link RawHit} into the public {@link GuardrailMatch} shape. */
+function toMatch(hit) {
+	return {
+		rule: `${DETECTOR_NAME}.${hit.label}`,
+		span: [hit.start, hit.end],
+		label: hit.label
+	};
+}
+/**
+* Build the built-in **PII detector** (`ai.guardrail.pii`) — a zero-runtime-
+* dependency {@link GuardrailDetector} that scans text for personally
+* identifiable information via a curated set of linear regexes plus an
+* optional exact-string dictionary.
+*
+* Categories (`detect`, default: all): `ssn`, `email`, `phone`,
+* `credit-card`, `ipv4`. `dictionary` adds extra exact terms matched
+* case-insensitively as literal strings (regex metacharacters escaped).
+*
+* On a hit the verdict follows `onMatch` (default `"redact"`):
+*
+* - **`redact`** — every matched span is replaced by the `mask` template
+*   (`{label}` → the matched category, default `"[REDACTED]"`) and the
+*   rewritten text is returned for the factory to substitute. Output and
+*   tool phases honour the rewrite; on the input phase the factory treats a
+*   `redact` verdict as a `block` (the core `trip.before` hook can only
+*   short-circuit, not rewrite-and-continue — see {@link PiiDetectorOptions}).
+* - **`block`** — a hard stop carrying the matches.
+* - **`flag`**  — the content passes but the matches are recorded.
+*
+* Clean text returns `{ type: "allow" }`.
+*
+* @example
+* ai.guardrail({ output: [ai.guardrail.pii()] }); // redact, default mask
+*
+* @example
+* ai.guardrail.pii({
+*   detect: ["ssn", "credit-card"],
+*   onMatch: "redact",
+*   mask: "[PII:{label}]",
+*   dictionary: ["Project Aurora"],
+* });
+*/
+function pii(options = {}) {
+	const categories = options.detect ?? ALL_CATEGORIES;
+	const onMatch = options.onMatch ?? "redact";
+	const dictionary = options.dictionary ?? [];
+	return {
+		name: DETECTOR_NAME,
+		check(text) {
+			const rawHits = [...scanCategories(text, categories), ...scanDictionary(text, dictionary)];
+			if (rawHits.length === 0) return { type: "allow" };
+			const hits = dedupeHits(rawHits);
+			const matches = hits.map(toMatch);
+			const labels = [...new Set(hits.map((hit) => hit.label))].join(", ");
+			if (onMatch === "block") return {
+				type: "block",
+				reason: `PII detected: ${labels}.`,
+				matches
+			};
+			if (onMatch === "flag") return {
+				type: "flag",
+				reason: `PII detected: ${labels}.`,
+				matches
+			};
+			return {
+				type: "redact",
+				text: redactText(text, hits, options.mask),
+				reason: `Redacted PII: ${labels}.`,
+				matches
+			};
+		}
+	};
+}
+
+//#endregion
+export { pii };
+//# sourceMappingURL=pii.mjs.map

package/esm/guard/detectors/pii.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/pii.ts"],"sourcesContent":["import type {\n  GuardrailMatch,\n  GuardrailVerdict,\n  PiiCategory,\n  PiiDetectorOptions,\n  SyncGuardrailDetector,\n} from \"../contracts\";\n\n/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */\nconst DETECTOR_NAME = \"pii\";\n\n/** Placeholder substituted for a matched span when the caller supplies no `mask`. */\nconst DEFAULT_MASK = \"[REDACTED]\";\n\n/**\n * The built-in PII category regexes. Each is linear (anchored alternations,\n * no nested quantifiers) so it is safe against catastrophic backtracking on\n * adversarial input. All carry the global flag so a single pass over the\n * text yields every occurrence; `lastIndex` is reset per use so a shared\n * instance never leaks state across calls.\n *\n * - `ssn`         — US Social Security number, `123-45-6789` / `123 45 6789`.\n * - `email`       — a pragmatic address shape, not full RFC 5322.\n * - `phone`       — North-American style, optional `+1`, separators, parens.\n * - `credit-card` — 13–16 digit runs, optional space / hyphen grouping.\n * - `ipv4`        — four dotted octets (loosely; out-of-range octets still match).\n */\nconst CATEGORY_PATTERNS: Record<PiiCategory, RegExp> = {\n  ssn: /\\b\\d{3}[-\\s]\\d{2}[-\\s]\\d{4}\\b/g,\n  email: /\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b/g,\n  phone: /(?:\\+?1[-.\\s]?)?(?:\\(\\d{3}\\)|\\d{3})[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b/g,\n  \"credit-card\": /\\b(?:\\d[ -]?){13,16}\\b/g,\n  ipv4: /\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\b/g,\n};\n\n/** Every built-in category, in a stable scan order. */\nconst ALL_CATEGORIES: readonly PiiCategory[] = [\n  \"ssn\",\n  \"email\",\n  \"phone\",\n  \"credit-card\",\n  \"ipv4\",\n];\n\n/**\n * A raw hit located inside the inspected text, before it is folded into a\n * {@link GuardrailMatch}. `label` is the category (built-in) or\n * `\"dictionary\"` (an extra term); `start` / `end` are inclusive offsets.\n */\ninterface RawHit {\n  readonly label: string;\n  readonly start: number;\n  readonly end: number;\n}\n\n/**\n * Escape a string for safe interpolation into a `RegExp` source, so an\n * extra dictionary term containing regex metacharacters (`.`, `+`, `(`, …)\n * matches literally rather than as a pattern.\n */\nfunction escapeRegExp(term: string): string {\n  return term.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\n/**\n * Build the `{label}` mask for a hit. The template's `{label}` token is\n * substituted with the hit's category; a template without the token is used\n * verbatim. Falls back to {@link DEFAULT_MASK} when no template is given.\n */\nfunction applyMask(template: string | undefined, label: string): string {\n  if (template === undefined) {\n    return DEFAULT_MASK;\n  }\n\n  return template.replace(/\\{label\\}/g, label);\n}\n\n/**\n * Collect every built-in-category hit in `text` for the requested\n * categories, in document order per category.\n */\nfunction scanCategories(text: string, categories: readonly PiiCategory[]): RawHit[] {\n  const hits: RawHit[] = [];\n\n  for (const category of categories) {\n    const pattern = CATEGORY_PATTERNS[category];\n    pattern.lastIndex = 0;\n\n    let match = pattern.exec(text);\n\n    while (match !== null) {\n      hits.push({\n        label: category,\n        start: match.index,\n        end: match.index + match[0].length - 1,\n      });\n\n      // Guard the zero-length-match case so `exec` can never spin forever.\n      if (match[0].length === 0) {\n        pattern.lastIndex += 1;\n      }\n\n      match = pattern.exec(text);\n    }\n  }\n\n  return hits;\n}\n\n/**\n * Collect every occurrence of each extra dictionary term in `text`,\n * case-insensitively, as `\"dictionary\"`-labelled hits.\n */\nfunction scanDictionary(text: string, dictionary: readonly string[]): RawHit[] {\n  const hits: RawHit[] = [];\n\n  for (const term of dictionary) {\n    if (term.length === 0) {\n      continue;\n    }\n\n    const pattern = new RegExp(escapeRegExp(term), \"gi\");\n    let match = pattern.exec(text);\n\n    while (match !== null) {\n      hits.push({\n        label: \"dictionary\",\n        start: match.index,\n        end: match.index + match[0].length - 1,\n      });\n\n      match = pattern.exec(text);\n    }\n  }\n\n  return hits;\n}\n\n/**\n * Sort hits by start offset, then drop any hit fully contained in (or\n * duplicating) an already-kept span. Different category regexes can overlap\n * on the same characters (e.g. a credit-card run inside a phone-shaped\n * span); keeping the earliest, widest span makes redaction deterministic\n * and avoids masking a sub-span twice.\n */\nfunction dedupeHits(hits: RawHit[]): RawHit[] {\n  const sorted = [...hits].sort((a, b) => {\n    if (a.start !== b.start) {\n      return a.start - b.start;\n    }\n\n    // Same start: keep the wider span first so the narrower one is absorbed.\n    return b.end - a.end;\n  });\n\n  const kept: RawHit[] = [];\n\n  for (const hit of sorted) {\n    const overlaps = kept.some(\n      existing => hit.start <= existing.end && hit.end >= existing.start,\n    );\n\n    if (!overlaps) {\n      kept.push(hit);\n    }\n  }\n\n  return kept;\n}\n\n/**\n * Rewrite `text`, replacing every kept hit's span with its mask. Applied\n * right-to-left so earlier offsets stay valid as later spans are spliced.\n */\nfunction redactText(text: string, hits: RawHit[], mask: string | undefined): string {\n  const ordered = [...hits].sort((a, b) => b.start - a.start);\n  let result = text;\n\n  for (const hit of ordered) {\n    const replacement = applyMask(mask, hit.label);\n    result = result.slice(0, hit.start) + replacement + result.slice(hit.end + 1);\n  }\n\n  return result;\n}\n\n/** Fold a {@link RawHit} into the public {@link GuardrailMatch} shape. */\nfunction toMatch(hit: RawHit): GuardrailMatch {\n  return {\n    rule: `${DETECTOR_NAME}.${hit.label}`,\n    span: [hit.start, hit.end],\n    label: hit.label,\n  };\n}\n\n/**\n * Build the built-in **PII detector** (`ai.guardrail.pii`) — a zero-runtime-\n * dependency {@link GuardrailDetector} that scans text for personally\n * identifiable information via a curated set of linear regexes plus an\n * optional exact-string dictionary.\n *\n * Categories (`detect`, default: all): `ssn`, `email`, `phone`,\n * `credit-card`, `ipv4`. `dictionary` adds extra exact terms matched\n * case-insensitively as literal strings (regex metacharacters escaped).\n *\n * On a hit the verdict follows `onMatch` (default `\"redact\"`):\n *\n * - **`redact`** — every matched span is replaced by the `mask` template\n *   (`{label}` → the matched category, default `\"[REDACTED]\"`) and the\n *   rewritten text is returned for the factory to substitute. Output and\n *   tool phases honour the rewrite; on the input phase the factory treats a\n *   `redact` verdict as a `block` (the core `trip.before` hook can only\n *   short-circuit, not rewrite-and-continue — see {@link PiiDetectorOptions}).\n * - **`block`** — a hard stop carrying the matches.\n * - **`flag`**  — the content passes but the matches are recorded.\n *\n * Clean text returns `{ type: \"allow\" }`.\n *\n * @example\n * ai.guardrail({ output: [ai.guardrail.pii()] }); // redact, default mask\n *\n * @example\n * ai.guardrail.pii({\n *   detect: [\"ssn\", \"credit-card\"],\n *   onMatch: \"redact\",\n *   mask: \"[PII:{label}]\",\n *   dictionary: [\"Project Aurora\"],\n * });\n */\nexport function pii(options: PiiDetectorOptions = {}): SyncGuardrailDetector {\n  const categories = options.detect ?? ALL_CATEGORIES;\n  const onMatch = options.onMatch ?? \"redact\";\n  const dictionary = options.dictionary ?? [];\n\n  return {\n    name: DETECTOR_NAME,\n    check(text: string): GuardrailVerdict {\n      const rawHits = [\n        ...scanCategories(text, categories),\n        ...scanDictionary(text, dictionary),\n      ];\n\n      if (rawHits.length === 0) {\n        return { type: \"allow\" };\n      }\n\n      const hits = dedupeHits(rawHits);\n      const matches = hits.map(toMatch);\n      const labels = [...new Set(hits.map(hit => hit.label))].join(\", \");\n\n      if (onMatch === \"block\") {\n        return {\n          type: \"block\",\n          reason: `PII detected: ${labels}.`,\n          matches,\n        };\n      }\n\n      if (onMatch === \"flag\") {\n        return {\n          type: \"flag\",\n          reason: `PII detected: ${labels}.`,\n          matches,\n        };\n      }\n\n      return {\n        type: \"redact\",\n        text: redactText(text, hits, options.mask),\n        reason: `Redacted PII: ${labels}.`,\n        matches,\n      };\n    },\n  };\n}\n"],"mappings":";;AASA,MAAM,gBAAgB;;AAGtB,MAAM,eAAe;;;;;;;;;;;;;;AAerB,MAAM,oBAAiD;CACrD,KAAK;CACL,OAAO;CACP,OAAO;CACP,eAAe;CACf,MAAM;AACR;;AAGA,MAAM,iBAAyC;CAC7C;CACA;CACA;CACA;CACA;AACF;;;;;;AAkBA,SAAS,aAAa,MAAsB;CAC1C,OAAO,KAAK,QAAQ,uBAAuB,MAAM;AACnD;;;;;;AAOA,SAAS,UAAU,UAA8B,OAAuB;CACtE,IAAI,aAAa,QACf,OAAO;CAGT,OAAO,SAAS,QAAQ,cAAc,KAAK;AAC7C;;;;;AAMA,SAAS,eAAe,MAAc,YAA8C;CAClF,MAAM,OAAiB,CAAC;CAExB,KAAK,MAAM,YAAY,YAAY;EACjC,MAAM,UAAU,kBAAkB;EAClC,QAAQ,YAAY;EAEpB,IAAI,QAAQ,QAAQ,KAAK,IAAI;EAE7B,OAAO,UAAU,MAAM;GACrB,KAAK,KAAK;IACR,OAAO;IACP,OAAO,MAAM;IACb,KAAK,MAAM,QAAQ,MAAM,EAAE,CAAC,SAAS;GACvC,CAAC;GAGD,IAAI,MAAM,EAAE,CAAC,WAAW,GACtB,QAAQ,aAAa;GAGvB,QAAQ,QAAQ,KAAK,IAAI;EAC3B;CACF;CAEA,OAAO;AACT;;;;;AAMA,SAAS,eAAe,MAAc,YAAyC;CAC7E,MAAM,OAAiB,CAAC;CAExB,KAAK,MAAM,QAAQ,YAAY;EAC7B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,UAAU,IAAI,OAAO,aAAa,IAAI,GAAG,IAAI;EACnD,IAAI,QAAQ,QAAQ,KAAK,IAAI;EAE7B,OAAO,UAAU,MAAM;GACrB,KAAK,KAAK;IACR,OAAO;IACP,OAAO,MAAM;IACb,KAAK,MAAM,QAAQ,MAAM,EAAE,CAAC,SAAS;GACvC,CAAC;GAED,QAAQ,QAAQ,KAAK,IAAI;EAC3B;CACF;CAEA,OAAO;AACT;;;;;;;;AASA,SAAS,WAAW,MAA0B;CAC5C,MAAM,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,GAAG,MAAM;EACtC,IAAI,EAAE,UAAU,EAAE,OAChB,OAAO,EAAE,QAAQ,EAAE;EAIrB,OAAO,EAAE,MAAM,EAAE;CACnB,CAAC;CAED,MAAM,OAAiB,CAAC;CAExB,KAAK,MAAM,OAAO,QAKhB,IAAI,CAJa,KAAK,MACpB,aAAY,IAAI,SAAS,SAAS,OAAO,IAAI,OAAO,SAAS,KAGnD,GACV,KAAK,KAAK,GAAG;CAIjB,OAAO;AACT;;;;;AAMA,SAAS,WAAW,MAAc,MAAgB,MAAkC;CAClF,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;CAC1D,IAAI,SAAS;CAEb,KAAK,MAAM,OAAO,SAAS;EACzB,MAAM,cAAc,UAAU,MAAM,IAAI,KAAK;EAC7C,SAAS,OAAO,MAAM,GAAG,IAAI,KAAK,IAAI,cAAc,OAAO,MAAM,IAAI,MAAM,CAAC;CAC9E;CAEA,OAAO;AACT;;AAGA,SAAS,QAAQ,KAA6B;CAC5C,OAAO;EACL,MAAM,GAAG,cAAc,GAAG,IAAI;EAC9B,MAAM,CAAC,IAAI,OAAO,IAAI,GAAG;EACzB,OAAO,IAAI;CACb;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,IAAI,UAA8B,CAAC,GAA0B;CAC3E,MAAM,aAAa,QAAQ,UAAU;CACrC,MAAM,UAAU,QAAQ,WAAW;CACnC,MAAM,aAAa,QAAQ,cAAc,CAAC;CAE1C,OAAO;EACL,MAAM;EACN,MAAM,MAAgC;GACpC,MAAM,UAAU,CACd,GAAG,eAAe,MAAM,UAAU,GAClC,GAAG,eAAe,MAAM,UAAU,CACpC;GAEA,IAAI,QAAQ,WAAW,GACrB,OAAO,EAAE,MAAM,QAAQ;GAGzB,MAAM,OAAO,WAAW,OAAO;GAC/B,MAAM,UAAU,KAAK,IAAI,OAAO;GAChC,MAAM,SAAS,CAAC,GAAG,IAAI,IAAI,KAAK,KAAI,QAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;GAEjE,IAAI,YAAY,SACd,OAAO;IACL,MAAM;IACN,QAAQ,iBAAiB,OAAO;IAChC;GACF;GAGF,IAAI,YAAY,QACd,OAAO;IACL,MAAM;IACN,QAAQ,iBAAiB,OAAO;IAChC;GACF;GAGF,OAAO;IACL,MAAM;IACN,MAAM,WAAW,MAAM,MAAM,QAAQ,IAAI;IACzC,QAAQ,iBAAiB,OAAO;IAChC;GACF;EACF;CACF;AACF"}

package/esm/guard/detectors/topic.d.mts

@@ -0,0 +1,29 @@
+import { SyncGuardrailDetector } from "../contracts/guardrail.contract.mjs";
+import { TopicFilterOptions } from "../contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/detectors/topic.d.ts
+/**
+ * Build the built-in **topic filter** (`ai.guardrail.topic`) — a
+ * zero-runtime-dependency {@link GuardrailDetector} that gates text against a
+ * deny list, an allow list, or both.
+ *
+ * - **`deny`** — any term that appears triggers `onMatch`. A `string`
+ *   matches case-insensitively as a substring; a `RegExp` is tested as-is.
+ *   The deny list is checked first; the first hit decides the verdict.
+ * - **`allow`** — when set, text matching **none** of the allow terms
+ *   triggers `onMatch` (an allow-list miss). Text matching at least one
+ *   allow term passes the allow gate.
+ *
+ * `onMatch` is `"block"` (default) or `"flag"`. With neither list supplied
+ * the detector is a no-op that always allows.
+ *
+ * @example
+ * ai.guardrail.topic({ deny: ["medical advice", /diagnos\w+/i] });
+ *
+ * @example
+ * // Stay on-topic: anything not about billing is flagged.
+ * ai.guardrail.topic({ allow: ["billing", "invoice", "refund"], onMatch: "flag" });
+ */
+declare function topic(options: TopicFilterOptions): SyncGuardrailDetector;
+//#endregion
+export { topic };
+//# sourceMappingURL=topic.d.mts.map

package/esm/guard/detectors/topic.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/topic.ts"],"mappings":";;;;;;;AAsEA;;;;;;;;AAAyE;;;;;;;;;;iBAAzD,KAAA,CAAM,OAAA,EAAS,kBAAA,GAAqB,qBAAqB"}

package/esm/guard/detectors/topic.mjs

@@ -0,0 +1,99 @@
+//#region ../@warlock.js/ai/src/guard/detectors/topic.ts
+/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
+const DETECTOR_NAME = "topic";
+/**
+* Locate the first occurrence of `term` in `text`. A `string` matches
+* case-insensitively as a substring; a `RegExp` is tested as-is (its own
+* flags decide case-sensitivity). Returns the inclusive `[start, end]`
+* span on a hit, or `undefined` when the term is absent.
+*/
+function locate(text, term) {
+	if (typeof term === "string") {
+		if (term.length === 0) return;
+		const index = text.toLowerCase().indexOf(term.toLowerCase());
+		if (index === -1) return;
+		return [index, index + term.length - 1];
+	}
+	const match = new RegExp(term.source, term.flags.replace(/[gy]/g, "")).exec(text);
+	if (match === null) return;
+	return [match.index, match.index + match[0].length - 1];
+}
+/** A human-readable label for a deny/allow term, used in the match rule + reason. */
+function describeTerm(term) {
+	return typeof term === "string" ? term : term.source;
+}
+/**
+* Build the built-in **topic filter** (`ai.guardrail.topic`) — a
+* zero-runtime-dependency {@link GuardrailDetector} that gates text against a
+* deny list, an allow list, or both.
+*
+* - **`deny`** — any term that appears triggers `onMatch`. A `string`
+*   matches case-insensitively as a substring; a `RegExp` is tested as-is.
+*   The deny list is checked first; the first hit decides the verdict.
+* - **`allow`** — when set, text matching **none** of the allow terms
+*   triggers `onMatch` (an allow-list miss). Text matching at least one
+*   allow term passes the allow gate.
+*
+* `onMatch` is `"block"` (default) or `"flag"`. With neither list supplied
+* the detector is a no-op that always allows.
+*
+* @example
+* ai.guardrail.topic({ deny: ["medical advice", /diagnos\w+/i] });
+*
+* @example
+* // Stay on-topic: anything not about billing is flagged.
+* ai.guardrail.topic({ allow: ["billing", "invoice", "refund"], onMatch: "flag" });
+*/
+function topic(options) {
+	const deny = options.deny ?? [];
+	const allow = options.allow ?? [];
+	const onMatch = options.onMatch ?? "block";
+	return {
+		name: DETECTOR_NAME,
+		check(text) {
+			for (const term of deny) {
+				const span = locate(text, term);
+				if (span !== void 0) {
+					const label = describeTerm(term);
+					const match = {
+						rule: `${DETECTOR_NAME}.deny.${label}`,
+						span,
+						label
+					};
+					return verdict(onMatch, options.reason ?? `Denied topic matched: ${label}.`, [match]);
+				}
+			}
+			if (allow.length > 0) {
+				if (!allow.some((term) => locate(text, term) !== void 0)) {
+					const match = {
+						rule: `${DETECTOR_NAME}.allow.miss`,
+						label: "allow-miss"
+					};
+					return verdict(onMatch, options.reason ?? "Text matched none of the allowed topics.", [match]);
+				}
+			}
+			return { type: "allow" };
+		}
+	};
+}
+/**
+* Fold the resolved action into a `block` or `flag` verdict. Topic never
+* redacts — it cannot meaningfully rewrite a whole-text policy miss — so the
+* action is constrained to `"block" | "flag"` at the type level.
+*/
+function verdict(action, reason, matches) {
+	if (action === "block") return {
+		type: "block",
+		reason,
+		matches
+	};
+	return {
+		type: "flag",
+		reason,
+		matches
+	};
+}
+
+//#endregion
+export { topic };
+//# sourceMappingURL=topic.mjs.map

package/esm/guard/detectors/topic.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/topic.ts"],"sourcesContent":["import type {\n  GuardrailMatch,\n  GuardrailVerdict,\n  SyncGuardrailDetector,\n  TopicFilterOptions,\n} from \"../contracts\";\n\n/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */\nconst DETECTOR_NAME = \"topic\";\n\n/**\n * Locate the first occurrence of `term` in `text`. A `string` matches\n * case-insensitively as a substring; a `RegExp` is tested as-is (its own\n * flags decide case-sensitivity). Returns the inclusive `[start, end]`\n * span on a hit, or `undefined` when the term is absent.\n */\nfunction locate(text: string, term: string | RegExp): readonly [number, number] | undefined {\n  if (typeof term === \"string\") {\n    if (term.length === 0) {\n      return undefined;\n    }\n\n    const index = text.toLowerCase().indexOf(term.toLowerCase());\n\n    if (index === -1) {\n      return undefined;\n    }\n\n    return [index, index + term.length - 1];\n  }\n\n  // RegExp: run a non-global copy so a caller-supplied `/g` term cannot leak\n  // `lastIndex` between calls and so `.exec` reports a deterministic first hit.\n  const probe = new RegExp(term.source, term.flags.replace(/[gy]/g, \"\"));\n  const match = probe.exec(text);\n\n  if (match === null) {\n    return undefined;\n  }\n\n  return [match.index, match.index + match[0].length - 1];\n}\n\n/** A human-readable label for a deny/allow term, used in the match rule + reason. */\nfunction describeTerm(term: string | RegExp): string {\n  return typeof term === \"string\" ? term : term.source;\n}\n\n/**\n * Build the built-in **topic filter** (`ai.guardrail.topic`) — a\n * zero-runtime-dependency {@link GuardrailDetector} that gates text against a\n * deny list, an allow list, or both.\n *\n * - **`deny`** — any term that appears triggers `onMatch`. A `string`\n *   matches case-insensitively as a substring; a `RegExp` is tested as-is.\n *   The deny list is checked first; the first hit decides the verdict.\n * - **`allow`** — when set, text matching **none** of the allow terms\n *   triggers `onMatch` (an allow-list miss). Text matching at least one\n *   allow term passes the allow gate.\n *\n * `onMatch` is `\"block\"` (default) or `\"flag\"`. With neither list supplied\n * the detector is a no-op that always allows.\n *\n * @example\n * ai.guardrail.topic({ deny: [\"medical advice\", /diagnos\\w+/i] });\n *\n * @example\n * // Stay on-topic: anything not about billing is flagged.\n * ai.guardrail.topic({ allow: [\"billing\", \"invoice\", \"refund\"], onMatch: \"flag\" });\n */\nexport function topic(options: TopicFilterOptions): SyncGuardrailDetector {\n  const deny = options.deny ?? [];\n  const allow = options.allow ?? [];\n  const onMatch = options.onMatch ?? \"block\";\n\n  return {\n    name: DETECTOR_NAME,\n    check(text: string): GuardrailVerdict {\n      // Deny list: the first present term decides the verdict.\n      for (const term of deny) {\n        const span = locate(text, term);\n\n        if (span !== undefined) {\n          const label = describeTerm(term);\n          const match: GuardrailMatch = {\n            rule: `${DETECTOR_NAME}.deny.${label}`,\n            span,\n            label,\n          };\n          const reason = options.reason ?? `Denied topic matched: ${label}.`;\n\n          return verdict(onMatch, reason, [match]);\n        }\n      }\n\n      // Allow list: matching NONE of the terms is a miss → trigger onMatch.\n      if (allow.length > 0) {\n        const matchedAny = allow.some(term => locate(text, term) !== undefined);\n\n        if (!matchedAny) {\n          const match: GuardrailMatch = {\n            rule: `${DETECTOR_NAME}.allow.miss`,\n            label: \"allow-miss\",\n          };\n          const reason =\n            options.reason ?? \"Text matched none of the allowed topics.\";\n\n          return verdict(onMatch, reason, [match]);\n        }\n      }\n\n      return { type: \"allow\" };\n    },\n  };\n}\n\n/**\n * Fold the resolved action into a `block` or `flag` verdict. Topic never\n * redacts — it cannot meaningfully rewrite a whole-text policy miss — so the\n * action is constrained to `\"block\" | \"flag\"` at the type level.\n */\nfunction verdict(\n  action: \"block\" | \"flag\",\n  reason: string,\n  matches: readonly GuardrailMatch[],\n): GuardrailVerdict {\n  if (action === \"block\") {\n    return { type: \"block\", reason, matches };\n  }\n\n  return { type: \"flag\", reason, matches };\n}\n"],"mappings":";;AAQA,MAAM,gBAAgB;;;;;;;AAQtB,SAAS,OAAO,MAAc,MAA8D;CAC1F,IAAI,OAAO,SAAS,UAAU;EAC5B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,QAAQ,KAAK,YAAY,CAAC,CAAC,QAAQ,KAAK,YAAY,CAAC;EAE3D,IAAI,UAAU,IACZ;EAGF,OAAO,CAAC,OAAO,QAAQ,KAAK,SAAS,CAAC;CACxC;CAKA,MAAM,QAAQ,IADI,OAAO,KAAK,QAAQ,KAAK,MAAM,QAAQ,SAAS,EAAE,CAClD,CAAC,CAAC,KAAK,IAAI;CAE7B,IAAI,UAAU,MACZ;CAGF,OAAO,CAAC,MAAM,OAAO,MAAM,QAAQ,MAAM,EAAE,CAAC,SAAS,CAAC;AACxD;;AAGA,SAAS,aAAa,MAA+B;CACnD,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK;AAChD;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,MAAM,SAAoD;CACxE,MAAM,OAAO,QAAQ,QAAQ,CAAC;CAC9B,MAAM,QAAQ,QAAQ,SAAS,CAAC;CAChC,MAAM,UAAU,QAAQ,WAAW;CAEnC,OAAO;EACL,MAAM;EACN,MAAM,MAAgC;GAEpC,KAAK,MAAM,QAAQ,MAAM;IACvB,MAAM,OAAO,OAAO,MAAM,IAAI;IAE9B,IAAI,SAAS,QAAW;KACtB,MAAM,QAAQ,aAAa,IAAI;KAC/B,MAAM,QAAwB;MAC5B,MAAM,GAAG,cAAc,QAAQ;MAC/B;MACA;KACF;KAGA,OAAO,QAAQ,SAFA,QAAQ,UAAU,yBAAyB,MAAM,IAEhC,CAAC,KAAK,CAAC;IACzC;GACF;GAGA,IAAI,MAAM,SAAS,GAGjB;QAAI,CAFe,MAAM,MAAK,SAAQ,OAAO,MAAM,IAAI,MAAM,MAE/C,GAAG;KACf,MAAM,QAAwB;MAC5B,MAAM,GAAG,cAAc;MACvB,OAAO;KACT;KAIA,OAAO,QAAQ,SAFb,QAAQ,UAAU,4CAEY,CAAC,KAAK,CAAC;IACzC;;GAGF,OAAO,EAAE,MAAM,QAAQ;EACzB;CACF;AACF;;;;;;AAOA,SAAS,QACP,QACA,QACA,SACkB;CAClB,IAAI,WAAW,SACb,OAAO;EAAE,MAAM;EAAS;EAAQ;CAAQ;CAG1C,OAAO;EAAE,MAAM;EAAQ;EAAQ;CAAQ;AACzC"}

package/esm/guard/errors.d.mts

@@ -0,0 +1,12 @@
+import { GuardrailViolationError, GuardrailViolationErrorOptions } from "../errors/guardrail-violation-error.mjs";
+
+//#region ../@warlock.js/ai/src/guard/errors.d.ts
+/**
+ * Curated install string thrown by the optional `moderation` detector on
+ * first `check()` when the `openai` peer is absent. Mirrors ai-panoptic's
+ * `LANGFUSE_INSTALL_INSTRUCTIONS`.
+ */
+declare const OPENAI_INSTALL_INSTRUCTIONS: string;
+//#endregion
+export { OPENAI_INSTALL_INSTRUCTIONS };
+//# sourceMappingURL=errors.d.mts.map

package/esm/guard/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/guard/errors.ts"],"mappings":";;;;;;;;cAuBa,2BAAA"}

package/esm/guard/errors.mjs

@@ -0,0 +1,18 @@
+import { GuardrailViolationError } from "../errors/guardrail-violation-error.mjs";
+
+//#region ../@warlock.js/ai/src/guard/errors.ts
+/**
+* Curated install string thrown by the optional `moderation` detector on
+* first `check()` when the `openai` peer is absent. Mirrors ai-panoptic's
+* `LANGFUSE_INSTALL_INSTRUCTIONS`.
+*/
+const OPENAI_INSTALL_INSTRUCTIONS = `
+The @warlock.js/ai moderation detector requires the optional "openai" peer.
+Install it with:
+
+  npm install openai
+`.trim();
+
+//#endregion
+export { OPENAI_INSTALL_INSTRUCTIONS };
+//# sourceMappingURL=errors.mjs.map

package/esm/guard/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/guard/errors.ts"],"sourcesContent":["/**\n * Error surface for `@warlock.js/ai`.\n *\n * **No new error class.** A `block` verdict reuses the existing\n * `@warlock.js/ai` {@link GuardrailViolationError} verbatim — its category\n * (`\"guardrail\"`) and `phase` field already model exactly what a guard\n * needs, and `phase` is widened by this package to include `\"tool\"` (a\n * source-compatible third value). Re-exported here so the future `guard()`\n * factory has one import site for the typed abort it throws.\n *\n * The optional `moderation` detector's missing-peer failure is an\n * *infrastructure* fault, not a content violation, so it throws a plain\n * `Error` carrying {@link OPENAI_INSTALL_INSTRUCTIONS} (the langfuse-style\n * lazy-import pattern) rather than an `AIError`.\n */\nexport { GuardrailViolationError } from \"../errors/guardrail-violation-error\";\nexport type { GuardrailViolationErrorOptions } from \"../errors/guardrail-violation-error\";\n\n/**\n * Curated install string thrown by the optional `moderation` detector on\n * first `check()` when the `openai` peer is absent. Mirrors ai-panoptic's\n * `LANGFUSE_INSTALL_INSTRUCTIONS`.\n */\nexport const OPENAI_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai moderation detector requires the optional \"openai\" peer.\nInstall it with:\n\n  npm install openai\n`.trim();\n"],"mappings":";;;;;;;;AAuBA,MAAa,8BAA8B;;;;;EAKzC,KAAK"}