@vivero/stoma 0.1.0-rc.10

package/dist/policies/sdk/define-policy.d.ts

@@ -0,0 +1,176 @@
+import { Context, Next } from 'hono';
+import { g as PolicyConfig, h as PolicyContext, m as PolicyInput, j as PolicyEvalContext, o as PolicyResult, p as ProcessingPhase, P as Policy } from '../../protocol-2fD3DJrL.js';
+import { DebugLogger } from '@vivero/stoma-core';
+import { TraceReporter } from './trace.js';
+
+/**
+ * `definePolicy()` - full convenience wrapper for policy authors.
+ *
+ * Combines {@link resolveConfig}, {@link policyDebug}, and {@link withSkip}
+ * into a single declarative API. Takes a {@link PolicyDefinition} and returns
+ * a factory function `(config?) => Policy`.
+ *
+ * Supports both HTTP-specific handlers (Hono middleware) and protocol-agnostic
+ * evaluators for multi-runtime policies (ext_proc, WebSocket).
+ *
+ * @module define-policy
+ */
+
+/**
+ * Context injected into every `definePolicy` handler invocation.
+ *
+ * Provides the fully-merged config, a pre-namespaced debug logger,
+ * and the gateway context (request ID, trace ID, etc.).
+ */
+interface PolicyHandlerContext<TConfig> {
+    /** Fully merged config (defaults + user overrides). */
+    config: TConfig;
+    /** Debug logger pre-namespaced to `stoma:policy:{name}`. Always callable. */
+    debug: DebugLogger;
+    /** Trace reporter - always callable, no-op when tracing is not active. */
+    trace: TraceReporter;
+    /** Gateway context, or `undefined` when running outside a gateway pipeline. */
+    gateway: PolicyContext | undefined;
+}
+/**
+ * Context injected into `definePolicy` evaluate handlers.
+ *
+ * Parallel to {@link PolicyHandlerContext} but protocol-agnostic -
+ * no Hono types. Extends the runtime-facing {@link PolicyEvalContext}
+ * with the fully-merged, typed config.
+ */
+interface PolicyEvalHandlerContext<TConfig> extends PolicyEvalContext {
+    /** Fully merged config (defaults + user overrides). */
+    config: TConfig;
+}
+/**
+ * Declarative policy definition passed to {@link definePolicy}.
+ */
+interface PolicyDefinition<TConfig extends PolicyConfig = PolicyConfig> {
+    /** Unique policy name (e.g. `"my-auth"`, `"custom-cache"`). */
+    name: string;
+    /** Execution priority. Use {@link Priority} constants. Default: `Priority.DEFAULT` (100). */
+    priority?: number;
+    /** Default values for optional config fields. */
+    defaults?: Partial<TConfig>;
+    /**
+     * Optional construction-time config validation.
+     *
+     * Called once when the factory is invoked (before any requests).
+     * Throw a {@link GatewayError} to reject invalid config eagerly
+     * rather than failing on the first request.
+     */
+    validate?: (config: TConfig) => void;
+    /**
+     * The HTTP policy handler. Receives the Hono context, `next`, and a
+     * {@link PolicyHandlerContext} with config, debug, and gateway context.
+     *
+     * Used by the HTTP runtime ({@link createGateway}).
+     */
+    handler: (c: Context, next: Next, ctx: PolicyHandlerContext<TConfig>) => Promise<void> | void;
+    /**
+     * Protocol-agnostic evaluator for multi-runtime policies.
+     *
+     * Used by non-HTTP runtimes (ext_proc, WebSocket). The HTTP runtime
+     * uses {@link handler} and ignores this field.
+     *
+     * Implement this alongside `handler` to make a policy work across
+     * all runtimes. The `config` is pre-merged and injected into
+     * {@link PolicyEvalHandlerContext}.
+     *
+     * @example
+     * ```ts
+     * const myPolicy = definePolicy<MyConfig>({
+     *   name: "my-policy",
+     *   priority: Priority.AUTH,
+     *   phases: ["request-headers"],
+     *   handler: async (c, next, { config }) => { ... },
+     *   evaluate: {
+     *     onRequest: async (input, { config }) => {
+     *       const token = input.headers.get("authorization");
+     *       if (!token) return { action: "reject", status: 401, code: "unauthorized", message: "Missing" };
+     *       return { action: "continue" };
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    evaluate?: {
+        onRequest?: (input: PolicyInput, ctx: PolicyEvalHandlerContext<TConfig>) => Promise<PolicyResult>;
+        onResponse?: (input: PolicyInput, ctx: PolicyEvalHandlerContext<TConfig>) => Promise<PolicyResult>;
+    };
+    /**
+     * Processing phases this policy participates in.
+     *
+     * Used by phase-based runtimes (ext_proc) to skip policies that
+     * don't apply to the current phase. Passed through to the
+     * returned {@link Policy.phases}.
+     *
+     * Default: `["request-headers"]`.
+     */
+    phases?: ProcessingPhase[];
+    /**
+     * Set to `true` for policies that only work with the HTTP protocol.
+     *
+     * These policies rely on HTTP-specific concepts (Request/Response objects,
+     * specific headers, HTTP status codes, etc.) and cannot be meaningfully
+     * evaluated in other protocols like ext_proc or WebSocket.
+     *
+     * When set, this is passed through to the returned Policy's `httpOnly` property.
+     */
+    httpOnly?: true;
+}
+/**
+ * Extract the keys of T that are required (not optional).
+ * Evaluates to `never` when all keys are optional.
+ */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+/**
+ * Conditional policy factory type.
+ *
+ * When `TConfig` has at least one required key, the factory requires
+ * a config argument. When all keys are optional (or TConfig is the
+ * base `PolicyConfig`), config is optional.
+ *
+ * This closes the gap between "type-safe config" and the runtime
+ * `validate` callback - the editor catches missing required fields
+ * at compile time.
+ */
+type PolicyFactory<TConfig extends PolicyConfig> = RequiredKeys<TConfig> extends never ? (config?: TConfig) => Policy : (config: TConfig) => Policy;
+/**
+ * Create a policy factory from a declarative definition.
+ *
+ * The returned factory function accepts user config, merges it with
+ * defaults, wires up skip logic, and injects a debug logger at
+ * request time.
+ *
+ * When `TConfig` has required keys, the factory requires a config
+ * argument. When all keys are optional, config is optional.
+ *
+ * @example
+ * ```ts
+ * import { definePolicy, Priority } from "@vivero/stoma";
+ *
+ * const myPolicy = definePolicy<MyConfig>({
+ *   name: "my-policy",
+ *   priority: Priority.AUTH,
+ *   defaults: { headerName: "x-custom" },
+ *   handler: async (c, next, { config, debug }) => {
+ *     debug("checking header");
+ *     const value = c.req.header(config.headerName!);
+ *     if (!value) throw new GatewayError(401, "unauthorized", "Missing header");
+ *     await next();
+ *   },
+ * });
+ *
+ * // Usage: myPolicy({ headerName: "x-api-key" })
+ * ```
+ *
+ * @param definition - Policy name, priority, defaults, and handler.
+ * @returns A factory function whose config parameter is required or optional based on TConfig.
+ */
+declare function definePolicy<TConfig extends PolicyConfig = PolicyConfig>(definition: PolicyDefinition<TConfig>): PolicyFactory<TConfig>;
+
+export { type PolicyDefinition, type PolicyEvalHandlerContext, type PolicyFactory, type PolicyHandlerContext, definePolicy };

