@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/routes/v1/claims.js

@@ -0,0 +1,153 @@
+/**
+ * The per-claim reads — where a claim got to (`claim_ingests`), what the engine decided
+ * (`decisions`), and any human answers (`claim_reviews`). UCAN-guarded like the rest of `/v1/*`;
+ * on top of that, READ access is the chain owner's or an evaluate-grant holder's (shared.ts
+ * `assertCanRead`), and one claim's record is also a live reviewer's of its collection (company
+ * authority D2: they answer from it) and its own submitter's (the claim's on-chain agent) — who
+ * sees the decision and its public receipt, but never the review's answers.
+ * Responses are straight selects — the `decision` json IS the API shape (codes, scores,
+ * identifiers; the row never held answer values).
+ *
+ *   GET  /v1/claims/:claimId          — the full record (ingest ⟕ decision ⟕ review)
+ *   GET  /v1/claims?collectionId=…    — summary list, newest first, keyset-paginated
+ *   DELETE /v1/claims/:claimId/body   — the collection's chain owner erases the claim's answer
+ *                                       copies (company authority F14; lib/claim-erase.ts)
+ *
+ * The review lane (answering a `review` verdict) is `/v1/reviews/:claimId` (reviews.ts).
+ */
+import { and, desc, eq, lt, or } from "drizzle-orm";
+import { Hono } from "hono";
+import { z } from "zod";
+import { claimIngests, decisions } from "../../db/schema.js";
+import { eraseChainClaim } from "../../lib/claim-erase.js";
+import { decodeCursor, encodeCursor } from "../../lib/cursor.js";
+import { AppError } from "../../lib/errors.js";
+import { validate } from "../../lib/validator.js";
+import { assertCanRead, assertChainOwner, decisionBody, ingestBody, reviewBody } from "./shared.js";
+export const claims = new Hono();
+// Same garbage guard as the workflow: real claimIds are CIDs and Matrix event ids — anything
+// printable-ASCII of sane length; the row lookup is the actual validation.
+const ClaimParam = z.object({ claimId: z.string().regex(/^[\x21-\x7e]{1,512}$/) });
+const ListQuery = z.object({
+    collectionId: z
+        .string()
+        .min(1)
+        .max(256)
+        .regex(/^[A-Za-z0-9._:-]+$/),
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+    cursor: z.string().max(1024).optional(),
+});
+// --- GET /v1/claims?collectionId=… — the list view -----------------------------------------------
+claims.get("/", validate("query", ListQuery), async (c) => {
+    const { collectionId, limit, cursor } = c.req.valid("query");
+    await assertCanRead(c, collectionId);
+    const after = cursor ? decodeCursor(cursor) : null;
+    const db = await c.var.db();
+    const rows = await db
+        .select({
+        claimId: claimIngests.claimId,
+        ingestStatus: claimIngests.status,
+        error: claimIngests.error,
+        createdAt: claimIngests.createdAt,
+        updatedAt: claimIngests.updatedAt,
+        verdict: decisions.verdict,
+        decisionStatus: decisions.status,
+        resultDigest: decisions.resultDigest,
+        receiptCid: decisions.receiptCid,
+        chainStatus: decisions.chainStatus,
+        txHash: decisions.txHash,
+        decidedAt: decisions.createdAt,
+    })
+        .from(claimIngests)
+        .leftJoin(decisions, eq(decisions.claimId, claimIngests.claimId))
+        .where(and(eq(claimIngests.collectionId, collectionId), after
+        ? or(lt(claimIngests.createdAt, after.createdAt), and(eq(claimIngests.createdAt, after.createdAt), lt(claimIngests.claimId, after.claimId)))
+        : undefined))
+        .orderBy(desc(claimIngests.createdAt), desc(claimIngests.claimId))
+        .limit(limit + 1);
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    return c.json({
+        items: page.map((r) => ({
+            claimId: r.claimId,
+            ingestStatus: r.ingestStatus,
+            error: r.error,
+            createdAt: r.createdAt.toISOString(),
+            updatedAt: r.updatedAt.toISOString(),
+            // Null until the decide step has run (the decision row is left-joined).
+            verdict: r.verdict ?? null,
+            decisionStatus: r.decisionStatus ?? null,
+            resultDigest: r.resultDigest ?? null,
+            receiptCid: r.receiptCid ?? null,
+            chainStatus: r.chainStatus ?? null,
+            txHash: r.txHash ?? null,
+            decidedAt: r.decidedAt?.toISOString() ?? null,
+        })),
+        nextCursor: rows.length > limit && last ? encodeCursor(last.createdAt, last.claimId) : null,
+    });
+});
+// --- GET /v1/claims/:claimId — the full record ---------------------------------------------------
+claims.get("/:claimId", validate("param", ClaimParam), async (c) => {
+    const { claimId } = c.req.valid("param");
+    const db = await c.var.db();
+    const [ingest, decision, review] = await Promise.all([
+        db.query.claimIngests.findFirst({ where: (t, { eq: eq_ }) => eq_(t.claimId, claimId) }),
+        db.query.decisions.findFirst({ where: (t, { eq: eq_ }) => eq_(t.claimId, claimId) }),
+        db.query.claimReviews.findFirst({ where: (t, { eq: eq_ }) => eq_(t.claimId, claimId) }),
+    ]);
+    // The ingest row is the ledger: no row means "this oracle hasn't seen the claim". `expected`:
+    // the portal polls just-submitted claims before the cron ingests them — a breadcrumb, not a warn.
+    if (!ingest) {
+        throw AppError.notFound(`Oracle has not seen claim ${claimId}`, { expected: true });
+    }
+    const { asAgent } = await assertCanRead(c, ingest.collectionId, {
+        reviewers: true,
+        agentOf: claimId,
+    });
+    // The submitter sees the decision and its receipt — public by CID anyway, and the receipt names
+    // who reviewed — but never the review's ANSWERS, nor the internal failure text (RPC / admin
+    // detail) of the ingest, the chain write and the errored facts. `reviewerDid` is nulled for tidiness, not secrecy.
+    const ingestView = ingestBody(ingest);
+    const decisionView = decision ? decisionBody(decision) : null;
+    const reviewView = review ? reviewBody(review) : null;
+    return c.json({
+        claimId,
+        collectionId: ingest.collectionId,
+        ingest: asAgent ? { ...ingestView, error: null } : ingestView,
+        decision: decisionView && asAgent
+            ? { ...decisionView, chainError: null, erroredFacts: null }
+            : decisionView,
+        review: reviewView && asAgent ? { ...reviewView, answers: null, reviewerDid: null } : reviewView,
+    });
+});
+// --- DELETE /v1/claims/:claimId/body — the owner's erase -----------------------------------------
+/**
+ * The owner erases one claim's answer copies (company authority D12, F14): the fact transcripts and
+ * the registry text go (lib/claim-erase.ts). The oracle never erases chain-lane data on its own —
+ * this route is how an organisation deletes its own. The collection's CURRENT chain owner only, read
+ * live (`assertChainOwner`) — the enroller, grant holders and `ORACLE_ADMIN_DIDS` get 403: the data
+ * is the owner's. Idempotent: a second call is `204` again. A Decision API claim has its own route
+ * (`DELETE /v1/api/claims/:claimId/body`), so it is `404` here, as an unseen claim is. A claim still
+ * being decided (`queued` / `processing`) is `409`: its evaluate would write the transcripts and the
+ * registry text again after the erase (and a cleared fact cache would buy its handlers twice).
+ */
+claims.delete("/:claimId/body", validate("param", ClaimParam), async (c) => {
+    const { claimId } = c.req.valid("param");
+    const db = await c.var.db();
+    const ingest = await db.query.claimIngests.findFirst({
+        columns: { collectionId: true, lane: true, status: true },
+        where: (t, { eq: eq_ }) => eq_(t.claimId, claimId),
+    });
+    if (ingest?.lane !== "chain") {
+        throw AppError.notFound(`Oracle has not seen chain claim ${claimId}`);
+    }
+    await assertChainOwner(c, ingest.collectionId, "erase its claims' data");
+    if (ingest.status === "queued" || ingest.status === "processing") {
+        throw AppError.conflict(`Claim ${claimId} is still being decided; erase it once it's decided (GET /v1/claims/${claimId})`);
+    }
+    await eraseChainClaim(db, claimId);
+    c.get("metrics").count("claims.erased", 1, { op: "chain" });
+    c.get("logger").info("claims.erased", { claimId, collectionId: ingest.collectionId });
+    return c.body(null, 204);
+});
+//# sourceMappingURL=claims.js.map

