@ixo/decision-oracle 0.2.5 → 0.2.6

package/migrations/meta/_journal.json

@@ -176,6 +176,13 @@
       "when": 1792009954775,
       "tag": "0024_pending_task_details",
       "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "6",
+      "when": 1792573809270,
+      "tag": "0025_openhands",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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/README.md

@@ -13,7 +13,7 @@ installed package (leaving any skill of your own in that directory alone).
 | `create-collection` | creating a claim collection an oracle can be hired against |
 | `decision-api-client` | testing a Decision API oracle from the customer side: devnet test credentials (source, keys, payment delegation), the SDK and CLI smoke, MCP from Claude Code, the docs agent test |
 | `decision-api-oracle` | turning on, deploying and verifying the Decision API lane — the shipment-delivery example (SwiftDrop Express) on devnet end to end: publish, identity, Cloudflare, deploy, engine registration (payable at once), operator, verify, emails |
-| `add-openhands-support` | making an oracle hireable from the Openhands app (asks, the Yoma youth world): the hire/scan adapter, the bridge's fact names, pricing, the picker's card fields, engine registration |
+| `add-openhands-support` | making an oracle hireable from the Openhands app (asks, the Yoma youth world): the OpenHands add-on (`init --openhands`), who pays for decisions, the account to register with, the picker's card, the bridge's fact names for a General checker |
 
 `reference/engine-contract.md` (here, beside the skills) is the decision engine's contract —
 background for all eight, not an interface anyone codes against.

package/skills/add-openhands-support/SKILL.md

@@ -1,114 +1,124 @@
 ---
 name: add-openhands-support
-description: Use when an oracle built on @ixo/decision-oracle should be hireable from the Openhands Network app (asks, quests, the Yoma youth world) — "make my oracle work with Openhands", an oracle missing from the Openhands checker picker, a hire nudge that 404s, an ask whose claims are never judged, or FACT_MISSING on judgeN / withinRadiusN / openhandsSite names.
+description: Use when an oracle built on @ixo/decision-oracle should be hireable from the Openhands Network app (asks, quests, the Yoma youth world) — "make my oracle work with Openhands", "init --openhands", an oracle missing from the Openhands checker picker, a hire call that 404s or 409s, an ask whose claims are never judged, or FACT_MISSING on judgeN / withinRadiusN / openhandsSite names.
 ---
 
 # Adding Openhands support to an oracle
 
 ## Overview
 
-An Openhands ask is its OWN protocol: the app writes a rubric per ask from the poster's sentence
-(`bridge.ts toEngineRubric`), escrows the pay, grants a **meta-authorization** to the checker the
-poster picked, and nudges that checker's `#eval` endpoint. A plain `decision-oracle init` project can
-do none of the Openhands half: it has no hire/scan routes, cannot mint its own evaluate grant from
-a meta-grant, does not answer the bridge's fact names, and is filtered out of the picker. This
-skill adds that adapter. The engine still decides; nothing here judges.
+The Openhands app lets anyone post an ask and pick the oracle ("checker") that judges the answers.
+When a poster picks yours, their posting transaction grants your oracle a **meta-authorization**
+(the right to authorize itself on the new collection) and the app calls
+`POST https://<your host>/openhands/hire/<collectionId>`. The package's **OpenHands add-on**
+answers that call: it checks the grant on chain, mints the oracle's own evaluate grant under it,
+registers the collection through the normal four gates and scans it — and a backstop every five
+minutes catches a call that never arrived and keeps every hired ask topped up. The engine still
+decides; nothing here judges.
 
