@rubric-protocol/decision-verify 1.0.1

package/dist/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,IAAI,EAAwB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,IAAI,EAAyD,MAAM,WAAW,CAAC;AAIxF,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAU/D,iEAAiE;AACjE,SAAS,cAAc,CAAC,GAAkB,EAAE,IAAqB;IAC/D,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC;IAE9D,IAAI,IAAI,KAAK,OAAO,IAAI,OAAO,EAAE,CAAC;QAChC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,GAAG,GAAG,UAAU;QACpB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC;QACrC,CAAC,CAAC,YAAY;YACZ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,YAAY,CAAC;YACzC,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,CAAC,UAAU,IAAI,CAAC,YAAY,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,wCAAwC,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC,CAAC;IAE5D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,2BAA2B,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IAElG,OAAO,IAAI,CAAC,GAAG,EAAE,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,yBAAyB,CAAC,IAAqB;IAC7D,MAAM,OAAO,GAAY,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;AACnF,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,3 @@
+import type { SignatureVerifier, VerifiableBundle, VerificationResult } from "./ports.js";
+export declare function assembleVerification(bundle: VerifiableBundle, verifySignature: SignatureVerifier): VerificationResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAgB,MAAM,YAAY,CAAC;AAmBxG,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,eAAe,EAAE,iBAAiB,GACjC,kBAAkB,CA2BpB"}

package/dist/verify.js

@@ -0,0 +1,55 @@
+/**
+ * Assemble a decision-verify result from a stored bundle (tasks/P4.md).
+ *
+ * Scope (be honest about what this proves): this checks the bundle's INTERNAL
+ * consistency — the decision still hashes to its committed decisionHash, the
+ * recomputed leaf is the one the proof carries, the proof folds to the root the
+ * bundle claims, and the (caller-supplied) signature verifies. It does NOT
+ * contact HCS to confirm the root was actually anchored, nor does it establish
+ * that the signing key is trusted. `consistencyVerified` reflects only the
+ * former; on-chain anchoring is the job of the (out-of-scope) attestation service.
+ */
+import { DAR_VERSION, decisionHashOf, leafHash } from "@rubric-protocol/attest-decision";
+import { verifyMerkleProof } from "./merkle.js";
+const LEAF_TYPES = new Set(["decision", "schema-change", "checkpoint"]);
+const KNOWN = parseVersion(DAR_VERSION); // { major: 0, minor: 1 }
+function parseVersion(v) {
+    const m = /^DAR\/(\d+)\.(\d+)$/.exec(v);
+    return m ? { major: Number(m[1]), minor: Number(m[2]) } : null;
+}
+/** Spec §5.1 version gate: reject unknown major / bad leafType; needs-upgrade for a newer minor. */
+function versionStatus(v, leafType) {
+    const parsed = parseVersion(v);
+    if (!parsed || parsed.major !== KNOWN.major)
+        return "rejected"; // unknown major/format
+    if (!LEAF_TYPES.has(leafType))
+        return "rejected";
+    if (parsed.minor > KNOWN.minor)
+        return "needs-upgrade"; // MUST NOT strip-and-rehash a newer minor
+    return "ok";
+}
+export function assembleVerification(bundle, verifySignature) {
+    const { dar, merkleProof, anchorRef } = bundle;
+    const status = versionStatus(dar.v, dar.leafType);
+    const sig = verifySignature(bundle.signature, anchorRef.root);
+    const base = {
+        decisionId: dar.decisionId,
+        dar,
+        merkleProof,
+        anchorRef,
+        signature: { verified: sig.verified, keyRef: sig.keyRef },
+    };
+    // Do not claim (or compute) leaf verification for a version we can't fully
+    // understand — spec §5.1 forbids strip-and-rehash of a newer minor.
+    if (status !== "ok") {
+        return { ...base, drift: false, status, consistencyVerified: false };
+    }
+    const decisionHashOk = decisionHashOf(dar.schemaHash, dar.inputHash, dar.outputHash) === dar.decisionHash;
+    const leaf = leafHash(dar);
+    const leafMatches = leaf === merkleProof.leaf;
+    const proofFolds = verifyMerkleProof(leaf, merkleProof.steps, merkleProof.root);
+    const rootMatchesAnchor = merkleProof.root === anchorRef.root;
+    const drift = !decisionHashOk || !leafMatches || !proofFolds || !rootMatchesAnchor;
+    return { ...base, drift, status, consistencyVerified: !drift && sig.verified };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

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

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rubric-protocol/decision-verify",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Rubric decision-verify route: x402 gate, Merkle/anchor/signature verification, chain-check",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xsims/rubric-attest.git",
+    "directory": "packages/verify"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@rubric-protocol/attest-decision": "^1.0.1",
+    "@rubric-protocol/attest-index": "^1.0.1"
+  }
+}

