@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/templates/project/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev --test-scheduled",
+    "deploy": "wrangler deploy",
+    "deploy:testnet": "wrangler deploy --env testnet",
+    "deploy:production": "wrangler deploy --env production",
+    "build": "wrangler deploy --dry-run --outdir dist",
+    "cf-typegen": "wrangler types --env-interface Env --include-runtime=false",
+    "db:migrate": "wrangler d1 migrations apply {{name}} --local",
+    "db:migrate:remote": "wrangler d1 migrations apply {{name}} --remote",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "check": "bun run typecheck && bun run lint && bun run test"
+  },
+  "dependencies": {
+    "@ixo/decision-oracle": "{{packageVersion}}"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@cloudflare/workers-types": "^5.20260910.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.146.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  }
+}

package/templates/project/src/facts/index.ts

@@ -0,0 +1,19 @@
+import { defineFacts } from "@ixo/decision-oracle/facts";
+
+/**
+ * How this oracle produces the facts a rubric asks for. List only the names you answer yourself;
+ * every other declared source runs the stock lane (a UCAN-signed POST to the declared endpoint)
+ * and every other AI check runs OpenRouter with the rubric's own instructions.
+ *
+ *   bunx decision-oracle protocol review <protocol did>   — what the rubric declares, and which names need a handler
+ *   bunx decision-oracle facts scaffold <protocol did>    — stubs + tests for those names
+ */
+export const facts = defineFacts({
+  ext: {
+    // deliveryConfirmed: async ({ send }, tools) => {
+    //   const res = await tools.http.json(`https://courier.example/deliveries/${send.reference}`);
+    //   return res.ok && res.body?.status === "delivered";
+    // },
+  },
+  ai: {},
+});

package/templates/project/src/index.ts

@@ -0,0 +1,25 @@
+import { defineOracle } from "@ixo/decision-oracle";
+import { facts } from "./facts";
+
+/**
+ * Your oracle. Deployment values (hosts, DIDs, keys) live in wrangler.jsonc vars and .dev.vars —
+ * this file is what the oracle IS: its listing, its price, its policies, and how it produces facts.
+ */
+const oracle = defineOracle({
+  name: "{{name}}",
+  description: "Evaluates claims against the collection's rubric via the IXO decision engine.",
+  // The protocol entity DIDs this oracle serves (GET /v1/info; enforced at register). [] ⇒ any.
+  supportedProtocols: [],
+  // The minimum on-chain evaluation payment a collection must carry (integer base units).
+  pricing: { evaluation: { denom: "uixo", minAmount: "1000000" } },
+  policies: {
+    autoSign: true,
+    allowAiChecks: true,
+    allowImageChecks: true,
+    allowStandingApprovals: false,
+  },
+  facts,
+});
+
+export default oracle;
+export const { ClaimIngest, ReviewComplete, SequenceManagerDO } = oracle;

package/templates/project/test/api-lane.test.ts

