@gkoos/caracal 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-09
+
+Initial public release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caracal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+<p align="center">
+  <img src="docs/caracal.svg" alt="Caracal" width="140">
+</p>
+
+# Caracal
+
+**Scoped distributed resilience for asynchronous operations.**
+
+Caracal is a library for wrapping asynchronous operations (like HTTP requests or database queries) with resilience policies. It provides a composable model for applying timeouts, retries, circuit breakers, and bulkheads to any operation that can be expressed as an adapter. The library is designed to work in distributed environments, allowing multiple instances of an application to **share and coordinate** their resilience policies through a shared Redis backend.
+
+### The problem
+
+There are many libraries for applying resilience policies to operations, but most of them are designed for a single process. In a distributed system, each replica of an application may have its own local concurrency limits and circuit breakers, which can lead to uncoordinated failures and resource exhaustion.
+
+If 40 replicas each enforce a local concurrency limit of 20, the downstream can still receive 800 concurrent requests. If each replica maintains its own circuit breaker, you get 40 independent failure windows and 40 independent recovery probes. Caracal uses Redis to coordinate those constraints across whichever scope actually matches your failure domain: region, shard, tenant, credential, workload class, or any grouping that makes sense for your application.
+
+## Quick start
+
+```sh
+npm install @gkoos/caracal
+# Redis coordination (optional peer dependency for distributed policies):
+npm install ioredis
+# PostgreSQL adapter (optional peer dependency for database operations):
+npm install pg
+```
+
+```ts
+import { bulkhead, circuitBreaker, operation, retry, timeout } from "@gkoos/caracal"
+import { createCoordinationClient, redisCoordinator, redisCircuitBreakerCoordinator } from "@gkoos/caracal/redis"
+import { fetchAdapter } from "@gkoos/caracal/fetch"
+import { Pool } from "pg"
+import { postgresAdapter } from "@gkoos/caracal/postgres"
+
+// Redis coordination - connect once, share across all policies
+const redis = createCoordinationClient(process.env.REDIS_URL!)
+await redis.connect()
+
+// Circuit breaker shared across all replicas, tracked per region.
+// Use circuitBreaker.local({ name, minimumThroughput, failureThreshold, openMs }) if you only need in-process tracking.
+const breaker = circuitBreaker.distributed({
+  name: "partner-api",
+  coordinator: redisCircuitBreakerCoordinator(redis, { namespace: "svc:prod" }),
+  scope: (ctx) => `region:${String(ctx.metadata.region)}`,
+  minimumThroughput: 20,
+  failureThreshold: 0.5,
+  openMs: 30_000,
+  halfOpenProbes: 3,
+  onCoordinatorError: "fail-open",
+})
+
+// Concurrency limit enforced across all replicas, per region.
+// Use bulkhead.local({ name, limit, queue }) if you only need a per-process limit.
+const capacity = bulkhead.distributed({
+  name: "partner-api",
+  coordinator: redisCoordinator(redis, { namespace: "svc:prod" }),
+  scope: (ctx) => `region:${String(ctx.metadata.region)}`,
+  limit: 20,
+  leaseMs: 30_000,
+})
+
+// Fetch operation: breaker outermost, bulkhead innermost around the adapter.
+// timeout bounds the whole retry sequence; retry drives individual attempts.
+const fetchOp = operation({
+  name: "partner-api",
+  adapter: fetchAdapter(),
+  policies: [
+    breaker,
+    timeout({ ms: 10_000 }),
+    retry({ maxAttempts: 3, delay: (n) => 100 * 2 ** (n - 1) }),
+    capacity,
+  ],
+  events: { emit: (e) => console.log(e.type, e) },
+})
+
+const response = await fetchOp.execute(
+  { url: "https://api.partner.com/orders/42" },
+  { metadata: { region: "eu-west-2" } },
+)
+
+// PostgreSQL operation reusing the same policy instances.
+// A distributed policy is identified by (namespace, policy name, operation
+// name, scope), so `orders-db` gets its own breaker window and capacity
+// budget. Reuse the same operation name to share them deliberately.
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+const dbOp = operation({
+  name: "orders-db",
+  adapter: postgresAdapter(pool),
+  policies: [breaker, retry({ maxAttempts: 2 }), timeout({ ms: 2_000 }), capacity],
+})
+
+const row = await dbOp.execute(
+  { sql: "select * from orders where id = $1", values: ["42"], replay: "safe" },
+  { metadata: { region: "eu-west-2" } },
+)
+
+// At shutdown
+await pool.end()
+redis.disconnect()
+```
+
+Distributed policies coordinate by `(namespace, policy name, operation name, scope)`. Two operations with different names get independent budgets and breaker windows even when they reuse the same policy instances. To share a budget or breaker deliberately, give the operations the same name - see [bulkheads](docs/bulkhead.md) and the [Redis key scheme](docs/redis.md).
+
+## How it works
+
+### Operations and adapters
+
+An `operation` wraps an `adapter`: an object that declares its cancellation and replay capabilities before executing underlying work:
+
+```ts
+import { operation, type Adapter } from "@gkoos/caracal"
+
+const adapter: Adapter<{ id: string }, Order> = {
+  capabilities: () => ({ abort: "supported", replay: "safe" }),
+  execute: async ({ id }, context) => fetchOrder(id, { signal: context.signal }),
+}
+
+const orders = operation({ name: "orders", adapter })
+const order = await orders.execute({ id: "42" }, { metadata: { region: "eu-west-2" } })
+```
+
+`abort` tells Caracal whether it can signal cancellation to the underlying work. `replay` tells retry whether a repeated attempt is safe. Both are declared explicitly by the adapter, Caracal never infers them.
+
+### Policies
+
+Policies are applied in array order, outermost first. The recommended ordering for a fully-configured operation is:
+
+```ts
+// Schematic - order only; each entry is a constructed policy instance.
+policies: [breaker, timeout, retry, capacity]
+```
+
+Each policy is described below.
+
+#### Timeout
+
+Bounds how long the caller waits. Local only, there is no distributed timeout.
+
+```ts
+import { timeout } from "@gkoos/caracal"
+
+timeout({ ms: 5_000 })
+```
+
+If the adapter declares `abort: "supported"`, Caracal cancels the underlying work when the deadline expires. If not, the caller still receives `TimeoutError` on time, but the underlying work may continue until it naturally settles.
+
+#### Retry
+
+Retries adapter-classified failures. Local only, there is no distributed retry.
+
+```ts
+import { retry } from "@gkoos/caracal"
+
+retry({
+  maxAttempts: 3,
+  delay: (attempt) => 100 * 2 ** (attempt - 1) * (0.5 + Math.random() * 0.5),
+})
+```
+
+`maxAttempts` includes the initial attempt. An attempt is only retried if the adapter classifies the outcome as `retryable` and declares `replay: "safe"`. The delay function receives the attempt number (1 = first retry) and a context carrying the settled outcome, so a protocol-specific helper can pace retries from server feedback. The fetch adapter ships an opt-in `Retry-After` implementation: `retry({ maxAttempts: 3, delay: retryAfterDelay })`. See [fetch](docs/fetch.md#retry-after).
+
+#### Bulkhead
+
+Limits concurrent underlying adapter calls. Available as local (per-process) or distributed (shared across replicas via Redis).
+
+```ts
+import { bulkhead } from "@gkoos/caracal"
+import { createCoordinationClient, redisCoordinator } from "@gkoos/caracal/redis"
+
+// Local - each process enforces its own limit independently
+const localCapacity = bulkhead.local({
+  name: "partner-api",
+  limit: 10,
+  queue: { limit: 50, timeoutMs: 2_000 }, // optional; default is immediate rejection
+})
+
+// Distributed - limit is shared across all replicas in the same scope
+const sharedCapacity = bulkhead.distributed({
+  name: "partner-api",
+  coordinator: redisCoordinator(redis, { namespace: "svc:prod" }),
+  scope: (ctx) => `region:${String(ctx.metadata.region)}`,
+  limit: 20,
+  leaseMs: 30_000,
+})
+```
+
+Permits are held for the duration of the underlying adapter call only, not for the caller's wait or the retry loop. **A distributed bulkhead rejects immediately when full, there is no distributed queue**. On coordinator loss, admission always fails closed with `CoordinatorUnavailableError`.
+
+#### Circuit breaker
+
+Opens when the failure rate in a sliding window exceeds a threshold, blocking further attempts until a probe succeeds. Available as local (per-process) or distributed (shared across replicas via Redis).
+
+```ts
+import { circuitBreaker } from "@gkoos/caracal"
+import { redisCircuitBreakerCoordinator } from "@gkoos/caracal/redis"
+
+// Local - each process tracks its own failure window independently
+const localBreaker = circuitBreaker.local({
+  name: "partner-api",
+  minimumThroughput: 10,  // minimum observations before the breaker may open
+  failureThreshold: 0.5,  // open when ≥ 50% of the window are failures
+  openMs: 10_000,         // stay open for 10s before allowing a probe
+})
+
+// Distributed - failure window and probe budget are shared across all replicas in the same scope
+const sharedBreaker = circuitBreaker.distributed({
+  name: "partner-api",
+  coordinator: redisCircuitBreakerCoordinator(redis, { namespace: "svc:prod" }),
+  scope: (ctx) => `region:${String(ctx.metadata.region)}`,
+  minimumThroughput: 20,
+  failureThreshold: 0.5,
+  openMs: 30_000,
+  halfOpenProbes: 3,       // globally bounded concurrent recovery probes per scope
+  onCoordinatorError: "fail-open",  // or "fail-closed"
+})
+```
+
+Place the local circuit breaker outside retry. The breaker then observes one outcome per logical execution - a transient failure that a retry recovers from never counts against the breaker. **A distributed breaker never silently falls back to local state on coordinator loss.**
+
+The `scope` function maps each execution context to a coordination key. Everything sharing that key shares the same failure window and state:
+
+```ts
+scope: (ctx) => `region:${String(ctx.metadata.region)}`   // one breaker per region
+scope: (ctx) => `tenant:${String(ctx.metadata.tenantId)}` // one breaker per tenant
+scope: () => "global"                                     // one breaker for all replicas
+```
+
+Use stable, non-secret values, scope keys are observable in the Redis keyspace.
+
+### Events and observability
+
+Every operation accepts an `events` sink - or an array of sinks - that receives structured events from every policy decision. Sinks are output-only and isolated: an exception in a sink cannot affect execution.
+
+```ts
+const op = operation({
+  name: "partner-api",
+  adapter: fetchAdapter(),
+  policies: [sharedBreaker, timeout({ ms: 5_000 }), retry({ maxAttempts: 3 }), sharedCapacity],
+  events: { emit: (event) => metrics.record(event) },
+})
+```
+
+The full set can be found in the [Events and observability](docs/events-and-observability.md) section.
+
+## Why not just use X, bro?
+
+There are many libraries for applying resilience policies to operations, but most of them are designed for a single process. Caracal'
+
+| Library / category | What it covers | Distributed aspect | Caracal difference |
+|---|---|---|---|
+| Polly-TS | Retry, breaker, timeout, bulkhead, rate limiting, cache, hedge, fallback; HTTP/framework integrations | Redis-backed distributed circuit breaker | Polly-TS adds Redis to one policy in an otherwise local-first, HTTP-centric library. In Caracal the policies coordinate across a user-defined scope - per region, per tenant, or any grouping - and the same model works for HTTP, PostgreSQL, or any async operation. |
+| Breakwater | TS resilience pipeline: breaker, retry, timeout, fallback, bulkhead, rate limiter, cache, telemetry | Redis distributed circuit breaker; shared rate quota | Same pattern: Redis is an add-on to a local pipeline. Caracal makes scoped coordination the foundation, not an afterthought. |
+| resilience4ts | Broad functional TS fault-tolerance patterns; distributed-first positioning | Distributed locks/cache and planned distributed context; project is small/early | Caracal's scope is narrower and more precise: explicit abort/replay traits, per-scope breaker and bulkhead with documented failure guarantees, and property/fuzz/multi-process integration testing. |
+| Cockatiel / Resilience4j / Polly (.NET) | Mature, well-tested composable resilience patterns | Per-process state only | These are excellent libraries for single-process resilience. Caracal exists for the case where the constraint - capacity, health - belongs to a shared downstream, not to one replica. |
+| Envoy / Envoy Gateway | Network-level circuit breaking, retries, concurrency limits; global rate limiting as a separate service | Circuit-breaker counters are not synchronised across Envoy processes | Envoy operates at the network layer without application semantics. Caracal works at the call site: it understands abort capability, replay safety, and lets you scope coordination to any application-defined group without a sidecar. |
+| Redis semaphore/rate-limit libraries | Individual distributed primitives (semaphores, token buckets) | Shared Redis state | Assembling raw primitives means wiring up admission, leasing, renewal, failure handling, and observability yourself, for each policy. Caracal provides a tested, composed model with consistent semantics across policies. |
+
+## Development
+
+Requires Node.js 20+.
+
+```sh
+npm install
+npm run check     # format, lint, typecheck, build, unit tests
+```
+
+### Tests
+
+```sh
+npm test                    # unit suite (test/unit) - fast, no external dependencies
+npm run test:property       # property suite - fast-check, CARACAL_TEST_SEED for replay
+npm run test:fuzz           # fuzz suite - seeded event-history generator
+npm run test:integration    # integration suite - requires services and CARACAL_* URLs
+npm run test:integration:cluster  # cluster suite - local three-master Valkey cluster (not run in CI)
+npm run test:all            # check, then the property, fuzz, and integration suites
+```
+
+Integration tests use real Valkey and PostgreSQL via Docker Compose. Each suite skips itself unless its URL is set, so starting the containers alone is not enough:
+
+```sh
+npm run redis:up
+CARACAL_REDIS_URL=redis://127.0.0.1:6379 npm run test:integration
+npm run redis:down
+```
+
+See [Testing](docs/testing.md) and [Local development](docs/development.md) for the full test environment setup, seeded replay, and benchmarks.
+
+## Documentation
+
+### Core
+
+- [Core API](docs/core-api.md) - Operation, adapter, policy composition, events
+- [Redis foundation](docs/redis.md) - Standalone and cluster clients, key scheme, security, tuning
+
+### Policies
+
+- [Timeout and retry](docs/timeout-and-retry.md) - Cancellation semantics, backoff, replay safety
+- [Bulkheads](docs/bulkhead.md) - Local and distributed, lease guarantees, failure modes
+- [Circuit breaker](docs/circuit-breaker.md) - State machine, sliding window, distributed coordination
+- [Events and observability](docs/events-and-observability.md) - Full event reference, metrics, alerting
+
+### Adapters
+
+- [Fetch adapter](docs/fetch.md) - Cancellation, replay safety, response classification, streaming
+- [PostgreSQL adapter](docs/postgres.md) - Cancellation, replay safety, SQLSTATE classification
+
+### Contributing
+
+- [Writing your own adapter](docs/adapter-contracts.md) - The `Adapter` interface, capabilities, and the contract test harness
+- [Testing](docs/testing.md) - Test suites, property/fuzz testing, multi-process harness
+- [Architecture](docs/architecture.md) - Package structure, subpath exports, tree-shaking rules
+- [Local development](docs/development.md) - Setup, scripts, integration environments, benchmarks

package/dist/chunk-5CXDW7W6.js

@@ -0,0 +1,202 @@
+import { randomUUID } from 'crypto';
+
+// src/core/operation.ts
+
+// src/core/runtime.ts
+var eventSinks = /* @__PURE__ */ Symbol("caracal.eventSinks");
+var admissionSignals = /* @__PURE__ */ new WeakMap();
+function admissionSignal(context) {
+  const admission = admissionSignals.get(context);
+  return admission && context.signal ? AbortSignal.any([admission, context.signal]) : admission ?? context.signal;
+}
+function withAdmissionSignal(context, signal) {
+  const derived = attachRuntime(
+    { ...context },
+    runtimeContext(context)[eventSinks] ?? []
+  );
+  const previous = admissionSignal(context);
+  admissionSignals.set(
+    derived,
+    previous ? AbortSignal.any([previous, signal]) : signal
+  );
+  return derived;
+}
+function inheritAdmission(source, target) {
+  const signal = admissionSignals.get(source);
+  if (signal) admissionSignals.set(target, signal);
+  return target;
+}
+function runtimeContext(context) {
+  return context;
+}
+function attachRuntime(values, sinks) {
+  const context = values;
+  Object.defineProperty(context, eventSinks, { value: sinks });
+  return Object.freeze(context);
+}
+function createExecutionContext(values, sinks) {
+  return attachRuntime({ attempt: 1, ...values }, sinks);
+}
+function nextAttempt(context) {
+  return inheritAdmission(
+    context,
+    attachRuntime(
+      { ...context, attempt: context.attempt + 1 },
+      runtimeContext(context)[eventSinks] ?? []
+    )
+  );
+}
+function withSignal(context, signal) {
+  return inheritAdmission(
+    context,
+    attachRuntime(
+      { ...context, signal },
+      runtimeContext(context)[eventSinks] ?? []
+    )
+  );
+}
+function emitRuntimeEvent(context, event) {
+  const sinks = runtimeContext(context)[eventSinks] ?? [];
+  const fullEvent = { ...event, at: Date.now(), context };
+  for (const sink of sinks) {
+    try {
+      sink.emit(fullEvent);
+    } catch {
+    }
+  }
+}
+function createClassifier(classify) {
+  return (outcome) => {
+    if (classify === void 0) {
+      return outcome.status === "success" ? "success" : "failure";
+    }
+    return classify(outcome);
+  };
+}
+
+// src/core/operation.ts
+var summarizeSuccess = () => ({
+  status: "success",
+  value: void 0
+});
+var summarizeFailure = (error) => ({
+  status: "failure",
+  error
+});
+function immutableCapabilities(capabilities) {
+  return Object.freeze({ ...capabilities });
+}
+function immutableMetadata(metadata) {
+  return Object.freeze({ ...metadata ?? {} });
+}
+function normalizeSinks(events) {
+  if (events === void 0) {
+    return [];
+  }
+  return "emit" in events ? [events] : events;
+}
+function emit(sinks, event) {
+  for (const sink of sinks) {
+    try {
+      sink.emit(event);
+    } catch {
+    }
+  }
+}
+function validateName(name, kind) {
+  if (name.trim().length === 0) {
+    throw new Error(`${kind} name must not be empty`);
+  }
+}
+function createPipeline(policies, adapter) {
+  return policies.reduceRight(
+    (next, policy) => async (context) => policy.execute(context, next),
+    adapter
+  );
+}
+function invokeAdapter(adapter, args, sinks) {
+  return async (context) => {
+    admissionSignal(context)?.throwIfAborted();
+    emit(sinks, { type: "attempt.started", at: Date.now(), context });
+    try {
+      const value = await adapter.execute(args, context);
+      const outcome = { status: "success", value };
+      const classification = context.classify(outcome);
+      emit(sinks, {
+        type: "attempt.settled",
+        at: Date.now(),
+        context,
+        outcome: summarizeSuccess(),
+        classification
+      });
+      return value;
+    } catch (error) {
+      const outcome = { status: "failure", error };
+      const classification = context.classify(outcome);
+      emit(sinks, {
+        type: "attempt.settled",
+        at: Date.now(),
+        context,
+        outcome: summarizeFailure(error),
+        classification
+      });
+      throw error;
+    }
+  };
+}
+function operation(options) {
+  validateName(options.name, "operation");
+  for (const policy of options.policies ?? []) {
+    validateName(policy.name, "policy");
+  }
+  const policies = Object.freeze([...options.policies ?? []]);
+  const sinks = Object.freeze(normalizeSinks(options.events));
+  return Object.freeze({
+    name: options.name,
+    async execute(args, executeOptions = {}) {
+      const capabilities = options.adapter.capabilities(args);
+      const context = createExecutionContext(
+        {
+          operationName: options.name,
+          executionId: executeOptions.executionId ?? randomUUID(),
+          signal: executeOptions.signal,
+          metadata: immutableMetadata(executeOptions.metadata),
+          capabilities: immutableCapabilities(capabilities),
+          classify: createClassifier(options.adapter.classify)
+        },
+        sinks
+      );
+      const adapter = createPipeline(
+        policies.filter((policy) => policy.phase === "attempt"),
+        invokeAdapter(options.adapter, args, sinks)
+      );
+      const pipeline = createPipeline(
+        policies.filter((policy) => policy.phase !== "attempt"),
+        adapter
+      );
+      emit(sinks, { type: "execution.started", at: Date.now(), context });
+      try {
+        const value = await pipeline(context);
+        emit(sinks, {
+          type: "execution.settled",
+          at: Date.now(),
+          context,
+          outcome: summarizeSuccess()
+        });
+        return value;
+      } catch (error) {
+        emit(sinks, {
+          type: "execution.settled",
+          at: Date.now(),
+          context,
+          outcome: summarizeFailure(error)
+        });
+        throw error;
+      }
+    }
+  });
+}
+
+export { admissionSignal, emitRuntimeEvent, nextAttempt, operation, withAdmissionSignal, withSignal };
+//# sourceMappingURL=chunk-5CXDW7W6.js.map
+//# sourceMappingURL=chunk-5CXDW7W6.js.map

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

@@ -0,0 +1 @@
+{"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"]}