@devilsdev/rag-core 3.8.0 → 3.8.2

package/dist/index.cjs

@@ -302,6 +302,19 @@ var require_plugin_signature_verifier = __commonJS({
         format: "jwk"
       });
     }
+    function rejectReservedKeys(value) {
+      if (value === null || typeof value !== "object") return;
+      if (Array.isArray(value)) {
+        value.forEach(rejectReservedKeys);
+        return;
+      }
+      for (const key of Object.keys(value)) {
+        if (key === "__proto__") {
+          throw new Error(`Invalid manifest: reserved key "${key}"`);
+        }
+        rejectReservedKeys(value[key]);
+      }
+    }
     function computeContentDigest({ files = [], baseDir, contents = {} } = {}) {
       const root = path.resolve(baseDir || process.cwd());
       const entries = /* @__PURE__ */ new Map();
@@ -331,6 +344,9 @@ var require_plugin_signature_verifier = __commonJS({
       }
       return DIGEST_PREFIX + hash.digest("hex");
     }
+    function hasContentDigest(manifest) {
+      return Boolean(manifest) && Object.hasOwn(manifest, "contentDigest") && manifest.contentDigest !== void 0 && manifest.contentDigest !== null;
+    }
     var PluginSignatureVerifier = class {
       constructor(options = {}) {
         this.enabled = options.enabled !== false;
@@ -399,37 +415,13 @@ var require_plugin_signature_verifier = __commonJS({
             }
             return verificationResult;
           }
-          if (!manifest || typeof manifest !== "object") {
-            throw new Error("Invalid manifest: must be an object");
-          }
-          if (!signature || typeof signature !== "string") {
-            throw new Error("Invalid signature: must be a non-empty string");
-          }
-          if (!signerId || typeof signerId !== "string") {
-            throw new Error("Invalid signerId: must be a non-empty string");
-          }
-          const trustedKey = this.trustStore.get(signerId);
-          if (!trustedKey) {
-            throw new Error(`Untrusted signer: ${signerId}`);
-          }
-          const canonicalManifest = this._canonicalizeManifest(manifest);
-          const manifestData = Buffer.from(
-            JSON.stringify(canonicalManifest),
-            "utf8"
-          );
-          const signatureBuffer = Buffer.from(signature, "base64");
-          const isValid = await this._verifyEd25519Signature(
-            manifestData,
-            signatureBuffer,
-            trustedKey.publicKey
-          );
-          if (!isValid) {
-            throw new Error("Signature verification failed");
-          }
-          verificationResult.contentVerified = this._verifyContentDigest(
-            canonicalManifest,
+          const { canonicalManifest, contentVerified } = this.verifyManifestSync(
+            manifest,
+            signature,
+            signerId,
             content
           );
+          verificationResult.contentVerified = contentVerified;
           verificationResult.verified = true;
           verificationResult.auditTrail.push({
             action: "signature_verified",
@@ -457,6 +449,51 @@ var require_plugin_signature_verifier = __commonJS({
         this._auditVerification(verificationResult, manifest);
         return verificationResult;
       }
+      /**
+       * Synchronous signature check shared by every verification path: input
+       * validation, trusted-signer lookup, Ed25519 signature over the canonical
+       * manifest, and the contentDigest check. Does not consult `enabled` and
+       * does not write audit entries; callers decide both.
+       *
+       * @param {object} manifest - Plugin manifest
+       * @param {string} signature - Base64 encoded signature
+       * @param {string} signerId - Signer identifier
+       * @param {object} [content] - `{ files, baseDir, contents }` to check
+       *   against manifest.contentDigest (see computeContentDigest)
+       * @returns {{contentVerified: boolean, canonicalManifest: object}}
+       *   contentVerified is false when the manifest has no contentDigest
+       * @throws {Error} When the manifest must not be trusted
+       */
+      verifyManifestSync(manifest, signature, signerId, content = null) {
+        if (!manifest || typeof manifest !== "object") {
+          throw new Error("Invalid manifest: must be an object");
+        }
+        if (!signature || typeof signature !== "string") {
+          throw new Error("Invalid signature: must be a non-empty string");
+        }
+        if (!signerId || typeof signerId !== "string") {
+          throw new Error("Invalid signerId: must be a non-empty string");
+        }
+        const trustedKey = this.trustStore.get(signerId);
+        if (!trustedKey) {
+          throw new Error(`Untrusted signer: ${signerId}`);
+        }
+        const canonicalManifest = this._canonicalizeManifest(manifest);
+        const manifestData = Buffer.from(JSON.stringify(canonicalManifest), "utf8");
+        const signatureBuffer = Buffer.from(signature, "base64");
+        if (!this._checkEd25519Signature(
+          manifestData,
+          signatureBuffer,
+          trustedKey.publicKey
+        )) {
+          throw new Error("Signature verification failed");
+        }
+        const contentVerified = this._verifyContentDigest(
+          canonicalManifest,
+          content
+        );
+        return { contentVerified, canonicalManifest };
+      }
       /**
        * Check the supplied plugin content against the signed contentDigest.
        * @param {object} canonicalManifest - Signed manifest
@@ -465,9 +502,9 @@ var require_plugin_signature_verifier = __commonJS({
        * @private
        */
       _verifyContentDigest(canonicalManifest, content) {
-        const declared = canonicalManifest.contentDigest;
+        const declared = hasContentDigest(canonicalManifest) ? canonicalManifest.contentDigest : void 0;
         const hasContent = content && (Array.isArray(content.files) && content.files.length > 0 || content.contents && Object.keys(content.contents).length > 0);
-        if (declared === void 0 || declared === null) {
+        if (declared === void 0) {
           if (this.requireContentDigest) {
             throw new Error(
               "Manifest has no contentDigest; the signature does not cover the plugin code"
@@ -501,6 +538,17 @@ var require_plugin_signature_verifier = __commonJS({
        * @returns {Promise<boolean>} Verification result
        */
       async _verifyEd25519Signature(data, signature, publicKey) {
+        return this._checkEd25519Signature(data, signature, publicKey);
+      }
+      /**
+       * Synchronous form of _verifyEd25519Signature.
+       * @param {Buffer} data - Data that was signed
+       * @param {Buffer} signature - Signature bytes
+       * @param {crypto.KeyObject|Buffer|string} publicKey - Ed25519 public key
+       * @returns {boolean}
+       * @private
+       */
+      _checkEd25519Signature(data, signature, publicKey) {
         const keyObject = toEd25519PublicKey(publicKey);
         if (!Buffer.isBuffer(signature) || signature.length !== 64) {
           return false;
@@ -514,6 +562,7 @@ var require_plugin_signature_verifier = __commonJS({
        */
       _canonicalizeManifest(manifest) {
         const canonical = JSON.parse(JSON.stringify(manifest));
+        rejectReservedKeys(canonical);
         delete canonical.signature;
         delete canonical.signerId;
         delete canonical.signedAt;
@@ -681,6 +730,7 @@ var require_plugin_signature_verifier = __commonJS({
       PluginSignatureVerifier,
       createPluginVerifier,
       computeContentDigest,
+      hasContentDigest,
       toEd25519PublicKey
     };
   }
@@ -1123,6 +1173,23 @@ ${errorMessage}`
       isSignatureVerificationEnabled() {
         return Boolean(this._signatureVerifier && this._signatureVerifier.enabled);
       }
+      /**
+       * The signature verifier this registry uses (trust store, policy flags).
+       * @returns {object} The PluginSignatureVerifier
+       */
+      getSignatureVerifier() {
+        return this._signatureVerifier;
+      }
+      /**
+       * Record an audit entry for a plugin verification decision made outside the
+       * registry (for example when a configured plugin is checked before load).
+       * @param {string} action - Audit action
+       * @param {object} details - Audit details
+       * @returns {void}
+       */
+      recordAuditEntry(action, details) {
+        this._emitAuditEntry(action, details);
+      }
       /**
        * Whether plugins without a signed manifest are rejected.
        * @returns {boolean}
@@ -1370,7 +1437,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@devilsdev/rag-pipeline-utils",
-      version: "3.8.0",
+      version: "3.8.2",
       description: "Composable retrieval-augmented generation (RAG) for Node.js: grounded citations, evaluation, guardrails, hybrid retrieval and a CLI.",
       main: "dist/index.cjs",
       type: "commonjs",
@@ -1629,10 +1696,10 @@ var require_package = __commonJS({
         "why-is-node-running": "^3.2.2"
       },
       dependencies: {
-        "@devilsdev/rag-connectors": "3.8.0",
-        "@devilsdev/rag-core": "3.8.0",
-        "@devilsdev/rag-eval": "3.8.0",
-        "@devilsdev/rag-guardrails": "3.8.0",
+        "@devilsdev/rag-connectors": "3.8.2",
+        "@devilsdev/rag-core": "3.8.2",
+        "@devilsdev/rag-eval": "3.8.2",
+        "@devilsdev/rag-guardrails": "3.8.2",
         ajv: "^8.17.1",
         axios: "^1.21.0",
         chokidar: "^4.0.3",
@@ -2903,18 +2970,21 @@ var require_scoring = __commonJS({
       `\\b(${REFERENCE_WORDS})\\.?\\s+\\d+[a-z]?\\b`,
       "giu"
     );
-    var IDENTIFIER_RE = new RegExp("(\\p{L}[\\p{L}\\p{N}]*)-(\\d+)\\b", "gu");
+    var IDENTIFIER_RE = new RegExp("(?<![\\p{L}\\p{N}])(\\p{N}*)(\\p{L}[\\p{L}\\p{N}]*)-(\\d+)\\b", "gu");
     function identifiers(text) {
       if (!text || typeof text !== "string") return [];
       return [
         ...new Set(
-          [...text.matchAll(IDENTIFIER_RE)].map((m) => `id:${m[0].toLowerCase()}`)
+          [...text.matchAll(IDENTIFIER_RE)].map(
+            // m[1] is digits before the word ("2kinesin-8"), not part of it
+            (m) => `id:${m[0].slice(m[1].length).toLowerCase()}`
+          )
         )
       ];
     }
     function withoutReferences(text) {
       if (!text || typeof text !== "string") return text;
-      return text.replace(REFERENCE_RE, " ").replace(IDENTIFIER_RE, (_, word) => word);
+      return text.replace(REFERENCE_RE, " ").replace(IDENTIFIER_RE, (_, lead, word) => lead + word);
     }
     var MONTHS = [
       ["january", "jan"],
@@ -5227,11 +5297,95 @@ var require_chunking_engine = __commonJS({
   }
 });
 
+// src/retrieval/access-fields.js
+var require_access_fields = __commonJS({
+  "src/retrieval/access-fields.js"(exports2, module2) {
+    "use strict";
+    var ACCESS_KEYS = ["requiredRole", "acl"];
+    var STORED_KEY = "rag_access";
+    var NO_ACCESS = "rag:no-access";
+    function accessFields(doc) {
+      const fields = {};
+      if (doc.acl !== void 0) fields.acl = doc.acl;
+      if (doc.requiredRole !== void 0) fields.requiredRole = doc.requiredRole;
+      return fields;
+    }
+    function storedMetadata(doc) {
+      const metadata = doc.metadata || {};
+      const access = accessFields(doc);
+      return Object.keys(access).length ? { ...metadata, [STORED_KEY]: access } : metadata;
+    }
+    function readStoredMetadata(stored) {
+      if (!stored || typeof stored !== "object" || !(STORED_KEY in stored)) {
+        return { metadata: stored || {}, access: {} };
+      }
+      const { [STORED_KEY]: access, ...metadata } = stored;
+      const readable = access && typeof access === "object" && !Array.isArray(access);
+      return {
+        metadata,
+        access: readable ? accessFields(access) : { acl: [NO_ACCESS] }
+      };
+    }
+    function restrictionLists(result) {
+      const lists = [];
+      if (!result || typeof result !== "object") return lists;
+      for (const source of [result, result.metadata, result.doc]) {
+        if (!source || typeof source !== "object") continue;
+        for (const key of ACCESS_KEYS) {
+          const value = source[key];
+          if (value === void 0 || value === null || value === "") continue;
+          const roles = [].concat(value);
+          if (roles.length > 0) lists.push(roles);
+        }
+      }
+      return lists;
+    }
+    var sameRoles = (a, b) => a.length === b.length && a.every((role) => b.includes(role));
+    function mergeAccess(first, others) {
+      const have = restrictionLists(first);
+      const extra = [];
+      for (const copy of others) {
+        for (const roles of restrictionLists(copy)) {
+          if (![...have, ...extra].some((list) => sameRoles(list, roles))) {
+            extra.push(roles);
+          }
+        }
+      }
+      if (extra.length === 0) return first;
+      const merged = { ...first };
+      const free = ACCESS_KEYS.filter(
+        (key) => restrictionLists({ [key]: merged[key] }).length === 0
+      );
+      if (extra.length <= free.length) {
+        extra.forEach((roles, i) => {
+          merged[free[i]] = roles;
+        });
+        return merged;
+      }
+      const lists = [...restrictionLists(accessFields(merged)), ...extra];
+      const shared = lists[0].filter(
+        (role) => lists.every((list) => list.includes(role))
+      );
+      delete merged.requiredRole;
+      merged.acl = shared.length ? shared : [NO_ACCESS];
+      return merged;
+    }
+    module2.exports = {
+      NO_ACCESS,
+      accessFields,
+      storedMetadata,
+      readStoredMetadata,
+      mergeAccess
+    };
+  }
+});
+
 // src/retrieval/bm25-search.js
 var require_bm25_search = __commonJS({
   "src/retrieval/bm25-search.js"(exports2, module2) {
     "use strict";
     var { EventEmitter } = require("events");
+    var { accessFields } = require_access_fields();
     var scoring = require_scoring();
     var DEFAULT_CONFIG = { k1: 1.2, b: 0.75 };
     var BM25Search = class extends EventEmitter {
@@ -5320,7 +5474,8 @@ var require_bm25_search = __commonJS({
             id: doc.id,
             score,
             content: doc.content || doc.text || "",
-            metadata: doc.metadata || {}
+            metadata: doc.metadata || {},
+            ...accessFields(doc)
           });
         }
         results.sort((a, b2) => b2.score - a.score);
@@ -5362,6 +5517,7 @@ var require_bm25_search = __commonJS({
 var require_rank_fusion = __commonJS({
   "src/retrieval/rank-fusion.js"(exports2, module2) {
     "use strict";
+    var { mergeAccess } = require_access_fields();
     var DEFAULT_CONFIG = { k: 60 };
     function reciprocalRankFusion(resultSets, options = {}) {
       const { k = DEFAULT_CONFIG.k, weights } = options;
@@ -5385,15 +5541,17 @@ var require_rank_fusion = __commonJS({
           if (scoreMap.has(id)) {
             const entry = scoreMap.get(id);
             entry.score += rrfScore;
+            entry.copies.push(doc);
           } else {
             const { score: _origScore, ...rest } = doc;
-            scoreMap.set(id, { score: rrfScore, fields: rest });
+            scoreMap.set(id, { score: rrfScore, fields: rest, copies: [] });
           }
         }
       }
       const fused = [];
       for (const [id, entry] of scoreMap) {
-        fused.push({ ...entry.fields, id, score: entry.score });
+        const fields = mergeAccess(entry.fields, entry.copies);
+        fused.push({ ...fields, id, score: entry.score });
       }
       fused.sort((a, b) => b.score - a.score);
       return fused;
@@ -7285,6 +7443,7 @@ var require_memory_retriever = __commonJS({
     var { randomBytes } = require("crypto");
     var { BaseConnector } = require_base_connector();
     var { throwIfAborted } = require_connector_utils();
+    var { accessFields } = require_access_fields();
     var DEFAULT_CONFIG = {
       maxDocuments: 1e5,
       // 'error' rejects a store() that would exceed maxDocuments; 'fifo' evicts
@@ -7366,7 +7525,8 @@ var require_memory_retriever = __commonJS({
           this.documents.set(doc.id, {
             vector: doc.vector,
             metadata: doc.metadata || {},
-            content: doc.content || ""
+            content: doc.content || "",
+            ...accessFields(doc)
           });
         }
         if (vectors.length > 0) this.dimensions = dimensions;
@@ -7424,7 +7584,8 @@ var require_memory_retriever = __commonJS({
             id,
             score,
             metadata: doc.metadata,
-            content: doc.content
+            content: doc.content,
+            ...accessFields(doc)
           });
         }
         results.sort((a, b) => b.score - a.score);
@@ -7592,6 +7753,7 @@ var modules = {
   "reranker/cascade-reranker.js": () => require_cascade_reranker(),
   "reranker/embedding-reranker.js": () => require_embedding_reranker(),
   "reranker/scoring-reranker.js": () => require_scoring_reranker(),
+  "retrieval/access-fields.js": () => require_access_fields(),
   "retrieval/bm25-search.js": () => require_bm25_search(),
   "retrieval/hybrid-retriever.js": () => require_hybrid_retriever(),
   "retrieval/rank-fusion.js": () => require_rank_fusion(),

package/dist/types/config/component-factory.d.ts

@@ -24,9 +24,11 @@ export function buildComponents(config: object, options?: {
 /**
  * Instantiate a custom plugin from `plugins.<stage>.<name>` in the config.
  * The module may export a class (constructed with the entry config), an
- * instance, or either of those as `default`.
+ * instance, or either of those as `default`. When the shared plugin registry
+ * has signature verification enabled (production by default), the module is
+ * verified against its signed manifest before it is loaded.
  */
-export function loadPluginModule(modulePath: any, entryConfig: any, configDir: any): any;
+export function loadPluginModule(modulePath: any, entryConfig: any, configDir: any, name: any): any;
 export namespace BUILT_INS {
     namespace loader {
         function auto(): typeof import("../loader/document-reader");

package/dist/types/config/load-plugin-config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Loads plugins from validated _config path and registers them.
+ * @param {string} configPath
+ */
+export function loadPluginsFromJson(configPath: string): Promise<void>;
+/**
+ * Verify a plugin file against its signed manifest BEFORE it is imported
+ * (importing runs the plugin's code).
+ *
+ * The manifest is read from `<plugin file>.manifest.json`. Its
+ * `contentDigest` (if any) must cover the plugin file plus any extra files
+ * listed in `manifest.files` (paths relative to the plugin file's
+ * directory). Nothing is checked when the registry's signature verification
+ * is disabled; when it is enabled and the registry was created with
+ * `requireSignedPlugins: true`, a missing manifest is an error.
+ *
+ * @param {string} name - Plugin name
+ * @param {string} absPath - Absolute path of the plugin entry file
+ * @returns {Promise<void>}
+ */
+export function verifyPluginBeforeImport(name: string, absPath: string): Promise<void>;
+/**
+ * Synchronous form of verifyPluginBeforeImport for loaders that `require`
+ * the plugin. Same policy: nothing happens while the registry's signature
+ * verification is disabled; otherwise a plugin with a manifest must have a
+ * valid signature from a trusted signer and matching content, and a plugin
+ * without one loads with a one-time warning unless the registry requires
+ * signed plugins. Every check completes before any plugin code runs.
+ *
+ * @param {string} name - Plugin name
+ * @param {string} absPath - Absolute path of the file that will be loaded
+ * @returns {void}
+ * @throws {Error} When the plugin must not be loaded
+ */
+export function verifyPluginBeforeLoad(name: string, absPath: string): void;

package/dist/types/config/validate-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Validates the full .ragrc.json _config structure
+ * @param {object} config
+ * @returns {{ valid: boolean, errors?: any[] }}
+ */
+export function validateRagrcSchema(config: object): {
+    valid: boolean;
+    errors?: any[];
+};
+/**
+ * Validates a plugin-only structure (for runtime plugin loading)
+ * @param {object} config
+ * @returns {{ valid: boolean, errors?: any[] }}
+ */
+export function validatePluginSchema(config: object): {
+    valid: boolean;
+    errors?: any[];
+};

package/dist/types/core/plugin-registry.d.ts

@@ -113,6 +113,19 @@ declare class PluginRegistry {
      * @returns {boolean}
      */
     isSignatureVerificationEnabled(): boolean;
+    /**
+     * The signature verifier this registry uses (trust store, policy flags).
+     * @returns {object} The PluginSignatureVerifier
+     */
+    getSignatureVerifier(): object;
+    /**
+     * Record an audit entry for a plugin verification decision made outside the
+     * registry (for example when a configured plugin is checked before load).
+     * @param {string} action - Audit action
+     * @param {object} details - Audit details
+     * @returns {void}
+     */
+    recordAuditEntry(action: string, details: object): void;
     /**
      * Whether plugins without a signed manifest are rejected.
      * @returns {boolean}

package/dist/types/ecosystem/plugin-probe.d.ts

@@ -12,6 +12,18 @@ export function probeContract(modulePath: string, stage: string, options?: {
     methods: string[];
     error?: string;
 }>;
+/**
+ * Environment for the probe process: only what Node needs to start, so the
+ * plugin code being loaded does not see the caller's other variables. HOME,
+ * NODE_OPTIONS and NODE_PATH are left out on purpose.
+ *
+ * @param {string} [platform] - Defaults to process.platform
+ * @param {object} [source] - Defaults to process.env
+ * @returns {Object<string, string>}
+ */
+export function probeEnvironment(platform?: string, source?: object): {
+    [x: string]: string;
+};
 export namespace STAGE_METHODS {
     let loader: string[];
     let embedder: string[];

package/dist/types/ecosystem/plugin-scanner.d.ts

@@ -1,12 +1,20 @@
 /**
+ * Besides files with a source extension, the package entry file and any
+ * file a scanned file loads by relative path are scanned whatever their
+ * extension, because Node runs them as JavaScript.
+ *
  * @param {string} pluginPath - Plugin directory or single .js file
+ * @param {object} [options]
+ * @param {string} [options.entry] - Package entry file (absolute or relative to pluginPath)
  * @returns {{
  *   findings: Array<{severity: string, rule: string, message: string, file: string, line?: number}>,
  *   counts: {high: number, medium: number, low: number},
  *   filesScanned: number
  * }}
  */
-export function scanPlugin(pluginPath: string): {
+export function scanPlugin(pluginPath: string, options?: {
+    entry?: string;
+}): {
     findings: Array<{
         severity: string;
         rule: string;

package/dist/types/enterprise/audit-logging.d.ts

@@ -65,8 +65,11 @@ export class AuditLogger extends EventEmitter {
     };
     logBuffer: any[];
     encryptionKey: string | Buffer<ArrayBufferLike>;
-    signingKey: any;
-    sequenceNumber: number;
+    signingKey: string | Buffer<ArrayBufferLike>;
+    _chainState: any;
+    _chainLoad: any;
+    _chainDirty: boolean;
+    _flushQueue: Promise<void>;
     /**
      * Initialize audit logging system
      */
@@ -105,9 +108,20 @@ export class AuditLogger extends EventEmitter {
      */
     _writeAuditLog(auditEvent: any): Promise<any>;
     /**
-     * Flush logs to persistent storage
+     * Flush logs to persistent storage. Flushes run one at a time, so records
+     * are numbered and chained in the order they are appended.
      */
     _flushLogs(): Promise<void>;
+    _flushOnce(): Promise<void>;
+    _endsMidLine(file: any): Promise<boolean>;
+    _stripChainFields(log: any): void;
+    /**
+     * Give each record its sequence, the link to the previous record, the key
+     * id, the integrity hash and (when signing is on) the signature, advancing
+     * `state` as it goes.
+     * @private
+     */
+    private _numberRecords;
     /**
      * Query audit logs
      */
@@ -115,13 +129,14 @@ export class AuditLogger extends EventEmitter {
         results: any[];
         total: number;
         hasMore: boolean;
+        skippedLines: number;
     }>;
     /**
      * Generate compliance report
      */
     generateComplianceReport(_options: any): Promise<{
         metadata: {
-            _tenantId: any;
+            _tenantId: string;
             standard: any;
             period: {
                 startDate: any;
@@ -148,7 +163,24 @@ export class AuditLogger extends EventEmitter {
         evidence: any[];
     }>;
     /**
-     * Verify log integrity
+     * Verify log integrity.
+     *
+     * Besides the per-record checks it reads the chain: every record carries its
+     * sequence, a link to the previous record and a keyed hash over the whole
+     * record, and the chain file holds the latest state.
+     *
+     * - `integrityBreaks`: `{ file, line, sequence, reason }`, where reason is
+     *   `edited`, `chain`, `order`, `tail`, `unparseable`, `chain file missing`,
+     *   `chain file reset` or `chain file forged`.
+     * - `missingLogs`: gaps in the sequence, `{ after, before, count }`.
+     * - `unchained`: records written before chain links existed (counted, and
+     *   they do not make `verified` false).
+     * - `otherKey`: records written with another signing key; they can't be
+     *   checked, so `verified` is false.
+     * - `secondWriter`: duplicate or interleaved sequences that look like two
+     *   writers on one log directory. A break is only reported here when every
+     *   record involved verifies and every interleaved run links up on its own;
+     *   otherwise it is reported as the tampering it may be.
      */
     verifyIntegrity(_options?: {}): Promise<{
         verified: boolean;
@@ -157,6 +189,15 @@ export class AuditLogger extends EventEmitter {
         tamperedLogs: any[];
         missingLogs: any[];
         integrityBreaks: any[];
+        unchained: {
+            count: number;
+            ranges: any[];
+        };
+        otherKey: {
+            count: number;
+            ranges: any[];
+        };
+        secondWriter: any[];
     }>;
     _calculateIntegrityHash(auditEvent: any): Promise<string>;
     _encryptSensitiveFields(auditEvent: any): Promise<any>;
@@ -190,9 +231,89 @@ export class AuditLogger extends EventEmitter {
      */
     _getCipherKey(): Buffer<ArrayBufferLike>;
     _createDecipher(encryptedField: any): crypto.DecipherGCM;
-    _generateSigningKey(): Buffer<ArrayBufferLike>;
-    _initializeIntegrityChain(): Promise<void>;
-    _updateIntegrityChain(logs: any): Promise<void>;
+    /**
+     * Resolve the key behind the integrity hashes, chain links and signatures.
+     *
+     * Order: the `signingKey` option, then the RAG_AUDIT_SIGNING_KEY env var,
+     * then a key stored in `<logDir>/integrity/signing.key` (created on first
+     * use), and only if that file can't be used a random per-process key. A
+     * stored key lets the logs be checked after a restart, but anyone who can
+     * read the log folder can read it, so it only detects accidental damage and
+     * casual edits. Both of the last two warn once per process.
+     *
+     * @param {Object} _options - Constructor options
+     * @returns {Buffer|string} Key material
+     * @private
+     */
+    private _resolveSigningKey;
+    /**
+     * The key stored in `<logDir>/integrity/signing.key` as 128 hex digits and
+     * a newline, created if it doesn't exist yet. It is created with the 'wx'
+     * flag, so of several processes starting together exactly one writes it and
+     * the rest read what it wrote (briefly retrying while it is still empty).
+     * Modes are owner-only (0o600 file, 0o700 directory); Windows ignores POSIX
+     * modes. A file that exists but is unreadable or invalid is never
+     * overwritten. It lives next to chain.json, not under daily/, so it is never
+     * read as a log file.
+     * @returns {{key: ?Buffer, file: string, reason?: string}}
+     * @private
+     */
+    private _storedSigningKey;
+    _hmac(text: any): string;
+    _keyId(): string;
+    _genesisLink(chainId: any): string;
+    _chainLink(chainPrev: any, integrity: any): string;
+    _stateTag(chainId: any, sequence: any, lastHash: any): string;
+    _chainFilePath(): string;
+    /**
+     * Read chain.json. Status is `missing`, `unreadable`, `legacy` (a file from
+     * before 3.8.2), `invalid` (wrong shape, or a state tag that doesn't match
+     * under this key), `otherKey` (written with another signing key) or `ok`.
+     * @private
+     */
+    private _readChainFile;
+    /**
+     * The chain state (chain id, last sequence and link), loaded once, at the
+     * first write.
+     * @private
+     */
+    private _loadChainState;
+    /**
+     * Work out where the chain stands before the first write of this process.
+     *
+     * - chain.json is valid and the newest records don't go past it: continue.
+     * - Records go past it and link from it (the process ended after the
+     *   file was appended to but before chain.json was rewritten): advance the state and continue.
+     * - Otherwise (chain.json missing, replaced, not valid under this key, or
+     *   records that don't link) a new chain segment starts. It is never
+     *   silent: it is recorded in chain.json `resets`, logged as a warning and
+     *   emitted as `chain_reset`, and the sequence carries on from the highest
+     *   one in the files. A chain problem never blocks logging.
+     * @private
+     */
+    private _recoverChainState;
+    /** Chained records of the newest daily file that has any, in file order. */
+    _newestChainedRecords(files: any): Promise<any[]>;
+    /**
+     * Move `state` forward over `records` if they continue it exactly: this
+     * key, consecutive sequences, each linked to the one before and with a
+     * valid hash. Leaves `state` alone otherwise.
+     * @private
+     */
+    private _advanceThrough;
+    /**
+     * Start a chain: fresh when no chained records exist yet (keeping the
+     * values of a pre-3.8.2 chain.json under `legacy`), or a new segment that
+     * continues the sequence when they do.
+     * @private
+     */
+    private _startChainSegment;
+    /**
+     * Write chain.json with the latest state. If the write fails the state is
+     * kept and written on the next flush.
+     * @private
+     */
+    private _persistChainState;
     _signAuditEvent(auditEvent: any): Promise<string>;
     _verifySignature(auditEvent: any): Promise<boolean>;
     /**
@@ -203,14 +324,26 @@ export class AuditLogger extends EventEmitter {
      * @private
      */
     private _getLogFilesInRange;
-    _readLogFile(filepath: any): Promise<any[]>;
+    /**
+     * Every non-blank line of a daily file (queryLogs() counts the unreadable ones as skippedLines) as `{ line, record }`, where `record`
+     * is null when the line isn't a JSON object (a half-written or damaged
+     * line). `line` counts from 1.
+     */
+    _readLogEntries(filepath: any): Promise<any[]>;
+    /**
+     * The tenant a query asks for, or undefined when it names none. A tenantId
+     * (or the underscore form `_tenantId`, read only when `tenantId` is absent)
+     * that is present must be a string: null, undefined and other types used to
+     * match every tenant.
+     * @private
+     */
+    private _resolveTenantFilter;
     _matchesQuery(log: any, query: any): boolean;
     _checkCompliance(log: any, standard: any): {
         requirement: any;
         violation: boolean;
         evidence: any;
     };
-    _sendToWebhook(logs: any): Promise<void>;
     /**
      * Cleanup old logs based on retention policy
      */

package/dist/types/guardrails/guardrails-pipeline.d.ts

@@ -21,6 +21,12 @@ export class GuardrailsPipeline extends EventEmitter {
     /**
      * Run the full guarded pipeline.
      *
+     * With `options.stream` and a post-generation guard, the token stream is
+     * buffered, checked and redacted as a whole, then released as an async
+     * iterable: one token chunk with the sanitized answer, then a done chunk
+     * carrying the redacted citations/evaluation and the `guardrails` summary.
+     * A strict-mode block yields only a done chunk with `success: false`.
+     *
      * @param {object} input - Pipeline input
      * @param {string} input.query - The user query
      * @param {Float32Array} [input.queryVector] - Optional precomputed query vector
@@ -34,6 +40,28 @@ export class GuardrailsPipeline extends EventEmitter {
         options?: object;
         context?: object;
     }): Promise<object>;
+    /**
+     * Whether the retrieval guard has a check that needs documents.
+     * @private
+     */
+    private _retrievalChecksActive;
+    /**
+     * Milliseconds left of the caller's options.timeout, or undefined.
+     * @private
+     */
+    private _remainingTimeout;
+    /** @private One warning per pipeline instance. */
+    private _warnRetrievalSkipped;
+    _warnedRetrievalSkipped: boolean;
+    /**
+     * Collect a token stream, run the post-generation guard on the whole
+     * answer and return an async iterable that yields the sanitized answer as
+     * one token chunk and then the done chunk. A blocked answer yields no
+     * tokens, only a done chunk with the error.
+     *
+     * @private
+     */
+    private _releaseStream;
     /**
      * Citations and evaluation details copy sentences from the raw answer, so
      * scrub every string in them with the same PII patterns as the answer.

package/dist/types/retrieval/access-fields.d.ts

@@ -0,0 +1,38 @@
+export const NO_ACCESS: "rag:no-access";
+/**
+ * The access fields (`acl`, `requiredRole`) set on a document's top level.
+ * Stores keep them on each result, as well as whatever metadata holds, so
+ * RetrievalGuard sees a restriction wherever it was set.
+ * @param {object} doc
+ * @returns {object}
+ */
+export function accessFields(doc: object): object;
+/**
+ * The metadata to store for a document: its metadata, plus its top-level
+ * access fields under a reserved key when it has any.
+ * @param {object} doc
+ * @returns {object}
+ */
+export function storedMetadata(doc: object): object;
+/**
+ * Splits stored metadata back into the document's metadata and its
+ * top-level access fields. Unreadable access fields restrict the document
+ * to no one.
+ * @param {object} stored
+ * @returns {{ metadata: object, access: object }}
+ */
+export function readStoredMetadata(stored: object): {
+    metadata: object;
+    access: object;
+};
+/**
+ * One result for copies of the same document: the first copy's fields,
+ * restricted by every restriction any copy sets. Restrictions the first
+ * copy lacks go on its free top-level access fields; when they don't fit,
+ * its top-level restrictions and the new ones become a single list of the
+ * roles they all share, which is at least as strict.
+ * @param {object} first
+ * @param {object[]} others
+ * @returns {object}
+ */
+export function mergeAccess(first: object, others: object[]): object;

package/dist/types/security/plugin-signature-verifier.d.ts

@@ -25,6 +25,25 @@ export class PluginSignatureVerifier {
      * @returns {Promise<object>} Verification result
      */
     verifyPluginSignature(manifest: object, signature: string, signerId: string, content?: object): Promise<object>;
+    /**
+     * Synchronous signature check shared by every verification path: input
+     * validation, trusted-signer lookup, Ed25519 signature over the canonical
+     * manifest, and the contentDigest check. Does not consult `enabled` and
+     * does not write audit entries; callers decide both.
+     *
+     * @param {object} manifest - Plugin manifest
+     * @param {string} signature - Base64 encoded signature
+     * @param {string} signerId - Signer identifier
+     * @param {object} [content] - `{ files, baseDir, contents }` to check
+     *   against manifest.contentDigest (see computeContentDigest)
+     * @returns {{contentVerified: boolean, canonicalManifest: object}}
+     *   contentVerified is false when the manifest has no contentDigest
+     * @throws {Error} When the manifest must not be trusted
+     */
+    verifyManifestSync(manifest: object, signature: string, signerId: string, content?: object): {
+        contentVerified: boolean;
+        canonicalManifest: object;
+    };
     /**
      * Check the supplied plugin content against the signed contentDigest.
      * @param {object} canonicalManifest - Signed manifest
@@ -42,6 +61,15 @@ export class PluginSignatureVerifier {
      * @returns {Promise<boolean>} Verification result
      */
     _verifyEd25519Signature(data: Buffer, signature: Buffer, publicKey: crypto.KeyObject | Buffer | string): Promise<boolean>;
+    /**
+     * Synchronous form of _verifyEd25519Signature.
+     * @param {Buffer} data - Data that was signed
+     * @param {Buffer} signature - Signature bytes
+     * @param {crypto.KeyObject|Buffer|string} publicKey - Ed25519 public key
+     * @returns {boolean}
+     * @private
+     */
+    private _checkEd25519Signature;
     /**
      * Canonicalize manifest for consistent signing
      * @param {object} manifest - Plugin manifest
@@ -125,6 +153,14 @@ export function computeContentDigest({ files, baseDir, contents }?: {
         [x: string]: Buffer | string;
     };
 }): string;
+/**
+ * Whether a manifest binds the plugin code: it has a contentDigest that is
+ * neither undefined nor null. Every path that decides "digest or no digest"
+ * (verification and the missing-digest warning) uses this one test.
+ * @param {object} manifest - Plugin manifest
+ * @returns {boolean}
+ */
+export function hasContentDigest(manifest: object): boolean;
 /**
  * Convert supported public key encodings to an Ed25519 KeyObject.
  *

package/dist/types/utils/deprecate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wrap a class so constructing it (or calling a static method) emits a
+ * one-time DeprecationWarning. A Proxy keeps the original's identity for
+ * prototype, name, statics, `extends` and `instanceof`, so instances created
+ * inside the library still satisfy `instanceof Wrapped`. The same class
+ * always gets the same wrapper, so aliases stay identical.
+ *
+ * @param {Function} Class - Class to wrap
+ * @param {object} info
+ * @param {string} info.name - Export name, used in the message and code
+ * @param {string} info.message - Full warning text
+ * @returns {Function} The wrapped class
+ */
+export function deprecateClass(Class: Function, { name, message }: {
+    name: string;
+    message: string;
+}): Function;
+/**
+ * Emit a DeprecationWarning once per process for each code.
+ * @param {string} code - Warning code, e.g. RAG_DEP_...
+ * @param {string} message - Full warning text
+ */
+export function warnOnce(code: string, message: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-core",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "description": "createRagPipeline and its building blocks: retrieval, reranking, caching, cost tracking and model routing.",
   "keywords": [
     "rag",