@ixo/decision-oracle 0.2.16 → 0.2.18

package/docs/guide.md

@@ -427,6 +427,11 @@ generated image gives itself away only in fine detail (moiré, a pixel grid, gar
 downsamples out. `high` costs more image tokens per check; drop to `low` only for an oracle whose
 rules never turn on it.
 
+The judge thinks at `AI_REASONING_EFFORT` — `low` by default, the measured balance: no thinking
+loses quality on rule-by-rule judgment, and `medium` / `high` answer slower with more output tokens.
+Measure latency and cost on your own claims before raising it. Each attempt has 60 s (3 minutes
+when a PDF, video or audio input rides along), three attempts per call.
+
 ### Reading attachments, and image provenance
 
 Attachments arrive as **descriptors** — the bytes stay in Matrix, content-addressed. Ask for them by
@@ -1151,13 +1156,20 @@ keep all three, or that tier's jobs never run:
 An unknown cron string is a `cron.unknown` log line and runs nothing. A provider that adds a
 trigger of its own handles it in its own `scheduled` before delegating the rest to the oracle's.
 
+**The claims feed.** Every minute the oracle reads the chain's new claims ONCE, chain-wide, and
+starts the ones in collections it watches (`claims-feed`, [api.md](./api.md#cron-three-triggers)):
+a claim is usually picked up within a minute or two of landing, however many collections you
+watch. An hourly replay re-reads what turned 24 h old, for a claim Blocksync indexed late.
+
 **The cron tick.** `CRON_COLLECTIONS_PER_TICK` (default `25`, see [api.md §11](./api.md#11-configuration))
 bounds how many watched collections one tick visits; a fleet larger than that rotates in over later
 ticks, least-recently-scanned first. Raise it for a large fleet. To act on one collection sooner
 than the next tick — e.g. the instant your own webhook sees a submission — call
 `scanCollection(env, collectionId)` from `@ixo/decision-oracle/runtime`, or hit
 `POST /v1/collections/:collectionId/scan`; both run the exact same discover-and-start pass the tick
-does, so a webhook and the cron racing on one claim can never double-start it.
+does, so a webhook and the cron racing on one claim can never double-start it. Only the tick's own
+visit moves a collection to the back of the rotation: an early webhook scan that finds nothing
+leaves it where it was.
 
 **Watching a claim.** `GET /v1/claims?collectionId=<id>` lists newest-first with a keyset cursor;
 `GET /v1/claims/:claimId` is the full record — the ingest row, the decision (codes, scores,

package/migrations/0027_cron_state.sql

@@ -0,0 +1,4 @@
+CREATE TABLE `cron_state` (
+	`name` text PRIMARY KEY NOT NULL,
+	`value` text NOT NULL
+);