@ixo/decision-oracle 0.2.34 → 0.3.0

package/docs/guide.md

@@ -1111,6 +1111,58 @@ Three things to decide:
   oracle's claims. Register the oracle with an account you will NOT use to post or review asks
   (a company or service login), so you can still answer reviews yourself.
 
+### Practice checks
+
+An app can let a person see what your oracle **would** decide on their completion before they hand
+it in. `POST /v1/practice-check` runs the same build a real claim runs — your facts table, the real
+tools, the real AI, the collection's real window, `now` as the clock and the person's address as the
+claim's signer — and asks the engine's preview route what it would decide. Nothing is kept: no
+claim, no chain write, no fee, no grant, no duplicate-registry row, no review task, no email, and the
+engine bills nothing. Only the AI spend is recorded, as a real check's is (`ai.tokens`, and
+`ai_calls` rows under a `practice-<uuid>` claim id), so you can see what practice costs you.
+
+It is off until you name the apps allowed to call it. Each is a server with its own key, calling
+with a UCAN `practice/check` (strict: never `*`) addressed to your oracle's `did:web`, like every
+other `/v1` route:
+
+```jsonc
+// wrangler.jsonc, every env
+"PRACTICE_CHECK_CALLERS": "did:web:<app host>",
+// optional daily limits (defaults shown), each per UTC day
+"PRACTICE_CHECK_LIMIT_ASK": "5",        // per person per collection
+"PRACTICE_CHECK_LIMIT_SUBMITTER": "30", // per person, every collection
+"PRACTICE_CHECK_LIMIT_ORACLE": "500",   // your whole oracle: the cost backstop
+```
+
+```http
+POST /v1/practice-check
+{ "collectionId": "1234", "submitter": "ixo1…", "answers": { … },
+  "attachments": [{ "question": "photo", "name": "a.jpg", "mediaType": "image/jpeg",
+                    "dataUrl": "data:image/jpeg;base64,…" }] }
+
+200 { "outcome": "approve" | "review" | "reject",
+      "reasons": [{ "code": "G-1", "outcome": "passed" | "failed" | "review", "reason": "…" }],
+      "notes": ["…"], "limits": { "remaining": 4, "resetsAt": "…" } }
+```
+
+`reasons` carries your rubric's own sentence for each gate and criterion; `notes` is what a reviewer
+would read (your reviewer note, when the oracle makes one — one more model call). When your rubric
+holds every claim for a person's final OK, `review` is the normal good answer. A spent limit is `429`
+with `retryAfter` and `limits`; an engine or AI that cannot answer is `502` / `503`, never a verdict.
+
+What is not the same as a real claim, and fails closed:
+
+- **The stock duplicate check** registers a claim before it compares, so it does not run: the dry-run
+  placeholder (the same one `facts run` uses, band `review`) answers instead, and `notes` says so. A
+  rubric with a `unique` rule therefore previews `review` at best. A `facts.unique` handler of your
+  own still runs — keep it free of writes.
+- **Attachments** arrive inline as `data:` URLs (up to 20 files, a 10 MB body) with no CID, so a
+  handler that reads `att.cid` sees none.
+- **The frequency count** adds the would-be claim to what Blocksync counts, as the real claim's own
+  count would include it.
+
+api.md §12 has the full contract.
+
 ### Third-party oracle fees
 
 An oracle that IXO does not run is paid on chain claims by the collection's on-chain **evaluation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.34",
+  "version": "0.3.0",
   "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/templates/project/.dev.vars.example

@@ -76,6 +76,9 @@ UNIQUE_HMAC_KEY="change-me-to-a-long-random-string"
 # status board), by its DID of any method. Not a secret — deployed, it lives in wrangler.jsonc `vars`;
 # set it here only to try it under `wrangler dev`. Unset ⇒ only ORACLE_ADMIN_DIDS can read the status.
 # STATUS_READER_DIDS="did:web:<monitor host>"
+# Callers of POST /v1/practice-check (an app's server, by its DID of any method). Not a secret —
+# deployed, it lives in wrangler.jsonc `vars`. Unset ⇒ the route is off (404).
+# PRACTICE_CHECK_CALLERS="did:web:<app host>"
 
 # --- Local dev logging ---
 # Pretty, colorized log lines for the terminal. Local-only: this file is never

package/templates/project/wrangler.jsonc

@@ -220,6 +220,12 @@
     // 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>",
+    // Callers of POST /v1/practice-check (an app's server, e.g. asks.world's did:web): what this oracle
+    // WOULD decide on a completion, nothing persisted. Unset ⇒ the route is off. Daily limits below.
+    // "PRACTICE_CHECK_CALLERS": "did:web:<app host>",
+    // "PRACTICE_CHECK_LIMIT_ASK": "5",
+    // "PRACTICE_CHECK_LIMIT_SUBMITTER": "30",
+    // "PRACTICE_CHECK_LIMIT_ORACLE": "500",
 
     // 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.
@@ -281,6 +287,7 @@
         // "AUTH_HUB_URL": "https://<authhub host>",
         // "ORACLE_ADMIN_DIDS": "did:ixo:<admin>",
         // "STATUS_READER_DIDS": "did:web:<monitor host>",
+        // "PRACTICE_CHECK_CALLERS": "did:web:<app host>",
 
         // "EMAIL_FROM_ADDRESS": "oracle@your-domain",
         // "EMAIL_FROM_NAME": "Your Oracle",
@@ -392,6 +399,7 @@
         // "AUTH_HUB_URL": "https://<authhub host>",
         // "ORACLE_ADMIN_DIDS": "did:ixo:<admin>",
         // "STATUS_READER_DIDS": "did:web:<monitor host>",
+        // "PRACTICE_CHECK_CALLERS": "did:web:<app host>",
 
         // "EMAIL_FROM_ADDRESS": "oracle@your-domain",
         // "EMAIL_FROM_NAME": "Your Oracle",
@@ -503,6 +511,7 @@
         // "AUTH_HUB_URL": "https://<authhub host>",
         // "ORACLE_ADMIN_DIDS": "did:ixo:<admin>",
         // "STATUS_READER_DIDS": "did:web:<monitor host>",
+        // "PRACTICE_CHECK_CALLERS": "did:web:<app host>",
 
         // "EMAIL_FROM_ADDRESS": "oracle@your-domain",
         // "EMAIL_FROM_NAME": "Your Oracle",