@fabricorg/policy-opa 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -25,6 +25,58 @@ interface OpaPolicyBinding {
      * keep the package name aligned with the decision path.
      */
     regoPackage?: string;
+    /**
+     * Optional selector for `bundleRevision` extraction when OPA's
+     * `provenance.bundles` carries multiple bundles. If absent and OPA reports
+     * a single bundle, the adapter uses that revision unambiguously. If absent
+     * and multiple bundles are present, the adapter marks the evidence with
+     * `bundleRevisionStatus: "ambiguous"` so audit dashboards can flag policies
+     * that need explicit selectors.
+     *
+     * Example: `"lending"` for a bundle named `lending` served by OPA.
+     */
+    bundleName?: string;
+}
+/**
+ * Result of one OPA evaluation, normalized for the adapter. Returned by
+ * implementations of {@link OpaPolicyExecutor}. The adapter accepts either a
+ * client (with `evaluate`) or an executor (with `execute`); the executor path
+ * preserves provenance OPA exposes via `?provenance=true` — primarily
+ * `decision_id` and `provenance.bundles[*].revision`.
+ */
+interface OpaPolicyExecution {
+    /** The raw decision body — the value of `result` in OPA's response. */
+    decision: unknown;
+    /** OPA's per-request decision ID (response field `decision_id`). */
+    decisionId?: string;
+    /**
+     * Pre-selected bundle revision, when the executor can determine it
+     * unambiguously without binding context (e.g. a transport that only ever
+     * sees a single bundle). The factory may override this from
+     * `provenance.bundles` + `binding.bundleName`.
+     */
+    bundleRevision?: string;
+    /** OPA server version (response field `provenance.version`). */
+    opaVersion?: string;
+    /**
+     * Raw `provenance` block from the OPA response. Carries
+     * `bundles: { [name]: { revision } }`, build info, etc. The factory uses
+     * this together with `binding.bundleName` to select `bundleRevision`.
+     */
+    provenance?: Record<string, unknown>;
+}
+/**
+ * Rich execution interface. Implementations are responsible for talking to
+ * OPA and surfacing provenance. Two official implementations ship in this
+ * package: {@link executorFromOpaClient} (wraps the high-level SDK; limited
+ * provenance) and {@link executorFromOpaHttp} (calls OPA REST directly with
+ * `?provenance=true`; full provenance).
+ *
+ * Hosts wire one of these into `ctx.services[serviceKey]` as an alternative
+ * to {@link OpaPolicyClient}.
+ */
+interface OpaPolicyExecutor {
+    execute(path: string, input: unknown): Promise<OpaPolicyExecution>;
 }
 /**
  * Structured Rego decision shape — the "house style" the adapter expects from
@@ -60,7 +112,18 @@ type OpaPolicyErrorMode = "block" | "throw";
  * something we couldn't parse" from "no client was injected at runtime".
  */
 type OpaPolicyFailureKind = "client_unavailable" | "input_build_failed" | "evaluation_failed" | "invalid_response";