package/dist/policies/sdk/define-policy.js

@@ -0,0 +1,42 @@
+import { getGatewayContext } from "../../core/pipeline";
+import { policyDebug, resolveConfig, withSkip } from "./helpers";
+import { Priority } from "./priority";
+import { policyTrace } from "./trace";
+function definePolicy(definition) {
+  return ((userConfig) => {
+    const config = resolveConfig(
+      definition.defaults ?? {},
+      userConfig
+    );
+    if (definition.validate) {
+      definition.validate(config);
+    }
+    const rawHandler = async (c, next) => {
+      const debug = policyDebug(c, definition.name);
+      const trace = policyTrace(c, definition.name);
+      const gateway = getGatewayContext(c);
+      await definition.handler(c, next, { config, debug, trace, gateway });
+    };
+    const handler = withSkip(config.skip, rawHandler);
+    let evaluate;
+    if (definition.evaluate) {
+      const defEval = definition.evaluate;
+      evaluate = {
+        onRequest: defEval.onRequest ? (input, ctx) => defEval.onRequest(input, { ...ctx, config }) : void 0,
+        onResponse: defEval.onResponse ? (input, ctx) => defEval.onResponse(input, { ...ctx, config }) : void 0
+      };
+    }
+    return {
+      name: definition.name,
+      priority: definition.priority ?? Priority.DEFAULT,
+      handler,
+      evaluate,
+      phases: definition.phases,
+      httpOnly: definition.httpOnly
+    };
+  });
+}
+export {
+  definePolicy
+};
+//# sourceMappingURL=define-policy.js.map

