@loomwork/middleware 0.0.0-stage → 0.1.0

package/dist/redaction.d.ts

@@ -0,0 +1,66 @@
+import type { StepDefinition } from "@loomwork/core";
+import type { EffectMiddleware } from "@loomwork/effect-runtime";
+/** The deterministic reference that stands in for a secret in step I/O and the log. */
+export interface SecretRef {
+    readonly __loomSecret: string;
+}
+export declare function secretRef(id: string): SecretRef;
+export declare function isSecretRef(value: unknown): value is SecretRef;
+/**
+ * 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 declare class InMemorySecretResolver implements SecretResolver {
+    private readonly secrets;
+    constructor(secrets?: Map<string, unknown>);
+    resolve(id: string): unknown;
+    store(id: string, value: unknown): void;
+}
+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[];
+}
+/**
+ * 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 declare function redactionMiddleware(options: RedactionOptions): EffectMiddleware;
+/**
+ * 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 declare function secretOutputPathsByStep(steps: readonly Pick<StepDefinition, "id" | "outputSchema">[]): Map<string, readonly string[]>;
+/**
+ * A {@link RedactionOptions.redactOutput} callback derived from `secret()` marks — pass the
+ * result of {@link secretOutputPathsByStep} (or let `defineConfig({ secrets })` wire it).
+ */
+export declare function redactOutputFrom(byStep: Map<string, readonly string[]>): (info: {
+    stepId: string;
+}) => readonly string[];
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAiB,gBAAgB,EAAc,MAAM,0BAA0B,CAAC;AAc5F,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAM9D;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAChD,kFAAkF;IAClF,KAAK,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,qBAAa,sBAAuB,YAAW,cAAc;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAa;IACtE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI5B,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;CAGxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,MAAM,EAAE,CAAC;CAChE;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAkC/E;AAcD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAGrC,KAAK,EAAE,SAAS,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,cAAc,CAAC,EAAE,GAC5D,GAAG,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAQhC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GACrC,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,SAAS,MAAM,EAAE,CAEjD"}

package/dist/redaction.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemorySecretResolver = void 0;
+exports.secretRef = secretRef;
+exports.isSecretRef = isSecretRef;
+exports.redactionMiddleware = redactionMiddleware;
+exports.secretOutputPathsByStep = secretOutputPathsByStep;
+exports.redactOutputFrom = redactOutputFrom;
+const classify_1 = require("@loomwork/classify");
+function secretRef(id) {
+    return { __loomSecret: id };
+}
+function isSecretRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.__loomSecret === "string");
+}
+class InMemorySecretResolver {
+    secrets;
+    constructor(secrets = new Map()) {
+        this.secrets = secrets;
+    }
+    resolve(id) {
+        if (!this.secrets.has(id))
+            throw new Error(`no secret registered for reference "${id}"`);
+        return this.secrets.get(id);
+    }
+    store(id, value) {
+        this.secrets.set(id, value);
+    }
+}
+exports.InMemorySecretResolver = InMemorySecretResolver;
+async function deepResolve(value, resolver) {
+    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 = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = await deepResolve(v, resolver);
+        return out;
+    }
+    return value;
+}
+function getPath(root, path) {
+    const segs = path.split(".");
+    let cursor = root;
+    for (let i = 0; i < segs.length - 1; i++) {
+        const next = cursor?.[segs[i]];
+        cursor =
+            typeof next === "object" && next !== null ? next : undefined;
+        if (cursor === undefined)
+            return undefined;
+    }
+    const leaf = segs[segs.length - 1];
+    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).
+ */
+function redactionMiddleware(options) {
+    const mw = async (ctx, input, next) => {
+        // 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 }) : mw);
+}
+// ── 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).
+ */
+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) {
+    const byStep = new Map();
+    for (const step of steps) {
+        if (step.outputSchema === undefined)
+            continue;
+        const paths = (0, classify_1.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).
+ */
+function redactOutputFrom(byStep) {
+    return ({ stepId }) => byStep.get(stepId) ?? [];
+}
+//# sourceMappingURL=redaction.js.map

package/dist/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}

package/dist/retry.d.ts

@@ -0,0 +1,50 @@
+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 declare function retryMiddleware(options?: RetryOptions): EffectMiddleware;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEhF,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACxC,yDAAyD;IACzD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACjG,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,YAAiB,GAAG,gBAAgB,CAmC5E"}

package/dist/retry.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryMiddleware = retryMiddleware;
+const core_1 = require("@loomwork/core");
+/**
+ * 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.
+ */
+function retryMiddleware(options = {}) {
+    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) => !(err instanceof core_1.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?.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 core_1.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, cfg, ctx) {
+    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) {
+    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, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(abortError(signal));
+            return;
+        }
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            cleanup();
+            reject(abortError(signal));
+        };
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function abortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error)
+        return reason;
+    return new Error("aborted");
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/safety.d.ts

