Compliance AI Shield: $CAIS API Documentation & Integration Guide

1. Overview

This document outlines the core TypeScript interfaces, pipeline orchestrator, gate implementations, and testing scenarios for integrating the Compliance AI Shield ($CAIS) 8-Gate Pipeline into your infrastructure.

2. The 8-Gate Pipeline Schema

The following shared primitives define the strict typings used by the regulatory engine for payload evaluation and tracking.

export type GateStatus = "PASS" | "HARD_STOP" | "TRANSFORMED" | "FLAGGED";

export interface GateResult<TMeta = Record<string, unknown>> {
gateId: number;
gateName: string;
status: GateStatus;
inputContent: string;
outputContent: string;
wasTransformed: boolean;
durationMs: number;
meta: TMeta;
timestamp: string; // ISO-8601
}

export interface LogicGate<TMeta = Record<string, unknown>> {
readonly gateId: number;
readonly gateName: string;
evaluate(content: string, context: TransactionContext): Promise<GateResult<TMeta>>;
}

export interface TransactionContext {
transactionId: string; // UUID v4
direction: "PROMPT" | "OUTPUT";
userId?: string;
orgId?: string;
regulatoryJurisdiction: "UK" | "EU" | "BOTH";
assetClass?: "RWA" | "TOKEN" | "NONE";
sessionMeta?: Record<string, unknown>;
}

3. CAISPipeline Orchestrator Implementation

The orchestrator synchronously evaluates prompts and outputs across the regulatory logic gates, logging deterministic outcomes directly to the $CAIS Audit Ledger.

import { performance } from "perf_hooks";

class CAISPipeline implements CAISPipeline {
private readonly gates: [
RegulatoryGate,
CyberGate,
FinancialGate,
HRBiasGate,
HSESafetyGate,
DataVaultGate,
RWAShieldGate,
];
private readonly auditLedger: AuditLedger;

constructor(gates: any, auditLedger: AuditLedger) {
this.gates = gates;
this.auditLedger = auditLedger;
}

async process(rawContent: string, context: TransactionContext): Promise<PipelineResult> {
const pipelineStart = performance.now();
const gateResults: GateResult[] = [];
let workingContent = rawContent;
let hardStopped = false;
let hardStopGateId: number | null = null;

for (const gate of this.gates) {
const result = await gate.evaluate(workingContent, context);
gateResults.push(result);
if (result.status === "HARD_STOP") {
hardStopped = true;
hardStopGateId = gate.gateId;
break;
}
workingContent = result.outputContent;
}

const auditResult = await this.auditLedger.evaluate(workingContent, context, gateResults);
gateResults.push(auditResult);

const finalStatus = this.deriveFinalStatus(gateResults);
const totalDurationMs = performance.now() - pipelineStart;
this.emitPerformanceTelemetry(totalDurationMs, context, hardStopGateId);

return {
transactionId: context.transactionId,
finalStatus,
finalContent: hardStopped ? "" : workingContent,
gateResults,
totalDurationMs,
auditReceipt: auditResult.meta,
};
}

private deriveFinalStatus(results: GateResult[]): GateStatus {
if (results.some((r) => r.status === "HARD_STOP")) return "HARD_STOP";
if (results.some((r) => r.status === "FLAGGED")) return "FLAGGED";
if (results.some((r) => r.status === "TRANSFORMED")) return "TRANSFORMED";
return "PASS";
}

private emitPerformanceTelemetry(totalDurationMs: number, context: TransactionContext, hardStopGateId: number | null): void {
const SLA_MS = 20;
const breached = totalDurationMs > SLA_MS;
if (breached) console.warn("[CAIS] SLA breach — 20ms target exceeded");
}
}

4. Gate Implementations

4.1 Gate 1: RegulatoryGateImpl

4.2 Gate 6: DataVaultGateImpl

import { createHash, randomBytes, createCipheriv, createDecipheriv } from "crypto";

const VAULT_KEY = randomBytes(32);

class DataVaultGateImpl implements DataVaultGate {
readonly gateId = 6 as const;
readonly gateName = "DATA_VAULT" as const;
private readonly vault = new Map<string, VaultEntry>();

async evaluate(content: string, context: TransactionContext): Promise<GateResult<DataVaultMeta>> {
const start = performance.now();
// 1. Detect PII
// 2. Tokenise and Vault (AES-256-GCM)
// 3. Apply Redactions (Right-to-Left)

return {
gateId: 6,
gateName: "DATA_VAULT",
status: "TRANSFORMED", // Gate 6 never HARD_STOPs
inputContent: content,
outputContent: "[REDACTED CONTENT]",
wasTransformed: true,
durationMs: performance.now() - start,
meta: { piiEntitiesFound: [], redactionStrategy: "TOKENISE", vaultReferences: [] },
timestamp: new Date().toISOString(),
};
}
}

5. Live Demo Harness: Execution Scenarios

Scenario 1: Prohibited Output (The Block)

Context: IFA submits a client brief containing PII and an unauthorised financial guarantee. Gate 1 should hard-stop before Gate 6 even runs.

const CLIENT_BRIEF = `
IFA Client Brief — Confidential
Client: Mrs Eleanor Voss
NI Number: SB 47 12 89 C

Adviser note: Based on current market conditions, I guarantee this
investment portfolio will yield 10% annually over the next 5 years.
`.trim();

// Expected Result:
// 🛑 FINAL STATUS: HARD_STOP
// 🔴 BEFORE: (original content)
// 🟡 AFTER: [CONTENT BLOCKED — not released to caller]

Scenario 2: Clean IFA Brief (The Filter)

Context: A legitimate client brief. PII is present, but no prohibited content exists. Gate 1 passes. Gate 6 redacts PII. Pipeline completes all 8 gates.

const CLEAN_CLIENT_BRIEF = `
IFA Client Brief — Confidential

Client: Mr Thomas Whitfield
NI Number: SB 94 37 21 D
Contact: t.whitfield@personalmail.co.uk
Phone: 07823 116492

Adviser note: Mr Whitfield is reviewing his retirement planning options.
He has expressed interest in a balanced portfolio with moderate risk exposure.
Please summarise the key differences between a Stocks & Shares ISA and a
Self-Invested Personal Pension (SIPP), and outline which may be more suitable
given a 15-year investment horizon. All recommendations should be presented
as options for further discussion with a qualified financial adviser.
`.trim();

// Expected Result:
// 🔄 FINAL STATUS: TRANSFORMED
// 🔴 BEFORE (raw PII visible)
// 🟡 AFTER (PII redacted — safe to pass to AI layer)
//
// PII REDACTION DIFF
// NAME Mr Thomas Whitfield [NAME_xxxx]
// NI_NUMBER SB 94 37 21 D [NI_NUMBER_xxxx]
// EMAIL t.whitfield@personalmail.co.uk [EMAIL_xxxx]
// PHONE 07823 116492 [PHONE_xxxx]