package/dist/policies/sdk/define-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/sdk/define-policy.ts"],"sourcesContent":["/**\n * `definePolicy()` - full convenience wrapper for policy authors.\n *\n * Combines {@link resolveConfig}, {@link policyDebug}, and {@link withSkip}\n * into a single declarative API. Takes a {@link PolicyDefinition} and returns\n * a factory function `(config?) => Policy`.\n *\n * Supports both HTTP-specific handlers (Hono middleware) and protocol-agnostic\n * evaluators for multi-runtime policies (ext_proc, WebSocket).\n *\n * @module define-policy\n */\nimport type { Context, Next } from \"hono\";\nimport { getGatewayContext } from \"../../core/pipeline\";\nimport type {\n  PolicyEvalContext,\n  PolicyEvaluator,\n  PolicyInput,\n  PolicyResult,\n  ProcessingPhase,\n} from \"../../core/protocol\";\nimport type { DebugLogger } from \"../../utils/debug\";\nimport type { Policy, PolicyConfig, PolicyContext } from \"../types\";\nimport { policyDebug, resolveConfig, withSkip } from \"./helpers\";\nimport { Priority } from \"./priority\";\nimport { policyTrace, type TraceReporter } from \"./trace\";\n\n/**\n * Context injected into every `definePolicy` handler invocation.\n *\n * Provides the fully-merged config, a pre-namespaced debug logger,\n * and the gateway context (request ID, trace ID, etc.).\n */\nexport interface PolicyHandlerContext<TConfig> {\n  /** Fully merged config (defaults + user overrides). */\n  config: TConfig;\n  /** Debug logger pre-namespaced to `stoma:policy:{name}`. Always callable. */\n  debug: DebugLogger;\n  /** Trace reporter - always callable, no-op when tracing is not active. */\n  trace: TraceReporter;\n  /** Gateway context, or `undefined` when running outside a gateway pipeline. */\n  gateway: PolicyContext | undefined;\n}\n\n/**\n * Context injected into `definePolicy` evaluate handlers.\n *\n * Parallel to {@link PolicyHandlerContext} but protocol-agnostic -\n * no Hono types. Extends the runtime-facing {@link PolicyEvalContext}\n * with the fully-merged, typed config.\n */\nexport interface PolicyEvalHandlerContext<TConfig> extends PolicyEvalContext {\n  /** Fully merged config (defaults + user overrides). */\n  config: TConfig;\n}\n\n/**\n * Declarative policy definition passed to {@link definePolicy}.\n */\nexport interface PolicyDefinition<TConfig extends PolicyConfig = PolicyConfig> {\n  /** Unique policy name (e.g. `\"my-auth\"`, `\"custom-cache\"`). */\n  name: string;\n  /** Execution priority. Use {@link Priority} constants. Default: `Priority.DEFAULT` (100). */\n  priority?: number;\n  /** Default values for optional config fields. */\n  defaults?: Partial<TConfig>;\n  /**\n   * Optional construction-time config validation.\n   *\n   * Called once when the factory is invoked (before any requests).\n   * Throw a {@link GatewayError} to reject invalid config eagerly\n   * rather than failing on the first request.\n   */\n  validate?: (config: TConfig) => void;\n  /**\n   * The HTTP policy handler. Receives the Hono context, `next`, and a\n   * {@link PolicyHandlerContext} with config, debug, and gateway context.\n   *\n   * Used by the HTTP runtime ({@link createGateway}).\n   */\n  handler: (\n    c: Context,\n    next: Next,\n    ctx: PolicyHandlerContext<TConfig>\n  ) => Promise<void> | void;\n\n  /**\n   * Protocol-agnostic evaluator for multi-runtime policies.\n   *\n   * Used by non-HTTP runtimes (ext_proc, WebSocket). The HTTP runtime\n   * uses {@link handler} and ignores this field.\n   *\n   * Implement this alongside `handler` to make a policy work across\n   * all runtimes. The `config` is pre-merged and injected into\n   * {@link PolicyEvalHandlerContext}.\n   *\n   * @example\n   * ```ts\n   * const myPolicy = definePolicy<MyConfig>({\n   *   name: \"my-policy\",\n   *   priority: Priority.AUTH,\n   *   phases: [\"request-headers\"],\n   *   handler: async (c, next, { config }) => { ... },\n   *   evaluate: {\n   *     onRequest: async (input, { config }) => {\n   *       const token = input.headers.get(\"authorization\");\n   *       if (!token) return { action: \"reject\", status: 401, code: \"unauthorized\", message: \"Missing\" };\n   *       return { action: \"continue\" };\n   *     },\n   *   },\n   * });\n   * ```\n   */\n  evaluate?: {\n    onRequest?: (\n      input: PolicyInput,\n      ctx: PolicyEvalHandlerContext<TConfig>\n    ) => Promise<PolicyResult>;\n    onResponse?: (\n      input: PolicyInput,\n      ctx: PolicyEvalHandlerContext<TConfig>\n    ) => Promise<PolicyResult>;\n  };\n\n  /**\n   * Processing phases this policy participates in.\n   *\n   * Used by phase-based runtimes (ext_proc) to skip policies that\n   * don't apply to the current phase. Passed through to the\n   * returned {@link Policy.phases}.\n   *\n   * Default: `[\"request-headers\"]`.\n   */\n  phases?: ProcessingPhase[];\n\n  /**\n   * Set to `true` for policies that only work with the HTTP protocol.\n   *\n   * These policies rely on HTTP-specific concepts (Request/Response objects,\n   * specific headers, HTTP status codes, etc.) and cannot be meaningfully\n   * evaluated in other protocols like ext_proc or WebSocket.\n   *\n   * When set, this is passed through to the returned Policy's `httpOnly` property.\n   */\n  httpOnly?: true;\n}\n\n/**\n * Extract the keys of T that are required (not optional).\n * Evaluates to `never` when all keys are optional.\n */\ntype RequiredKeys<T> = {\n  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;\n}[keyof T];\n\n/**\n * Conditional policy factory type.\n *\n * When `TConfig` has at least one required key, the factory requires\n * a config argument. When all keys are optional (or TConfig is the\n * base `PolicyConfig`), config is optional.\n *\n * This closes the gap between \"type-safe config\" and the runtime\n * `validate` callback - the editor catches missing required fields\n * at compile time.\n */\nexport type PolicyFactory<TConfig extends PolicyConfig> =\n  RequiredKeys<TConfig> extends never\n    ? (config?: TConfig) => Policy\n    : (config: TConfig) => Policy;\n\n/**\n * Create a policy factory from a declarative definition.\n *\n * The returned factory function accepts user config, merges it with\n * defaults, wires up skip logic, and injects a debug logger at\n * request time.\n *\n * When `TConfig` has required keys, the factory requires a config\n * argument. When all keys are optional, config is optional.\n *\n * @example\n * ```ts\n * import { definePolicy, Priority } from \"@vivero/stoma\";\n *\n * const myPolicy = definePolicy<MyConfig>({\n *   name: \"my-policy\",\n *   priority: Priority.AUTH,\n *   defaults: { headerName: \"x-custom\" },\n *   handler: async (c, next, { config, debug }) => {\n *     debug(\"checking header\");\n *     const value = c.req.header(config.headerName!);\n *     if (!value) throw new GatewayError(401, \"unauthorized\", \"Missing header\");\n *     await next();\n *   },\n * });\n *\n * // Usage: myPolicy({ headerName: \"x-api-key\" })\n * ```\n *\n * @param definition - Policy name, priority, defaults, and handler.\n * @returns A factory function whose config parameter is required or optional based on TConfig.\n */\nexport function definePolicy<TConfig extends PolicyConfig = PolicyConfig>(\n  definition: PolicyDefinition<TConfig>\n): PolicyFactory<TConfig> {\n  return ((userConfig?: TConfig): Policy => {\n    const config = resolveConfig<TConfig>(\n      (definition.defaults ?? {}) as Partial<TConfig>,\n      userConfig as Partial<TConfig> | undefined\n    );\n\n    // Construction-time validation - fail fast on bad config\n    if (definition.validate) {\n      definition.validate(config);\n    }\n\n    const rawHandler = async (c: Context, next: Next): Promise<void> => {\n      const debug = policyDebug(c, definition.name);\n      const trace = policyTrace(c, definition.name);\n      const gateway = getGatewayContext(c);\n      await definition.handler(c, next, { config, debug, trace, gateway });\n    };\n\n    const handler = withSkip(config.skip, rawHandler);\n\n    // Build the protocol-agnostic evaluator by injecting the merged\n    // config into the runtime-provided PolicyEvalContext.\n    let evaluate: PolicyEvaluator | undefined;\n    if (definition.evaluate) {\n      const defEval = definition.evaluate;\n      evaluate = {\n        onRequest: defEval.onRequest\n          ? (input: PolicyInput, ctx: PolicyEvalContext) =>\n              defEval.onRequest!(input, { ...ctx, config })\n          : undefined,\n        onResponse: defEval.onResponse\n          ? (input: PolicyInput, ctx: PolicyEvalContext) =>\n              defEval.onResponse!(input, { ...ctx, config })\n          : undefined,\n      };\n    }\n\n    return {\n      name: definition.name,\n      priority: definition.priority ?? Priority.DEFAULT,\n      handler,\n      evaluate,\n      phases: definition.phases,\n      httpOnly: definition.httpOnly,\n    };\n  }) as PolicyFactory<TConfig>;\n}\n"],"mappings":"AAaA,SAAS,yBAAyB;AAUlC,SAAS,aAAa,eAAe,gBAAgB;AACrD,SAAS,gBAAgB;AACzB,SAAS,mBAAuC;AAkLzC,SAAS,aACd,YACwB;AACxB,UAAQ,CAAC,eAAiC;AACxC,UAAM,SAAS;AAAA,MACZ,WAAW,YAAY,CAAC;AAAA,MACzB;AAAA,IACF;AAGA,QAAI,WAAW,UAAU;AACvB,iBAAW,SAAS,MAAM;AAAA,IAC5B;AAEA,UAAM,aAAa,OAAO,GAAY,SAA8B;AAClE,YAAM,QAAQ,YAAY,GAAG,WAAW,IAAI;AAC5C,YAAM,QAAQ,YAAY,GAAG,WAAW,IAAI;AAC5C,YAAM,UAAU,kBAAkB,CAAC;AACnC,YAAM,WAAW,QAAQ,GAAG,MAAM,EAAE,QAAQ,OAAO,OAAO,QAAQ,CAAC;AAAA,IACrE;AAEA,UAAM,UAAU,SAAS,OAAO,MAAM,UAAU;AAIhD,QAAI;AACJ,QAAI,WAAW,UAAU;AACvB,YAAM,UAAU,WAAW;AAC3B,iBAAW;AAAA,QACT,WAAW,QAAQ,YACf,CAAC,OAAoB,QACnB,QAAQ,UAAW,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAC9C;AAAA,QACJ,YAAY,QAAQ,aAChB,CAAC,OAAoB,QACnB,QAAQ,WAAY,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAC/C;AAAA,MACN;AAAA,IACF;AAEA,WAAO;AAAA,MACL,MAAM,WAAW;AAAA,MACjB,UAAU,WAAW,YAAY,SAAS;AAAA,MAC1C;AAAA,MACA;AAAA,MACA,QAAQ,WAAW;AAAA,MACnB,UAAU,WAAW;AAAA,IACvB;AAAA,EACF;AACF;","names":[]}