package/src/bazaar.ts

@@ -0,0 +1,88 @@
+/**
+ * x402 discovery + settlement (tasks/P4.md). An unpaid request is answered with
+ * `svcSend402`: HTTP 402 carrying a "bazaar blob" — the discoverable payment
+ * requirements — computed with zero downstream (index/store) work. A settled
+ * (paid) response carries `extensions.bazaar`.
+ */
+import { json, type VerifyResponse } from "./http.js";
+
+export interface BazaarConfig {
+  resource: string; // e.g. "/v1/x402/decision-verify"
+  network: string; // e.g. "hedera-testnet"
+  asset: string; // token/asset identifier
+  maxAmountRequired: string; // price, atomic units, as a string
+  payTo: string; // recipient address
+  description?: string;
+  discoveryUrl?: string; // bazaar listing URL
+  category?: string;
+}
+
+export interface X402Accept {
+  scheme: "exact";
+  network: string;
+  maxAmountRequired: string;
+  resource: string;
+  description: string;
+  payTo: string;
+  asset: string;
+  mimeType: "application/json";
+}
+
+export interface BazaarBlob {
+  x402Version: 1;
+  accepts: X402Accept[];
+  bazaar: { discoverable: true; resource: string; category: string; url?: string };
+}
+
+/** The discoverable 402 challenge body. */
+export function buildBazaarBlob(cfg: BazaarConfig): BazaarBlob {
+  const accept: X402Accept = {
+    scheme: "exact",
+    network: cfg.network,
+    maxAmountRequired: cfg.maxAmountRequired,
+    resource: cfg.resource,
+    description: cfg.description ?? "Rubric decision-verify",
+    payTo: cfg.payTo,
+    asset: cfg.asset,
+    mimeType: "application/json",
+  };
+  const bazaar: BazaarBlob["bazaar"] = {
+    discoverable: true,
+    resource: cfg.resource,
+    category: cfg.category ?? "attestation.verify",
+  };
+  if (cfg.discoveryUrl !== undefined) bazaar.url = cfg.discoveryUrl;
+  return { x402Version: 1, accepts: [accept], bazaar };
+}
+
+/** Instant 402 (no downstream work): the discovery response. */
+export function svcSend402(cfg: BazaarConfig): VerifyResponse {
+  return json(402, buildBazaarBlob(cfg), { "www-authenticate": `x402 resource="${cfg.resource}"` });
+}
+
+export interface SettlementBlob {
+  settled: true;
+  resource: string;
+  network: string;
+  asset: string;
+  amount: string;
+  payer?: string;
+  settlementId?: string;
+}
+
+/** The `extensions.bazaar` payload attached to a settled response. */
+export function settlementBlob(
+  cfg: BazaarConfig,
+  payment: { payer?: string; settlementId?: string },
+): SettlementBlob {
+  const blob: SettlementBlob = {
+    settled: true,
+    resource: cfg.resource,
+    network: cfg.network,
+    asset: cfg.asset,
+    amount: cfg.maxAmountRequired,
+  };
+  if (payment.payer !== undefined) blob.payer = payment.payer;
+  if (payment.settlementId !== undefined) blob.settlementId = payment.settlementId;
+  return blob;
+}

package/src/chain.ts

