@warlock.js/core 4.7.0 → 4.8.1

package/esm/ai/src/guard/detectors/injection.mjs

@@ -1,254 +0,0 @@
-//#region ../@warlock.js/ai/src/guard/detectors/injection.ts
-const DETECTOR_NAME = "injection";
-/**
-* Built-in jailbreak / prompt-injection marker phrases. Each entry is a
-* case-insensitive substring (matched lowercased) paired with the rule
-* label surfaced on the {@link GuardrailMatch} (`injection.<label>`).
-*
-* The set targets the canonical override / role-reset / exfiltration
-* patterns rather than trying to be exhaustive — a curated, low-false-
-* positive seed that callers extend with their own `markers`. Phrases are
-* deliberately specific (`"ignore previous instructions"`, not the bare
-* word `"ignore"`) so ordinary prose does not trip the rule.
-*/
-const BUILT_IN_MARKERS = [
-	{
-		phrase: "ignore previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "ignore all previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "ignore the above instructions",
-		label: "override"
-	},
-	{
-		phrase: "disregard previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "disregard all previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "forget previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "forget all previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "ignore your instructions",
-		label: "override"
-	},
-	{
-		phrase: "override your instructions",
-		label: "override"
-	},
-	{
-		phrase: "do not follow your instructions",
-		label: "override"
-	},
-	{
-		phrase: "you are now",
-		label: "role-reset"
-	},
-	{
-		phrase: "act as",
-		label: "role-reset"
-	},
-	{
-		phrase: "pretend to be",
-		label: "role-reset"
-	},
-	{
-		phrase: "developer mode",
-		label: "jailbreak"
-	},
-	{
-		phrase: "jailbreak",
-		label: "jailbreak"
-	},
-	{
-		phrase: "dan mode",
-		label: "jailbreak"
-	},
-	{
-		phrase: "do anything now",
-		label: "jailbreak"
-	},
-	{
-		phrase: "bypass your",
-		label: "jailbreak"
-	},
-	{
-		phrase: "ignore your guidelines",
-		label: "jailbreak"
-	},
-	{
-		phrase: "ignore your safety",
-		label: "jailbreak"
-	},
-	{
-		phrase: "ignore the rules",
-		label: "jailbreak"
-	},
-	{
-		phrase: "without any restrictions",
-		label: "jailbreak"
-	},
-	{
-		phrase: "reveal your system prompt",
-		label: "exfiltration"
-	},
-	{
-		phrase: "print your system prompt",
-		label: "exfiltration"
-	},
-	{
-		phrase: "show your system prompt",
-		label: "exfiltration"
-	},
-	{
-		phrase: "repeat your instructions",
-		label: "exfiltration"
-	},
-	{
-		phrase: "what are your instructions",
-		label: "exfiltration"
-	},
-	{
-		phrase: "reveal your prompt",
-		label: "exfiltration"
-	}
-];
-/**
-* The zero-dependency built-in injection detector — the internal class
-* behind the {@link injection} factory. Scans for jailbreak / prompt-
-* injection marker phrases (built-in set + caller `markers`) and returns a
-* `block` or `flag` verdict (per `onMatch`) listing every match, or `allow`
-* when the text is clean.
-*
-* Detection only: a detector never throws or mutates the pipeline — the
-* `guard()` factory translates the verdict into the trip's throw / record
-* mechanics.
-*/
-var InjectionDetector = class {
-	constructor(options = {}) {
-		this.name = DETECTOR_NAME;
-		this.block = options.onMatch === "block";
-		this.markers = compileMarkers(options.markers ?? []);
-	}
-	/**
-	* Inspect `text` for any built-in or caller marker. Returns `allow` when
-	* none hit, otherwise the configured `block` / `flag` verdict carrying a
-	* {@link GuardrailMatch} per hit (with a `[start, end]` span for literal
-	* substrings; regex hits report a span only when the match is locatable).
-	*/
-	check(text) {
-		const matches = this.scan(text);
-		if (matches.length === 0) return { type: "allow" };
-		const reason = `Detected ${matches.length} prompt-injection marker(s).`;
-		if (this.block) return {
-			type: "block",
-			reason,
-			matches
-		};
-		return {
-			type: "flag",
-			reason,
-			matches
-		};
-	}
-	/** Collect every marker hit in `text`, in marker registration order. */
-	scan(text) {
-		const lowered = text.toLowerCase();
-		const matches = [];
-		for (const marker of this.markers) {
-			if (marker.phrase !== void 0) {
-				const start = lowered.indexOf(marker.phrase);
-				if (start !== -1) matches.push({
-					rule: `${DETECTOR_NAME}.${marker.label}`,
-					label: marker.label,
-					span: [start, start + marker.phrase.length - 1]
-				});
-				continue;
-			}
-			const pattern = marker.pattern;
-			if (pattern === void 0) continue;
-			const result = pattern.exec(text);
-			if (result !== null) {
-				const start = result.index;
-				matches.push({
-					rule: `${DETECTOR_NAME}.${marker.label}`,
-					label: marker.label,
-					span: [start, start + result[0].length - 1]
-				});
-			}
-		}
-		return matches;
-	}
-};
-/**
-* Compile the built-in phrase set plus any caller `markers` into a single
-* ordered list. A caller `string` becomes a lowercased substring matcher
-* (labelled `custom`); a caller `RegExp` is carried as-is (labelled
-* `custom`). Built-ins keep their threat-category label.
-*/
-function compileMarkers(extra) {
-	const compiled = BUILT_IN_MARKERS.map((entry) => ({
-		label: entry.label,
-		phrase: entry.phrase
-	}));
-	for (const marker of extra) {
-		if (typeof marker === "string") {
-			compiled.push({
-				label: "custom",
-				phrase: marker.toLowerCase()
-			});
-			continue;
-		}
-		compiled.push({
-			label: "custom",
-			pattern: marker
-		});
-	}
-	return compiled;
-}
-/**
-* Build the built-in `injection` detector (surfaced as
-* `ai.guardrail.injection(options?)`). Matches a curated set of jailbreak /
-* prompt-injection marker phrases — override (`"ignore previous
-* instructions"`), role-reset (`"you are now"`), jailbreak (`"developer
-* mode"`, `"do anything now"`), and exfiltration (`"reveal your system
-* prompt"`) — extensible with caller `markers` (case-insensitive substrings
-* or `RegExp`s).
-*
-* Zero runtime dependency: matching is pure string / regex. On a hit the
-* verdict is `flag` by default (record but allow); pass `onMatch: "block"`
-* to reject instead — commonly used on the `input` phase, where the core
-* `trip.before` seam supports `block` / `flag` only.
-*
-* @param options - Extra `markers` and the `onMatch` action (`"flag"` | `"block"`).
-* @returns A {@link SyncGuardrailDetector} for the guard's `input` / `output` / `tool` arrays.
-*
-* @example
-* const guard = ai.guardrail({
-*   input: [ai.guardrail.injection({ onMatch: "block" })],
-*   output: [ai.guardrail.injection()], // flag-only on the model's reply
-* });
-*
-* @example
-* // Extend the built-in set with a house rule.
-* ai.guardrail.injection({ markers: [/system\s*:\s*override/i, "sudo mode"] });
-*/
-function injection(options) {
-	return new InjectionDetector(options);
-}
-
-//#endregion
-export { injection };
-//# sourceMappingURL=injection.mjs.map