package/dist/policies/sdk/helpers.d.ts

@@ -0,0 +1,132 @@
+import { Context, MiddlewareHandler } from 'hono';
+import { DebugLogger } from '@vivero/stoma-core';
+
+/**
+ * Composable helpers for policy authors.
+ *
+ * Utilities that eliminate the most common boilerplate:
+ * - {@link resolveConfig} - merge defaults with user config
+ * - {@link policyDebug} - get a pre-namespaced debug logger
+ * - {@link withSkip} - wrap a handler with `PolicyConfig.skip` logic
+ * - {@link safeCall} - graceful store failure degradation
+ * - {@link setDebugHeader} - contribute debug data for client-requested debug headers
+ *
+ * @module helpers
+ */
+
+/**
+ * Merge default config values with user-provided config.
+ *
+ * Performs a shallow merge: `{ ...defaults, ...userConfig }`.
+ * Explicit `undefined` values in userConfig override defaults.
+ *
+ * @param defaults - Default values for all optional config fields.
+ * @param userConfig - User-provided config (may be undefined).
+ * @returns Fully merged config typed as `TConfig`.
+ */
+declare function resolveConfig<TConfig>(defaults: Partial<TConfig>, userConfig?: Partial<TConfig>): TConfig;
+/**
+ * Get a debug logger pre-namespaced to `stoma:policy:{name}`.
+ *
+ * Returns {@link noopDebugLogger} when there is no gateway context
+ * (e.g. outside a gateway pipeline) or when debug is disabled.
+ * This eliminates the repeated `getGatewayContext(c)?.debug(...)` pattern.
+ *
+ * @param c - Hono request context.
+ * @param policyName - Policy name used in the namespace.
+ * @returns A {@link DebugLogger} - always callable, never undefined.
+ */
+declare function policyDebug(c: Context, policyName: string): DebugLogger;
+/**
+ * Wrap a middleware handler with skip logic.
+ *
+ * If `skipFn` is undefined, returns the original handler unchanged
+ * (zero overhead). Otherwise wraps it: when `skipFn(c)` returns `true`,
+ * calls `next()` without running the handler.
+ *
+ * This implements the `PolicyConfig.skip` feature that was defined in
+ * types but never enforced at runtime.
+ *
+ * @param skipFn - Optional predicate from `PolicyConfig.skip`.
+ * @param handler - The policy's middleware handler.
+ * @returns The original handler or a skip-aware wrapper.
+ */
+declare function withSkip(skipFn: ((c: unknown) => boolean | Promise<boolean>) | undefined, handler: MiddlewareHandler): MiddlewareHandler;
+/**
+ * Execute an async operation with graceful error handling.
+ *
+ * Designed for store-backed policies (cache, rate-limit, circuit-breaker)
+ * where a store failure should degrade gracefully - not crash the request.
+ * Returns the `fallback` value if `fn` throws.
+ *
+ * @param fn - The async operation to attempt.
+ * @param fallback - Value to return if `fn` throws.
+ * @param debug - Optional debug logger for error reporting.
+ * @param label - Optional label for the debug message (e.g. `"store.get()"`).
+ * @returns The result of `fn`, or `fallback` on error.
+ *
+ * @example
+ * ```ts
+ * const cached = await safeCall(
+ *   () => store.get(key),
+ *   null,
+ *   debug,
+ *   "store.get()",
+ * );
+ * ```
+ */
+declare function safeCall<T>(fn: () => Promise<T>, fallback: T, debug?: DebugLogger, label?: string): Promise<T>;
+/**
+ * Set a debug header value for client-requested debug output.
+ *
+ * Policies call this to contribute debug data. The value is only stored
+ * if the client requested it via the `x-stoma-debug` request header AND
+ * the gateway has debug headers enabled. When neither condition is met,
+ * this is a no-op (single Map lookup).
+ *
+ * @param c - Hono request context.
+ * @param name - Header name (e.g. `"x-stoma-cache-key"`).
+ * @param value - Header value. Numbers and booleans are stringified.
+ *
+ * @example
+ * ```ts
+ * setDebugHeader(c, "x-stoma-cache-key", key);
+ * setDebugHeader(c, "x-stoma-cache-ttl", resolved.ttlSeconds);
+ * ```
+ */
+declare function setDebugHeader(c: Context, name: string, value: string | number | boolean): void;
+/**
+ * Parse the client's debug header request and store the requested set.
+ *
+ * Called by the pipeline's context injector when `debugHeaders` is enabled.
+ * Parses the comma-separated request header and stores a Set of requested
+ * header names on the Hono context.
+ *
+ * @param c - Hono request context.
+ * @param requestHeaderName - The request header to read (default: `"x-stoma-debug"`).
+ * @param allow - Optional allowlist. When set, only these header names are permitted.
+ * @internal
+ */
+declare function parseDebugRequest(c: Context, requestHeaderName: string, allow?: string[]): void;
+/**
+ * Read all collected debug headers for emission on the response.
+ *
+ * Called by the pipeline's context injector after all policies have run.
+ *
+ * @param c - Hono request context.
+ * @returns Map of header name → value, or undefined if none collected.
+ * @internal
+ */
+declare function getCollectedDebugHeaders(c: Context): Map<string, string> | undefined;
+/**
+ * Check whether the client requested debug output via the `x-stoma-debug` header.
+ *
+ * Returns `true` when any debug header names were requested (i.e. the
+ * `_stomaDebugRequested` context key is a non-empty Set).
+ *
+ * @param c - Hono request context.
+ * @returns `true` if the client sent a valid `x-stoma-debug` request header.
+ */
+declare function isDebugRequested(c: Context): boolean;
+
+export { getCollectedDebugHeaders, isDebugRequested, parseDebugRequest, policyDebug, resolveConfig, safeCall, setDebugHeader, withSkip };

package/dist/policies/sdk/helpers.js