@@ -0,0 +1,56 @@
+/**
+ * Chain-check: build a continuity report for an agent's per-agent `prev` chain
+ * (tasks/P4.md). Forks (a decision with >1 child) are reported as branches, and
+ * are explicitly NOT treated as tampering — a legitimately branched history is
+ * still authentic. Gaps (a `prev` pointing at an absent decision) are surfaced
+ * too. Actual tampering is detected per-record via the drift flag (see verify).
+ */
+import type { ContinuityReport, IndexRow } from "./ports.js";
+
+const byId = (rows: IndexRow[]) => new Map(rows.map((r) => [r.decisionId, r]));
+
+export function chainCheck(agentId: string, rows: IndexRow[]): ContinuityReport {
+  const present = byId(rows);
+  const childrenOf = new Map<string, string[]>();
+  const referenced = new Set<string>();
+
+  for (const r of rows) {
+    if (r.prev !== null) {
+      referenced.add(r.prev);
+      (childrenOf.get(r.prev) ?? childrenOf.set(r.prev, []).get(r.prev)!).push(r.decisionId);
+    }
+  }
+
+  const sorted = (xs: string[]) => xs.slice().sort();
+
+  const genesis = sorted(rows.filter((r) => r.prev === null).map((r) => r.decisionId));
+  const heads = sorted(rows.filter((r) => !referenced.has(r.decisionId)).map((r) => r.decisionId));
+
+  const branches = [...childrenOf.entries()]
+    .filter(([, kids]) => kids.length > 1)
+    .map(([parent, kids]) => ({ parent, children: sorted(kids) }))
+    .sort((a, b) => (a.parent < b.parent ? -1 : 1));
+
+  const gaps = rows
+    .filter((r) => r.prev !== null && !present.has(r.prev))
+    .map((r) => ({ decisionId: r.decisionId, missingPrev: r.prev! }))
+    .sort((a, b) => (a.decisionId < b.decisionId ? -1 : 1));
+
+  const linear =
+    rows.length > 0 &&
+    genesis.length === 1 &&
+    heads.length === 1 &&
+    branches.length === 0 &&
+    gaps.length === 0;
+
+  return {
+    agentId,
+    count: rows.length,
+    genesis,
+    heads,
+    branches,
+    gaps,
+    linear,
+    tampering: false,
+  };
+}

package/src/gate.ts

