@vivero/stoma 0.1.0-rc.5

package/dist/core/health.d.ts

@@ -0,0 +1,78 @@
+import { RouteConfig } from './types.js';
+import 'hono';
+import '../protocol-2fD3DJrL.js';
+import '../policies/sdk/trace.js';
+import '@vivero/stoma-core';
+import '../observability/metrics.js';
+import '../observability/tracing.js';
+
+/**
+ * Health check route factory with optional upstream probing.
+ *
+ * @module health
+ */
+
+interface HealthConfig {
+    /** Health endpoint path. Default: "/health". */
+    path?: string;
+    /** URLs to probe for upstream health. */
+    upstreamProbes?: string[];
+    /** Include individual upstream statuses in response. Default: false. */
+    includeUpstreamStatus?: boolean;
+    /** Timeout in ms for each upstream probe. Default: 5000. */
+    probeTimeoutMs?: number;
+    /** HTTP method for upstream probes. Default: `"HEAD"`. */
+    probeMethod?: string;
+    /** Status code returned when all probes are unhealthy. Default: 503. */
+    unhealthyStatusCode?: number;
+}
+/**
+ * Create a health check route for liveness and upstream probing.
+ *
+ * Returns a {@link RouteConfig} (not a Policy) - add it directly to the
+ * gateway's `routes` array. Without upstream probes, returns a simple
+ * `{ status: "healthy" }` response. With probes, performs concurrent HEAD
+ * requests (5s timeout each) and reports aggregate status:
+ * - `"healthy"` - all probes passed
+ * - `"degraded"` - some probes failed
+ * - `"unhealthy"` - all probes failed (returns 503)
+ *
+ * @security Enabling `includeUpstreamStatus: true` causes the response to
+ * include the URLs and availability status of internal upstream services.
+ * On public-facing endpoints this leaks internal service topology, which
+ * can aid attackers in reconnaissance (identifying internal hostnames,
+ * ports, and service availability patterns). Restrict health routes that
+ * expose upstream status to internal or admin-only paths, or protect them
+ * with an authentication policy.
+ *
+ * @param config - Endpoint path, upstream probe URLs, and status detail toggle. All fields optional.
+ * @returns A {@link RouteConfig} for a GET health endpoint.
+ *
+ * @example
+ * ```ts
+ * import { createGateway } from "@vivero/stoma";
+ * import { health } from "@vivero/stoma/policies";
+ *
+ * createGateway({
+ *   routes: [
+ *     // Simple liveness check at /health
+ *     health(),
+ *
+ *     // Probe upstreams with detailed status at /healthz
+ *     health({
+ *       path: "/healthz",
+ *       upstreamProbes: [
+ *         "https://api.example.com/health",
+ *         "https://auth.example.com/health",
+ *       ],
+ *       includeUpstreamStatus: true,
+ *     }),
+ *
+ *     // ...other routes
+ *   ],
+ * });
+ * ```
+ */
+declare function health<TBindings = Record<string, unknown>>(config?: HealthConfig): RouteConfig<TBindings>;
+
+export { type HealthConfig, health };

package/dist/core/health.js