package/dist/routes/v1/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../../../src/routes/v1/claims.ts"],"names":[],"mappings":"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"}

package/dist/routes/v1/collections.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The marketplace "hire" handshake (README "How a claim flows" step 1). UCAN-guarded. The
+ * enrollment rules: ANYONE holding evaluate rights on the collection may register it; the
+ * collection's OWNER is the one paying the evaluation fees; and the collection's on-chain
+ * evaluation payment must match what this oracle requires, because that payment is the only way
+ * the oracle gets paid.
+ *
+ * So four gates, in order:
+ *   1. WHO — the caller is the collection entity's owner (`claimCollection.entity` → `entity.owner`),
+ *      or holds an active on-chain `EvaluateClaimAuthorization` for it (granter = the collection
+ *      admin — the portal's "Grant Role" flow). One permission model, not two (lib/ixo/authz.ts).
+ *   2. HIRED — THIS oracle holds that same grant, or it can never sign `MsgEvaluateClaim` (409).
+ *   3. PROTOCOL — if the oracle config's `supportedProtocols` (the `GET /v1/info` listing) is non-empty,
+ *      the collection's protocol DID must be in it (409): a provider that only advertises certain
+ *      protocols must not silently start watching one it was never built to produce facts for.
+ *      Checked BEFORE payment: a wrong-protocol collection should
+ *      hear "this oracle won't serve you" first, not be sent off to fix a payment that would never
+ *      have mattered.
+ *   4. PAID — `Payments.evaluation` is in the oracle's denom and ≥ its fee (the config's `pricing`,
+ *      `pricing.byProtocol[protocol] ?? pricing.evaluation`; lib/ixo/payment.ts), else 402: the
+ *      chain's 80/10/10 split of that coin is the oracle's income — a zero fee is the one legal
+ *      exception, for a protocol whose income isn't that split.
+ *
+ * `ownerDid` on the row is ALWAYS the chain owner, never the enroller: the pull path reads the
+ * owner→oracle Matrix delegation keyed on it (lib/ixo/index.ts), and that delegation is the owner's
+ * to issue. The enroller is recorded beside it (`enrolledByDid`) for the read gate. We deliberately
+ * do NOT read ownership off `collection.admin`: on-chain, a collection's `admin` is the entity
+ * *account* address (a module-derived operating address), NOT the owner's wallet — see portal
+ * `useGrantAgentAndEvaluatorAuthZ.ts`, which threads `admin` and `ownerAddress` as distinct values.
+ *
+ * The delegation is persisted HERE so the read path needs zero UCAN-Store round trips: the body may
+ * carry the CAR directly (verified against the OWNER before we trust it), otherwise we fetch the
+ * owner's deposited delegation from the store once. Either way it lands on the row.
+ *
+ *   POST /v1/collections/register              { collectionId, delegationCar?, contactEmail? }
+ *   GET  /v1/collections                       the collections the caller owns or enrolled
+ *   POST /v1/collections/:collectionId/pause   owner / enroller / operator — the cron enqueues nothing
+ *   POST /v1/collections/:collectionId/resume  same gate
+ *   POST /v1/collections/:collectionId/scan    the read gate (+ grant holders) — discover + start NOW
+ *   PATCH /v1/collections/:collectionId/settings  the CURRENT chain owner only — `{ operatorAmounts }`
+ */
+import { Hono } from "hono";
+import type { AppEnv } from "../../context.js";
+export declare const collections: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=collections.d.ts.map

