@loomwork/middleware 0.0.0-stage → 0.1.0

package/src/killSwitchRegistry.ts

@@ -0,0 +1,168 @@
+import type { EffectContext, EffectMiddleware } from "@loomwork/effect-runtime";
+import { SafetyViolationError } from "./safety";
+
+// ── Scoped kill switch (R9 — autonomy envelope) ──────────────────────────────
+//
+// `killSwitch(isTripped)` (safety.ts) is a synchronous per-process predicate over NOTHING:
+// it cannot say WHICH tenant to stop, and an operator has no handle to reach it. A runaway
+// agent for one tenant needed either a redeploy or stopping everyone.
+//
+// This adds the missing scopes and an admin handle:
+//   system   — every effect in every tenant stops
+//   tenant   — every effect whose principal chain names that tenant stops
+//   workflow — every effect of that flow (the "stop this agent" case)
+//
+// It is consulted BEFORE each effect (outermost middleware) and refuses with a typed
+// `KillSwitchEngagedError`. What it does NOT do — and cannot, in a 1P middleware — is
+// reach an effect already in flight, or cancel a running execution's children: that is the
+// kernel's cancel cascade. A stopped execution fails at its NEXT effect; a flow that
+// catches the refusal and carries on to a non-effect finish is not interrupted.
+//
+// The registry is an SPI so a deployment can back the flags with a shared store (a DB row,
+// a feature-flag service) and stop a tenant across processes; `InMemoryKillSwitch` is the
+// single-process implementation and the reference. `check` may be async — a networked
+// registry should cache with a short TTL, since it sits on every effect.
+
+export type KillScope = "system" | "tenant" | "workflow";
+
+/** Why an effect is being refused. */
+export interface KillVerdict {
+  scope: KillScope;
+  /** The tenant / workflow id (absent for `system`). */
+  key?: string;
+  reason: string;
+}
+
+/**
+ * Where the stop flags live. Return `undefined` to let the effect run. Must be cheap — it is
+ * consulted before EVERY effect — and must fail CLOSED or open as the deployment prefers;
+ * a throw is treated as a refusal (fail closed) by {@link killSwitchMiddleware}.
+ */
+export interface KillSwitchRegistry {
+  /**
+   * Where the stop flags live, DECLARED by the registry. Optional and additive (no SPI version
+   * bump: an absent field changes nothing for any existing registry).
+   *
+   *  - `"process"` — the flags live in this process's memory ({@link InMemoryKillSwitch}); a stop
+   *    issued in another process is invisible here.
+   *  - `"shared"` — the flags live in a store every process reads (a DB row, a feature-flag
+   *    service), so a stop issued anywhere applies here.
+   *
+   * Tooling that runs your effects OUTSIDE the long-running app (`loom resume` / `loom start`)
+   * reads this and is FAIL-CLOSED: only a registry that affirmatively declares `"shared"` is
+   * trusted to carry an operator stop across processes. Absent, or anything else, is treated as
+   * process-local. A wrapper or subclass must re-declare it: forwarding is the wrapper's claim.
+   */
+  readonly scope?: "process" | "shared";
+  check(ctx: EffectContext): KillVerdict | undefined | Promise<KillVerdict | undefined>;
+}
+
+export class KillSwitchEngagedError extends SafetyViolationError {
+  readonly scope: KillScope;
+  readonly key: string | undefined;
+  /** A stop is a decision, not a fault: retrying it just repeats the refusal. */
+  readonly retryable = false;
+  constructor(verdict: KillVerdict) {
+    super(
+      "kill-switch",
+      `${verdict.scope}${verdict.key !== undefined ? ` "${verdict.key}"` : ""} stopped: ${verdict.reason}`,
+      "kill-switch"
+    );
+    this.name = "KillSwitchEngagedError";
+    this.scope = verdict.scope;
+    this.key = verdict.key;
+  }
+}
+
+/** Single-process registry with the operator-facing admin API. */
+export class InMemoryKillSwitch implements KillSwitchRegistry {
+  /** Declares itself process-local (see {@link KillSwitchRegistry.scope}). */
+  readonly scope = "process" as const;
+  private system: string | undefined;
+  private readonly tenants = new Map<string, string>();
+  private readonly workflows = new Map<string, string>();
+
+  /** Stop every effect in the process. */
+  stopAll(reason = "system stop"): void {
+    this.system = reason;
+  }
+  resumeAll(): void {
+    this.system = undefined;
+  }
+  /** Stop every effect whose principal chain names `tenant`. */
+  stopTenant(tenant: string, reason = "tenant stop"): void {
+    this.tenants.set(tenant, reason);
+  }
+  resumeTenant(tenant: string): void {
+    this.tenants.delete(tenant);
+  }
+  /** Stop every effect of one flow (one agent). */
+  stopWorkflow(workflowId: string, reason = "workflow stop"): void {
+    this.workflows.set(workflowId, reason);
+  }
+  resumeWorkflow(workflowId: string): void {
+    this.workflows.delete(workflowId);
+  }
+
+  /** What is currently stopped, for an operator console. */
+  status(): {
+    system?: string;
+    tenants: Record<string, string>;
+    workflows: Record<string, string>;
+  } {
+    return {
+      ...(this.system !== undefined && { system: this.system }),
+      tenants: Object.fromEntries(this.tenants),
+      workflows: Object.fromEntries(this.workflows),
+    };
+  }
+
+  check(ctx: EffectContext): KillVerdict | undefined {
+    if (this.system !== undefined) return { scope: "system", reason: this.system };
+    const tenant = ctx.principal?.tenant;
+    if (tenant !== undefined) {
+      const reason = this.tenants.get(tenant);
+      if (reason !== undefined) return { scope: "tenant", key: tenant, reason };
+    }
+    const wf = this.workflows.get(ctx.workflowId);
+    if (wf !== undefined) return { scope: "workflow", key: ctx.workflowId, reason: wf };
+    return undefined;
+  }
+}
+
+/**
+ * Refuse every effect the registry stops. Place it OUTERMOST so a stopped effect never
+ * resolves a secret or spends budget. The refusal is recorded as a durable `SAFETY_BLOCKED`
+ * fact (the same audit list the K6 kill-switch validator writes) and thrown as
+ * {@link KillSwitchEngagedError}, a `SafetyViolationError` carrying `retryable = false`
+ * (which `retryMiddleware`'s default classifier honours), so it fails the step through the
+ * existing path and is not retried.
+ */
+export function killSwitchMiddleware(registry: KillSwitchRegistry): EffectMiddleware {
+  return async (ctx, _input, next): Promise<unknown> => {
+    let verdict: KillVerdict | undefined;
+    try {
+      verdict = await registry.check(ctx);
+    } catch (err) {
+      // A registry that cannot answer fails CLOSED: a kill switch that errors open is a
+      // switch that is off exactly when the store it reads is down.
+      verdict = {
+        scope: "system",
+        reason: `kill-switch registry unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+    if (verdict !== undefined) {
+      ctx.emit("SAFETY_BLOCKED", {
+        stepId: ctx.stepId,
+        validatorId: "kill-switch",
+        phase: "input",
+        reason: verdict.reason,
+        category: "kill-switch",
+        scope: verdict.scope,
+        ...(verdict.key !== undefined && { key: verdict.key }),
+      });
+      throw new KillSwitchEngagedError(verdict);
+    }
+    return next();
+  };
+}

package/src/metering.ts

@@ -0,0 +1,226 @@
+import type { EffectContext, EffectMiddleware, ResourceSnapshot } from "@loomwork/effect-runtime";
+
+// ── 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`).
+
+import { BUILTIN_METER_DIMENSIONS, isVocabularyName } from "@loomwork/core";
+
+export interface ResourceDelta {
+  tokens?: number;
+  costUsd?: number;
+  ms?: number;
+  // ADR 0032 (R1) — additional dimensions, metered only where an effect can measure
+  // them (e.g. a K7 isolated child reports peak RSS). All optional and additive;
+  // an effect that doesn't report a dimension leaves it undefined (no false zeros).
+  /** Peak resident memory attributable to the effect, in bytes. */
+  memBytes?: number;
+  /** Wall-clock time, in ms (distinct from `ms` when the effect runs off-thread). */
+  wallMs?: number;
+  /** Network bytes transferred by the effect. */
+  netBytes?: number;
+  /**
+   * ADR 0115 — open dimensions (`gpu_seconds`, `credits`), by name. Folded into
+   * `_resources.custom`; the kernel assigns no unit and no price, so converting these to money
+   * is this pricing function's job. At most 32 names, each matching `VOCABULARY_NAME_PATTERN`
+   * (`@loomwork/core`), never a built-in name. A bad name (or value) makes `ctx.emit` throw AFTER the
+   * effect ran, like a built-in ceiling breach.
+   */
+  custom?: Readonly<Record<string, number>>;
+}
+
+export interface MeterInfo {
+  stepId: string;
+  input: unknown;
+  /** The effect's result — `undefined` when metering an aborted effect (K8). */
+  result: unknown;
+  /** Measured wall-time of the effect, in ms. */
+  ms: number;
+  /**
+   * K8 — true when the effect was severed mid-flight (cancellation/deadline).
+   * The wall-time up to the abort is still metered so cancel-before-completion
+   * cannot evade budgets; pricing may add provider-reported partial usage.
+   */
+  aborted?: boolean;
+}
+
+/** Compute the resource delta for one effect call — e.g. tokens×rate for an LLM. */
+export type Pricing = (info: MeterInfo) => ResourceDelta;
+
+export interface Budget {
+  maxTokens?: number;
+  maxCostUsd?: number;
+  // ADR 0032 (R1) — ceilings for the additional dimensions. Only enforced when set.
+  maxMemBytes?: number;
+  maxWallMs?: number;
+  maxNetBytes?: number;
+  /**
+   * ADR 0115 — ceilings for open dimensions, by name (`{ gpu_seconds: 60 }`): an execution whose
+   * `_resources.custom[name]` has reached the ceiling has its next effect denied, like every
+   * other dimension. Only enforced where set.
+   */
+  maxCustom?: Readonly<Record<string, number>>;
+}
+
+/** True when `name` is a built-in metering dimension (never a custom one). */
+export function isBuiltinDimension(name: string): boolean {
+  return BUILTIN_METER_DIMENSIONS.has(name);
+}
+
+/** True when `name` is a valid custom dimension name (pattern shared with the fold's guard). */
+export function isCustomDimensionName(name: string): boolean {
+  return isVocabularyName(name) && !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.
+ */
+export function assertMaxCustom(
+  maxCustom: Readonly<Record<string, number>> | undefined
+): Readonly<Record<string, number>> | undefined {
+  if (maxCustom === undefined) return undefined;
+  for (const [name, max] of Object.entries(maxCustom)) {
+    if (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. */
+export function overCustomBudget(
+  custom: Readonly<Record<string, number>> | undefined,
+  maxCustom: Readonly<Record<string, number>> | undefined
+): string | null {
+  if (maxCustom === undefined) return null;
+  for (const [name, max] of Object.entries(maxCustom)) {
+    const spent =
+      custom !== undefined && Object.hasOwn(custom, name) ? (custom[name] as number) : 0;
+    if (spent >= max) return `${name} ${spent} >= budget ${max}`;
+  }
+  return null;
+}
+
+export interface MeteringOptions {
+  pricing: Pricing;
+  /** When set, an execution over budget has its next effect denied (admission control). */
+  budget?: Budget;
+  /** Injectable clock (defaults to Date.now); only affects the measured `ms`. */
+  clock?: () => number;
+}
+
+export class QuotaExceededError extends Error {
+  readonly reason: string;
+  /** A budget refusal is a decision; retrying repeats it (`retryMiddleware` honours this). */
+  readonly retryable = false;
+  constructor(reason: string) {
+    super(`Quota exceeded: ${reason}`);
+    this.name = "QuotaExceededError";
+    this.reason = reason;
+  }
+}
+
+function overBudget(r: ResourceSnapshot, b: Budget): string | null {
+  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. */
+export function meteredPayload(
+  delta: ResourceDelta,
+  ms: number
+): Record<string, number | Readonly<Record<string, number>>> {
+  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 } }`). */
+export function llmUsageTokens(result: unknown): number {
+  const usage = (result as { usage?: { inputTokens?: number; outputTokens?: number } } | null)
+    ?.usage;
+  if (usage === undefined || usage === null) return 0;
+  return (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+}
+
+export function meteringMiddleware(options: MeteringOptions): EffectMiddleware {
+  const now = options.clock ?? (() => Date.now());
+  const frozenMax = assertMaxCustom(options.budget?.maxCustom);
+  const budget: Budget | undefined =
+    options.budget === undefined
+      ? undefined
+      : { ...options.budget, ...(frozenMax !== undefined && { maxCustom: frozenMax }) };
+  return async (ctx: EffectContext, input: unknown, next): Promise<unknown> => {
+    // 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: unknown;
+    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;
+  };
+}

package/src/nestedBudget.ts

@@ -0,0 +1,200 @@
+import type { EffectContext, EffectMiddleware } from "@loomwork/effect-runtime";
+import {
+  type Budget,
+  type Pricing,
+  QuotaExceededError,
+  type ResourceDelta,
+  assertMaxCustom,
+  isCustomDimensionName,
+  overCustomBudget,
+} from "./metering";
+
+// ── K12.3 — nested budgets (tenant → workflow → execution) ────────────────────
+//
+// The K3 per-execution budget is a pure fold of ONE execution's log
+// (`ctx.resources`). A tenant- or workflow-level budget aggregates spend across
+// MANY executions' logs — so it is admission control over a PROJECTION
+// (eventually consistent), NOT a replay-pure per-execution fold. This is a
+// deliberate category change (the amendment states it explicitly): the verdict
+// is still durable and logged (QUOTA_EXCEEDED, P9), but the tenant/workflow
+// totals live in a ledger the app maintains from the RESOURCE_METERED stream,
+// not in any single fold. The most-restrictive bound wins, and each trip is
+// attributed to its level.
+
+export interface ScopeSpend {
+  tokens: number;
+  costUsd: number;
+  // ADR 0032 (R1) — additional dimensions, accumulated additively across a scope.
+  memBytes?: number;
+  wallMs?: number;
+  netBytes?: number;
+  /** ADR 0115 — open dimensions, accumulated by name (own-property keys only). */
+  custom?: Record<string, number>;
+}
+
+/** 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.
+ */
+export class BudgetLedger {
+  private readonly spend = new Map<string, ScopeSpend>();
+
+  add(scopeKey: string, delta: ResourceDelta): void {
+    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" || !isCustomDimensionName(name))
+          continue;
+        if (!Object.hasOwn(custom, name) && Object.keys(custom).length >= LEDGER_CUSTOM_MAX) {
+          continue;
+        }
+        custom[name] = (Object.hasOwn(custom, name) ? (custom[name] as number) : 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: string): ScopeSpend {
+    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: readonly string[], payload: unknown): void {
+    const p = payload as {
+      tokens?: number;
+      costUsd?: number;
+      memBytes?: number;
+      wallMs?: number;
+      netBytes?: number;
+      custom?: Record<string, number>;
+    };
+    const delta: ResourceDelta = {
+      ...(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);
+  }
+}
+
+/** 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;
+}
+
+function over(spent: ScopeSpend, b: Budget): boolean {
+  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) ||
+    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.
+ */
+export function nestedBudgetMiddleware(options: NestedBudgetOptions): EffectMiddleware {
+  const now = options.clock ?? (() => Date.now());
+  return async (ctx: EffectContext, input: unknown, next): Promise<unknown> => {
+    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) assertMaxCustom(scope.budget.maxCustom);
+
+    // Admission control — most-restrictive wins, attributed to its level.
+    for (const scope of scopes) {
+      const spent: ScopeSpend =
+        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 as Record<string, number>,
+              }),
+            }
+          : 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 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;
+  };
+}

package/src/profile.ts

@@ -0,0 +1,86 @@
+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 function effectTimingMiddleware(): EffectProfiler {
+  let calls = 0;
+  let totalEffectMs = 0;
+  let maxEffectMs = 0;
+  let inFlight = 0;
+  let peakConcurrentEffects = 0;
+  const byTool = new Map<string, { calls: number; totalMs: number }>();
+
+  const middleware: EffectMiddleware = 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();
+    },
+  };
+}