-type OpaPolicyDecisionMapper<TDb = unknown> = (decision: OpaDecision, ctx: PolicyContext<TDb>) => Pick<PolicyOutcome, "result" | "reason"> & {
+/**
+ * Maps a validated `OpaDecision` to the fields of a `PolicyOutcome` the
+ * adapter consumes (`result`, `reason`, optional extra `metadata`). The
+ * optional third argument, `execution`, exposes OPA-side provenance
+ * (`decisionId`, `bundleRevision`, raw `provenance`) so a mapper can lift
+ * specific fields into `outcome.metadata` if the host wants them queryable
+ * outside `dispatchEvidence.engine`.
+ *
+ * Existing two-argument mappers (`(decision, ctx) => …`) remain valid —
+ * TypeScript permits implementations with fewer parameters.
+ */
+type OpaPolicyDecisionMapper<TDb = unknown> = (decision: OpaDecision, ctx: PolicyContext<TDb>, execution: OpaPolicyExecution) => Partial<PolicyOutcome> & {
     metadata?: Record<string, unknown>;
 };
 interface CreateOpaPolicyEvaluatorOptions<TDb = unknown> {
@@ -111,20 +174,39 @@ interface CreateOpaPolicyEvaluatorOptions<TDb = unknown> {
 
 /**
  * Build a Fabric `PolicyEvaluator` that delegates decision-making to an OPA
- * (Open Policy Agent) deployment. The evaluator:
+ * (Open Policy Agent) deployment.
+ *
+ * The adapter accepts either of two service shapes under
+ * `ctx.services[serviceKey]`:
  *
- * 1. Reads the host-injected OPA client from `ctx.services[serviceKey]`.
+ * - `OpaPolicyExecutor` (preferred) — `execute(path, input)` returning a rich
+ *   `OpaPolicyExecution` (decision plus `decisionId`, `bundleRevision`,
+ *   `opaVersion`, `provenance`). Ship one with {@link executorFromOpaHttp} or
+ *   {@link executorFromOpaClient}.
+ * - `OpaPolicyClient` — `evaluate(path, input)` returning the raw decision
+ *   only. Compatible with the high-level `@open-policy-agent/opa` SDK at the
+ *   cost of OPA-side provenance.
+ *
+ * If both methods are present, `execute` is preferred.
+ *
+ * The evaluator:
+ *
+ * 1. Resolves the service from `ctx.services[serviceKey]`.
  * 2. Builds a JSON input snapshot via `buildInput(ctx)` — domain code that
- *    snapshots facts the engine needs. Fabric platform never lets OPA reach
- *    into the database directly; all facts flow through this function.
- * 3. Evaluates the Rego decision at `binding.decisionPath`.
+ *    snapshots facts the engine needs. OPA never reaches into the database
+ *    directly; all facts flow through this function.
+ * 3. Calls OPA at `binding.decisionPath`.
  * 4. Validates the response against the house-style shape (`OpaDecision`).
  * 5. Maps the decision to a `PolicyOutcome` and attaches engine provenance
- *    (`engine.name = "opa"`, `decisionPath`, `inputHash`) for audit.
+ *    under `dispatchEvidence.engine` — `name`, optional `version`, and
+ *    metadata covering `decisionPath`, `regoPackage`, `inputHash`, plus (when
+ *    the executor surfaces them) `decisionId`, `bundleName`, `bundleRevision`,
+ *    `bundleRevisionStatus`, and the raw `provenance` block.
  *
- * Failures (missing client, build failure, network failure, malformed response)
- * are governed by `onError`. Default `"block"` honors Fabric's default-deny
- * posture and records the failure category under `engine.metadata.error`.
+ * Failures (missing client, build failure, network failure, malformed
+ * response) are governed by `onError`. Default `"block"` honors Fabric's
+ * default-deny posture and records the failure category under
+ * `engine.metadata.error`.
  */
 declare function createOpaPolicyEvaluator<TDb = unknown>(options: CreateOpaPolicyEvaluatorOptions<TDb>): PolicyEvaluator<TDb>;
 
@@ -160,4 +242,85 @@ declare function stableStringify(value: unknown): string;
  */
 declare function defaultHashInput(input: Record<string, unknown>): string;
 
-export { type CreateOpaPolicyEvaluatorOptions, type OpaDecision, type OpaDecisionParseResult, type OpaPolicyBinding, type OpaPolicyClient, type OpaPolicyDecisionMapper, type OpaPolicyErrorMode, type OpaPolicyFailureKind, createOpaPolicyEvaluator, defaultHashInput, parseOpaDecision, stableStringify };
+/**
+ * Wrap an `OpaPolicyClient` (the high-level `@open-policy-agent/opa` SDK
+ * shape) as an {@link OpaPolicyExecutor}. The resulting executor carries no
+ * OPA-side provenance — the high-level SDK discards `decisionId` and
+ * `provenance` from the response — but does centralize the
+ * `(path, input) => execution` plumbing so hosts can choose at startup whether
+ * to wire a client or a full executor.
+ *
+ * For full provenance (decisionId, bundleRevision, opaVersion), prefer
+ * {@link executorFromOpaHttp}.
+ */
+declare function executorFromOpaClient(client: OpaPolicyClient): OpaPolicyExecutor;
+
+interface OpaHttpExecutorOptions {
+    /**
+     * Base URL of the OPA server, e.g. `"http://localhost:8181"` or
+     * `"https://opa.internal.example.com"`. Trailing slash is permitted; the
+     * executor normalizes it.
+     */
+    baseUrl: string;
+    /**
+     * Override for `globalThis.fetch`. Lets the host inject a fetch instance
+     * with retries, mTLS, OpenTelemetry instrumentation, etc. Defaults to
+     * `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Extra request headers (e.g. `Authorization`). */
+    headers?: Record<string, string>;
+    /**
+     * Request OPA-side provenance (`decision_id`, `provenance.version`,
+     * `provenance.bundles[*].revision`) via `?provenance=true`. Defaults to
+     * `true` — turning it off forfeits OPA's contribution to audit evidence
+     * and is rarely what you want.
+     */
+    provenance?: boolean;
+}
+/**
+ * Build an {@link OpaPolicyExecutor} that talks to OPA's REST API directly.
+ *
+ * POSTs to `{baseUrl}/v1/data/{path}?provenance=true` with body
+ * `{ "input": ... }`. Parses the snake_case response and lifts:
+ *
+ * - `result` → `execution.decision`
+ * - `decision_id` → `execution.decisionId`
+ * - `provenance.version` → `execution.opaVersion`
+ * - `provenance` (whole block) → `execution.provenance`
+ *
+ * Bundle revision selection happens in the factory, not the executor, because
+ * it depends on `binding.bundleName`.
+ *
+ * Calling this in environments without `globalThis.fetch` (older Node) throws
+ * at call time; pass `fetch: nodeFetch` or `fetch: undici-fetch` etc. via the
+ * options to support those runtimes explicitly.
+ */
+declare function executorFromOpaHttp(opts: OpaHttpExecutorOptions): OpaPolicyExecutor;
+
+interface BundleSelection {
+    bundleRevision?: string;
+    /**
+     * Set to `"ambiguous"` when OPA reports multiple bundles and the binding
+     * did not pick one with `bundleName`. The adapter records this on the
+     * evidence so dashboards can flag policies that need explicit selectors.
+     * `"missing"` is set when provenance was expected but absent.
+     */
+    bundleRevisionStatus?: "ambiguous" | "missing";
+}
+/**
+ * Determine which OPA bundle revision applies to this decision.
+ *
+ * Rules (in order):
+ *   1. If the executor already populated `execution.bundleRevision`, use it.
+ *   2. If `binding.bundleName` is set, look it up in `provenance.bundles`.
+ *   3. If exactly one bundle is reported, use its revision unambiguously.
+ *   4. If multiple bundles are reported and no selector exists, mark
+ *      `bundleRevisionStatus: "ambiguous"`.
+ *   5. If no provenance is reported at all, return `{}` — the caller decides
+ *      whether absence is meaningful (it is not, for executors that don't
+ *      carry provenance).
+ */
+declare function selectBundleRevision(execution: OpaPolicyExecution, binding: OpaPolicyBinding): BundleSelection;
+
+export { type BundleSelection, type CreateOpaPolicyEvaluatorOptions, type OpaDecision, type OpaDecisionParseResult, type OpaHttpExecutorOptions, type OpaPolicyBinding, type OpaPolicyClient, type OpaPolicyDecisionMapper, type OpaPolicyErrorMode, type OpaPolicyExecution, type OpaPolicyExecutor, type OpaPolicyFailureKind, createOpaPolicyEvaluator, defaultHashInput, executorFromOpaClient, executorFromOpaHttp, parseOpaDecision, selectBundleRevision, stableStringify };

package/dist/index.d.ts

@@ -25,6 +25,58 @@ interface OpaPolicyBinding {
      * keep the package name aligned with the decision path.
      */
     regoPackage?: string;
+    /**
+     * Optional selector for `bundleRevision` extraction when OPA's
+     * `provenance.bundles` carries multiple bundles. If absent and OPA reports
+     * a single bundle, the adapter uses that revision unambiguously. If absent
+     * and multiple bundles are present, the adapter marks the evidence with
+     * `bundleRevisionStatus: "ambiguous"` so audit dashboards can flag policies
+     * that need explicit selectors.
+     *
+     * Example: `"lending"` for a bundle named `lending` served by OPA.
+     */
+    bundleName?: string;
+}
+/**
+ * Result of one OPA evaluation, normalized for the adapter. Returned by
+ * implementations of {@link OpaPolicyExecutor}. The adapter accepts either a
+ * client (with `evaluate`) or an executor (with `execute`); the executor path
+ * preserves provenance OPA exposes via `?provenance=true` — primarily
+ * `decision_id` and `provenance.bundles[*].revision`.
+ */
+interface OpaPolicyExecution {
+    /** The raw decision body — the value of `result` in OPA's response. */
+    decision: unknown;
+    /** OPA's per-request decision ID (response field `decision_id`). */
+    decisionId?: string;
+    /**
+     * Pre-selected bundle revision, when the executor can determine it
+     * unambiguously without binding context (e.g. a transport that only ever
+     * sees a single bundle). The factory may override this from
+     * `provenance.bundles` + `binding.bundleName`.
+     */
+    bundleRevision?: string;
+    /** OPA server version (response field `provenance.version`). */
+    opaVersion?: string;
+    /**
+     * Raw `provenance` block from the OPA response. Carries
+     * `bundles: { [name]: { revision } }`, build info, etc. The factory uses
+     * this together with `binding.bundleName` to select `bundleRevision`.
+     */
+    provenance?: Record<string, unknown>;
+}
+/**
+ * Rich execution interface. Implementations are responsible for talking to
+ * OPA and surfacing provenance. Two official implementations ship in this
+ * package: {@link executorFromOpaClient} (wraps the high-level SDK; limited
+ * provenance) and {@link executorFromOpaHttp} (calls OPA REST directly with
+ * `?provenance=true`; full provenance).
+ *
+ * Hosts wire one of these into `ctx.services[serviceKey]` as an alternative
+ * to {@link OpaPolicyClient}.
+ */
+interface OpaPolicyExecutor {
+    execute(path: string, input: unknown): Promise<OpaPolicyExecution>;
 }
 /**
  * Structured Rego decision shape — the "house style" the adapter expects from
@@ -60,7 +112,18 @@ type OpaPolicyErrorMode = "block" | "throw";
  * something we couldn't parse" from "no client was injected at runtime".
  */
 type OpaPolicyFailureKind = "client_unavailable" | "input_build_failed" | "evaluation_failed" | "invalid_response";
-type OpaPolicyDecisionMapper<TDb = unknown> = (decision: OpaDecision, ctx: PolicyContext<TDb>) => Pick<PolicyOutcome, "result" | "reason"> & {
+/**
+ * Maps a validated `OpaDecision` to the fields of a `PolicyOutcome` the
+ * adapter consumes (`result`, `reason`, optional extra `metadata`). The
+ * optional third argument, `execution`, exposes OPA-side provenance
+ * (`decisionId`, `bundleRevision`, raw `provenance`) so a mapper can lift
+ * specific fields into `outcome.metadata` if the host wants them queryable
+ * outside `dispatchEvidence.engine`.
+ *
+ * Existing two-argument mappers (`(decision, ctx) => …`) remain valid —
+ * TypeScript permits implementations with fewer parameters.
+ */
+type OpaPolicyDecisionMapper<TDb = unknown> = (decision: OpaDecision, ctx: PolicyContext<TDb>, execution: OpaPolicyExecution) => Partial<PolicyOutcome> & {
     metadata?: Record<string, unknown>;
 };
 interface CreateOpaPolicyEvaluatorOptions<TDb = unknown> {
@@ -111,20 +174,39 @@ interface CreateOpaPolicyEvaluatorOptions<TDb = unknown> {
 
 /**
  * Build a Fabric `PolicyEvaluator` that delegates decision-making to an OPA
- * (Open Policy Agent) deployment. The evaluator:
+ * (Open Policy Agent) deployment.
+ *
+ * The adapter accepts either of two service shapes under
+ * `ctx.services[serviceKey]`:
  *
- * 1. Reads the host-injected OPA client from `ctx.services[serviceKey]`.
+ * - `OpaPolicyExecutor` (preferred) — `execute(path, input)` returning a rich
+ *   `OpaPolicyExecution` (decision plus `decisionId`, `bundleRevision`,
+ *   `opaVersion`, `provenance`). Ship one with {@link executorFromOpaHttp} or
+ *   {@link executorFromOpaClient}.
+ * - `OpaPolicyClient` — `evaluate(path, input)` returning the raw decision
+ *   only. Compatible with the high-level `@open-policy-agent/opa` SDK at the
+ *   cost of OPA-side provenance.
+ *
+ * If both methods are present, `execute` is preferred.
+ *
+ * The evaluator:
+ *
+ * 1. Resolves the service from `ctx.services[serviceKey]`.
  * 2. Builds a JSON input snapshot via `buildInput(ctx)` — domain code that
- *    snapshots facts the engine needs. Fabric platform never lets OPA reach
- *    into the database directly; all facts flow through this function.
- * 3. Evaluates the Rego decision at `binding.decisionPath`.
+ *    snapshots facts the engine needs. OPA never reaches into the database
+ *    directly; all facts flow through this function.
+ * 3. Calls OPA at `binding.decisionPath`.
  * 4. Validates the response against the house-style shape (`OpaDecision`).
  * 5. Maps the decision to a `PolicyOutcome` and attaches engine provenance
- *    (`engine.name = "opa"`, `decisionPath`, `inputHash`) for audit.
+ *    under `dispatchEvidence.engine` — `name`, optional `version`, and
+ *    metadata covering `decisionPath`, `regoPackage`, `inputHash`, plus (when
+ *    the executor surfaces them) `decisionId`, `bundleName`, `bundleRevision`,
+ *    `bundleRevisionStatus`, and the raw `provenance` block.
  *
- * Failures (missing client, build failure, network failure, malformed response)
- * are governed by `onError`. Default `"block"` honors Fabric's default-deny
- * posture and records the failure category under `engine.metadata.error`.
+ * Failures (missing client, build failure, network failure, malformed
+ * response) are governed by `onError`. Default `"block"` honors Fabric's
+ * default-deny posture and records the failure category under
+ * `engine.metadata.error`.
  */
 declare function createOpaPolicyEvaluator<TDb = unknown>(options: CreateOpaPolicyEvaluatorOptions<TDb>): PolicyEvaluator<TDb>;
 
@@ -160,4 +242,85 @@ declare function stableStringify(value: unknown): string;
  */
 declare function defaultHashInput(input: Record<string, unknown>): string;
 
-export { type CreateOpaPolicyEvaluatorOptions, type OpaDecision, type OpaDecisionParseResult, type OpaPolicyBinding, type OpaPolicyClient, type OpaPolicyDecisionMapper, type OpaPolicyErrorMode, type OpaPolicyFailureKind, createOpaPolicyEvaluator, defaultHashInput, parseOpaDecision, stableStringify };
+/**
+ * Wrap an `OpaPolicyClient` (the high-level `@open-policy-agent/opa` SDK
+ * shape) as an {@link OpaPolicyExecutor}. The resulting executor carries no
+ * OPA-side provenance — the high-level SDK discards `decisionId` and
+ * `provenance` from the response — but does centralize the
+ * `(path, input) => execution` plumbing so hosts can choose at startup whether
+ * to wire a client or a full executor.
+ *
+ * For full provenance (decisionId, bundleRevision, opaVersion), prefer
+ * {@link executorFromOpaHttp}.
+ */
+declare function executorFromOpaClient(client: OpaPolicyClient): OpaPolicyExecutor;
+
+interface OpaHttpExecutorOptions {
+    /**
+     * Base URL of the OPA server, e.g. `"http://localhost:8181"` or
+     * `"https://opa.internal.example.com"`. Trailing slash is permitted; the
+     * executor normalizes it.
+     */
+    baseUrl: string;
+    /**
+     * Override for `globalThis.fetch`. Lets the host inject a fetch instance
+     * with retries, mTLS, OpenTelemetry instrumentation, etc. Defaults to
+     * `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Extra request headers (e.g. `Authorization`). */
+    headers?: Record<string, string>;
+    /**
+     * Request OPA-side provenance (`decision_id`, `provenance.version`,
+     * `provenance.bundles[*].revision`) via `?provenance=true`. Defaults to
+     * `true` — turning it off forfeits OPA's contribution to audit evidence
+     * and is rarely what you want.
+     */
+    provenance?: boolean;
+}
+/**
+ * Build an {@link OpaPolicyExecutor} that talks to OPA's REST API directly.
+ *
+ * POSTs to `{baseUrl}/v1/data/{path}?provenance=true` with body
+ * `{ "input": ... }`. Parses the snake_case response and lifts:
+ *
+ * - `result` → `execution.decision`
+ * - `decision_id` → `execution.decisionId`
+ * - `provenance.version` → `execution.opaVersion`
+ * - `provenance` (whole block) → `execution.provenance`
+ *
+ * Bundle revision selection happens in the factory, not the executor, because
+ * it depends on `binding.bundleName`.
+ *
+ * Calling this in environments without `globalThis.fetch` (older Node) throws
+ * at call time; pass `fetch: nodeFetch` or `fetch: undici-fetch` etc. via the
+ * options to support those runtimes explicitly.
+ */
+declare function executorFromOpaHttp(opts: OpaHttpExecutorOptions): OpaPolicyExecutor;
+
+interface BundleSelection {
+    bundleRevision?: string;
+    /**
+     * Set to `"ambiguous"` when OPA reports multiple bundles and the binding
+     * did not pick one with `bundleName`. The adapter records this on the
+     * evidence so dashboards can flag policies that need explicit selectors.
+     * `"missing"` is set when provenance was expected but absent.
+     */
+    bundleRevisionStatus?: "ambiguous" | "missing";
+}
+/**
+ * Determine which OPA bundle revision applies to this decision.
+ *
+ * Rules (in order):
+ *   1. If the executor already populated `execution.bundleRevision`, use it.
+ *   2. If `binding.bundleName` is set, look it up in `provenance.bundles`.
+ *   3. If exactly one bundle is reported, use its revision unambiguously.
+ *   4. If multiple bundles are reported and no selector exists, mark
+ *      `bundleRevisionStatus: "ambiguous"`.
+ *   5. If no provenance is reported at all, return `{}` — the caller decides
+ *      whether absence is meaningful (it is not, for executors that don't
+ *      carry provenance).
+ */
+declare function selectBundleRevision(execution: OpaPolicyExecution, binding: OpaPolicyBinding): BundleSelection;
+
+export { type BundleSelection, type CreateOpaPolicyEvaluatorOptions, type OpaDecision, type OpaDecisionParseResult, type OpaHttpExecutorOptions, type OpaPolicyBinding, type OpaPolicyClient, type OpaPolicyDecisionMapper, type OpaPolicyErrorMode, type OpaPolicyExecution, type OpaPolicyExecutor, type OpaPolicyFailureKind, createOpaPolicyEvaluator, defaultHashInput, executorFromOpaClient, executorFromOpaHttp, parseOpaDecision, selectBundleRevision, stableStringify };

package/dist/index.js

@@ -1,5 +1,32 @@
 import { createHash } from 'crypto';
 
+// src/bundle-selector.ts
+function selectBundleRevision(execution, binding) {
+  if (typeof execution.bundleRevision === "string" && execution.bundleRevision.length > 0) {
+    return { bundleRevision: execution.bundleRevision };
+  }
+  const bundles = readBundles(execution.provenance);
+  if (!bundles) return {};
+  const names = Object.keys(bundles);
+  if (names.length === 0) return {};
+  if (binding.bundleName) {
+    const revision = bundles[binding.bundleName]?.revision;
+    return typeof revision === "string" && revision.length > 0 ? { bundleRevision: revision } : {};
+  }
+  if (names.length === 1) {
+    const only = names[0];
+    const revision = only !== void 0 ? bundles[only]?.revision : void 0;
+    return typeof revision === "string" && revision.length > 0 ? { bundleRevision: revision } : {};
+  }
+  return { bundleRevisionStatus: "ambiguous" };
+}
+function readBundles(provenance) {
+  if (!provenance || typeof provenance !== "object") return void 0;
+  const b = provenance.bundles;
+  if (!b || typeof b !== "object" || Array.isArray(b)) return void 0;
+  return b;
+}
+
 // src/decision-schema.ts
 var POLICY_RESULTS = ["pass", "warn", "block"];
 function parseOpaDecision(raw) {
@@ -89,13 +116,14 @@ function createOpaPolicyEvaluator(options) {
     version: binding.version,
     previewSafe,
     evaluate: async (ctx) => {
-      const client = ctx.services?.[serviceKey];
-      if (!client || typeof client.evaluate !== "function") {
+      const service = ctx.services?.[serviceKey];
+      const transport = resolveTransport(service);
+      if (!transport) {
         return makeFailureOutcome(
           binding,
           engineVersion,
           "client_unavailable",
-          `No OPA client at ctx.services["${serviceKey}"]`,
+          `No OPA client/executor at ctx.services["${serviceKey}"]`,
           onError
         );
       }
@@ -116,9 +144,9 @@ function createOpaPolicyEvaluator(options) {
         inputHash = hashInput(input);
       } catch {
       }
-      let rawResult;
+      let execution;
       try {
-        rawResult = await client.evaluate(binding.decisionPath, input);
+        execution = await transport(binding.decisionPath, input);
       } catch (err) {
         return makeFailureOutcome(
           binding,
@@ -129,7 +157,7 @@ function createOpaPolicyEvaluator(options) {
           inputHash
         );
       }
-      const parsed = parseOpaDecision(rawResult);
+      const parsed = parseOpaDecision(execution.decision);
       if (!parsed.ok) {
         return makeFailureOutcome(
           binding,
@@ -137,13 +165,15 @@ function createOpaPolicyEvaluator(options) {
           "invalid_response",
           `OPA returned malformed decision: ${parsed.error}`,
           onError,
-          inputHash
+          inputHash,
+          execution
         );
       }
       return buildSuccessOutcome(
         binding,
         engineVersion,
         parsed.decision,
+        execution,
         inputHash,
         ctx,
         mapDecision
@@ -151,13 +181,28 @@ function createOpaPolicyEvaluator(options) {
     }
   };
 }
-function buildSuccessOutcome(binding, engineVersion, decision, inputHash, ctx, mapDecision) {
-  const mapped = mapDecision ? mapDecision(decision, ctx) : { result: decision.result, reason: decision.reason };
+function resolveTransport(service) {
+  if (!service || typeof service !== "object") return null;
+  const exec = service.execute;
+  if (typeof exec === "function") {
+    return (path, input) => service.execute(path, input);
+  }
+  const eval_ = service.evaluate;
+  if (typeof eval_ === "function") {
+    return async (path, input) => ({
+      decision: await service.evaluate(path, input)
+    });
+  }
+  return null;
+}
+function buildSuccessOutcome(binding, engineVersion, decision, execution, inputHash, ctx, mapDecision) {
+  const selection = selectBundleRevision(execution, binding);
+  const mapped = mapDecision ? mapDecision(decision, ctx, execution) : { result: decision.result, reason: decision.reason };
   return {
     policyId: binding.policyId,
     policyVersion: binding.version,
-    result: mapped.result,
-    reason: mapped.reason,
+    result: mapped.result ?? decision.result,
+    reason: mapped.reason ?? decision.reason,
     metadata: {
       ...mapped.metadata ?? {},
       opaDecision: decision
@@ -169,11 +214,16 @@ function buildSuccessOutcome(binding, engineVersion, decision, inputHash, ctx, m
       dispatchPath: ["code"],
       engine: {
         name: ENGINE_NAME,
-        version: engineVersion,
+        version: execution.opaVersion ?? engineVersion,
         metadata: stripUndefined({
           decisionPath: binding.decisionPath,
           regoPackage: binding.regoPackage,
           inputHash,
+          decisionId: execution.decisionId,
+          bundleName: binding.bundleName,
+          bundleRevision: selection.bundleRevision,
+          bundleRevisionStatus: selection.bundleRevisionStatus,
+          provenance: execution.provenance,
           conditionResults: decision.conditionResults,
           factsUsed: decision.factsUsed,
           obligations: decision.obligations
@@ -182,12 +232,13 @@ function buildSuccessOutcome(binding, engineVersion, decision, inputHash, ctx, m
     }
   };
 }
-function makeFailureOutcome(binding, engineVersion, error, reason, onError, inputHash) {
+function makeFailureOutcome(binding, engineVersion, error, reason, onError, inputHash, execution) {
   if (onError === "throw") {
     const err = new Error(reason);
     err.kind = error;
     throw err;
   }
+  const selection = execution ? selectBundleRevision(execution, binding) : {};
   return {
     policyId: binding.policyId,
     policyVersion: binding.version,
@@ -203,11 +254,16 @@ function makeFailureOutcome(binding, engineVersion, error, reason, onError, inpu
       dispatchPath: ["code"],
       engine: {
         name: ENGINE_NAME,
-        version: engineVersion,
+        version: execution?.opaVersion ?? engineVersion,
         metadata: stripUndefined({
           decisionPath: binding.decisionPath,
           regoPackage: binding.regoPackage,
           inputHash,
+          decisionId: execution?.decisionId,
+          bundleName: binding.bundleName,
+          bundleRevision: selection.bundleRevision,
+          bundleRevisionStatus: selection.bundleRevisionStatus,
+          provenance: execution?.provenance,
           error,
           errorReason: reason
         })
@@ -232,6 +288,71 @@ function formatError(err) {
   }
 }
 
-export { createOpaPolicyEvaluator, defaultHashInput, parseOpaDecision, stableStringify };
+// src/executor-client.ts
+function executorFromOpaClient(client) {
+  return {
+    async execute(path, input) {
+      const decision = await client.evaluate(path, input);
+      return { decision };
+    }
+  };
+}
+
+// src/executor-http.ts
+function executorFromOpaHttp(opts) {
+  const baseUrl = stripTrailingSlash(opts.baseUrl);
+  const provenance = opts.provenance ?? true;
+  const customFetch = opts.fetch;
+  const headers = {
+    "content-type": "application/json",
+    accept: "application/json",
+    ...opts.headers ?? {}
+  };
+  return {
+    async execute(path, input) {
+      const fetchImpl = customFetch ?? globalThis.fetch;
+      if (typeof fetchImpl !== "function") {
+        throw new Error(
+          "executorFromOpaHttp: no fetch implementation available. Pass `fetch` in options or run on a runtime with `globalThis.fetch`."
+        );
+      }
+      const url = `${baseUrl}/v1/data/${stripLeadingSlash(path)}${provenance ? "?provenance=true" : ""}`;
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ input })
+      });
+      if (!response.ok) {
+        const text = await safeReadText(response);
+        throw new Error(`OPA HTTP ${response.status} at ${url}: ${truncate(text, 500)}`);
+      }
+      const body = await response.json();
+      return {
+        decision: body.result,
+        decisionId: body.decision_id,
+        opaVersion: body.provenance?.version,
+        provenance: body.provenance
+      };
+    }
+  };
+}
+function stripTrailingSlash(s) {
+  return s.replace(/\/+$/, "");
+}
+function stripLeadingSlash(s) {
+  return s.replace(/^\/+/, "");
+}
+async function safeReadText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return "<unreadable body>";
+  }
+}
+function truncate(s, max) {
+  return s.length <= max ? s : `${s.slice(0, max)}\u2026`;
+}
+
+export { createOpaPolicyEvaluator, defaultHashInput, executorFromOpaClient, executorFromOpaHttp, parseOpaDecision, selectBundleRevision, stableStringify };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map