package/dist/routes/v1/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../../src/routes/v1/collections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAc,MAAM,EAAE,MAAM,eAAe,CAAC;AAiBxD,eAAO,MAAM,WAAW,qDAAqB,CAAC"}

package/dist/routes/v1/collections.js

@@ -0,0 +1,201 @@
+/**
+ * The marketplace "hire" handshake (README "How a claim flows" step 1). UCAN-guarded. The
+ * enrollment rules: ANYONE holding evaluate rights on the collection may register it; the
+ * collection's OWNER is the one paying the evaluation fees; and the collection's on-chain
+ * evaluation payment must match what this oracle requires, because that payment is the only way
+ * the oracle gets paid.
+ *
+ * So four gates, in order:
+ *   1. WHO — the caller is the collection entity's owner (`claimCollection.entity` → `entity.owner`),
+ *      or holds an active on-chain `EvaluateClaimAuthorization` for it (granter = the collection
+ *      admin — the portal's "Grant Role" flow). One permission model, not two (lib/ixo/authz.ts).
+ *   2. HIRED — THIS oracle holds that same grant, or it can never sign `MsgEvaluateClaim` (409).
+ *   3. PROTOCOL — if the oracle config's `supportedProtocols` (the `GET /v1/info` listing) is non-empty,
+ *      the collection's protocol DID must be in it (409): a provider that only advertises certain
+ *      protocols must not silently start watching one it was never built to produce facts for.
+ *      Checked BEFORE payment: a wrong-protocol collection should
+ *      hear "this oracle won't serve you" first, not be sent off to fix a payment that would never
+ *      have mattered.
+ *   4. PAID — `Payments.evaluation` is in the oracle's denom and ≥ its fee (the config's `pricing`,
+ *      `pricing.byProtocol[protocol] ?? pricing.evaluation`; lib/ixo/payment.ts), else 402: the
+ *      chain's 80/10/10 split of that coin is the oracle's income — a zero fee is the one legal
+ *      exception, for a protocol whose income isn't that split.
+ *
+ * `ownerDid` on the row is ALWAYS the chain owner, never the enroller: the pull path reads the
+ * owner→oracle Matrix delegation keyed on it (lib/ixo/index.ts), and that delegation is the owner's
+ * to issue. The enroller is recorded beside it (`enrolledByDid`) for the read gate. We deliberately
+ * do NOT read ownership off `collection.admin`: on-chain, a collection's `admin` is the entity
+ * *account* address (a module-derived operating address), NOT the owner's wallet — see portal
+ * `useGrantAgentAndEvaluatorAuthZ.ts`, which threads `admin` and `ownerAddress` as distinct values.
+ *
+ * The delegation is persisted HERE so the read path needs zero UCAN-Store round trips: the body may
+ * carry the CAR directly (verified against the OWNER before we trust it), otherwise we fetch the
+ * owner's deposited delegation from the store once. Either way it lands on the row.
+ *
+ *   POST /v1/collections/register              { collectionId, delegationCar?, contactEmail? }
+ *   GET  /v1/collections                       the collections the caller owns or enrolled
+ *   POST /v1/collections/:collectionId/pause   owner / enroller / operator — the cron enqueues nothing
+ *   POST /v1/collections/:collectionId/resume  same gate
+ *   POST /v1/collections/:collectionId/scan    the read gate (+ grant holders) — discover + start NOW
+ *   PATCH /v1/collections/:collectionId/settings  the CURRENT chain owner only — `{ operatorAmounts }`
+ */
+import { desc, eq, or } from "drizzle-orm";
+import { Hono } from "hono";
+import { z } from "zod";
+import { processCollection } from "../../cron/collection.js";
+import { watchedCollections } from "../../db/schema.js";
+import { AppError } from "../../lib/errors.js";
+import { operatorAmountsEffective } from "../../lib/ixo/chain-write.js";
+import { registerCollection } from "../../lib/register.js";
+import { validate } from "../../lib/validator.js";
+import { notifyCollectionResumed } from "../../workflows/steps.js";
+import { assertCanManage, assertCanRead, assertChainOwner, collectionBody, collectionColumns, viewOf, } from "./shared.js";
+export const collections = new Hono();
+const CollectionId = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[A-Za-z0-9._:-]+$/);
+const RegisterBody = z.object({
+    collectionId: CollectionId,
+    /** The owner→oracle delegation (base64 CAR). Optional: absent → fetched from the UCAN Store. */
+    delegationCar: z.string().min(1).max(65536).optional(),
+    /**
+     * Where the commissioner is reached (review requests, pauses). Client-supplied on purpose: it is
+     * the caller naming a notification address, not an authorization input. Absent leaves the stored
+     * address alone (re-register is the "change my mind" path); "" clears it. On a re-register only
+     * the chain owner or the current enroller may change it (lib/register.ts) — anyone else's is 403.
+     */
+    contactEmail: z
+        .string()
+        .trim()
+        .max(254)
+        .pipe(z.union([z.email(), z.literal("")]))
+        .optional(),
+});
+const CollectionParam = z.object({ collectionId: CollectionId });
+// The four gates (WHO/HIRED/PROTOCOL/PAID), the delegation resolution, the upsert and the
+// paused→active notice all live in lib/register.ts, shared verbatim with the `registerCollection`
+// runtime export (../../runtime.ts) that a provider's own Workflow calls directly. This route is a
+// thin adapter: validate the body, build the ctx from the request, call, project the row. The body
+// schema deliberately does not expose `cursor` — only the runtime export can seed one.
+collections.post("/register", validate("json", RegisterBody), async (c) => {
+    const { collectionId, delegationCar, contactEmail } = c.req.valid("json");
+    const row = await registerCollection({
+        config: c.get("config"),
+        trace: c.get("trace"),
+        logger: c.get("logger"),
+        metrics: c.get("metrics"),
+        db: await c.var.db(),
+        env: c.env,
+    }, { collectionId, principal: c.get("principal"), delegationCar, contactEmail });
+    return c.json(collectionBody(viewOf(row)));
+});
+// --- GET /v1/collections — the collections the caller owns or enrolled --------------------------
+collections.get("/", async (c) => {
+    const { did } = c.get("principal");
+    const db = await c.var.db();
+    // F2 residual: listed by the row's memory (ownerDid / enrolledByDid), not the chain's answer now.
+    const rows = await db
+        .select(collectionColumns)
+        .from(watchedCollections)
+        .where(or(eq(watchedCollections.ownerDid, did), eq(watchedCollections.enrolledByDid, did)))
+        .orderBy(desc(watchedCollections.createdAt));
+    return c.json({ items: rows.map(collectionBody) });
+});
+// --- pause / resume — owner, enroller or operator (shared.ts `assertCanManage`) ------------------
+async function setStatus(c, collectionId, status) {
+    // Read BEFORE the write — the resume notice fires only on a REAL paused→active flip, never on an
+    // operator re-pausing an already-paused row or re-resuming an already-active one.
+    const watched = await assertCanManage(c, collectionId);
+    const db = await c.var.db();
+    const [row] = await db
+        .update(watchedCollections)
+        // An operator's pause has no engine reason; a resume clears whichever reason the engine set.
+        .set({ status, pausedReason: null })
+        .where(eq(watchedCollections.collectionId, collectionId))
+        .returning(collectionColumns);
+    if (!row)
+        throw AppError.internal("Status update returned no row");
+    const logger = c.get("logger");
+    logger.info(`collection.${status}`, { collectionId });
+    // Fail-soft: a notice failure must never fail the pause/resume response.
+    if (status === "active" && watched.status === "paused") {
+        await notifyCollectionResumed(db, {
+            logger,
+            metrics: c.get("metrics"),
+            config: c.get("config"),
+            trace: c.get("trace"),
+            cache: c.env.CACHE_KV,
+            email: c.env.EMAIL,
+        }, collectionId).catch((err) => logger.warn("collection.notice.failed", { collectionId, detail: String(err) }));
+    }
+    return c.json(collectionBody(row));
+}
+collections.post("/:collectionId/pause", validate("param", CollectionParam), (c) => setStatus(c, c.req.valid("param").collectionId, "paused"));
+collections.post("/:collectionId/resume", validate("param", CollectionParam), (c) => setStatus(c, c.req.valid("param").collectionId, "active"));
+// --- POST /v1/collections/:collectionId/scan — the nudge ------------------------------------------
+/**
+ * Run the cron's per-collection pass for THIS collection right now (demo / "I just submitted,
+ * where is it?"). Exactly the tick's code path — same dedupe, same cursor rules — so an eager
+ * caller can never double-start a claim. Paused means "enqueue nothing" and the nudge honors it.
+ */
+collections.post("/:collectionId/scan", validate("param", CollectionParam), async (c) => {
+    const { collectionId } = c.req.valid("param");
+    const watched = await assertCanRead(c, collectionId);
+    if (watched.status !== "active") {
+        throw AppError.conflict(`Collection ${collectionId} is paused — resume it first`);
+    }
+    const started = await processCollection({
+        deps: { config: c.get("config"), trace: c.get("trace") },
+        db: await c.var.db(),
+        env: c.env,
+        logger: c.get("logger"),
+        metrics: c.get("metrics"),
+    }, { collectionId, cursor: watched.cursor });
+    return c.json({ started });
+});
+// --- GET /v1/collections/:collectionId/settings — the owner's say, as the act lane reads it -------
+/**
+ * The settings for the Portal (S14): what the owner set, who set it, and whether it is in force NOW
+ * (`effective`) — computed by the act lane's own reading (`operatorAmountsEffective`) against the
+ * live owner, so the display can never say "allowed" while the lane pays its default. Same gate as
+ * the PATCH: the current chain owner only.
+ */
+collections.get("/:collectionId/settings", validate("param", CollectionParam), async (c) => {
+    const { collectionId } = c.req.valid("param");
+    const { owner } = await assertChainOwner(c, collectionId, "read its settings");
+    const db = await c.var.db();
+    const row = await db.query.watchedCollections.findFirst({
+        columns: { operatorAmounts: true, operatorAmountsBy: true },
+        where: eq(watchedCollections.collectionId, collectionId),
+    });
+    if (!row)
+        throw AppError.notFound(`Collection ${collectionId} is not watched by this oracle`);
+    return c.json({ ...row, effective: operatorAmountsEffective(row, owner) });
+});
+// --- PATCH /v1/collections/:collectionId/settings — the owner's say ------------------------------
+/**
+ * What only the collection's owner decides (company authority D7). `operatorAmounts`: whether the
+ * act seam's on-chain amount may stand (`allowed`) or the lane pays its default (`off`, the
+ * default — chain-write.ts). The owner sets it on the oracle the collection hired, which is also
+ * where the act lane reads it — together with who set it (`operatorAmountsBy`), so an ownership
+ * transfer turns it off until the new owner says yes again.
+ */
+const SettingsBody = z.strictObject({ operatorAmounts: z.enum(["off", "allowed"]) });
+collections.patch("/:collectionId/settings", validate("param", CollectionParam), validate("json", SettingsBody), async (c) => {
+    const { collectionId } = c.req.valid("param");
+    const { owner } = await assertChainOwner(c, collectionId);
+    const settings = c.req.valid("json");
+    const db = await c.var.db();
+    const [row] = await db
+        .update(watchedCollections)
+        .set({ ...settings, operatorAmountsBy: owner })
+        .where(eq(watchedCollections.collectionId, collectionId))
+        .returning(collectionColumns);
+    if (!row)
+        throw AppError.internal("Settings update returned no row");
+    c.get("logger").info("collection.settings", { collectionId, ...settings });
+    return c.json(collectionBody(row));
+});
+//# sourceMappingURL=collections.js.map