@@ -0,0 +1,65 @@
+function health(config) {
+  const path = config?.path ?? "/health";
+  const probes = config?.upstreamProbes ?? [];
+  const includeStatus = config?.includeUpstreamStatus ?? false;
+  const probeTimeoutMs = config?.probeTimeoutMs ?? 5e3;
+  const probeMethod = config?.probeMethod ?? "HEAD";
+  const unhealthyStatusCode = config?.unhealthyStatusCode ?? 503;
+  return {
+    path,
+    methods: ["GET"],
+    pipeline: {
+      upstream: {
+        type: "handler",
+        handler: async (c) => {
+          if (probes.length === 0) {
+            return c.json({
+              status: "healthy",
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            });
+          }
+          const results = await Promise.all(
+            probes.map(async (url) => {
+              const start = Date.now();
+              try {
+                const res = await fetch(url, {
+                  method: probeMethod,
+                  signal: AbortSignal.timeout(probeTimeoutMs)
+                });
+                return {
+                  url,
+                  status: res.ok ? "healthy" : "unhealthy",
+                  latencyMs: Date.now() - start
+                };
+              } catch {
+                return {
+                  url,
+                  status: "unhealthy",
+                  latencyMs: Date.now() - start
+                };
+              }
+            })
+          );
+          const allHealthy = results.every((r) => r.status === "healthy");
+          const allUnhealthy = results.every((r) => r.status === "unhealthy");
+          const status = allHealthy ? "healthy" : allUnhealthy ? "unhealthy" : "degraded";
+          const body = {
+            status,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          if (includeStatus) {
+            body.upstreams = results;
+          }
+          return c.json(
+            body,
+            status === "unhealthy" ? unhealthyStatusCode : 200
+          );
+        }
+      }
+    }
+  };
+}
+export {
+  health
+};
+//# sourceMappingURL=health.js.map

package/dist/core/health.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/health.ts"],"sourcesContent":["/**\n * Health check route factory with optional upstream probing.\n *\n * @module health\n */\nimport type { RouteConfig } from \"./types\";\n\nexport interface HealthConfig {\n  /** Health endpoint path. Default: \"/health\". */\n  path?: string;\n  /** URLs to probe for upstream health. */\n  upstreamProbes?: string[];\n  /** Include individual upstream statuses in response. Default: false. */\n  includeUpstreamStatus?: boolean;\n  /** Timeout in ms for each upstream probe. Default: 5000. */\n  probeTimeoutMs?: number;\n  /** HTTP method for upstream probes. Default: `\"HEAD\"`. */\n  probeMethod?: string;\n  /** Status code returned when all probes are unhealthy. Default: 503. */\n  unhealthyStatusCode?: number;\n}\n\ninterface UpstreamStatus {\n  url: string;\n  status: \"healthy\" | \"unhealthy\";\n  latencyMs: number;\n}\n\n/**\n * Create a health check route for liveness and upstream probing.\n *\n * Returns a {@link RouteConfig} (not a Policy) - add it directly to the\n * gateway's `routes` array. Without upstream probes, returns a simple\n * `{ status: \"healthy\" }` response. With probes, performs concurrent HEAD\n * requests (5s timeout each) and reports aggregate status:\n * - `\"healthy\"` - all probes passed\n * - `\"degraded\"` - some probes failed\n * - `\"unhealthy\"` - all probes failed (returns 503)\n *\n * @security Enabling `includeUpstreamStatus: true` causes the response to\n * include the URLs and availability status of internal upstream services.\n * On public-facing endpoints this leaks internal service topology, which\n * can aid attackers in reconnaissance (identifying internal hostnames,\n * ports, and service availability patterns). Restrict health routes that\n * expose upstream status to internal or admin-only paths, or protect them\n * with an authentication policy.\n *\n * @param config - Endpoint path, upstream probe URLs, and status detail toggle. All fields optional.\n * @returns A {@link RouteConfig} for a GET health endpoint.\n *\n * @example\n * ```ts\n * import { createGateway } from \"@vivero/stoma\";\n * import { health } from \"@vivero/stoma/policies\";\n *\n * createGateway({\n *   routes: [\n *     // Simple liveness check at /health\n *     health(),\n *\n *     // Probe upstreams with detailed status at /healthz\n *     health({\n *       path: \"/healthz\",\n *       upstreamProbes: [\n *         \"https://api.example.com/health\",\n *         \"https://auth.example.com/health\",\n *       ],\n *       includeUpstreamStatus: true,\n *     }),\n *\n *     // ...other routes\n *   ],\n * });\n * ```\n */\nexport function health<TBindings = Record<string, unknown>>(\n  config?: HealthConfig\n): RouteConfig<TBindings> {\n  const path = config?.path ?? \"/health\";\n  const probes = config?.upstreamProbes ?? [];\n  const includeStatus = config?.includeUpstreamStatus ?? false;\n  const probeTimeoutMs = config?.probeTimeoutMs ?? 5000;\n  const probeMethod = config?.probeMethod ?? \"HEAD\";\n  const unhealthyStatusCode = config?.unhealthyStatusCode ?? 503;\n\n  return {\n    path,\n    methods: [\"GET\"],\n    pipeline: {\n      upstream: {\n        type: \"handler\",\n        handler: async (c) => {\n          if (probes.length === 0) {\n            return c.json({\n              status: \"healthy\",\n              timestamp: new Date().toISOString(),\n            });\n          }\n\n          const results = await Promise.all(\n            probes.map(async (url): Promise<UpstreamStatus> => {\n              const start = Date.now();\n              try {\n                const res = await fetch(url, {\n                  method: probeMethod,\n                  signal: AbortSignal.timeout(probeTimeoutMs),\n                });\n                return {\n                  url,\n                  status: res.ok ? \"healthy\" : \"unhealthy\",\n                  latencyMs: Date.now() - start,\n                };\n              } catch {\n                return {\n                  url,\n                  status: \"unhealthy\",\n                  latencyMs: Date.now() - start,\n                };\n              }\n            })\n          );\n\n          const allHealthy = results.every((r) => r.status === \"healthy\");\n          const allUnhealthy = results.every((r) => r.status === \"unhealthy\");\n\n          const status = allHealthy\n            ? \"healthy\"\n            : allUnhealthy\n              ? \"unhealthy\"\n              : \"degraded\";\n\n          const body: Record<string, unknown> = {\n            status,\n            timestamp: new Date().toISOString(),\n          };\n\n          if (includeStatus) {\n            body.upstreams = results;\n          }\n\n          return c.json(\n            body,\n            status === \"unhealthy\" ? (unhealthyStatusCode as 503) : 200\n          );\n        },\n      },\n    },\n  };\n}\n"],"mappings":"AA2EO,SAAS,OACd,QACwB;AACxB,QAAM,OAAO,QAAQ,QAAQ;AAC7B,QAAM,SAAS,QAAQ,kBAAkB,CAAC;AAC1C,QAAM,gBAAgB,QAAQ,yBAAyB;AACvD,QAAM,iBAAiB,QAAQ,kBAAkB;AACjD,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,sBAAsB,QAAQ,uBAAuB;AAE3D,SAAO;AAAA,IACL;AAAA,IACA,SAAS,CAAC,KAAK;AAAA,IACf,UAAU;AAAA,MACR,UAAU;AAAA,QACR,MAAM;AAAA,QACN,SAAS,OAAO,MAAM;AACpB,cAAI,OAAO,WAAW,GAAG;AACvB,mBAAO,EAAE,KAAK;AAAA,cACZ,QAAQ;AAAA,cACR,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,YACpC,CAAC;AAAA,UACH;AAEA,gBAAM,UAAU,MAAM,QAAQ;AAAA,YAC5B,OAAO,IAAI,OAAO,QAAiC;AACjD,oBAAM,QAAQ,KAAK,IAAI;AACvB,kBAAI;AACF,sBAAM,MAAM,MAAM,MAAM,KAAK;AAAA,kBAC3B,QAAQ;AAAA,kBACR,QAAQ,YAAY,QAAQ,cAAc;AAAA,gBAC5C,CAAC;AACD,uBAAO;AAAA,kBACL;AAAA,kBACA,QAAQ,IAAI,KAAK,YAAY;AAAA,kBAC7B,WAAW,KAAK,IAAI,IAAI;AAAA,gBAC1B;AAAA,cACF,QAAQ;AACN,uBAAO;AAAA,kBACL;AAAA,kBACA,QAAQ;AAAA,kBACR,WAAW,KAAK,IAAI,IAAI;AAAA,gBAC1B;AAAA,cACF;AAAA,YACF,CAAC;AAAA,UACH;AAEA,gBAAM,aAAa,QAAQ,MAAM,CAAC,MAAM,EAAE,WAAW,SAAS;AAC9D,gBAAM,eAAe,QAAQ,MAAM,CAAC,MAAM,EAAE,WAAW,WAAW;AAElE,gBAAM,SAAS,aACX,YACA,eACE,cACA;AAEN,gBAAM,OAAgC;AAAA,YACpC;AAAA,YACA,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,UACpC;AAEA,cAAI,eAAe;AACjB,iBAAK,YAAY;AAAA,UACnB;AAEA,iBAAO,EAAE;AAAA,YACP;AAAA,YACA,WAAW,cAAe,sBAA8B;AAAA,UAC1D;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/core/pipeline.d.ts

