@ixo/decision-oracle 0.2.11 → 0.2.13

package/migrations/meta/_journal.json

@@ -183,6 +183,13 @@
       "when": 1792573809270,
       "tag": "0025_openhands",
       "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "6",
+      "when": 1792581171066,
+      "tag": "0026_reviewer_note",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "license": "Apache-2.0",
   "description": "Run an IXO evaluation oracle: pull claims, produce facts with your handlers, let the decision engine decide, sign on chain",
   "keywords": [

package/skills/create-oracle/SKILL.md

@@ -62,7 +62,7 @@ bunx @ixo/decision-oracle init <dir> [--name <project-name>] [--openhands]
 cd <dir> && bun install
 bun run cf-typegen                       # after ANY wrangler.jsonc binding/var change, too
 wrangler d1 create <project-name>        # paste the id into wrangler.jsonc
-wrangler kv namespace create CACHE_KV    # paste the id into wrangler.jsonc
+wrangler kv namespace create <project>-cache   # paste the id into wrangler.jsonc (KV names are per account)
 bun run db:migrate                       # the package's own migrations, applied to the local D1
 cp .dev.vars.example .dev.vars           # git-ignored; secrets only
 ```
@@ -77,19 +77,23 @@ every env) — then follow `add-openhands-support` for who pays, registering and
 ### 1. Identity — two keys
 
 ```bash
-bunx decision-oracle derive --new     # run TWICE
+bunx decision-oracle derive --new --write .dev.vars --as SERVICE_ED25519_MNEMONIC
+bunx decision-oracle derive --new --write .dev.vars
 ```
 
-- Run one: take the mnemonic line and paste it into `.dev.vars` **relabelled** as
-  `SERVICE_ED25519_MNEMONIC=` — `derive` always prints it as `ORACLE_SECP_MNEMONIC=`, so a verbatim
-  paste silently sets the wrong key. This is the did:web key that signs every UCAN invocation this
-  oracle mints and backs `/.well-known/did.json`; ignore the `ORACLE_*` lines this run prints.
-- Run two: the mnemonic is `ORACLE_SECP_MNEMONIC` (the chain wallet that signs `MsgEvaluateClaim`);
-  the same run prints `ORACLE_ADDRESS`, `ORACLE_DID` and `ORACLE_MATRIX_USER_ID` — those three are
-  **public vars**, so they go in `wrangler.jsonc` `vars`, not `.dev.vars`.
+`--write` appends the key to the file (0600) and never prints it — never run `derive --new` without
+it in an agent session, or the mnemonic lands in the transcript.
 
-Also set `ORACLE_HOSTNAME` (the host the did:web is served from — `localhost:8787` locally, and it
-must equal the Custom Domain in `routes` for any env you deploy), `IXO_NETWORK`, and
+- The first is `SERVICE_ED25519_MNEMONIC`: the did:web key that signs every UCAN invocation this
+  oracle mints and backs `/.well-known/did.json`.
+- The second is `ORACLE_SECP_MNEMONIC` (the chain wallet that signs `MsgEvaluateClaim`); it prints
+  `ORACLE_ADDRESS`, `ORACLE_DID` and `ORACLE_MATRIX_USER_ID` — **public vars**, so they go in
+  `wrangler.jsonc` `vars` (top level and every env), not `.dev.vars`.
+
+`ORACLE_HOSTNAME` (the host the did:web is served from) is `localhost:8787` in `.dev.vars` for local
+dev ONLY. Each deployed env's host lives in that env's `wrangler.jsonc` `vars` and must equal its
+Custom Domain in `routes`; a per-env secrets file (`.dev.vars.<env>`) must NOT carry a localhost
+`ORACLE_HOSTNAME`, or `engine register --env-file .dev.vars.<env>` registers localhost. Also put
 `UNIQUE_HMAC_KEY` in `.dev.vars` (any long random string; rotating it orphans every registered
 duplicate digest). `derive "<existing mnemonic>"` uses a wallet the provider already holds instead of
 minting one. `ORACLE_ADDRESS` is asserted against the mnemonic before the first proof or signature:
@@ -308,7 +312,7 @@ where a live token would have skipped (it mints a new Matrix device — not a ca
 ```bash
 bun run db:migrate:remote        # BEFORE the first deploy of the default env; for a named env:
                                  #   bunx wrangler d1 migrations apply DB --remote --env <env>
-bun run deploy                   # or deploy:testnet / deploy:production
+bun run deploy:devnet            # or deploy:testnet / deploy:production (`--env <env>`)
 wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN     # the value step 8 wrote into .dev.vars
 ```
 
@@ -332,7 +336,7 @@ failed check — `identity` means `ORACLE_ENTITY_DID` is missing from that env's
 **Then register with the engine — do it now, don't wait for the first claim:**
 
 ```bash
-bunx decision-oracle engine register --env <env> --env-file .dev.vars
+bunx decision-oracle engine register --env <env> --env-file .dev.vars.<env>
 ```
 
 The chain lane proves its address lazily, on its first `decide`; until then the engine — and the

package/skills/create-rubric/SKILL.md

@@ -110,6 +110,13 @@ default here is the author's call — ask.
   approvals only.
 - Everything a rubric declares under `sources` / `aiChecks` becomes work for whatever oracle is
   hired: a name declared here is a fact someone has to produce. Don't declare one nobody can answer.
+- **A person reads what an AI check says.** When a claim is held for review, the reviewer sees each
+  check's reason beside the answer. Write `aiChecks` instructions so the model reports what it SAW
+  in plain words ("the photo shows a cleared pavement on Main St"), not that a rule held ("the
+  answer is specific and not placeholder text"). Oracles that turn on `policies.reviewerNote` (on
+  by default for Openhands checkers) also give the reviewer a plain-words note of what the answer
+  claims and what no check could verify, so a ReviewTask's `prompt` should ask the one question the
+  person must decide, in plain words.
 
 ## Output contract
 

package/skills/create-rubric/reference/format-cheatsheet.md

@@ -135,6 +135,26 @@ tasks downgrade approve/partial to review → verdict → action.
                "map": { "true": "approve", "false": "reject" } } ] }   // EVERY possible answer mapped
 ```
 
+`assignTo.role` is **routing, not access**: any non-empty name for the lane the review goes to (default
+`"reviewer"`; who may answer is the review gate's business — the company's reviewer grants — never this
+field). `assigneeDid` names ONE person instead; `route.matrixRoom` sends it to a room. Use one or the other.
+
+**Claim-level task** — a `ReviewTask` with NO `forCriterion` that no `ManualScore` binds: the "a person
+gives the final OK" question.
+
+```jsonc
+{ "@type": "ReviewTask", "id": "MED-RT-FINAL", "prompt": "Do you accept this delivery as done?",
+  "show": ["$deliveryPhoto", "$clinicId"], "answer": { "type": "boolean" },
+  "map": { "true": "approve", "false": "reject" } }
+```
+
+- **When it is asked:** on the claim's first decision, whenever the verdict is `review` — beside anything
+  else pending (a held ManualScore, a duplicate hold, a gate with `onFail: "review"`, an errored
+  `onError: "review"` check). A claim the machine approves or rejects outright is never asked.
+- **What the answer does:** its `map` IS the final verdict (several claim-level answers: reject beats
+  partial beats approve). It settles even a capped or errored-check hold — it is the final human authority.
+- To make EVERY claim go to a person, pair it with a gate whose `onFail` is `"review"` and that always holds.
+
 ## Derived values
 
 ```jsonc

package/skills/decision-api-oracle/SKILL.md

@@ -84,7 +84,7 @@ It must list `ext.orderKnown`, `ext.deliveryCodeValid`, `ext.cashReconciled`,
 
 ### 2. Identity
 
-Do `create-oracle` step 1 (two `derive --new` runs; relabel the first as `SERVICE_ED25519_MNEMONIC`;
+Do `create-oracle` step 1 (two `derive --new --write` runs, the first `--as SERVICE_ED25519_MNEMONIC`;
 the second is `ORACLE_SECP_MNEMONIC`) and step 6 (the owner's engine delegation), with:
 
 - the three public lines (`ORACLE_ADDRESS`, `ORACLE_DID`, `ORACLE_MATRIX_USER_ID`) written into BOTH
@@ -125,7 +125,7 @@ deploy — `devnet` in the example, `testnet` / `production` in the template):
 
 ```bash
 bunx wrangler d1 create shipment-delivery-oracle-devnet          # → env.<env> d1 database_id
-bunx wrangler kv namespace create CACHE_KV --env devnet          # → env.<env> kv id
+bunx wrangler kv namespace create <project>-cache-devnet          # → env.<env> kv id
 bunx wrangler r2 bucket create shipment-delivery-oracle-uploads-devnet
 ```
 

package/templates/project/README.md

@@ -30,7 +30,7 @@ Create the two bindings and paste their ids into `wrangler.jsonc` (once per env
 
 ```bash
 wrangler d1 create {{name}}
-wrangler kv namespace create CACHE_KV
+wrangler kv namespace create {{name}}-cache
 bun run db:migrate        # applies the package's migrations to the local D1
 ```
 
@@ -39,7 +39,8 @@ never write a migration.
 
 ## 3. Identity — two keys, two DIDs
 
-`bunx decision-oracle derive --new` prints a fresh mnemonic and the three public vars derived from it.
+`bunx decision-oracle derive --new --write .dev.vars [--as SERVICE_ED25519_MNEMONIC]` writes a fresh
+mnemonic into `.dev.vars` (never printed) and prints the three public vars derived from it.
 Secrets go in `.dev.vars` locally (`cp .dev.vars.example .dev.vars`) and via
 `wrangler secret put <NAME>` once deployed; their public halves are `vars` in `wrangler.jsonc`.
 
@@ -139,7 +140,7 @@ under `/v1` requires a UCAN invocation addressed to `did:web:<ORACLE_HOSTNAME>`.
 ## 7. Deploy and declare yourself on chain
 
 ```bash
-bun run deploy                # or deploy:testnet / deploy:production
+bun run deploy:devnet         # or deploy:testnet / deploy:production
 ```
 
 The Custom Domain in `routes` must equal `ORACLE_HOSTNAME` — the did:web document is served from

package/templates/project/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "wrangler dev --test-scheduled",
     "deploy": "wrangler deploy",
+    "deploy:devnet": "wrangler deploy --env devnet",
     "deploy:testnet": "wrangler deploy --env testnet",
     "deploy:production": "wrangler deploy --env production",
     "build": "wrangler deploy --dry-run --outdir dist",

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>",