@@ -0,0 +1,55 @@
+/**
+ * x402 payment gate (tasks/P4.md). Fronts a handler: an unpaid request is
+ * answered instantly with `svcSend402` (the bazaar discovery blob) — the wrapped
+ * handler, which does the index/store work, is NEVER invoked until payment is
+ * present, so discovery does zero DB work. A settled response carries
+ * `extensions.bazaar` (and an `x-payment-response` header).
+ */
+import { svcSend402, settlementBlob, type BazaarConfig } from "./bazaar.js";
+import type { Handler, VerifyRequest, VerifyResponse } from "./http.js";
+
+export const X402_PAYMENT_HEADER = "x-payment";
+
+export interface PaymentResult {
+  paid: boolean;
+  payer?: string;
+  settlementId?: string;
+}
+
+/** Verifies a payment header. Injected + mockable; MUST NOT do DB work. */
+export type PaymentVerifier = (
+  paymentHeader: string | undefined,
+  req: VerifyRequest,
+) => PaymentResult;
+
+export interface GateOptions {
+  bazaar: BazaarConfig;
+  verifyPayment: PaymentVerifier;
+  paymentHeader?: string;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export function gate(handler: Handler, opts: GateOptions): Handler {
+  const headerName = (opts.paymentHeader ?? X402_PAYMENT_HEADER).toLowerCase();
+  return async (req: VerifyRequest): Promise<VerifyResponse> => {
+    const payment = opts.verifyPayment(req.headers[headerName], req);
+    if (!payment.paid) {
+      // Discovery: instant 402 with the bazaar blob, before any downstream work.
+      return svcSend402(opts.bazaar);
+    }
+
+    const res = await handler(req);
+
+    // Settle path: attach extensions.bazaar to a successful JSON body.
+    if (res.status >= 200 && res.status < 300 && isObject(res.body)) {
+      const settle = settlementBlob(opts.bazaar, payment);
+      const existingExt = isObject(res.body.extensions) ? res.body.extensions : {};
+      res.body = { ...res.body, extensions: { ...existingExt, bazaar: settle } };
+      res.headers["x-payment-response"] = Buffer.from(JSON.stringify(settle), "utf8").toString("base64");
+    }
+    return res;
+  };
+}

package/src/http.ts

@@ -0,0 +1,53 @@
+/**
+ * Framework-agnostic request/response shapes for the route, plus a thin Node
+ * `http` adapter. The route is a pure `Handler` so tests drive it directly; the
+ * adapter is for running it as a real server.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export interface VerifyRequest {
+  method: string;
+  path: string;
+  query: Record<string, string | undefined>;
+  headers: Record<string, string | undefined>;
+}
+
+export interface VerifyResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+export type Handler = (req: VerifyRequest) => VerifyResponse | Promise<VerifyResponse>;
+
+/** Build a JSON response. */
+export function json(status: number, body: unknown, headers: Record<string, string> = {}): VerifyResponse {
+  return { status, headers: { "content-type": "application/json", ...headers }, body };
+}
+
+function firstHeader(v: string | string[] | undefined): string | undefined {
+  return Array.isArray(v) ? v[0] : v;
+}
+
+/** Adapt a Handler to a Node `http` request listener. */
+export function toNodeListener(handler: Handler) {
+  return (req: IncomingMessage, res: ServerResponse): void => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const query: Record<string, string | undefined> = {};
+    for (const [k, val] of url.searchParams) query[k] = val;
+    const headers: Record<string, string | undefined> = {};
+    for (const [k, val] of Object.entries(req.headers)) headers[k.toLowerCase()] = firstHeader(val);
+
+    const request: VerifyRequest = { method: req.method ?? "GET", path: url.pathname, query, headers };
+
+    Promise.resolve(handler(request))
+      .then((r) => {
+        res.writeHead(r.status, r.headers);
+        res.end(typeof r.body === "string" ? r.body : JSON.stringify(r.body));
+      })
+      .catch(() => {
+        res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "internal error" }));
+      });
+  };
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @rubric-protocol/decision-verify — the x402-gated decision-verify route (tasks/P4.md).
+ *
+ * A framework-agnostic Handler that, once payment is present, verifies a DAR
+ * against its Merkle inclusion proof, HCS anchor ref, and service signature
+ * (surfacing a drift flag), or produces a chain-check continuity report.
+ */
+export { createDecisionVerifyRoute, DECISION_VERIFY_PATH, type VerifyRouteDeps } from "./route.js";
+export { gate, X402_PAYMENT_HEADER, type GateOptions, type PaymentVerifier, type PaymentResult } from "./gate.js";
+export {
+  svcSend402,
+  buildBazaarBlob,
+  settlementBlob,
+  type BazaarConfig,
+  type BazaarBlob,
+  type SettlementBlob,
+} from "./bazaar.js";
+export { assembleVerification } from "./verify.js";
+export { chainCheck } from "./chain.js";
+export { verifyMerkleProof, buildMerkleTree, nodeHash } from "./merkle.js";
+export { json, toNodeListener, type VerifyRequest, type VerifyResponse, type Handler } from "./http.js";
+export type {
+  IndexPort,
+  StorePort,
+  SignatureVerifier,
+  SignatureResult,
+  VerifiableBundle,
+  VerificationResult,
+  VerifyStatus,
+  MerkleProof,
+  MerkleProofStep,
+  AnchorRef,
+  BatchSignature,
+  ContinuityReport,
+  ChainBranch,
+  ChainGap,
+  IndexRow,
+} from "./ports.js";

package/src/merkle.ts