-**Explain before acting.** Tell the provider what will happen — files copied into their project,
-a redeploy, an `oracle init` that signs chain transactions (card refresh), `engine register` —
+Two kinds of checker — ask the provider which they are building:
+
+| Kind | `supportedProtocols` | What the asks look like | Facts you answer |
+| --- | --- | --- | --- |
+| **Expert** (most providers) | your protocol(s) | The poster's ask uses YOUR protocol as it is — your rubric, your form | Your own rubric's names, as for any oracle |
+| **General** | `[]` | Openhands writes a rubric per ask from the poster's sentence | The bridge's vocabulary (step 3) |
+
+**Explain before acting.** Tell the provider what will happen — edits to `src/index.ts` and
+`wrangler.jsonc`, a redeploy, `engine register`, an `oracle init` that signs chain transactions —
 and wait for their OK. Dry-run every chain step first (`create-oracle` step 8's contract).
 
-## The adapter (copy, don't rewrite)
+## 1. Turn the add-on on
 
-Source of truth: `examples/street-check-oracle` in the eval-oracle repo (an `init` project with
-the adapter added, deployed on devnet). Copy:
+A NEW project: `bunx decision-oracle init <dir> --openhands` — done, go to step 2.
 
-| Path | What it is |
-| --- | --- |
-| `src/openhands/` | `routes.ts` (`POST /openhands/hire/:id`, `/openhands/scan/:id`, `GET /openhands/claims/:id/why`), `invitations.ts` (10-min backstop), `chain.ts` (meta-grant → `MsgCreateClaimAuthorization`), `act.ts` / `release.ts` (pooled payouts — the act seam's amount stands only where the collection's owner set `operatorAmounts: "allowed"`; Verify step 4), `spots.ts` |
-| `src/workflows/hire.ts` | `OpenhandsHire`: verify → mint → register → scan, one instance per collection |
-| `src/facts/` | the bridge's names: `withinRadius[2..5]`, `located`, `beforeAfter` (package stock), `notElsewhere[N]`, `notMarkedGenerated[N]`, `photoShape[N]`, `daylight`, `weather`, `notAlreadyMapped`, `cooldown`, `reMeasure[N]`, `openhandsSite`; `ai.judge[N]` is the stock judge |
-| `src/index.ts` | wraps `oracle.fetch` with `handleOpenhandsRoute`, routes cron `*/10` to the three passes, exports `OpenhandsHire` |
-| `src/env.ts`, `src/pricing.ts`, `migrations/`, `scripts/flatten-package-migrations.ts` (+ `scripts/lib/`) | `OH_DB`, `HIRE_WORKFLOW`, `WHY_RATE_LIMITER`, the check price |
-
-Outside the eval-oracle repo, get it with `git clone https://github.com/ixoworld/eval-oracle` and
-copy from `examples/street-check-oracle/`. The fact handlers are not street-specific: they are the
-bridge's generic vocabulary, and each ask's rubric picks which ones it asks for — copy them as
-they are. If the project already answers one of these names, keep ONE handler for it: a name
-answered twice throws at module evaluation (`defineFacts`).
-
-`wrangler.jsonc`: a second D1 `OH_DB` (`migrations_dir: "migrations"`), the `HIRE_WORKFLOW`
-workflow (`class_name: "OpenhandsHire"`), crons `["* * * * *", "*/5 * * * *", "0 * * * *", "*/10 * * * *"]`
-(the package's three tiers plus Openhands' ten-minute one), the
-`WHY_RATE_LIMITER` ratelimit — in EVERY env. Keep `supportedProtocols: []` (every ask is new).
+An EXISTING project — three edits:
 
-```bash
-wrangler d1 create <name>-oh-<env>       # paste the id into that env's OH_DB
-bun run db:migrate:remote                # must apply BOTH databases — copy the example's script
-bun run cf-typegen && bun run check
+1. `src/index.ts`: add `openhands: {}` to `defineOracle({...})`, and re-export the hire:
+   `export const { ClaimIngest, ReviewComplete, OpenhandsHire, SequenceManagerDO } = oracle;`
+2. `wrangler.jsonc`, in the top level AND every `env.<name>` block (named envs inherit no
+   bindings): a workflow `{ "name": "<project>-openhands-hire[-<env>]", "binding": "HIRE_WORKFLOW",
+   "class_name": "OpenhandsHire" }`, and a ratelimit `{ "name": "OPENHANDS_RATE_LIMITER",
+   "namespace_id": "1003", "simple": { "limit": 300, "period": 60 } }`. Without the limiter a
+   deployed oracle answers the webhooks `503` (fail closed).
+3. `bun run cf-typegen && bun run check`.
+
+Nothing else: no second database (the add-on's two tables ship in the package's migrations), no
+extra cron (it rides the package's `*/5` tier), no routes to write.
+
+## 2. Decide who pays for decisions
+
+The engine bills every decision to the account that registered the oracle. Pick one:
+
+- **Charge a fee** — `pricing.evaluation` (or that env's `EVALUATION_DENOM` /
+  `EVALUATION_MIN_AMOUNT`, required on mainnet) in the app's ask denom: `uixo` on devnet, `upay` on
+  testnet/mainnet. The poster's escrow carries it; an ask escrowing less is refused 402 and never
+  judged. A sensible default is `350000` base units (0.35 PAY), above the engine's per-decision cost.
+- **Or free, bounded** — `minAmount: "0"` and an `openhands.admit` hook that refuses asks you will
+  not pay for (an allow-list of admins, a daily budget):
+
+```ts
+openhands: {
+  admit: ({ admin }) => (MY_ADMINS.has(admin) ? null : "not one of our asks"),
+},
 ```
 
-## Pricing — set it deliberately per env
-
-`src/pricing.ts` `CHECK_PRICE_DENOM` / `CHECK_PRICE_AMOUNT` feed `pricing.evaluation` AND the
-ceiling written on every minted grant. Denom = the app's ask denom (`uixo` on devnet, `upay` on
-testnet/mainnet). In a template project the `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars in
-`wrangler.jsonc` override `pricing.evaluation` for that env — so set `EVALUATION_DENOM=upay` and
-`EVALUATION_MIN_AMOUNT=<the check price>` in the testnet AND mainnet envs (mainnet will not boot
-without them), or `EVALUATION_MIN_AMOUNT=0` for an oracle IXO bills per review (its collections
-carry an empty evaluation leg). Outside per-review billing, 0 means the oracle works for free while
-the engine bills its owner per decision. The picker shows the price from `/v1/info`, and the
-poster's escrow carries it; an ask escrowing less is refused 402 and never judged. Default, unless
-the provider names one: `350_000` base units — 0.35 IXO on devnet, 0.35 PAY ($0.35) on
-testnet/mainnet, Openhands' own check fee, which covers the engine's $0.30 per decision.
-
-## Being listed and hired
-
-The app's picker lists an oracle when its entity has: `#acard` with a **`check-openhands`** service (next to
-`check-measure`, priced in PAY — the app reads the service id, and `check-openhands` is what marks
-the oracle Openhands-compatible); `#orz` granting `ORACLE_ADDRESS`; `#eval` = an https base URL
-whose `/v1/info` answers that address, the ask denom, and `policies.allowAiChecks: true` (else it
-is offered only for asks without written checks); and the oracle **registered with the engine**
-(`engine register`, below). `oracle init` writes `#orz`, `#eval` and the card — re-run it after any
-price change (`acard` drifts); it is idempotent against live state, so a re-run on an initialised
-oracle only replaces what drifted. `--openhands` adds the `check-openhands` service, priced in
-PAY at the oracle's per-review price (`/v1/info`'s `pricing.api`, else `--price-pay <n>`;
-1 PAY = 1 USD):
+Free with no `admit` means any poster can spend your credits.
+
+## 3. Facts — only for a General checker
+
+An Expert checker answers its own rubric; skip this. A General checker judges Openhands' per-ask
+rubrics, which ask for the bridge's names: `withinRadius[2..5]`, `located`, `beforeAfter`
+(package stock — `@ixo/decision-oracle/facts`), `notElsewhere[N]`, `notMarkedGenerated[N]`,
+`photoShape[N]`, `daylight`, `weather`, `notAlreadyMapped`, `cooldown`, `reMeasure[N]`,
+`openhandsSite`; `ai.judge[N]` is the stock judge. Copy the handlers from
+`examples/street-check-oracle/src/facts/` in https://github.com/ixoworld/eval-oracle as they are —
+they are the bridge's generic vocabulary, not street-specific. If the project already answers one
+of these names, keep ONE handler for it (a name answered twice throws at module evaluation).
+Keep `supportedProtocols: []`.
+
+## 4. Deploy, register, card
 
 ```bash
-bunx decision-oracle oracle init --protocol <any ask's protocol, or the app's claim-form entity> \
-  --kit-url https://<host> --logo https://<host>/logo.svg --openhands --network <n>   # dry run; then --yes
+bunx wrangler d1 migrations apply DB --remote --env <env>     # 0025_openhands, before the deploy
+bunx wrangler deploy --env <env>
+bunx decision-oracle engine register --env <env> --env-file .dev.vars.<env>
+bunx decision-oracle oracle init --protocol <your protocol> --kit-url https://<host> \
+  --logo https://<host>/logo.svg --network <n>          # dry run; then --yes
 ```
 
