@ixo/decision-oracle 0.2.10 → 0.2.12

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

@@ -3,7 +3,8 @@ 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.
+ * and every other AI check runs the stock judge with the rubric's own instructions (the Cloudflare
+ * AI Gateway by default; OpenRouter with AI_PROVIDER=openrouter).
  *
  *   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
@@ -12,7 +13,10 @@ 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";
+    //   // An outage is not a "no": a throw becomes an error fact with the rubric's onError
+    //   // (`throw fact.retryLater(…)` instead retries the whole step later).
+    //   if (!res.ok) throw new Error(`courier answered ${res.status ?? "nothing"}`);
+    //   return res.body?.status === "delivered";
     // },
   },
   ai: {},

package/templates/project/src/index.ts

@@ -10,7 +10,9 @@ const oracle = defineOracle({
   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).
+  // The minimum on-chain evaluation payment a collection must carry (integer base units) — the one
+  // place to change it, except on mainnet, where wrangler.jsonc's EVALUATION_DENOM /
+  // EVALUATION_MIN_AMOUNT (required there, real USDC) replace it. Never PAY: only IXO-run oracles.
   pricing: { evaluation: { denom: "uixo", minAmount: "1000000" } },
   policies: {
     autoSign: true,

package/templates/project/wrangler.jsonc

@@ -39,11 +39,11 @@
 
   // 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
+  //   wrangler kv namespace create {{name}}-cache
   "kv_namespaces": [
     {
       "binding": "CACHE_KV",
-      "id": "<create with: wrangler kv namespace create CACHE_KV>"
+      "id": "<create with: wrangler kv namespace create {{name}}-cache>"
     }
   ],
 
@@ -133,6 +133,8 @@
   // 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 is one of development | staging | production — anything else and the worker
+    // refuses its config (every request 500s, and the log names the var).
     "ENVIRONMENT": "development",
     "LOG_LEVEL": "debug",
     "SERVICE_NAME": "{{name}}",
@@ -148,12 +150,9 @@
     // 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",
+    // The evaluation fee is `pricing.evaluation` in src/index.ts — the ONE place to change it off
+    // mainnet. EVALUATION_DENOM / EVALUATION_MIN_AMOUNT, when set in an env, REPLACE it there (the
+    // production env sets them: mainnet requires them, in real USDC).
 
     // 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`
@@ -226,6 +225,114 @@
   },
 
   "env": {
+    "devnet": {
+      // Without this the worker deploys as "<top-level name>-devnet" anyway — naming it here
+      // keeps the deployed name explicit and independent of the top-level one.
+      "name": "{{name}}-devnet",
+      // 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 devnet 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": "devnet",
+        // No EVALUATION_DENOM / EVALUATION_MIN_AMOUNT: the fee is `pricing.evaluation` (src/index.ts).
+        "ORACLE_HOSTNAME": "<REPLACE: your devnet 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>:devmx.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: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>",
+        // "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": "devnet"
+      },
+
+      // 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}}-devnet
+      "ai": { "binding": "AI" },
+      "d1_databases": [
+        {
+          "binding": "DB",
+          "database_name": "{{name}}-devnet",
+          "database_id": "<DEVNET_D1_ID>",
+          "migrations_dir": "node_modules/@ixo/decision-oracle/migrations"
+        }
+      ],
+      "kv_namespaces": [{ "binding": "CACHE_KV", "id": "<DEVNET_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-devnet
+      // "r2_buckets": [{ "binding": "API_UPLOADS", "bucket_name": "{{name}}-uploads-devnet" }],
+      //   wrangler r2 bucket create {{name}}-answers-devnet
+      // "r2_buckets": [{ "binding": "ANSWERS_ARCHIVE", "bucket_name": "{{name}}-answers-devnet" }],
+      // "analytics_engine_datasets": [{ "binding": "METRICS", "dataset": "eval_oracle_metrics_devnet" }],
+      "send_email": [{ "name": "EMAIL", "remote": true }],
+      "workflows": [
+        {
+          "name": "{{name}}-claim-ingest-devnet",
+          "binding": "CLAIM_WORKFLOW",
+          "class_name": "ClaimIngest"
+        },
+        {
+          "name": "{{name}}-review-complete-devnet",
+          "binding": "REVIEW_WORKFLOW",
+          "class_name": "ReviewComplete"
+        }
+      ],
+      "durable_objects": {
+        "bindings": [{ "name": "SEQUENCE_MANAGER", "class_name": "SequenceManagerDO" }]
+      }
+    },
     "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.
@@ -242,9 +349,7 @@
         "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",
+        // No EVALUATION_DENOM / EVALUATION_MIN_AMOUNT: the fee is `pricing.evaluation` (src/index.ts).
         "ORACLE_HOSTNAME": "<REPLACE: your testnet host>",
         "ORACLE_DID": "did:ixo:<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",
         "ORACLE_ADDRESS": "<REPLACE_WITH_YOUR_ORACLE_ADDRESS>",