AI guardrails
AI guardrails are the fail-closed input/output chokepoint every LLM call passes through before a prompt reaches a provider and before its answer reaches a caller: an unconditional credential-shape scan, a swappable content moderator under a deadline, and PII redaction. Caisson's @caisson/guardrails blocks on a moderator outage rather than passing text through unchecked.
In code
async function moderate(
stage: "input" | "output",
text: string,
policy: GuardPolicy,
rt: GuardRuntime,
): Promise<void> {
// Unconditional credential-shape gate (ADR-0215): runs before the moderator call.
// No policy field, no opt-out: a raw credential in either leg never reaches a moderator.
if (looksLikeSecret(text)) block(stage, "secret", false, policy, rt);
let result: ModerationResult;
try {
result = await moderateWithDeadline(
policy.moderator,
text,
policy.timeoutMs ?? DEFAULT_TIMEOUT_MS,
);
} catch {
// Outage / timeout / driver throw -> fail-closed unless explicitly opted out.
if (policy.failOpen === true) return;
block(stage, "moderation", true, policy, rt);
}
if (result.flagged) block(stage, result.category, false, policy, rt);
}How it holds
Unconditional secret gate
Every input and output leg runs looksLikeSecret before any moderator call, with no policy field to disable it: a raw credential never reaches a provider or a caller, live moderator or not.
Fail-closed on outage
moderateWithDeadline races the configured moderator against a timeout; a driver throw, a rejection, or a deadline miss blocks the call unless the policy explicitly sets failOpen: true.
Swappable moderator port
A local zero-network regex driver, a provider driver wrapping an injected HTTP check, or a custom hook all implement the same Moderator interface, so the gate logic never changes when the driver does.
Metadata-only telemetry
A block emits a guardrail.blocked event to the kernel EventSink carrying block metadata only (block id, stage, category, policy, fail-closed flag, tenant), never the flagged text, so the audit trail never re-leaks what it just redacted.