@@ -0,0 +1,63 @@
+/**
+ * Merkle inclusion proofs over SHA3-256 (tasks/P4.md; interior-node hashing is
+ * defined by the attestation service per spec/dar-0.1.md §4.3). Leaves are DAR
+ * leaf hashes; interior nodes are domain-separated to prevent second-preimage
+ * ambiguity between leaves and internal nodes.
+ */
+import { sha3_256, type HashString } from "@rubric-protocol/attest-decision";
+import type { MerkleProofStep } from "./ports.js";
+
+const NODE_DOMAIN = "rubric-merkle-node/1\n";
+
+/** Hash an interior node from its ordered children. */
+export function nodeHash(left: HashString, right: HashString): HashString {
+  return sha3_256(`${NODE_DOMAIN}${left}\n${right}`);
+}
+
+/** Fold a leaf up through its proof steps and check it reproduces `root`. */
+export function verifyMerkleProof(leaf: HashString, steps: MerkleProofStep[], root: HashString): boolean {
+  let acc = leaf;
+  for (const step of steps) {
+    acc = step.position === "left" ? nodeHash(step.sibling, acc) : nodeHash(acc, step.sibling);
+  }
+  return acc === root;
+}
+
+/**
+ * Build a Merkle root and an inclusion proof for every leaf. Odd levels promote
+ * the last node by pairing it with itself. Utility for constructing anchored
+ * bundles (and test fixtures); the route only needs verifyMerkleProof.
+ */
+export function buildMerkleTree(leaves: HashString[]): { root: HashString; proofs: MerkleProofStep[][] } {
+  if (leaves.length === 0) throw new Error("merkle: cannot build a tree over zero leaves");
+
+  const proofs: MerkleProofStep[][] = leaves.map(() => []);
+  // indexAtLevel[i] tracks where original leaf i currently sits in `level`.
+  let level = leaves.slice();
+  let positions = leaves.map((_, i) => i);
+
+  while (level.length > 1) {
+    const next: HashString[] = [];
+    const nextPositions = positions.map(() => 0);
+    for (let i = 0; i < level.length; i += 2) {
+      const left = level[i]!;
+      const right = i + 1 < level.length ? level[i + 1]! : level[i]!; // promote odd tail
+      const parent = nodeHash(left, right);
+      const parentIdx = next.length;
+      next.push(parent);
+      for (let li = 0; li < positions.length; li++) {
+        if (positions[li] === i) {
+          proofs[li]!.push({ sibling: right, position: "right" });
+          nextPositions[li] = parentIdx;
+        } else if (positions[li] === i + 1) {
+          proofs[li]!.push({ sibling: left, position: "left" });
+          nextPositions[li] = parentIdx;
+        }
+      }
+    }
+    level = next;
+    positions = nextPositions;
+  }
+
+  return { root: level[0]!, proofs };
+}

package/src/ports.ts

@@ -0,0 +1,123 @@
+/**
+ * Ports and wire types for the decision-verify route (tasks/P4.md).
+ *
+ * The route depends only on these interfaces, so tests inject in-memory mocks
+ * for the index and store ("route tests green on mocked index+store").
+ */
+import type { DarCore, HashString } from "@rubric-protocol/attest-decision";
+import type { IndexRow } from "@rubric-protocol/attest-index";
+
+export type { IndexRow };
+
+/** A Merkle inclusion proof step: a sibling hash and which side it sits on. */
+export interface MerkleProofStep {
+  sibling: HashString;
+  position: "left" | "right";
+}
+
+/** Inclusion proof from a leaf up to a published root. */
+export interface MerkleProof {
+  leaf: HashString;
+  steps: MerkleProofStep[];
+  root: HashString;
+}
+
+/** Reference to the on-chain (HCS) anchor that committed a Merkle root. */
+export interface AnchorRef {
+  network: string;
+  topicId: string;
+  sequenceNumber: number;
+  root: HashString;
+  consensusTimestamp?: string;
+}
+
+/** Service signature over an anchored root. */
+export interface BatchSignature {
+  alg: string;
+  keyRef: string;
+  signature: string;
+  over: HashString; // the root the signature covers
+}
+
+/** A stored bundle: the DAR core plus the attestation envelope (spec §6). */
+export interface VerifiableBundle {
+  attestationId: string;
+  dar: DarCore;
+  merkleProof: MerkleProof;
+  anchorRef: AnchorRef;
+  signature: BatchSignature;
+}
+
+/** Index port — row lookups by decisionId/decisionHash and per-agent chains. */
+export interface IndexPort {
+  byDecisionId(decisionId: string): IndexRow | undefined;
+  byDecisionHash(decisionHash: string): IndexRow | undefined;
+  agentChain(agentId: string): IndexRow[];
+}
+
+/** Store port — load a full bundle by its path. */
+export interface StorePort {
+  get(bundlePath: string): VerifiableBundle | undefined;
+}
+
+export interface SignatureResult {
+  verified: boolean;
+  keyRef: string;
+}
+
+/** Verifies a service signature over an anchored root. Injected (mockable). */
+export type SignatureVerifier = (signature: BatchSignature, root: HashString) => SignatureResult;
+
+/** Version gate outcome (spec §5.1). */
+export type VerifyStatus = "ok" | "needs-upgrade" | "rejected";
+
+/** The decision-verify result body. */
+export interface VerificationResult {
+  decisionId: string;
+  dar: DarCore;
+  merkleProof: MerkleProof;
+  anchorRef: AnchorRef;
+  signature: SignatureResult;
+  /** True when the record no longer matches the proof/root carried in its bundle (tampering). */
+  drift: boolean;
+  /**
+   * Version gate per spec §5.1: `rejected` (unknown DAR major or bad leafType),
+   * `needs-upgrade` (known major but a newer minor this verifier can't fully
+   * check), or `ok` (this verifier fully understands the record's version).
+   */
+  status: VerifyStatus;
+  /**
+   * INTERNAL CONSISTENCY ONLY. True iff status is `ok`, there is no drift, and
+   * the supplied signature verified. This attests that the bundle is internally
+   * self-consistent — it is NOT proof that the Merkle root was anchored on HCS,
+   * nor that the signing key is trusted. Those require the (out-of-scope)
+   * attestation service; this route does not contact any ledger.
+   */
+  consistencyVerified: boolean;
+}
+
+/** A fork point: a decision with more than one child in the chain. */
+export interface ChainBranch {
+  parent: string;
+  children: string[];
+}
+
+/** A break where a record's `prev` points at a decision absent from the index. */
+export interface ChainGap {
+  decisionId: string;
+  missingPrev: string;
+}
+
+/** Continuity report for an agent's chain (tasks/P4.md). */
+export interface ContinuityReport {
+  agentId: string;
+  count: number;
+  genesis: string[]; // decisions with prev === null
+  heads: string[]; // tips: not referenced as anyone's prev
+  branches: ChainBranch[]; // forks, represented as branches (NOT tampering)
+  gaps: ChainGap[];
+  /** True iff a single unbroken linear chain (one genesis, one head, no forks/gaps). */
+  linear: boolean;
+  /** Forks and gaps are structural, not tampering — always false here. */
+  tampering: false;
+}

