@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/routes/v1/oauth.js

@@ -0,0 +1,256 @@
+/**
+ * The approvals back-channel (MCP over OAuth, spec 2026-10-06; AuthHub plan Task 9; S3 review §3,
+ * §6) — AuthHub's approve page reads an approval from HERE and posts the user's answer back:
+ *
+ *   GET  /v1/oauth/approvals/:approvalId   `oauth/approval/read`     what the page shows
+ *   POST /v1/oauth/approvals/:approvalId   `oauth/approval/approve`  approve (+ delegation) | decline
+ *   GET | PUT | DELETE /v1/oauth/standing/:grantId   `oauth/standing/read | set | revoke`
+ *                                          a grant's auto-approve (standing.ts) — set only where
+ *                                          `policies.allowStandingApprovals` (D8), else 403
+ *
+ * The invoker must BE AuthHub's `did:web` (`AUTH_HUB_URL`): a UCAN from anyone else is 403 even
+ * with the right action, and the legacy `*` is never accepted here (`middleware/capability.ts`
+ * `STRICT_ACTIONS`). Anything but a known, pending, unexpired approval is 404 — AuthHub binds the
+ * row's `did` and `grantId` to its signed-in user; the oracle binds the delegation to the row.
+ *
+ * The delegation is a bearer credential: it is validated, stored, and never logged or returned —
+ * the GET has no field that could carry it.
+ *
+ * Accepted risk (S3 review L2): the chain lane keeps no replay store, so a leaked
+ * `oauth/approval/approve` invocation can be replayed within its life (≤ 600 s; AuthHub signs 120 s).
+ * All it can do is DECLINE a pending approval it already knows the id of — approving needs a payment
+ * delegation the user's own key signed, for exactly this approval's price, this oracle and our
+ * facilitator, which the token does not carry. A wrongly declined approval costs the user one
+ * re-approval, never money.
+ */
+import { Hono } from "hono";
+import { z } from "zod";
+import { apiAudit } from "../../db/schema.js";
+import { newId } from "../../lib/api-lane/ids.js";
+import { AppError } from "../../lib/errors.js";
+import { resolveServiceDid } from "../../lib/ixo/did.js";
+import { oracleWebDid } from "../../lib/ixo/ucan.js";
+import { APPROVAL_TTL_MS, answerApproval, delegationRefusal, pendingApproval, } from "../../lib/oauth/approvals.js";
+import { approveWithStanding, grantDid, liveStanding, revokeStanding, setStanding, standingApprovalsAllowed, standingApprovalsOff, standingRefusal, } from "../../lib/oauth/standing.js";
+import { authHubDid } from "../../lib/oauth/token.js";
+import { facilitatorUrl } from "../../lib/payments/facilitator.js";
+import { validate } from "../../lib/validator.js";
+import { nameOf } from "./api/protocols.js";
+export const oauth = new Hono();
+/** upay as AuthHub sends it: a non-negative integer string. */
+const Upay = z.string().regex(/^(0|[1-9]\d{0,15})$/);
+const Limits = z.strictObject({ perClaimUpay: Upay, totalUpay: Upay, until: z.int() });
+const Answer = z.discriminatedUnion("decision", [
+    z.strictObject({
+        decision: z.literal("approve"),
+        did: z.string().min(1),
+        delegation: z.string().min(1).nullable(),
+        /** Auto-approve: keep `delegation` as the grant's standing authority with these limits. */
+        standing: Limits.optional(),
+    }),
+    z.strictObject({ decision: z.literal("decline"), did: z.string().min(1) }),
+]);
+const SetStanding = Limits.extend({ did: z.string().min(1), delegation: z.string().min(1) });
+const RevokeStanding = z.strictObject({ did: z.string().min(1) });
+/** A total below what this auto-approve has already spent (S3 review of #87, item 7). */
+const overSpent = () => AppError.validation("The total is below what this auto-approve has already spent.", {
+    reason: "limits_invalid",
+});
+const gone = () => AppError.notFound("This approval does not exist, or is no longer pending.");
+oauth.use("*", async (c, next) => {
+    const config = c.get("config");
+    if (!config.API_LANE)
+        throw AppError.notFound("No MCP server on this oracle");
+    if (c.get("principal").did !== authHubDid(config)) {
+        throw AppError.forbidden("Only IXO AuthHub may read or answer an approval.");
+    }
+    await next();
+});
+oauth.get("/approvals/:approvalId", async (c) => {
+    const row = await pendingApproval(await c.var.db(), c.req.param("approvalId"));
+    if (!row)
+        throw gone();
+    c.header("Cache-Control", "no-store");
+    return c.json({
+        did: row.did,
+        grantId: row.grantId,
+        clientName: row.clientName,
+        protocol: { did: row.protocolDid, name: await nameOf(c.env, row.protocolDid) },
+        price: { display: row.price, maxAmountUpay: row.maxAmountUpay },
+        billingMode: row.billingMode,
+        status: row.status,
+        expiresAt: Math.floor(row.expiresAt.getTime() / 1000),
+    });
+});
+oauth.post("/approvals/:approvalId", validate("json", Answer), async (c) => {
+    const db = await c.var.db();
+    const answer = c.req.valid("json");
+    const row = await pendingApproval(db, c.req.param("approvalId"));
+    if (!row || row.did !== answer.did)
+        throw gone();
+    if (answer.decision === "decline") {
+        if (!(await answerApproval(db, row.id, { status: "declined" })))
+            throw gone();
+        await auditAnswer(c.get("requestId"), db, row, "oauth.approval_declined");
+        return c.json({ status: "declined" });
+    }
+    const { standing } = answer;
+    // D8: limits on an oracle that takes no standing approvals refuse the whole answer — approving the
+    // claim alone would hand the user less than they asked for, silently. AuthHub re-asks without.
+    if (standing && !standingApprovalsAllowed())
+        throw standingApprovalsOff();
+    // Billing `none` charges nothing, so the claim keeps no payment authority — whatever was sent.
+    let delegation = null;
+    if (row.billingMode === "x402" || standing) {
+        if (!answer.delegation) {
+            throw AppError.validation("Approving this needs the payment delegation.");
+        }
+        const expect = await expectedDelegation(c);
+        const refusal = standing
+            ? await standingRefusal(answer.delegation, standing, {
+                ...expect,
+                did: row.did,
+                claimUpay: row.maxAmountUpay,
+            })
+            : await delegationRefusal(answer.delegation, row, expect);
+        if (refusal)
+            refuse(c, refusal, expect.facilitatorDid, row.id);
+        if (row.billingMode === "x402")
+            delegation = answer.delegation;
+    }
+    // One batch: this answer claims the approval's marker first; the flip and the standing write need
+    // it. Limits that would not cover what this auto-approve already spent claim nothing — the
+    // approval stays pending and the answer is refused (S3 review of #90, B).
+    const done = await approveWithStanding(db, { id: row.id, grantId: row.grantId, did: row.did, delegation }, standing && answer.delegation
+        ? {
+            limits: standing,
+            delegation: answer.delegation,
+            // This claim is paid from the same delegation, so it counts against the same total.
+            spentUpay: row.billingMode === "x402" ? Number(row.maxAmountUpay) : 0,
+        }
+        : null, new Date(Date.now() + APPROVAL_TTL_MS));
+    if (!done.approved) {
+        // Still pending after a refused claim: only the limits can have refused it — nothing changed.
+        if (standing && done.pending)
+            throw overSpent();
+        throw gone();
+    }
+    await auditAnswer(c.get("requestId"), db, row, "oauth.approval_approved", standing);
+    return c.json({ status: "approved" });
+});
+/**
+ * A grant's auto-approve, as AuthHub's `/connect/apps` and its grants API read, replace and end
+ * it (`oauth/standing/read | set | revoke`). Never the delegation. `did` must be the grant's
+ * user as this oracle has seen it (its standing, else an approval of it); anything else is 404.
+ */
+oauth.get("/standing/:grantId", async (c) => {
+    // D8: off, this oracle keeps no auto-approve to show — whatever is stored waits for the sweep.
+    if (!standingApprovalsAllowed()) {
+        throw AppError.notFound("This app has no auto-approve on this oracle.");
+    }
+    const row = await liveStanding(await c.var.db(), c.req.param("grantId"));
+    if (!row)
+        throw AppError.notFound("This app has no auto-approve on this oracle.");
+    c.header("Cache-Control", "no-store");
+    return c.json({
+        perClaimUpay: String(row.perClaimUpay),
+        totalUpay: String(row.totalUpay),
+        spentUpay: String(row.spentUpay),
+        until: Math.floor(row.until.getTime() / 1000),
+    });
+});
+oauth.put("/standing/:grantId", validate("json", SetStanding), async (c) => {
+    const db = await c.var.db();
+    const grantId = c.req.param("grantId");
+    const { did, delegation, ...limits } = c.req.valid("json");
+    if (!standingApprovalsAllowed())
+        throw standingApprovalsOff();
+    if ((await grantDid(db, grantId)) !== did) {
+        throw AppError.notFound("This oracle has seen no such app for this user.");
+    }
+    const expect = await expectedDelegation(c);
+    const refusal = await standingRefusal(delegation, limits, { ...expect, did });
+    if (refusal)
+        refuse(c, refusal, expect.facilitatorDid, grantId);
+    // What it has spent is never reset (the total is this auto-approve's total, across every
+    // delegation AuthHub signs for it): the new total must still cover it.
+    if (!(await setStanding(db, grantId, did, limits, delegation, 0)))
+        throw overSpent();
+    await auditStanding(c.get("requestId"), db, did, grantId, "oauth.auto_approve_set", limits);
+    return c.json({ status: "set" });
+});
+/**
+ * Accepted risk (as L2): a leaked `oauth/standing/revoke` invocation, replayable within its life,
+ * can only turn a user's auto-approve OFF — a denial of a convenience, never a payment — and it
+ * needs AuthHub's key to mint in the first place.
+ */
+oauth.delete("/standing/:grantId", validate("json", RevokeStanding), async (c) => {
+    const db = await c.var.db();
+    const grantId = c.req.param("grantId");
+    const { did } = c.req.valid("json");
+    if (!(await revokeStanding(db, grantId, did))) {
+        throw AppError.notFound("This oracle has seen no such app for this user.");
+    }
+    await auditStanding(c.get("requestId"), db, did, grantId, "oauth.auto_approve_revoked");
+    return c.json({ status: "revoked" });
+});
+/** What a delegation must name: this oracle, and the facilitator this oracle pays through. */
+async function expectedDelegation(c) {
+    const config = c.get("config");
+    return {
+        oracleDid: oracleWebDid(config),
+        facilitatorDid: await resolveServiceDid(c.get("trace"), c.env.CACHE_KV, facilitatorUrl(config)),
+    };
+}
+/** A refused delegation: logged (never its bytes) and answered `400` with its reason. */
+function refuse(c, refusal, facilitatorDid, target) {
+    const logger = c.get("logger");
+    if (refusal.reason === "facilitator_mismatch") {
+        // AuthHub and this oracle name different facilitators: a deploy to fix, never to guess.
+        logger.warn("oauth.approval.facilitator_mismatch", {
+            target,
+            delegationAudience: refusal.audience,
+            facilitatorDid,
+        });
+    }
+    else {
+        logger.warn("oauth.approval.delegation-refused", { target, reason: refusal.reason });
+    }
+    throw AppError.validation(`The payment delegation can't be accepted: ${refusal.message}.`, {
+        reason: refusal.reason,
+    });
+}
+/** The user's auto-approve changed on AuthHub: a grant-level audit row (no source). */
+async function auditStanding(requestId, db, did, grantId, action, limits) {
+    await db.insert(apiAudit).values({
+        auditId: newId("aud"),
+        sourceId: null,
+        actor: did,
+        actorKind: "oauth",
+        action,
+        target: grantId,
+        details: limits ? { ...limits } : null,
+        requestId,
+    });
+}
+/** The source's audit log: the user, through the app, answered (never the delegation). */
+async function auditAnswer(requestId, db, row, action, standing) {
+    await db.insert(apiAudit).values({
+        auditId: newId("aud"),
+        sourceId: row.sourceId,
+        actor: row.did,
+        actorKind: "oauth",
+        clientId: row.clientId,
+        clientName: row.clientName,
+        action,
+        target: row.id,
+        details: {
+            grantId: row.grantId,
+            price: row.price,
+            protocolDid: row.protocolDid,
+            ...(standing ? { autoApprove: standing } : {}),
+        },
+        requestId,
+    });
+}
+//# sourceMappingURL=oauth.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * A chain collection's reviewers (company authority D2; ownership review F1, F12): the people the
+ * COMPANY names to answer its claims' review tasks. A current controller of the collection's entity
+ * signs each one a `claims/review` delegation on `ixo:oracle/<our did:web>/collection/<id>` (at most
+ * 30 days) and files it here; the reviewer sends it back with every answer (`POST /v1/reviews/
+ * :claimId`), where the gate in lib/review/reviewer-grant.ts holds it to the chain again. Filing
+ * runs the same checks up front, so an owner hears "that person evaluates this collection" now,
+ * not at their reviewer's first answer.
+ *
+ *   POST /v1/collections/:collectionId/reviewers   { delegation }  a controller files a grant they signed
+ *   GET  /v1/collections/:collectionId/reviewers   a controller: every grant; a reviewer: their own
+ *                                                  (with the CAR — the Portal sends it with an answer)
+ *   POST /v1/collections/:collectionId/reviewers/:delegationCid/revoke   a controller; kicks the
+ *                                                  reviewer from the review room
+ *
+ * Controllers are read live (Blocksync, uncached): a person removed from the entity stops managing
+ * its reviewers at once. Each route takes its own action, strict (middleware/capability.ts).
+ */
+import { Hono } from "hono";
+import type { AppEnv } from "../../context.js";
+export declare const reviewers: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=reviewers.d.ts.map

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

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

