gateia 0.1.4 → 0.2.0

package/README.md

@@ -1,160 +1,159 @@
 # Gateia
 
-**The Trust Layer for AI in Production.**
+<div align="center">
 
-Gateia is a TypeScript-first SDK that sits between your application and LLMs. It enforces structured contracts (Zod), applies compliance policies, and provides detailed enforcement reports.
 
-It is NOT an orchestration framework. It is a trust middleware.
+**The Deterministic Verification Layer for Enterprise AI.**
 
-## Features
+[![npm version](https://img.shields.io/npm/v/gateia.svg?style=flat-square)](https://www.npmjs.com/package/gateia)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/Tests-Passing-green.svg?style=flat-square)]()
+[![Type Safety](https://img.shields.io/badge/TypeScript-Strict-blue.svg?style=flat-square)]()
 
-- **Model Routing**: Unified API for OpenAI, Gemini, and others.
-- **Contract Enforcement**: Validators ensures outputs match your Zod schemas. Auto-repair loop included.
-- **Policy Engine**: Deterministic rules to block or rewrite unsafe content.
-- **Enforcement Reporting**: Every call returns a traceId and a full report of what happened.
+</div>
 
-## Quickstart
+---
+
+**Gateia** is the standard for implementing **Deterministic Guardrails** in AI applications. It acts as a final, immutable security layer between your AI models and your customers.
+
+Unlike "AI-judging-AI" solutions, Gateia enables you to enforce **strict, code-based contracts**, ensuring that your application never halluncinates, leaks PII, or violates business rules—regardless of the underlying model (OpenAI, Anthropic, or Llama).
+
+## 🚀 Why Gateia?
+
+In production, **probability is a liability.** Gateia restores deterministic control.
+
+*   **🛡️ Zero Hallucination Policy**: Gateia does not use LLMs to verify. It uses deterministic logic and regex engines. It is impossible for the verifier to hallucinate.
+*   **🏗️ Contract-First Architecture**: Define your data requirements with Zod schemas. If the output doesn't match, it doesn't ship.
+*   **📋 Audit-Ready Logging**: Every decision is traced, logged, and categorized by severity, making compliance (SOC2, HIPAA) audits straightforward.
+*   **🔒 Fail-Closed Security**: If a policy returns a block signal (even with malformed data), Gateia defaults to blocking. Security is never compromised by runtime errors.
+
+---
+
+## 📦 Installation
 
 ```bash
 npm install gateia zod
 ```
 
-```typescript
-import { gate } from "gateia";
-import { z } from "zod";
+---
+
+## ⚡️ Quick Start
+
+Secure a loan processing agent in 30 seconds.
 
-const RefundSchema = z.object({
-  valid: z.boolean(),
+```typescript
+import { verify } from 'gateia';
+import { z } from 'zod';
+
+// 1. Define the Business Contract
+// The AI *must* return data in this shape.
+const LoanDecisionContract = z.object({
+  approved: z.boolean(),
+  rate: z.number().min(2.5).max(10.0), // Business Logic
   reason: z.string(),
-  refund_amount: z.number().max(500)
+  risk_level: z.enum(['low', 'medium', 'high'])
 });
 
-const result = await gate({
-  model: "gpt-4.1",
-  prompt: "Analyze this refund request against policy...", 
-  contract: RefundSchema,
-  policies: ["support-safe"]
+// 2. The Verification Step
+// Run this *after* your LLM generates content.
+const result = await verify({
+  output: llmResponse, 
+  contract: LoanDecisionContract,
+  policies: ['finance-safe', 'pii-safe', 'secrets-safe'],
+  mode: 'enforce'
 });
 
-console.log(result.safeOutput);
-// { valid: true, reason: "Item damaged in transit", refund_amount: 49.99 }
-
-console.log(result.enforcement.appliedPolicies); 
-// [{ id: 'finance-safe', outcome: 'pass' }]
-
-console.log(result.traceId);
-// "uuid..."
+// 3. Deterministic Decision
+if (!result.allowed) {
+  // Blocked. Do not show to user.
+  console.error("Security Violation:", result.enforcement.violations);
+} else {
+  // Safe. Proceed to database/frontend.
+  console.log("Verified Data:", result.safeOutput);
+}
 ```
 
-## Configuration
+---
 
-Set environment variables for providers:
-```env
-OPENAI_API_KEY=sk-...
-GEMINI_API_KEY=AIza...
-```
+## 🛡️ Policy Library
 
-To test without real keys (Mock Mode):
-```env
-GATEIA_MOCK_ADAPTERS=true
-```
+Gateia ships with battle-tested policies for common enterprise risks.
 
-## API Reference
+| Policy ID | Risk Category | Description | Severity |
+|-----------|---------------|-------------|----------|
+| `finance-safe` | **Compliance** | Blocks non-compliant guarantee language (e.g., "100% no risk", "guaranteed return"). | High |
+| `pii-safe` | **Privacy** | Redacts or blocks Personally Identifiable Information (Emails, Phone Numbers). | High |
+| `secrets-safe` | **Security** | Detects leaked API keys (AWS, Stripe, OpenAI, Slack) and private keys. | High |
+| `markup-safe` | **Security** | Prevents XSS by blocking `<script>`, `iframe`, and other HTML injection vectors. | High |
 
-### `gate(params)`
+---
 
-- `model`: Model identifier (e.g., `gpt-4`, `gemini-pro`).
-- `prompt`: String or chat object.
-- `contract`: Zod schema.
-- `policies`: Array of policy IDs (strings) or Policy objects.
-- `behavior`: Logic for repair, retries, and blocking.
+## 🧩 Advanced Usage
 
-**Returns:** `Promise<GateResult<T>>`
+### Type-Safe Custom Policies
+Gateia leverages TypeScript generics to ensure your security policies are strictly typed against your contracts.
 
 ```typescript
-type GateResult<T> = {
-  safeOutput?: T;                 // Type-safe validated output
-  traceId: string;                // Unique ID for this request
-  
-  enforcement: {
-    appliedPolicies: Array<{
-      id: string;
-      mode: "enforce" | "audit";
-      outcome: "pass" | "warn" | "block";
-      reasons?: string[];
-    }>;
-    
-    contract: {
-      outcome: "pass" | "fail" | "repaired";
-      errors?: Array<{ path: string; message: string }>;
-    };
-    
-    actions: Array<{ type: "rewrite" | "block"; policyId?: string; }>;
-    violations: Array<{ 
-      policyId: string; 
-      code: string; 
-      severity: "low"|"med"|"high"; 
-      message: string; 
-    }>;
-  };
-
-  usage: {
-    model: string;
-    provider: string;
-    latencyMs: number;
-    tokens?: { prompt: number; completion: number; total: number };
-    costUsd?: number;
-  };
-};
+// Your contract expects { score: number }
+const Contract = z.object({ score: z.number() });
+
+// TypeScript knows 'output' is { score: number }
+const result = await verify({
+  output: data,
+  contract: Contract,
+  policies: [{
+     id: 'check-score',
+     mode: 'enforce',
+     // Compile Error if you access invalid properties
+     check: (output) => { 
+        if (output.score < 0) return { outcome: 'block', violations: [...] }
+        return { outcome: 'pass' }
+     }
+  }]
+});
 ```
 
-### Policies
+### Audit Mode (Passive Monitoring)
+Deploy policies without disrupting user flow. Violations are recorded but `allowed` remains `true`.
+```typescript
+const result = await verify({
+  output: output,
+  contract: z.any(),
+  policies: ['finance-safe'],
+  mode: 'audit' // Logs violations, does not block.
+});
+```
 
-## Policy Library
+---
+
+## 📊 The Enforcement Report
+
+Every call to `verify()` returns a comprehensive `EnforcementReport`. Use this for your internal dashboards and compliance logs.
+
+```json
+{
+  "allowed": false,
+  "traceId": "123e4567-e89b-12d3-a456-426614174000",
+  "enforcement": {
+    "contract": { "outcome": "pass" },
+    "appliedPolicies": [
+      { "id": "finance-safe", "outcome": "block" },
+      { "id": "pii-safe", "outcome": "pass" }
+    ],
+    "violations": [
+      {
+        "policyId": "finance-safe",
+        "code": "FIN_GUARANTEE",
+        "message": "Contains forbidden guarantee language: 'no risk'",
+        "severity": "high"
+      }
+    ]
+  }
+}
+```
 
-Gateia comes with a set of built-in policies you can use immediately.
+---
 
-| Policy ID | Function | Checks For | Outcome |
-|-----------|----------|------------|---------|
-| **`finance-safe`** | Financial Compliance | "Guaranteed returns", "No risk", "Guaranteed approval", "100% guaranteed" | `BLOCK` |
-| **`support-safe`** | Support Safety (Alias) | Same as above. Useful for refund processing agents. | `BLOCK` |
-| **`pii-safe`** | Data Privacy | Email addresses (`x@y.com`), Phone numbers (Format: `123-456-7890`) | `BLOCK` |
-| **`secrets-safe`** | Security | API Keys (OpenAI, AWS, GitHub), Private Keys | `BLOCK` |
-| **`markup-safe`** | XSS Prevention | `<script>`, `<iframe>`, `javascript:` URIs | `BLOCK` |
+## License
 
-### Custom Policies
-```typescript
-import { gate, Policy } from 'gateia';
-
-// 1. Define your custom policy
-const noCompetitors: Policy = {
-  id: 'no-competitors',
-  mode: 'enforce', // 'audit' to just warn
-  check: (output) => {
-    // output is strict typed from your Contract (or string if simple)
-    const text = JSON.stringify(output).toLowerCase();
-    
-    if (text.includes('acme corp')) {
-        return {
-           outcome: 'block',
-           violations: [{
-               policyId: 'no-competitors',
-               code: 'COMPETITOR_MENTION',
-               message: 'Mentioned competitor Acme Corp',
-               severity: 'high',
-               evidence: { snippet: 'acme corp' }
-           }]
-        };
-    }
-    return { outcome: 'pass' };
-  }
-};
-
-// 2. Use it in the gate
-await gate({
-  model: 'gpt-4',
-  prompt: 'Who is the best provider?',
-  contract: z.string(),
-  policies: ['finance-safe', noCompetitors] // Mix built-in ID strings and custom objects
-});
-```
+MIT 

package/dist/engine/contract.d.ts

@@ -10,5 +10,4 @@ export interface ContractResult<T> {
 }
 export declare class ContractEngine {
     validate<T>(data: any, schema: z.ZodType<T>): ContractResult<T>;
-    formatRepairInstruction(error: string): string;
 }

package/dist/engine/contract.js

@@ -18,9 +18,5 @@ class ContractEngine {
             return { success: false, error: errorMsg, errors: formattedErrors };
         }
     }
-    // Helper to format error for the LLM repair prompt
-    formatRepairInstruction(error) {
-        return `The previous response failed schema validation:\n${error}\nPlease fix the JSON to match the schema. Return ONLY valid JSON.`;
-    }
 }
 exports.ContractEngine = ContractEngine;

package/dist/engine/policy.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PolicyEngine = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../types");
+// Runtime schema to validate Policy returns (Defense against bad JS)
+const ViolationSchema = zod_1.z.object({
+    policyId: zod_1.z.string(),
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    severity: zod_1.z.enum(['low', 'med', 'high']),
+    evidence: zod_1.z.object({ snippet: zod_1.z.string() }).optional()
+});
+const PolicyResultSchema = zod_1.z.object({
+    outcome: zod_1.z.enum(['pass', 'block', 'warn', 'rewrite']),
+    violations: zod_1.z.array(ViolationSchema).optional(),
+    rewriteFn: zod_1.z.function().optional()
+});
 class PolicyEngine {
     async evaluate(policies, output, context) {
         const violations = [];
@@ -9,15 +24,15 @@ class PolicyEngine {
         let hasRewrite = false;
         // Policies are applied in order
         for (const policy of policies) {
-            if (policy.mode === 'audit' || (policy.mode !== 'enforce' && policy.mode !== 'audit')) {
-                // Default to audit if not specified? Or enforce? 
-                // User requirements say "Policy interface: mode: enforce|audit"
-                // Let's assume default is 'enforce' if not present in policy object, 
-                // BUT the policy object itself has a mode.
-                // Actually, the `gate` call has behavior.mode too.
-                // We will respect policies' own mode property.
+            // Execute Policy
+            const rawResult = await policy.check(currentOutput, context);
+            // FATAL: Runtime Validation of Policy Result
+            // If the user made a typo (e.g. 'outcomee') or forgot severity, we MUST crash/alert.
+            const parse = PolicyResultSchema.safeParse(rawResult);
+            if (!parse.success) {
+                throw new types_1.GateiaError(`Invalid Policy Result from '${policy.id}': ${parse.error.issues.map(i => i.path.join('.') + ' ' + i.message).join(', ')}`, context.traceId);
             }
-            const result = await policy.check(currentOutput, context);
+            const result = parse.data; // safe now
             // If violations, add them
             if (result.violations) {
                 violations.push(...result.violations);
@@ -36,19 +51,14 @@ class PolicyEngine {
                 }
             }
             else if (result.outcome === 'rewrite') {
-                if (result.rewriteFn && policy.mode !== 'audit') {
-                    currentOutput = result.rewriteFn(currentOutput);
+                // Re-attach the function from raw result because Zod strips functions sometimes or we just want the original reference
+                // Actually Zod schema above allows function pass-through if configured, but let's be safe:
+                if (rawResult.rewriteFn && policy.mode !== 'audit') {
+                    currentOutput = rawResult.rewriteFn(currentOutput);
                     hasRewrite = true;
-                    // If it was pass but now rewrite, outcome is pass (with rewrite)
-                }
-                else if (policy.mode === 'audit') {
-                    // record that it WOULD have rewritten
                 }
             }
         }
-        // If any blocking violation occurred (non-audit), result is block
-        // We need to filter violations to check if any critical/enforced ones exist
-        // Actually simplicity: if `finalOutcome` was set to 'block', return block.
         return {
             outcome: finalOutcome,
             violations,

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import { z } from 'zod';
-import { GateParams, GateResult } from './types';
-export declare function gate<T extends z.ZodTypeAny>(params: GateParams<T>): Promise<GateResult<z.infer<T>>>;
+export { verify } from './verify';
 export * from './types';
+export * from './policies';

package/dist/index.js

@@ -14,206 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.gate = gate;
-const zod_1 = require("zod");
-const types_1 = require("./types");
-const uuid_1 = require("uuid");
-const registry_1 = require("./adapters/registry");
-const contract_1 = require("./engine/contract");
-const policy_1 = require("./engine/policy");
-const policies_1 = require("./policies");
-// Global instances
-const registry = new registry_1.ModelRegistry();
-const contractEngine = new contract_1.ContractEngine();
-const policyEngine = new policy_1.PolicyEngine();
-async function gate(params) {
-    const traceId = (0, uuid_1.v4)();
-    const { model, prompt, contract, policies = [], behavior, options } = params;
-    try {
-        // 1. Resolve Adapter
-        const adapter = registry.getAdapter(model);
-        // 2. Resolve Policies
-        const activePolicies = policies.map(p => {
-            if (typeof p === 'string') {
-                const found = policies_1.policyLibrary[p];
-                if (!found)
-                    throw new types_1.GateiaError(`Unknown policy: ${p}`, traceId);
-                return found;
-            }
-            return p;
-        });
-        // 3. Execution Loop (Simple Retry Logic for Contract)
-        let attempts = 0;
-        let maxRetries = behavior?.contract?.maxRetries ?? 0;
-        // Bounded auto repair
-        if (behavior?.contract?.repair === 'auto' && maxRetries === 0) {
-            maxRetries = 3; // Default
-        }
-        else if (behavior?.contract?.repair === 'off') {
-            maxRetries = 0;
-        }
-        let currentPrompt = prompt;
-        let lastError;
-        let finalSafeOutput;
-        let contractOutcome = 'fail';
-        // Track usage
-        let totalTokens = { prompt: 0, completion: 0, total: 0 };
-        let finalLatency = 0;
-        let rawResult;
-        while (attempts <= maxRetries) {
-            attempts++;
-            // Call Model
-            const result = await adapter.generate(currentPrompt, {
-            // If contract is object/schema, hint json mode if supported by adapter?
-            // For now, adapter ignores options in stub
-            });
-            if (result.tokens) {
-                totalTokens.prompt += result.tokens.prompt;
-                totalTokens.completion += result.tokens.completion;
-                totalTokens.total += result.tokens.total;
-            }
-            finalLatency = result.latencyMs || 0;
-            // Parse Output (assume text for now, try to parse JSON if schema expects object)
-            // Usually LLM returns string. If Schema is object, we try JSON.parse
-            let outputToValidate = result.text;
-            let isJsonSchema = contract instanceof zod_1.z.ZodObject || contract instanceof zod_1.z.ZodArray;
-            if (result.structured) {
-                outputToValidate = result.structured;
-            }
-            else if (isJsonSchema) {
-                try {
-                    // Simple extraction of JSON if wrapped in markdown
-                    const jsonMatch = result.text.match(/```json\n([\s\S]*?)\n```/) || result.text.match(/\{[\s\S]*\}/);
-                    if (jsonMatch) {
-                        outputToValidate = JSON.parse(jsonMatch[0].replace(/```json|```/g, ''));
-                    }
-                    else {
-                        outputToValidate = JSON.parse(result.text);
-                    }
-                }
-                catch (e) {
-                    // Parsing failed
-                }
-            }
-            rawResult = outputToValidate;
-            // Validate Contract
-            const contractRes = contractEngine.validate(outputToValidate, contract);
-            if (contractRes.success) {
-                finalSafeOutput = contractRes.data;
-                contractOutcome = attempts === 1 ? 'pass' : 'repaired';
-                break; // Success!
-            }
-            else {
-                lastError = contractRes.error;
-                if (attempts <= maxRetries) {
-                    // Prepare repair prompt
-                    const repairMsg = contractEngine.formatRepairInstruction(lastError || "Invalid Format");
-                    // Append to prompt? Or new message?
-                    // Simple "chat" append if prompt is array-like?
-                    // For MVP, if prompt is string, we append.
-                    if (typeof currentPrompt === 'string') {
-                        currentPrompt = `${currentPrompt}\n\nUser: ${repairMsg}`; // Very naive chat history
-                    }
-                    else {
-                        // If it's object, assumes single turn. We can't easily extend without a chat structure.
-                        // For MVP assume simple string prompt works best for repair loop.
-                        // Or just append to user message.
-                        currentPrompt = {
-                            ...currentPrompt,
-                            user: `${currentPrompt.user}\n\n(System: Previous output invalid: ${lastError}. Fix it.)`
-                        };
-                    }
-                }
-            }
-        }
-        // Construct usage object
-        const finalUsage = {
-            provider: registry.getAdapter(model).constructor.name,
-            model: params.model,
-            latencyMs: finalLatency,
-            inputTokens: totalTokens.prompt,
-            outputTokens: totalTokens.completion,
-            totalTokens: totalTokens.total,
-            // costUsd: ... // TODO: Add cost calculation logic based on provider/model
-        };
-        if (!finalSafeOutput) {
-            // Block/Throw
-            // Construct report
-            const report = {
-                appliedPolicies: [], // Policies not applied due to contract failure
-                contract: {
-                    outcome: 'fail',
-                    errors: contractEngine.validate(rawResult, contract).errors // re-running valid logic or grabbing from lastError
-                },
-                actions: [],
-                violations: [{ policyId: 'contract', code: 'CONTRACT_FAIL', message: lastError || "Contract Validation Failed", severity: 'high' }]
-            };
-            // For accurate errors we might want to capture them better above instead of re-running or assuming lastError string
-            // But for now this matches structure.
-            throw new types_1.GateiaError("Contract Check Failed", traceId, report);
-        }
-        // 4. Apply Policies
-        // Note: Policies applied on safeOutput? Or raw text?
-        // Usually policies check content. If we have safe object, we check that.
-        const policyCtx = { model: params.model, prompt: params.prompt, traceId };
-        const policyResult = await policyEngine.evaluate(activePolicies, finalSafeOutput, policyCtx);
-        let finalViolations = policyResult.violations || [];
-        let enforcementActions = [];
-        // Detailed policy reporting
-        const appliedRecs = activePolicies.map(p => {
-            const policyViolations = finalViolations.filter(v => v.policyId === p.id);
-            let outcome = 'pass';
-            if (policyViolations.length > 0) {
-                const isBlock = policyViolations.some(v => v.severity === 'high');
-                outcome = isBlock ? 'block' : 'warn';
-            }
-            return {
-                id: p.id,
-                version: p.version,
-                mode: p.mode || 'enforce',
-                outcome,
-                reasons: policyViolations.map(v => v.message)
-            };
-        });
-        if (policyResult.rewrittenOutput) {
-            finalSafeOutput = policyResult.rewrittenOutput;
-            enforcementActions.push({ type: 'rewrite', policyId: 'policy-engine', note: 'Content rewritten by policy' });
-        }
-        const report = {
-            appliedPolicies: appliedRecs,
-            contract: {
-                outcome: contractOutcome,
-                // If repaired, we could list repairs here if we tracked them detailly
-            },
-            actions: enforcementActions,
-            violations: finalViolations
-        };
-        if (policyResult.outcome === 'block') {
-            const onBlock = behavior?.onBlock || 'throw'; // Default throw?
-            if (onBlock === 'throw') {
-                throw new types_1.GateiaError("Policy Blocked Response", traceId, report);
-            }
-            // Return with no safeOutput? Or just raw?
-            return {
-                safeOutput: undefined,
-                traceId,
-                enforcement: report,
-                usage: finalUsage,
-                rawOutput: options?.includeRawOutput ? rawResult : undefined
-            };
-        }
-        return {
-            safeOutput: finalSafeOutput,
-            traceId,
-            enforcement: report,
-            usage: finalUsage,
-            rawOutput: options?.includeRawOutput ? rawResult : undefined
-        };
-    }
-    catch (error) {
-        if (error instanceof types_1.GateiaError)
-            throw error;
-        throw new types_1.GateiaError(error.message, traceId, undefined, error);
-    }
-}
+exports.verify = void 0;
+var verify_1 = require("./verify");
+Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return verify_1.verify; } });
 __exportStar(require("./types"), exports);
+__exportStar(require("./policies"), exports);

package/dist/policies/finance.d.ts

@@ -4,5 +4,5 @@ export declare const supportSafe: {
     id: string;
     version?: string;
     mode?: "enforce" | "audit";
-    check: (output: any, context: import("../types").PolicyContext) => import("../types").PolicyResult | Promise<import("../types").PolicyResult>;
+    check: (output: any, context: import("../types").PolicyContext) => import("../types").PolicyResult<any> | Promise<import("../types").PolicyResult<any>>;
 };

package/dist/types.d.ts

@@ -15,46 +15,19 @@ export interface Violation {
     };
 }
 export interface PolicyContext {
-    model: string;
-    prompt: any;
     traceId: string;
+    metadata?: Record<string, any>;
 }
-export interface PolicyResult {
+export interface PolicyResult<T = any> {
     outcome: GateOutcome;
     violations?: Violation[];
-    rewriteFn?: (output: any) => any;
+    rewriteFn?: (output: T) => T;
 }
-export interface Policy {
+export interface Policy<T = any> {
     id: string;
     version?: string;
     mode?: 'enforce' | 'audit';
-    check: (output: any, context: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-}
-export interface GateOptions {
-    includeRawOutput?: boolean;
-}
-export interface GateBehavior {
-    mode?: 'enforce' | 'audit';
-    contract?: {
-        repair?: 'off' | 'auto';
-        maxRetries?: number;
-        maxRepairAttempts?: number;
-    };
-    policy?: {
-        rewrite?: 'off' | 'allowed';
-    };
-    onBlock?: 'throw' | 'return';
-}
-export interface GateParams<T extends z.ZodTypeAny> {
-    model: string;
-    prompt: string | {
-        system?: string;
-        user: string;
-    };
-    contract: T;
-    policies?: (string | Policy)[];
-    behavior?: GateBehavior;
-    options?: GateOptions;
+    check: (output: T, context: PolicyContext) => PolicyResult<T> | Promise<PolicyResult<T>>;
 }
 export interface AppliedPolicyRec {
     id: string;
@@ -64,43 +37,37 @@ export interface AppliedPolicyRec {
     reasons?: string[];
 }
 export interface ContractEnforcement {
-    name?: string;
-    outcome: 'pass' | 'fail' | 'repaired';
+    outcome: 'pass' | 'fail';
     errors?: {
         path: string;
         message: string;
     }[];
-    repairs?: {
-        op: 'add' | 'remove' | 'replace';
-        path: string;
-        note?: string;
-    }[];
 }
-export interface GateEnforcementReport {
+export interface VerifyParams<T extends z.ZodTypeAny> {
+    output: unknown;
+    contract: T;
+    policies?: (string | Policy<z.infer<T>>)[];
+    mode?: 'enforce' | 'audit';
+    options?: {
+        includeRawOutput?: boolean;
+    };
+}
+export interface EnforcementReport {
     appliedPolicies: AppliedPolicyRec[];
     contract: ContractEnforcement;
     actions: PolicyAction[];
     violations: Violation[];
 }
-export interface GateUsage {
-    provider: string;
-    model: string;
-    latencyMs: number;
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-    costUsd?: number;
-}
-export interface GateResult<T> {
+export interface VerifyResult<T> {
+    allowed: boolean;
     safeOutput?: T;
     traceId: string;
-    enforcement: GateEnforcementReport;
-    usage: GateUsage;
+    enforcement: EnforcementReport;
     rawOutput?: any;
 }
 export declare class GateiaError extends Error {
     traceId: string;
-    report?: GateEnforcementReport;
+    report?: EnforcementReport;
     originalError?: unknown;
-    constructor(message: string, traceId: string, report?: GateEnforcementReport, originalError?: unknown);
+    constructor(message: string, traceId: string, report?: EnforcementReport, originalError?: unknown);
 }

package/dist/verify.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import { VerifyParams, VerifyResult } from './types';
+export declare function verify<T extends z.ZodTypeAny>(params: VerifyParams<T>): Promise<VerifyResult<z.infer<T>>>;

package/dist/verify.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verify = verify;
+const zod_1 = require("zod");
+const uuid_1 = require("uuid");
+const types_1 = require("./types");
+const contract_1 = require("./engine/contract");
+const policy_1 = require("./engine/policy");
+const policies_1 = require("./policies");
+const contractEngine = new contract_1.ContractEngine();
+const policyEngine = new policy_1.PolicyEngine();
+async function verify(params) {
+    const traceId = (0, uuid_1.v4)();
+    const { output, contract, policies = [], mode = 'enforce' } = params;
+    try {
+        // --- 1. Contract Validation ---
+        // (If output is string and contract is Object, we might want to try parsing it? 
+        //  The pivot request says "Gateia works with outputs generated by ANY provider".
+        //  Users might pass raw JSON string. Should we auto-parse? 
+        //  For now, assume user handles parsing OR we do simple string->object if schema demands it.)
+        let outputToValidate = output;
+        // Auto-parse JSON string if schema is object/array but output is string
+        if (typeof output === 'string' && (contract instanceof zod_1.z.ZodObject || contract instanceof zod_1.z.ZodArray)) {
+            try {
+                // 1. Try to extract from markdown code blocks
+                const jsonBlockMatch = output.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+                if (jsonBlockMatch && jsonBlockMatch[1]) {
+                    outputToValidate = JSON.parse(jsonBlockMatch[1].trim());
+                }
+                else {
+                    // 2. Try parsing the raw string (maybe it's just JSON)
+                    outputToValidate = JSON.parse(output.trim());
+                }
+            }
+            catch (e) {
+                // Failed to parse, validation will likely fail next
+            }
+        }
+        const contractRes = contractEngine.validate(outputToValidate, contract);
+        let safeOutput = contractRes.success ? contractRes.data : undefined;
+        const contractErrors = contractRes.success ? undefined : contractRes.errors;
+        const contractOutcome = contractRes.success ? 'pass' : 'fail';
+        // --- 2. Policy Enforcement ---
+        // Resolve policies
+        const activePolicies = policies.map(p => {
+            if (typeof p === 'string') {
+                const found = policies_1.policyLibrary[p];
+                if (!found)
+                    throw new types_1.GateiaError(`Unknown policy: ${p}`, traceId);
+                return found;
+            }
+            return p;
+        });
+        // Run policies
+        // Note: We run policies on the *safeOutput* if valid, or original *output* if not?
+        // Ideally we check specific fields if valid. If invalid, we might still check the raw string?
+        // Let's run on `currentOutput` which is `safeOutput` ?? `output`.
+        const contentToCheck = safeOutput !== undefined ? safeOutput : output;
+        const policyCtx = { traceId };
+        const policyResult = await policyEngine.evaluate(activePolicies, contentToCheck, policyCtx);
+        let finalViolations = policyResult.violations || [];
+        let enforcementActions = [];
+        // Apply Rewrites if allowed
+        if (policyResult.rewrittenOutput) {
+            safeOutput = policyResult.rewrittenOutput;
+            enforcementActions.push({ type: 'rewrite', policyId: 'policy-engine', note: 'Content rewritten' });
+        }
+        // Build Applied Report
+        const appliedRecs = activePolicies.map(p => {
+            const pViolations = finalViolations.filter(v => v.policyId === p.id);
+            let outcome = 'pass';
+            if (pViolations.length > 0) {
+                const isBlock = pViolations.some(v => v.severity === 'high');
+                outcome = isBlock ? 'block' : 'warn';
+            }
+            return {
+                id: p.id,
+                version: p.version,
+                mode: p.mode || 'enforce',
+                outcome,
+                reasons: pViolations.map(v => v.message)
+            };
+        });
+        // --- 3. Decision ---
+        // BLOCK if: 
+        // 1. Contract Failed (Invalid structure)
+        // 2. Any High Severity Violation (unless mode=audit)
+        const contractFailed = !contractRes.success;
+        // Check both explicit violations AND the aggregated outcome from policy engine
+        // This handles cases where a user returns { outcome: 'block' } but omits violations
+        const blockedByPolicy = finalViolations.some(v => v.severity === 'high') ||
+            (policyResult.outcome === 'block' && mode === 'enforce');
+        // Safety Fallback: If blocked but no violations, inject one for reporting
+        if (blockedByPolicy && finalViolations.length === 0) {
+            finalViolations.push({
+                policyId: 'gateia-core',
+                code: 'IMPLICIT_BLOCK',
+                message: 'A policy returned BLOCK status but provided no violation details.',
+                severity: 'high'
+            });
+        }
+        let allowed = true;
+        if (contractFailed)
+            allowed = false;
+        if (blockedByPolicy && mode === 'enforce')
+            allowed = false;
+        const report = {
+            appliedPolicies: appliedRecs,
+            contract: {
+                outcome: contractOutcome,
+                errors: contractErrors
+            },
+            actions: enforcementActions,
+            violations: finalViolations
+        };
+        return {
+            allowed,
+            safeOutput: allowed ? safeOutput : undefined,
+            traceId,
+            enforcement: report,
+            rawOutput: params.options?.includeRawOutput ? output : undefined
+        };
+    }
+    catch (error) {
+        if (error instanceof types_1.GateiaError)
+            throw error;
+        throw new types_1.GateiaError(error.message, traceId, undefined, error);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gateia",
-  "version": "0.1.4",
-  "description": "The trust layer for AI in production. Middleware for model routing, contract enforcement, and policy compliance.",
+  "version": "0.2.0",
+  "description": "The Deterministic Verification Layer for Enterprise AI.",
   "keywords": [
     "ai",
     "llm",
@@ -31,14 +31,14 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "zod": "^3.22.4",
-    "uuid": "^9.0.1"
+    "uuid": "^13.0.0",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.1",
     "@types/node": "^20.11.0",
-    "@types/uuid": "^9.0.7"
+    "@types/uuid": "^9.0.7",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
   },
   "engines": {
     "node": ">=18"