@@ -0,0 +1,87 @@
+import { getGatewayContext } from "../../core/pipeline";
+import { noopDebugLogger } from "../../utils/debug";
+import { TRACE_REQUESTED_KEY } from "./trace";
+function resolveConfig(defaults, userConfig) {
+  if (!userConfig) return { ...defaults };
+  return { ...defaults, ...userConfig };
+}
+function policyDebug(c, policyName) {
+  return getGatewayContext(c)?.debug(`stoma:policy:${policyName}`) ?? noopDebugLogger;
+}
+function withSkip(skipFn, handler) {
+  if (!skipFn) return handler;
+  return async (c, next) => {
+    const shouldSkip = await skipFn(c);
+    if (shouldSkip) {
+      await next();
+      return;
+    }
+    await handler(c, next);
+  };
+}
+async function safeCall(fn, fallback, debug, label) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (debug && label) {
+      debug(
+        `${label} failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return fallback;
+  }
+}
+const DEBUG_HEADERS_KEY = "_stomaDebugHeaders";
+const DEBUG_REQUESTED_KEY = "_stomaDebugRequested";
+function setDebugHeader(c, name, value) {
+  const requested = c.get(DEBUG_REQUESTED_KEY);
+  if (!requested || !(requested.has(name) || requested.has("*"))) return;
+  const headers = c.get(DEBUG_HEADERS_KEY) ?? /* @__PURE__ */ new Map();
+  headers.set(name, String(value));
+  c.set(DEBUG_HEADERS_KEY, headers);
+}
+function parseDebugRequest(c, requestHeaderName, allow) {
+  const raw = c.req.header(requestHeaderName);
+  if (!raw) return;
+  const names = raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (names.length === 0) return;
+  const allowSet = allow ? new Set(allow.map((a) => a.toLowerCase())) : null;
+  const requested = /* @__PURE__ */ new Set();
+  if (names.includes("*")) {
+    if (allowSet) {
+      for (const a of allowSet) requested.add(a);
+    } else {
+      requested.add("*");
+    }
+  }
+  for (const name of names) {
+    if (name === "*") continue;
+    if (!allowSet || allowSet.has(name)) {
+      requested.add(name);
+    }
+  }
+  if (requested.size > 0) {
+    c.set(DEBUG_REQUESTED_KEY, requested);
+  }
+  if (requested.has("trace") || requested.has("*")) {
+    c.set(TRACE_REQUESTED_KEY, true);
+  }
+}
+function getCollectedDebugHeaders(c) {
+  return c.get(DEBUG_HEADERS_KEY);
+}
+function isDebugRequested(c) {
+  const requested = c.get(DEBUG_REQUESTED_KEY);
+  return requested !== void 0 && requested.size > 0;
+}
+export {
+  getCollectedDebugHeaders,
+  isDebugRequested,
+  parseDebugRequest,
+  policyDebug,
+  resolveConfig,
+  safeCall,
+  setDebugHeader,
+  withSkip
+};
+//# sourceMappingURL=helpers.js.map

package/dist/policies/sdk/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/sdk/helpers.ts"],"sourcesContent":["/**\n * Composable helpers for policy authors.\n *\n * Utilities that eliminate the most common boilerplate:\n * - {@link resolveConfig} - merge defaults with user config\n * - {@link policyDebug} - get a pre-namespaced debug logger\n * - {@link withSkip} - wrap a handler with `PolicyConfig.skip` logic\n * - {@link safeCall} - graceful store failure degradation\n * - {@link setDebugHeader} - contribute debug data for client-requested debug headers\n *\n * @module helpers\n */\nimport type { Context, MiddlewareHandler, Next } from \"hono\";\nimport { getGatewayContext } from \"../../core/pipeline\";\nimport type { DebugLogger } from \"../../utils/debug\";\nimport { noopDebugLogger } from \"../../utils/debug\";\nimport { TRACE_REQUESTED_KEY } from \"./trace\";\n\n/**\n * Merge default config values with user-provided config.\n *\n * Performs a shallow merge: `{ ...defaults, ...userConfig }`.\n * Explicit `undefined` values in userConfig override defaults.\n *\n * @param defaults - Default values for all optional config fields.\n * @param userConfig - User-provided config (may be undefined).\n * @returns Fully merged config typed as `TConfig`.\n */\nexport function resolveConfig<TConfig>(\n  defaults: Partial<TConfig>,\n  userConfig?: Partial<TConfig>\n): TConfig {\n  if (!userConfig) return { ...defaults } as TConfig;\n  return { ...defaults, ...userConfig } as TConfig;\n}\n\n/**\n * Get a debug logger pre-namespaced to `stoma:policy:{name}`.\n *\n * Returns {@link noopDebugLogger} when there is no gateway context\n * (e.g. outside a gateway pipeline) or when debug is disabled.\n * This eliminates the repeated `getGatewayContext(c)?.debug(...)` pattern.\n *\n * @param c - Hono request context.\n * @param policyName - Policy name used in the namespace.\n * @returns A {@link DebugLogger} - always callable, never undefined.\n */\nexport function policyDebug(c: Context, policyName: string): DebugLogger {\n  return (\n    getGatewayContext(c)?.debug(`stoma:policy:${policyName}`) ?? noopDebugLogger\n  );\n}\n\n/**\n * Wrap a middleware handler with skip logic.\n *\n * If `skipFn` is undefined, returns the original handler unchanged\n * (zero overhead). Otherwise wraps it: when `skipFn(c)` returns `true`,\n * calls `next()` without running the handler.\n *\n * This implements the `PolicyConfig.skip` feature that was defined in\n * types but never enforced at runtime.\n *\n * @param skipFn - Optional predicate from `PolicyConfig.skip`.\n * @param handler - The policy's middleware handler.\n * @returns The original handler or a skip-aware wrapper.\n */\nexport function withSkip(\n  skipFn: ((c: unknown) => boolean | Promise<boolean>) | undefined,\n  handler: MiddlewareHandler\n): MiddlewareHandler {\n  if (!skipFn) return handler;\n\n  return async (c: Context, next: Next) => {\n    const shouldSkip = await skipFn(c);\n    if (shouldSkip) {\n      await next();\n      return;\n    }\n    await handler(c, next);\n  };\n}\n\n/**\n * Execute an async operation with graceful error handling.\n *\n * Designed for store-backed policies (cache, rate-limit, circuit-breaker)\n * where a store failure should degrade gracefully - not crash the request.\n * Returns the `fallback` value if `fn` throws.\n *\n * @param fn - The async operation to attempt.\n * @param fallback - Value to return if `fn` throws.\n * @param debug - Optional debug logger for error reporting.\n * @param label - Optional label for the debug message (e.g. `\"store.get()\"`).\n * @returns The result of `fn`, or `fallback` on error.\n *\n * @example\n * ```ts\n * const cached = await safeCall(\n *   () => store.get(key),\n *   null,\n *   debug,\n *   \"store.get()\",\n * );\n * ```\n */\nexport async function safeCall<T>(\n  fn: () => Promise<T>,\n  fallback: T,\n  debug?: DebugLogger,\n  label?: string\n): Promise<T> {\n  try {\n    return await fn();\n  } catch (err) {\n    if (debug && label) {\n      debug(\n        `${label} failed: ${err instanceof Error ? err.message : String(err)}`\n      );\n    }\n    return fallback;\n  }\n}\n\n// --- Debug headers ---\n\nconst DEBUG_HEADERS_KEY = \"_stomaDebugHeaders\";\nconst DEBUG_REQUESTED_KEY = \"_stomaDebugRequested\";\n\n/**\n * Set a debug header value for client-requested debug output.\n *\n * Policies call this to contribute debug data. The value is only stored\n * if the client requested it via the `x-stoma-debug` request header AND\n * the gateway has debug headers enabled. When neither condition is met,\n * this is a no-op (single Map lookup).\n *\n * @param c - Hono request context.\n * @param name - Header name (e.g. `\"x-stoma-cache-key\"`).\n * @param value - Header value. Numbers and booleans are stringified.\n *\n * @example\n * ```ts\n * setDebugHeader(c, \"x-stoma-cache-key\", key);\n * setDebugHeader(c, \"x-stoma-cache-ttl\", resolved.ttlSeconds);\n * ```\n */\nexport function setDebugHeader(\n  c: Context,\n  name: string,\n  value: string | number | boolean\n): void {\n  const requested = c.get(DEBUG_REQUESTED_KEY) as Set<string> | undefined;\n  if (!requested || !(requested.has(name) || requested.has(\"*\"))) return;\n\n  const headers = (c.get(DEBUG_HEADERS_KEY) ??\n    new Map<string, string>()) as Map<string, string>;\n  headers.set(name, String(value));\n  c.set(DEBUG_HEADERS_KEY, headers);\n}\n\n/**\n * Parse the client's debug header request and store the requested set.\n *\n * Called by the pipeline's context injector when `debugHeaders` is enabled.\n * Parses the comma-separated request header and stores a Set of requested\n * header names on the Hono context.\n *\n * @param c - Hono request context.\n * @param requestHeaderName - The request header to read (default: `\"x-stoma-debug\"`).\n * @param allow - Optional allowlist. When set, only these header names are permitted.\n * @internal\n */\nexport function parseDebugRequest(\n  c: Context,\n  requestHeaderName: string,\n  allow?: string[]\n): void {\n  const raw = c.req.header(requestHeaderName);\n  if (!raw) return;\n\n  const names = raw\n    .split(\",\")\n    .map((s) => s.trim().toLowerCase())\n    .filter(Boolean);\n  if (names.length === 0) return;\n\n  const allowSet = allow ? new Set(allow.map((a) => a.toLowerCase())) : null;\n  const requested = new Set<string>();\n\n  // Wildcard: \"*\" means \"all debug headers\". When an allowlist is configured,\n  // expand to all allowed names. Without an allowlist, store the \"*\" sentinel\n  // which setDebugHeader() checks for.\n  if (names.includes(\"*\")) {\n    if (allowSet) {\n      for (const a of allowSet) requested.add(a);\n    } else {\n      requested.add(\"*\");\n    }\n  }\n\n  for (const name of names) {\n    if (name === \"*\") continue;\n    if (!allowSet || allowSet.has(name)) {\n      requested.add(name);\n    }\n  }\n\n  if (requested.size > 0) {\n    c.set(DEBUG_REQUESTED_KEY, requested);\n  }\n\n  // Activate tracing when \"trace\" is explicitly requested or \"*\" wildcard is used.\n  // Respects the allowlist - if an allowlist exists and \"trace\" isn't in it, tracing is blocked.\n  if (requested.has(\"trace\") || requested.has(\"*\")) {\n    c.set(TRACE_REQUESTED_KEY, true);\n  }\n}\n\n/**\n * Read all collected debug headers for emission on the response.\n *\n * Called by the pipeline's context injector after all policies have run.\n *\n * @param c - Hono request context.\n * @returns Map of header name → value, or undefined if none collected.\n * @internal\n */\nexport function getCollectedDebugHeaders(\n  c: Context\n): Map<string, string> | undefined {\n  return c.get(DEBUG_HEADERS_KEY) as Map<string, string> | undefined;\n}\n\n/**\n * Check whether the client requested debug output via the `x-stoma-debug` header.\n *\n * Returns `true` when any debug header names were requested (i.e. the\n * `_stomaDebugRequested` context key is a non-empty Set).\n *\n * @param c - Hono request context.\n * @returns `true` if the client sent a valid `x-stoma-debug` request header.\n */\nexport function isDebugRequested(c: Context): boolean {\n  const requested = c.get(DEBUG_REQUESTED_KEY) as Set<string> | undefined;\n  return requested !== undefined && requested.size > 0;\n}\n"],"mappings":"AAaA,SAAS,yBAAyB;AAElC,SAAS,uBAAuB;AAChC,SAAS,2BAA2B;AAY7B,SAAS,cACd,UACA,YACS;AACT,MAAI,CAAC,WAAY,QAAO,EAAE,GAAG,SAAS;AACtC,SAAO,EAAE,GAAG,UAAU,GAAG,WAAW;AACtC;AAaO,SAAS,YAAY,GAAY,YAAiC;AACvE,SACE,kBAAkB,CAAC,GAAG,MAAM,gBAAgB,UAAU,EAAE,KAAK;AAEjE;AAgBO,SAAS,SACd,QACA,SACmB;AACnB,MAAI,CAAC,OAAQ,QAAO;AAEpB,SAAO,OAAO,GAAY,SAAe;AACvC,UAAM,aAAa,MAAM,OAAO,CAAC;AACjC,QAAI,YAAY;AACd,YAAM,KAAK;AACX;AAAA,IACF;AACA,UAAM,QAAQ,GAAG,IAAI;AAAA,EACvB;AACF;AAyBA,eAAsB,SACpB,IACA,UACA,OACA,OACY;AACZ,MAAI;AACF,WAAO,MAAM,GAAG;AAAA,EAClB,SAAS,KAAK;AACZ,QAAI,SAAS,OAAO;AAClB;AAAA,QACE,GAAG,KAAK,YAAY,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,MACtE;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACF;AAIA,MAAM,oBAAoB;AAC1B,MAAM,sBAAsB;AAoBrB,SAAS,eACd,GACA,MACA,OACM;AACN,QAAM,YAAY,EAAE,IAAI,mBAAmB;AAC3C,MAAI,CAAC,aAAa,EAAE,UAAU,IAAI,IAAI,KAAK,UAAU,IAAI,GAAG,GAAI;AAEhE,QAAM,UAAW,EAAE,IAAI,iBAAiB,KACtC,oBAAI,IAAoB;AAC1B,UAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAC/B,IAAE,IAAI,mBAAmB,OAAO;AAClC;AAcO,SAAS,kBACd,GACA,mBACA,OACM;AACN,QAAM,MAAM,EAAE,IAAI,OAAO,iBAAiB;AAC1C,MAAI,CAAC,IAAK;AAEV,QAAM,QAAQ,IACX,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,EACjC,OAAO,OAAO;AACjB,MAAI,MAAM,WAAW,EAAG;AAExB,QAAM,WAAW,QAAQ,IAAI,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,IAAI;AACtE,QAAM,YAAY,oBAAI,IAAY;AAKlC,MAAI,MAAM,SAAS,GAAG,GAAG;AACvB,QAAI,UAAU;AACZ,iBAAW,KAAK,SAAU,WAAU,IAAI,CAAC;AAAA,IAC3C,OAAO;AACL,gBAAU,IAAI,GAAG;AAAA,IACnB;AAAA,EACF;AAEA,aAAW,QAAQ,OAAO;AACxB,QAAI,SAAS,IAAK;AAClB,QAAI,CAAC,YAAY,SAAS,IAAI,IAAI,GAAG;AACnC,gBAAU,IAAI,IAAI;AAAA,IACpB;AAAA,EACF;AAEA,MAAI,UAAU,OAAO,GAAG;AACtB,MAAE,IAAI,qBAAqB,SAAS;AAAA,EACtC;AAIA,MAAI,UAAU,IAAI,OAAO,KAAK,UAAU,IAAI,GAAG,GAAG;AAChD,MAAE,IAAI,qBAAqB,IAAI;AAAA,EACjC;AACF;AAWO,SAAS,yBACd,GACiC;AACjC,SAAO,EAAE,IAAI,iBAAiB;AAChC;AAWO,SAAS,iBAAiB,GAAqB;AACpD,QAAM,YAAY,EAAE,IAAI,mBAAmB;AAC3C,SAAO,cAAc,UAAa,UAAU,OAAO;AACrD;","names":[]}