@@ -0,0 +1,57 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestHarness } from "wrangler";
+
+/**
+ * Boots THIS project's worker — wrangler.jsonc, src/index.ts, the installed package — the way
+ * `bun run dev` does, and proves the Decision API lane switch: on, it serves its contract; off
+ * (the shipped default), it exposes nothing. None of these routes reaches D1.
+ */
+const lane = (on: boolean) => ({
+  workers: [
+    {
+      configPath: "./wrangler.jsonc",
+      vars: { API_LANE: String(on), ORACLE_HOSTNAME: "oracle.test" },
+      // The config refuses to start the lane without either.
+      secrets: {
+        WEBHOOK_ENCRYPTION_KEY: "test-only-webhook-encryption-key",
+        UNIQUE_HMAC_KEY: "test-only-unique-hmac-key",
+      },
+    },
+  ],
+});
+
+const server = createTestHarness(lane(true));
+
+beforeAll(async () => {
+  await server.listen();
+}, 60_000);
+
+afterAll(async () => {
+  await server.close();
+});
+
+describe("the Decision API lane", () => {
+  it("serves its contract when API_LANE is on", async () => {
+    const openapi = await server.fetch("/v1/api/openapi.json");
+    expect(openapi.status).toBe(200);
+    const doc = (await openapi.json()) as { openapi: string; servers: { url: string }[] };
+    expect(doc.openapi).toMatch(/^3\.1/);
+    expect(doc.servers[0]?.url).toBe("https://oracle.test");
+
+    const llms = await server.fetch("/llms.txt");
+    expect(llms.status).toBe(200);
+    expect(await llms.text()).toContain("https://oracle.test/v1/api/openapi.json");
+
+    const keys = await server.fetch("/v1/api/keys");
+    expect(keys.status).toBe(401);
+    expect(await keys.json()).toMatchObject({
+      error: { code: "UNAUTHORIZED", requestId: expect.any(String), docsUrl: expect.any(String) },
+    });
+  });
+
+  it("exposes nothing when API_LANE is off", async () => {
+    await server.update(lane(false));
+    expect((await server.fetch("/v1/api/openapi.json")).status).toBe(404);
+    expect((await server.fetch("/llms.txt")).status).toBe(404);
+  }, 60_000);
+});

package/templates/project/test/facts.test.ts

@@ -0,0 +1,14 @@
+import { fakeTools, runFacts, sampleClaim, sampleManifest } from "@ixo/decision-oracle/testing";
+import { describe, expect, it } from "vitest";
+import { facts } from "../src/facts";
+
+describe("facts", () => {
+  it("produces exactly what the manifest declares", async () => {
+    const out = await runFacts(facts, {
+      claim: sampleClaim({ reference: "ABC" }),
+      manifest: sampleManifest({}),
+      tools: fakeTools(),
+    });
+    expect(out.issues).toEqual([]);
+  });
+});

package/templates/project/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext"],
+    "types": ["@cloudflare/workers-types"],
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+
+    "noEmit": true
+  },
+  "include": ["src", "test", "worker-configuration.d.ts"],
+  "exclude": ["node_modules", "dist", ".wrangler"]
+}

package/templates/project/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Handler tests are plain node: `runFacts` runs the same runner production does, with fake tools
+ * instead of the network — no Worker, no D1, no workers pool to boot. The one worker-level test
+ * (test/api-lane.test.ts) boots the real worker from node too, through wrangler's test harness.
+ */
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["test/**/*.test.ts"],
+  },
+});

package/templates/project/wrangler.jsonc