package/dist/routes/v1/collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.js","sourceRoot":"","sources":["../../../src/routes/v1/collections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EACL,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,MAAM,GACP,MAAM,UAAU,CAAC;AAElB,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,IAAI,EAAU,CAAC;AAE9C,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,oBAAoB,CAAC,CAAC;AAE/B,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,YAAY,EAAE,YAAY;IAC1B,gGAAgG;IAChG,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE;IACtD;;;;;OAKG;IACH,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,IAAI,EAAE;SACN,GAAG,CAAC,GAAG,CAAC;SACR,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;SACzC,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC,CAAC;AAEjE,0FAA0F;AAC1F,kGAAkG;AAClG,mGAAmG;AACnG,mGAAmG;AACnG,uFAAuF;AACvF,WAAW,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IACxE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1E,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAClC;QACE,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QACvB,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;QACzB,EAAE,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE;QACpB,GAAG,EAAE,CAAC,CAAC,GAAG;KACX,EACD,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,CAC7E,CAAC;IACF,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC,CAAC,CAAC;AAEH,mGAAmG;AAEnG,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IAC/B,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;IAC5B,kGAAkG;IAClG,MAAM,IAAI,GAAG,MAAM,EAAE;SAClB,MAAM,CAAC,iBAAiB,CAAC;SACzB,IAAI,CAAC,kBAAkB,CAAC;SACxB,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC;SAC1F,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC;AAEH,oGAAoG;AAEpG,KAAK,UAAU,SAAS,CAAC,CAAa,EAAE,YAAoB,EAAE,MAA2B;IACvF,iGAAiG;IACjG,kFAAkF;IAClF,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACvD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;IAC5B,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,CAAC,kBAAkB,CAAC;QAC3B,6FAA6F;SAC5F,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;SACnC,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;SACxD,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG;QAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,+BAA+B,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,CAAC,IAAI,CAAC,cAAc,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IAEtD,yEAAyE;IACzE,IAAI,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACvD,MAAM,uBAAuB,CAC3B,EAAE,EACF;YACE,MAAM;YACN,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;YACvB,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;YACrB,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;YACrB,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK;SACnB,EACD,YAAY,CACb,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACd,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAC/E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,WAAW,CAAC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACjF,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,QAAQ,CAAC,CAC1D,CAAC;AAEF,WAAW,CAAC,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAClF,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,QAAQ,CAAC,CAC1D,CAAC;AAEF,qGAAqG;AAErG;;;;GAIG;AACH,WAAW,CAAC,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IACtF,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,QAAQ,CAAC,QAAQ,CAAC,cAAc,YAAY,8BAA8B,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,iBAAiB,CACrC;QACE,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;QACxD,EAAE,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE;QACpB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;KAC1B,EACD,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CACzC,CAAC;IACF,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;AAC7B,CAAC,CAAC,CAAC;AAEH,qGAAqG;AAErG;;;;;GAKG;AACH,WAAW,CAAC,GAAG,CAAC,yBAAyB,EAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IACzF,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAC;IAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;IAC5B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC;QACtD,OAAO,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;QAC3D,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC;KACzD,CAAC,CAAC;IACH,IAAI,CAAC,GAAG;QAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,cAAc,YAAY,gCAAgC,CAAC,CAAC;IAC9F,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,wBAAwB,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;AAC7E,CAAC,CAAC,CAAC;AAEH,oGAAoG;AAEpG;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;AAErF,WAAW,CAAC,KAAK,CACf,yBAAyB,EACzB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,EAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,EAC9B,KAAK,EAAE,CAAC,EAAE,EAAE;IACV,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,gBAAgB,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;IAC5B,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,CAAC,kBAAkB,CAAC;SAC1B,GAAG,CAAC,EAAE,GAAG,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;SAC9C,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;SACxD,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG;QAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,iCAAiC,CAAC,CAAC;IACrE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,YAAY,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;AACrC,CAAC,CACF,CAAC"}

