@floatingsidewal/bulkhead-core 0.3.0

package/README.md

@@ -0,0 +1,142 @@
+# @floatingsidewal/bulkhead-core
+
+Cascading content protection engine -- detects and redacts PII, secrets, prompt injection, and system prompt leakage in text before it reaches LLMs.
+
+Part of the [Bulkhead](https://github.com/floatingsidewal/bulkhead) project.
+
+## Install
+
+
+```
+```
+
+Then install:
+
+```bash
+npm install @floatingsidewal/bulkhead-core
+```
+
+## Quick Start
+
+```typescript
+import { createEngine } from "@floatingsidewal/bulkhead-core";
+
+const engine = createEngine();
+
+// Fast regex-only scan (sub-millisecond)
+const result = await engine.analyze("My SSN is 123-45-6789 and key is AKIAIOSFODNN7EXAMPLE");
+
+console.log(result.passed);      // false
+console.log(result.detections);   // [{ entityType: "US_SSN", ... }, { entityType: "AWS_ACCESS_KEY", ... }]
+
+// Scan and redact
+const redacted = await engine.scan("Call me at 555-867-5309");
+console.log(redacted.redactedText); // "Call me at [REDACTED-US_PHONE]"
+```
+
+## What It Detects
+
+| Category | Coverage |
+|----------|----------|
+| **PII** | 45+ entity types across 20+ countries (SSN, credit cards, IBAN, phone, email, medical IDs, national IDs) |
+| **Secrets** | 154 patterns across 13 categories (AWS, Azure, GCP, GitHub, Slack, Stripe, database credentials, private keys) |
+| **Prompt Injection** | 16+ patterns (role-play attacks, DAN mode, instruction override) |
+| **System Prompt Leakage** | 7+ patterns (prompt extraction, "repeat everything above") |
+
+All structured patterns include checksum validation where applicable (Luhn, IBAN mod-97, Verhoeff).
+
+## Configuration
+
+```typescript
+import { createEngine, type BulkheadConfig } from "@floatingsidewal/bulkhead-core";
+
+const engine = createEngine({
+  enabled: true,
+  debounceMs: 500,
+  guards: {
+    pii: { enabled: true },
+    secret: { enabled: true },
+    injection: { enabled: true },
+    contentSafety: { enabled: false },
+  },
+  cascade: {
+    modelEnabled: false,       // Enable BERT layer (see below)
+    escalationThreshold: 0.75,
+    contextSentences: 3,
+    modelId: "Xenova/bert-base-NER",
+  },
+});
+```
+
+## Custom Guard Composition
+
+For fine-grained control, compose guards directly:
+
+```typescript
+import { GuardrailsEngine, PiiGuard, SecretGuard } from "@floatingsidewal/bulkhead-core";
+
+const engine = new GuardrailsEngine();
+engine.addGuard(new PiiGuard());
+engine.addGuard(new SecretGuard());
+// Skip injection/leakage guards if not needed
+```
+
+## BERT Layer (Optional)
+
+The regex layer catches structured patterns. For contextual entities like names, locations, and organizations, enable the BERT layer:
+
+```bash
+npm install @huggingface/transformers
+```
+
+```typescript
+const engine = createEngine({
+  // ...
+  cascade: {
+    modelEnabled: true,  // Enables BERT NER model
+    // ...
+  },
+});
+
+// Use deepScan for full cascade (regex + BERT + optional LLM)
+const result = await engine.deepScan("Send the report to John Smith at Acme Corp");
+
+// Or modelScan for regex + BERT only (no LLM)
+const result = await engine.modelScan(text);
+```
+
+The BERT model (~29 MB) downloads on first inference and runs in a worker thread. No GPU required.
+
+## API
+
+### `createEngine(config?)`
+
+Creates a configured engine from a `BulkheadConfig`. Returns a `GuardrailsEngine`.
+
+### `engine.analyze(text)`
+
+Layer 1 only (regex). Sub-millisecond. Returns `{ passed, detections, stats }`.
+
+### `engine.scan(text)`
+
+Layer 1 scan with redaction. Returns `{ passed, detections, redactedText, stats }`.
+
+### `engine.modelScan(text)`
+
+Regex + BERT (Layers 1-2). Requires `cascade.modelEnabled: true`.
+
+### `engine.deepScan(text)`
+
+Full cascade (Layers 1-3). Requires cascade configuration.
+
+### `engine.dispose()`
+
+Cleanup (terminates BERT worker thread if running).
+
+## Documentation
+
+See the [full documentation](https://github.com/floatingsidewal/bulkhead/tree/develop/docs) for architecture details, deployment guides, and API reference.
+
+## License
+
+MIT

package/dist/cascade/bert-worker.js

@@ -0,0 +1,84 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cascade/bert-worker.ts
+var bert_worker_exports = {};
+module.exports = __toCommonJS(bert_worker_exports);
+var import_node_worker_threads = require("worker_threads");
+var pipeline = null;
+var currentModelId = null;
+async function loadModel(modelId) {
+  if (pipeline && currentModelId === modelId) return;
+  const { pipeline: createPipeline } = await import("@huggingface/transformers");
+  pipeline = await createPipeline("token-classification", modelId, {
+    dtype: "q8",
+    // Use ONNX runtime for Node.js
+    device: "cpu"
+  });
+  currentModelId = modelId;
+}
+async function analyze(text, modelId) {
+  await loadModel(modelId);
+  const results = await pipeline(text, {
+    aggregation_strategy: "simple"
+  });
+  return results.map((r) => ({
+    entity: r.entity_group ?? r.entity,
+    score: r.score,
+    word: r.word ?? r.text ?? "",
+    start: r.start ?? 0,
+    end: r.end ?? (r.start != null ? r.start + (r.word?.length ?? 0) : 0)
+  }));
+}
+if (import_node_worker_threads.parentPort) {
+  import_node_worker_threads.parentPort.on("message", async (msg) => {
+    if (msg.type === "dispose") {
+      pipeline = null;
+      currentModelId = null;
+      import_node_worker_threads.parentPort.postMessage({ type: "ready", id: msg.id });
+      return;
+    }
+    if (msg.type === "analyze" && msg.text) {
+      try {
+        const tokens = await analyze(
+          msg.text,
+          msg.modelId ?? "gravitee-io/bert-small-pii-detection"
+        );
+        import_node_worker_threads.parentPort.postMessage({
+          type: "result",
+          id: msg.id,
+          tokens
+        });
+      } catch (err) {
+        import_node_worker_threads.parentPort.postMessage({
+          type: "error",
+          id: msg.id,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  });
+}
+//# sourceMappingURL=bert-worker.js.map

package/dist/cascade/bert-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cascade/bert-worker.ts"],"sourcesContent":["/**\n * BERT model worker thread for Layer 2 of the cascading classifier.\n * Runs in a separate thread to avoid blocking the VS Code extension host.\n *\n * Uses @huggingface/transformers to load and run a token-classification model.\n * The model loads lazily on first request and stays loaded (singleton).\n */\n\nimport { parentPort } from \"node:worker_threads\";\n\n/** Message types between main thread and worker */\nexport interface WorkerRequest {\n  type: \"analyze\" | \"dispose\";\n  id: string;\n  text?: string;\n  modelId?: string;\n}\n\nexport interface BertToken {\n  entity: string; // e.g., \"B-PERSON\", \"I-LOCATION\"\n  score: number;\n  word: string;\n  start: number;\n  end: number;\n}\n\nexport interface WorkerResponse {\n  type: \"result\" | \"error\" | \"ready\";\n  id: string;\n  tokens?: BertToken[];\n  error?: string;\n}\n\nlet pipeline: any = null;\nlet currentModelId: string | null = null;\n\nasync function loadModel(modelId: string): Promise<void> {\n  if (pipeline && currentModelId === modelId) return;\n\n  // Dynamic import to avoid loading transformers.js at module level\n  const { pipeline: createPipeline } = await import(\n    \"@huggingface/transformers\"\n  );\n\n  pipeline = await createPipeline(\"token-classification\", modelId, {\n    dtype: \"q8\",\n    // Use ONNX runtime for Node.js\n    device: \"cpu\",\n  });\n  currentModelId = modelId;\n}\n\nasync function analyze(\n  text: string,\n  modelId: string\n): Promise<BertToken[]> {\n  await loadModel(modelId);\n\n  const results = await pipeline(text, {\n    aggregation_strategy: \"simple\",\n  });\n\n  return (results as any[]).map((r) => ({\n    entity: r.entity_group ?? r.entity,\n    score: r.score,\n    word: r.word ?? r.text ?? \"\",\n    start: r.start ?? 0,\n    end: r.end ?? (r.start != null ? r.start + (r.word?.length ?? 0) : 0),\n  }));\n}\n\n// Worker message handler\nif (parentPort) {\n  parentPort.on(\"message\", async (msg: WorkerRequest) => {\n    if (msg.type === \"dispose\") {\n      pipeline = null;\n      currentModelId = null;\n      parentPort!.postMessage({ type: \"ready\", id: msg.id } as WorkerResponse);\n      return;\n    }\n\n    if (msg.type === \"analyze\" && msg.text) {\n      try {\n        const tokens = await analyze(\n          msg.text,\n          msg.modelId ?? \"gravitee-io/bert-small-pii-detection\"\n        );\n        parentPort!.postMessage({\n          type: \"result\",\n          id: msg.id,\n          tokens,\n        } as WorkerResponse);\n      } catch (err) {\n        parentPort!.postMessage({\n          type: \"error\",\n          id: msg.id,\n          error: err instanceof Error ? err.message : String(err),\n        } as WorkerResponse);\n      }\n    }\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAQA,iCAA2B;AAyB3B,IAAI,WAAgB;AACpB,IAAI,iBAAgC;AAEpC,eAAe,UAAU,SAAgC;AACvD,MAAI,YAAY,mBAAmB,QAAS;AAG5C,QAAM,EAAE,UAAU,eAAe,IAAI,MAAM,OACzC,2BACF;AAEA,aAAW,MAAM,eAAe,wBAAwB,SAAS;AAAA,IAC/D,OAAO;AAAA;AAAA,IAEP,QAAQ;AAAA,EACV,CAAC;AACD,mBAAiB;AACnB;AAEA,eAAe,QACb,MACA,SACsB;AACtB,QAAM,UAAU,OAAO;AAEvB,QAAM,UAAU,MAAM,SAAS,MAAM;AAAA,IACnC,sBAAsB;AAAA,EACxB,CAAC;AAED,SAAQ,QAAkB,IAAI,CAAC,OAAO;AAAA,IACpC,QAAQ,EAAE,gBAAgB,EAAE;AAAA,IAC5B,OAAO,EAAE;AAAA,IACT,MAAM,EAAE,QAAQ,EAAE,QAAQ;AAAA,IAC1B,OAAO,EAAE,SAAS;AAAA,IAClB,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,KAAK;AAAA,EACrE,EAAE;AACJ;AAGA,IAAI,uCAAY;AACd,wCAAW,GAAG,WAAW,OAAO,QAAuB;AACrD,QAAI,IAAI,SAAS,WAAW;AAC1B,iBAAW;AACX,uBAAiB;AACjB,4CAAY,YAAY,EAAE,MAAM,SAAS,IAAI,IAAI,GAAG,CAAmB;AACvE;AAAA,IACF;AAEA,QAAI,IAAI,SAAS,aAAa,IAAI,MAAM;AACtC,UAAI;AACF,cAAM,SAAS,MAAM;AAAA,UACnB,IAAI;AAAA,UACJ,IAAI,WAAW;AAAA,QACjB;AACA,8CAAY,YAAY;AAAA,UACtB,MAAM;AAAA,UACN,IAAI,IAAI;AAAA,UACR;AAAA,QACF,CAAmB;AAAA,MACrB,SAAS,KAAK;AACZ,8CAAY,YAAY;AAAA,UACtB,MAAM;AAAA,UACN,IAAI,IAAI;AAAA,UACR,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,QACxD,CAAmB;AAAA,MACrB;AAAA,IACF;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/cascade/index.d.mts

@@ -0,0 +1 @@
+export { k as BertLayer, B as BertLayerConfig, c as CascadeClassifier, C as CascadeConfig, l as LlmLayer, L as LlmLayerConfig, h as LlmProvider } from '../index-BNiM_sPB.mjs';

package/dist/cascade/index.d.ts

@@ -0,0 +1 @@
+export { k as BertLayer, B as BertLayerConfig, c as CascadeClassifier, C as CascadeConfig, l as LlmLayer, L as LlmLayerConfig, h as LlmProvider } from '../index-BNiM_sPB.js';

package/dist/cascade/index.js

@@ -0,0 +1,386 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cascade/index.ts
+var cascade_exports = {};
+__export(cascade_exports, {
+  BertLayer: () => BertLayer,
+  CascadeClassifier: () => CascadeClassifier,
+  LlmLayer: () => LlmLayer
+});
+module.exports = __toCommonJS(cascade_exports);
+
+// src/cascade/bert-layer.ts
+var import_node_worker_threads = require("worker_threads");
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+var DEFAULT_MODEL_ID = "Xenova/bert-base-NER";
+var BertLayer = class {
+  worker = null;
+  pendingRequests = /* @__PURE__ */ new Map();
+  requestId = 0;
+  config;
+  /** Whether the BERT model has been loaded and first inference completed */
+  _loaded = false;
+  get loaded() {
+    return this._loaded;
+  }
+  constructor(config) {
+    this.config = {
+      escalationThreshold: 0.75,
+      ...config
+    };
+  }
+  /** Resolve the worker path — supports both compiled .js and source .ts */
+  resolveWorkerPath() {
+    const compiledPath = (0, import_node_path.resolve)(__dirname, "cascade", "bert-worker.js");
+    if ((0, import_node_fs.existsSync)(compiledPath)) return compiledPath;
+    const tsPath = (0, import_node_path.resolve)(__dirname, "bert-worker.ts");
+    if ((0, import_node_fs.existsSync)(tsPath)) return tsPath;
+    return compiledPath;
+  }
+  /** Ensure the worker thread is running */
+  ensureWorker() {
+    if (!this.worker) {
+      const workerPath = this.resolveWorkerPath();
+      const isTs = workerPath.endsWith(".ts");
+      this.worker = isTs ? new import_node_worker_threads.Worker(workerPath, {
+        execArgv: ["--require", "tsx/cjs"]
+      }) : new import_node_worker_threads.Worker(workerPath);
+      this.worker.on("message", (msg) => {
+        const pending = this.pendingRequests.get(msg.id);
+        if (!pending) return;
+        this.pendingRequests.delete(msg.id);
+        if (msg.type === "error") {
+          pending.reject(new Error(msg.error ?? "Unknown worker error"));
+        } else {
+          pending.resolve(msg.tokens ?? []);
+        }
+      });
+      this.worker.on("error", (err) => {
+        for (const [id, pending] of this.pendingRequests) {
+          pending.reject(err);
+          this.pendingRequests.delete(id);
+        }
+      });
+    }
+    return this.worker;
+  }
+  /** Send text to the BERT worker and get raw token results */
+  async analyzeRaw(text) {
+    const worker = this.ensureWorker();
+    const id = String(++this.requestId);
+    return new Promise((resolve2, reject) => {
+      this.pendingRequests.set(id, { resolve: resolve2, reject });
+      worker.postMessage({
+        type: "analyze",
+        id,
+        text,
+        modelId: this.config.modelId ?? DEFAULT_MODEL_ID
+      });
+    });
+  }
+  /**
+   * Analyze text and return Detection objects with escalation disposition.
+   * Tokens above the escalation threshold are "confirmed",
+   * tokens below are "escalate" (need LLM review).
+   */
+  async analyze(text) {
+    const tokens = await this.analyzeRaw(text);
+    this._loaded = true;
+    return tokens.map((token) => {
+      const entityType = token.entity.replace(/^[BI]-/, "");
+      const isConfirmed = token.score >= this.config.escalationThreshold;
+      const confidence = token.score >= 0.9 ? "high" : token.score >= 0.7 ? "medium" : "low";
+      return {
+        entityType,
+        start: token.start,
+        end: token.end,
+        text: token.word,
+        confidence,
+        score: token.score,
+        guardName: "cascade-bert",
+        source: "bert",
+        context: text.slice(
+          Math.max(0, token.start - 150),
+          Math.min(text.length, token.end + 150)
+        ),
+        disposition: isConfirmed ? "confirmed" : "escalate"
+      };
+    });
+  }
+  /** Terminate the worker thread */
+  async dispose() {
+    if (this.worker) {
+      await this.worker.terminate();
+      this.worker = null;
+      this.pendingRequests.clear();
+    }
+  }
+};
+
+// src/cascade/llm-layer.ts
+var LlmLayer = class {
+  config;
+  constructor(config) {
+    this.config = {
+      contextSentences: 3,
+      ...config
+    };
+  }
+  /** Set the LLM provider (can be swapped at runtime) */
+  setProvider(provider) {
+    this.config.provider = provider;
+  }
+  /**
+   * Disambiguate escalated detections using an LLM.
+   * @param escalated Detections with disposition "escalate"
+   * @param fullText The full document text
+   * @param confirmed Already-confirmed detections (passed as context to help disambiguation)
+   */
+  async disambiguate(escalated, fullText, confirmed) {
+    if (!this.config.provider) {
+      return escalated;
+    }
+    const results = [];
+    for (const detection of escalated) {
+      const prompt = this.buildPrompt(detection, fullText, confirmed);
+      try {
+        const response = await this.config.provider(prompt);
+        const parsed = this.parseResponse(response);
+        if (parsed && parsed.type !== "NONE") {
+          results.push({
+            ...detection,
+            entityType: parsed.type,
+            score: parsed.confidence,
+            confidence: parsed.confidence >= 0.9 ? "high" : parsed.confidence >= 0.7 ? "medium" : "low",
+            source: "llm",
+            disposition: "confirmed"
+          });
+        } else {
+          results.push({
+            ...detection,
+            source: "llm",
+            disposition: "dismissed"
+          });
+        }
+      } catch {
+        results.push(detection);
+      }
+    }
+    return results;
+  }
+  /** Build a focused disambiguation prompt */
+  buildPrompt(detection, fullText, confirmed) {
+    const contextWindow = this.extractSentenceContext(
+      fullText,
+      detection.start,
+      detection.end
+    );
+    const confirmedList = confirmed.filter((d) => d.disposition === "confirmed").map((d) => `${d.text} (${d.entityType})`).slice(0, 10);
+    return `You are a PII detection system. Determine if the highlighted span is personally identifiable information.
+
+Context: "${contextWindow}"
+Span: "${detection.text}"
+BERT suggested: ${detection.entityType} (confidence: ${detection.score.toFixed(2)})
+${confirmedList.length > 0 ? `Other confirmed entities in document: [${confirmedList.join(", ")}]` : ""}
+
+Is this span PII? If yes, what type? If it's ambiguous (e.g., "Jordan" could be a person or country), use the context to decide.
+
+Respond with ONLY a JSON object: { "type": "PERSON"|"LOCATION"|"ORGANIZATION"|"NONE", "confidence": 0.0-1.0 }`;
+  }
+  /** Extract ±N sentences around a span */
+  extractSentenceContext(text, start, end) {
+    const n = this.config.contextSentences;
+    const sentenceBreaks = [0];
+    const sentenceRegex = /[.!?]+\s+/g;
+    let match;
+    while ((match = sentenceRegex.exec(text)) !== null) {
+      sentenceBreaks.push(match.index + match[0].length);
+    }
+    sentenceBreaks.push(text.length);
+    let spanSentenceIdx = 0;
+    for (let i = 0; i < sentenceBreaks.length - 1; i++) {
+      if (sentenceBreaks[i] <= start && start < sentenceBreaks[i + 1]) {
+        spanSentenceIdx = i;
+        break;
+      }
+    }
+    const contextStart = sentenceBreaks[Math.max(0, spanSentenceIdx - n)];
+    const contextEnd = sentenceBreaks[Math.min(sentenceBreaks.length - 1, spanSentenceIdx + n + 1)];
+    return text.slice(contextStart, contextEnd).trim();
+  }
+  /** Parse the LLM response JSON */
+  parseResponse(response) {
+    try {
+      const jsonMatch = response.match(/\{[^}]+\}/);
+      if (!jsonMatch) return null;
+      const parsed = JSON.parse(jsonMatch[0]);
+      if (typeof parsed.type === "string" && typeof parsed.confidence === "number") {
+        return parsed;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/cascade/cascade.ts
+var DEFAULT_CASCADE_CONFIG = {
+  escalationThreshold: 0.75,
+  contextSentences: 3,
+  bertEnabled: true,
+  llmEnabled: false,
+  modelId: "Xenova/bert-base-NER"
+};
+var CascadeClassifier = class {
+  config;
+  bertLayer = null;
+  llmLayer;
+  regexGuards = [];
+  constructor(config) {
+    this.config = { ...DEFAULT_CASCADE_CONFIG, ...config };
+    this.llmLayer = new LlmLayer({
+      contextSentences: this.config.contextSentences,
+      provider: this.config.llmProvider
+    });
+  }
+  /** Whether the cascade is ready to serve (BERT model loaded if enabled) */
+  get ready() {
+    if (!this.config.bertEnabled) return true;
+    if (!this.bertLayer) return true;
+    return this.bertLayer.loaded;
+  }
+  /** Register regex-based guards (Layer 1) */
+  addRegexGuard(guard) {
+    this.regexGuards.push(guard);
+    return this;
+  }
+  /** Set the LLM provider for Layer 3 */
+  setLlmProvider(provider) {
+    this.config.llmProvider = provider;
+    this.llmLayer.setProvider(provider);
+  }
+  /**
+   * Run the full cascade: Regex → BERT → LLM
+   * Returns a unified GuardResult with all detections carrying provenance.
+   */
+  async deepScan(text) {
+    const regexDetections = await this.runRegexLayer(text);
+    if (!this.config.bertEnabled) {
+      return this.buildCascadeResult(text, regexDetections);
+    }
+    const bertDetections = await this.runBertLayer(text);
+    const mergedBert = this.deduplicateAgainstRegex(
+      bertDetections,
+      regexDetections
+    );
+    const allDetections = [...regexDetections, ...mergedBert];
+    const escalated = allDetections.filter((d) => d.disposition === "escalate");
+    if (!this.config.llmEnabled || escalated.length === 0 || !this.config.llmProvider) {
+      return this.buildCascadeResult(text, allDetections);
+    }
+    const confirmed = allDetections.filter((d) => d.disposition === "confirmed");
+    const resolved = await this.llmLayer.disambiguate(
+      escalated,
+      text,
+      confirmed
+    );
+    const finalDetections = [
+      ...allDetections.filter((d) => d.disposition !== "escalate"),
+      ...resolved
+    ];
+    return this.buildCascadeResult(text, finalDetections);
+  }
+  /** Run Layer 1 only (for fast auto-scan path) */
+  async regexScan(text) {
+    const detections = await this.runRegexLayer(text);
+    return this.buildCascadeResult(text, detections);
+  }
+  /** Run Layers 1 + 2 only (no LLM, for "Scan File" command) */
+  async modelScan(text) {
+    const regexDetections = await this.runRegexLayer(text);
+    if (!this.config.bertEnabled) {
+      return this.buildCascadeResult(text, regexDetections);
+    }
+    const bertDetections = await this.runBertLayer(text);
+    const mergedBert = this.deduplicateAgainstRegex(
+      bertDetections,
+      regexDetections
+    );
+    return this.buildCascadeResult(text, [...regexDetections, ...mergedBert]);
+  }
+  // --- Private methods ---
+  async runRegexLayer(text) {
+    const allDetections = [];
+    for (const guard of this.regexGuards) {
+      const result = await guard.analyze(text);
+      allDetections.push(...result.detections);
+    }
+    return allDetections;
+  }
+  async runBertLayer(text) {
+    if (!this.bertLayer) {
+      this.bertLayer = new BertLayer({
+        modelId: this.config.modelId,
+        escalationThreshold: this.config.escalationThreshold
+      });
+    }
+    return this.bertLayer.analyze(text);
+  }
+  /** Remove BERT detections that overlap with regex detections */
+  deduplicateAgainstRegex(bertDetections, regexDetections) {
+    return bertDetections.filter((bert) => {
+      return !regexDetections.some(
+        (regex) => bert.start < regex.end && bert.end > regex.start
+      );
+    });
+  }
+  buildCascadeResult(text, detections) {
+    const activeDetections = detections.filter(
+      (d) => d.disposition !== "dismissed"
+    );
+    const passed = activeDetections.length === 0;
+    const score = activeDetections.length > 0 ? Math.max(...activeDetections.map((d) => d.score)) : 0;
+    const sources = [...new Set(detections.map((d) => d.source))];
+    const types = [...new Set(activeDetections.map((d) => d.entityType))];
+    return {
+      passed,
+      reason: passed ? "No issues detected" : `Detected via ${sources.join("+")}: ${types.join(", ")}`,
+      guardName: "cascade",
+      score,
+      detections
+    };
+  }
+  /** Clean up resources */
+  async dispose() {
+    if (this.bertLayer) {
+      await this.bertLayer.dispose();
+      this.bertLayer = null;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BertLayer,
+  CascadeClassifier,
+  LlmLayer
+});
+//# sourceMappingURL=index.js.map