package/dist/policies/sdk/index.d.ts

@@ -0,0 +1,10 @@
+export { Priority, PriorityLevel } from './priority.js';
+export { getCollectedDebugHeaders, isDebugRequested, parseDebugRequest, policyDebug, resolveConfig, safeCall, setDebugHeader, withSkip } from './helpers.js';
+export { PolicyDefinition, PolicyEvalHandlerContext, PolicyFactory, PolicyHandlerContext, definePolicy } from './define-policy.js';
+export { PolicyTestHarnessOptions, createPolicyTestHarness } from './testing.js';
+export { PolicyTrace, PolicyTraceDetail, PolicyTraceEntry, TraceReporter, isTraceRequested, noopTraceReporter, policyTrace } from './trace.js';
+import 'hono';
+import '@vivero/stoma-core';
+import '../../protocol-2fD3DJrL.js';
+import 'hono/types';
+import '../../adapters/testing.js';

package/dist/policies/sdk/index.js

@@ -0,0 +1,35 @@
+import { Priority } from "./priority";
+import {
+  getCollectedDebugHeaders,
+  isDebugRequested,
+  parseDebugRequest,
+  policyDebug,
+  resolveConfig,
+  safeCall,
+  setDebugHeader,
+  withSkip
+} from "./helpers";
+import { definePolicy } from "./define-policy";
+import { createPolicyTestHarness } from "./testing";
+import {
+  isTraceRequested,
+  noopTraceReporter,
+  policyTrace
+} from "./trace";
+export {
+  Priority,
+  createPolicyTestHarness,
+  definePolicy,
+  getCollectedDebugHeaders,
+  isDebugRequested,
+  isTraceRequested,
+  noopTraceReporter,
+  parseDebugRequest,
+  policyDebug,
+  policyTrace,
+  resolveConfig,
+  safeCall,
+  setDebugHeader,
+  withSkip
+};
+//# sourceMappingURL=index.js.map