package/dist/routes/v1/reviewers.js

@@ -0,0 +1,165 @@
+/**
+ * A chain collection's reviewers (company authority D2; ownership review F1, F12): the people the
+ * COMPANY names to answer its claims' review tasks. A current controller of the collection's entity
+ * signs each one a `claims/review` delegation on `ixo:oracle/<our did:web>/collection/<id>` (at most
+ * 30 days) and files it here; the reviewer sends it back with every answer (`POST /v1/reviews/
+ * :claimId`), where the gate in lib/review/reviewer-grant.ts holds it to the chain again. Filing
+ * runs the same checks up front, so an owner hears "that person evaluates this collection" now,
+ * not at their reviewer's first answer.
+ *
+ *   POST /v1/collections/:collectionId/reviewers   { delegation }  a controller files a grant they signed
+ *   GET  /v1/collections/:collectionId/reviewers   a controller: every grant; a reviewer: their own
+ *                                                  (with the CAR — the Portal sends it with an answer)
+ *   POST /v1/collections/:collectionId/reviewers/:delegationCid/revoke   a controller; kicks the
+ *                                                  reviewer from the review room
+ *
+ * Controllers are read live (Blocksync, uncached): a person removed from the entity stops managing
+ * its reviewers at once. Each route takes its own action, strict (middleware/capability.ts).
+ */
+import { and, desc, eq, isNull } from "drizzle-orm";
+import { Hono } from "hono";
+import { z } from "zod";
+import { collectionReviewers } from "../../db/schema.js";
+import { AppError } from "../../lib/errors.js";
+import { getCollection, getEntityControllers } from "../../lib/ixo/blocksync/index.js";
+import { syncCollectionReviewRoom } from "../../lib/matrix/deliver.js";
+import { assertReviewerAuthority, parseReviewerGrant } from "../../lib/review/reviewer-grant.js";
+import { validate } from "../../lib/validator.js";
+import { watchedOr404 } from "./shared.js";
+export const reviewers = new Hono();
+const CollectionParam = z.object({
+    collectionId: z
+        .string()
+        .min(1)
+        .max(256)
+        .regex(/^[A-Za-z0-9._:-]+$/),
+});
+const RevokeParam = CollectionParam.extend({
+    delegationCid: z.string().regex(/^[a-z0-9]{8,128}$/),
+});
+const GrantBody = z.object({ delegation: z.string().min(1).max(16384) });
+/** Is the caller a current controller of the collection's entity? Watched first (404). */
+async function isController(c, collectionId) {
+    await watchedOr404(c, collectionId);
+    const deps = { config: c.get("config"), trace: c.get("trace") };
+    const collection = await getCollection(deps, collectionId);
+    if (!collection?.entity)
+        return false;
+    return (await getEntityControllers(deps, collection.entity)).includes(c.get("principal").did);
+}
+const controllerOnly = (collectionId) => AppError.forbidden(`Only a current controller of collection ${collectionId}'s entity may manage its reviewers`);
+function reviewerBody(row) {
+    return {
+        collectionId: row.collectionId,
+        memberDid: row.memberDid,
+        rootDid: row.rootDid,
+        delegationCid: row.delegationCid,
+        delegation: row.delegation,
+        expiresAt: row.expiresAt.toISOString(),
+        revokedAt: row.revokedAt?.toISOString() ?? null,
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+reviewers.post("/:collectionId/reviewers", validate("param", CollectionParam), validate("json", GrantBody), async (c) => {
+    const { collectionId } = c.req.valid("param");
+    const { delegation } = c.req.valid("json");
+    const config = c.get("config");
+    const { did } = c.get("principal");
+    const watched = await watchedOr404(c, collectionId);
+    const grant = await parseReviewerGrant(config, delegation, collectionId);
+    // The owner is in the review room by right (`ensureReviewRoom`), and the room sync never kicks
+    // them; a grant to them would only be a row whose revoke could not take that seat away.
+    if (grant.memberDid === watched.ownerDid) {
+        throw new AppError("This reviewer grant can't be used: the owner already sees its reviews.", {
+            code: "REVIEWER_GRANT_INVALID",
+            details: { reason: "audience" },
+        });
+    }
+    // The caller files only what they signed themselves: an uploaded grant is a controller's own
+    // word, never one they found.
+    if (grant.rootDid !== did) {
+        throw new AppError("File a reviewer grant you signed yourself", {
+            code: "REVIEWER_NOT_AUTHORIZED",
+            details: { reason: "identity" },
+        });
+    }
+    await assertReviewerAuthority({ config, trace: c.get("trace") }, grant, collectionId);
+    const db = await c.var.db();
+    // The CID is the identity (schema.ts): a second upload of the same grant is the same row —
+    // and a revoked one stays revoked; a new grant is a new delegation.
+    await db
+        .insert(collectionReviewers)
+        .values({
+        collectionId,
+        memberDid: grant.memberDid,
+        rootDid: grant.rootDid,
+        delegation,
+        delegationCid: grant.cid,
+        expiresAt: new Date(grant.exp * 1000),
+    })
+        .onConflictDoNothing();
+    const row = await db.query.collectionReviewers.findFirst({
+        where: and(eq(collectionReviewers.collectionId, collectionId), eq(collectionReviewers.delegationCid, grant.cid)),
+    });
+    if (!row)
+        throw AppError.internal("Reviewer grant insert returned no row");
+    if (row.revokedAt) {
+        throw AppError.conflict("This grant was revoked — sign a new one to grant review again");
+    }
+    c.get("logger").info("reviewers.granted", {
+        collectionId,
+        memberDid: grant.memberDid,
+        rootDid: grant.rootDid,
+        delegationCid: grant.cid,
+    });
+    return c.json(reviewerBody(row), 201);
+});
+reviewers.get("/:collectionId/reviewers", validate("param", CollectionParam), async (c) => {
+    const { collectionId } = c.req.valid("param");
+    const { did } = c.get("principal");
+    const controller = await isController(c, collectionId);
+    const db = await c.var.db();
+    const rows = await db
+        .select()
+        .from(collectionReviewers)
+        .where(controller
+        ? eq(collectionReviewers.collectionId, collectionId)
+        : and(eq(collectionReviewers.collectionId, collectionId), eq(collectionReviewers.memberDid, did)))
+        .orderBy(desc(collectionReviewers.createdAt));
+    // Neither a controller nor ever granted: nothing here is theirs to see.
+    if (!controller && rows.length === 0)
+        throw controllerOnly(collectionId);
+    return c.json({ reviewers: rows.map(reviewerBody) });
+});
+reviewers.post("/:collectionId/reviewers/:delegationCid/revoke", validate("param", RevokeParam), async (c) => {
+    const { collectionId, delegationCid } = c.req.valid("param");
+    if (!(await isController(c, collectionId)))
+        throw controllerOnly(collectionId);
+    const db = await c.var.db();
+    const key = and(eq(collectionReviewers.collectionId, collectionId), eq(collectionReviewers.delegationCid, delegationCid));
+    // Stamped once: a second revoke keeps the first time.
+    await db
+        .update(collectionReviewers)
+        .set({ revokedAt: new Date() })
+        .where(and(key, isNull(collectionReviewers.revokedAt)));
+    const row = await db.query.collectionReviewers.findFirst({ where: key });
+    if (!row)
+        throw AppError.notFound(`No reviewer grant ${delegationCid} on ${collectionId}`);
+    c.get("logger").info("reviewers.revoked", {
+        collectionId,
+        memberDid: row.memberDid,
+        delegationCid,
+    });
+    // Out of the review room now, not at the hourly pass. Fail-soft: a pending answer is refused
+    // by the fold's own gate whatever Matrix does.
+    await syncCollectionReviewRoom({
+        config: c.get("config"),
+        logger: c.get("logger"),
+        trace: c.get("trace"),
+        metrics: c.get("metrics"),
+        cache: c.env.CACHE_KV,
+        runDb: async (fn) => fn(db),
+    }, collectionId).catch((err) => c.get("logger").warn("matrix.review_kick.failed", { collectionId, reason: String(err) }));
+    return c.json(reviewerBody(row));
+});
+//# sourceMappingURL=reviewers.js.map

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

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

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

@@ -0,0 +1,38 @@
+/**
+ * The review lane (README "How a claim flows" step 6). A `pending_review` decision names the ReviewTasks a human
+ * must answer (`decision.pendingTasks`); the answers land here and the `ReviewComplete` workflow
+ * folds them into the SAME decision through the engine (never a second evaluation). UCAN-guarded
+ * like the rest of `/v1/*`; on top of that, only a reviewer the COMPANY named may answer (company
+ * authority D2; ownership review F1, F12): the answer carries `reviewerGrant`, the `claims/review`
+ * delegation a current controller of the collection's entity gave the reviewer, and it must pass
+ * the gate (lib/review/reviewer-grant.ts) — filed and unrevoked here, rooted at a live controller,
+ * no oracle and no evaluator in it. An evaluate grant alone never answers: that power can already
+ * sign `MsgEvaluateClaim` and move the collection's payments. A rubric's `assignTo` is routing, not
+ * access. The fold re-runs the gate and forwards the grant verbatim; the engine checks its root.
+ *
+ *   POST /v1/reviews/:claimId   { answers: { taskId → boolean | string }, attestation, reviewerGrant }
+ *                               → 202 + the review row
+ *   GET  /v1/reviews/:claimId   the pending tasks, the stored answers, and why a fold failed — the
+ *                               read gate's audience plus the collection's live reviewers
+ *
+ * Answers must cover EXACTLY the pending tasks (all-or-nothing); their VALUES are the engine's to
+ * check against the rubric's ReviewTasks at fold time. Answered-once until folded: a re-POST
+ * before the fold replaces the answers and re-spawns (the crash-window / "try again" recovery —
+ * also how a `foldError` is cleared); after the fold it conflicts.
+ *
+ * `attestation` is the reviewer's own signed statement over those answers (design §B.3) and is
+ * REQUIRED on every review (owner ruling, 2026-09-14): there is no unsigned path and no flag — a
+ * review answer IS a signed statement, or it is refused `ATTESTATION_REQUIRED` before any lookup or
+ * write. This route is the only place that signature CAN be bound to a person: we are the only
+ * party that sees the reviewer's UCAN invocation, so `issuer` is checked against `principal.did`
+ * here and nowhere else. Every check passes or NOTHING is written — which is also why a stored
+ * answer stays signed: the only thing that can replace one is another signature.
+ *
+ * DEPLOY ORDER (docs/ENGINE-CONTRACT.md): the portal signs FIRST — an older kit's body schema
+ * ignores the extra field harmlessly — then engine and kit go out together, because the engine's
+ * fold schema is strict and this kit now forwards `attestation` on every fold.
+ */
+import { Hono } from "hono";
+import type { AppEnv } from "../../context.js";
+export declare const reviews: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=reviews.d.ts.map

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

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