-Hire/scan nudges go to the PICKED oracle's `#eval`; you know the app routes to you when the hire
-nudge shows up in THIS oracle's logs after a post.
-
-Then, right after deploy: `bunx decision-oracle engine register --env <env> --env-file .dev.vars`.
-The Openhands app lists only registered oracles, and otherwise the engine (and the Decision
-Console) learns the oracle only at its first decision.
+- **Register with an account you will not post or review with.** The engine never lets the
+  account that registered an oracle review that oracle's claims (`oracle-owner`). Use a company or
+  service login, so the provider can still answer reviews on their own asks.
+- `oracle init` sees the `openhands` webhooks on `/v1/info` and adds the **`check-openhands`**
+  service to the Agent Card — the marker the app's picker reads, priced at `pricing.api` on
+  `/v1/info`, else `--price-pay <n>`, else your evaluation fee when it is in `upay`
+  (1 PAY = 1 USD). Re-run it after a price change; it is idempotent and only replaces what drifted.
+- The picker lists an oracle whose entity has that card, `#orz` granting `ORACLE_ADDRESS`, an https
+  `#eval` whose `/v1/info` answers that address and names `openhands`, and that is registered with
+  the engine. `policies.allowAiChecks: false` hides it from asks with written checks.
 
 ## Verify (in order)
 