package/dist/policies/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/sdk/index.ts"],"sourcesContent":["/**\n * Policy SDK - shared primitives for building built-in and custom policies.\n *\n * Four layers of increasing convenience:\n *\n * 1. **Priority** - Named constants for policy ordering (lower = earlier).\n * 2. **Composable helpers** - `resolveConfig`, `policyDebug`, `withSkip` for eliminating boilerplate.\n * 3. **definePolicy** - Full convenience wrapper combining all helpers into a declarative API.\n * 4. **Testing** - `createPolicyTestHarness` for zero-boilerplate policy unit tests.\n *\n * @example\n * ```ts\n * import { definePolicy, Priority } from \"@vivero/stoma\";\n *\n * const myPolicy = definePolicy<MyConfig>({\n *   name: \"my-policy\",\n *   priority: Priority.AUTH,\n *   defaults: { headerName: \"x-custom\" },\n *   handler: async (c, next, { config, debug }) => {\n *     debug(\"checking header\");\n *     // ... policy logic ...\n *     await next();\n *   },\n * });\n * ```\n *\n * @module sdk\n */\n\n// Layer 1 - Priority constants\n\n/** Union of all named priority level values. */\nexport type { PriorityLevel } from \"./priority\";\n/** Named priority constants (OBSERVABILITY, AUTH, RATE_LIMIT, etc.) for policy ordering. */\nexport { Priority } from \"./priority\";\n\n// Layer 2 - Composable helpers\n\n/** Shallow-merge default config values with user-provided config. */\nexport {\n  /** Read all collected debug headers (internal - used by the pipeline). */\n  getCollectedDebugHeaders,\n  /** Check whether the client requested debug output via the `x-stoma-debug` header. */\n  isDebugRequested,\n  /** Parse the client's debug header request (internal - used by the pipeline). */\n  parseDebugRequest,\n  /** Get a debug logger pre-namespaced to `stoma:policy:{name}` from the gateway context. */\n  policyDebug,\n  resolveConfig,\n  /** Execute an async operation with graceful error handling - returns a fallback value on failure. */\n  safeCall,\n  /** Set a debug header value for client-requested debug output. */\n  setDebugHeader,\n  /** Wrap a middleware handler with `PolicyConfig.skip` conditional bypass logic. */\n  withSkip,\n} from \"./helpers\";\n\n// Layer 3 - Full convenience wrapper\n\n/** Declarative policy definition passed to {@link definePolicy}. */\nexport type {\n  PolicyDefinition,\n  /** Context injected into `definePolicy` evaluate handlers (protocol-agnostic, with typed config). */\n  PolicyEvalHandlerContext,\n  /** Conditional factory type - config required when TConfig has required keys. */\n  PolicyFactory,\n  /** Context injected into `definePolicy` handlers: merged config, debug logger, and gateway context. */\n  PolicyHandlerContext,\n} from \"./define-policy\";\n/** Create a policy factory from a declarative definition - combines resolveConfig, policyDebug, and withSkip. */\nexport { definePolicy } from \"./define-policy\";\n\n// Layer 4 - Testing utility\n\n/** Options for {@link createPolicyTestHarness}: custom upstream, path, gateway name, adapter. */\nexport type { PolicyTestHarnessOptions } from \"./testing\";\n/** Create a minimal test harness for a policy with error handling, context injection, and configurable upstream. */\nexport { createPolicyTestHarness } from \"./testing\";\n\n// Layer 5 - Trace (deep policy debugging)\n\nexport type {\n  /** Full trace payload emitted as `x-stoma-trace`. */\n  PolicyTrace,\n  /** Policy-reported detail (cooperative opt-in). */\n  PolicyTraceDetail,\n  /** Combined baseline + detail for a single policy trace entry. */\n  PolicyTraceEntry,\n  /** A trace reporter function: `(action, data?) => void`. */\n  TraceReporter,\n} from \"./trace\";\n/** Get a trace reporter for a specific policy - always callable, no-op when not tracing. */\nexport {\n  /** Fast-path check: is tracing requested for this request? */\n  isTraceRequested,\n  /** Shared no-op trace reporter instance. */\n  noopTraceReporter,\n  policyTrace,\n} from \"./trace\";\n"],"mappings":"AAkCA,SAAS,gBAAgB;AAKzB;AAAA,EAEE;AAAA,EAEA;AAAA,EAEA;AAAA,EAEA;AAAA,EACA;AAAA,EAEA;AAAA,EAEA;AAAA,EAEA;AAAA,OACK;AAeP,SAAS,oBAAoB;AAO7B,SAAS,+BAA+B;AAexC;AAAA,EAEE;AAAA,EAEA;AAAA,EACA;AAAA,OACK;","names":[]}