@@ -0,0 +1,62 @@
+import { Context, MiddlewareHandler } from 'hono';
+import { h as PolicyContext, P as Policy, G as GatewayAdapter } from '../protocol-2fD3DJrL.js';
+import { TracingConfig } from '../observability/tracing.js';
+import { DebugLogger } from '@vivero/stoma-core';
+import { DebugHeadersConfig } from './types.js';
+import '../policies/sdk/trace.js';
+import '../observability/metrics.js';
+
+/**
+ * Policy pipeline - merges, sorts, and wraps policies as Hono middleware.
+ *
+ * The pipeline is the core execution model: global policies are merged with
+ * route-level policies (route wins on name collision), sorted by priority
+ * (ascending), and converted to Hono middleware handlers. A context injector
+ * runs first on every request to set the request ID, timing, and debug factory.
+ *
+ * @module pipeline
+ */
+
+/**
+ * Merge global and route-level policies, deduplicate by name
+ * (route-level wins), and sort by priority ascending.
+ *
+ * @param globalPolicies - Policies from `GatewayConfig.policies`.
+ * @param routePolicies - Policies from `RouteConfig.pipeline.policies`.
+ * @param debug - Optional debug logger for tracing overrides and chain order.
+ * @returns Sorted array of merged policies.
+ */
+declare function buildPolicyChain(globalPolicies: Policy[], routePolicies: Policy[], debug?: DebugLogger, defaultPriority?: number): Policy[];
+/**
+ * Convert a sorted Policy array into an array of Hono MiddlewareHandlers.
+ *
+ * @param policies - Sorted policy array from {@link buildPolicyChain}.
+ * @returns Hono middleware handlers in execution order.
+ */
+declare function policiesToMiddleware(policies: Policy[]): MiddlewareHandler[];
+/**
+ * Create the context-injection middleware that runs at the start of every
+ * pipeline. Sets requestId, startTime, gateway metadata, and debug factory
+ * on Hono's context variables. Also adds `x-request-id` to the response.
+ *
+ * @param gatewayName - Gateway name from config.
+ * @param routePath - The matched route path pattern.
+ * @param debugFactory - Factory for creating namespaced debug loggers.
+ * @param requestIdHeader - Response header name for the request ID.
+ * @param adapter - Optional runtime adapter for runtime-specific capabilities.
+ * @param debugHeaders - Client-requested debug headers configuration.
+ * @returns Hono middleware that injects {@link PolicyContext}.
+ */
+declare function createContextInjector(gatewayName: string, routePath: string, debugFactory?: (namespace: string) => DebugLogger, requestIdHeader?: string, adapter?: GatewayAdapter, debugHeaders?: boolean | DebugHeadersConfig, tracing?: TracingConfig): MiddlewareHandler;
+/**
+ * Retrieve the {@link PolicyContext} from a Hono context.
+ *
+ * Returns `undefined` if called outside the gateway pipeline (e.g. in
+ * a standalone Hono app without context injection).
+ *
+ * @param c - The Hono request context.
+ * @returns The gateway context, or `undefined` if not in a gateway pipeline.
+ */
+declare function getGatewayContext(c: Context): PolicyContext | undefined;
+
+export { buildPolicyChain, createContextInjector, getGatewayContext, policiesToMiddleware };

package/dist/core/pipeline.js