-1. `curl <host>/v1/info` → address, `pricing.evaluation` in the ask denom, `allowAiChecks: true`.
-2. The composer's checker step lists the oracle at its price.
-3. Post an ask picking it → `wrangler workflows instances describe <name>-hire-<env> <collectionId>`
-   shows verify, mint (a tx), register `active`, scan.
-4. Submit a claim → logs `evaluate.done` (`decided`) then `act.submitted`; the receipt page
-   `/r/<id>` shows the decision trace and the payout line naming the check fee. The pooled amount
-   the act seam picks stands only if the collection's owner set `operatorAmounts: "allowed"` —
-   `PATCH /v1/collections/:id/settings` with `{ "operatorAmounts": "allowed" }` (UCAN action
-   `collections/settings`), under the owner's
-   own UCAN. Otherwise the oracle pays the default leg and logs `act.amount-ignored-not-opted-in`.
+1. `curl https://<host>/v1/info` → `openhands: { hire, scan }`, `address`, pricing in the ask denom.
+2. `curl -X POST https://<host>/openhands/hire/1` → `404` or `409` with a JSON reason (not `503`:
+   that is a missing `OPENHANDS_RATE_LIMITER`).
+3. The app's checker step lists the oracle at its price.
+4. Post an ask picking it → `bunx wrangler workflows instances describe <project>-openhands-hire-<env>
+   <collectionId>` shows `verify`, `mint` (a tx), `register` (`active`), `scan`. Logs:
+   `openhands.hire.done`.
+5. Submit a claim → `evaluate.done` (`decided`), then `act.submitted`.
 
 ## Common mistakes
 
 | Symptom | Cause / fix |
 | --- | --- |
