@spendguard/sdk 0.5.0

package/dist/retry.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Classification bucket for an RPC error per Python `_classify_rpc_error`.
+ *
+ * - `"transient"` → the sidecar / network is temporarily unavailable. Safe to
+ *   retry IF the caller has a stable idempotency key.
+ * - `"permanent"` → all other failures (invalid argument, decision denied,
+ *   precondition failed, etc.). MUST NOT retry — retrying a permanent error
+ *   either does nothing (waste of latency budget) or worse, re-asserts a
+ *   broken request shape.
+ */
+type RpcErrorClassification = "transient" | "permanent";
+/**
+ * The gRPC status codes that mirror Python's transient-error bucket.
+ * Listed here as a frozen set so tests can assert the bucket is the locked
+ * three (review-standards.md §1.2 verbatim-signature gate).
+ *
+ * The string values are the canonical `@grpc/grpc-js` status names; same
+ * spelling as `grpc.StatusCode.<NAME>` and `protobuf-ts`'s `RpcError.code`.
+ */
+declare const TRANSIENT_STATUS_CODES: ReadonlySet<string>;
+/**
+ * Classify an error as transient or permanent.
+ *
+ * Inputs accepted (in order of dispatch):
+ *   1. `SidecarUnavailable` instance — `"transient"` (we already classified it
+ *      upstream via `mapGrpcStatusToError`).
+ *   2. Object with `.code` matching one of `TRANSIENT_STATUS_CODES` — typed
+ *      `"transient"`. This is the `protobuf-ts` `RpcError` shape AND the
+ *      `@grpc/grpc-js` ServiceError shape AND a duck-typed mock for tests.
+ *   3. Everything else — `"permanent"`.
+ *
+ * Matches Python `_classify_rpc_error` line-for-line: same three statuses,
+ * same fallthrough, same conservative default ("if we don't know, don't retry").
+ *
+ * @param err The error to classify. Accepts any thrown value (RpcError,
+ *   SpendGuardError subclasses, plain Error, string, undefined, …).
+ * @returns `"transient"` or `"permanent"`.
+ *
+ * @example
+ *   import { classifyRpcError } from "@spendguard/sdk/retry";
+ *
+ *   try {
+ *     await client.reserve(req);
+ *   } catch (err) {
+ *     if (classifyRpcError(err) === "transient") {
+ *       // queue for retry
+ *     } else {
+ *       throw err;
+ *     }
+ *   }
+ */
+declare function classifyRpcError(err: unknown): RpcErrorClassification;
+/**
+ * Options for `runWithRetry`.
+ *
+ * - `idempotencyKey` — REQUIRED for any retry to actually occur. Without one,
+ *   `runWithRetry` runs `fn` exactly once and rethrows a pointed
+ *   `SidecarUnavailable(cause: err)` on a transient error so the adapter can
+ *   route. With one, `fn` runs up to `maxAttempts` times on transient errors.
+ * - `maxAttempts` — total attempts (initial + retries). Default 2; legal
+ *   range [1, 5]. The default 2 matches design.md §6.5 line 428 ("initial +
+ *   1 retry"); values ≥ 5 require an explicit opt-in to discourage runaway
+ *   retry loops in the substrate.
+ * - `baseBackoffMs` — fixed delay between attempts. Default 25 ms per
+ *   design.md §6.5 line 429.
+ * - `jitterMs` — random delay added on top of `baseBackoffMs`. Default 25 ms;
+ *   sampled uniformly from `[0, jitterMs]`. Avoids retry-storm pile-ups when
+ *   N adapters share a single sidecar.
+ * - `sleep` — pluggable sleeper for tests. Defaults to `setTimeout`.
+ */
+interface RunWithRetryOptions {
+    idempotencyKey?: string;
+    maxAttempts?: number;
+    baseBackoffMs?: number;
+    jitterMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Run `fn()` with bounded retry per design.md §6.5 + Python
+ * `_classify_rpc_error` parity.
+ *
+ * Algorithm:
+ *   1. Run `fn()`. If it succeeds, return the value.
+ *   2. If it throws, classify the error via `classifyRpcError(err)`.
+ *      - PERMANENT → rethrow as-is (NEVER retry).
+ *      - TRANSIENT without `idempotencyKey` → throw
+ *        `SidecarUnavailable(cause: err)` immediately. Caller's adapter is
+ *        responsible for routing; the substrate refuses to retry without a
+ *        stable key because a fresh decision on retry would double-reserve.
+ *      - TRANSIENT with `idempotencyKey` AND attempts remaining → sleep
+ *        `baseBackoffMs + uniform(0, jitterMs)`, then go to step 1.
+ *      - TRANSIENT with `idempotencyKey` AND attempts exhausted → throw the
+ *        LAST error (preserves the original `cause` if it's already a
+ *        `SidecarUnavailable`).
+ *
+ * Permanent errors NEVER retry — design.md §6.5 line 426 spells out the
+ * three-status transient cluster as the only retry-eligible surface.
+ *
+ * The `sleep` function in tests defaults to `setTimeout` — for unit tests,
+ * pass a no-op (`async () => {}`) so the retry loop runs synchronously.
+ *
+ * @param fn The function to run. Awaited; thrown errors are inspected.
+ * @param opts Retry options. `idempotencyKey` MUST be set for retries to
+ *   actually occur.
+ *
+ * @returns The result of `fn()` on success.
+ *
+ * @throws SidecarUnavailable when `fn` fails transiently without an
+ *   idempotency key.
+ * @throws The last error from `fn` when attempts are exhausted (or the
+ *   error type is permanent).
+ *
+ * @example
+ *   await runWithRetry(
+ *     () => client.requestDecision(grpcReq, { timeout: 250 }),
+ *     { idempotencyKey: req.idempotencyKey, maxAttempts: 2 },
+ *   );
+ */
+declare function runWithRetry<T>(fn: () => Promise<T>, opts?: RunWithRetryOptions): Promise<T>;
+
+export { type RpcErrorClassification, type RunWithRetryOptions, TRANSIENT_STATUS_CODES, classifyRpcError, runWithRetry };

package/dist/retry.js

@@ -0,0 +1,92 @@
+// src/errors.ts
+var SpendGuardError = class extends Error {
+  name = "SpendGuardError";
+  constructor(message, opts) {
+    super(message);
+    if (opts?.cause !== void 0) {
+      this.cause = opts.cause;
+    }
+    Object.defineProperty(this, "name", {
+      value: this.name,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+  }
+};
+var SidecarUnavailable = class extends SpendGuardError {
+  name = "SidecarUnavailable";
+  statusCode = 503;
+};
+
+// src/retry.ts
+var TRANSIENT_STATUS_CODES = /* @__PURE__ */ new Set([
+  "UNAVAILABLE",
+  "DEADLINE_EXCEEDED",
+  "CANCELLED"
+]);
+function classifyRpcError(err) {
+  if (err instanceof SidecarUnavailable) return "transient";
+  if (err !== null && typeof err === "object" && "code" in err) {
+    const code = err.code;
+    if (typeof code === "string" && TRANSIENT_STATUS_CODES.has(code)) {
+      return "transient";
+    }
+  }
+  return "permanent";
+}
+async function runWithRetry(fn, opts = {}) {
+  const idempotencyKey = opts.idempotencyKey;
+  const maxAttempts = clampMaxAttempts(opts.maxAttempts ?? 2);
+  const baseBackoffMs = opts.baseBackoffMs ?? 25;
+  const jitterMs = opts.jitterMs ?? 25;
+  const sleep = opts.sleep ?? defaultSleep;
+  let lastErr;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const classification = classifyRpcError(err);
+      if (classification === "permanent") {
+        throw err;
+      }
+      if (idempotencyKey === void 0 || idempotencyKey.length === 0) {
+        if (err instanceof SidecarUnavailable) {
+          throw err;
+        }
+        throw new SidecarUnavailable(
+          `transient RPC failure with no idempotency key; refusing to retry: ${errorMessage(err)}`,
+          { cause: err }
+        );
+      }
+      lastErr = err;
+      if (attempt < maxAttempts) {
+        const delay = baseBackoffMs + Math.floor(Math.random() * (jitterMs + 1));
+        await sleep(delay);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastErr ?? new SpendGuardError("runWithRetry: unreachable");
+}
+function clampMaxAttempts(value) {
+  if (!Number.isFinite(value) || !Number.isInteger(value)) return 2;
+  if (value < 1) return 1;
+  if (value > 5) return 5;
+  return value;
+}
+function defaultSleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  return String(err);
+}
+
+export { TRANSIENT_STATUS_CODES, classifyRpcError, runWithRetry };
+//# sourceMappingURL=retry.js.map
+//# sourceMappingURL=retry.js.map

package/dist/runPlan.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Caller-declared plan for one logical agent run.
+ *
+ * - `plannedCalls`  — expected number of LLM calls in the run. Non-negative integer.
+ * - `plannedTools` — expected number of tool calls in the run. Non-negative integer.
+ *
+ * The SDK ships `plannedStepsHint = plannedCalls + plannedTools` on every
+ * `DecisionRequest` issued inside the active scope (per spec §5.1: steps are
+ * the disjoint union of LLM + tool calls). The sidecar-side projector
+ * enforces an upper bound `[0, MAX_PLANNED_STEPS]`
+ * (`services/run_cost_projector/src/server.rs::MAX_PLANNED_STEPS`); we don't
+ * repeat the bound here so a future Rust-side bump doesn't require an SDK
+ * release.
+ */
+interface RunPlan {
+    plannedCalls: number;
+    plannedTools: number;
+}
+/**
+ * Read the in-scope `RunPlan` if one exists, otherwise `null`.
+ *
+ * Returns `null` (not `undefined`) per LOCKED design.md §4.7 line 300 — the
+ * shape is `RunPlan | null` for parity with the Python `current_run_plan()`
+ * reference (which returns `None`) and review-standards §8.3.
+ *
+ * Returned object is the SAME reference `withRunPlan` stored (defensively
+ * copied at scope entry); adapters MUST treat the returned value as
+ * immutable.
+ */
+declare function currentRunPlan(): RunPlan | null;
+/**
+ * Higher-order function that installs `plan` in async-local scope around `fn`.
+ *
+ * CURRIED form per design.md §4.7 lines 295-298 — calling `withRunPlan(plan, fn)`
+ * returns a NEW callable; the wrapped `fn` is only invoked when the returned
+ * callable is called. Mirrors the `@with_run_plan(...)` decorator pattern in
+ * `sdk/python/src/spendguard/run_plan.py`.
+ *
+ * ## Validation (LOCKED §8.4)
+ *
+ * `plannedCalls` and `plannedTools` are validated at HOF construction time
+ * (NOT at wrapped-call time): if either is missing, non-integer, or negative,
+ * a `TypeError` is thrown synchronously from `withRunPlan` — surfacing the
+ * misuse at decorator application rather than first call. `plannedTools` is
+ * optional on input and defaults to `0`.
+ *
+ * ## Nesting (LOCKED §8.2 — OUTER WINS)
+ *
+ * When the returned callable is invoked inside an existing `withRunPlan`
+ * scope, the inner call is a NO-OP for plan storage — the outer plan stays
+ * active and `currentRunPlan()` continues to return it. The inner `fn` is
+ * still invoked with its arguments; only the storage swap is skipped. This
+ * matches `run_plan.py` lines 183-191 (outer wins) and protects the budget
+ * envelope from being silently rewritten by a sub-agent helper.
+ *
+ * @param plan The run plan to install. Validated immediately.
+ * @param fn   The (sync or async) function to run inside the plan scope.
+ * @returns A NEW async function that, when called, runs `fn(...args)` with
+ *          the plan in scope and returns `Promise<TRet>`.
+ *
+ * @throws TypeError if `plannedCalls` or `plannedTools` is not a non-negative
+ *         integer.
+ */
+declare function withRunPlan<TArgs extends unknown[], TRet>(plan: {
+    plannedCalls: number;
+    plannedTools?: number;
+}, fn: (...args: TArgs) => TRet | Promise<TRet>): (...args: TArgs) => Promise<TRet>;
+
+export { type RunPlan, currentRunPlan, withRunPlan };

package/dist/runPlan.js

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+// src/runPlan.ts
+var storage = new AsyncLocalStorage();
+function currentRunPlan() {
+  return storage.getStore() ?? null;
+}
+function withRunPlan(plan, fn) {
+  if (!Number.isInteger(plan.plannedCalls) || plan.plannedCalls < 0) {
+    throw new TypeError(
+      `withRunPlan: plannedCalls must be a non-negative integer, got ${String(plan.plannedCalls)}`
+    );
+  }
+  const tools = plan.plannedTools ?? 0;
+  if (!Number.isInteger(tools) || tools < 0) {
+    throw new TypeError(
+      `withRunPlan: plannedTools must be a non-negative integer, got ${String(plan.plannedTools)}`
+    );
+  }
+  const fullPlan = Object.freeze({
+    plannedCalls: plan.plannedCalls,
+    plannedTools: tools
+  });
+  return async (...args) => {
+    const existing = storage.getStore();
+    if (existing !== void 0) {
+      return await fn(...args);
+    }
+    return await storage.run(fullPlan, () => fn(...args));
+  };
+}
+
+export { currentRunPlan, withRunPlan };
+//# sourceMappingURL=runPlan.js.map
+//# sourceMappingURL=runPlan.js.map

package/fixtures/cross-language/v1.json

@@ -0,0 +1,327 @@
+{
+  "version": 1,
+  "generated_at": "2026-06-07",
+  "generated_with": {
+    "python_reference": "spendguard.ids.* + spendguard.prompt_hash.compute",
+    "note": "Python implementation is the reference. TS asserts the SAME expected_output for the SAME inputs. Drift in either direction is a P0 review-standards §2 blocker."
+  },
+  "fixtures": [
+    {
+      "id": "FX1",
+      "fn": "derive_idempotency_key",
+      "description": "ASCII numeric IDs, LLM_CALL_PRE trigger",
+      "inputs": {
+        "tenant_id": "t-1",
+        "session_id": "s-1",
+        "run_id": "r-1",
+        "step_id": "step-1",
+        "llm_call_id": "llm-1",
+        "trigger": "LLM_CALL_PRE"
+      },
+      "expected_output": "sg-df6a372619ee74530c2d9e6e4cbbc4b9"
+    },
+    {
+      "id": "FX2",
+      "fn": "derive_idempotency_key",
+      "description": "ASCII numeric IDs, alternate values",
+      "inputs": {
+        "tenant_id": "t-2",
+        "session_id": "s-2",
+        "run_id": "r-2",
+        "step_id": "step-2",
+        "llm_call_id": "llm-2",
+        "trigger": "LLM_CALL_PRE"
+      },
+      "expected_output": "sg-faefca72f21e98f85ca1428a07ff74cf"
+    },
+    {
+      "id": "FX3",
+      "fn": "derive_idempotency_key",
+      "description": "Canonical UUID tenant",
+      "inputs": {
+        "tenant_id": "00000000-0000-0000-0000-000000000001",
+        "session_id": "sess-1",
+        "run_id": "run-1",
+        "step_id": "step-1",
+        "llm_call_id": "llm-1",
+        "trigger": "LLM_CALL_PRE"
+      },
+      "expected_output": "sg-8f58c05cb80e39934ac161f5a4c7db40"
+    },
+    {
+      "id": "FX4",
+      "fn": "derive_idempotency_key",
+      "description": "Empty trigger field",
+      "inputs": {
+        "tenant_id": "tenant-abc",
+        "session_id": "sess-1",
+        "run_id": "run-1",
+        "step_id": "step-1",
+        "llm_call_id": "llm-1",
+        "trigger": ""
+      },
+      "expected_output": "sg-3a2090b41777421828f4362daca7aaa5"
+    },
+    {
+      "id": "FX5",
+      "fn": "derive_idempotency_key",
+      "description": "All fields empty",
+      "inputs": {
+        "tenant_id": "",
+        "session_id": "",
+        "run_id": "",
+        "step_id": "",
+        "llm_call_id": "",
+        "trigger": ""
+      },
+      "expected_output": "sg-ff302dc3560c000bc0cf9b9f72359b10"
+    },
+    {
+      "id": "FX6",
+      "fn": "derive_idempotency_key",
+      "description": "AGENT_STEP_PRE trigger boundary",
+      "inputs": {
+        "tenant_id": "tenant-xyz",
+        "session_id": "sess-42",
+        "run_id": "run-42",
+        "step_id": "step-7",
+        "llm_call_id": "llm-7",
+        "trigger": "AGENT_STEP_PRE"
+      },
+      "expected_output": "sg-a0c3ef27b9ef67c2649e3f54763f28cd"
+    },
+    {
+      "id": "FX7",
+      "fn": "derive_idempotency_key",
+      "description": "Multi-byte UTF-8 tenant id (CJK)",
+      "inputs": {
+        "tenant_id": "租户-甲",
+        "session_id": "sess-1",
+        "run_id": "run-1",
+        "step_id": "step-1",
+        "llm_call_id": "llm-1",
+        "trigger": "LLM_CALL_PRE"
+      },
+      "expected_output": "sg-95f41144d9bcd120386eeba22b83b74c"
+    },
+    {
+      "id": "FX8",
+      "fn": "derive_idempotency_key",
+      "description": "Unit-Separator probe (long tenant, empty session)",
+      "inputs": {
+        "tenant_id": "abcd",
+        "session_id": "",
+        "run_id": "x",
+        "step_id": "y",
+        "llm_call_id": "z",
+        "trigger": "T"
+      },
+      "expected_output": "sg-28cc1690aed794c64279c30f8ba49dfb"
+    },
+    {
+      "id": "FXP1",
+      "fn": "compute_prompt_hash",
+      "description": "ASCII prompt + canonical UUID tenant",
+      "inputs": {
+        "prompt_text": "hello world",
+        "tenant_id": "00000000-0000-0000-0000-000000000001"
+      },
+      "expected_output": "5d55a1ebc9782455de0979780fd6cf686127dadcba580f230ddc3fea31516d0d"
+    },
+    {
+      "id": "FXP2",
+      "fn": "compute_prompt_hash",
+      "description": "Empty prompt + canonical UUID tenant",
+      "inputs": {
+        "prompt_text": "",
+        "tenant_id": "00000000-0000-0000-0000-000000000001"
+      },
+      "expected_output": "698e521970ba6005a5555a4dc63797488a0f673a3386adfe0410aa11c9b6757b"
+    },
+    {
+      "id": "FXP3",
+      "fn": "compute_prompt_hash",
+      "description": "Whitespace-padded prompt + non-UUID tenant (strip gate)",
+      "inputs": {
+        "prompt_text": "  trim me  ",
+        "tenant_id": "tenant-abc"
+      },
+      "expected_output": "d97fa1377ce7133eeae08a7b9d67eaf50f80edc917d4550720ac6e9fccbd89e4"
+    },
+    {
+      "id": "FXP4",
+      "fn": "compute_prompt_hash",
+      "description": "Multi-byte UTF-8 prompt (CJK punctuation)",
+      "inputs": {
+        "prompt_text": "Hello, 世界!",
+        "tenant_id": "00000000-0000-0000-0000-000000000042"
+      },
+      "expected_output": "7caa95cf8b5b9118721f192d4998515655d570c40be02c4c8402a201c6e2f7e5"
+    },
+    {
+      "id": "FXP5",
+      "fn": "compute_prompt_hash",
+      "description": "UTF-8 BOM-prefixed prompt (non-ASCII whitespace preserved)",
+      "inputs": {
+        "prompt_text": "test prompt",
+        "tenant_id": "00000000-0000-0000-0000-000000000007"
+      },
+      "expected_output": "83476ff5befaf561d2b1b72b8dd803f2dce55219abb0041ee283cd451e6e8d66"
+    },
+    {
+      "id": "FXP6",
+      "fn": "compute_prompt_hash",
+      "description": "Embedded control characters NUL/BEL/VT preserved",
+      "inputs": {
+        "prompt_text": "before\u0000\u0007\u000bafter",
+        "tenant_id": "tenant-control"
+      },
+      "expected_output": "25274faa082e3f462b3956657b1e7f4624f4210f863b755e497349693013f8c7"
+    },
+    {
+      "id": "FXP7",
+      "fn": "compute_prompt_hash",
+      "description": "10KB ASCII prompt + non-UUID tenant",
+      "inputs": {
+        "prompt_text": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "tenant_id": "tenant-long"
+      },
+      "expected_output": "b4c8c062972c201681f906fbb86560d6304628bf0664d5375929cbc9379fa88d"
+    },
+    {
+      "id": "FXP8",
+      "fn": "compute_prompt_hash",
+      "description": "Mixed-case UUID tenant (canonicaliser lowercases hex)",
+      "inputs": {
+        "prompt_text": "hello world",
+        "tenant_id": "ABCDEF12-3456-7890-ABCD-EF1234567890"
+      },
+      "expected_output": "27ad8586fff06972454564d1fe1f447877a52807142815d2eb3e03f962152486"
+    },
+    {
+      "id": "FXU1",
+      "fn": "derive_uuid_from_signature",
+      "description": "decision_id scope",
+      "inputs": {
+        "signature": "sig-abc",
+        "scope": "decision_id"
+      },
+      "expected_output": "5f870046-6d3e-4e1d-87bd-d3cbb46ec8e8"
+    },
+    {
+      "id": "FXU2",
+      "fn": "derive_uuid_from_signature",
+      "description": "llm_call_id scope (same sig as FXU1)",
+      "inputs": {
+        "signature": "sig-abc",
+        "scope": "llm_call_id"
+      },
+      "expected_output": "7c0559d1-18d5-4a6b-9e3e-22a039284498"
+    },
+    {
+      "id": "FXU3",
+      "fn": "derive_uuid_from_signature",
+      "description": "audit_chain scope",
+      "inputs": {
+        "signature": "audit-row-v1|tenant-a|2026-06-07",
+        "scope": "audit_chain"
+      },
+      "expected_output": "443453c9-c3d0-4638-a95e-f30abcf3e000"
+    },
+    {
+      "id": "FXU4",
+      "fn": "derive_uuid_from_signature",
+      "description": "Custom scope string",
+      "inputs": {
+        "signature": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "scope": "custom-test-scope"
+      },
+      "expected_output": "cf460197-b943-49a9-b936-dfb4b830c9b2"
+    },
+    {
+      "id": "FXOA1",
+      "fn": "derive_agent_signature",
+      "description": "D08 openai_agents — simple string input, no system instructions",
+      "inputs": {
+        "input": "Say hi",
+        "system_instructions": null
+      },
+      "expected_output": "0b8e468f6a5faab3cf0459d24035a33c"
+    },
+    {
+      "id": "FXOA2",
+      "fn": "derive_agent_signature",
+      "description": "D08 openai_agents — string input + system instructions",
+      "inputs": {
+        "input": "Say hi",
+        "system_instructions": "Be polite"
+      },
+      "expected_output": "bb805e8a571a9ee6772e1b3985575deb"
+    },
+    {
+      "id": "FXOA3",
+      "fn": "derive_agent_signature",
+      "description": "D08 openai_agents — short ASCII input + sys instructions (string-shape, cross-language byte-equal)",
+      "inputs": {
+        "input": "tools test",
+        "system_instructions": "Use the calculator tool"
+      },
+      "_note": "v0.1.x cross-language byte equality is limited to string-shape inputs because Python repr(list-of-dict) and TS JSON.stringify(list-of-dict) emit different byte sequences (single vs double quotes). The TS adapter falls back to JSON.stringify for non-string inputs, the Python adapter uses repr; the design.md §8 rendering quirk documents this divergence. A future v2.json could mint a canonical JSON form on both sides to close this gap; for now, FXOA* rows ship string-input only.",
+      "expected_output": "d2b0f7783bcbf3be27cc841b98e4c4ec"
+    },
+    {
+      "id": "FXOA4",
+      "fn": "derive_agent_signature",
+      "description": "D08 openai_agents — empty string input + empty system",
+      "inputs": {
+        "input": "",
+        "system_instructions": ""
+      },
+      "expected_output": "7d6395228c93bac41591f4c6b65aea03"
+    },
+    {
+      "id": "FXOA5",
+      "fn": "derive_agent_signature",
+      "description": "D08 openai_agents — multi-byte UTF-8 input + CJK tenant",
+      "inputs": {
+        "input": "Hello, 世界!",
+        "system_instructions": null
+      },
+      "expected_output": "3941e46a71c2a2cf4b196f5bb6c21e87"
+    },
+    {
+      "id": "FXOA1_IK",
+      "fn": "derive_idempotency_key",
+      "description": "D08 openai_agents — FXOA1 signature → idempotencyKey for runId=r-1",
+      "inputs": {
+        "tenant_id": "t-1",
+        "session_id": "s-1",
+        "run_id": "r-1",
+        "step_id": "r-1:oai-call:0b8e468f6a5faab3",
+        "llm_call_id": "9fa6e431-89e0-403e-8eee-2b252a7bd77c",
+        "trigger": "LLM_CALL_PRE"
+      },
+      "expected_output": "sg-e4d1ba4a538f53e1f25839e227de8f1f"
+    },
+    {
+      "id": "FXOA1_DEC",
+      "fn": "derive_uuid_from_signature",
+      "description": "D08 openai_agents — FXOA1 signature → decision_id UUID",
+      "inputs": {
+        "signature": "0b8e468f6a5faab3cf0459d24035a33c",
+        "scope": "decision_id"
+      },
+      "expected_output": "b18ca2dd-a146-4d69-952f-c6215b6b4d75"
+    },
+    {
+      "id": "FXOA1_LLM",
+      "fn": "derive_uuid_from_signature",
+      "description": "D08 openai_agents — FXOA1 signature → llm_call_id UUID",
+      "inputs": {
+        "signature": "0b8e468f6a5faab3cf0459d24035a33c",
+        "scope": "llm_call_id"
+      },
+      "expected_output": "9fa6e431-89e0-403e-8eee-2b252a7bd77c"
+    }
+  ]
+}