@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/skills/write-facts/reference/facts-api.md

@@ -0,0 +1,232 @@
+# The facts API — cheat sheet
+
+Full reference: `node_modules/@ixo/decision-oracle/docs/api.md` (or `packages/eval-oracle/docs/api.md`
+in this repo) — every export, every default, every cap. This page is the working subset.
+
+Everything a handler is handed, everything it may hand back, and the rules the runner enforces
+around it. Import surface: `@ixo/decision-oracle/facts` (node-safe) and `@ixo/decision-oracle/testing`
+(node-safe). A handler never imports the worker.
+
+## The table
+
+```ts
+import { defineFacts, group } from "@ixo/decision-oracle/facts";
+
+export const facts = defineFacts({
+  ext:  { [name]: ExtHandler },        // unlisted ⇒ the STOCK ext lane (a UCAN-signed POST to the declared endpoint)
+  ai:   { [name]: AiHandler,           // unlisted ⇒ the STOCK ai lane (the configured AI provider with the rubric's instructions)
+          "*":    AiHandler },         // catches every check not named above; a named handler still wins
+  groups: [group([name, name], GroupHandler)],  // ONE call answers several sources (below)
+  unique:    UniqueHandler,            // absent ⇒ the stock duplicate lane (this oracle's D1 registries)
+  frequency: FrequencyHandler,         // absent ⇒ the stock Blocksync submission count
+});
+```
+
+A table is a DIFF against stock, never a replacement of it. A handler for a name the manifest does
+not declare is ignored with one `facts.handler-unused` warning — a renamed rubric entry shows up as
+that warning, not as a broken build. One name, one handler: a name listed in `ext` *and* claimed by
+a group (or claimed by two groups) throws at **boot**.
+
+```ts
+// Each returns the value OR a promise of it — a synchronous handler is fine.
+type ExtHandler       = (input: ExtInput, tools: ExtTools)        => Promise<ExtResult> | ExtResult;        // boolean | number | ExtFact | FactErrorDraft
+type AiHandler        = (input: AiInput, tools: AiTools)          => Promise<AiResult> | AiResult;          // boolean | AiFact | FactErrorDraft
+type GroupHandler     = (input: GroupInput, tools: FactTools)     => Promise<GroupResult> | GroupResult;    // Record<name, ExtResult>
+type UniqueHandler    = (input: UniqueInput, tools: FactTools)    => Promise<UniqueFact> | UniqueFact;
+type FrequencyHandler = (input: FrequencyInput, tools: FactTools) => Promise<FrequencyFact> | FrequencyFact;
+```
+
+`ExtTools` / `AiTools` are `FactTools` narrowed to the lane's own fact — that is what makes
+`return tools.stock()` type-check with no cast.
+
+## The input
+
+Every handler gets these:
+
+| Field | What it is |
+| --- | --- |
+| `claim` | the pulled claim: `claimId`, `collectionId`, `metadata` (agent address, submission date, payment), `attachments`, `body` |
+| `answers` | `claim.body` — the credentialSubject, verbatim |
+| `ctx` | the build's ONE clock read + the collection window: `{ now, collection: { startDate, endDate }, claim: { submitter, submitterAddress, submissionDate } }`. **Never read the clock in a handler** — `ctx.now` is what the engine's rules compare against |
+| `settings` | this oracle's policies for this build: `{ allowAiChecks, allowImageChecks }` |
+| `manifest` | the whole work order: `fields`, `derived`, `ctx`, `unique`, `frequency`, every `ext`/`ai` declaration |
+
+Per lane, on top of that:
+
+```ts
+ExtInput  { name, expected: ManifestExt, send, unresolved }
+AiInput   { name, check: ManifestAi, send, unresolved, inputs: AiSendEntry[] }
+GroupInput     { names: string[], sources: Record<name, ExtInput> }   // one call, several sources
+UniqueInput    { rule: UniqueRule }              // rule defaults already applied
+FrequencyInput { rule: FrequencyRule | null }    // null ⇒ the manifest declared no max/per
+```
+
+- `send` — the rubric's declared `send` map, already resolved against the answers and ctx. A slot
+  naming a `~derived` value is `null` and its ref is listed in `unresolved`; the expression is in
+  `manifest.derived[]` if your handler wants to compute it (the stock lanes refuse it instead).
+- `expected` / `check` — the declaration for THIS name: `expect` (`"boolean"` | `"score"`),
+  `onError`, `endpoint`, `audience`, `capability`, `timeoutMs`, `instructions`, `usedBy`.
+- `inputs` (ai) — the `send` map as the judge's typed, ordered entries: `{ kind: "text", key, value }`
+  and one `{ kind: "attachment", key, attachment }` per file on a `$question` slot.
+
+## What to return
+
+| Return | Becomes |
+| --- | --- |
+| `true` / `false` (ext, ai) | `{ status: "ok", value, reason: null }` (ai also gets `failedRules: []`, `score: 100`) |
+| `8200` (ext, `expect: "score"`) | `{ status: "ok", value: 8200, reason: null }` — an INTEGER 0..10000, never a float, never clamped |
+| `fact.ok(value, { reason?, confidence?, transcript? })` | the same, with colour for the trace |
+| `fact.ai.ok(value, { reason?, failedRules?, score?, confidence?, transcript? })` | an AI verdict; `score` is confidence in the VERDICT (0–100), not input quality |
+| `fact.error(detail, { transcript? })` | `{ status: "error", onError: <the manifest's>, detail }` |
+| `throw fact.retryLater(detail)` | the workflow step retries; facts already answered are kept |
+| a retryable engine/chain failure (5xx, `UNAVAILABLE`, `RATE_LIMITED`, an outage) | NOT a fact — it retries too, same as `retryLater` |
+| any other throw | an `error` fact with the manifest's `onError`, logged `facts.handler-threw` |
+
+`fact.error` takes no `onError` and there is no way to pass one: the runner stamps the rubric's own,
+over whatever a handler put there. **A handler cannot turn its own failure into an approval.**
+
+**A deterministic failure is a fact; a transient one is a retry.** Don't `catch` a transient
+engine/chain error yourself and turn it into `fact.error(...)` — that freezes a verdict over
+trouble that was never the claim's fault, and a claim is decided once, so it can never be re-run
+(task-14, 2026-09-14: a devnet claim was held for review on every fact because the engine's own 5xx
+got frozen this way). `tools.agreement()` and `tools.chain.*` already let a retryable failure
+propagate instead of catching it — see below.
+
+## One call, many facts
+
+`group(["quality", "price"], handler)` in `groups` takes those `ext` names over and answers them
+from ONE call — four criteria judged by a single structured model call is four completions as four
+handlers and one as a group. It is the sanctioned way to share a call between facts; a private cache
+inside a handler still is not (the runner's fact cache is the only cache).
+
+AI checks cannot currently be grouped; `group()` answers `ext` sources only.
+
+```ts
+export const workScores: GroupHandler = async ({ names, answers }, tools) => {
+  const res = await tools.http.json<Scores>(JUDGE_URL, { method: "POST", body: { …answers } });
+  // One call, one failure: every name it owed gets an error carrying the rubric's own `onError`.
+  if (!res.ok) return Object.fromEntries(names.map((n) => [n, fact.error(`judge ${res.status}`)]));
+  return { quality: 8600, price: fact.ok(7000, { reason: "under the agreed price" }) };
+};
+```
+
+- `names` — the names THIS call must answer (the group's names, minus any the manifest does not
+  declare and any a previous attempt already paid for). **Answer every one of them**: a name you
+  leave out becomes its own `handler returned no fact for <name>` error.
+- `sources[name]` — that name's `ExtInput`: its `expected` declaration and its resolved `send`.
+- Return one fact per name, each anything a single ext handler may return.
+- The group is **one** call per claim and **one** slot in the fan-out cap. Each fact still carries
+  its own declaration's `onError` and its own cache entry; a throw freezes every name it owed.
+- A name nobody asked for is dropped with a `facts.group-extra-fact` warning. `tools.stock()`
+  throws inside a group — it names none of the group's sources.
+
+## `tools`
+
+| Call | One-line use |
+| --- | --- |
+| `tools.stock()` | `const base = await tools.stock();` — the stock lane for THIS fact: wrap it, fall back to it, or ignore it. Typed per lane (an `ExtFact` in an ext handler, an `AiFact` in an ai one), so `return tools.stock()` needs no cast |
+| `tools.http.json<T>(url, init?)` | `const res = await tools.http.json<Reply>(url, { method: "POST", body, timeoutMs: 5000 });` — retries, timeout, SSRF guard, a recorded transcript; NEVER throws for an HTTP outcome. `{ ok, status, body, transcript }`, `status: null` = no response at all. Name the response type (or `body` is `unknown`) |
+| `tools.http.json(url, { ucan })` | `await tools.http.json(expected.endpoint, { method: "POST", ucan: true, body })` — signed as this oracle's did:web FOR THAT URL'S HOST; `ucan: { capability }` for your own (in code — never `expected.capability`, the rubric's, which is ignored). An `ixo:` service capability is an error fact |
+| `tools.http.ucanHeaders(audience, capability?)` | the same token as headers, for back-compat — the audience must be the host you call; prefer `json(url, { ucan })` |
+| `tools.ai.judge(instructions, inputs, opts?)` | `return tools.ai.judge(["Shows a passport"], input.inputs);` — the stock judge with YOUR rules; errors when `settings.allowAiChecks` is off |
+| `tools.ai.inputsFor(check)` | `tools.ai.inputsFor(input.check).filter((e) => e.kind === "attachment")` — re-slice what the lane would send |
+| `tools.attachments.on(question)` | `const [photo] = tools.attachments.on("deliveryPhoto");` — by ROOT question name, not `$path` |
+| `tools.attachments.bytes(att, opts?)` | `const body = await tools.attachments.bytes(photo, { maxBytes: 5_000_000 });` → `{ ok: true, bytes } \| { ok: false, reason }` |
+| `tools.attachments.size(att)` | `await tools.attachments.size(photo)` → bytes or `null` |
+| `tools.c2pa.screen(bytes, mediaType?)` | `const prov = await tools.c2pa.screen(body.bytes);` — Content Credentials, `null` when there are none |
+| `tools.chain.linkedResources(entityDid)` | `const [card] = (await tools.chain.linkedResources(did)).filter((r) => r.id === "#acard");` — what an entity anchors on chain, with each resource's `proof` hash |
+| `tools.chain.claimIntent({ agentAddress, collectionId, before, after? })` | `const intent = await tools.chain.claimIntent({ agentAddress, collectionId, before: submittedAt, after: agreed.consentedAt });` → `{ time, transactionHash }` or `null` — the newest `MsgClaimIntent` this agent filed on this collection before `before`, **bare or authz-wrapped** (an intent filed as an authz grantee is nested in a `MsgExec`, which is how the portal and the boilerplate chain client file one). **One server-side filtered query, never a scan**; `null` means it filed none. Pass the agreement's consent time as `after` so an earlier engagement's intent can never become the clock |
+| `tools.chain.query()` | `const q = await tools.chain.query();` — the chain RPC query client (balances, grants, module state). The SDK loads on first call and is memoised per isolate |
+| `tools.agreement(counterparty?)` | `const agreed = await tools.agreement();` — the buyer statement for this collection. **Read it LAST.** Omitted ⇒ the claim's own agent; an explicit `null` ⇒ the collection's own terms. The agreement is read once per claim and shared: every handler in the build sees the same snapshot, at the cost of one engine call. `null` means a real 404 — no agreement on file; a transient engine failure (5xx / `UNAVAILABLE` / `RATE_LIMITED`) throws instead, so don't wrap this call in your own `try/catch` |
+| `tools.logger` | `tools.logger.warn("vendor slow", { name });` — structured, ends up in the oracle's logs |
+| `tools.config` | validated config (`IXO_NETWORK`, hostnames, …) |
+| `tools.env` | YOUR bindings and secrets from `wrangler.jsonc` / `.dev.vars` — where a vendor API key comes from |
+
+Two readers come with the API for picking values out of a claim body the way the engine's binder
+does: `readAnswer(answers, "$q.row.col")` and `rootQuestionName("$deliveryPhoto")`.
+
+**`tools.chain` is reads only, and an empty answer is a FACT.** An entity that anchors nothing
+answers `[]`. Blocksync being *unreachable* is a different thing and throws, which the runner passes
+through as the step's retry signal — so a chain outage retries instead of freezing a verdict. Catch
+it only if "could not read the chain" is genuinely the fact you mean, and then say so with
+`fact.error`. `tools.agreement()` follows the same rule against the eval engine (task-14): a real
+"no agreement on file" is `null`, a transient engine outage throws.
+
+**There is no GENERAL chain message-history read, and you must not build one.** The one thing an
+oracle may look up about what preceded a claim is the agent's own commitment, and `claimIntent` is
+on `tools.chain` precisely so it stays ONE filtered query — the indexer narrows by message type
+(bare intent, or the authz `MsgExec` an intent is normally filed through), by the agent/collection
+inside the message's jsonb `value`, and by time, and hands back at most one row. A handler that
+pages the chain looking for anything is a bug, not a fact. `null` from `claimIntent` is the ANSWER
+"this agent filed no intent"; an outage throws, as above.
+
+## What the runner guarantees, for stock and custom alike
+
+1. **Normalization** — a plain return becomes a full fact; a `fact.error` draft becomes a full error.
+2. **Fail closed** — an error carries the MANIFEST's `onError`. A throw is an error fact, never an
+   approve, never a lost claim — unless it's transient (next point).
+3. **One retry signal** — `fact.retryLater()`, the package's own loud errors, and a retryable
+   `EngineError` from the eval engine (5xx / `UNAVAILABLE` / `RATE_LIMITED`, e.g. `tools.agreement()`)
+   all get out, as `unavailable`, so the workflow step retries instead of freezing a verdict. A
+   deterministic failure is a fact; a transient one is a retry.
+4. **The fact cache** — every `ext`/`ai` answer is cached for the claim, so a step retry after a
+   crash never re-buys a paid answer and never re-runs the handler. `unique`/`frequency` never cache.
+5. **The fan-out cap** — at most 4 ext/ai handlers in flight at once; a group is ONE of them,
+   however many names it answers.
+6. **Type check** — `validateFacts` refuses the build if a declared name is missing, an `ok` value is
+   the wrong type, an error's `onError` was tampered with, or an undeclared name is present.
+
+## Testing
+
+```ts
+import { fakeTools, httpResponse, runFacts, sampleClaim, sampleManifest } from "@ixo/decision-oracle/testing";
+
+const out = await runFacts(facts, {
+  claim: sampleClaim({ reference: "ABC" }, { agentAddress: "ixo1…", attachments: [{ question: "photo", name: "p.jpg", mediaType: "image/jpeg", url: "https://media.example/p.jpg" }] }),
+  manifest: sampleManifest({ ext: { deliveryConfirmed: { expect: "boolean", onError: "review" } } }),
+  tools: fakeTools({
+    http: { "https://courier.example/deliveries/ABC": { status: "delivered" } },   // any value = that body, under a 200
+    // httpResponse(503, { error: "down" })  — when the STATUS is the point
+    // stock: fact.ai.ok(true), agreement: { id, digest, counterparty, doc }, attachments: { url: bytes }, c2pa: null, env: { VENDOR_KEY: "k" }
+    // chain: { linkedResources: { "did:ixo:entity:…": [{ id: "#acard", proof: "…" }] }, claimIntent: { time, transactionHash } | null | ((params) => …), query }
+  }),
+});
+
+expect(out.issues).toEqual([]);                       // empty ⇔ the engine would accept this FactSet
+expect(out.ext.deliveryConfirmed).toMatchObject({ status: "ok", value: true });
+```
+
+An AI check is declared with its instructions, and a handler that wraps the stock judge is tested by
+canning that judge:
+
+```ts
+manifest: sampleManifest({ ai: { photoLooksReal: { instructions: ["Shows a passport"], onError: "review" } } }),
+tools: fakeTools({ stock: fact.ai.ok(true, { score: 90 }) }),
+// …and the failure half: fakeTools({ stock: fact.ai.ok(true) }) with a claim that has no photo,
+// asserting the handler answered `{ status: "error", onError: "review", detail: … }` anyway.
+```
+
+`runFacts` runs the SAME runner production runs, then the SAME `validateFacts` — minus the cache and
+D1. `fakeTools().logs` collects what the handler logged, and `fakeTools().chainCalls` every
+`tools.chain` call in order (`{ call: "linkedResources", entityDid }` / `{ call: "claimIntent", params }`
+/ `{ call: "query" }`) — assert on what your handler asked for. An unlisted entity DID answers
+`[]` and `claimIntent` answers `null`, as on chain; give `claimIntent` a FUNCTION when the test is
+about what was asked, or to throw and stand in for an outage. `chain.query()` throws "not available
+in tests" unless you supply a client. An
+unmatched URL is a network failure
+(`ok: false`, `status: null`), which is exactly the case worth testing. `sampleCtx({ now })` fixes
+the clock. There is no stock lane behind a test: `tools.stock()` answers an error fact unless you
+pass `stock`, and `runFacts({ stock: { ext, ai } })` overrides a whole lane.
+
+## Gotchas
+
+- **`tools.stock()` needs no cast** — it is typed to the lane's OWN fact: an `ExtFact` in an `ext`
+  handler, an `AiFact` in an `ai` one, so `return tools.stock()` type-checks as it stands. Only
+  `unique`/`frequency`/grouped handlers see the bare `ExtFact | AiFact` union, and there `stock()`
+  throws by design — such a handler REPLACES the lane for every name it answers.
+- **Money and scores are integers** — basis points 0..10000 for a `score` fact, whole cents for USD
+  comparisons. Never float equality.
+- **`send` vs the endpoint** — if you call the declared endpoint yourself, do NOT also call
+  `tools.stock()`: that is two calls (and two charges) for one fact.
+- **`ctx.now`, not `Date.now()`** — the engine's date rules compare against the frozen `ctx.now`;
+  a second clock read makes a fact that cannot be replayed.

package/templates/project/.dev.vars.example

@@ -0,0 +1,93 @@
+# Local secrets for `wrangler dev`. Copy to `.dev.vars` (git-ignored) and fill in.
+# Non-secret config lives in wrangler.jsonc `vars`. Real secrets in production are
+# set with: wrangler secret put <NAME>
+#
+# Every secret is optional so the Worker boots (health, did.json) without them; each lane fails
+# loudly (or no-ops, where noted) at the point of use when its secret is missing.
+
+# --- This oracle's identities ---
+# did:web key: SHA256(mnemonic) → Ed25519 seed. Signs every UCAN invocation this oracle mints
+# (to the eval engine, the claim bot, the UCAN Store) and backs /.well-known/did.json.
+SERVICE_ED25519_MNEMONIC="twelve word mnemonic ..."
+# Chain signer (secp256k1) — signs `MsgEvaluateClaim`. Must be the wallet behind ORACLE_ADDRESS
+# in wrangler.jsonc. Unset ⇒ the chain-write lane logs one line and skips.
+# Both of these, and the three public vars derived from the second, come from:
+#   bunx decision-oracle derive --new
+ORACLE_SECP_MNEMONIC="twelve word mnemonic ..."
+# The oracle OWNER's UCAN delegation to the decision engine (base64 CAR), posted once at register
+# so the engine can find (and bill) their subscription. Mint it as the owner with
+# `bunx decision-oracle delegation --for engine --audience <engine did:web> --oracle <this did:web>`
+# (after `bunx decision-oracle login --network <n>`, once — the AuthHub login of the subscriber).
+# Unset ⇒ register refuses, loudly. A 402 at register means: open the portal at the printed URL,
+# buy credits, then register again.
+OWNER_DELEGATION_CAR="uCAR..."
+# The oracle bot's Matrix access token (the ORACLE_MATRIX_USER_ID account). Read by the
+# review-notification lane; unset ⇒ that lane logs and skips. You do NOT obtain this yourself:
+# `bunx decision-oracle oracle init` creates the account and writes this line, in place, for you
+# (deployed: wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN).
+# ORACLE_MATRIX_ACCESS_TOKEN=   # unset = Matrix lane off; an empty string is refused by the config schema
+# ORACLE_ENTITY_DID is NOT here: it is public config, so it lives in wrangler.jsonc `vars` (already
+# there, "" until `bunx decision-oracle oracle init` declares the entity) — one value per environment.
+
+# --- Connectors ---
+# AI checks + the duplicate lane's same-event judge. Default provider: the Cloudflare AI Gateway —
+# the `ai` binding + AI_GATEWAY_ID (wrangler.jsonc); nothing secret here. `facts run` in a
+# terminal has no binding, so it calls the gateway's REST endpoint with these two:
+# CLOUDFLARE_ACCOUNT_ID="..."
+# CLOUDFLARE_API_TOKEN="..."        # Workers AI: Read
+# Only with AI_PROVIDER=openrouter:
+# OPENROUTER_API_KEY="sk-or-..."
+# HMAC key for the duplicate-detection body digest (a rubric declaring `unique`). Keep it for the
+# oracle's lifetime — rotating it orphans every registered digest. Generate one with:
+#   openssl rand -base64 32
+UNIQUE_HMAC_KEY="change-me-to-a-long-random-string"
+
+# --- Decision API lane ---
+# The lane (paid, off-chain claims at /v1/api) is switched by API_LANE in wrangler.jsonc — per env,
+# "false" by default. Its only secret:
+# Encrypts webhook signing secrets at rest (every endpoint's, and each source's own) — one per
+# deployment, kept for its lifetime (rotating it strands every stored secret). REQUIRED when
+# API_LANE is on: the worker refuses to start without it. Generate one with:
+#   openssl rand -base64 32
+# (deployed: wrangler secret put WEBHOOK_ENCRYPTION_KEY [--env testnet|production])
+# WEBHOOK_ENCRYPTION_KEY="change-me-to-a-long-random-string"
+# Where your earnings land is NOT a secret: EARNINGS_ADDRESS (ixo1…, PAY and USDC on IXO) and
+# EARNINGS_BASE_WALLET (0x…, USDC on Base) live in wrangler.jsonc `vars`, per env. Each offer names
+# them as its payTo; a way to pay whose address is unset is not offered. For `wrangler dev` only:
+# EARNINGS_ADDRESS="ixo1..."
+
+# --- Observability ---
+# Sentry DSN. Unset ⇒ error reporting is a no-op (local dev and CI never ship events).
+# SENTRY_DSN=   # unset = Sentry off; an empty string is refused by the config schema
+# Sentry tuning. Not secrets — deployed, they live in wrangler.jsonc `vars` per env; set them here
+# only to try them under `wrangler dev`. Unset ⇒ 0.1 of requests traced, environment = ENVIRONMENT.
+# SENTRY_TRACES_SAMPLE_RATE="1"
+# SENTRY_ENVIRONMENT="local"
+# A Slack-compatible incoming webhook for ops alerts (a paused collection, a dead webhook, a lost
+# settlement, a failing cron job) — one message per condition per 30 minutes. The URL is the
+# credential. Unset ⇒ alerts reach Sentry only (nowhere without SENTRY_DSN).
+# OPS_ALERT_WEBHOOK_URL=   # unset = no Slack alerts; an empty string counts as unset
+# Read-only access to GET /v1/admin/status for a monitoring service (e.g. your decision engine's
+# 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>"
+
+# --- Local dev logging ---
+# Pretty, colorized log lines for the terminal. Local-only: this file is never
+# uploaded, so deployed envs always emit JSON (what Workers Logs ingests).
+LOG_PRETTY="true"
+
+# --- Local harness / self-hosted stacks ---
+# When your claim bot is NOT reachable at the derived
+# `https://claim.bot.<homeserver domain>` (e.g. a local testing harness runs
+# it on a plain host:port), set the URL to use as-is. Never set in deployed
+# environments — the derivation is the production behavior.
+# CLAIM_BOT_URL_OVERRIDE="http://localhost:34083"
+
+# EVAL_ENGINE_HOSTNAME is normally left unset and defaults per IXO_NETWORK.
+# Set it here ONLY to point at a local engine or a tunnel instead of the network's real engine:
+# EVAL_ENGINE_HOSTNAME="localhost:8787"
+
+# AUTH_HUB_URL (the OAuth server of /v1/mcp) also defaults per IXO_NETWORK. Set it ONLY for a
+# local AuthHub; its did:web is then the one the approvals back-channel accepts:
+# AUTH_HUB_URL="http://localhost:8787"

package/templates/project/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2

package/templates/project/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository.
+
+## What this is
+
+`{{name}}` — an IXO **evaluation oracle** on Cloudflare Workers, built on `@ixo/decision-oracle`. It
+pulls claims from the collections it was hired for, produces the **facts** the collection's rubric
+asks for, sends them to the IXO decision engine, and signs the verdict on chain.
+
+## Ours, and the package's
+
+- `src/facts/index.ts` (and anything it imports) is **the work**: one handler per fact name the
+  rubric declares and the stock lane cannot answer. Everything a handler needs is injected as
+  `tools`; handler files import only `@ixo/decision-oracle/facts` (`defineFacts`, `fact`, types).
+- `src/index.ts` declares what this oracle is: name, `supportedProtocols`, `pricing`, `policies`.
+- `wrangler.jsonc` + `.dev.vars` are deployment: bindings, network, identity, secrets. Binding and
+  var names are the package's contract — never rename them.
+- Everything else — claim pulling, the engine handshake, the D1 ledgers, review folds, the chain
+  write, billing pauses, notifications — is `@ixo/decision-oracle`. Read its README before rebuilding.
+- The package ships its own docs: `node_modules/@ixo/decision-oracle/docs/api.md` (the complete
+  reference — every export, option, default and cap) and `.../docs/guide.md` (building and
+  operating an oracle, end to end). Read those before guessing at an import or a default.
+
+## Skills
+
+`.claude/skills/` holds the skills shipped with the package — `create-oracle` (the build runbook),
+`write-facts` (one fact handler at a time), `create-rubric`, `publish-protocol`,
+`create-collection`, `decision-api-oracle` (the Decision API lane: deploy, register, verify). Use
+them for those workflows rather than improvising, and refresh them after upgrading:
+`bunx decision-oracle skills sync`.
+
+## The two rules
+
+1. **Never fake an ok.** A fact that could not be established is `fact.error(detail)`, never `false`
+   and never a guess — the rubric's own `onError` decides what it means. A handler that turns a
+   failure into an approval is the one unrecoverable bug in an oracle.
+2. **Never decide here.** No rubric parsing, no thresholds, no gates, no binding to the claim form.
+   The engine judges; this project produces facts and signs.
+
+## Working here
+
+- `bun run check` before you finish; `bun run cf-typegen` after any `wrangler.jsonc` binding or var
+  change. Handler tests are plain vitest with `@ixo/decision-oracle/testing` — never real network.
+  Comments explain **why** (an invariant, a source's quirk), not what.

package/templates/project/README.md

@@ -0,0 +1,199 @@
+# {{name}}
+
+An IXO **evaluation oracle**, built on
+[`@ixo/decision-oracle`](https://www.npmjs.com/package/@ixo/decision-oracle). It pulls each new claim from
+the collections you were hired for, produces the **facts** the collection's rubric asks for, sends
+them to the IXO **decision engine** — the deterministic decider you pay per decision — and signs
+the verdict on chain with your own key.
+
+The rubric is the work order. The engine decides. You produce facts and sign.
+
+Everything else — pulling claims, the engine handshake, the D1 ledgers, review folds, the chain
+write, billing pauses, email and Matrix notices — is the package's. What is yours is three files:
+
+| File | What it is |
+| --- | --- |
+| `src/index.ts` | what this oracle IS: its listing, its price, its policies |
+| `src/facts/index.ts` | how it produces the facts a rubric asks for — the only oracle-specific code |
+| `wrangler.jsonc` | where it runs: bindings, the network, its identity |
+
+## 1. Install
+
+```bash
+bun install
+bun run cf-typegen        # generates worker-configuration.d.ts from wrangler.jsonc
+```
+
+## 2. Storage
+
+Create the two bindings and paste their ids into `wrangler.jsonc` (once per env you deploy):
+
+```bash
+wrangler d1 create {{name}}
+wrangler kv namespace create CACHE_KV
+bun run db:migrate        # applies the package's migrations to the local D1
+```
+
+The schema ships with `@ixo/decision-oracle` — `migrations_dir` points into `node_modules`, so you
+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.
+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`.
+
+| Secret | Derives | Public var(s) in `wrangler.jsonc` |
+| --- | --- | --- |
+| `SERVICE_ED25519_MNEMONIC` | the did:web key — `SHA256(mnemonic)` → Ed25519 | `ORACLE_HOSTNAME` — the host `did:web:<host>` is served from |
+| `ORACLE_SECP_MNEMONIC` | the chain wallet (cosmos path, `ixo` prefix) that signs `MsgEvaluateClaim` | `ORACLE_ADDRESS` (its `ixo1…` address), `ORACLE_DID` (`did:ixo:<address>`), `ORACLE_MATRIX_USER_ID` (`@did-ixo-<address>:<homeserver>`) |
+| _(none)_ | `ORACLE_ENTITY_DID` — the on-chain oracle ENTITY (step 7), not a key; the portal resolves this oracle from its `#eval` service, so a review card's `oracleDid` must be it | `ORACLE_ENTITY_DID` (optional; unset ⇒ `ORACLE_DID`, portal-page review only) |
+| `OWNER_DELEGATION_CAR` | not derived — forwarded verbatim at register; the engine bills the OWNER's credits per decision, never this oracle's wallet | none — minted by the owner with `bunx decision-oracle login` then `bunx decision-oracle delegation --for engine` |
+
+`ORACLE_ADDRESS` is asserted against the mnemonic at first use — a mismatch fails loud, never signs
+as someone else.
+
+## 4. The work order
+
+A rubric is authored and anchored on chain against a protocol; the engine turns it into a
+**manifest** — the list of `ext.<name>` and `ai.<name>` facts your oracle must produce, with the
+type each expects and what happens when one cannot be answered. Ask for it in plain words:
+
+```bash
+bunx decision-oracle protocol review <protocol did>
+```
+
+Every declared name has a **stock** lane already: an external source becomes a UCAN-signed POST to
+the endpoint the rubric declares, an AI check runs the configured AI provider (Cloudflare AI Gateway by default) with the rubric's own instructions.
+You only write a handler for the names stock cannot answer — typically anything that needs YOUR
+system, or a value the rubric derives.
+
+```bash
+bunx decision-oracle facts scaffold <protocol did>    # stubs + tests for exactly those names
+```
+
+## 5. Write the handlers
+
+One name, one function. Return a plain value for the happy path; return `fact.error(detail)` when
+the truth is unreachable — the runner stamps the rubric's own `onError` (a handler can never turn
+a failure into an approval, and can never pick a different `onError`).
+
+```ts
+import { defineFacts, fact } from "@ixo/decision-oracle/facts";
+
+export const facts = defineFacts({
+  ext: {
+    // input: { name, expected, send, unresolved, claim, answers, ctx, settings, manifest }
+    deliveryConfirmed: async ({ send }, tools) => {
+      const res = await tools.http.json<{ status: string }>(
+        `https://courier.example/deliveries/${send.reference}`,
+      );
+      if (!res.ok) return fact.error(`courier responded ${res.status}`);
+      return res.body?.status === "delivered";        // boolean | number ⇒ an `ok` fact
+    },
+  },
+  ai: {
+    // "*" answers every AI check you did not name; `tools.stock()` runs the lane you would replace
+    // "*": async (_input, tools) => tools.stock(),
+  },
+});
+```
+
+The `tools` a handler is handed:
+
+| Tool | For |
+| --- | --- |
+| `tools.stock()` | run the stock lane for this very fact (wrap it, don't reimplement it) |
+| `tools.http.json(url, init?)` | a JSON request with retries, a timeout, the SSRF guard and a recorded transcript — never throws for an HTTP outcome |
+| `tools.http.json(url, { ucan: true })` | the call signed as this oracle for that URL's host, for a source that authenticates you — capability `ixo:external-source`; `ucan: { capability }` for your own (never the rubric's `expected.capability`) |
+| `tools.ai.judge(instructions, inputs)` | the stock judge with YOUR rules |
+| `tools.attachments.on(question)` / `.bytes(att)` | the claim's files |
+| `tools.c2pa.screen(bytes)` | Content Credentials on an image |
+| `tools.agreement()` | the buyer's statement for this collection — read it LAST |
+| `tools.logger`, `tools.config`, `tools.env` | logging and your own bindings/secrets |
+
+`throw fact.retryLater(detail)` when a source is temporarily down: the workflow step retries and
+the facts already answered are kept. Anything else that throws becomes an `error` fact, logged.
+
+Test them without a Worker — plain vitest, fake tools:
+
+```bash
+bun run test
+bunx decision-oracle facts run --protocol <protocol did> --claim claim.json --preview
+```
+
+`claim.json` is a flat answers object under the question names the rubric reads — or the full
+`{ answers, attachments }` envelope when the claim carries files. `--preview` asks the engine for
+the decision your facts would produce, without recording anything.
+
+## 6. Run it
+
+```bash
+bun run dev     # local D1 under .wrangler/state; --test-scheduled, so you can fire the cron:
+curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"
+```
+
+`GET /v1/info` is your public listing; `GET /.well-known/did.json` is your identity. Everything
+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
+```
+
+The Custom Domain in `routes` must equal `ORACLE_HOSTNAME` — the did:web document is served from
+it, and that is how anyone verifies who you are.
+
+`GET /v1/info` only answers a portal that already knows your host. For discovery that starts from
+the protocol, declare yourself on chain — an oracle entity, a `#eval` service pointing at your
+host, a `linkedEntity` per supported protocol, and the back-link on the protocol itself:
+
+```bash
+bunx decision-oracle login                                        # once per network (AuthHub)
+bunx decision-oracle oracle init --protocol <protocol did> --kit-url https://<your host>
+```
+
+Ownership vs. runtime identity: the oracle entity is owned by whoever logged in via AuthHub;
+`ORACLE_ADDRESS` / `ORACLE_DID` stay this oracle's runtime identity — what signs `MsgEvaluateClaim`
+and what a commissioner's grant must name. Put the entity DID it prints in `ORACLE_ENTITY_DID`.
+
+Keep `supportedProtocols` in `src/index.ts` in lockstep with what you declared on chain: register
+enforces only the config side, so a protocol declared on chain but missing from the config (or the
+reverse) is a drift nothing can see for you.
+
+## 8. Get hired
+
+A commissioner grants `ORACLE_ADDRESS` an `EvaluateClaimAuthorization` on their collection (the
+portal's Grant Role flow) and registers it with you:
+
+```bash
+bunx decision-oracle register --collection <collection id>
+bunx decision-oracle scan --collection <collection id>     # discover + start now, instead of next tick
+```
+
+Registration is refused, loudly, unless the collection's on-chain evaluation payment meets your
+fee — `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` in `wrangler.jsonc` (per env: a `uixo` stand-in
+on devnet/testnet, real USDC on mainnet, where they are required), else the `pricing` in
+`src/index.ts`. That payment is how you earn.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `bun run dev` | `wrangler dev` with a local D1 and the cron fireable by hand |
+| `bun run check` | typecheck + lint + tests — run before you finish |
+| `bun run test` | handler tests (plain node, no Worker) |
+| `bun run cf-typegen` | REQUIRED after any `wrangler.jsonc` binding/var change |
+| `bun run db:migrate` / `db:migrate:remote` | apply the package's migrations locally / to the deployed D1 |
+| `bun run build` | dry-run deploy — bundle validation |
+| `bun run deploy[:testnet\|:production]` | deploy the named env |
+| `bunx decision-oracle --help` | the full CLI (identity, protocol, facts, register, scan) |
+| `bunx decision-oracle skills sync` | refresh `.claude/skills/` from the installed package |
+
+## The two rules
+
+1. **Never fake an ok.** A fact you could not establish is `fact.error(detail)` — the rubric decides
+   what that means. Returning `false` says "I checked, and it is false".
+2. **Never decide here.** This oracle produces facts and signs the verdict; the engine judges them
+   against the live claim form. No rubric parsing, no thresholds, no gates in this project.

package/templates/project/biome.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!worker-configuration.d.ts", "!dist", "!.wrangler", "!protocol"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always"
+    }
+  }
+}

package/templates/project/gitignore

@@ -0,0 +1,29 @@
+# deps
+node_modules/
+
+# build output (`bun run build` — the wrangler dry-run bundle)
+dist/
+
+# wrangler / local runtime state (includes the local D1 database under .wrangler/state)
+.wrangler/
+
+# secrets: .dev.vars is read by `wrangler dev` and never uploaded — keep the example, never the file
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+
+# generated binding types (regenerate with `bun run cf-typegen`)
+worker-configuration.d.ts
+
+# UCAN delegation CARs — credentials, never committed
+*.car
+
+# host tooling env
+.env
+.env.*
+!.env.example
+
+# logs / misc
+*.log
+.DS_Store
+coverage/