@@ -0,0 +1,93 @@
+import type { EffectMiddleware } from "@loomwork/effect-runtime";
+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 declare 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);
+}
+export declare function safetyMiddleware(options: SafetyOptions): EffectMiddleware;
+/** Block if the checked value (input or result) matches any pattern (jailbreak/policy). */
+export declare function denyPatterns(patterns: readonly RegExp[], opts?: {
+    id?: string;
+    phase?: SafetyPhase;
+    category?: string;
+}): SafetyValidator;
+/** Block if the checked value contains obvious PII (email, US SSN, card-like digits). */
+export declare function piiValidator(opts?: {
+    id?: string;
+    phase?: SafetyPhase;
+}): SafetyValidator;
+/** 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 declare function schemaValidator(schema: SchemaLike, opts?: {
+    id?: string;
+}): SafetyValidator;
+/** A real kill-switch: block every effect while `isTripped()` returns true (distinct from K4). */
+export declare function killSwitch(isTripped: () => boolean, opts?: {
+    id?: string;
+}): SafetyValidator;
+//# sourceMappingURL=safety.d.ts.map

package/dist/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAmBhF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,aAAa,CAAC;IAC5C;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,eAAe,GAAG,aAAa,CAAC;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,SAAS;gBACf,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAOnE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB,CA2DzE;AAQD,2FAA2F;AAC3F,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,eAAe,CAuBjB;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAO,GAAG,eAAe,CAU7F;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACjD;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,eAAe,CAW/F;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,OAAO,EAAE,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,eAAe,CAShG"}

package/dist/safety.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafetyViolationError = void 0;
+exports.safetyMiddleware = safetyMiddleware;
+exports.denyPatterns = denyPatterns;
+exports.piiValidator = piiValidator;
+exports.schemaValidator = schemaValidator;
+exports.killSwitch = killSwitch;
+class SafetyViolationError extends Error {
+    validatorId;
+    category;
+    reason;
+    /**
+     * 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`.
+     */
+    retryable = false;
+    constructor(validatorId, reason, category) {
+        super(`Safety violation [${validatorId}]: ${reason}`);
+        this.name = "SafetyViolationError";
+        this.validatorId = validatorId;
+        this.category = category;
+        this.reason = reason;
+    }
+}
+exports.SafetyViolationError = SafetyViolationError;
+function safetyMiddleware(options) {
+    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 = [];
+    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, v, phase, reason) => {
+        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, validators, info) => {
+        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, input, next) => {
+        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 }),
+        ...(deltaChecks.length > 0 && {
+            deltaGuard: (ctx) => {
+                let text = "";
+                return (delta) => {
+                    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");
+                    }
+                };
+            },
+        }),
+    });
+}
+// ── Built-in validators ──────────────────────────────────────────────────────
+function asText(value) {
+    return typeof value === "string" ? value : JSON.stringify(value ?? "");
+}
+/** Block if the checked value (input or result) matches any pattern (jailbreak/policy). */
+function denyPatterns(patterns, opts = {}) {
+    const phase = opts.phase ?? "output";
+    const scan = (text) => {
+        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) => scan(info.text ?? "") }),
+    };
+}
+/** Block if the checked value contains obvious PII (email, US SSN, card-like digits). */
+function piiValidator(opts = {}) {
+    const PII = [
+        /\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",
+    };
+}
+/** Enforce an effect's output schema at runtime (schemas are defined-but-unchecked today). */
+function schemaValidator(schema, opts = {}) {
+    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). */
+function killSwitch(isTripped, opts = {}) {
+    return {
+        id: opts.id ?? "kill-switch",
+        phase: "input",
+        category: "kill-switch",
+        check() {
+            return isTripped() ? { ok: false, reason: "kill-switch engaged" } : { ok: true };
+        },
+    };
+}
+//# sourceMappingURL=safety.js.map

package/dist/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"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"}