@loomwork/middleware 0.0.0-stage → 0.1.0

package/src/rateLimit.ts

@@ -0,0 +1,126 @@
+import type { EffectContext, EffectMiddleware } from "@loomwork/effect-runtime";
+
+// ── Effect rate limiting (R9 — autonomy envelope) ────────────────────────────
+//
+// A runaway agent is not only expensive, it is FAST: a tool loop can issue thousands of
+// effects a second long before a token budget notices (a cheap tool meters ~0 tokens).
+// A token bucket bounds the RATE of effects per scope, which the cost budgets cannot.
+//
+// It lives at the EFFECT layer, not in the fold, so it is replay-safe: middleware runs only
+// when an effect actually executes (completed steps are served from the log and never reach
+// it), and a refusal is a thrown error that fails the step through the ordinary path. The
+// bucket state is process-local and wall-clock driven by design — it is admission control,
+// not a fact about the execution — so it never enters the log and two nodes each enforce
+// their own bucket (the limit is per process; cluster-wide limits are a store-backed
+// concern this middleware deliberately does not pretend to solve).
+
+/** Which requests share one bucket. */
+export type RateLimitScope = "execution" | "tenant" | "workflow" | "global";
+
+export interface RateLimitOptions {
+  /** Bucket size: the burst a scope may issue at once. Must be a positive integer. */
+  capacity: number;
+  /** Sustained rate: tokens added per second. Must be positive. */
+  refillPerSecond: number;
+  /**
+   * Who shares a bucket. Default `"execution"` (one runaway execution cannot starve the
+   * rest). `"tenant"` keys on `ctx.principal.tenant` — a request with no tenant shares ONE
+   * `"(no-tenant)"` bucket rather than escaping the limit. `"workflow"` keys on the flow id
+   * (the per-agent case); `"global"` is one bucket for the process.
+   */
+  scope?: RateLimitScope;
+  /** Injectable clock in ms (tests); defaults to `Date.now`. */
+  clock?: () => number;
+  /**
+   * Upper bound on live buckets. A fresh bucket is created per execution/tenant key, so an
+   * unbounded map would be a leak; the least-recently-used bucket is evicted past this size
+   * (an evicted key simply starts full again — it can only err toward permitting). Default 10_000.
+   */
+  maxBuckets?: number;
+}
+
+/**
+ * The typed, NON-retryable refusal for a rate-limit trip. It is the control plane speaking,
+ * not a transient fault: retrying immediately repeats it, so callers that classify errors by
+ * `name` (loom-ui's `isControlPlaneError`) must treat `"RateLimitExceededError"` as a refusal.
+ */
+export class RateLimitExceededError extends Error {
+  readonly scope: RateLimitScope;
+  readonly key: string;
+  /** Milliseconds until one token is available again (a hint, never a promise). */
+  readonly retryAfterMs: number;
+  /** Honoured by `retryMiddleware`'s default classifier: an immediate retry repeats the refusal. */
+  readonly retryable = false;
+  constructor(scope: RateLimitScope, key: string, retryAfterMs: number) {
+    super(`Rate limit exceeded for ${scope} "${key}" — retry after ~${retryAfterMs}ms`);
+    this.name = "RateLimitExceededError";
+    this.scope = scope;
+    this.key = key;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+interface Bucket {
+  tokens: number;
+  at: number;
+}
+
+function keyOf(scope: RateLimitScope, ctx: EffectContext): string {
+  switch (scope) {
+    case "execution":
+      return ctx.executionId;
+    case "workflow":
+      return ctx.workflowId;
+    case "tenant":
+      return ctx.principal?.tenant ?? "(no-tenant)";
+    case "global":
+      return "*";
+  }
+}
+
+export function rateLimitMiddleware(options: RateLimitOptions): EffectMiddleware {
+  const { capacity, refillPerSecond } = options;
+  if (!Number.isInteger(capacity) || capacity < 1) {
+    throw new Error(`rateLimitMiddleware: capacity must be a positive integer (got ${capacity})`);
+  }
+  if (!(refillPerSecond > 0) || !Number.isFinite(refillPerSecond)) {
+    throw new Error(
+      `rateLimitMiddleware: refillPerSecond must be a positive number (got ${refillPerSecond})`
+    );
+  }
+  const scope = options.scope ?? "execution";
+  const now = options.clock ?? (() => Date.now());
+  const maxBuckets = options.maxBuckets ?? 10_000;
+  // Map iteration order is insertion order, so delete+set on every touch keeps the OLDEST
+  // key first — an O(1) LRU without a second structure.
+  const buckets = new Map<string, Bucket>();
+
+  return async (ctx, _input, next): Promise<unknown> => {
+    const key = keyOf(scope, ctx);
+    const t = now();
+    const bucket = buckets.get(key) ?? { tokens: capacity, at: t };
+    buckets.delete(key);
+    const elapsedSec = Math.max(0, t - bucket.at) / 1000;
+    bucket.tokens = Math.min(capacity, bucket.tokens + elapsedSec * refillPerSecond);
+    bucket.at = t;
+    const admitted = bucket.tokens >= 1;
+    if (admitted) bucket.tokens -= 1;
+    buckets.set(key, bucket);
+    if (buckets.size > maxBuckets) {
+      const oldest = buckets.keys().next().value;
+      if (oldest !== undefined) buckets.delete(oldest);
+    }
+    if (!admitted) {
+      const retryAfterMs = Math.ceil(((1 - bucket.tokens) / refillPerSecond) * 1000);
+      ctx.emit("SAFETY_BLOCKED", {
+        stepId: ctx.stepId,
+        validatorId: "rate-limit",
+        phase: "input",
+        reason: `rate limit exceeded for ${scope} "${key}"`,
+        category: "rate-limit",
+      });
+      throw new RateLimitExceededError(scope, key, retryAfterMs);
+    }
+    return next();
+  };
+}

package/src/redaction.ts

@@ -0,0 +1,184 @@
+import { pathsOfClass } from "@loomwork/classify";
+import type { StepDefinition } from "@loomwork/core";
+import type { EffectContext, EffectMiddleware, EffectNext } from "@loomwork/effect-runtime";
+
+// ── K10.3 — redaction markers: keep secrets OUT of the log entirely ───────────
+//
+// K10.2 (crypto-shredding) stores an encrypted secret IN the log and erases it
+// by destroying the key. K10.3 goes further for values that must never be
+// persisted at all: a step's input carries a deterministic REFERENCE
+// (`secretRef("stripe-key")`) instead of the raw secret, so the STEP_STARTED
+// event — and the fold, and every snapshot — only ever contains the reference.
+// A `SecretResolver` resolves the reference to the real value at effect-execution
+// time (this middleware runs kernel-side, before the K7 boundary, so an isolated
+// tool receives the resolved value while the parent's LOG never sees it — A5).
+// The MUST is "secrets never enter the log", and it holds with or without K7.
+
+/** The deterministic reference that stands in for a secret in step I/O and the log. */
+export interface SecretRef {
+  readonly __loomSecret: string;
+}
+
+export function secretRef(id: string): SecretRef {
+  return { __loomSecret: id };
+}
+
+export function isSecretRef(value: unknown): value is SecretRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { __loomSecret?: unknown }).__loomSecret === "string"
+  );
+}
+
+/**
+ * Resolves secret references to their real values (read) and, for output
+ * redaction, stores a value under a reference (write). Back it with a vault /
+ * KMS / secret manager in production; the resolver is the boundary the plaintext
+ * lives behind. `InMemorySecretResolver` is for tests.
+ */
+export interface SecretResolver {
+  resolve(id: string): Promise<unknown> | unknown;
+  /** Optional — required only when `redactOutput` mints references from results. */
+  store?(id: string, value: unknown): Promise<void> | void;
+}
+
+export class InMemorySecretResolver implements SecretResolver {
+  constructor(private readonly secrets: Map<string, unknown> = new Map()) {}
+  resolve(id: string): unknown {
+    if (!this.secrets.has(id)) throw new Error(`no secret registered for reference "${id}"`);
+    return this.secrets.get(id);
+  }
+  store(id: string, value: unknown): void {
+    this.secrets.set(id, value);
+  }
+}
+
+export interface RedactionOptions {
+  resolver: SecretResolver;
+  /**
+   * Output dot-paths (per effect) whose values must NOT enter the log: the value
+   * is stored in the resolver under a deterministic reference
+   * (`executionId:stepId:path`) and REPLACED by that reference in the result, so
+   * STEP_COMPLETED logs the reference. Requires `resolver.store`. Omit to only
+   * resolve input references (the common case).
+   */
+  redactOutput?: (info: { stepId: string }) => readonly string[];
+}
+
+async function deepResolve(value: unknown, resolver: SecretResolver): Promise<unknown> {
+  if (isSecretRef(value)) return resolver.resolve(value.__loomSecret);
+  if (Array.isArray(value)) return Promise.all(value.map((v) => deepResolve(v, resolver)));
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = await deepResolve(v, resolver);
+    return out;
+  }
+  return value;
+}
+
+function getPath(
+  root: unknown,
+  path: string
+): { parent: Record<string, unknown>; leaf: string } | undefined {
+  const segs = path.split(".");
+  let cursor = root as Record<string, unknown> | undefined;
+  for (let i = 0; i < segs.length - 1; i++) {
+    const next = cursor?.[segs[i] as string];
+    cursor =
+      typeof next === "object" && next !== null ? (next as Record<string, unknown>) : undefined;
+    if (cursor === undefined) return undefined;
+  }
+  const leaf = segs[segs.length - 1] as string;
+  return cursor !== undefined && Object.hasOwn(cursor, leaf) ? { parent: cursor, leaf } : undefined;
+}
+
+/**
+ * K10.3 — redaction middleware. Runs on the effect path (like metering/safety):
+ *  - **input**: resolves every `SecretRef` in the effect input to its real value
+ *    before the tool runs, WITHOUT touching the logged input (STEP_STARTED keeps
+ *    the reference — the secret never enters the log).
+ *  - **output** (optional): replaces marked result fields with deterministic
+ *    references (storing the value in the resolver), so STEP_COMPLETED logs the
+ *    reference, not the secret.
+ *
+ * Unwired (no middleware), effects run byte-identically; with it but no refs in
+ * play, it is a deep-walk pass-through (G2).
+ */
+export function redactionMiddleware(options: RedactionOptions): EffectMiddleware {
+  const mw = async (ctx: EffectContext, input: unknown, next: EffectNext): Promise<unknown> => {
+    // Input phase — resolve references into the value the tool actually sees,
+    // WITHOUT touching the logged input (STEP_STARTED keeps the reference).
+    const resolvedInput = await deepResolve(input, options.resolver);
+    const result = await next(resolvedInput);
+
+    // Output phase — redact marked result fields into references.
+    const paths = options.redactOutput?.({ stepId: ctx.stepId }) ?? [];
+    if (paths.length === 0) return result;
+    if (options.resolver.store === undefined) {
+      throw new Error("redactOutput requires a SecretResolver with store()");
+    }
+    const redacted = structuredClone(result);
+    for (const path of paths) {
+      const hit = getPath(redacted, path);
+      if (hit === undefined) continue;
+      // A transient call stamped as an execution shares (executionId, stepId) with its
+      // siblings; callKey keeps their secret refs distinct (undefined for durable steps).
+      const refId = `${ctx.executionId}:${ctx.stepId}${
+        ctx.callKey !== undefined ? `:${ctx.callKey}` : ""
+      }:${path}`;
+      await options.resolver.store(refId, hit.parent[hit.leaf]);
+      hit.parent[hit.leaf] = secretRef(refId); // the LOG gets the reference
+    }
+    return redacted;
+  };
+  // ADR 0119 — output redaction REWRITES the result after `next()`; a streamed delta
+  // bypasses that masking, so declare it: the runtime then refuses live deltas (fail
+  // closed) rather than stream the secret past the mask. Input-only resolution does not
+  // touch output, so it stays streamable.
+  return (
+    options.redactOutput !== undefined ? Object.assign(mw, { inspectsOutput: true as const }) : mw
+  ) as EffectMiddleware;
+}
+
+// ── K10-R2 — derive output redaction from `secret()` marks ────────────────────
+//
+// Instead of hand-authoring a `redactOutput: ({stepId}) => paths` callback, mark the
+// field once — `apiToken: secret(z.string())` — and derive it. A step's output fields
+// classified `"secret"` are the ones that must never be persisted; each becomes a
+// redactOutput path (relative to the effect RESULT, which is why there is no `output.`
+// prefix — the crypto map operates on the event payload, redaction on the raw result).
+//
+// This is the low-risk half of K10-R2: it drives the EXISTING effect-path redaction seam
+// off the R1 taxonomy, with NO kernel change. Automatic secret substitution before
+// STEP_STARTED in the hot path remains deferred (its determinism stakes are higher).
+
+/**
+ * Precompute a `stepId → secret output paths` lookup from step definitions, for O(1) access
+ * in the per-effect redactOutput callback (a Map, not a per-call schema walk). Steps with no
+ * `secret()`-marked output field are omitted, so an all-unmarked app yields an empty Map and
+ * the redaction pass stays a no-op (G2).
+ */
+export function secretOutputPathsByStep(
+  // Only id + output schema are read; Pick drops the invariant handler field so concrete
+  // `StepDefinition<In, Out>` values pass without a cast.
+  steps: readonly Pick<StepDefinition, "id" | "outputSchema">[]
+): Map<string, readonly string[]> {
+  const byStep = new Map<string, readonly string[]>();
+  for (const step of steps) {
+    if (step.outputSchema === undefined) continue;
+    const paths = pathsOfClass(step.outputSchema, "secret");
+    if (paths.length > 0) byStep.set(step.id, paths);
+  }
+  return byStep;
+}
+
+/**
+ * A {@link RedactionOptions.redactOutput} callback derived from `secret()` marks — pass the
+ * result of {@link secretOutputPathsByStep} (or let `defineConfig({ secrets })` wire it).
+ */
+export function redactOutputFrom(
+  byStep: Map<string, readonly string[]>
+): (info: { stepId: string }) => readonly string[] {
+  return ({ stepId }) => byStep.get(stepId) ?? [];
+}

