@intflows/genkit-guard 0.0.13 → 0.1.0

package/dist/middleware/middleware.js

@@ -1,10 +1,21 @@
+import { publishDecision } from '../core/audit.js';
+import { runGuardModel } from '../util/fallback.js';
+import { GuardToolError } from '../core/decision.js';
+import { resolveGuardModels } from '../guard.config.js';
 import { generateMiddleware, z } from 'genkit';
 import { analyzeIntentStructured, detectInjection } from '../intent/intentAnalyzer.js';
 import { detectPII } from '../pii/detector.js';
 import { PiiTokenizer } from '../pii/tokenizer.js';
 import { defaultPiiVaultStorage } from '../pii/storage.js';
 const GUARD_CONTEXT_KEY = '__genkitGuard';
+const toolActionSchema = z.enum(['allow', 'block', 'redact', 'approval-required']);
 const guardConfigSchema = z.object({
+    policyVersion: z.string().optional(),
+    tools: z.object({
+        defaultAction: toolActionSchema.optional(),
+        rules: z.record(z.string(), toolActionSchema).optional(),
+        approve: z.any().optional(),
+    }).optional(),
     intent: z.object({
         mode: z.string().optional(),
         allowedIntent: z.string().optional(),
@@ -17,6 +28,11 @@ const guardConfigSchema = z.object({
         reversible: z.boolean().optional(),
         model: z.string().optional(),
         mode: z.enum(['ner', 'classifier']).optional(),
+        fallback: z.object({
+            model: z.string(), mode: z.enum(['ner', 'classifier']).optional(),
+            labelMappings: z.record(z.string(), z.string().regex(/^[A-Z_]+$/).nullable()).optional(),
+        }).optional(),
+        labelMappings: z.record(z.string(), z.string().regex(/^[A-Z_]+$/).nullable()).optional(),
         vault: z.object({
             storage: z.any().optional(),
             scopeId: z.any().optional(),
@@ -26,9 +42,12 @@ const guardConfigSchema = z.object({
         enabled: z.boolean().optional(),
         level: z.enum(['debug', 'info', 'warn', 'error']).optional(),
         serviceName: z.string().optional(),
+        onDecision: z.any().optional(),
+        store: z.any().optional(),
     }).optional(),
     models: z.object({
         extractor: z.string().optional(),
+        extractorFallback: z.string().optional(),
     }).optional(),
 }).passthrough();
 export const guardMiddleware = generateMiddleware({
@@ -40,6 +59,10 @@ export const guardPlugin = guardMiddleware.plugin;
 export function guard(config) {
     const hooks = createGuardHooks(config);
     const baseMiddleware = guardMiddleware(config);
+    // Genkit treats every function as legacy model-only middleware, ignoring tool hooks.
+    // New tool policies must use a native reference; legacy configurations stay callable.
+    if (config?.tools)
+        return Object.assign(baseMiddleware, hooks);
     const fnRunner = async (req, ctxOrNext, maybeNext) => {
         if (typeof maybeNext === 'function') {
             return hooks.model(req, ctxOrNext, maybeNext);
@@ -62,8 +85,11 @@ export function guard(config) {
 export const guardAction = guard;
 function createGuardHooks(config) {
     const logger = createLogger(config);
+    const models = resolveGuardModels(config);
+    const decide = (start, fields) => publishDecision(config, start, fields);
     return {
         model: async (req, ctx, next) => {
+            const started = performance.now();
             const input = getInputText(req);
             logger('info', 'guard.model.start', 'Starting guard checks for model request');
             const isInjection = await detectInjection(input);
@@ -71,17 +97,26 @@ function createGuardHooks(config) {
                 logger('warn', 'guard.intent.blocked', 'Prompt injection pattern detected', {
                     reason: 'pattern_match',
                 });
+                await decide(started, { guard: 'injection', action: 'block', reasonCode: 'INJECTION_PATTERN' });
                 return block('Prompt injection detected', {
                     reason: 'pattern_match',
                 });
             }
+            await decide(started, { guard: 'injection', action: 'allow', reasonCode: 'INJECTION_CLEAR' });
+            const intentStarted = performance.now();
             logger('info', 'guard.intent.analysis.start', 'Analyzing request intent');
-            const intentResult = await analyzeIntentStructured(input, config?.intent?.semantic?.intents ?? {}, config?.intent?.semantic?.threshold ?? 0.7);
+            const analyze = (model) => analyzeIntentStructured(input, config?.intent?.semantic?.intents ?? {}, config?.intent?.semantic?.threshold ?? 0.7, model);
+            const intentResult = await runGuardModel(config, 'intent', () => analyze(models.extractor), config?.models?.extractorFallback ? () => analyze(config.models.extractorFallback) : undefined);
             logger('info', 'guard.intent.analysis.complete', 'Intent analysis completed', {
                 intent: intentResult.intent,
                 score: roundScore(intentResult.score),
                 allowed: intentResult.allowed,
             });
+            await decide(intentStarted, {
+                guard: 'intent', action: intentResult.allowed ? 'allow' : 'block',
+                reasonCode: intentResult.allowed ? 'INTENT_ALLOWED' : 'INTENT_REJECTED',
+                confidence: intentResult.score,
+            });
             if (!intentResult.allowed) {
                 logger('warn', 'guard.intent.blocked', 'Intent not allowed', {
                     intent: intentResult.intent,
@@ -92,6 +127,7 @@ function createGuardHooks(config) {
                     score: intentResult.score,
                 });
             }
+            const piiStarted = performance.now();
             const textForPii = collectModelRequestText(req);
             const piiResponse = await scanPII(textForPii, config);
             const piiMatches = piiResponse?.matches || [];
@@ -100,11 +136,13 @@ function createGuardHooks(config) {
             await tokenizer.importTokens(textForPii);
             await maskModelRequest(req, tokenizer, piiMatches);
             pushTokenizer(ctx, tokenizer);
+            await decide(piiStarted, { guard: 'pii', action: piiMatches.length ? 'redact' : 'allow',
+                reasonCode: piiMatches.length ? 'PII_DETECTED' : 'PII_CLEAR' });
             logger(piiMatches.length > 0 ? 'warn' : 'info', 'guard.model.pii.masked', 'PII scan completed for model request', {
                 piiDetected: piiMatches.length > 0,
                 piiMatchCount: piiMatches.length,
                 piiTypes,
-                piiMode: config?.pii?.mode ?? 'ner',
+                piiMode: piiResponse.effectiveMode ?? models.mode,
                 classifierOutputPresent: Boolean(piiResponse.classifier),
             });
             req.metadata = {
@@ -117,6 +155,9 @@ function createGuardHooks(config) {
                 piiModel: config?.pii?.model,
                 piiMode: config?.pii?.mode,
                 piiClassifierOutput: piiResponse.classifier,
+                piiEffectiveModel: piiResponse.effectiveModel,
+                piiEffectiveMode: piiResponse.effectiveMode,
+                piiUsedFallback: piiResponse.usedFallback,
             };
             const res = await next(req, ctx);
             const unmaskedResponse = await unmaskObject(res, getGuardState(ctx).tokenizers);
@@ -126,8 +167,23 @@ function createGuardHooks(config) {
             return unmaskedResponse;
         },
         tool: async (req, ctx, next) => {
-            const state = getGuardState(ctx);
+            const started = performance.now();
             const toolName = req?.toolRequest?.name;
+            const stop = async (action, reasonCode) => {
+                throw new GuardToolError(await decide(started, { guard: 'tool', action, reasonCode }));
+            };
+            const rules = config?.tools?.rules;
+            const action = rules && Object.hasOwn(rules, toolName)
+                ? rules[toolName] : config?.tools?.defaultAction ?? 'allow';
+            if (!['allow', 'block', 'redact', 'approval-required'].includes(action)) {
+                return stop('block', 'TOOL_POLICY_ERROR');
+            }
+            if (action === 'block')
+                return stop('block', 'TOOL_BLOCKED');
+            if (action === 'approval-required' && !config?.tools?.approve) {
+                return stop('approval-required', 'TOOL_APPROVAL_REQUIRED');
+            }
+            const state = getGuardState(ctx);
             // Genkit may provide a fresh middleware context for a tool turn. Create a recovery
             // tokenizer that uses the configured vault so opaque tokens can be rehydrated safely.
             if (state.tokenizers.length === 0) {
@@ -136,6 +192,19 @@ function createGuardHooks(config) {
             if (req?.toolRequest && 'input' in req.toolRequest) {
                 req.toolRequest.input = await unmaskObject(req.toolRequest.input, state.tokenizers);
             }
+            if (action === 'approval-required') {
+                let approved;
+                try {
+                    approved = await config.tools.approve({
+                        toolName, input: structuredClone(req?.toolRequest?.input), context: ctx?.context,
+                    });
+                }
+                catch {
+                    return stop('block', 'TOOL_POLICY_ERROR');
+                }
+                if (approved !== true)
+                    return stop('block', 'TOOL_APPROVAL_DENIED');
+            }
             const toolInputText = collectStrings(req?.toolRequest?.input).join('\n');
             const piiResponse = await scanPII(toolInputText, config);
             const piiMatches = piiResponse?.matches || [];
@@ -145,6 +214,9 @@ function createGuardHooks(config) {
                 piiDetected: piiMatches.length > 0,
                 piiTypes,
                 piiMatchCount: piiMatches.length,
+                piiEffectiveModel: piiResponse.effectiveModel,
+                piiEffectiveMode: piiResponse.effectiveMode,
+                piiUsedFallback: piiResponse.usedFallback,
             };
             logger(piiMatches.length > 0 ? 'warn' : 'info', 'guard.tool.pii.checked', 'Tool request PII scan completed', {
                 toolName,
@@ -152,6 +224,18 @@ function createGuardHooks(config) {
                 piiMatchCount: piiMatches.length,
                 piiTypes,
             });
+            if (action === 'redact' && req?.toolRequest) {
+                req.toolRequest.input = await transformStrings(req.toolRequest.input, (value) => {
+                    // Irreversible redaction: do not send recoverable vault tokens to this tool.
+                    for (const match of [...piiMatches].sort((a, b) => b.value.length - a.value.length)) {
+                        if (match.value)
+                            value = value.split(match.value).join('[REDACTED]');
+                    }
+                    return value;
+                });
+            }
+            await decide(started, { guard: 'tool', action: action === 'redact' ? 'redact' : 'allow',
+                reasonCode: action === 'redact' ? 'TOOL_REDACTED' : action === 'approval-required' ? 'TOOL_APPROVED' : 'TOOL_ALLOWED' });
             const res = await next(req, ctx);
             const toolResponseText = collectStrings(res).join('\n');
             if (toolResponseText) {
@@ -247,12 +331,18 @@ async function scanPII(text, config) {
         return {
             matches: [],
             classifier: undefined,
+            effectiveModel: undefined,
+            effectiveMode: undefined,
+            usedFallback: false,
         };
     }
+    const models = resolveGuardModels(config);
     return detectPII(text, {
-        model: config?.pii?.model,
-        mode: config?.pii?.mode,
-    });
+        model: models.pii,
+        mode: models.mode,
+        labelMappings: config?.pii?.labelMappings,
+        fallback: config?.pii?.fallback,
+    }, config);
 }
 function getGuardState(ctx = {}) {
     ctx.context = ctx.context || {};

package/dist/pii/detector.d.ts

@@ -1,3 +1,5 @@
+import type { GuardConfig } from '../middleware/middleware.js';
+import type { PiiLabelMappings } from '../guard.config.js';
 export type PiiMatch = {
     type: string;
     value: string;
@@ -10,11 +12,11 @@ export type PrivacyFilterSpan = {
     end?: number;
     score?: number;
 };
-export declare function detectPII(text: string, opts?: {
-    model?: string;
-    mode?: 'ner' | 'classifier';
-}): Promise<{
+export declare function detectPII(text: string, opts?: GuardConfig['pii'], config?: GuardConfig): Promise<{
     matches: PiiMatch[];
     classifier: any;
+    effectiveModel: string;
+    effectiveMode: "ner" | "classifier";
+    usedFallback: boolean;
 }>;
-export declare function privacyFilterOutputToMatches(text: string, output: unknown): PiiMatch[];
+export declare function privacyFilterOutputToMatches(text: string, output: unknown, labelMappings?: PiiLabelMappings): PiiMatch[];

package/dist/pii/detector.js

@@ -1,3 +1,4 @@
+import { runGuardModel } from '../util/fallback.js';
 import { ModelSingleton } from '../util/singleton.js';
 const PRIVACY_FILTER_TYPE_MAP = {
     account_number: 'ACCOUNT_NUMBER',
@@ -25,7 +26,7 @@ const REGEX_RULES = [
     // CREDIT CARD (keep your existing one if needed)
     { type: 'CREDIT_CARD', pattern: /\b(?:\d[ -]*?){13,16}\b/g }
 ];
-export async function detectPII(text, opts) {
+export async function detectPII(text, opts, config) {
     const mode = opts?.mode ?? 'ner';
     const model = opts?.model;
     const results = [];
@@ -34,34 +35,49 @@ export async function detectPII(text, opts) {
         const matches = text.match(rule.pattern) || [];
         matches.forEach(m => results.push({ type: rule.type, value: m }));
     }
-    // ---- NER ----
+    // Only model loading/inference is retried. Label mapping errors are not model failures.
+    const infer = async (selected, usedFallback = false) => {
+        const selectedMode = selected.mode ?? mode;
+        const pipeline = selectedMode === 'ner'
+            ? await ModelSingleton.getNER(selected.model)
+            : await ModelSingleton.getPIIClassifier(selected.model);
+        const output = selectedMode === 'ner' ? await pipeline(text)
+            : await pipeline(text, { aggregation_strategy: 'simple' });
+        if (!Array.isArray(output))
+            throw new Error('Invalid PII model output');
+        return { output, mode: selectedMode, labelMappings: selected.labelMappings, usedFallback,
+            model: selected.model ?? (selectedMode === 'ner' ? 'Xenova/bert-base-NER' : 'openai/privacy-filter') };
+    };
+    const selected = await runGuardModel(config, 'pii', () => infer({ model, mode, labelMappings: opts?.labelMappings }), opts?.fallback ? () => infer(opts.fallback, true) : undefined);
     let classifierOutput = undefined;
-    if (mode === 'ner') {
-        const ner = await ModelSingleton.getNER(model);
-        const entities = await ner(text);
-        for (const e of entities) {
-            if (e.entity && e.entity.includes('PER')) {
+    if (selected.mode === 'ner') {
+        for (const e of selected.output) {
+            const mappedType = mappedLabel(e.entity_group ?? e.entity, selected.labelMappings);
+            if (mappedType !== undefined) {
+                if (mappedType)
+                    results.push(...privacyFilterOutputToMatches(text, [e], selected.labelMappings));
+            }
+            else if (e.entity && e.entity.includes('PER')) {
                 results.push({ type: 'NAME', value: (e.word || '').replace(/##/g, '') });
             }
         }
     }
     else {
-        // Privacy Filter is a token-classification model. Aggregation produces complete spans
-        // rather than individual BIOES-labelled tokens.
-        const cls = await ModelSingleton.getPIIClassifier(model);
-        classifierOutput = await cls(text, { aggregation_strategy: 'simple' });
-        for (const match of privacyFilterOutputToMatches(text, classifierOutput)) {
-            if (!results.some((existing) => existing.value === match.value)) {
+        classifierOutput = selected.output;
+        for (const match of privacyFilterOutputToMatches(text, classifierOutput, selected.labelMappings)) {
+            if (!results.some((existing) => existing.value === match.value))
                 results.push(match);
-            }
         }
     }
     return {
         matches: results,
-        classifier: classifierOutput
+        classifier: classifierOutput,
+        effectiveModel: selected.model,
+        effectiveMode: selected.mode,
+        usedFallback: selected.usedFallback,
     };
 }
-export function privacyFilterOutputToMatches(text, output) {
+export function privacyFilterOutputToMatches(text, output, labelMappings) {
     if (!Array.isArray(output))
         return [];
     const matches = [];
@@ -73,7 +89,8 @@ export function privacyFilterOutputToMatches(text, output) {
         if (typeof rawLabel !== 'string')
             continue;
         const label = rawLabel.replace(/^[BIES]-/, '').toLowerCase();
-        const type = PRIVACY_FILTER_TYPE_MAP[label];
+        const customType = mappedLabel(rawLabel, labelMappings);
+        const type = customType !== undefined ? customType : (Object.hasOwn(PRIVACY_FILTER_TYPE_MAP, label) ? PRIVACY_FILTER_TYPE_MAP[label] : undefined);
         if (!type)
             continue;
         let value;
@@ -95,3 +112,16 @@ export function privacyFilterOutputToMatches(text, output) {
     }
     return matches;
 }
+function mappedLabel(label, mappings) {
+    if (typeof label !== 'string' || !mappings)
+        return undefined;
+    const normalize = (value) => value.replace(/^[BIES]-/i, '').toLowerCase();
+    const entry = Object.entries(mappings).find(([key]) => normalize(key) === normalize(label));
+    if (!entry)
+        return undefined;
+    const type = entry[1];
+    if (type !== null && !/^[A-Z_]+$/.test(type)) {
+        throw new Error('PII label mapping types must contain only uppercase letters and underscores');
+    }
+    return type;
+}

package/dist/util/fallback.d.ts

@@ -0,0 +1,8 @@
+import type { GuardConfig } from '../middleware/middleware.js';
+export declare class GuardModelError extends Error {
+    readonly guard: 'intent' | 'pii';
+    readonly code = "MODEL_UNAVAILABLE";
+    constructor(guard: 'intent' | 'pii');
+}
+/** One fallback attempt per operation, only after a model operation throws. */
+export declare function runGuardModel<T>(config: GuardConfig | undefined, guard: 'intent' | 'pii', primary: () => Promise<T>, fallback?: () => Promise<T>): Promise<T>;

package/dist/util/fallback.js

@@ -0,0 +1,32 @@
+import { publishDecision } from '../core/audit.js';
+export class GuardModelError extends Error {
+    guard;
+    code = 'MODEL_UNAVAILABLE';
+    constructor(guard) {
+        // Do not attach underlying errors: inference errors can contain request content.
+        super(`Primary and fallback ${guard} models failed`);
+        this.guard = guard;
+        this.name = 'GuardModelError';
+    }
+}
+/** One fallback attempt per operation, only after a model operation throws. */
+export async function runGuardModel(config, guard, primary, fallback) {
+    const start = performance.now();
+    try {
+        return await primary();
+    }
+    catch (error) {
+        if (!fallback)
+            throw error; // Preserve existing failure behavior without opt-in.
+    }
+    let result;
+    try {
+        result = await fallback();
+    }
+    catch {
+        await publishDecision(config, start, { guard, action: 'block', reasonCode: 'MODEL_UNAVAILABLE' });
+        throw new GuardModelError(guard);
+    }
+    await publishDecision(config, start, { guard, action: 'allow', reasonCode: 'MODEL_FALLBACK_USED' });
+    return result;
+}

package/package.json

@@ -22,7 +22,7 @@
     "huggingface"
   ],
   "license": "Apache-2.0",
-  "version": "0.0.13",
+  "version": "0.1.0",
   "type": "module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,13 +36,17 @@
     "prepare-models": "node scripts/download-model.js",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc",
-    "test": "npm run test:types && npm run test:privacy-filter && npm run test:storage && npm run test:concurrency",
+    "test": "npm run test:types && npm run test:privacy-filter && npm run test:storage && npm run test:concurrency && npm run test:config && npm run test:release1 && npm run test:release2",
     "test:types": "tsc --noEmit --ignoreConfig --module NodeNext --moduleResolution NodeNext --target ESNext --strict --skipLibCheck scripts/test-types.ts",
     "test:privacy-filter": "npm run build && node scripts/test-privacy-filter.js",
     "test:storage": "npm run build && node scripts/test-storage.js",
     "test:concurrency": "npm run build && node scripts/test-concurrent-vault.js",
     "test:redis": "npm run build && node scripts/test-redis-vault.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test:config": "npm run build && node scripts/test-config.js",
+    "wiki:publish": "node scripts/publish-wiki.js",
+    "test:release1": "npm run build && node --test scripts/test-release1.js scripts/test-publish-wiki.js",
+    "test:release2": "npm run build && node --test scripts/test-release2.js"
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",

package/scripts/publish-wiki.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readdirSync, copyFileSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+let source = join(root, 'docs/wiki-v0.1.0');
+let repository = 'https://github.com/IntFlows/genkit-guard.wiki.git';
+let publish = false;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--publish') publish = true;
+  else if (['--source', '--repo'].includes(args[i])) {
+    const flag = args[i];
+    const value = args[++i];
+    if (!value || value.startsWith('-')) throw new Error(`Missing value for ${flag}`);
+    if (flag === '--source') source = resolve(value);
+    else repository = value;
+  } else if (args[i] === '--help') {
+    console.log('node scripts/publish-wiki.js [--source DIRECTORY] [--repo URL] [--publish]');
+    console.log('Default: clone wiki and preview diff. --publish commits and pushes changed numbered pages.');
+    process.exit(0);
+  } else throw new Error(`Unknown option: ${args[i]}`);
+}
+source = realpathSync(source);
+const pages = readdirSync(source, { withFileTypes: true })
+  .filter(entry => entry.isFile() && /^\d+\..+\.md$/.test(entry.name)).map(entry => entry.name).sort();
+if (!pages.length) throw new Error('No numbered Markdown wiki pages found');
+const work = mkdtempSync(join(tmpdir(), 'genkit-guard-wiki-'));
+const checkout = join(work, 'wiki');
+function git(args, cwd = work) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', shell: false });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(result.stderr || result.stdout || 'Git command failed');
+  return result.stdout;
+}
+try {
+  git(['clone', '--', repository, checkout]);
+  for (const page of pages) copyFileSync(join(source, page), join(checkout, page));
+  git(['add', '--', ...pages], checkout);
+  const summary = git(['diff', '--cached', '--stat'], checkout);
+  if (!summary.trim()) console.log('Wiki already matches these pages; nothing to publish.');
+  else {
+    console.log(summary);
+    console.log(git(['diff', '--cached', '--'], checkout));
+    if (!publish) console.log('Preview only. Run again with --publish to commit and push.');
+    else {
+      git(['commit', '-m', 'Update Genkit Guard wiki documentation'], checkout);
+      // Normal push: concurrent remote updates reject safely; never force-push.
+      console.log(git(['push', 'origin', 'HEAD'], checkout));
+      console.log('Wiki changes published.');
+    }
+  }
+} finally {
+  // Only remove the temporary directory created by this process.
+  rmSync(work, { recursive: true, force: true });
+}

package/scripts/test-config.js

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import { guard, initGuard, defineGuardConfig } from '../dist/index.js';
+import { ModelSingleton } from '../dist/util/singleton.js';
+import { detectPII, privacyFilterOutputToMatches } from '../dist/pii/detector.js';
+const calls = [];
+const originals = {};
+for (const method of ['getExtractor', 'getNER', 'getPIIClassifier']) {
+  originals[method] = ModelSingleton[method];
+  ModelSingleton[method] = async (name) => {
+    calls.push([method, name]);
+    return async () => method === 'getExtractor' ? { tolist: () => [[1, 0], [1, 0]] } : [{ entity: 'B-LABEL_1', word: 'Alice' }];
+  };
+}
+try {
+  await initGuard();
+  assert.deepEqual(calls.splice(0), [['getExtractor', 'Xenova/all-MiniLM-L6-v2'], ['getNER', 'Xenova/bert-base-NER']]);
+  for (const mode of ['ner', 'classifier']) {
+    const config = defineGuardConfig({
+      models: { extractor: 'custom/intent' },
+      intent: { semantic: { intents: { support: 'Customer support' } } },
+      pii: { mode, model: 'custom/pii', labelMappings: { LABEL_1: 'NAME' } },
+      logging: { enabled: false },
+    });
+    await initGuard(config);
+    const result = await guard(config).model({ prompt: 'Help Alice' }, {}, async (req) => {
+      assert.match(req.prompt, /\[\[NAME_/);
+      assert.doesNotMatch(req.prompt, /Alice/);
+      return { text: req.prompt };
+    });
+    assert.equal(result.text, 'Help Alice');
+    const expected = [['getExtractor', 'custom/intent'], [mode === 'ner' ? 'getNER' : 'getPIIClassifier', 'custom/pii']];
+    assert.deepEqual(calls.splice(0), [...expected, ...expected]);
+  }
+  await initGuard({ pii: { mode: 'classifier' } });
+  assert.equal(calls.splice(0)[1][1], 'openai/privacy-filter');
+  assert.deepEqual(privacyFilterOutputToMatches('Alice', [{ entity: 'S-private_person', word: 'Alice' }], { private_person: null }), []);
+  assert.deepEqual(privacyFilterOutputToMatches('Alice', [{ entity: 'B-label_1', word: 'Alice' }], { LABEL_1: 'CUSTOM_NAME' }), [{ type: 'CUSTOM_NAME', value: 'Alice' }]);
+  assert.deepEqual(privacyFilterOutputToMatches('Alice', [{ entity: 'toString', word: 'Alice' }]), []);
+  assert.throws(() => privacyFilterOutputToMatches('Alice', [{ entity: 'LABEL_1', word: 'Alice' }], { LABEL_1: 'bad-token' }), /uppercase/);
+  const regex = await detectPII('alice@example.com', { mode: 'classifier', labelMappings: { LABEL_1: null } });
+  assert.equal(regex.matches[0].type, 'EMAIL');
+} finally {
+  Object.assign(ModelSingleton, originals);
+}
+console.log('Shared model configuration and compatibility tests passed.');

package/scripts/test-publish-wiki.js

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+test('wiki preview never pushes; publish updates pages and preserves unrelated files', () => {
+  const work = mkdtempSync(join(tmpdir(), 'wiki-test-'));
+  const run = (cmd, args, cwd = work) => {
+    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8', env: { ...process.env, GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 'test@example.com', GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 'test@example.com' } });
+    assert.equal(result.status, 0, result.stderr); return result.stdout;
+  };
+  try {
+    const remote = join(work, 'remote.git'); const seed = join(work, 'seed'); const source = join(work, 'pages');
+    run('git', ['init', '--bare', remote]); run('git', ['clone', remote, seed]);
+    writeFileSync(join(seed, 'Home.md'), 'Preserve me');
+    run('git', ['add', '.'], seed); run('git', ['commit', '-m', 'initial'], seed); run('git', ['push', 'origin', 'HEAD'], seed);
+    mkdirSync(source); writeFileSync(join(source, '1.-Home.md'), '# New home'); writeFileSync(join(source, 'README.md'), 'Do not publish');
+    const args = [resolve('scripts/publish-wiki.js'), '--repo', remote, '--source', source];
+    const before = run('git', ['rev-parse', 'HEAD'], remote);
+    assert.match(run(process.execPath, args), /Preview only/);
+    assert.equal(run('git', ['rev-parse', 'HEAD'], remote), before);
+    assert.match(run(process.execPath, [...args, '--publish']), /published/);
+    assert.equal(run('git', ['show', 'HEAD:1.-Home.md'], remote), '# New home');
+    assert.equal(run('git', ['show', 'HEAD:Home.md'], remote), 'Preserve me');
+    assert.doesNotMatch(run('git', ['ls-tree', '--name-only', 'HEAD'], remote), /README/);
+    assert.match(run(process.execPath, [...args, '--publish']), /nothing to publish/);
+  } finally { rmSync(work, { recursive: true, force: true }); }
+});

package/scripts/test-release1.js

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { genkit, z } from 'genkit';
+import { guard, guardMiddleware, GuardToolError } from '../dist/index.js';
+import { ModelSingleton } from '../dist/util/singleton.js';
+ModelSingleton.getExtractor = async () => async () => ({ tolist: () => [[1, 0], [1, 0]] });
+ModelSingleton.getNER = async () => async () => [];
+const base = { intent: { semantic: { intents: { support: 'Support' } } }, logging: { enabled: false } };
+const request = () => ({ toolRequest: { name: 'sendEmail', input: { email: 'alice@example.com', nested: ['alice@example.com'] } } });
+
+test('tool policies enforce before execution and redact nested arguments', async () => {
+  for (const action of ['allow', 'block', 'redact', 'approval-required']) {
+    const decisions = [];
+    const middleware = guard({ ...base, tools: { rules: { sendEmail: action } }, logging: { enabled: false, onDecision: d => decisions.push(d) } });
+    let executed = 0;
+    const run = middleware.tool(request(), {}, async req => {
+      executed++;
+      if (action === 'redact') assert.deepEqual(req.toolRequest.input, { email: '[REDACTED]', nested: ['[REDACTED]'] });
+      else assert.equal(req.toolRequest.input.email, 'alice@example.com');
+      return { toolResponse: { name: 'sendEmail', output: 'ok' } };
+    });
+    if (action === 'block' || action === 'approval-required') await assert.rejects(run, GuardToolError);
+    else await run;
+    assert.equal(executed, action === 'allow' || action === 'redact' ? 1 : 0);
+    assert.equal(decisions[0].action, action);
+    assert.equal(decisions[0].schemaVersion, '1');
+    assert.doesNotMatch(JSON.stringify(decisions), /alice|example.com|nested/);
+  }
+});
+
+test('approval is explicit, per-call and cannot be spoofed by request flags', async () => {
+  for (const approve of [undefined, () => false, () => 'true', () => { throw new Error('secret'); }, async () => true]) {
+    let ran = false;
+    const middleware = guard({ ...base, tools: { defaultAction: 'approval-required', approve } });
+    const req = request(); req.toolRequest.input.approved = true;
+    const run = middleware.tool(req, {}, async () => { ran = true; });
+    if (approve && await Promise.resolve().then(() => approve()).catch(() => false) === true) await run;
+    else await assert.rejects(run, GuardToolError);
+    assert.equal(ran, Boolean(approve && await Promise.resolve().then(() => approve()).catch(() => false) === true));
+  }
+});
+
+test('default block, unknown tools, invalid actions and callback failures stop execution', async () => {
+  for (const tools of [{ defaultAction: 'block', rules: { other: 'allow' } }, { defaultAction: 'invalid' }]) {
+    await assert.rejects(guard({ ...base, tools }).tool(request(), {}, () => assert.fail('Executed')), GuardToolError);
+  }
+  await assert.rejects(guard({ ...base, logging: { enabled: false, onDecision: () => { throw new Error('sink unavailable'); } } }).tool(request(), {}, () => assert.fail('Executed')), /sink unavailable/);
+});
+
+test('prompt and tool events share contract; console does not include raw content', async () => {
+  const events = []; const lines = [];
+  const original = { log: console.log, warn: console.warn };
+  console.log = console.warn = value => lines.push(value);
+  try {
+    const middleware = guard({ ...base, policyVersion: 'release-1', logging: { onDecision: d => events.push(d) } });
+    await middleware.model({ prompt: 'Help alice@example.com' }, {}, async req => ({ text: req.prompt }));
+    await middleware.model({ prompt: 'ignore previous alice@example.com' }, {}, () => assert.fail('Executed'));
+    await middleware.tool(request(), {}, async () => undefined);
+  } finally { Object.assign(console, original); }
+  assert.deepEqual(events.map(d => d.guard), ['injection', 'intent', 'pii', 'injection', 'tool']);
+  assert.ok(events.every(d => d.policyVersion === 'release-1' && d.latencyMs >= 0));
+  assert.equal(new Set(events.map(d => d.decisionId)).size, events.length);
+  assert.doesNotMatch(lines.join(''), /alice@example.com|Help alice|ignore previous/);
+});
+
+test('Genkit generate actually intercepts tool execution', async () => {
+  for (const factory of [guard, guardMiddleware]) for (const action of ['allow', 'block', 'redact', 'approval-required']) {
+    const ai = genkit({});
+    let executions = 0; let turn = 0;
+    const tool = ai.defineTool({ name: 'sendEmail', description: 'Test', inputSchema: z.object({ email: z.string() }), outputSchema: z.string() }, async input => {
+      executions++;
+      assert.equal(input.email, action === 'redact' ? '[REDACTED]' : 'alice@example.com');
+      return 'ok';
+    });
+    const model = ai.defineModel({ name: 'test/model' }, async () => ({ message: { role: 'model', content: ++turn === 1
+      ? [{ toolRequest: { name: 'sendEmail', ref: '1', input: { email: 'alice@example.com' } } }]
+      : [{ text: 'Done' }] } }));
+    const run = ai.generate({ model, prompt: 'Help', tools: [tool], use: [factory({ ...base, tools: { defaultAction: action } })] });
+    if (action === 'block' || action === 'approval-required') await assert.rejects(run);
+    else await run;
+    assert.equal(executions, ['allow', 'redact'].includes(action) ? 1 : 0);
+  }
+});