@@ -0,0 +1,214 @@
+import {
+  generateOtelSpanId,
+  SemConv,
+  SpanBuilder,
+  shouldSample
+} from "../observability/tracing";
+import {
+  getCollectedDebugHeaders,
+  parseDebugRequest
+} from "../policies/sdk/helpers";
+import {
+  TRACE_DETAILS_KEY,
+  TRACE_ENTRIES_KEY,
+  TRACE_REQUESTED_KEY
+} from "../policies/sdk/trace";
+import { noopDebugLogger } from "../utils/debug";
+import { toSelfTimes } from "../utils/timing";
+import {
+  formatTraceparent,
+  generateSpanId,
+  generateTraceContext,
+  parseTraceparent
+} from "../utils/trace-context";
+const noopDebugFactory = () => noopDebugLogger;
+const GATEWAY_CONTEXT_KEY = "gateway";
+function buildPolicyChain(globalPolicies, routePolicies, debug, defaultPriority = 100) {
+  const policyMap = /* @__PURE__ */ new Map();
+  for (const p of globalPolicies) {
+    policyMap.set(p.name, p);
+  }
+  for (const p of routePolicies) {
+    if (policyMap.has(p.name)) {
+      debug?.(`policy "${p.name}" overridden by route-level policy`);
+    }
+    policyMap.set(p.name, p);
+  }
+  const sorted = Array.from(policyMap.values()).sort(
+    (a, b) => (a.priority ?? defaultPriority) - (b.priority ?? defaultPriority)
+  );
+  if (sorted.length > 0) {
+    debug?.(
+      `chain: ${sorted.map((p) => `${p.name}:${p.priority ?? defaultPriority}`).join(" -> ")}`
+    );
+  }
+  return sorted;
+}
+function policiesToMiddleware(policies) {
+  return policies.map((policy) => {
+    const originalHandler = policy.handler;
+    const policyPriority = policy.priority ?? 100;
+    const wrappedHandler = async (c, next) => {
+      const start = Date.now();
+      if (c.get(TRACE_REQUESTED_KEY) !== true && c.get("_otelSpans") === void 0) {
+        try {
+          return await originalHandler(c, next);
+        } finally {
+          const durationMs = Date.now() - start;
+          const timings = c.get("_policyTimings") ?? [];
+          timings.push({ name: policy.name, durationMs });
+          c.set("_policyTimings", timings);
+        }
+      }
+      let calledNext = false;
+      let errorMsg = null;
+      let handlerResult;
+      try {
+        const tracedNext = async () => {
+          calledNext = true;
+          await next();
+        };
+        handlerResult = await originalHandler(c, tracedNext);
+      } catch (err) {
+        errorMsg = err instanceof Error ? err.message : String(err);
+        throw err;
+      } finally {
+        const durationMs = Date.now() - start;
+        const timings = c.get("_policyTimings") ?? [];
+        timings.push({ name: policy.name, durationMs });
+        c.set("_policyTimings", timings);
+        if (c.get(TRACE_REQUESTED_KEY) === true) {
+          const entries = c.get(TRACE_ENTRIES_KEY) ?? [];
+          entries.push({
+            name: policy.name,
+            priority: policyPriority,
+            durationMs,
+            calledNext,
+            error: errorMsg
+          });
+          c.set(TRACE_ENTRIES_KEY, entries);
+        }
+        const otelSpans = c.get("_otelSpans");
+        if (otelSpans !== void 0) {
+          const rootSpan = c.get("_otelRootSpan");
+          const span = new SpanBuilder(
+            `policy:${policy.name}`,
+            "INTERNAL",
+            rootSpan.traceId,
+            generateOtelSpanId(),
+            rootSpan.spanId,
+            start
+          );
+          span.setAttribute("policy.name", policy.name).setAttribute("policy.priority", policyPriority);
+          if (errorMsg) {
+            span.setStatus("ERROR", errorMsg);
+          }
+          otelSpans.push(span.end());
+        }
+      }
+      return handlerResult;
+    };
+    return wrappedHandler;
+  });
+}
+function createContextInjector(gatewayName, routePath, debugFactory = noopDebugFactory, requestIdHeader = "x-request-id", adapter, debugHeaders, tracing) {
+  const debugHeadersConfig = debugHeaders === true ? {} : debugHeaders || void 0;
+  const debugRequestHeader = debugHeadersConfig?.requestHeader ?? "x-stoma-debug";
+  const debugAllow = debugHeadersConfig?.allow;
+  return async (c, next) => {
+    const incomingTraceparent = c.req.header("traceparent") ?? null;
+    const parsed = parseTraceparent(incomingTraceparent);
+    const traceId = parsed?.traceId ?? generateTraceContext().traceId;
+    const spanId = generateSpanId();
+    const ctx = {
+      requestId: crypto.randomUUID(),
+      startTime: Date.now(),
+      gatewayName,
+      routePath,
+      traceId,
+      spanId,
+      debug: debugFactory,
+      adapter
+    };
+    c.set(GATEWAY_CONTEXT_KEY, ctx);
+    let otelRootSpan;
+    if (tracing && shouldSample(tracing.sampleRate ?? 1)) {
+      const otelSpanId = generateOtelSpanId();
+      otelRootSpan = new SpanBuilder(
+        `${c.req.method} ${routePath}`,
+        "SERVER",
+        traceId,
+        otelSpanId,
+        parsed?.parentId,
+        ctx.startTime
+      );
+      otelRootSpan.setAttribute(SemConv.HTTP_METHOD, c.req.method).setAttribute(SemConv.HTTP_ROUTE, routePath).setAttribute(SemConv.URL_PATH, new URL(c.req.url).pathname).setAttribute("gateway.name", gatewayName);
+      c.set("_otelRootSpan", otelRootSpan);
+      c.set("_otelSpans", []);
+    }
+    if (debugHeadersConfig) {
+      parseDebugRequest(c, debugRequestHeader, debugAllow);
+    }
+    await next();
+    c.res.headers.set(requestIdHeader, ctx.requestId);
+    c.res.headers.set(
+      "traceparent",
+      formatTraceparent({
+        version: "00",
+        traceId: ctx.traceId,
+        parentId: ctx.spanId,
+        flags: parsed?.flags ?? "01"
+      })
+    );
+    if (debugHeadersConfig) {
+      const collected = getCollectedDebugHeaders(c);
+      if (collected) {
+        for (const [name, value] of collected) {
+          c.res.headers.set(name, value);
+        }
+      }
+    }
+    if (c.get(TRACE_REQUESTED_KEY) === true) {
+      const rawEntries = c.get(TRACE_ENTRIES_KEY);
+      if (rawEntries && rawEntries.length > 0) {
+        const details = c.get(TRACE_DETAILS_KEY);
+        const selfEntries = toSelfTimes(rawEntries);
+        const entries = selfEntries.map((baseline) => {
+          const detail = details?.get(baseline.name);
+          return detail ? { ...baseline, detail } : baseline;
+        });
+        const trace = {
+          requestId: ctx.requestId,
+          traceId: ctx.traceId,
+          route: routePath,
+          totalMs: Date.now() - ctx.startTime,
+          entries
+        };
+        c.res.headers.set("x-stoma-trace", JSON.stringify(trace));
+      }
+    }
+    if (otelRootSpan) {
+      otelRootSpan.setAttribute(SemConv.HTTP_STATUS_CODE, c.res.status).setStatus(
+        c.res.status >= 500 ? "ERROR" : c.res.status >= 400 ? "UNSET" : "OK"
+      );
+      const rootReadable = otelRootSpan.end();
+      const childSpans = c.get("_otelSpans") ?? [];
+      const allSpans = [rootReadable, ...childSpans];
+      const exportPromise = tracing.exporter.export(allSpans).catch(() => {
+      });
+      if (adapter?.waitUntil) {
+        adapter.waitUntil(exportPromise);
+      }
+    }
+  };
+}
+function getGatewayContext(c) {
+  return c.get(GATEWAY_CONTEXT_KEY);
+}
+export {
+  buildPolicyChain,
+  createContextInjector,
+  getGatewayContext,
+  policiesToMiddleware
+};
+//# sourceMappingURL=pipeline.js.map