package/dist/routes/v1/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * v1 API surface — collection registration (the marketplace "hire" handshake), the claim reads,
+ * the review lane, and the operator's status (`/v1/admin/status`, ORACLE_ADMIN_DIDS).
+ *
+ * Claim ingestion deliberately has NO public endpoint: the cron pull is the system of record (the
+ * chain is truth, so a pushed claimId adds nothing we'd trust), and operator recovery happens via
+ * workflow reruns in the Cloudflare dashboard. Status/tracking lives in the `claim_ingests`
+ * ledger — readable per claim via `/v1/claims`.
+ */
+import { Hono } from "hono";
+import type { AppEnv } from "../../context.js";
+export declare const v1: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=index.d.ts.map

package/dist/routes/v1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/routes/v1/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAW5C,eAAO,MAAM,EAAE,qDAAqB,CAAC"}

package/dist/routes/v1/index.js

@@ -0,0 +1,41 @@
+/**
+ * v1 API surface — collection registration (the marketplace "hire" handshake), the claim reads,
+ * the review lane, and the operator's status (`/v1/admin/status`, ORACLE_ADMIN_DIDS).
+ *
+ * Claim ingestion deliberately has NO public endpoint: the cron pull is the system of record (the
+ * chain is truth, so a pushed claimId adds nothing we'd trust), and operator recovery happens via
+ * workflow reruns in the Cloudflare dashboard. Status/tracking lives in the `claim_ingests`
+ * ledger — readable per claim via `/v1/claims`.
+ */
+import { Hono } from "hono";
+import { except } from "hono/combine";
+import { requireAction } from "../../middleware/capability.js";
+import { ucanAuth } from "../../middleware/ucan-auth.js";
+import { admin } from "./admin.js";
+import { claims } from "./claims.js";
+import { collections } from "./collections.js";
+import { info } from "./info.js";
+import { oauth } from "./oauth.js";
+import { reviewers } from "./reviewers.js";
+import { reviews } from "./reviews.js";
+export const v1 = new Hono();
+/**
+ * Secure by default: EVERY v1 route requires a UCAN unless it is on this explicit public list.
+ * A new route is authenticated the moment it mounts — making an endpoint public is a conscious,
+ * greppable decision here, never an omission in a route file.
+ */
+const PUBLIC_V1_PATHS = [
+    "/v1/info", // the marketplace listing — a portal must be able to read it before it holds any
+    // credential for the collection it wants this oracle to evaluate.
+    "/v1/api/*", // the Decision API lane: its own router, its own auth on every route (`access()`).
+];
+// Authenticate, then hold the invocation to the route's ONE action (`middleware/capability.ts`).
+v1.use("*", except([...PUBLIC_V1_PATHS], ucanAuth, requireAction));
+v1.route("/admin", admin);
+v1.route("/claims", claims);
+v1.route("/collections", collections);
+v1.route("/collections", reviewers);
+v1.route("/info", info);
+v1.route("/oauth", oauth);
+v1.route("/reviews", reviews);
+//# sourceMappingURL=index.js.map

package/dist/routes/v1/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/routes/v1/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAU,CAAC;AAErC;;;;GAIG;AACH,MAAM,eAAe,GAAsB;IACzC,UAAU,EAAE,iFAAiF;IAC7F,kEAAkE;IAClE,WAAW,EAAE,mFAAmF;CACjG,CAAC;AACF,iGAAiG;AACjG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,eAAe,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC;AAEnE,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC1B,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC5B,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;AACtC,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;AACpC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACxB,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC1B,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC"}

package/dist/routes/v1/info.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `GET /v1/info` — the oracle's marketplace listing. Public, no
+ * ucanAuth: a portal shopping for an oracle has to be able to read this before it holds any
+ * credential for the collection it wants evaluated. The wire shape is FROZEN — a portal consumer
+ * is built against these exact field names; don't rename, nest, or omit any of them.
+ *
+ * `serviceDid` uses `oracleWebDid` (lib/ixo/ucan.ts) rather than `getDIDWeb` (lib/ixo/identity.ts):
+ * it's the same `did:web:<ORACLE_HOSTNAME>` string, but derived from the hostname alone, so this
+ * public route never depends on `SERVICE_ED25519_MNEMONIC` being configured.
+ */
+import { Hono } from "hono";
+import type { AppEnv } from "../../context.js";
+export declare const info: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=info.d.ts.map

package/dist/routes/v1/info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/routes/v1/info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAK5C,eAAO,MAAM,IAAI,qDAAqB,CAAC"}

package/dist/routes/v1/info.js

@@ -0,0 +1,75 @@
+/**
+ * `GET /v1/info` — the oracle's marketplace listing. Public, no
+ * ucanAuth: a portal shopping for an oracle has to be able to read this before it holds any
+ * credential for the collection it wants evaluated. The wire shape is FROZEN — a portal consumer
+ * is built against these exact field names; don't rename, nest, or omit any of them.
+ *
+ * `serviceDid` uses `oracleWebDid` (lib/ixo/ucan.ts) rather than `getDIDWeb` (lib/ixo/identity.ts):
+ * it's the same `did:web:<ORACLE_HOSTNAME>` string, but derived from the hostname alone, so this
+ * public route never depends on `SERVICE_ED25519_MNEMONIC` being configured.
+ */
+import { Hono } from "hono";
+import { oracleWebDid } from "../../lib/ixo/ucan.js";
+import { advertisedPrice, reviewBillingActive } from "../../lib/payments/review-billing.js";
+import { effectivePricing, getOracle } from "../../oracle.js";
+export const info = new Hono();
+/** Per review only while ACTIVE — IXO's plan for the oracle (review-billing.ts). */
+async function reviewBillingInfo(deps) {
+    if (!(await reviewBillingActive(deps)))
+        return { mode: "escrow", pricePerReview: null };
+    const amount = advertisedPrice(deps.config);
+    return {
+        mode: "x402",
+        pricePerReview: amount === null ? null : { denom: "upay", amount },
+    };
+}
+info.get("/", async (c) => {
+    const config = c.get("config");
+    // `pricing` carries `evaluation` and, when configured, `byProtocol` (oracle.ts) — both served
+    // verbatim, so a per-protocol fee shows up here the moment it's set, with no route change.
+    const { name, description, supportedProtocols, pricing, payouts } = getOracle().config;
+    const { actSummary, ...policies } = getOracle().config.policies;
+    // A marketplace listing changes by a redeploy, not by the request — long enough to spare a
+    // crawler, short enough that a price/policy edit shows up within minutes.
+    c.header("cache-control", "public, max-age=300");
+    return c.json({
+        name,
+        description,
+        did: config.ORACLE_DID,
+        address: config.ORACLE_ADDRESS,
+        // The on-chain oracle ENTITY (`oracle init`), where a console reads the oracle's name and image
+        // (its domain card / `#pro` profile / `#acard`). Distinct from `did` (the runtime account).
+        entityDid: config.ORACLE_ENTITY_DID || null,
+        serviceDid: oracleWebDid(config),
+        supportedProtocols,
+        // What register charges by: `pricing.evaluation` replaced by the per-network vars when set.
+        pricing: effectivePricing(pricing, config),
+        policies,
+        // Where the operator's earnings land (payments spec §3.2) — read-only, set in the oracle's
+        // config. Public on purpose: every 402 already names the address as its `payTo`, and it is on
+        // chain anyway. (Not `payouts`: that now means a company paying its people.)
+        earnings: {
+            address: config.EARNINGS_ADDRESS ?? null,
+            baseWallet: config.EARNINGS_BASE_WALLET ?? null,
+        },
+        // How a payout amount is chosen, so a portal can show it before a company opts in: per
+        // protocol, the claim answer that holds the decision-to-pay amount and its currency
+        // (`payouts` in oracle.ts, verbatim; a protocol absent here gets no decision to pay), and the
+        // operator's own summary of its `act` amounts (null without an act policy or a summary).
+        payouts: {
+            decisionToPay: payouts ?? {},
+            operatorAmount: policies.act && actSummary ? { summary: actSummary } : null,
+        },
+        // How a collection pays for its reviews, so a poster knows what to fund: `x402` — per review,
+        // from the company's credits (IXO's plan for the oracle allows it; the collection's evaluation leg
+        // stays empty) — or `escrow`, the collection's on-chain evaluation payment (`pricing`).
+        // `pricePerReview` is the published per-review price, the Agent Card's.
+        reviewBilling: await reviewBillingInfo({
+            config,
+            logger: c.get("logger"),
+            trace: c.get("trace"),
+            cache: c.env.CACHE_KV,
+        }),
+    });
+});
+//# sourceMappingURL=info.js.map

package/dist/routes/v1/info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../../../src/routes/v1/info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAU,CAAC;AAEvC,oFAAoF;AACpF,KAAK,UAAU,iBAAiB,CAAC,IAA+C;IAC9E,IAAI,CAAC,CAAC,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAiB,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IACjG,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO;QACL,IAAI,EAAE,MAAe;QACrB,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAe,EAAE,MAAM,EAAE;KAC5E,CAAC;AACJ,CAAC;AAED,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IACxB,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,8FAA8F;IAC9F,2FAA2F;IAC3F,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,CAAC,MAAM,CAAC;IACvF,MAAM,EAAE,UAAU,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;IAChE,2FAA2F;IAC3F,0EAA0E;IAC1E,CAAC,CAAC,MAAM,CAAC,eAAe,EAAE,qBAAqB,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,IAAI,CAAC;QACZ,IAAI;QACJ,WAAW;QACX,GAAG,EAAE,MAAM,CAAC,UAAU;QACtB,OAAO,EAAE,MAAM,CAAC,cAAc;QAC9B,gGAAgG;QAChG,4FAA4F;QAC5F,SAAS,EAAE,MAAM,CAAC,iBAAiB,IAAI,IAAI;QAC3C,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC;QAChC,kBAAkB;QAClB,4FAA4F;QAC5F,OAAO,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC;QAC1C,QAAQ;QACR,2FAA2F;QAC3F,8FAA8F;QAC9F,6EAA6E;QAC7E,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,CAAC,gBAAgB,IAAI,IAAI;YACxC,UAAU,EAAE,MAAM,CAAC,oBAAoB,IAAI,IAAI;SAChD;QACD,uFAAuF;QACvF,oFAAoF;QACpF,8FAA8F;QAC9F,yFAAyF;QACzF,OAAO,EAAE;YACP,aAAa,EAAE,OAAO,IAAI,EAAE;YAC5B,cAAc,EAAE,QAAQ,CAAC,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI;SAC5E;QACD,8FAA8F;QAC9F,mGAAmG;QACnG,wFAAwF;QACxF,wEAAwE;QACxE,aAAa,EAAE,MAAM,iBAAiB,CAAC;YACrC,MAAM;YACN,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;YACvB,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;YACrB,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;SACtB,CAAC;KACH,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}