-| Hire nudge 404 | the adapter's routes are not wrapped in `src/index.ts` `fetch` |
-| Every claim rejected `weather` "unreachable" | `weather` left as a stub; copy `src/facts/weather.ts` (Open-Meteo, no key) |
-| Oracle missing from the picker | no `check-openhands` service on `#acard`, no `#orz`/https `#eval`, not `engine register`ed, or its price unreadable |
-| Picker shows the oracle at 0 | `pricing.ts` / that env's `EVALUATION_MIN_AMOUNT` still 0 on an oracle not billed per review, or the denom ≠ the ask denom |
-| `withinRadius` fails for everyone | the ask's place was geocoded from a word ("You" → a village in Burkina Faso); set the place by name |
-| Console "Could not read this oracle's prices" | the console reads the Decision API price list; a chain-lane oracle has none (`API_LANE` off) — console-side, not an oracle fault |
-| Wrangler can't resolve `protobufjs/minimal.js` | inside the eval-oracle workspace there is one hoisted protobufjs; drop any protobufjs `alias` you copied in |
-| `chain.test.ts` fails after a denom change | the "foreign denom" fixtures used your new denom; give them one you are not paid in |
+| Hire call 404 on every id, including real ones | `openhands` is not set in `defineOracle` — the routes only exist with it (the 404 is then the app's not-found, not JSON) |
+| Hire call 503 "rate limiter unavailable" | no `OPENHANDS_RATE_LIMITER` in that env's `wrangler.jsonc` |
+| Hire call 409 "no live meta-grant" | the poster picked another checker, or the grant was signed by someone other than the collection's admin — check which oracle address the ask granted (`/cosmos/authz/v1beta1/grants/granter/<admin>`) |
+| Hire instance ends "is not served" | your `admit` hook refused it — by design |
+| Hire instance ends at `register` with 402 | the ask escrows less than your evaluation fee, or in another denom |
+| Hire instance ends at `register` with 409 "protocol" | an Expert checker picked for an ask on a protocol you do not list |
+| `HIRE_WORKFLOW binding is missing` in the logs | the workflow is missing from that env's `wrangler.jsonc`, or `OpenhandsHire` is not re-exported from `src/index.ts` |
+| Oracle missing from the picker | no `check-openhands` card (re-run `oracle init`), no `#orz`/https `#eval`, not `engine register`ed, or no per-review price |
+| `REVIEWER_NOT_AUTHORIZED: oracle-owner` when the provider reviews | they registered the oracle with the same login they post and review with — register it under a separate account |
+| Every claim of a General ask rejected `weather` "unreachable" | `weather` left as a stub; copy `src/facts/weather.ts` (Open-Meteo, no key) |

package/skills/create-oracle/SKILL.md

@@ -58,7 +58,7 @@ handlers themselves (`write-facts`, handed off to at step 3).
 ### 0. The project
 
 ```bash
-bunx @ixo/decision-oracle init <dir> [--name <project-name>]
+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
@@ -70,6 +70,10 @@ cp .dev.vars.example .dev.vars           # git-ignored; secrets only
 Three files are the provider's: `src/index.ts` (what the oracle IS), `src/facts/index.ts` (how it
 answers), `wrangler.jsonc` (where it runs).
 
+Ask first: **is this oracle for Openhands** (picked by posters in the Openhands app)? Yes ⇒
+`--openhands`, which wires the add-on (the hire webhooks, the hire workflow and its rate limiter in
+every env) — then follow `add-openhands-support` for who pays, registering and the picker card.
+
 ### 1. Identity — two keys
 
 ```bash
@@ -334,9 +338,10 @@ Decision Console, which lists the engine's `GET /v1/oracles` — does not know t
 
 ### 10. Get hired
 
-Hired from the Openhands app (asks, the Yoma youth world) rather than a portal collection? That is
-the `add-openhands-support` skill — the hire/scan adapter, the bridge's fact names, the picker's
-card fields.
+Hired from the Openhands app (asks, the Yoma youth world) rather than a portal collection? The
+oracle hires itself on each ask that picks it (`openhands: {}` — `init --openhands`); the
+`add-openhands-support` skill covers who pays, the account to register with, the picker's card and
+the bridge's fact names for a General checker.
 
 A real commissioner grants `ORACLE_ADDRESS` the Evaluate role on their collection and registers it
 (the portal makes that call). To prove the loop yourself, hire yourself with the `create-collection`
@@ -360,6 +365,7 @@ the required fee (`pricing.byProtocol` for that collection's protocol, else the
 
 | Slot | Ask | Lands in |
 | --- | --- | --- |
+| Openhands | will posters pick it in the Openhands app? An Expert (its own protocol) or a General checker (Openhands' per-ask rubrics)? | `init --openhands`, `supportedProtocols` (`add-openhands-support`) |
 | Protocol | the DID, and which network | `--protocol`, `supportedProtocols` |
 | Pricing | denom + minimum per-evaluation payment per network; any protocol priced differently (incl. free)? | `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` per env, optionally `pricing.byProtocol` |
 | AI / image policy | does the work order declare `ai` checks; do any read images | `policies.allowAiChecks` / `allowImageChecks` |