package/dist/core/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/pipeline.ts"],"sourcesContent":["/**\n * Policy pipeline - merges, sorts, and wraps policies as Hono middleware.\n *\n * The pipeline is the core execution model: global policies are merged with\n * route-level policies (route wins on name collision), sorted by priority\n * (ascending), and converted to Hono middleware handlers. A context injector\n * runs first on every request to set the request ID, timing, and debug factory.\n *\n * @module pipeline\n */\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport type { GatewayAdapter } from \"../adapters/types\";\nimport type { ReadableSpan, TracingConfig } from \"../observability/tracing\";\nimport {\n  generateOtelSpanId,\n  SemConv,\n  SpanBuilder,\n  shouldSample,\n} from \"../observability/tracing\";\nimport {\n  getCollectedDebugHeaders,\n  parseDebugRequest,\n} from \"../policies/sdk/helpers\";\nimport {\n  type PolicyTrace,\n  type PolicyTraceBaseline,\n  type PolicyTraceDetail,\n  type PolicyTraceEntry,\n  TRACE_DETAILS_KEY,\n  TRACE_ENTRIES_KEY,\n  TRACE_REQUESTED_KEY,\n} from \"../policies/sdk/trace\";\nimport type { Policy, PolicyContext } from \"../policies/types\";\nimport type { DebugLogger } from \"../utils/debug\";\nimport { noopDebugLogger } from \"../utils/debug\";\nimport { toSelfTimes } from \"../utils/timing\";\nimport {\n  formatTraceparent,\n  generateSpanId,\n  generateTraceContext,\n  parseTraceparent,\n} from \"../utils/trace-context\";\nimport type { DebugHeadersConfig } from \"./types\";\n\nconst noopDebugFactory = () => noopDebugLogger;\n\nconst GATEWAY_CONTEXT_KEY = \"gateway\";\n\n/**\n * Merge global and route-level policies, deduplicate by name\n * (route-level wins), and sort by priority ascending.\n *\n * @param globalPolicies - Policies from `GatewayConfig.policies`.\n * @param routePolicies - Policies from `RouteConfig.pipeline.policies`.\n * @param debug - Optional debug logger for tracing overrides and chain order.\n * @returns Sorted array of merged policies.\n */\nexport function buildPolicyChain(\n  globalPolicies: Policy[],\n  routePolicies: Policy[],\n  debug?: DebugLogger,\n  defaultPriority = 100\n): Policy[] {\n  const policyMap = new Map<string, Policy>();\n\n  // Global policies first\n  for (const p of globalPolicies) {\n    policyMap.set(p.name, p);\n  }\n\n  // Route-level policies override global by name\n  for (const p of routePolicies) {\n    if (policyMap.has(p.name)) {\n      debug?.(`policy \"${p.name}\" overridden by route-level policy`);\n    }\n    policyMap.set(p.name, p);\n  }\n\n  // Sort by priority ascending (lower = earlier)\n  const sorted = Array.from(policyMap.values()).sort(\n    (a, b) => (a.priority ?? defaultPriority) - (b.priority ?? defaultPriority)\n  );\n\n  if (sorted.length > 0) {\n    debug?.(\n      `chain: ${sorted.map((p) => `${p.name}:${p.priority ?? defaultPriority}`).join(\" -> \")}`\n    );\n  }\n\n  return sorted;\n}\n\n/**\n * Convert a sorted Policy array into an array of Hono MiddlewareHandlers.\n *\n * @param policies - Sorted policy array from {@link buildPolicyChain}.\n * @returns Hono middleware handlers in execution order.\n */\nexport function policiesToMiddleware(policies: Policy[]): MiddlewareHandler[] {\n  return policies.map((policy) => {\n    const originalHandler = policy.handler;\n    const policyPriority = policy.priority ?? 100;\n    // Wrap with skip logic and per-policy timing.\n    // Uses try-finally so timing is recorded even when a policy throws\n    // (e.g. timeout throwing GatewayError on deadline exceeded).\n    const wrappedHandler: MiddlewareHandler = async (c, next) => {\n      const start = Date.now();\n\n      // Fast path: when neither policy trace nor OTel tracing is active,\n      // avoid allocating trace-only variables and the tracedNext closure.\n      if (\n        c.get(TRACE_REQUESTED_KEY) !== true &&\n        c.get(\"_otelSpans\") === undefined\n      ) {\n        try {\n          // Return the handler result so Hono's compose() can finalize the\n          // context when a policy short-circuits by returning a Response\n          // (e.g. Hono's CORS middleware returns a 204 for OPTIONS preflight).\n          return await originalHandler(c, next);\n        } finally {\n          const durationMs = Date.now() - start;\n          const timings = (c.get(\"_policyTimings\") ?? []) as Array<{\n            name: string;\n            durationMs: number;\n          }>;\n          timings.push({ name: policy.name, durationMs });\n          c.set(\"_policyTimings\", timings);\n        }\n      }\n\n      // Slow path: tracing active (policy trace, OTel, or both) -\n      // track calledNext, errors, and push entries.\n      let calledNext = false;\n      let errorMsg: string | null = null;\n      let handlerResult: Response | void;\n\n      try {\n        const tracedNext = async () => {\n          calledNext = true;\n          await next();\n        };\n        handlerResult = await originalHandler(c, tracedNext);\n      } catch (err) {\n        errorMsg = err instanceof Error ? err.message : String(err);\n        throw err;\n      } finally {\n        const durationMs = Date.now() - start;\n\n        // Accumulate per-policy timing data for observability policies\n        const timings = (c.get(\"_policyTimings\") ?? []) as Array<{\n          name: string;\n          durationMs: number;\n        }>;\n        timings.push({ name: policy.name, durationMs });\n        c.set(\"_policyTimings\", timings);\n\n        // Accumulate trace baseline entries (policy trace system)\n        if (c.get(TRACE_REQUESTED_KEY) === true) {\n          const entries = (c.get(TRACE_ENTRIES_KEY) ??\n            []) as PolicyTraceBaseline[];\n          entries.push({\n            name: policy.name,\n            priority: policyPriority,\n            durationMs,\n            calledNext,\n            error: errorMsg,\n          });\n          c.set(TRACE_ENTRIES_KEY, entries);\n        }\n\n        // OTel: create INTERNAL child span per policy\n        const otelSpans = c.get(\"_otelSpans\") as ReadableSpan[] | undefined;\n        if (otelSpans !== undefined) {\n          const rootSpan = c.get(\"_otelRootSpan\") as SpanBuilder;\n          const span = new SpanBuilder(\n            `policy:${policy.name}`,\n            \"INTERNAL\",\n            rootSpan.traceId,\n            generateOtelSpanId(),\n            rootSpan.spanId,\n            start\n          );\n          span\n            .setAttribute(\"policy.name\", policy.name)\n            .setAttribute(\"policy.priority\", policyPriority);\n          if (errorMsg) {\n            span.setStatus(\"ERROR\", errorMsg);\n          }\n          otelSpans.push(span.end());\n        }\n      }\n\n      return handlerResult;\n    };\n    return wrappedHandler;\n  });\n}\n\n/**\n * Create the context-injection middleware that runs at the start of every\n * pipeline. Sets requestId, startTime, gateway metadata, and debug factory\n * on Hono's context variables. Also adds `x-request-id` to the response.\n *\n * @param gatewayName - Gateway name from config.\n * @param routePath - The matched route path pattern.\n * @param debugFactory - Factory for creating namespaced debug loggers.\n * @param requestIdHeader - Response header name for the request ID.\n * @param adapter - Optional runtime adapter for runtime-specific capabilities.\n * @param debugHeaders - Client-requested debug headers configuration.\n * @returns Hono middleware that injects {@link PolicyContext}.\n */\nexport function createContextInjector(\n  gatewayName: string,\n  routePath: string,\n  debugFactory: (namespace: string) => DebugLogger = noopDebugFactory,\n  requestIdHeader = \"x-request-id\",\n  adapter?: GatewayAdapter,\n  debugHeaders?: boolean | DebugHeadersConfig,\n  tracing?: TracingConfig\n): MiddlewareHandler {\n  // Pre-compute debug header config once at construction time\n  const debugHeadersConfig =\n    debugHeaders === true\n      ? ({} as DebugHeadersConfig)\n      : debugHeaders || undefined;\n  const debugRequestHeader =\n    debugHeadersConfig?.requestHeader ?? \"x-stoma-debug\";\n  const debugAllow = debugHeadersConfig?.allow;\n\n  return async (c, next) => {\n    // Parse incoming traceparent or generate a new trace context\n    const incomingTraceparent = c.req.header(\"traceparent\") ?? null;\n    const parsed = parseTraceparent(incomingTraceparent);\n    const traceId = parsed?.traceId ?? generateTraceContext().traceId;\n    const spanId = generateSpanId();\n\n    const ctx: PolicyContext = {\n      requestId: crypto.randomUUID(),\n      startTime: Date.now(),\n      gatewayName,\n      routePath,\n      traceId,\n      spanId,\n      debug: debugFactory,\n      adapter,\n    };\n    c.set(GATEWAY_CONTEXT_KEY, ctx);\n\n    // OTel tracing: create root SERVER span if sampled\n    let otelRootSpan: SpanBuilder | undefined;\n    if (tracing && shouldSample(tracing.sampleRate ?? 1.0)) {\n      const otelSpanId = generateOtelSpanId();\n      otelRootSpan = new SpanBuilder(\n        `${c.req.method} ${routePath}`,\n        \"SERVER\",\n        traceId,\n        otelSpanId,\n        parsed?.parentId,\n        ctx.startTime\n      );\n      otelRootSpan\n        .setAttribute(SemConv.HTTP_METHOD, c.req.method)\n        .setAttribute(SemConv.HTTP_ROUTE, routePath)\n        .setAttribute(SemConv.URL_PATH, new URL(c.req.url).pathname)\n        .setAttribute(\"gateway.name\", gatewayName);\n\n      c.set(\"_otelRootSpan\", otelRootSpan);\n      c.set(\"_otelSpans\", [] as ReadableSpan[]);\n    }\n\n    // Parse client debug header request before policies run\n    if (debugHeadersConfig) {\n      parseDebugRequest(c, debugRequestHeader, debugAllow);\n    }\n\n    await next();\n\n    // Set request ID header on the final response (after downstream runs)\n    // so it's present even when handlers return raw Response objects\n    c.res.headers.set(requestIdHeader, ctx.requestId);\n    // Propagate W3C traceparent on the response\n    c.res.headers.set(\n      \"traceparent\",\n      formatTraceparent({\n        version: \"00\",\n        traceId: ctx.traceId,\n        parentId: ctx.spanId,\n        flags: parsed?.flags ?? \"01\",\n      })\n    );\n\n    // Emit collected debug headers on the response\n    if (debugHeadersConfig) {\n      const collected = getCollectedDebugHeaders(c);\n      if (collected) {\n        for (const [name, value] of collected) {\n          c.res.headers.set(name, value);\n        }\n      }\n    }\n\n    // Emit policy trace when tracing was requested\n    if (c.get(TRACE_REQUESTED_KEY) === true) {\n      const rawEntries = c.get(TRACE_ENTRIES_KEY) as\n        | PolicyTraceBaseline[]\n        | undefined;\n      if (rawEntries && rawEntries.length > 0) {\n        const details = c.get(TRACE_DETAILS_KEY) as\n          | Map<string, PolicyTraceDetail>\n          | undefined;\n\n        // Convert inclusive timings to self-time (execution order)\n        const selfEntries = toSelfTimes(rawEntries);\n\n        // Merge baseline + detail\n        const entries: PolicyTraceEntry[] = selfEntries.map((baseline) => {\n          const detail = details?.get(baseline.name);\n          return detail ? { ...baseline, detail } : baseline;\n        });\n\n        const trace: PolicyTrace = {\n          requestId: ctx.requestId,\n          traceId: ctx.traceId,\n          route: routePath,\n          totalMs: Date.now() - ctx.startTime,\n          entries,\n        };\n\n        c.res.headers.set(\"x-stoma-trace\", JSON.stringify(trace));\n      }\n    }\n\n    // OTel tracing: finalize root span and export\n    if (otelRootSpan) {\n      otelRootSpan\n        .setAttribute(SemConv.HTTP_STATUS_CODE, c.res.status)\n        .setStatus(\n          c.res.status >= 500 ? \"ERROR\" : c.res.status >= 400 ? \"UNSET\" : \"OK\"\n        );\n\n      const rootReadable = otelRootSpan.end();\n      const childSpans = (c.get(\"_otelSpans\") ?? []) as ReadableSpan[];\n      const allSpans = [rootReadable, ...childSpans];\n\n      // Export asynchronously - don't block the response\n      const exportPromise = tracing!.exporter.export(allSpans).catch(() => {\n        // Swallow export errors - tracing must never break the request\n      });\n\n      if (adapter?.waitUntil) {\n        adapter.waitUntil(exportPromise);\n      }\n    }\n  };\n}\n\n/**\n * Retrieve the {@link PolicyContext} from a Hono context.\n *\n * Returns `undefined` if called outside the gateway pipeline (e.g. in\n * a standalone Hono app without context injection).\n *\n * @param c - The Hono request context.\n * @returns The gateway context, or `undefined` if not in a gateway pipeline.\n */\nexport function getGatewayContext(c: Context): PolicyContext | undefined {\n  return c.get(GATEWAY_CONTEXT_KEY) as PolicyContext | undefined;\n}\n"],"mappings":"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","names":[]}