package/esm/ai/src/guard/detectors/injection.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"injection.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/guard/detectors/injection.ts"],"sourcesContent":["import type {\n  GuardrailMatch,\n  GuardrailVerdict,\n  InjectionDetectorOptions,\n  SyncGuardrailDetector,\n} from \"../contracts\";\n\nconst DETECTOR_NAME = \"injection\";\n\n/**\n * Built-in jailbreak / prompt-injection marker phrases. Each entry is a\n * case-insensitive substring (matched lowercased) paired with the rule\n * label surfaced on the {@link GuardrailMatch} (`injection.<label>`).\n *\n * The set targets the canonical override / role-reset / exfiltration\n * patterns rather than trying to be exhaustive — a curated, low-false-\n * positive seed that callers extend with their own `markers`. Phrases are\n * deliberately specific (`\"ignore previous instructions\"`, not the bare\n * word `\"ignore\"`) so ordinary prose does not trip the rule.\n */\nconst BUILT_IN_MARKERS: readonly { readonly phrase: string; readonly label: string }[] = [\n  { phrase: \"ignore previous instructions\", label: \"override\" },\n  { phrase: \"ignore all previous instructions\", label: \"override\" },\n  { phrase: \"ignore the above instructions\", label: \"override\" },\n  { phrase: \"disregard previous instructions\", label: \"override\" },\n  { phrase: \"disregard all previous instructions\", label: \"override\" },\n  { phrase: \"forget previous instructions\", label: \"override\" },\n  { phrase: \"forget all previous instructions\", label: \"override\" },\n  { phrase: \"ignore your instructions\", label: \"override\" },\n  { phrase: \"override your instructions\", label: \"override\" },\n  { phrase: \"do not follow your instructions\", label: \"override\" },\n  { phrase: \"you are now\", label: \"role-reset\" },\n  { phrase: \"act as\", label: \"role-reset\" },\n  { phrase: \"pretend to be\", label: \"role-reset\" },\n  { phrase: \"developer mode\", label: \"jailbreak\" },\n  { phrase: \"jailbreak\", label: \"jailbreak\" },\n  { phrase: \"dan mode\", label: \"jailbreak\" },\n  { phrase: \"do anything now\", label: \"jailbreak\" },\n  { phrase: \"bypass your\", label: \"jailbreak\" },\n  { phrase: \"ignore your guidelines\", label: \"jailbreak\" },\n  { phrase: \"ignore your safety\", label: \"jailbreak\" },\n  { phrase: \"ignore the rules\", label: \"jailbreak\" },\n  { phrase: \"without any restrictions\", label: \"jailbreak\" },\n  { phrase: \"reveal your system prompt\", label: \"exfiltration\" },\n  { phrase: \"print your system prompt\", label: \"exfiltration\" },\n  { phrase: \"show your system prompt\", label: \"exfiltration\" },\n  { phrase: \"repeat your instructions\", label: \"exfiltration\" },\n  { phrase: \"what are your instructions\", label: \"exfiltration\" },\n  { phrase: \"reveal your prompt\", label: \"exfiltration\" },\n];\n\n/**\n * A compiled marker — either a literal substring (matched case-insensitively\n * against the lowercased text) or a caller-supplied `RegExp` (tested as-is).\n * `label` is the namespaced rule suffix (`injection.<label>`); for built-in\n * phrases it is the threat category, for caller markers the index.\n */\ninterface CompiledMarker {\n  readonly label: string;\n  readonly phrase?: string;\n  readonly pattern?: RegExp;\n}\n\n/**\n * The zero-dependency built-in injection detector — the internal class\n * behind the {@link injection} factory. Scans for jailbreak / prompt-\n * injection marker phrases (built-in set + caller `markers`) and returns a\n * `block` or `flag` verdict (per `onMatch`) listing every match, or `allow`\n * when the text is clean.\n *\n * Detection only: a detector never throws or mutates the pipeline — the\n * `guard()` factory translates the verdict into the trip's throw / record\n * mechanics.\n */\nclass InjectionDetector implements SyncGuardrailDetector {\n  public readonly name = DETECTOR_NAME;\n\n  /** The compiled built-in + caller markers, scanned in registration order. */\n  private readonly markers: readonly CompiledMarker[];\n\n  /** Whether a match escalates to `block` (`true`) or stays a `flag`. */\n  private readonly block: boolean;\n\n  public constructor(options: InjectionDetectorOptions = {}) {\n    this.block = options.onMatch === \"block\";\n    this.markers = compileMarkers(options.markers ?? []);\n  }\n\n  /**\n   * Inspect `text` for any built-in or caller marker. Returns `allow` when\n   * none hit, otherwise the configured `block` / `flag` verdict carrying a\n   * {@link GuardrailMatch} per hit (with a `[start, end]` span for literal\n   * substrings; regex hits report a span only when the match is locatable).\n   */\n  public check(text: string): GuardrailVerdict {\n    const matches = this.scan(text);\n\n    if (matches.length === 0) {\n      return { type: \"allow\" };\n    }\n\n    const reason = `Detected ${matches.length} prompt-injection marker(s).`;\n\n    if (this.block) {\n      return { type: \"block\", reason, matches };\n    }\n\n    return { type: \"flag\", reason, matches };\n  }\n\n  /** Collect every marker hit in `text`, in marker registration order. */\n  private scan(text: string): GuardrailMatch[] {\n    const lowered = text.toLowerCase();\n    const matches: GuardrailMatch[] = [];\n\n    for (const marker of this.markers) {\n      if (marker.phrase !== undefined) {\n        const start = lowered.indexOf(marker.phrase);\n\n        if (start !== -1) {\n          matches.push({\n            rule: `${DETECTOR_NAME}.${marker.label}`,\n            label: marker.label,\n            span: [start, start + marker.phrase.length - 1],\n          });\n        }\n\n        continue;\n      }\n\n      // Caller-supplied RegExp — tested against the original (not lowered)\n      // text so author-controlled case sensitivity is preserved.\n      const pattern = marker.pattern;\n\n      if (pattern === undefined) {\n        continue;\n      }\n\n      const result = pattern.exec(text);\n\n      if (result !== null) {\n        const start = result.index;\n\n        matches.push({\n          rule: `${DETECTOR_NAME}.${marker.label}`,\n          label: marker.label,\n          span: [start, start + result[0].length - 1],\n        });\n      }\n    }\n\n    return matches;\n  }\n}\n\n/**\n * Compile the built-in phrase set plus any caller `markers` into a single\n * ordered list. A caller `string` becomes a lowercased substring matcher\n * (labelled `custom`); a caller `RegExp` is carried as-is (labelled\n * `custom`). Built-ins keep their threat-category label.\n */\nfunction compileMarkers(\n  extra: readonly (string | RegExp)[],\n): readonly CompiledMarker[] {\n  const compiled: CompiledMarker[] = BUILT_IN_MARKERS.map((entry) => ({\n    label: entry.label,\n    phrase: entry.phrase,\n  }));\n\n  for (const marker of extra) {\n    if (typeof marker === \"string\") {\n      compiled.push({ label: \"custom\", phrase: marker.toLowerCase() });\n\n      continue;\n    }\n\n    compiled.push({ label: \"custom\", pattern: marker });\n  }\n\n  return compiled;\n}\n\n/**\n * Build the built-in `injection` detector (surfaced as\n * `ai.guardrail.injection(options?)`). Matches a curated set of jailbreak /\n * prompt-injection marker phrases — override (`\"ignore previous\n * instructions\"`), role-reset (`\"you are now\"`), jailbreak (`\"developer\n * mode\"`, `\"do anything now\"`), and exfiltration (`\"reveal your system\n * prompt\"`) — extensible with caller `markers` (case-insensitive substrings\n * or `RegExp`s).\n *\n * Zero runtime dependency: matching is pure string / regex. On a hit the\n * verdict is `flag` by default (record but allow); pass `onMatch: \"block\"`\n * to reject instead — commonly used on the `input` phase, where the core\n * `trip.before` seam supports `block` / `flag` only.\n *\n * @param options - Extra `markers` and the `onMatch` action (`\"flag\"` | `\"block\"`).\n * @returns A {@link SyncGuardrailDetector} for the guard's `input` / `output` / `tool` arrays.\n *\n * @example\n * const guard = ai.guardrail({\n *   input: [ai.guardrail.injection({ onMatch: \"block\" })],\n *   output: [ai.guardrail.injection()], // flag-only on the model's reply\n * });\n *\n * @example\n * // Extend the built-in set with a house rule.\n * ai.guardrail.injection({ markers: [/system\\s*:\\s*override/i, \"sudo mode\"] });\n */\nexport function injection(\n  options?: InjectionDetectorOptions,\n): SyncGuardrailDetector {\n  return new InjectionDetector(options);\n}\n"],"mappings":"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"}

package/esm/ai/src/guard/detectors/moderation.mjs

@@ -1,134 +0,0 @@
-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("../../../../node_modules/openai/index.mjs");
-			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/ai/src/guard/detectors/moderation.mjs.map

@@ -1 +0,0 @@
-{"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/ai/src/guard/detectors/pii.mjs

@@ -1,199 +0,0 @@
-//#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/ai/src/guard/detectors/pii.mjs.map

@@ -1 +0,0 @@
-{"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":"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"}