package/src/retry.ts

@@ -0,0 +1,133 @@
+import { SuspendError, TypedFailure } from "@loomwork/core";
+import type { EffectContext, EffectMiddleware } from "@loomwork/effect-runtime";
+
+export interface RetryOptions {
+  /** Max retries after the first attempt. Default 2 (⇒ up to 3 tries). */
+  maxRetries?: number;
+  /** Delay before the first retry, in ms. Default 100. */
+  baseDelayMs?: number;
+  /** Exponential growth factor between retries. Default 2. */
+  factor?: number;
+  /** Upper bound on any single delay, in ms. Default 30_000. */
+  maxDelayMs?: number;
+  /** Spread delays deterministically to avoid thundering herds. Default true. */
+  jitter?: boolean;
+  /**
+   * Decide whether a given error is retryable. Default: all (non-control) errors
+   * EXCEPT `TypedFailure` (DE-4) — a declared domain outcome is not transient, so
+   * retrying it by default would just burn attempts on a deterministic result — and any
+   * error that declares `retryable: false` (R9's `KillSwitchEngagedError`,
+   * `RateLimitExceededError`, `SpawnLimitExceededError`, `SafetyViolationError`).
+   * An explicit `isRetryable` retains full control (retrying a TypedFailure
+   * in-memory is legal: no durable event has been emitted yet).
+   */
+  isRetryable?: (err: unknown) => boolean;
+  /** Observability hook fired before each backoff wait. */
+  onRetry?: (info: { ctx: EffectContext; attempt: number; delayMs: number; err: unknown }) => void;
+  /** Injectable sleep (for tests). Must reject if `signal` aborts. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Retry-with-backoff middleware — fills the gap where effect failures are
+ * terminal today. Wraps a single `EffectRuntime.execute`; on a retryable error
+ * it waits (exponential backoff + deterministic jitter) and re-invokes the
+ * effect, up to `maxRetries` times.
+ *
+ * Correctness rules:
+ *  - **Never retries `SuspendError`** (a control-flow signal, not a failure) or a
+ *    **cancelled** execution (`ctx.signal.aborted`) — both rethrow immediately.
+ *  - Retries happen **in-memory within one execute call** and emit no durable
+ *    events, so the STEP_STARTED/COMPLETED envelope and the event log stay
+ *    deterministic; use `onRetry` for logging/metrics. Exhaustion rethrows the
+ *    last error into the existing `STEP_FAILED` path — behavior-preserving.
+ *  - Jitter is a deterministic hash of `executionId:stepId:attempt` (no
+ *    `Math.random`), so replay/behaviour stays stable.
+ */
+export function retryMiddleware(options: RetryOptions = {}): EffectMiddleware {
+  const maxRetries = options.maxRetries ?? 2;
+  const baseDelayMs = options.baseDelayMs ?? 100;
+  const factor = options.factor ?? 2;
+  const maxDelayMs = options.maxDelayMs ?? 30_000;
+  const useJitter = options.jitter ?? true;
+  const isRetryable =
+    options.isRetryable ??
+    ((err: unknown) =>
+      !(err instanceof TypedFailure) &&
+      // R9 — a control-plane refusal (kill switch, rate limit, spawn cap) marks itself
+      // `retryable: false`: it is a decision, and retrying repeats it.
+      (err as { retryable?: unknown } | null)?.retryable !== false);
+  const sleep = options.sleep ?? defaultSleep;
+
+  return async (ctx, _input, next) => {
+    for (let attemptIndex = 0; ; attemptIndex++) {
+      try {
+        return await next();
+      } catch (err) {
+        // Control-flow + cancellation are never "failures" to retry.
+        if (err instanceof SuspendError) throw err;
+        if (ctx.signal?.aborted === true) throw err;
+        if (attemptIndex >= maxRetries || !isRetryable(err)) throw err;
+
+        const delayMs = computeDelay(
+          attemptIndex,
+          { baseDelayMs, factor, maxDelayMs, useJitter },
+          ctx
+        );
+        options.onRetry?.({ ctx, attempt: attemptIndex + 1, delayMs, err });
+        await sleep(delayMs, ctx.signal);
+      }
+    }
+  };
+}
+
+function computeDelay(
+  attemptIndex: number,
+  cfg: { baseDelayMs: number; factor: number; maxDelayMs: number; useJitter: boolean },
+  ctx: EffectContext
+): number {
+  const base = Math.min(cfg.maxDelayMs, cfg.baseDelayMs * cfg.factor ** attemptIndex);
+  if (!cfg.useJitter) return Math.round(base);
+  // Deterministic "full jitter" in [base/2, base] — stable across replay.
+  const frac = hashFraction(`${ctx.executionId}:${ctx.stepId}:${attemptIndex}`);
+  return Math.round(base / 2 + frac * (base / 2));
+}
+
+/** FNV-1a → [0, 1). Deterministic; no Math.random. */
+function hashFraction(key: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  // >>> 0 to unsigned, scale into [0,1)
+  return (h >>> 0) / 0xffffffff;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted === true) {
+      reject(abortError(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      cleanup();
+      reject(abortError(signal));
+    };
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function abortError(signal?: AbortSignal): Error {
+  const reason = signal?.reason;
+  if (reason instanceof Error) return reason;
+  return new Error("aborted");
+}

package/src/safety.ts

@@ -0,0 +1,235 @@
+import type { EffectContext, EffectMiddleware } from "@loomwork/effect-runtime";
+
+// ── Behavioral safety ring (Loom 2.0 K6) ─────────────────────────────────────
+//
+// K2 governs *who may act*; K3 governs *how much it costs*. Neither governs
+// *whether the action or its output is safe* — the guarantee an autonomous
+// intelligent system most needs. K6 adds a governed check on the effect path:
+// pluggable validators inspect an effect's INPUT before it runs (block an unsafe
+// action, like K3 admission control) and its OUTPUT after (stop an unsafe result
+// from propagating). A block is a durable `SAFETY_BLOCKED` fact (folded into a
+// reserved `variables._safety` audit list) and throws `SafetyViolationError`,
+// which fails the step via the normal `STEP_FAILED` path — exactly like a K3 quota
+// trip. Opt-in and replay-safe: unwired, an effect runs identically to today
+// (P10); a block is a logged fact served from the log on replay (P9), so a blocked
+// run reconstructs identically. Validators run only on live execution (replay
+// serves completed/failed steps from the log and never re-invokes them); keep them
+// cheap and pure for latency and auditability, and route any ML/LLM classifier
+// verdict through the decision seam (P9) if it must be reproduced.
+
+export type SafetyPhase = "input" | "output" | "delta";
+
+export interface SafetyCheckInfo {
+  phase: SafetyPhase;
+  stepId: string;
+  /** The effect input ("input" and "output" phases; `undefined` on "delta"). */
+  input: unknown;
+  /** The effect result — present only on the "output" phase. */
+  result?: unknown;
+  /**
+   * The RUNNING text of a streamed call — present only on the "delta" phase. It is the
+   * last {@link SafetyOptions.deltaWindow} characters received so far INCLUDING the delta
+   * under test, so a pattern split across deltas is seen whole (up to the window).
+   */
+  text?: string;
+}
+
+export interface SafetyVerdict {
+  ok: boolean;
+  reason?: string;
+}
+
+export interface SafetyValidator {
+  id: string;
+  phase: SafetyPhase;
+  category?: string;
+  /**
+   * Return `{ ok: false }` to block. Should be pure/deterministic. A `"delta"`-phase
+   * validator receives `info.text` (the running streamed text) and runs ONLY on a
+   * streamed call, severing the stream before the offending delta is delivered.
+   */
+  check(info: SafetyCheckInfo): SafetyVerdict;
+  /**
+   * ADR 0119 — the DELTA FORM of an `"output"` validator: the same policy applied to the
+   * running text of a streamed call (`info.phase === "delta"`, `info.text`). An output
+   * validator WITHOUT one cannot see a stream, so when any is configured the runtime
+   * REFUSES streaming to every delta sink — per-call and configured (`EffectMiddleware.inspectsOutput`) rather than stream
+   * text past it. The output form still runs on the final result either way.
+   */
+  checkDelta?(info: SafetyCheckInfo): SafetyVerdict;
+}
+
+export interface SafetyOptions {
+  validators: readonly SafetyValidator[];
+  /**
+   * ADR 0119 — how many trailing characters of a streamed call's running text a delta
+   * check sees (default 4096). It bounds per-delta cost (the check is O(window), not
+   * O(text so far)). A pattern that SPANS more than the window across deltas can evade
+   * the delta check; the output form still sees the whole result, but by then the
+   * caller's live tail has already received it. Text BEFORE a match completes is also
+   * delivered (a card number is severed at its last digit, not its first) — a delta
+   * form narrows what a live tail can show, it does not make a stream as safe as a
+   * buffered result.
+   */
+  deltaWindow?: number;
+}
+
+export class SafetyViolationError extends Error {
+  readonly validatorId: string;
+  readonly category: string | undefined;
+  readonly reason: string;
+  /**
+   * Honoured by `retryMiddleware`'s default classifier: a violation is a policy decision,
+   * not a transient fault. Retrying re-calls the provider — for a severed stream (ADR 0119)
+   * that is a second paid call whose deltas a live tail already started showing. An app
+   * that wants "regenerate on violation" opts in with an explicit `isRetryable`.
+   */
+  readonly retryable = false;
+  constructor(validatorId: string, reason: string, category?: string) {
+    super(`Safety violation [${validatorId}]: ${reason}`);
+    this.name = "SafetyViolationError";
+    this.validatorId = validatorId;
+    this.category = category;
+    this.reason = reason;
+  }
+}
+
+export function safetyMiddleware(options: SafetyOptions): EffectMiddleware {
+  const inputValidators = options.validators.filter((v) => v.phase === "input");
+  const outputValidators = options.validators.filter((v) => v.phase === "output");
+  // The delta checks: a delta-phase validator's `check`, an output validator's `checkDelta`.
+  const deltaChecks: Array<{ v: SafetyValidator; run: (i: SafetyCheckInfo) => SafetyVerdict }> = [];
+  for (const v of options.validators) {
+    if (v.phase === "delta") deltaChecks.push({ v, run: (i) => v.check(i) });
+    else if (v.phase === "output" && v.checkDelta !== undefined) {
+      const f = v.checkDelta.bind(v);
+      deltaChecks.push({ v, run: f });
+    }
+  }
+  const uncoveredOutput = outputValidators.some((v) => v.checkDelta === undefined);
+  const window = Math.max(1, options.deltaWindow ?? 4096);
+
+  const block = (ctx: EffectContext, v: SafetyValidator, phase: SafetyPhase, reason: string) => {
+    ctx.emit("SAFETY_BLOCKED", {
+      stepId: ctx.stepId,
+      validatorId: v.id,
+      phase,
+      reason,
+      ...(v.category !== undefined && { category: v.category }),
+    });
+    throw new SafetyViolationError(v.id, reason, v.category);
+  };
+
+  const run = (ctx: EffectContext, validators: SafetyValidator[], info: SafetyCheckInfo): void => {
+    for (const v of validators) {
+      const verdict = v.check(info);
+      if (!verdict.ok) block(ctx, v, info.phase, verdict.reason ?? "blocked");
+    }
+  };
+
+  const mw = async (ctx: EffectContext, input: unknown, next: () => Promise<unknown>) => {
+    run(ctx, inputValidators, { phase: "input", stepId: ctx.stepId, input });
+    const result = await next();
+    if (outputValidators.length > 0) {
+      run(ctx, outputValidators, { phase: "output", stepId: ctx.stepId, input, result });
+    }
+    return result;
+  };
+
+  return Object.assign(mw, {
+    // An output validator with no delta form cannot see a stream: tell the runtime so it
+    // refuses a live sink instead of streaming text past it (fail-closed).
+    ...(uncoveredOutput && { inspectsOutput: true as const }),
+    ...(deltaChecks.length > 0 && {
+      deltaGuard: (ctx: EffectContext) => {
+        let text = "";
+        return (delta: string): void => {
+          text = (text + delta).slice(-window);
+          for (const { v, run: check } of deltaChecks) {
+            const verdict = check({ phase: "delta", stepId: ctx.stepId, input: undefined, text });
+            if (!verdict.ok) block(ctx, v, "delta", verdict.reason ?? "blocked");
+          }
+        };
+      },
+    }),
+  }) as EffectMiddleware;
+}
+
+// ── Built-in validators ──────────────────────────────────────────────────────
+
+function asText(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value ?? "");
+}
+
+/** Block if the checked value (input or result) matches any pattern (jailbreak/policy). */
+export function denyPatterns(
+  patterns: readonly RegExp[],
+  opts: { id?: string; phase?: SafetyPhase; category?: string } = {}
+): SafetyValidator {
+  const phase = opts.phase ?? "output";
+  const scan = (text: string): SafetyVerdict => {
+    for (const p of patterns) {
+      if (p.test(text)) return { ok: false, reason: `matched ${p}` };
+    }
+    return { ok: true };
+  };
+  return {
+    id: opts.id ?? "deny-patterns",
+    phase,
+    category: opts.category ?? "policy",
+    check(info) {
+      return scan(
+        info.phase === "delta"
+          ? (info.text ?? "")
+          : asText(phase === "output" ? info.result : info.input)
+      );
+    },
+    // The delta form of the default (output) validator: the same patterns over the running
+    // text, so a default config protects a stream. An input-phase validator has none.
+    ...(phase === "output" && { checkDelta: (info: SafetyCheckInfo) => scan(info.text ?? "") }),
+  };
+}
+
+/** Block if the checked value contains obvious PII (email, US SSN, card-like digits). */
+export function piiValidator(opts: { id?: string; phase?: SafetyPhase } = {}): SafetyValidator {
+  const PII: RegExp[] = [
+    /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/, // email
+    /\b\d{3}-\d{2}-\d{4}\b/, // US SSN
+    /\b(?:\d[ -]?){13,16}\b/, // card-like
+  ];
+  return {
+    ...denyPatterns(PII, { id: opts.id ?? "pii", ...(opts.phase && { phase: opts.phase }) }),
+    category: "pii",
+  };
+}
+
+/** A minimal Zod-compatible shape — anything with a `safeParse`. */
+export interface SchemaLike {
+  safeParse(value: unknown): { success: boolean };
+}
+
+/** Enforce an effect's output schema at runtime (schemas are defined-but-unchecked today). */
+export function schemaValidator(schema: SchemaLike, opts: { id?: string } = {}): SafetyValidator {
+  return {
+    id: opts.id ?? "schema",
+    phase: "output",
+    category: "schema",
+    check(info) {
+      return schema.safeParse(info.result).success
+        ? { ok: true }
+        : { ok: false, reason: "output failed schema validation" };
+    },
+  };
+}
+
+/** A real kill-switch: block every effect while `isTripped()` returns true (distinct from K4). */
+export function killSwitch(isTripped: () => boolean, opts: { id?: string } = {}): SafetyValidator {
+  return {
+    id: opts.id ?? "kill-switch",
+    phase: "input",
+    category: "kill-switch",
+    check() {
+      return isTripped() ? { ok: false, reason: "kill-switch engaged" } : { ok: true };
+    },
+  };
+}