package/dist/core/protocol.d.ts

@@ -0,0 +1,4 @@
+export { A as AttributeMutation, B as BodyMutation, H as HeaderMutation, M as Mutation, i as PolicyContinue, j as PolicyEvalContext, k as PolicyEvaluator, l as PolicyImmediateResponse, m as PolicyInput, n as PolicyReject, o as PolicyResult, p as ProcessingPhase, q as ProtocolType, S as StatusMutation } from '../protocol-2fD3DJrL.js';
+import '../policies/sdk/trace.js';
+import '@vivero/stoma-core';
+import 'hono';

package/dist/core/protocol.js

@@ -0,0 +1 @@
+//# sourceMappingURL=protocol.js.map

package/dist/core/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/core/scope.d.ts

@@ -0,0 +1,67 @@
+import { P as Policy } from '../protocol-2fD3DJrL.js';
+import { RouteConfig } from './types.js';
+import 'hono';
+import '../policies/sdk/trace.js';
+import '@vivero/stoma-core';
+import '../observability/metrics.js';
+import '../observability/tracing.js';
+
+/**
+ * Route scoping - group routes under a shared path prefix with shared policies.
+ *
+ * `scope()` transforms an array of {@link RouteConfig} by prepending a path
+ * prefix, prepending shared policies, and merging metadata. The output is a
+ * flat `RouteConfig[]` that can be spread directly into `GatewayConfig.routes`.
+ *
+ * Nesting works naturally - pass the output of an inner `scope()` as the
+ * `routes` of an outer `scope()`.
+ *
+ * @module scope
+ *
+ * @example
+ * ```ts
+ * import { createGateway, scope, jwtAuth, rateLimit } from "@vivero/stoma";
+ *
+ * const gateway = createGateway({
+ *   routes: [
+ *     ...scope({
+ *       prefix: "/api/v1",
+ *       policies: [jwtAuth({ secret: "..." })],
+ *       routes: [
+ *         { path: "/users", pipeline: { upstream: { type: "url", target: "https://users.internal" } } },
+ *         { path: "/orders", pipeline: { upstream: { type: "url", target: "https://orders.internal" } } },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/**
+ * Configuration for a route scope (group).
+ *
+ * @typeParam TBindings - Worker bindings type, propagated to child routes.
+ */
+interface ScopeConfig<TBindings = Record<string, unknown>> {
+    /** Path prefix prepended to all child routes (e.g. "/api/v1") */
+    prefix: string;
+    /** Policies prepended to every child route's pipeline policies */
+    policies?: Policy[];
+    /** Child routes to scope */
+    routes: RouteConfig<TBindings>[];
+    /** Metadata merged into every child route (child wins on conflict) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Group routes under a shared path prefix with shared policies and metadata.
+ *
+ * Returns a flat array of transformed {@link RouteConfig} objects ready to be
+ * spread into `GatewayConfig.routes`.
+ *
+ * @typeParam TBindings - Worker bindings type, propagated to child routes.
+ * @param config - Scope configuration.
+ * @returns Array of route configs with prefix, policies, and metadata applied.
+ */
+declare function scope<TBindings = Record<string, unknown>>(config: ScopeConfig<TBindings>): RouteConfig<TBindings>[];
+
+export { type ScopeConfig, scope };

package/dist/core/scope.js

@@ -0,0 +1,44 @@
+function normalizePrefix(prefix) {
+  let normalized = prefix;
+  if (!normalized.startsWith("/")) {
+    normalized = `/${normalized}`;
+  }
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+function joinPaths(prefix, path) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  if (normalizedPath === "/") {
+    return prefix;
+  }
+  if (prefix.endsWith("/") && normalizedPath.startsWith("/")) {
+    return `${prefix}${normalizedPath.slice(1)}`;
+  }
+  return `${prefix}${normalizedPath}`;
+}
+function scope(config) {
+  const prefix = normalizePrefix(config.prefix);
+  const scopePolicies = config.policies ?? [];
+  const scopeMetadata = config.metadata ?? {};
+  return config.routes.map((route) => {
+    const fullPath = joinPaths(prefix, route.path);
+    const routePolicies = route.pipeline.policies ?? [];
+    const mergedPolicies = scopePolicies.length > 0 || routePolicies.length > 0 ? [...scopePolicies, ...routePolicies] : void 0;
+    const mergedMetadata = Object.keys(scopeMetadata).length > 0 || route.metadata ? { ...scopeMetadata, ...route.metadata } : void 0;
+    return {
+      ...route,
+      path: fullPath,
+      pipeline: {
+        ...route.pipeline,
+        ...mergedPolicies !== void 0 ? { policies: mergedPolicies } : {}
+      },
+      ...mergedMetadata !== void 0 ? { metadata: mergedMetadata } : {}
+    };
+  });
+}
+export {
+  scope
+};
+//# sourceMappingURL=scope.js.map

package/dist/core/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/scope.ts"],"sourcesContent":["/**\n * Route scoping - group routes under a shared path prefix with shared policies.\n *\n * `scope()` transforms an array of {@link RouteConfig} by prepending a path\n * prefix, prepending shared policies, and merging metadata. The output is a\n * flat `RouteConfig[]` that can be spread directly into `GatewayConfig.routes`.\n *\n * Nesting works naturally - pass the output of an inner `scope()` as the\n * `routes` of an outer `scope()`.\n *\n * @module scope\n *\n * @example\n * ```ts\n * import { createGateway, scope, jwtAuth, rateLimit } from \"@vivero/stoma\";\n *\n * const gateway = createGateway({\n *   routes: [\n *     ...scope({\n *       prefix: \"/api/v1\",\n *       policies: [jwtAuth({ secret: \"...\" })],\n *       routes: [\n *         { path: \"/users\", pipeline: { upstream: { type: \"url\", target: \"https://users.internal\" } } },\n *         { path: \"/orders\", pipeline: { upstream: { type: \"url\", target: \"https://orders.internal\" } } },\n *       ],\n *     }),\n *   ],\n * });\n * ```\n */\nimport type { Policy } from \"../policies/types\";\nimport type { RouteConfig } from \"./types\";\n\n/**\n * Configuration for a route scope (group).\n *\n * @typeParam TBindings - Worker bindings type, propagated to child routes.\n */\nexport interface ScopeConfig<TBindings = Record<string, unknown>> {\n  /** Path prefix prepended to all child routes (e.g. \"/api/v1\") */\n  prefix: string;\n  /** Policies prepended to every child route's pipeline policies */\n  policies?: Policy[];\n  /** Child routes to scope */\n  routes: RouteConfig<TBindings>[];\n  /** Metadata merged into every child route (child wins on conflict) */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Normalize a path prefix: ensure leading `/`, strip trailing `/`.\n *\n * @internal\n */\nfunction normalizePrefix(prefix: string): string {\n  let normalized = prefix;\n\n  // Ensure leading slash\n  if (!normalized.startsWith(\"/\")) {\n    normalized = `/${normalized}`;\n  }\n\n  // Strip trailing slash (unless the prefix is just \"/\")\n  if (normalized.length > 1 && normalized.endsWith(\"/\")) {\n    normalized = normalized.slice(0, -1);\n  }\n\n  return normalized;\n}\n\n/**\n * Join a normalized prefix and a route path, avoiding double slashes.\n *\n * @internal\n */\nfunction joinPaths(prefix: string, path: string): string {\n  // Ensure path has leading slash\n  const normalizedPath = path.startsWith(\"/\") ? path : `/${path}`;\n\n  // Root path \"/\" means \"the scope prefix itself\" — return prefix without\n  // a trailing slash so that `/environment` + `/` → `/environment`, not\n  // `/environment/` (which Hono treats as a different route).\n  if (normalizedPath === \"/\") {\n    return prefix;\n  }\n\n  // Avoid double slashes at the join point\n  if (prefix.endsWith(\"/\") && normalizedPath.startsWith(\"/\")) {\n    return `${prefix}${normalizedPath.slice(1)}`;\n  }\n\n  return `${prefix}${normalizedPath}`;\n}\n\n/**\n * Group routes under a shared path prefix with shared policies and metadata.\n *\n * Returns a flat array of transformed {@link RouteConfig} objects ready to be\n * spread into `GatewayConfig.routes`.\n *\n * @typeParam TBindings - Worker bindings type, propagated to child routes.\n * @param config - Scope configuration.\n * @returns Array of route configs with prefix, policies, and metadata applied.\n */\nexport function scope<TBindings = Record<string, unknown>>(\n  config: ScopeConfig<TBindings>\n): RouteConfig<TBindings>[] {\n  const prefix = normalizePrefix(config.prefix);\n  const scopePolicies = config.policies ?? [];\n  const scopeMetadata = config.metadata ?? {};\n\n  return config.routes.map((route) => {\n    const fullPath = joinPaths(prefix, route.path);\n\n    // Prepend scope policies before route policies (scope runs first)\n    const routePolicies = route.pipeline.policies ?? [];\n    const mergedPolicies =\n      scopePolicies.length > 0 || routePolicies.length > 0\n        ? [...scopePolicies, ...routePolicies]\n        : undefined;\n\n    // Merge metadata: scope metadata as base, child wins on conflict\n    const mergedMetadata =\n      Object.keys(scopeMetadata).length > 0 || route.metadata\n        ? { ...scopeMetadata, ...route.metadata }\n        : undefined;\n\n    return {\n      ...route,\n      path: fullPath,\n      pipeline: {\n        ...route.pipeline,\n        ...(mergedPolicies !== undefined ? { policies: mergedPolicies } : {}),\n      },\n      ...(mergedMetadata !== undefined ? { metadata: mergedMetadata } : {}),\n    };\n  });\n}\n"],"mappings":"AAsDA,SAAS,gBAAgB,QAAwB;AAC/C,MAAI,aAAa;AAGjB,MAAI,CAAC,WAAW,WAAW,GAAG,GAAG;AAC/B,iBAAa,IAAI,UAAU;AAAA,EAC7B;AAGA,MAAI,WAAW,SAAS,KAAK,WAAW,SAAS,GAAG,GAAG;AACrD,iBAAa,WAAW,MAAM,GAAG,EAAE;AAAA,EACrC;AAEA,SAAO;AACT;AAOA,SAAS,UAAU,QAAgB,MAAsB;AAEvD,QAAM,iBAAiB,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI,IAAI;AAK7D,MAAI,mBAAmB,KAAK;AAC1B,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,SAAS,GAAG,KAAK,eAAe,WAAW,GAAG,GAAG;AAC1D,WAAO,GAAG,MAAM,GAAG,eAAe,MAAM,CAAC,CAAC;AAAA,EAC5C;AAEA,SAAO,GAAG,MAAM,GAAG,cAAc;AACnC;AAYO,SAAS,MACd,QAC0B;AAC1B,QAAM,SAAS,gBAAgB,OAAO,MAAM;AAC5C,QAAM,gBAAgB,OAAO,YAAY,CAAC;AAC1C,QAAM,gBAAgB,OAAO,YAAY,CAAC;AAE1C,SAAO,OAAO,OAAO,IAAI,CAAC,UAAU;AAClC,UAAM,WAAW,UAAU,QAAQ,MAAM,IAAI;AAG7C,UAAM,gBAAgB,MAAM,SAAS,YAAY,CAAC;AAClD,UAAM,iBACJ,cAAc,SAAS,KAAK,cAAc,SAAS,IAC/C,CAAC,GAAG,eAAe,GAAG,aAAa,IACnC;AAGN,UAAM,iBACJ,OAAO,KAAK,aAAa,EAAE,SAAS,KAAK,MAAM,WAC3C,EAAE,GAAG,eAAe,GAAG,MAAM,SAAS,IACtC;AAEN,WAAO;AAAA,MACL,GAAG;AAAA,MACH,MAAM;AAAA,MACN,UAAU;AAAA,QACR,GAAG,MAAM;AAAA,QACT,GAAI,mBAAmB,SAAY,EAAE,UAAU,eAAe,IAAI,CAAC;AAAA,MACrE;AAAA,MACA,GAAI,mBAAmB,SAAY,EAAE,UAAU,eAAe,IAAI,CAAC;AAAA,IACrE;AAAA,EACF,CAAC;AACH;","names":[]}