@@ -0,0 +1,446 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "{{name}}",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-07-07",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // The Custom Domain IS the did:web identity — it must equal ORACLE_HOSTNAME below.
+  // "routes": [{ "pattern": "<your ORACLE_HOSTNAME>", "custom_domain": true }],
+
+  // D1 is the oracle's database: the ledger tables the package owns. `migrations_dir` points INTO
+  // the installed package — the schema ships with it, you never generate a migration. Create the
+  // database once and paste the id here; the placeholder is fine for local dev and tests.
+  //   wrangler d1 create {{name}} && bun run db:migrate
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "{{name}}",
+      "database_id": "<create with: wrangler d1 create {{name}}>",
+      "migrations_dir": "node_modules/@ixo/decision-oracle/migrations"
+    }
+  ],
+
+  // Without this the deployed bundle is minified and every stack trace points at one anonymous
+  // line. Generated and uploaded on `wrangler deploy` only — no cold-start or CPU cost.
+  "upload_source_maps": true,
+
+  // Workers Logs: the structured log stream (Observability → Logs) this oracle's counters and
+  // timings ride on. Alerts are configured there.
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1,
+    // Workers Traces are optional (docs/guide.md "Traces"): each span is billed as one log event
+    // from 2026-10-01. Uncommenting this traces every env that has no `observability` block of its
+    // own — uncomment testnet's and production's blocks below too (lower rates) before you do.
+    // "traces": { "enabled": true, "head_sampling_rate": 1 },
+    "logs": { "enabled": true }
+  },
+
+  // KV: caches only (UCAN principals, peer did:web documents, the engine-registered marker, chain
+  // grants, the C2PA trust list). Nothing here is a source of truth — it can be emptied any time.
+  //   wrangler kv namespace create CACHE_KV
+  "kv_namespaces": [
+    {
+      "binding": "CACHE_KV",
+      "id": "<create with: wrangler kv namespace create CACHE_KV>"
+    }
+  ],
+
+  // A coarse per-IP guard on the whole API — edge-enforced, best-effort. limit/period live HERE,
+  // not in code; `period` must be 10 or 60. A no-op in local dev and tests.
+  "ratelimits": [
+    {
+      "name": "API_RATE_LIMITER",
+      "namespace_id": "1001",
+      "simple": { "limit": 100, "period": 60 }
+    },
+    // The Decision API lane's per-key / per-source limit — its own namespace, read only when
+    // API_LANE is on. Placeholder numbers until you have load-tested your own traffic.
+    {
+      "name": "API_KEY_RATE_LIMITER",
+      "namespace_id": "1002",
+      "simple": { "limit": 600, "period": 60 }
+    }
+  ],
+
+  // R2 for the Decision API lane's uploads — optional: absent means the upload route answers 501
+  // and URL attachments still work. Only worth it with API_LANE on.
+  //   wrangler r2 bucket create {{name}}-uploads
+  // "r2_buckets": [{ "binding": "API_UPLOADS", "bucket_name": "{{name}}-uploads" }],
+  //
+  // R2 for the answer archive — optional: bound means every evaluated ask, answer and photo is kept
+  // under <askId>-<title>/ (docs/guide.md, "The answer archive"). It holds exact locations and photos: keep the bucket PRIVATE. Both buckets share
+  // the one "r2_buckets" array.
+  //   wrangler r2 bucket create {{name}}-answers
+  // "r2_buckets": [{ "binding": "ANSWERS_ARCHIVE", "bucket_name": "{{name}}-answers" }],
+
+  // Workers Analytics Engine for p50/p95/p99 and rates — optional: absent means every metric stays
+  // a `msg = "metric"` log line only. The dataset is created on first write; one per environment,
+  // and a distinct dataset per oracle if you run several on one account. Cloudflare's docs publish
+  // no character rule for dataset names, but the name is the table in the SQL API (`FROM <name>`),
+  // where a `-` would need quoting in every query — keep to letters, digits and `_`.
+  // "analytics_engine_datasets": [{ "binding": "METRICS", "dataset": "eval_oracle_metrics_devnet" }],
+
+  // Email: pause / resume / review-request notices to a collection's contact address. The sending
+  // domain is onboarded once, out of band (`wrangler email sending enable <domain>`); until then
+  // the lane logs and skips — a bounced notice never fails a workflow step.
+  //
+  // NO `remote: true` here, deliberately: this block is what local dev and the test runner read,
+  // and a remote binding opens a real proxy session (Cloudflare credentials, one unambiguous
+  // account). Local dev simulates instead — a dev run must never email a real customer.
+  "send_email": [{ "name": "EMAIL" }],
+
+  // Durable, checkpointed claim ingestion and review folds. Both classes come from the package and
+  // are re-exported by src/index.ts; the runtime instantiates them BY EXPORT, so the names here and
+  // the exports there must stay in step. Workflow NAMES are account-global — they carry the project
+  // name (and, below, the env) so two oracles in one Cloudflare account never collide.
+  "workflows": [
+    {
+      "name": "{{name}}-claim-ingest",
+      "binding": "CLAIM_WORKFLOW",
+      "class_name": "ClaimIngest"
+    },
+    {
+      "name": "{{name}}-review-complete",
+      "binding": "REVIEW_WORKFLOW",
+      "class_name": "ReviewComplete"
+    }
+  ],
+
+  // The sequence keeper for the `MsgEvaluateClaim` chain write: one instance per signer address,
+  // allocating account sequence numbers atomically so concurrent workflow steps signing from the
+  // ONE oracle account never race.
+  "durable_objects": {
+    "bindings": [{ "name": "SEQUENCE_MANAGER", "class_name": "SequenceManagerDO" }]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["SequenceManagerDO"]
+    }
+  ],
+
+  // Three triggers, one tier each (the package's cron/scan.ts CRON_TIERS) — keep all three, or that
+  // tier's jobs never run: every minute the claim scan, resumes and webhooks; every five minutes
+  // the AI-cost backfill and the payment reconcile; hourly housekeeping, reminders and re-checks.
+  // Locally crons don't fire on a schedule — run `bun run dev` (it passes --test-scheduled), then
+  // `curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"` (or `*/5+*+*+*+*`, `0+*+*+*+*`).
+  "triggers": {
+    "crons": ["* * * * *", "*/5 * * * *", "0 * * * *"]
+  },
+
+  // Non-secret runtime config. Secrets go in .dev.vars locally (see .dev.vars.example) and via
+  // `wrangler secret put <NAME>` once deployed — never here.
+  "vars": {
+    "ENVIRONMENT": "development",
+    "LOG_LEVEL": "debug",
+    "SERVICE_NAME": "{{name}}",
+    "SERVICE_VERSION": "0.1.0",
+    "CORS_ORIGINS": "*",
+    // Watched collections visited per cron tick — raise it for a large fleet.
+    "CRON_COLLECTIONS_PER_TICK": "25",
+    // Read by the sequence keeper: the minimum gap between two sequence allocations from the
+    // oracle account. 1s spaces broadcasts so each tx reaches the mempool before the next signs.
+    "IXO_CLIENT_SEQUENCE_MIN_DELAY_MS": "1000",
+
+    // The network this oracle serves. Every per-network URL (engine, blocksync, matrix, UCAN
+    // store, VFS, IPFS gateway, RPC, portal) defaults from it — set one of those vars only to
+    // override.
+    "IXO_NETWORK": "devnet",
+    // The coin (and minimum, integer base units) a collection's on-chain evaluation payment must
+    // pay this oracle in — register refuses any other denom (402). It replaces `pricing.evaluation`
+    // from `defineOracle`. devnet/testnet: a stand-in coin is fine (`uixo`). mainnet: REQUIRED,
+    // and real USDC (see the production env) — the oracle refuses to start without it.
+    "EVALUATION_DENOM": "uixo",
+    "EVALUATION_MIN_AMOUNT": "1000000",
+
+    // THIS oracle's did:web host — the audience every inbound UCAN invocation must name, and the
+    // issuer of every invocation this oracle mints. It must equal the Custom Domain in `routes`
+    // for the env you deploy: callers resolve you by fetching https://<host>/.well-known/did.json.
+    "ORACLE_HOSTNAME": "<REPLACE: the host your did:web is served from>",
+
+    // This oracle's PUBLIC chain identifiers, printed together by `bunx decision-oracle derive`.
+    // Config, not credentials: the keys that prove them are secrets (.dev.vars). ORACLE_ADDRESS
+    // must be the ORACLE_SECP_MNEMONIC wallet's address — asserted at first use, fails loud.
+    "ORACLE_DID": "did:ixo:<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
+    "ORACLE_ADDRESS": "<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
+    "ORACLE_MATRIX_USER_ID": "@did-ixo-<REPLACE_WITH_YOUR_ORACLE_ADDRESS>:devmx.ixo.earth",
+
+    // The on-chain oracle ENTITY (did:ixo:entity:…, from `bunx decision-oracle oracle init`) — a
+    // different DID from ORACLE_DID. The portal resolves this oracle's API from its `#eval`
+    // service, so the Matrix review card names it. "" ⇒ unset: the card falls back to ORACLE_DID
+    // and a review can only be answered from the portal's claim page, not from chat.
+    "ORACLE_ENTITY_DID": "",
+
+    // The pinned model for AI checks (any provider), and the C2PA
+    // image-provenance gate — a cryptographically verified AI-generated manifest fails an AI check
+    // outright (fail-safe: it can only ever ADD a rejection).
+    "AI_CHECK_MODEL": "openai/gpt-6-luna",
+    // AI provider (README "Configuration"): the AI Gateway by default — the `ai` binding plus the
+    // gateway's name; OpenRouter instead with AI_PROVIDER=openrouter + the OPENROUTER_API_KEY secret.
+    // Local dev has no `ai` binding (it is remote-only: `wrangler dev` would need a login, and the
+    // test harness can't run one) — an AI fact here throws "AI binding not configured". To run AI
+    // checks locally, add `"ai": { "binding": "AI" }` at this level, or use AI_PROVIDER=openrouter.
+    "AI_PROVIDER": "cloudflare",
+    // "AI_AUDIO_VIDEO": "false", // audio/video inputs — OpenRouter only
+    // "AI_GATEWAY_ID": "<your gateway>",
+    "C2PA_IMAGE_CHECK": "true",
+
+    // Sign `MsgEvaluateClaim` on a terminal verdict automatically. "false" ⇒ decisions are
+    // recorded and receipted, but a human submits them from the portal.
+    "AUTO_SIGN": "true",
+
+    // The Decision API lane: paid, off-chain claims over HTTP at /v1/api. Dormant until API_LANE is
+    // "true"; with API_PAYMENTS "false" new submits answer 503 payments-disabled, so nothing is
+    // ever accepted unpaid. Turning it on also needs the WEBHOOK_ENCRYPTION_KEY secret (see
+    // .dev.vars.example) — without it the worker refuses to start. The rest stay commented until
+    // you turn the lane on — an empty string fails config validation. Flip it per env below.
+    "API_LANE": "false",
+    "API_PAYMENTS": "false"
+    // "API_PRICE_USD_CENTS": "120",
+    // "X402_FACILITATOR_URL": "https://<facilitator host>",
+    // "X402_NETWORK": "cosmos:devnet-1",
+    // Where your earnings land (your own accounts; each offer's payTo). Unset ⇒ that way to pay is not offered.
+    // "EARNINGS_ADDRESS": "ixo1<your account>",
+    // "EARNINGS_BASE_WALLET": "0x<your Base wallet>",
+    // "BILLING_ENGINE_URL": "https://<billing-engine host>",
+    // "CONSOLE_URL": "https://<console host>",
+    // The OAuth server of /v1/mcp (MCP over OAuth); defaults per IXO_NETWORK — set for a local AuthHub.
+    // "AUTH_HUB_URL": "https://<authhub host>",
+    // "ORACLE_ADMIN_DIDS": "did:ixo:<admin>,did:ixo:<admin>",
+    // Read-only access to GET /v1/admin/status for a monitoring service (any DID method, e.g. your
+    // decision engine's status board by its did:web). Never an oracle admin: it reaches nothing else.
+    // "STATUS_READER_DIDS": "did:web:<monitor host>",
+
+    // The From address/name on pause, resume and review notices. Unset ⇒ the email lane logs once
+    // and skips. Commented, not blank: an empty string fails config validation.
+    // "EMAIL_FROM_ADDRESS": "oracle@your-domain",
+    // "EMAIL_FROM_NAME": "Your Oracle",
+
+    // Sentry tuning — only matters with the SENTRY_DSN secret set. Unset ⇒ 0.1 of requests traced
+    // and the environment tag is ENVIRONMENT. (OPS_ALERT_WEBHOOK_URL, for Slack alerts, is a
+    // secret: .dev.vars.example.)
+    // "SENTRY_TRACES_SAMPLE_RATE": "1",
+    // "SENTRY_ENVIRONMENT": "devnet"
+  },
+
+  "env": {
+    "testnet": {
+      // Without this the worker deploys as "<top-level name>-testnet" anyway — naming it here
+      // keeps the deployed name explicit and independent of the top-level one.
+      "name": "{{name}}-testnet",
+      // The Custom Domain IS the identity: it must equal ORACLE_HOSTNAME below. Declared here so
+      // the deploy attaches it (and its DNS record) instead of it being a dashboard step.
+      "routes": [{ "pattern": "<REPLACE: your testnet host>", "custom_domain": true }],
+      "vars": {
+        "ENVIRONMENT": "staging",
+        "LOG_LEVEL": "info",
+        "SERVICE_NAME": "{{name}}",
+        "SERVICE_VERSION": "0.1.0",
+        "CORS_ORIGINS": "*",
+        "CRON_COLLECTIONS_PER_TICK": "25",
+        "IXO_CLIENT_SEQUENCE_MIN_DELAY_MS": "1000",
+        "IXO_NETWORK": "testnet",
+        // Stand-in coin on testnet (owner ruling: any coin is fine off mainnet).
+        "EVALUATION_DENOM": "uixo",
+        "EVALUATION_MIN_AMOUNT": "1000000",
+        "ORACLE_HOSTNAME": "<REPLACE: your testnet host>",
+        "ORACLE_DID": "did:ixo:<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
+        "ORACLE_ADDRESS": "<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
+        "ORACLE_MATRIX_USER_ID": "@did-ixo-<REPLACE_WITH_YOUR_ORACLE_ADDRESS>:testmx.ixo.earth",
+        "ORACLE_ENTITY_DID": "",
+        "AI_CHECK_MODEL": "openai/gpt-6-luna",
+        // AI provider (README "Configuration"): the AI Gateway by default — the `ai` binding plus the
+        // gateway's name; OpenRouter instead with AI_PROVIDER=openrouter + the OPENROUTER_API_KEY secret.
+        "AI_PROVIDER": "cloudflare",
+        // "AI_AUDIO_VIDEO": "false", // audio/video inputs — OpenRouter only
+        // "AI_GATEWAY_ID": "<your gateway>",
+        "C2PA_IMAGE_CHECK": "true",
+        "AUTO_SIGN": "true",
+        "API_LANE": "false",
+        "API_PAYMENTS": "false"
+        // "API_PRICE_USD_CENTS": "120",
+        // "X402_FACILITATOR_URL": "https://<facilitator host>",
+        // "X402_NETWORK": "cosmos:pandora-8",
+        // Where your earnings land (your own accounts; each offer's payTo). Unset ⇒ that way to pay is not offered.
+        // "EARNINGS_ADDRESS": "ixo1<your account>",
+        // "EARNINGS_BASE_WALLET": "0x<your Base wallet>",
+        // "BILLING_ENGINE_URL": "https://<billing-engine host>",
+        // "CONSOLE_URL": "https://<console host>",
+        // The OAuth server of /v1/mcp (MCP over OAuth); defaults per IXO_NETWORK — set for a local AuthHub.
+        // "AUTH_HUB_URL": "https://<authhub host>",
+        // "ORACLE_ADMIN_DIDS": "did:ixo:<admin>",
+        // "STATUS_READER_DIDS": "did:web:<monitor host>",
+
+        // "EMAIL_FROM_ADDRESS": "oracle@your-domain",
+        // "EMAIL_FROM_NAME": "Your Oracle",
+
+        // "SENTRY_TRACES_SAMPLE_RATE": "0.2",
+        // "SENTRY_ENVIRONMENT": "testnet"
+      },
+
+      // Optional Workers Traces for this env (billed per span from 2026-10-01): `observability` is
+      // inherited whole, so uncommenting this replaces the top-level block — traces 20%.
+      // "observability": {
+      //   "enabled": true,
+      //   "head_sampling_rate": 1,
+      //   "traces": { "enabled": true, "head_sampling_rate": 0.2 },
+      //   "logs": { "enabled": true }
+      // },
+
+      // Every binding and the `vars` block are redeclared per env — those inherit nothing from the
+      // top level (unlike `main`, `compatibility_date`, `triggers`, `migrations`, `observability`).
+      //   wrangler d1 create {{name}}-testnet
+      "ai": { "binding": "AI" },
+      "d1_databases": [
+        {
+          "binding": "DB",
+          "database_name": "{{name}}-testnet",
+          "database_id": "<TESTNET_D1_ID>",
+          "migrations_dir": "node_modules/@ixo/decision-oracle/migrations"
+        }
+      ],
+      "kv_namespaces": [{ "binding": "CACHE_KV", "id": "<TESTNET_CACHE_KV_ID>" }],
+      "ratelimits": [
+        {
+          "name": "API_RATE_LIMITER",
+          "namespace_id": "1001",
+          "simple": { "limit": 100, "period": 60 }
+        },
+        {
+          "name": "API_KEY_RATE_LIMITER",
+          "namespace_id": "1002",
+          "simple": { "limit": 600, "period": 60 }
+        }
+      ],
+      //   wrangler r2 bucket create {{name}}-uploads-testnet
+      // "r2_buckets": [{ "binding": "API_UPLOADS", "bucket_name": "{{name}}-uploads-testnet" }],
+      //   wrangler r2 bucket create {{name}}-answers-testnet
+      // "r2_buckets": [{ "binding": "ANSWERS_ARCHIVE", "bucket_name": "{{name}}-answers-testnet" }],
+      // "analytics_engine_datasets": [{ "binding": "METRICS", "dataset": "eval_oracle_metrics_testnet" }],
+      "send_email": [{ "name": "EMAIL", "remote": true }],
+      "workflows": [
+        {
+          "name": "{{name}}-claim-ingest-testnet",
+          "binding": "CLAIM_WORKFLOW",
+          "class_name": "ClaimIngest"
+        },
+        {
+          "name": "{{name}}-review-complete-testnet",
+          "binding": "REVIEW_WORKFLOW",
+          "class_name": "ReviewComplete"
+        }
+      ],
+      "durable_objects": {
+        "bindings": [{ "name": "SEQUENCE_MANAGER", "class_name": "SequenceManagerDO" }]
+      }
+    },
+
+    "production": {
+      "name": "{{name}}-production",
+      "routes": [{ "pattern": "<REPLACE: your production host>", "custom_domain": true }],
+      "vars": {
+        "ENVIRONMENT": "production",
+        "LOG_LEVEL": "info",
+        "SERVICE_NAME": "{{name}}",
+        "SERVICE_VERSION": "0.1.0",
+        "CORS_ORIGINS": "*",
+        "CRON_COLLECTIONS_PER_TICK": "25",
+        "IXO_CLIENT_SEQUENCE_MIN_DELAY_MS": "1000",
+        "IXO_NETWORK": "mainnet",
+        // Real USDC on mainnet — Noble USDC over IBC (transfer/channel-26/uusdc, 6 decimals), never a
+        // stand-in. REQUIRED here: config validation fails at isolate start without it. 1000000 = 1 USDC.
+        "EVALUATION_DENOM": "ibc/6BBE9BD4246F8E04948D5A4EEE7164B2630263B9EBB5E7DC5F0A46C62A2FF97B",
+        "EVALUATION_MIN_AMOUNT": "1000000",
+        "ORACLE_HOSTNAME": "<REPLACE: your production host>",
+        "ORACLE_DID": "did:ixo:<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
+        "ORACLE_ADDRESS": "<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
+        "ORACLE_MATRIX_USER_ID": "@did-ixo-<REPLACE_WITH_YOUR_ORACLE_ADDRESS>:mx.ixo.earth",
+        "ORACLE_ENTITY_DID": "",
+        "AI_CHECK_MODEL": "openai/gpt-6-luna",
+        // AI provider (README "Configuration"): the AI Gateway by default — the `ai` binding plus the
+        // gateway's name; OpenRouter instead with AI_PROVIDER=openrouter + the OPENROUTER_API_KEY secret.
+        "AI_PROVIDER": "cloudflare",
+        // "AI_AUDIO_VIDEO": "false", // audio/video inputs — OpenRouter only
+        // "AI_GATEWAY_ID": "<your gateway>",
+        "C2PA_IMAGE_CHECK": "true",
+        "AUTO_SIGN": "true",
+        "API_LANE": "false",
+        "API_PAYMENTS": "false"
+        // "API_PRICE_USD_CENTS": "120",
+        // "X402_FACILITATOR_URL": "https://<facilitator host>",
+        // "X402_NETWORK": "cosmos:ixo-5",
+        // Where your earnings land (your own accounts; each offer's payTo). Unset ⇒ that way to pay is not offered.
+        // "EARNINGS_ADDRESS": "ixo1<your account>",
+        // "EARNINGS_BASE_WALLET": "0x<your Base wallet>",
+        // "BILLING_ENGINE_URL": "https://<billing-engine host>",
+        // "CONSOLE_URL": "https://<console host>",
+        // The OAuth server of /v1/mcp (MCP over OAuth); defaults per IXO_NETWORK — set for a local AuthHub.
+        // "AUTH_HUB_URL": "https://<authhub host>",
+        // "ORACLE_ADMIN_DIDS": "did:ixo:<admin>",
+        // "STATUS_READER_DIDS": "did:web:<monitor host>",
+
+        // "EMAIL_FROM_ADDRESS": "oracle@your-domain",
+        // "EMAIL_FROM_NAME": "Your Oracle",
+
+        // "SENTRY_TRACES_SAMPLE_RATE": "0.1",
+        // "SENTRY_ENVIRONMENT": "mainnet"
+      },
+
+      // Optional Workers Traces for this env (billed per span from 2026-10-01): `observability` is
+      // inherited whole, so uncommenting this replaces the top-level block — traces 5%.
+      // "observability": {
+      //   "enabled": true,
+      //   "head_sampling_rate": 1,
+      //   "traces": { "enabled": true, "head_sampling_rate": 0.05 },
+      //   "logs": { "enabled": true }
+      // },
+
+      //   wrangler d1 create {{name}}-production
+      "ai": { "binding": "AI" },
+      "d1_databases": [
+        {
+          "binding": "DB",
+          "database_name": "{{name}}-production",
+          "database_id": "<PRODUCTION_D1_ID>",
+          "migrations_dir": "node_modules/@ixo/decision-oracle/migrations"
+        }
+      ],
+      "kv_namespaces": [{ "binding": "CACHE_KV", "id": "<PRODUCTION_CACHE_KV_ID>" }],
+      "ratelimits": [
+        {
+          "name": "API_RATE_LIMITER",
+          "namespace_id": "1001",
+          "simple": { "limit": 100, "period": 60 }
+        },
+        {
+          "name": "API_KEY_RATE_LIMITER",
+          "namespace_id": "1002",
+          "simple": { "limit": 600, "period": 60 }
+        }
+      ],
+      //   wrangler r2 bucket create {{name}}-uploads-production
+      // "r2_buckets": [{ "binding": "API_UPLOADS", "bucket_name": "{{name}}-uploads-production" }],
+      //   wrangler r2 bucket create {{name}}-answers-production
+      // "r2_buckets": [{ "binding": "ANSWERS_ARCHIVE", "bucket_name": "{{name}}-answers-production" }],
+      // "analytics_engine_datasets": [{ "binding": "METRICS", "dataset": "eval_oracle_metrics_mainnet" }],
+      "send_email": [{ "name": "EMAIL", "remote": true }],
+      "workflows": [
+        {
+          "name": "{{name}}-claim-ingest-production",
+          "binding": "CLAIM_WORKFLOW",
+          "class_name": "ClaimIngest"
+        },
+        {
+          "name": "{{name}}-review-complete-production",
+          "binding": "REVIEW_WORKFLOW",
+          "class_name": "ReviewComplete"
+        }
+      ],
+      "durable_objects": {
+        "bindings": [{ "name": "SEQUENCE_MANAGER", "class_name": "SequenceManagerDO" }]
+      }
+    }
+  }
+}