package/src/route.ts

@@ -0,0 +1,55 @@
+/**
+ * The gate()-fronted /v1/x402/decision-verify route (tasks/P4.md).
+ *
+ * Query:
+ *   ?decisionId=... | ?decisionHash=...   -> single-record verification
+ *   ?agentId=...    (or ?mode=chain)      -> chain-check continuity report
+ */
+import { assembleVerification } from "./verify.js";
+import { chainCheck } from "./chain.js";
+import { gate, type PaymentVerifier } from "./gate.js";
+import { json, type Handler, type VerifyRequest, type VerifyResponse } from "./http.js";
+import type { BazaarConfig } from "./bazaar.js";
+import type { IndexPort, SignatureVerifier, StorePort } from "./ports.js";
+
+export const DECISION_VERIFY_PATH = "/v1/x402/decision-verify";
+
+export interface VerifyRouteDeps {
+  index: IndexPort;
+  store: StorePort;
+  verifySignature: SignatureVerifier;
+  bazaar: BazaarConfig;
+  verifyPayment: PaymentVerifier;
+}
+
+/** The paid handler — this is where index/store work happens. */
+function decisionVerify(req: VerifyRequest, deps: VerifyRouteDeps): VerifyResponse {
+  const { decisionId, decisionHash, agentId, mode } = req.query;
+
+  if (mode === "chain" || agentId) {
+    if (!agentId) return json(400, { error: "agentId is required for chain-check" });
+    return json(200, chainCheck(agentId, deps.index.agentChain(agentId)));
+  }
+
+  const row = decisionId
+    ? deps.index.byDecisionId(decisionId)
+    : decisionHash
+      ? deps.index.byDecisionHash(decisionHash)
+      : undefined;
+
+  if (!decisionId && !decisionHash) {
+    return json(400, { error: "decisionId or decisionHash is required" });
+  }
+  if (!row) return json(404, { error: "decision not found" });
+
+  const bundle = deps.store.get(row.bundlePath);
+  if (!bundle) return json(502, { error: "bundle missing from store", bundlePath: row.bundlePath });
+
+  return json(200, assembleVerification(bundle, deps.verifySignature));
+}
+
+/** Build the gate()-fronted route handler. */
+export function createDecisionVerifyRoute(deps: VerifyRouteDeps): Handler {
+  const handler: Handler = (req) => decisionVerify(req, deps);
+  return gate(handler, { bazaar: deps.bazaar, verifyPayment: deps.verifyPayment });
+}