@gkoos/caracal 0.1.0 → 0.2.0

package/src/core/circuit-breaker.ts

@@ -108,10 +108,35 @@ const DEFAULT_HALF_OPEN_SUCCESSES = 1
 const DEFAULT_HALF_OPEN_PROBES = 1
 const DEFAULT_WINDOW_SIZE = 100
 
+// The distributed coordinator compares the failure threshold as an integer
+// numerator of thousandths (`wFail * 1000 >= numerator * wTotal`).  A threshold
+// that rounds to 0 makes that comparison unconditionally true, so the breaker
+// opens on a success-only window and re-opens after every recovery; a threshold
+// that rounds to the full scale requires every observation to fail, so the
+// breaker effectively never opens.  Both are rejected instead of silently
+// reinterpreted, and the local breaker enforces the same bounds so one policy
+// config works with either coordination.
+const FAILURE_THRESHOLD_SCALE = 1000
+
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
 
+/**
+ * Rejects a failureThreshold the thousandths comparison cannot represent.
+ *
+ * Accepts `0.0005 <= failureThreshold < 0.9995`.  Anything else resolves to a
+ * numerator of 0 or of the full scale, which changes what the threshold means
+ * rather than how precisely it is expressed.
+ */
+function assertResolvableThreshold(failureThreshold: number): void {
+  const numerator = Math.round(failureThreshold * FAILURE_THRESHOLD_SCALE)
+  if (numerator < 1 || numerator >= FAILURE_THRESHOLD_SCALE)
+    throw new RangeError(
+      `failureThreshold must be at least 0.0005 and below 0.9995 (thresholds are resolved to thousandths); got ${failureThreshold}`,
+    )
+}
+
 function validate(opts: LocalBreakerOptions): void {
   if (!opts.name.trim())
     throw new RangeError("Circuit breaker name must not be empty")
@@ -127,6 +152,7 @@ function validate(opts: LocalBreakerOptions): void {
     failureThreshold >= 1
   )
     throw new RangeError("failureThreshold must be a number in (0, 1)")
+  assertResolvableThreshold(failureThreshold)
 
   const { openMs = DEFAULT_OPEN_MS } = opts
   if (!Number.isInteger(openMs) || openMs < 1)
@@ -519,7 +545,12 @@ export interface BreakerCoordinator {
     identity: BreakerIdentity,
     params: {
       readonly probeToken: string
-      readonly outcome: "success" | "failure"
+      /**
+       * `"success"` and `"failure"` record an outcome; `"ignored"` releases the
+       * probe's slot without recording anything, which is what the policy sends
+       * when its classifier ignores the result.
+       */
+      readonly outcome: "success" | "failure" | "ignored"
       readonly generation: number
       readonly halfOpenSuccesses: number
       readonly openMs: number
@@ -648,6 +679,7 @@ function validateDistributed(opts: DistributedBreakerOptions): void {
     failureThreshold >= 1
   )
     throw new RangeError("failureThreshold must be a number in (0, 1)")
+  assertResolvableThreshold(failureThreshold)
 
   const { openMs = DEFAULT_DIST_OPEN_MS } = opts
   if (!Number.isInteger(openMs) || openMs < 1)
@@ -701,7 +733,9 @@ function distributed(
     options.minimumThroughput ?? DEFAULT_DIST_MINIMUM_THROUGHPUT
   const failureThreshold =
     options.failureThreshold ?? DEFAULT_DIST_FAILURE_THRESHOLD
-  const failureThresholdNumerator = Math.round(failureThreshold * 1000)
+  const failureThresholdNumerator = Math.round(
+    failureThreshold * FAILURE_THRESHOLD_SCALE,
+  )
   const windowSize = options.windowSize ?? DEFAULT_DIST_WINDOW_SIZE
   const openMs = options.openMs ?? DEFAULT_DIST_OPEN_MS
   const windowTtlMs = options.windowTtlMs ?? Math.max(openMs * 3, 60_000)
@@ -930,11 +964,18 @@ function distributed(
             ? { status: "success", value }
             : { status: "failure", error: thrownError },
         )
-        if (breakerOutcome !== "ignored") {
+        // An ignored result is never recorded.  A probe still has to settle
+        // though: releasing the slot it holds is what lets the next probe
+        // through, instead of stalling the recovery window until the probe lease
+        // elapses.  The local breaker frees its slot immediately, and a release
+        // records nothing and does not advance recovery.
+        if (breakerOutcome !== "ignored" || admission.kind === "probe") {
           const outcomeStr =
             breakerOutcome === "success"
               ? ("success" as const)
               : ("failure" as const)
+          const settleOutcome =
+            breakerOutcome === "ignored" ? ("ignored" as const) : outcomeStr
 
           if (admission.kind === "closed") {
             try {
@@ -998,49 +1039,53 @@ function distributed(
             try {
               const result = await coordinator.settleProbe(identity, {
                 probeToken: admission.probeToken,
-                outcome: outcomeStr,
+                outcome: settleOutcome,
                 generation: admission.generation,
                 halfOpenSuccesses,
                 openMs,
                 windowTtlMs,
               })
-              if (result.type === "stale") {
-                emitRuntimeEvent(context, {
-                  type: "breaker.observation-stale",
-                  coordination: "distributed",
-                  policyName: name,
-                  scope,
-                  attemptGeneration: admission.generation,
-                  currentGeneration: result.generation,
-                })
-              } else {
-                emitRuntimeEvent(context, {
-                  type: "breaker.observation",
-                  coordination: "distributed",
-                  policyName: name,
-                  scope,
-                  outcome: outcomeStr,
-                  generation: admission.generation,
-                })
-                if (result.type === "transitioned") {
-                  if (result.newState === "closed") {
-                    lastKnownState.forget(identity.operation, scope)
-                  } else {
-                    lastKnownState.remember(
-                      identity.operation,
-                      scope,
-                      result.newState,
-                    )
-                  }
+              // A release reports nothing: it is not an observation, so there is
+              // no breaker.observation event and no transition to announce.
+              if (breakerOutcome !== "ignored") {
+                if (result.type === "stale") {
                   emitRuntimeEvent(context, {
-                    type: "breaker.state-changed",
+                    type: "breaker.observation-stale",
                     coordination: "distributed",
                     policyName: name,
                     scope,
-                    state: result.newState,
-                    previousState: "half-open",
-                    generation: result.newGeneration,
+                    attemptGeneration: admission.generation,
+                    currentGeneration: result.generation,
+                  })
+                } else {
+                  emitRuntimeEvent(context, {
+                    type: "breaker.observation",
+                    coordination: "distributed",
+                    policyName: name,
+                    scope,
+                    outcome: outcomeStr,
+                    generation: admission.generation,
                   })
+                  if (result.type === "transitioned") {
+                    if (result.newState === "closed") {
+                      lastKnownState.forget(identity.operation, scope)
+                    } else {
+                      lastKnownState.remember(
+                        identity.operation,
+                        scope,
+                        result.newState,
+                      )
+                    }
+                    emitRuntimeEvent(context, {
+                      type: "breaker.state-changed",
+                      coordination: "distributed",
+                      policyName: name,
+                      scope,
+                      state: result.newState,
+                      previousState: "half-open",
+                      generation: result.newGeneration,
+                    })
+                  }
                 }
               }
             } catch (settleError) {

package/src/core/operation.ts

@@ -4,6 +4,7 @@ import {
   admissionSignal,
   createClassifier,
   createExecutionContext,
+  emitToSink,
 } from "./runtime.js"
 import type {
   Adapter,
@@ -51,11 +52,7 @@ function normalizeSinks(events: EventSinks | undefined): readonly EventSink[] {
 
 function emit(sinks: readonly EventSink[], event: OperationEvent): void {
   for (const sink of sinks) {
-    try {
-      sink.emit(event)
-    } catch {
-      // Observability must not modify resilience execution.
-    }
+    emitToSink(sink, event)
   }
 }
 

package/src/core/retry.ts

@@ -1,4 +1,9 @@
-import { admissionSignal, emitRuntimeEvent, nextAttempt } from "./runtime.js"
+import {
+  MAX_TIMER_MS,
+  admissionSignal,
+  emitRuntimeEvent,
+  nextAttempt,
+} from "./runtime.js"
 import type {
   Classification,
   ExecutionContext,
@@ -71,6 +76,11 @@ function delayFor(
   if (!Number.isFinite(delay) || delay < 0) {
     throw new RangeError("retry delay must be a finite non-negative number")
   }
+  if (delay > MAX_TIMER_MS) {
+    throw new RangeError(
+      `retry delay must not exceed ${MAX_TIMER_MS} ms, the largest delay setTimeout honours`,
+    )
+  }
 
   return delay
 }
@@ -124,6 +134,16 @@ export function retry(options: RetryOptions): Policy {
   if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1) {
     throw new RangeError("maxAttempts must be a positive integer")
   }
+  if (
+    typeof options.delay === "number" &&
+    (!Number.isFinite(options.delay) ||
+      options.delay < 0 ||
+      options.delay > MAX_TIMER_MS)
+  ) {
+    throw new RangeError(
+      `retry delay must be a finite number within 0..${MAX_TIMER_MS} ms`,
+    )
+  }
 
   return Object.freeze({
     name: "retry",
@@ -144,6 +164,17 @@ export function retry(options: RetryOptions): Policy {
             outcomeClassification !== "retryable" ||
             context.capabilities.replay !== "safe"
           ) {
+            // Declining to retry is observable: without this, a call that was
+            // never retried looks identical to one with no retry policy.
+            emitRuntimeEvent(context, {
+              type: "retry.declined",
+              outcome: summarized(outcome),
+              classification: outcomeClassification,
+              reason:
+                context.capabilities.replay !== "safe"
+                  ? "replay-unsafe"
+                  : "not-retryable",
+            })
             return value
           }
 
@@ -170,11 +201,24 @@ export function retry(options: RetryOptions): Policy {
           const outcome: Outcome<Result> = { status: "failure", error }
           const outcomeClassification = classification(context, outcome)
 
+          if (admissionSignal(context)?.aborted) {
+            throw error
+          }
           if (
-            admissionSignal(context)?.aborted ||
             context.capabilities.replay !== "safe" ||
             outcomeClassification !== "retryable"
           ) {
+            // Same event as the value path: the caller can tell a declined
+            // retry from a missing retry policy.
+            emitRuntimeEvent(context, {
+              type: "retry.declined",
+              outcome: summarized(outcome),
+              classification: outcomeClassification,
+              reason:
+                context.capabilities.replay !== "safe"
+                  ? "replay-unsafe"
+                  : "not-retryable",
+            })
             throw error
           }
 

package/src/core/runtime.ts

@@ -94,6 +94,31 @@ export function withSignal(
   )
 }
 
+/**
+ * Largest delay `setTimeout` honours.  Anything above it is silently clamped to
+ * 1 ms by the platform, so accepting larger values would turn a long wait into
+ * an immediate one.
+ */
+export const MAX_TIMER_MS = 2_147_483_647
+
+/**
+ * Delivers one event to one sink, isolating execution from it.  Sinks are
+ * fire-and-forget: a synchronous throw and a rejected promise are both dropped,
+ * so a failing sink can neither modify resilience execution nor surface as an
+ * unhandled rejection.
+ */
+export function emitToSink(sink: EventSink, event: OperationEvent): void {
+  try {
+    const pending = sink.emit(event) as unknown
+    const thenable = pending as { catch?: unknown } | null | undefined
+    if (typeof thenable?.catch === "function") {
+      void (pending as Promise<unknown>).catch(() => {})
+    }
+  } catch {
+    // See above: a failing sink must never modify execution.
+  }
+}
+
 export function emitRuntimeEvent(
   context: ExecutionContext,
   event: EventWithoutRuntimeFields,
@@ -102,11 +127,7 @@ export function emitRuntimeEvent(
   const fullEvent = { ...event, at: Date.now(), context } as OperationEvent
 
   for (const sink of sinks) {
-    try {
-      sink.emit(fullEvent)
-    } catch {
-      // Observability must not modify resilience execution.
-    }
+    emitToSink(sink, fullEvent)
   }
 }
 

package/src/core/timeout.ts

@@ -1,4 +1,9 @@
-import { emitRuntimeEvent, withAdmissionSignal, withSignal } from "./runtime.js"
+import {
+  MAX_TIMER_MS,
+  emitRuntimeEvent,
+  withAdmissionSignal,
+  withSignal,
+} from "./runtime.js"
 import type { ExecutionContext, Next, Policy } from "./types.js"
 
 export class TimeoutError extends Error {
@@ -31,6 +36,11 @@ export function timeout(options: TimeoutOptions): Policy {
   if (!Number.isFinite(options.ms) || options.ms <= 0) {
     throw new RangeError("timeout ms must be a finite positive number")
   }
+  if (options.ms > MAX_TIMER_MS) {
+    throw new RangeError(
+      `timeout ms must not exceed ${MAX_TIMER_MS} ms, the largest delay setTimeout honours`,
+    )
+  }
 
   return Object.freeze({
     name: "timeout",

package/src/core/types.ts

@@ -190,6 +190,14 @@ export type OperationEvent =
       outcome: Outcome<undefined>
       classification: Classification
     }>
+  | Readonly<{
+      type: "retry.declined"
+      at: number
+      context: ExecutionContext
+      outcome: Outcome<undefined>
+      classification: Classification
+      reason: "replay-unsafe" | "not-retryable"
+    }>
 
 /** Output-only observability contract. Sinks cannot alter policy execution. */
 export interface EventSink {

package/test/harness/adapter-contract.ts

@@ -0,0 +1,170 @@
+import { operation } from "../../src/core/operation.js"
+import type {
+  Adapter,
+  Classification,
+  OperationCapabilities,
+  OperationEvent,
+  Outcome,
+} from "../../src/core/types.js"
+
+export interface AdapterContractSuccess<Args, Result> {
+  readonly args: Args
+  readonly assertResult?: (result: Result) => void | Promise<void>
+}
+
+export interface AdapterContractCapabilityCase<Args> {
+  readonly args: Args
+  readonly expected: OperationCapabilities
+}
+
+export interface AdapterContractClassificationCase<Result> {
+  readonly outcome: Outcome<Result>
+  readonly expected: Classification
+}
+
+export interface AdapterContractAbortCase<Args> {
+  readonly args: Args
+  readonly verify: (controls: {
+    readonly controller: AbortController
+    readonly execute: () => Promise<unknown>
+  }) => void | Promise<void>
+}
+
+export interface AdapterContractOptions<Args, Result> {
+  readonly name: string
+  readonly adapter: Adapter<Args, Result>
+  readonly success: AdapterContractSuccess<Args, Result>
+  readonly capabilities: readonly AdapterContractCapabilityCase<Args>[]
+  readonly classifications?: readonly AdapterContractClassificationCase<Result>[]
+  readonly abort?: AdapterContractAbortCase<Args>
+}
+
+export interface AdapterContractCheck {
+  readonly name: string
+  run(): Promise<void>
+}
+
+export interface AdapterContractSuite {
+  readonly name: string
+  readonly checks: readonly AdapterContractCheck[]
+}
+
+function assertEqual<T>(actual: T, expected: T, message: string): void {
+  if (!Object.is(actual, expected)) {
+    throw new Error(
+      `${message}: expected ${String(expected)}, received ${String(actual)}`,
+    )
+  }
+}
+
+function assertLifecycle(events: readonly OperationEvent[]): void {
+  const types = events.map((event) => event.type)
+  const expected = [
+    "execution.started",
+    "attempt.started",
+    "attempt.settled",
+    "execution.settled",
+  ]
+  if (
+    types.length !== expected.length ||
+    types.some((type, index) => type !== expected[index])
+  ) {
+    throw new Error(
+      `expected operation lifecycle ${expected.join(" -> ")}; received ${types.join(" -> ")}`,
+    )
+  }
+}
+
+/**
+ * Returns runner-agnostic checks for a third-party adapter. Register each
+ * check with the application's test runner; this module imports no test runner.
+ */
+export function defineAdapterContractSuite<Args, Result>(
+  options: AdapterContractOptions<Args, Result>,
+): AdapterContractSuite {
+  const checks: AdapterContractCheck[] = options.capabilities.map(
+    (capabilityCase, index) => ({
+      name: `${options.name}: capabilities ${index + 1}`,
+      async run(): Promise<void> {
+        const actual = options.adapter.capabilities(capabilityCase.args)
+        assertEqual(
+          actual.abort,
+          capabilityCase.expected.abort,
+          "abort capability",
+        )
+        assertEqual(
+          actual.replay,
+          capabilityCase.expected.replay,
+          "replay capability",
+        )
+      },
+    }),
+  )
+
+  checks.push({
+    name: `${options.name}: successful operation lifecycle`,
+    async run(): Promise<void> {
+      const events: OperationEvent[] = []
+      const subject = operation({
+        name: `adapter-contract:${options.name}`,
+        adapter: options.adapter,
+        events: { emit: (event) => events.push(event) },
+      })
+      const result = await subject.execute(options.success.args, {
+        executionId: "adapter-contract",
+      })
+      await options.success.assertResult?.(result)
+      assertLifecycle(events)
+    },
+  })
+
+  for (const [index, classificationCase] of (
+    options.classifications ?? []
+  ).entries()) {
+    checks.push({
+      name: `${options.name}: classification ${index + 1}`,
+      async run(): Promise<void> {
+        const actual =
+          options.adapter.classify?.(classificationCase.outcome) ??
+          (classificationCase.outcome.status === "success"
+            ? "success"
+            : "failure")
+        assertEqual(
+          actual,
+          classificationCase.expected,
+          "outcome classification",
+        )
+      },
+    })
+  }
+
+  if (options.abort !== undefined) {
+    checks.push({
+      name: `${options.name}: abort behavior`,
+      async run(): Promise<void> {
+        const controller = new AbortController()
+        const subject = operation({
+          name: `adapter-contract:${options.name}`,
+          adapter: options.adapter,
+        })
+        await options.abort?.verify({
+          controller,
+          execute: () =>
+            subject.execute(options.abort?.args as Args, {
+              signal: controller.signal,
+            }),
+        })
+      },
+    })
+  }
+
+  return Object.freeze({ name: options.name, checks: Object.freeze(checks) })
+}
+
+export async function runAdapterContractSuite(
+  suite: AdapterContractSuite,
+): Promise<void> {
+  for (const check of suite.checks) {
+    await check.run()
+  }
+}

package/test/harness/index.ts

@@ -0,0 +1,15 @@
+/** Runner-agnostic adapter contract checks; source remains outside src/. */
+
+export type {
+  AdapterContractAbortCase,
+  AdapterContractCapabilityCase,
+  AdapterContractCheck,
+  AdapterContractClassificationCase,
+  AdapterContractOptions,
+  AdapterContractSuccess,
+  AdapterContractSuite,
+} from "./adapter-contract.js"
+export {
+  defineAdapterContractSuite,
+  runAdapterContractSuite,
+} from "./adapter-contract.js"

package/dist/chunk-5CXDW7W6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/runtime.ts","../src/core/operation.ts"],"names":[],"mappings":"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","file":"chunk-5CXDW7W6.js","sourcesContent":["import type {\n  Classification,\n  EventSink,\n  ExecutionContext,\n  OperationEvent,\n  Outcome,\n  OutcomeClassifier,\n} from \"./types.js\"\n\nconst eventSinks = Symbol(\"caracal.eventSinks\")\nconst admissionSignals = new WeakMap<ExecutionContext, AbortSignal>()\nexport function admissionSignal(\n  context: ExecutionContext,\n): AbortSignal | undefined {\n  const admission = admissionSignals.get(context)\n  return admission && context.signal\n    ? AbortSignal.any([admission, context.signal])\n    : (admission ?? context.signal)\n}\nexport function withAdmissionSignal(\n  context: ExecutionContext,\n  signal: AbortSignal,\n): ExecutionContext {\n  const derived = attachRuntime(\n    { ...context },\n    runtimeContext(context)[eventSinks] ?? [],\n  )\n  const previous = admissionSignal(context)\n  admissionSignals.set(\n    derived,\n    previous ? AbortSignal.any([previous, signal]) : signal,\n  )\n  return derived\n}\nfunction inheritAdmission(\n  source: ExecutionContext,\n  target: ExecutionContext,\n): ExecutionContext {\n  const signal = admissionSignals.get(source)\n  if (signal) admissionSignals.set(target, signal)\n  return target\n}\n\ntype EventWithoutRuntimeFields = OperationEvent extends infer Event\n  ? Event extends OperationEvent\n    ? Omit<Event, \"at\" | \"context\">\n    : never\n  : never\n\ntype RuntimeExecutionContext = ExecutionContext & {\n  readonly [eventSinks]: readonly EventSink[]\n}\n\nfunction runtimeContext(context: ExecutionContext): RuntimeExecutionContext {\n  return context as RuntimeExecutionContext\n}\n\nfunction attachRuntime(\n  values: ExecutionContext,\n  sinks: readonly EventSink[],\n): ExecutionContext {\n  const context = values as RuntimeExecutionContext\n  Object.defineProperty(context, eventSinks, { value: sinks })\n  return Object.freeze(context)\n}\n\nexport function createExecutionContext(\n  values: Omit<ExecutionContext, \"attempt\">,\n  sinks: readonly EventSink[],\n): ExecutionContext {\n  return attachRuntime({ attempt: 1, ...values }, sinks)\n}\n\nexport function nextAttempt(context: ExecutionContext): ExecutionContext {\n  return inheritAdmission(\n    context,\n    attachRuntime(\n      { ...context, attempt: context.attempt + 1 },\n      runtimeContext(context)[eventSinks] ?? [],\n    ),\n  )\n}\n\nexport function withSignal(\n  context: ExecutionContext,\n  signal: AbortSignal | undefined,\n): ExecutionContext {\n  return inheritAdmission(\n    context,\n    attachRuntime(\n      { ...context, signal },\n      runtimeContext(context)[eventSinks] ?? [],\n    ),\n  )\n}\n\nexport function emitRuntimeEvent(\n  context: ExecutionContext,\n  event: EventWithoutRuntimeFields,\n): void {\n  const sinks = runtimeContext(context)[eventSinks] ?? []\n  const fullEvent = { ...event, at: Date.now(), context } as OperationEvent\n\n  for (const sink of sinks) {\n    try {\n      sink.emit(fullEvent)\n    } catch {\n      // Observability must not modify resilience execution.\n    }\n  }\n}\n\nexport function createClassifier<Result>(\n  classify: ((outcome: Outcome<Result>) => Classification) | undefined,\n): OutcomeClassifier {\n  return (outcome) => {\n    if (classify === undefined) {\n      return outcome.status === \"success\" ? \"success\" : \"failure\"\n    }\n\n    return classify(outcome as Outcome<Result>)\n  }\n}\n","import { randomUUID } from \"node:crypto\"\n\nimport {\n  admissionSignal,\n  createClassifier,\n  createExecutionContext,\n} from \"./runtime.js\"\nimport type {\n  Adapter,\n  EventSink,\n  EventSinks,\n  ExecutionMetadata,\n  Next,\n  Operation,\n  OperationCapabilities,\n  OperationEvent,\n  OperationExecuteOptions,\n  OperationOptions,\n  Outcome,\n  Policy,\n} from \"./types.js\"\n\nconst summarizeSuccess = (): Outcome<undefined> => ({\n  status: \"success\",\n  value: undefined,\n})\nconst summarizeFailure = (error: unknown): Outcome<undefined> => ({\n  status: \"failure\",\n  error,\n})\n\nfunction immutableCapabilities(\n  capabilities: OperationCapabilities,\n): OperationCapabilities {\n  return Object.freeze({ ...capabilities })\n}\n\nfunction immutableMetadata(\n  metadata: Readonly<Record<string, unknown>> | undefined,\n): ExecutionMetadata {\n  return Object.freeze({ ...(metadata ?? {}) })\n}\n\nfunction normalizeSinks(events: EventSinks | undefined): readonly EventSink[] {\n  if (events === undefined) {\n    return []\n  }\n\n  return \"emit\" in events ? [events] : events\n}\n\nfunction emit(sinks: readonly EventSink[], event: OperationEvent): void {\n  for (const sink of sinks) {\n    try {\n      sink.emit(event)\n    } catch {\n      // Observability must not modify resilience execution.\n    }\n  }\n}\n\nfunction validateName(name: string, kind: \"operation\" | \"policy\"): void {\n  if (name.trim().length === 0) {\n    throw new Error(`${kind} name must not be empty`)\n  }\n}\n\nfunction createPipeline<Result>(\n  policies: readonly Policy[],\n  adapter: Next<Result>,\n): Next<Result> {\n  return policies.reduceRight<Next<Result>>(\n    (next, policy) => async (context) => policy.execute(context, next),\n    adapter,\n  )\n}\n\nfunction invokeAdapter<Args, Result>(\n  adapter: Adapter<Args, Result>,\n  args: Args,\n  sinks: readonly EventSink[],\n): Next<Result> {\n  return async (context) => {\n    admissionSignal(context)?.throwIfAborted()\n    emit(sinks, { type: \"attempt.started\", at: Date.now(), context })\n\n    try {\n      const value = await adapter.execute(args, context)\n      const outcome: Outcome<Result> = { status: \"success\", value }\n      const classification = context.classify(outcome)\n      emit(sinks, {\n        type: \"attempt.settled\",\n        at: Date.now(),\n        context,\n        outcome: summarizeSuccess(),\n        classification,\n      })\n      return value\n    } catch (error) {\n      const outcome: Outcome<Result> = { status: \"failure\", error }\n      const classification = context.classify(outcome)\n      emit(sinks, {\n        type: \"attempt.settled\",\n        at: Date.now(),\n        context,\n        outcome: summarizeFailure(error),\n        classification,\n      })\n      throw error\n    }\n  }\n}\n\n/** Creates a named, protocol-agnostic operation. */\nexport function operation<Args, Result>(\n  options: OperationOptions<Args, Result>,\n): Operation<Args, Result> {\n  validateName(options.name, \"operation\")\n  for (const policy of options.policies ?? []) {\n    validateName(policy.name, \"policy\")\n  }\n\n  const policies = Object.freeze([...(options.policies ?? [])])\n  const sinks = Object.freeze(normalizeSinks(options.events))\n\n  return Object.freeze({\n    name: options.name,\n    async execute(\n      args: Args,\n      executeOptions: OperationExecuteOptions = {},\n    ): Promise<Result> {\n      const capabilities = options.adapter.capabilities(args)\n      const context = createExecutionContext(\n        {\n          operationName: options.name,\n          executionId: executeOptions.executionId ?? randomUUID(),\n          signal: executeOptions.signal,\n          metadata: immutableMetadata(executeOptions.metadata),\n          capabilities: immutableCapabilities(capabilities),\n          classify: createClassifier(options.adapter.classify),\n        },\n        sinks,\n      )\n      const adapter = createPipeline(\n        policies.filter((policy) => policy.phase === \"attempt\"),\n        invokeAdapter(options.adapter, args, sinks),\n      )\n      const pipeline = createPipeline(\n        policies.filter((policy) => policy.phase !== \"attempt\"),\n        adapter,\n      )\n\n      emit(sinks, { type: \"execution.started\", at: Date.now(), context })\n      try {\n        const value = await pipeline(context)\n        emit(sinks, {\n          type: \"execution.settled\",\n          at: Date.now(),\n          context,\n          outcome: summarizeSuccess(),\n        })\n        return value\n      } catch (error) {\n        emit(sinks, {\n          type: \"execution.settled\",\n          at: Date.now(),\n          context,\n          outcome: summarizeFailure(error),\n        })\n        throw error\n      }\n    },\n  })\n}\n"]}