@loomwork/middleware 0.0.0-stage → 0.1.1

package/dist/metering.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = void 0;
+exports.isBuiltinDimension = isBuiltinDimension;
+exports.isCustomDimensionName = isCustomDimensionName;
+exports.assertMaxCustom = assertMaxCustom;
+exports.overCustomBudget = overCustomBudget;
+exports.meteredPayload = meteredPayload;
+exports.llmUsageTokens = llmUsageTokens;
+exports.meteringMiddleware = meteringMiddleware;
+// ── Resource accounting & quotas (Loom 2.0 K3) ───────────────────────────────
+//
+// The scarce resource for intelligent software is tokens / $ / latency, not CPU
+// cycles. This middleware meters every effect it wraps as a durable RESOURCE_METERED
+// fact (folded into `variables._resources`), and — given a budget — enforces a quota
+// by admission control: once an execution has spent its budget, the next effect is
+// refused (QUOTA_EXCEEDED + a thrown QuotaExceededError that fails the step). Both
+// the accounting and the enforcement are replay-safe (metered facts live in the log;
+// the running total is read from the deterministic fold via `ctx.resources`).
+const core_1 = require("@loomwork/core");
+/** True when `name` is a built-in metering dimension (never a custom one). */
+function isBuiltinDimension(name) {
+    return core_1.BUILTIN_METER_DIMENSIONS.has(name);
+}
+/** True when `name` is a valid custom dimension name (pattern shared with the fold's guard). */
+function isCustomDimensionName(name) {
+    return (0, core_1.isVocabularyName)(name) && !core_1.BUILTIN_METER_DIMENSIONS.has(name);
+}
+/**
+ * Validate a `Budget.maxCustom` and return a FROZEN shallow copy to enforce against (so a later
+ * mutation of the caller's object cannot smuggle in a built-in name or a bad ceiling). Refuses a
+ * built-in dimension name (use `maxTokens` etc.: a custom ceiling on `tokens` would read
+ * `_resources.custom.tokens`, which nothing meters) and a non-numeric ceiling.
+ */
+function assertMaxCustom(maxCustom) {
+    if (maxCustom === undefined)
+        return undefined;
+    for (const [name, max] of Object.entries(maxCustom)) {
+        if (core_1.BUILTIN_METER_DIMENSIONS.has(name)) {
+            throw new Error(`Budget.maxCustom."${name}" names a built-in dimension; use its own max field (e.g. maxTokens)`);
+        }
+        if (typeof max !== "number" || !Number.isFinite(max) || max < 0) {
+            throw new Error(`Budget.maxCustom."${name}" must be a finite non-negative number`);
+        }
+    }
+    return Object.freeze({ ...maxCustom });
+}
+/** The first custom ceiling the spend has reached, as a reason — own-property reads only. */
+function overCustomBudget(custom, maxCustom) {
+    if (maxCustom === undefined)
+        return null;
+    for (const [name, max] of Object.entries(maxCustom)) {
+        const spent = custom !== undefined && Object.hasOwn(custom, name) ? custom[name] : 0;
+        if (spent >= max)
+            return `${name} ${spent} >= budget ${max}`;
+    }
+    return null;
+}
+class QuotaExceededError extends Error {
+    reason;
+    /** A budget refusal is a decision; retrying repeats it (`retryMiddleware` honours this). */
+    retryable = false;
+    constructor(reason) {
+        super(`Quota exceeded: ${reason}`);
+        this.name = "QuotaExceededError";
+        this.reason = reason;
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;
+function overBudget(r, b) {
+    if (b.maxCostUsd !== undefined && r.costUsd >= b.maxCostUsd) {
+        return `cost ${r.costUsd} >= budget ${b.maxCostUsd} USD`;
+    }
+    if (b.maxTokens !== undefined && r.tokens >= b.maxTokens) {
+        return `tokens ${r.tokens} >= budget ${b.maxTokens}`;
+    }
+    if (b.maxMemBytes !== undefined && (r.memBytes ?? 0) >= b.maxMemBytes) {
+        return `memBytes ${r.memBytes ?? 0} >= budget ${b.maxMemBytes}`;
+    }
+    if (b.maxWallMs !== undefined && (r.wallMs ?? 0) >= b.maxWallMs) {
+        return `wallMs ${r.wallMs ?? 0} >= budget ${b.maxWallMs}`;
+    }
+    if (b.maxNetBytes !== undefined && (r.netBytes ?? 0) >= b.maxNetBytes) {
+        return `netBytes ${r.netBytes ?? 0} >= budget ${b.maxNetBytes}`;
+    }
+    return overCustomBudget(r.custom, b.maxCustom);
+}
+/** The RESOURCE_METERED payload for a delta — only dimensions the pricing reported. */
+function meteredPayload(delta, ms) {
+    return {
+        ...(delta.tokens !== undefined && { tokens: delta.tokens }),
+        ...(delta.costUsd !== undefined && { costUsd: delta.costUsd }),
+        ...(delta.memBytes !== undefined && { memBytes: delta.memBytes }),
+        ...(delta.wallMs !== undefined && { wallMs: delta.wallMs }),
+        ...(delta.netBytes !== undefined && { netBytes: delta.netBytes }),
+        ...(delta.custom !== undefined && { custom: delta.custom }),
+        ms: delta.ms ?? ms,
+    };
+}
+/** Read token usage from an LlmResponse-shaped result (`{ usage: { inputTokens, outputTokens } }`). */
+function llmUsageTokens(result) {
+    const usage = result
+        ?.usage;
+    if (usage === undefined || usage === null)
+        return 0;
+    return (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+}
+function meteringMiddleware(options) {
+    const now = options.clock ?? (() => Date.now());
+    const frozenMax = assertMaxCustom(options.budget?.maxCustom);
+    const budget = options.budget === undefined
+        ? undefined
+        : { ...options.budget, ...(frozenMax !== undefined && { maxCustom: frozenMax }) };
+    return async (ctx, input, next) => {
+        // Admission control: refuse if the execution has already spent its budget.
+        if (budget !== undefined && ctx.resources !== undefined) {
+            const reason = overBudget(ctx.resources, budget);
+            if (reason !== null) {
+                ctx.emit("QUOTA_EXCEEDED", { stepId: ctx.stepId, reason });
+                throw new QuotaExceededError(reason);
+            }
+        }
+        const start = now();
+        let result;
+        try {
+            result = await next();
+        }
+        catch (err) {
+            // K8 — meter an aborted effect before rethrowing. Metering normally runs
+            // after next(), so a severed call would never be seen and
+            // start-expensive-effect → cancel → repeat could evade the budget forever.
+            // Only aborts are metered here; an ordinary failure keeps today's
+            // unmetered semantics.
+            if (ctx.signal?.aborted === true) {
+                const ms = now() - start;
+                const delta = options.pricing({
+                    stepId: ctx.stepId,
+                    input,
+                    result: undefined,
+                    ms,
+                    aborted: true,
+                });
+                ctx.emit("RESOURCE_METERED", meteredPayload(delta, ms));
+            }
+            throw err;
+        }
+        const ms = now() - start;
+        const delta = options.pricing({ stepId: ctx.stepId, input, result, ms });
+        ctx.emit("RESOURCE_METERED", meteredPayload(delta, ms));
+        return result;
+    };
+}
+//# sourceMappingURL=metering.js.map

package/dist/metering.js.map

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

package/dist/nestedBudget.d.ts

@@ -0,0 +1,60 @@
+import type { EffectContext, EffectMiddleware } from "@loomwork/effect-runtime";
+import { type Budget, type Pricing, type ResourceDelta } from "./metering";
+export interface ScopeSpend {
+    tokens: number;
+    costUsd: number;
+    memBytes?: number;
+    wallMs?: number;
+    netBytes?: number;
+    /** ADR 0115 — open dimensions, accumulated by name (own-property keys only). */
+    custom?: Record<string, number>;
+}
+/**
+ * A projection of spend per scope key (e.g. `tenant:acme`, `workflow:audit`).
+ * The app updates it from the RESOURCE_METERED event stream (across all of a
+ * tenant's executions) — typically in `defineConfig({ onEvent })`. It is
+ * eventually consistent by nature; two nodes may briefly under-count, which is
+ * the accepted trade-off for cross-execution budgets.
+ */
+export declare class BudgetLedger {
+    private readonly spend;
+    add(scopeKey: string, delta: ResourceDelta): void;
+    spent(scopeKey: string): ScopeSpend;
+    /** Fold a RESOURCE_METERED event into the given scope keys (from an onEvent hook). */
+    applyMetered(scopeKeys: readonly string[], payload: unknown): void;
+}
+/** One level of the nesting: a labelled scope key + its budget. */
+export interface BudgetScope {
+    /** e.g. "tenant", "workflow", "execution" — recorded in the trip for attribution. */
+    level: string;
+    /** The ledger key this level accumulates under (execution uses ctx.resources instead). */
+    key: string;
+    budget: Budget;
+}
+export interface NestedBudgetOptions {
+    /** Cost model — same shape as `meteringMiddleware`. */
+    pricing: Pricing;
+    /** The cross-execution spend projection (tenant/workflow levels). */
+    ledger: BudgetLedger;
+    /**
+     * Resolve the nested scopes for an effect, OUTERMOST (broadest) first. The
+     * execution level should use `key: ""` — its spend is read from the pure
+     * per-execution fold (`ctx.resources`), not the ledger.
+     */
+    scopesOf: (ctx: EffectContext) => BudgetScope[];
+    /** Injectable clock for the measured `ms`. */
+    clock?: () => number;
+}
+/**
+ * K12.3 — nested-budget admission control. Before an effect runs, every scope
+ * (tenant → workflow → execution) is checked; the FIRST (most-restrictive)
+ * breach denies with a `QUOTA_EXCEEDED` fact attributed to that `level`, and the
+ * effect never runs. Otherwise the effect runs, is priced, and its delta is
+ * recorded into the ledger's non-execution scopes (the execution level is
+ * metered by the durable fold as usual) and emitted as `RESOURCE_METERED`.
+ *
+ * The execution level reads spend from `ctx.resources` (the pure fold, K3); the
+ * broader levels read from the ledger projection.
+ */
+export declare function nestedBudgetMiddleware(options: NestedBudgetOptions): EffectMiddleware;
+//# sourceMappingURL=nestedBudget.d.ts.map

package/dist/nestedBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestedBudget.d.ts","sourceRoot":"","sources":["../src/nestedBudget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EACL,KAAK,MAAM,EACX,KAAK,OAAO,EAEZ,KAAK,aAAa,EAInB,MAAM,YAAY,CAAC;AAcpB,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAEhB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAKD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IA4BjD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAInC,sFAAsF;IACtF,YAAY,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;CAqBnE;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,WAAW,EAAE,CAAC;IAChD,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAkDrF"}

package/dist/nestedBudget.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetLedger = void 0;
+exports.nestedBudgetMiddleware = nestedBudgetMiddleware;
+const metering_1 = require("./metering");
+/** Distinct custom dimension names one ledger scope keeps (the fold's own cap, ADR 0115). */
+const LEDGER_CUSTOM_MAX = 32;
+/**
+ * A projection of spend per scope key (e.g. `tenant:acme`, `workflow:audit`).
+ * The app updates it from the RESOURCE_METERED event stream (across all of a
+ * tenant's executions) — typically in `defineConfig({ onEvent })`. It is
+ * eventually consistent by nature; two nodes may briefly under-count, which is
+ * the accepted trade-off for cross-execution budgets.
+ */
+class BudgetLedger {
+    spend = new Map();
+    add(scopeKey, delta) {
+        const cur = this.spend.get(scopeKey) ?? { tokens: 0, costUsd: 0 };
+        const memBytes = (cur.memBytes ?? 0) + (delta.memBytes ?? 0);
+        const wallMs = (cur.wallMs ?? 0) + (delta.wallMs ?? 0);
+        const netBytes = (cur.netBytes ?? 0) + (delta.netBytes ?? 0);
+        let custom = cur.custom;
+        if (delta.custom !== undefined) {
+            custom = { ...cur.custom };
+            for (const [name, v] of Object.entries(delta.custom)) {
+                if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+                    continue;
+                if (name === "constructor" || name === "prototype" || !(0, metering_1.isCustomDimensionName)(name))
+                    continue;
+                if (!Object.hasOwn(custom, name) && Object.keys(custom).length >= LEDGER_CUSTOM_MAX) {
+                    continue;
+                }
+                custom[name] = (Object.hasOwn(custom, name) ? custom[name] : 0) + v;
+            }
+        }
+        this.spend.set(scopeKey, {
+            tokens: cur.tokens + (delta.tokens ?? 0),
+            ...(custom !== undefined && { custom }),
+            costUsd: cur.costUsd + (delta.costUsd ?? 0),
+            ...(memBytes > 0 && { memBytes }),
+            ...(wallMs > 0 && { wallMs }),
+            ...(netBytes > 0 && { netBytes }),
+        });
+    }
+    spent(scopeKey) {
+        return this.spend.get(scopeKey) ?? { tokens: 0, costUsd: 0 };
+    }
+    /** Fold a RESOURCE_METERED event into the given scope keys (from an onEvent hook). */
+    applyMetered(scopeKeys, payload) {
+        const p = payload;
+        const delta = {
+            ...(p.custom !== undefined &&
+                typeof p.custom === "object" &&
+                p.custom !== null && { custom: p.custom }),
+            ...(p.tokens !== undefined && { tokens: p.tokens }),
+            ...(p.costUsd !== undefined && { costUsd: p.costUsd }),
+            ...(p.memBytes !== undefined && { memBytes: p.memBytes }),
+            ...(p.wallMs !== undefined && { wallMs: p.wallMs }),
+            ...(p.netBytes !== undefined && { netBytes: p.netBytes }),
+        };
+        for (const key of scopeKeys)
+            this.add(key, delta);
+    }
+}
+exports.BudgetLedger = BudgetLedger;
+function over(spent, b) {
+    return ((b.maxCostUsd !== undefined && spent.costUsd >= b.maxCostUsd) ||
+        (b.maxTokens !== undefined && spent.tokens >= b.maxTokens) ||
+        (b.maxMemBytes !== undefined && (spent.memBytes ?? 0) >= b.maxMemBytes) ||
+        (b.maxWallMs !== undefined && (spent.wallMs ?? 0) >= b.maxWallMs) ||
+        (b.maxNetBytes !== undefined && (spent.netBytes ?? 0) >= b.maxNetBytes) ||
+        (0, metering_1.overCustomBudget)(spent.custom, b.maxCustom) !== null);
+}
+/**
+ * K12.3 — nested-budget admission control. Before an effect runs, every scope
+ * (tenant → workflow → execution) is checked; the FIRST (most-restrictive)
+ * breach denies with a `QUOTA_EXCEEDED` fact attributed to that `level`, and the
+ * effect never runs. Otherwise the effect runs, is priced, and its delta is
+ * recorded into the ledger's non-execution scopes (the execution level is
+ * metered by the durable fold as usual) and emitted as `RESOURCE_METERED`.
+ *
+ * The execution level reads spend from `ctx.resources` (the pure fold, K3); the
+ * broader levels read from the ledger projection.
+ */
+function nestedBudgetMiddleware(options) {
+    const now = options.clock ?? (() => Date.now());
+    return async (ctx, input, next) => {
+        const scopes = options.scopesOf(ctx);
+        // Scopes are resolved per effect, so their budgets cannot be checked at construction; refuse a
+        // bad `maxCustom` (built-in name / non-numeric ceiling) here, before any scope is evaluated,
+        // rather than part-way through the admission loop. Not memoised: a mutation cannot bypass it.
+        for (const scope of scopes)
+            (0, metering_1.assertMaxCustom)(scope.budget.maxCustom);
+        // Admission control — most-restrictive wins, attributed to its level.
+        for (const scope of scopes) {
+            const spent = scope.level === "execution"
+                ? {
+                    tokens: ctx.resources?.tokens ?? 0,
+                    costUsd: ctx.resources?.costUsd ?? 0,
+                    ...(ctx.resources?.memBytes !== undefined && { memBytes: ctx.resources.memBytes }),
+                    ...(ctx.resources?.wallMs !== undefined && { wallMs: ctx.resources.wallMs }),
+                    ...(ctx.resources?.netBytes !== undefined && { netBytes: ctx.resources.netBytes }),
+                    ...(ctx.resources?.custom !== undefined && {
+                        custom: ctx.resources.custom,
+                    }),
+                }
+                : options.ledger.spent(scope.key);
+            if (over(spent, scope.budget)) {
+                const reason = `${scope.level} budget exceeded (${scope.key || ctx.executionId})`;
+                ctx.emit("QUOTA_EXCEEDED", { stepId: ctx.stepId, reason, level: scope.level });
+                throw new metering_1.QuotaExceededError(reason);
+            }
+        }
+        const start = now();
+        const result = await next();
+        const ms = now() - start;
+        const delta = options.pricing({ stepId: ctx.stepId, input, result, ms });
+        ctx.emit("RESOURCE_METERED", {
+            ...(delta.tokens !== undefined && { tokens: delta.tokens }),
+            ...(delta.costUsd !== undefined && { costUsd: delta.costUsd }),
+            ...(delta.custom !== undefined && { custom: delta.custom }),
+            ms: delta.ms ?? ms,
+        });
+        // Update the projection for the broader (non-execution) levels immediately,
+        // so within a node successive effects see the running total (the durable
+        // fold + cross-node ledger reconcile via the RESOURCE_METERED stream).
+        for (const scope of scopes) {
+            if (scope.level !== "execution")
+                options.ledger.add(scope.key, delta);
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=nestedBudget.js.map

package/dist/nestedBudget.js.map

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

package/dist/profile.d.ts

@@ -0,0 +1,38 @@
+import type { EffectMiddleware } from "@loomwork/effect-runtime";
+/** Effect-side timings, in milliseconds. */
+export interface EffectProfile {
+    /** Effect invocations that completed (successfully or not). */
+    calls: number;
+    /** Summed wall time inside effects. */
+    totalEffectMs: number;
+    /** Longest single effect. */
+    maxEffectMs: number;
+    /** Greatest number of effects in flight at once. */
+    peakConcurrentEffects: number;
+    /** Per-tool breakdown, so a single slow tool is visible rather than averaged away. */
+    byTool: Record<string, {
+        calls: number;
+        totalMs: number;
+    }>;
+}
+export interface EffectProfiler {
+    middleware: EffectMiddleware;
+    profile(): EffectProfile;
+    reset(): void;
+}
+/**
+ * Measures what effects actually cost, as the counterpart to `ProfilingEventStore`.
+ *
+ * Together they answer [ADR 0065](../../../docs/adr/0065-group-commit-deferred-evidence-gate.md)
+ * gate 1: is **event-write throughput** the bottleneck for this workload, or is it effect
+ * latency? The gate requires that question be settled by profiling rather than intuition,
+ * and it is not rhetorical — `ExecutionJournal` queues appends on a serial tail, so the
+ * interpreter is decoupled from write latency and a workload can write a great deal without
+ * writes ever constraining it.
+ *
+ * Wire it as effect-runtime middleware in your own app, wrap your store in
+ * `ProfilingEventStore`, run real traffic, and compare `totalEffectMs` against
+ * `totalWriteMs`. Batching the write path can only help if the latter dominates.
+ */
+export declare function effectTimingMiddleware(): EffectProfiler;
+//# sourceMappingURL=profile.d.ts.map

package/dist/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,IAAI,aAAa,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CAiDvD"}

package/dist/profile.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectTimingMiddleware = effectTimingMiddleware;
+/**
+ * Measures what effects actually cost, as the counterpart to `ProfilingEventStore`.
+ *
+ * Together they answer [ADR 0065](../../../docs/adr/0065-group-commit-deferred-evidence-gate.md)
+ * gate 1: is **event-write throughput** the bottleneck for this workload, or is it effect
+ * latency? The gate requires that question be settled by profiling rather than intuition,
+ * and it is not rhetorical — `ExecutionJournal` queues appends on a serial tail, so the
+ * interpreter is decoupled from write latency and a workload can write a great deal without
+ * writes ever constraining it.
+ *
+ * Wire it as effect-runtime middleware in your own app, wrap your store in
+ * `ProfilingEventStore`, run real traffic, and compare `totalEffectMs` against
+ * `totalWriteMs`. Batching the write path can only help if the latter dominates.
+ */
+function effectTimingMiddleware() {
+    let calls = 0;
+    let totalEffectMs = 0;
+    let maxEffectMs = 0;
+    let inFlight = 0;
+    let peakConcurrentEffects = 0;
+    const byTool = new Map();
+    const middleware = async (ctx, input, next) => {
+        const started = performance.now();
+        inFlight++;
+        if (inFlight > peakConcurrentEffects)
+            peakConcurrentEffects = inFlight;
+        try {
+            return await next(input);
+        }
+        finally {
+            const elapsed = performance.now() - started;
+            inFlight--;
+            calls++;
+            totalEffectMs += elapsed;
+            if (elapsed > maxEffectMs)
+                maxEffectMs = elapsed;
+            // `stepId` is the tool identity at this seam; fall back so an unnamed effect still
+            // shows up rather than vanishing from the breakdown.
+            const tool = ctx.stepId || "<unknown>";
+            const entry = byTool.get(tool);
+            if (entry === undefined)
+                byTool.set(tool, { calls: 1, totalMs: elapsed });
+            else {
+                entry.calls++;
+                entry.totalMs += elapsed;
+            }
+        }
+    };
+    return {
+        middleware,
+        profile: () => ({
+            calls,
+            totalEffectMs,
+            maxEffectMs,
+            peakConcurrentEffects,
+            byTool: Object.fromEntries([...byTool].map(([k, v]) => [k, { ...v }])),
+        }),
+        reset: () => {
+            calls = 0;
+            totalEffectMs = 0;
+            maxEffectMs = 0;
+            peakConcurrentEffects = 0;
+            byTool.clear();
+        },
+    };
+}
+//# sourceMappingURL=profile.js.map

package/dist/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":";;AAoCA,wDAiDC;AA/DD;;;;;;;;;;;;;GAaG;AACH,SAAgB,sBAAsB;IACpC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,qBAAqB,GAAG,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8C,CAAC;IAErE,MAAM,UAAU,GAAqB,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC9D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,QAAQ,EAAE,CAAC;QACX,IAAI,QAAQ,GAAG,qBAAqB;YAAE,qBAAqB,GAAG,QAAQ,CAAC;QACvE,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;YAC5C,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE,CAAC;YACR,aAAa,IAAI,OAAO,CAAC;YACzB,IAAI,OAAO,GAAG,WAAW;gBAAE,WAAW,GAAG,OAAO,CAAC;YACjD,mFAAmF;YACnF,qDAAqD;YACrD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,WAAW,CAAC;YACvC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,KAAK,KAAK,SAAS;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;iBACrE,CAAC;gBACJ,KAAK,CAAC,KAAK,EAAE,CAAC;gBACd,KAAK,CAAC,OAAO,IAAI,OAAO,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,UAAU;QACV,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,KAAK;YACL,aAAa;YACb,WAAW;YACX,qBAAqB;YACrB,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;SACvE,CAAC;QACF,KAAK,EAAE,GAAG,EAAE;YACV,KAAK,GAAG,CAAC,CAAC;YACV,aAAa,GAAG,CAAC,CAAC;YAClB,WAAW,GAAG,CAAC,CAAC;YAChB,qBAAqB,GAAG,CAAC,CAAC;YAC1B,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/rateLimit.d.ts

@@ -0,0 +1,40 @@
+import type { EffectMiddleware } from "@loomwork/effect-runtime";
+/** 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 declare 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);
+}
+export declare function rateLimitMiddleware(options: RateLimitOptions): EffectMiddleware;
+//# sourceMappingURL=rateLimit.d.ts.map

package/dist/rateLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimit.d.ts","sourceRoot":"","sources":["../src/rateLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAgBhF,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,SAAS,SAAS;gBACf,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAOrE;AAoBD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CA6C/E"}

package/dist/rateLimit.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitExceededError = void 0;
+exports.rateLimitMiddleware = rateLimitMiddleware;
+/**
+ * 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.
+ */
+class RateLimitExceededError extends Error {
+    scope;
+    key;
+    /** Milliseconds until one token is available again (a hint, never a promise). */
+    retryAfterMs;
+    /** Honoured by `retryMiddleware`'s default classifier: an immediate retry repeats the refusal. */
+    retryable = false;
+    constructor(scope, key, retryAfterMs) {
+        super(`Rate limit exceeded for ${scope} "${key}" — retry after ~${retryAfterMs}ms`);
+        this.name = "RateLimitExceededError";
+        this.scope = scope;
+        this.key = key;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+exports.RateLimitExceededError = RateLimitExceededError;
+function keyOf(scope, ctx) {
+    switch (scope) {
+        case "execution":
+            return ctx.executionId;
+        case "workflow":
+            return ctx.workflowId;
+        case "tenant":
+            return ctx.principal?.tenant ?? "(no-tenant)";
+        case "global":
+            return "*";
+    }
+}
+function rateLimitMiddleware(options) {
+    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();
+    return async (ctx, _input, next) => {
+        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();
+    };
+}
+//# sourceMappingURL=rateLimit.js.map

package/dist/rateLimit.js.map

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