package/dist/policies/sdk/priority.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Named priority constants for policy ordering.
+ *
+ * Lower numbers execute first. These replace magic numbers throughout
+ * the built-in policies and are exported for custom policy authors.
+ *
+ * @module priority
+ */
+declare const Priority: {
+    /** Observability policies (e.g. requestLog) - wraps everything */
+    readonly OBSERVABILITY: 0;
+    /** IP filtering - runs before all other logic */
+    readonly IP_FILTER: 1;
+    /** Metrics collection - just after observability */
+    readonly METRICS: 1;
+    /** Early pipeline (e.g. cors) - before auth */
+    readonly EARLY: 5;
+    /** Authentication (e.g. jwtAuth, apiKeyAuth, basicAuth) */
+    readonly AUTH: 10;
+    /** Rate limiting - after auth */
+    readonly RATE_LIMIT: 20;
+    /** Circuit breaker - protects upstream */
+    readonly CIRCUIT_BREAKER: 30;
+    /** Caching - before upstream */
+    readonly CACHE: 40;
+    /** Request header transforms - mid-pipeline */
+    readonly REQUEST_TRANSFORM: 50;
+    /** Timeout - wraps upstream call */
+    readonly TIMEOUT: 85;
+    /** Retry - wraps upstream fetch */
+    readonly RETRY: 90;
+    /** Response header transforms - after upstream */
+    readonly RESPONSE_TRANSFORM: 92;
+    /** Proxy header manipulation - just before upstream */
+    readonly PROXY: 95;
+    /** Default priority for unspecified policies */
+    readonly DEFAULT: 100;
+    /** Mock - terminal, replaces upstream */
+    readonly MOCK: 999;
+};
+/** Union of all named priority levels. */
+type PriorityLevel = (typeof Priority)[keyof typeof Priority];
+
+export { Priority, type PriorityLevel };

package/dist/policies/sdk/priority.js

@@ -0,0 +1,36 @@
+const Priority = {
+  /** Observability policies (e.g. requestLog) - wraps everything */
+  OBSERVABILITY: 0,
+  /** IP filtering - runs before all other logic */
+  IP_FILTER: 1,
+  /** Metrics collection - just after observability */
+  METRICS: 1,
+  /** Early pipeline (e.g. cors) - before auth */
+  EARLY: 5,
+  /** Authentication (e.g. jwtAuth, apiKeyAuth, basicAuth) */
+  AUTH: 10,
+  /** Rate limiting - after auth */
+  RATE_LIMIT: 20,
+  /** Circuit breaker - protects upstream */
+  CIRCUIT_BREAKER: 30,
+  /** Caching - before upstream */
+  CACHE: 40,
+  /** Request header transforms - mid-pipeline */
+  REQUEST_TRANSFORM: 50,
+  /** Timeout - wraps upstream call */
+  TIMEOUT: 85,
+  /** Retry - wraps upstream fetch */
+  RETRY: 90,
+  /** Response header transforms - after upstream */
+  RESPONSE_TRANSFORM: 92,
+  /** Proxy header manipulation - just before upstream */
+  PROXY: 95,
+  /** Default priority for unspecified policies */
+  DEFAULT: 100,
+  /** Mock - terminal, replaces upstream */
+  MOCK: 999
+};
+export {
+  Priority
+};
+//# sourceMappingURL=priority.js.map

package/dist/policies/sdk/priority.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/sdk/priority.ts"],"sourcesContent":["/**\n * Named priority constants for policy ordering.\n *\n * Lower numbers execute first. These replace magic numbers throughout\n * the built-in policies and are exported for custom policy authors.\n *\n * @module priority\n */\n\nexport const Priority = {\n  /** Observability policies (e.g. requestLog) - wraps everything */\n  OBSERVABILITY: 0,\n  /** IP filtering - runs before all other logic */\n  IP_FILTER: 1,\n  /** Metrics collection - just after observability */\n  METRICS: 1,\n  /** Early pipeline (e.g. cors) - before auth */\n  EARLY: 5,\n  /** Authentication (e.g. jwtAuth, apiKeyAuth, basicAuth) */\n  AUTH: 10,\n  /** Rate limiting - after auth */\n  RATE_LIMIT: 20,\n  /** Circuit breaker - protects upstream */\n  CIRCUIT_BREAKER: 30,\n  /** Caching - before upstream */\n  CACHE: 40,\n  /** Request header transforms - mid-pipeline */\n  REQUEST_TRANSFORM: 50,\n  /** Timeout - wraps upstream call */\n  TIMEOUT: 85,\n  /** Retry - wraps upstream fetch */\n  RETRY: 90,\n  /** Response header transforms - after upstream */\n  RESPONSE_TRANSFORM: 92,\n  /** Proxy header manipulation - just before upstream */\n  PROXY: 95,\n  /** Default priority for unspecified policies */\n  DEFAULT: 100,\n  /** Mock - terminal, replaces upstream */\n  MOCK: 999,\n} as const;\n\n/** Union of all named priority levels. */\nexport type PriorityLevel = (typeof Priority)[keyof typeof Priority];\n"],"mappings":"AASO,MAAM,WAAW;AAAA;AAAA,EAEtB,eAAe;AAAA;AAAA,EAEf,WAAW;AAAA;AAAA,EAEX,SAAS;AAAA;AAAA,EAET,OAAO;AAAA;AAAA,EAEP,MAAM;AAAA;AAAA,EAEN,YAAY;AAAA;AAAA,EAEZ,iBAAiB;AAAA;AAAA,EAEjB,OAAO;AAAA;AAAA,EAEP,mBAAmB;AAAA;AAAA,EAEnB,SAAS;AAAA;AAAA,EAET,OAAO;AAAA;AAAA,EAEP,oBAAoB;AAAA;AAAA,EAEpB,OAAO;AAAA;AAAA,EAEP,SAAS;AAAA;AAAA,EAET,MAAM;AACR;","names":[]}