@supercuts-walrus/backend 0.1.4 → 0.1.5

package/config/proofs-v2.json

@@ -0,0 +1,122 @@
+{
+  "version": "supercuts.proofs.v2",
+  "githubRepo": "wurli-sh/supercuts-walrus",
+  "tag": "proofs-v2",
+  "baseUrl": "https://github.com/wurli-sh/supercuts-walrus/releases/download/proofs-v2",
+  "files": [
+    {
+      "path": "proving-manifest.json",
+      "asset": "proving-manifest.json",
+      "size": 1743,
+      "sha256": "fca6f28a579057a2b8bc4eb9068b99bf377a4d930d60f5462658a3bb184ab7ff"
+    },
+    {
+      "path": "deposit_v2_js/generate_witness.js",
+      "asset": "deposit_v2_js--generate_witness.js",
+      "size": 697,
+      "sha256": "4995a2e6b01432f76182abec6a831fdaf7f840384035072002ccaa43101b14d4"
+    },
+    {
+      "path": "deposit_v2_js/witness_calculator.js",
+      "asset": "deposit_v2_js--witness_calculator.js",
+      "size": 10356,
+      "sha256": "cc2d37b2cff2a589dd86f8636f1a1dc9fe4a854550b021aa0cea2e235d14e942"
+    },
+    {
+      "path": "deposit_v2_js/deposit_v2.wasm",
+      "asset": "deposit_v2_js--deposit_v2.wasm",
+      "size": 4948782,
+      "sha256": "45f887ebab9b395932934c644a3018b1c6447d1dbda508bd04026fa1d3b7fdc4"
+    },
+    {
+      "path": "proofs/deposit_v2/deposit_v2.zkey",
+      "asset": "proofs--deposit_v2--deposit_v2.zkey",
+      "size": 84649008,
+      "sha256": "d398776a54628c390e8bf822007e47ed8fac00e92e8ea95bb17d20db517998dc"
+    },
+    {
+      "path": "proofs/deposit_v2/verifying-key.bin",
+      "asset": "proofs--deposit_v2--verifying-key.bin",
+      "size": 328,
+      "sha256": "838404ff0ae3a9fc82da0856b68a11428cf3ffef335b4c6539fa1860d8e1ba26"
+    },
+    {
+      "path": "proofs/deposit_v2/verification-key.json",
+      "asset": "proofs--deposit_v2--verification-key.json",
+      "size": 3108,
+      "sha256": "cb4338c9a155908ed241406726f1f7b7e284fb2c37bbc8062cb996d893748379"
+    },
+    {
+      "path": "transfer_v2_js/generate_witness.js",
+      "asset": "transfer_v2_js--generate_witness.js",
+      "size": 697,
+      "sha256": "4995a2e6b01432f76182abec6a831fdaf7f840384035072002ccaa43101b14d4"
+    },
+    {
+      "path": "transfer_v2_js/witness_calculator.js",
+      "asset": "transfer_v2_js--witness_calculator.js",
+      "size": 10356,
+      "sha256": "cc2d37b2cff2a589dd86f8636f1a1dc9fe4a854550b021aa0cea2e235d14e942"
+    },
+    {
+      "path": "transfer_v2_js/transfer_v2.wasm",
+      "asset": "transfer_v2_js--transfer_v2.wasm",
+      "size": 8272696,
+      "sha256": "aaf3a7d9c29dab52211682e30934c7cdf911eb6f51a2ae670f7109e04950088e"
+    },
+    {
+      "path": "proofs/transfer_v2/transfer_v2.zkey",
+      "asset": "proofs--transfer_v2--transfer_v2.zkey",
+      "size": 158316569,
+      "sha256": "6e7bcac98b8d2a78fd1811e2caadd83d0d6a301951f8cf27ac55a67006b001c2"
+    },
+    {
+      "path": "proofs/transfer_v2/verifying-key.bin",
+      "asset": "proofs--transfer_v2--verifying-key.bin",
+      "size": 328,
+      "sha256": "8a6896f3f330769aa69e0dc1251a19fb69c4d6264b5729d0104df8d262e573ba"
+    },
+    {
+      "path": "proofs/transfer_v2/verification-key.json",
+      "asset": "proofs--transfer_v2--verification-key.json",
+      "size": 3111,
+      "sha256": "431c8320b41a1b853c09b9bf1be8408621ce93972334d0d8c98e35f116072d67"
+    },
+    {
+      "path": "withdraw_v2_js/generate_witness.js",
+      "asset": "withdraw_v2_js--generate_witness.js",
+      "size": 697,
+      "sha256": "4995a2e6b01432f76182abec6a831fdaf7f840384035072002ccaa43101b14d4"
+    },
+    {
+      "path": "withdraw_v2_js/witness_calculator.js",
+      "asset": "withdraw_v2_js--witness_calculator.js",
+      "size": 10356,
+      "sha256": "cc2d37b2cff2a589dd86f8636f1a1dc9fe4a854550b021aa0cea2e235d14e942"
+    },
+    {
+      "path": "withdraw_v2_js/withdraw_v2.wasm",
+      "asset": "withdraw_v2_js--withdraw_v2.wasm",
+      "size": 5748363,
+      "sha256": "1a57b0cf692012838d7d4d00f397b71907fc386d00fcb756e7b166374129033c"
+    },
+    {
+      "path": "proofs/withdraw_v2/withdraw_v2.zkey",
+      "asset": "proofs--withdraw_v2--withdraw_v2.zkey",
+      "size": 104313713,
+      "sha256": "fd303dd0dd53b9b752dac0de546dabdd03198a7a4defde5e8d6018bccd419c56"
+    },
+    {
+      "path": "proofs/withdraw_v2/verifying-key.bin",
+      "asset": "proofs--withdraw_v2--verifying-key.bin",
+      "size": 328,
+      "sha256": "445c1982bea5e465fb0f5665023bb279637d820a9425f16a4c2f2ee7460e7e4a"
+    },
+    {
+      "path": "proofs/withdraw_v2/verification-key.json",
+      "asset": "proofs--withdraw_v2--verification-key.json",
+      "size": 3107,
+      "sha256": "f5cdca32c58e2b0c66891f4a5d774468d276f0579efe3faef50765409a625a75"
+    }
+  ]
+}

package/dist/buyer-setup.js

@@ -136,6 +136,7 @@ function setupBuyerConfig(home, config) {
             `Fund only this buyer with Testnet SUI: supercuts funding execute --home ${home} --public-payment <MIST> --shielded-payment 0 --operation-id fund-1 --request-faucet --confirm (or use https://faucet.sui.io for ${address})`,
             ...(config.allowedCounterparties?.length ? [] : [`Review the directory, then approve a seller: supercuts policy approve-seller --home ${home} --capability-id <id>`]),
             ...(config.memoryConfigFile ? [`Keep the Walrus Memory embedding adapter running (supercuts-embedding-adapter). An MCP agent flushes outcome memories itself; SDK-only hosts also run: supercuts-memory-worker ${home}`] : []),
+            "For shielded (private) payments, install the hash-pinned proving keys once per machine (~370 MB): supercuts proofs install",
             `Check readiness: supercuts onboarding doctor --home ${home}`,
             `Connect an agent with ${session.mcpConfig}, or call BuyerClient.executeDeal from @supercuts-walrus/sdk.`,
         ] };

package/dist/cli.js

@@ -7,16 +7,24 @@ import { packageHostedSeller } from "./seller-package.js";
 import { promptSellerSetup, setupSeller } from "./seller-setup.js";
 import { scaffoldSeller } from "./seller-scaffold.js";
 import { generateSellerResearch } from "./seller-research.js";
+import { installProofs, proofsStatus } from "./proofs-install.js";
 const words = process.argv.slice(2);
 let command = words.shift() ?? "";
-if (["wallet", "offer", "pay", "resource", "memory", "audit", "capability", "settlement", "setup", "policy", "onboarding", "onboard", "funding", "seller"].includes(command))
+if (["wallet", "offer", "pay", "resource", "memory", "audit", "capability", "settlement", "setup", "policy", "onboarding", "onboard", "funding", "seller", "proofs"].includes(command))
     command += `.${words.shift() ?? ""}`;
 try {
     if (!command || command === "help" || command === "--help" || command === "setup.") {
-        process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.help.v1", ok: true, commands: ["onboard buyer", "onboard seller", "seller scaffold", "seller research", "seller package", "funding prepare", "funding execute", "setup buyer", "setup seller", "setup renew", "setup session", "init", "doctor", "status", "wallet", "offer", "pay", "memory", "memory insights", "capability", "audit"], setup: "Run supercuts onboard buyer or supercuts onboard seller with an isolated --home. Then use seller scaffold to generate a capability. Research sellers can use seller research to create a cited owner-review draft before packaging.", live: "Fund only the generated buyer address. A seller does not need faucet funds to publish or receive a capability payment." })}\n`);
+        process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.help.v1", ok: true, commands: ["onboard buyer", "onboard seller", "seller scaffold", "seller research", "seller package", "funding prepare", "funding execute", "setup buyer", "setup seller", "setup renew", "setup session", "init", "doctor", "status", "wallet", "offer", "pay", "memory", "memory insights", "proofs install", "proofs status", "capability", "audit"], setup: "Run supercuts onboard buyer or supercuts onboard seller with an isolated --home. Then use seller scaffold to generate a capability. Research sellers can use seller research to create a cited owner-review draft before packaging.", live: "Fund only the generated buyer address. A seller does not need faucet funds to publish or receive a capability payment." })}\n`);
         process.exit(0);
     }
     const args = parseArgs(words);
+    if (command === "proofs.install" || command === "proofs.status") {
+        // Proving keys are shared, public, hash-pinned files; they need no role home.
+        const dir = typeof args.dir === "string" ? args.dir : undefined;
+        const data = command === "proofs.status" ? await proofsStatus(dir) : await installProofs({ ...(dir ? { dir } : {}), ...(typeof args.source === "string" ? { source: args.source } : {}), onProgress: (file) => process.stderr.write(`verifying ${file.path} (${Math.ceil(file.size / 1048576)} MB)\n`) });
+        process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.proofs.v1", ok: true, command, data })}\n`);
+        process.exit(0);
+    }
     const home = homePath(args);
     const fundingInput = { publicPayment: String(args["public-payment"] ?? "0"), shieldedPayment: String(args["shielded-payment"] ?? "0"), ...(typeof args["gas-reserve"] === "string" ? { gasReserve: args["gas-reserve"] } : {}), ...(typeof args["change-reserve"] === "string" ? { changeReserve: args["change-reserve"] } : {}) };
     const result = command === "init" ? initialize(home, args) : command === "setup.buyer" || command === "onboard.buyer" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: typeof args.config === "string" ? setupBuyer(home, args.config) : await promptBuyerSetup(home) } : command === "setup.seller" || command === "onboard.seller" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: typeof args.config === "string" ? setupSeller(home, args.config) : await promptSellerSetup(home) } : command === "seller.scaffold" ? { schemaVersion: "supercuts.seller-scaffold.v1", ok: true, command, data: scaffoldSeller({ ...args, home }) } : command === "seller.research" ? { schemaVersion: "supercuts.seller-research.v1", ok: true, command, data: await generateSellerResearch({ kind: String(args.kind ?? ""), topic: String(args.topic ?? ""), output: String(args.output ?? ""), ...(typeof args["context-file"] === "string" ? { contextFile: args["context-file"] } : {}), ...(typeof args["allowed-domains"] === "string" ? { allowedDomains: args["allowed-domains"] } : {}), ...(typeof args.model === "string" ? { model: args.model } : {}) }) } : command === "setup.renew" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: renewBuyer(home, String(args.config ?? "")) } : command === "setup.session" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: createBuyerSession(home) } : command === "funding.prepare" ? { schemaVersion: "supercuts.funding.v1", ok: true, command, data: await prepareFunding(home, fundingInput) } : command === "funding.execute" ? { schemaVersion: "supercuts.funding.v1", ok: true, command, data: await executeFunding(home, { ...fundingInput, operationId: String(args["operation-id"] ?? ""), requestFaucet: args["request-faucet"] === true, confirmed: args.confirm === true }) } : command === "seller.package" ? { schemaVersion: "supercuts.seller-package.v1", ok: true, command, data: await packageHostedSeller({ home, spec: String(args.spec ?? ""), artifact: String(args.artifact ?? ""), metadata: String(args.metadata ?? ""), registration: String(args.registration ?? ""), bundle: String(args.bundle ?? ""), ...(typeof args["content-type"] === "string" ? { contentType: args["content-type"] } : {}) }) } : command === "policy.add" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await addBuyerPrivacyRule(home, String(args["capability-id"] ?? "")) } : command === "policy.approve-seller" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await approveBuyerSeller(home, String(args["capability-id"] ?? "")) } : command === "memory.insights" ? await (async () => { const app = new Phase3App(home); try {

package/dist/deal-engine.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { validateCapabilityPayload, verifySignedCapability } from "./capability.js";
 import { dealChildId } from "./deal.js";
 import { fail, SupercutsError } from "./errors.js";
-import { canonicalJson, validateSettlementPlan } from "./settlement.js";
+import { canonicalJson, planHonoursRail, validateSettlementPlan } from "./settlement.js";
 /**
  * Codes the buyer runtime verified against seller-supplied evidence. Buyer-side, network, and Walrus readback
  * errors are excluded: a readback mismatch can come from an aggregator, not the seller.
@@ -81,7 +81,7 @@ export class DealEngine {
             validateSettlementPlan(plan);
         if (plan.operationId !== paymentOperationId || plan.manifestHash !== registration.manifest.manifestHash || plan.asset !== input.budget.asset || BigInt(plan.maximumAmount) > BigInt(input.budget.maximum))
             fail("DEAL_PLAN_MISMATCH", "saved plan exceeds the deal's capability or budget");
-        if (input.requestedRail && plan.rail !== input.requestedRail || input.privacyHint === "shielded" && plan.rail !== "shielded")
+        if (!planHonoursRail(plan, input.requestedRail) || input.privacyHint === "shielded" && plan.rail !== "shielded")
             fail("DEAL_PRIVACY_UNAVAILABLE", "planned rail differs from the requested privacy");
         if (!input.requestedRail && registration.manifest.supportedRails.includes("shielded") && plan.rail !== "shielded")
             fail("DEAL_PRIVACY_UNAVAILABLE", "shielded is the default rail when the seller supports it");

package/dist/groth16-convert.d.ts

@@ -0,0 +1,7 @@
+export declare function encodeG1(value: unknown, label?: string): Buffer;
+export declare function encodeG2(value: unknown, label?: string): Buffer;
+export declare function encodePublicInputs(value: unknown): Buffer;
+export declare function encodeProof(proof: Record<string, unknown>): Buffer;
+export declare function encodeVerifyingKey(key: Record<string, unknown>): Buffer;
+/** Same outputs as the Rust converter: verifying-key.bin, proof.bin, public-inputs.bin in `outputDir`. */
+export declare function convertGroth16(verificationKeyPath: string, proofPath: string, publicPath: string, outputDir: string): void;

package/dist/groth16-convert.js

@@ -0,0 +1,108 @@
+/**
+ * SnarkJS Groth16 JSON -> Arkworks canonical compressed BN254 bytes (the format Sui's groth16 module expects).
+ *
+ * TypeScript port of `crates/supercuts-groth16`, so npm installs do not need a Rust toolchain. The prover runs
+ * `snarkjs groth16 verify` before conversion and then checks the converted verifying key against the pinned
+ * deployment hash, so a conversion bug cannot produce an accepted-but-wrong proof.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "./errors.js";
+const FQ = 21888242871839275222246405745257275088696311157297823662689037894645226208583n;
+const FR = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+const NEGATIVE = 0x80, INFINITY = 0x40;
+function field(value, modulus, label) {
+    if (typeof value !== "string" || !/^\d{1,80}$/.test(value))
+        return fail("PROOF_INVALID", `${label} must be a decimal string`);
+    const parsed = BigInt(value);
+    if (parsed >= modulus)
+        fail("PROOF_INVALID", `${label} is outside its field`);
+    return parsed;
+}
+function le32(value) {
+    const out = Buffer.alloc(32);
+    for (let index = 0, rest = value; index < 32; index += 1, rest >>= 8n)
+        out[index] = Number(rest & 0xffn);
+    return out;
+}
+const negative = (value) => value > (FQ - value) % FQ;
+function array(value, length, label) {
+    if (!Array.isArray(value) || value.length < length)
+        fail("PROOF_INVALID", `${label} must have ${length} coordinates`);
+    return value;
+}
+/** Projective SnarkJS points carry z = 1 for affine points; anything else is not a canonical affine point. */
+function affine(z, one, label) {
+    if (z === undefined)
+        return;
+    const value = Array.isArray(z) ? z : [z];
+    if (value[0] !== "1" || value.slice(1).some((item) => item !== one))
+        fail("PROOF_INVALID", `${label} must be an affine point`);
+}
+export function encodeG1(value, label = "G1") {
+    const point = array(value, 2, label);
+    affine(point[2], undefined, label);
+    const x = field(point[0], FQ, `${label}.x`), y = field(point[1], FQ, `${label}.y`);
+    if (x === 0n && y === 0n)
+        fail("PROOF_INVALID", `${label} is the point at infinity`);
+    const out = le32(x);
+    if (out[31] & (NEGATIVE | INFINITY))
+        fail("PROOF_INVALID", `${label}.x overlaps the flag bits`);
+    if (negative(y))
+        out[31] |= NEGATIVE;
+    return out;
+}
+export function encodeG2(value, label = "G2") {
+    const point = array(value, 2, label);
+    affine(point[2], "0", label);
+    const [x0, x1] = array(point[0], 2, `${label}.x`).map((item, index) => field(item, FQ, `${label}.x.c${index}`));
+    const [y0, y1] = array(point[1], 2, `${label}.y`).map((item, index) => field(item, FQ, `${label}.y.c${index}`));
+    if (x0 === 0n && x1 === 0n && y0 === 0n && y1 === 0n)
+        fail("PROOF_INVALID", `${label} is the point at infinity`);
+    const out = Buffer.concat([le32(x0), le32(x1)]);
+    if (out[63] & (NEGATIVE | INFINITY))
+        fail("PROOF_INVALID", `${label}.x overlaps the flag bits`);
+    // Arkworks orders Fq2 lexicographically from the highest coefficient: c1 decides unless it is zero.
+    if (y1 !== 0n ? negative(y1) : negative(y0))
+        out[63] |= NEGATIVE;
+    return out;
+}
+export function encodePublicInputs(value) {
+    if (!Array.isArray(value) || !value.length)
+        return fail("PROOF_INVALID", "public inputs must be a non-empty array");
+    return Buffer.concat(value.map((item, index) => le32(field(item, FR, `public[${index}]`))));
+}
+export function encodeProof(proof) {
+    return Buffer.concat([
+        encodeG1(proof.pi_a, "pi_a"),
+        encodeG2(proof.pi_b, "pi_b"),
+        encodeG1(proof.pi_c, "pi_c"),
+    ]);
+}
+export function encodeVerifyingKey(key) {
+    const ic = key.IC;
+    if (!Array.isArray(ic) || ic.length < 2)
+        return fail("PROOF_INVALID", "verification key IC is missing");
+    const length = Buffer.alloc(8);
+    length.writeBigUInt64LE(BigInt(ic.length));
+    return Buffer.concat([
+        encodeG1(key.vk_alpha_1, "vk_alpha_1"),
+        encodeG2(key.vk_beta_2, "vk_beta_2"),
+        encodeG2(key.vk_gamma_2, "vk_gamma_2"),
+        encodeG2(key.vk_delta_2, "vk_delta_2"),
+        length,
+        ...ic.map((point, index) => encodeG1(point, `IC[${index}]`)),
+    ]);
+}
+/** Same outputs as the Rust converter: verifying-key.bin, proof.bin, public-inputs.bin in `outputDir`. */
+export function convertGroth16(verificationKeyPath, proofPath, publicPath, outputDir) {
+    const read = (path) => JSON.parse(readFileSync(path, "utf8"));
+    const key = read(verificationKeyPath), proof = read(proofPath), inputs = read(publicPath);
+    const publicInputs = encodePublicInputs(inputs);
+    if (key.IC.length !== publicInputs.length / 32 + 1)
+        fail("PROOF_INVALID", "verification key and public input counts differ");
+    mkdirSync(outputDir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(outputDir, "verifying-key.bin"), encodeVerifyingKey(key));
+    writeFileSync(join(outputDir, "proof.bin"), encodeProof(proof));
+    writeFileSync(join(outputDir, "public-inputs.bin"), publicInputs);
+}

package/dist/live-runtime.d.ts

@@ -1,4 +1,5 @@
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { Transaction } from "@mysten/sui/transactions";
 import { LivePoolIndex } from "./live-index.js";
 import { ProtocolEngine } from "./protocol-engine.js";
 import { Groth16Prover, type ProverConfig } from "./prover.js";
@@ -7,6 +8,9 @@ import { TatumLedger } from "./tatum.js";
 import type { RoleStore } from "./store.js";
 export declare function x402ResourceFailure(status: number, response: Uint8Array): string;
 export declare function timestampExpirationUnsupported(value: unknown): boolean;
+/** A replacement signature is safe only after every validator must reject the old bytes.
+ * Timestamp expiry gets a clock/finality margin; epoch expiry is checked conservatively. */
+export declare function x402TransactionValidityEnded(expiration: ReturnType<Transaction["getData"]>["expiration"], currentEpoch: string | undefined, now?: number, safetyMarginMs?: number): boolean;
 export interface LiveRuntimeProfile {
     role: "buyer" | "seller" | "auditor";
     packageId: string;
@@ -49,7 +53,9 @@ export declare class LiveRuntime {
     static create(profile: LiveRuntimeProfile, store: RoleStore): Promise<LiveRuntime>;
     doctor(proofsRequired?: boolean): Promise<Record<string, unknown>>;
     balance(): Promise<Record<string, unknown>>;
+    private signTransaction;
     private signed;
+    private signedX402;
     private operationContext;
     private existingSigned;
     private submit;

package/dist/live-runtime.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { Transaction } from "@mysten/sui/transactions";
+import { TransactionError } from "@mysten/sui/client";
 import { fail, SupercutsError } from "./errors.js";
 import { assertSuiFinality, assertTatumFinality } from "./finality.js";
 import { LivePoolIndex } from "./live-index.js";
@@ -9,6 +11,7 @@ import { Groth16Prover } from "./prover.js";
 import { buildDeposit, buildPrivateTransfer, buildWithdraw, writeClient } from "./sui.js";
 import { V2ExitQueue } from "./v2-exits.js";
 import { TatumLedger } from "./tatum.js";
+import { resolveProverPaths } from "./proofs-install.js";
 import { paymentBindingBytes, requirementsHash } from "./x402.js";
 export function x402ResourceFailure(status, response) {
     const fallback = `paid resource returned ${status}`;
@@ -42,6 +45,18 @@ export function timestampExpirationUnsupported(value) {
     visit(value);
     return messages.some((message) => /timestamp-based transaction expiration is not yet supported|timestamp.*expiration.*not supported/i.test(message));
 }
+/** A replacement signature is safe only after every validator must reject the old bytes.
+ * Timestamp expiry gets a clock/finality margin; epoch expiry is checked conservatively. */
+export function x402TransactionValidityEnded(expiration, currentEpoch, now = Date.now(), safetyMarginMs = 60_000) {
+    if (!expiration || expiration.$kind !== "ValidDuring")
+        return false;
+    const validity = expiration.ValidDuring;
+    if (validity.maxTimestamp != null && now > Number(validity.maxTimestamp) + safetyMarginMs)
+        return true;
+    if (validity.maxEpoch != null && currentEpoch !== undefined && BigInt(currentEpoch) > BigInt(validity.maxEpoch))
+        return true;
+    return false;
+}
 const hex = (value) => value.toString(16).padStart(64, "0");
 const bytes32 = (value) => Buffer.from(hex(value), "hex");
 const hash = (value) => createHash("sha256").update(value).digest("hex");
@@ -64,12 +79,16 @@ export class LiveRuntime {
         this.engine = engine;
         this.client = writeClient(profile.live.writeGrpcEndpoint);
         this.index = new LivePoolIndex(store, this.client, engine, profile.packageId, profile.poolId, BigInt(profile.live.deploymentCheckpoint), profile.verifierVersion === 2 ? "pool_v2" : "pool");
-        this.prover = new Groth16Prover({ artifactRoot: profile.live.artifactRoot, snarkjsPath: profile.live.snarkjsPath, converterPath: profile.live.converterPath, ...(profile.live.rapidsnarkPath ? { rapidsnarkPath: profile.live.rapidsnarkPath } : {}), ...(profile.verifierVersion === 2 ? { version: 2 } : {}), expected: profile.live.artifacts });
+        this.prover = new Groth16Prover({ ...resolveProverPaths(profile.live, profile.verifierVersion === 2 ? "transfer_v2" : "transfer"), ...(profile.verifierVersion === 2 ? { version: 2 } : {}), expected: profile.live.artifacts });
         store.db.exec(`CREATE TABLE IF NOT EXISTS live_signed_transactions (
       operation_id TEXT PRIMARY KEY, intent_hash TEXT NOT NULL, transaction_bytes BLOB NOT NULL,
       signature TEXT NOT NULL, digest TEXT NOT NULL UNIQUE, status TEXT NOT NULL, updated_at INTEGER NOT NULL
     ); CREATE TABLE IF NOT EXISTS live_x402_deliveries (
       operation_id TEXT PRIMARY KEY, resource_url TEXT NOT NULL, receipt TEXT NOT NULL, response BLOB NOT NULL, updated_at INTEGER NOT NULL
+    ); CREATE TABLE IF NOT EXISTS live_superseded_x402_transactions (
+      operation_id TEXT NOT NULL, intent_hash TEXT NOT NULL, transaction_bytes BLOB NOT NULL,
+      signature TEXT NOT NULL, digest TEXT NOT NULL UNIQUE, status TEXT NOT NULL, superseded_at INTEGER NOT NULL,
+      PRIMARY KEY(operation_id, digest)
     ); CREATE TABLE IF NOT EXISTS live_agreements (
       session_id TEXT PRIMARY KEY, agreement TEXT NOT NULL, deal_commitment TEXT NOT NULL, accepted_at INTEGER NOT NULL
     ); CREATE TABLE IF NOT EXISTS live_seller_agreements (
@@ -110,9 +129,8 @@ export class LiveRuntime {
         const identity = this.engine.identity(babySeed);
         const fixes = [], shieldedFixes = [];
         if (shieldedProofs === "unavailable")
-            shieldedFixes.push(`Shielded payments are unavailable (${shieldedProofsReason}): install the hash-pinned v2 proving artifacts, SnarkJS, and the converter. Public x402 payments do not need them.`);
-        else if (!artifacts.rapidSnark)
-            shieldedFixes.push("Set an executable RapidSnark path in the role profile for v2 proofs.");
+            shieldedFixes.push(`Shielded payments are unavailable (${shieldedProofsReason}): run \`supercuts proofs install\` to download and verify the hash-pinned v2 proving keys (~370 MB). Public x402 payments do not need them.`);
+        const warnings = shieldedProofs === "ready" && !artifacts.rapidSnark ? ["RapidSnark is not configured; shielded proofs use SnarkJS, which is slower. Set SUPERCUTS_RAPIDSNARK to a RapidSnark prover binary to speed them up."] : [];
         if (!this.profile.live.walrusPublisherUrl)
             fixes.push("Configure the Walrus publisher URL for capability and transcript writes.");
         if (!this.profile.live.walrusAggregatorUrl)
@@ -129,7 +147,7 @@ export class LiveRuntime {
                 fixes.push(`Walrus ${name} is unreachable; check the configured URL and network access.`);
             }
         }
-        return { role: this.profile.role, network: "testnet", packageId: this.profile.packageId, poolId: this.profile.poolId, asset: this.profile.coinType, verifierVersion: this.profile.verifierVersion, keyPermissions: "owner-only", rpc: this.profile.live.writeGrpcEndpoint, healthy: true, readyForDemo: fixes.length === 0 && (!proofsRequired || shieldedFixes.length === 0), fixes: [...fixes, ...(proofsRequired ? shieldedFixes : [])], publicFixes: fixes, shieldedProofs, shieldedFixes, readyForPublicRail: fixes.length === 0, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), memoryConfigured: Boolean(this.store.getSecret("live:memory-config")), proofsRequired, rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
+        return { role: this.profile.role, network: "testnet", packageId: this.profile.packageId, poolId: this.profile.poolId, asset: this.profile.coinType, verifierVersion: this.profile.verifierVersion, keyPermissions: "owner-only", rpc: this.profile.live.writeGrpcEndpoint, healthy: true, readyForDemo: fixes.length === 0 && (!proofsRequired || shieldedFixes.length === 0), fixes: [...fixes, ...(proofsRequired ? shieldedFixes : [])], publicFixes: fixes, shieldedProofs, shieldedFixes, warnings, readyForPublicRail: fixes.length === 0, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), memoryConfigured: Boolean(this.store.getSecret("live:memory-config")), proofsRequired, rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
     }
     async balance() {
         const state = await this.index.sync();
@@ -147,6 +165,15 @@ export class LiveRuntime {
         return { available: available.toString(), notes, root: hex(state.root), nextLeaf: state.nextLeaf.toString(), checkpoint: state.lastCheckpoint.toString(), evidence: "event-derived-and-pool-object-verified",
             ...(state.activity ? { poolActivity: state.activity, privacyWarning: state.activity.reducedPrivacy ? "Sparse observed pool use reduces privacy; distinct depositing addresses do not prove independent users" : undefined } : {}) };
     }
+    async signTransaction(tx) {
+        tx.setSender(this.signer.toSuiAddress());
+        const simulation = await this.client.simulateTransaction({ transaction: tx, include: { effects: true } });
+        const simulated = simulation.Transaction ?? simulation.FailedTransaction;
+        if (!simulated?.status.success)
+            fail("TRANSACTION_SIMULATION_FAILED", "Sui rejected the transaction during simulation");
+        const transaction = await tx.build({ client: this.client }), digest = await tx.getDigest({ client: this.client }), signature = (await this.signer.signTransaction(transaction)).signature;
+        return { transaction, signature, digest };
+    }
     async signed(operationId, intentHash, tx, legacyIntentHash) {
         const existing = this.store.db.prepare("SELECT intent_hash,transaction_bytes,signature,digest FROM live_signed_transactions WHERE operation_id=?").get(operationId);
         if (existing) {
@@ -154,15 +181,77 @@ export class LiveRuntime {
                 fail("OPERATION_ID_CONFLICT", "operation ID identifies different transaction intent");
             return { digest: existing.digest, transaction: existing.transaction_bytes, signature: existing.signature };
         }
-        tx.setSender(this.signer.toSuiAddress());
-        const simulation = await this.client.simulateTransaction({ transaction: tx, include: { effects: true } });
-        const simulated = simulation.Transaction ?? simulation.FailedTransaction;
-        if (!simulated?.status.success)
-            fail("TRANSACTION_SIMULATION_FAILED", "Sui rejected the transaction during simulation");
-        const transaction = await tx.build({ client: this.client }), digest = await tx.getDigest({ client: this.client }), signature = (await this.signer.signTransaction(transaction)).signature;
+        const { transaction, signature, digest } = await this.signTransaction(tx);
         this.store.db.prepare("INSERT INTO live_signed_transactions(operation_id,intent_hash,transaction_bytes,signature,digest,status,updated_at) VALUES(?,?,?,?,?,'signed',?)").run(operationId, intentHash, Buffer.from(transaction), signature, digest, Date.now());
         return { transaction, signature, digest };
     }
+    async signedX402(operationId, intentHash, tx, legacyIntentHash) {
+        const existing = this.store.db.prepare("SELECT intent_hash,transaction_bytes,signature,digest,status FROM live_signed_transactions WHERE operation_id=?").get(operationId);
+        if (!existing || existing.intent_hash === intentHash || existing.intent_hash === legacyIntentHash)
+            return this.signed(operationId, intentHash, tx, legacyIntentHash);
+        // A fresh seller nonce does not itself authorize another transfer. First reuse the exact old
+        // signed bytes. Replace them only if the old digest is finalized-failed, or is absent from the
+        // authoritative RPC after its validity window and safety margin have ended.
+        let observed;
+        try {
+            observed = await this.client.getTransaction({ digest: existing.digest, include: { effects: true } });
+        }
+        catch (error) {
+            if (!(error instanceof TransactionError) || error.reason !== "notFound")
+                fail("X402_RESIGN_UNSAFE", "could not prove the prior signed payment absent; retry the same operation without creating another signature", error);
+        }
+        if (observed) {
+            const envelope = observed.Transaction ?? observed.FailedTransaction ?? observed, observedDigest = envelope?.digest ?? envelope?.effects?.transactionDigest;
+            if (observedDigest !== existing.digest || !envelope?.checkpoint)
+                fail("X402_RESIGN_UNSAFE", "prior payment lookup returned ambiguous settlement evidence");
+            if (envelope.status?.success === true) {
+                const checkpoint = assertSuiFinality(observed.Transaction || observed.FailedTransaction ? observed : { Transaction: envelope }, existing.digest);
+                await this.confirmTatum(existing.digest, checkpoint);
+                this.store.db.prepare("UPDATE live_signed_transactions SET status='finalized',updated_at=? WHERE operation_id=?").run(Date.now(), operationId);
+                return { digest: existing.digest, transaction: existing.transaction_bytes, signature: existing.signature };
+            }
+            if (envelope.status?.success !== false)
+                fail("X402_RESIGN_UNSAFE", "prior payment finality is ambiguous; refusing a replacement signature");
+        }
+        else {
+            let expiration;
+            try {
+                expiration = Transaction.from(existing.transaction_bytes).getData().expiration;
+            }
+            catch (error) {
+                return fail("X402_RESIGN_UNSAFE", "prior signed payment validity could not be decoded", error);
+            }
+            let currentEpoch;
+            if (expiration?.$kind === "ValidDuring" && expiration.ValidDuring.maxTimestamp == null && expiration.ValidDuring.maxEpoch != null) {
+                try {
+                    currentEpoch = (await this.client.core.getCurrentSystemState()).systemState.epoch;
+                }
+                catch (error) {
+                    return fail("X402_RESIGN_UNSAFE", "could not verify that the prior payment validity window ended", error);
+                }
+            }
+            if (!x402TransactionValidityEnded(expiration, currentEpoch)) {
+                if (expiration?.$kind === "ValidDuring" && expiration.ValidDuring.maxTimestamp != null && Date.now() > Number(expiration.ValidDuring.maxTimestamp)) {
+                    fail("X402_RESIGN_UNSAFE", "prior payment expired but its finality safety margin has not ended; retry this same operation ID shortly");
+                }
+                return { digest: existing.digest, transaction: existing.transaction_bytes, signature: existing.signature };
+            }
+        }
+        const replacement = await this.signTransaction(tx), now = Date.now();
+        this.store.db.exec("BEGIN IMMEDIATE");
+        try {
+            this.store.db.prepare("INSERT OR IGNORE INTO live_superseded_x402_transactions(operation_id,intent_hash,transaction_bytes,signature,digest,status,superseded_at) VALUES(?,?,?,?,?,?,?)").run(operationId, existing.intent_hash, existing.transaction_bytes, existing.signature, existing.digest, existing.status, now);
+            const updated = this.store.db.prepare("UPDATE live_signed_transactions SET intent_hash=?,transaction_bytes=?,signature=?,digest=?,status='signed',updated_at=? WHERE operation_id=? AND digest=?").run(intentHash, Buffer.from(replacement.transaction), replacement.signature, replacement.digest, now, operationId, existing.digest);
+            if (updated.changes !== 1)
+                fail("X402_RESIGN_UNSAFE", "payment journal changed while replacing an expired signature; retry the same operation ID");
+            this.store.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.store.db.exec("ROLLBACK");
+            throw error;
+        }
+        return replacement;
+    }
     operationContext(operationId, kind, subject) {
         const existing = this.store.db.prepare("SELECT kind,subject FROM live_operation_context WHERE operation_id=?").get(operationId);
         if (existing) {
@@ -625,7 +714,7 @@ export class LiveRuntime {
             tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: null, chain: validity.chain, nonce: validity.nonce } });
         }
         const legacyIntentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString() }));
-        const intentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString(), requestId, requirementsHash: String(extra?.requirementsHash) })), signed = await this.signed(operationId, intentHash, tx, legacyIntentHash);
+        const intentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString(), requestId, requirementsHash: String(extra?.requirementsHash) })), signed = await this.signedX402(operationId, intentHash, tx, legacyIntentHash);
         const unsignedBinding = { requestId, nonce, requirementsHash: requirementsHash(unsignedRequirements), transactionDigest: signed.digest, payer: this.signer.toSuiAddress() };
         const payerSignature = (await this.signer.signPersonalMessage(paymentBindingBytes(unsignedBinding))).signature;
         const paymentPayload = { x402Version: 2, resource, accepted: requirements, payload: { signature: signed.signature, transaction: Buffer.from(signed.transaction).toString("base64") } };

package/dist/phase3.js

@@ -11,7 +11,7 @@ import { validateCapabilityManifest } from "./capability.js";
 import { ManualMemory, openMemoryText, withMemoryDefaults } from "./memwal.js";
 import { WorkflowMemory } from "./workflow-memory.js";
 import { buildScorecard } from "./memory-scorecard.js";
-import { canonicalJson, createSettlementPlan, explainMemoryInfluence, isRelevantMemory, settlementMandateHash, settlementPlanHash, validateSettlementMemory, validateSettlementPlan } from "./settlement.js";
+import { canonicalJson, createSettlementPlan, explainMemoryInfluence, planHonoursRail, isRelevantMemory, settlementMandateHash, settlementPlanHash, validateSettlementMemory, validateSettlementPlan } from "./settlement.js";
 const PACKAGE = "0xf887433ddfd1068f6df3020cd757939b99ceb418f0d8b9924092b01c7aee846e";
 const POOL = "0x873e37b4745316f21a2780893f5fc36f87da559b08923fb4dad6237cd2e95d98";
 const V2_PACKAGE = "0x32d104c1ab422d497df4ae3a6861258694949c86428f886ca338e07bd055cf76";
@@ -459,7 +459,7 @@ export class Phase3App {
             const requestedAmount = typeof args["requested-amount"] === "string" ? BigInt(args["requested-amount"]) : BigInt(existing.manifestMinimum);
             const boundedAmount = requestedAmount < BigInt(existing.manifestMinimum) ? BigInt(existing.manifestMinimum) : requestedAmount > BigInt(existing.maximumAmount) ? BigInt(existing.maximumAmount) : requestedAmount;
             const requestedRail = args["requested-rail"] === "x402" || args["requested-rail"] === "shielded" ? args["requested-rail"] : undefined;
-            if (existing.mandateHash !== settlementMandateHash(mandate) || !manifests.some((manifest) => manifest.manifestHash === existing.manifestHash) || requestedRail && requestedRail !== existing.rail || args["privacy-hint"] === "shielded" && existing.rail !== "shielded" || boundedAmount.toString() !== existing.openingAmount) {
+            if (existing.mandateHash !== settlementMandateHash(mandate) || !manifests.some((manifest) => manifest.manifestHash === existing.manifestHash) || !planHonoursRail(existing, requestedRail) || args["privacy-hint"] === "shielded" && existing.rail !== "shielded" || boundedAmount.toString() !== existing.openingAmount) {
                 fail("OPERATION_ID_CONFLICT", "planning operation already identifies another immutable plan");
             }
             return existing;
@@ -536,23 +536,26 @@ export class Phase3App {
         const recalled = await this.recallSettlementMemories(allowed.map(memoryQuery)), now = Date.now(), maxDistance = this.profile.policy.maxMemoryDistance ?? 0.35;
         const relevant = recalled.filter((item) => isRelevantMemory(item, maxDistance));
         // Only rank sellers that the deal could actually plan and pay: budget, rail, privacy, and price bounds.
-        const payable = allowed.filter((manifest) => {
+        const payableWith = (memories) => (manifest) => {
             try {
-                const plan = createSettlementPlan({ operationId: `rank:${operationId}`, mandate, manifests: [manifest], requestedAmount: manifest.priceBand.minimum, recalled, maxMemoryDistance: maxDistance, now, ...(request.requestedRail ? { requestedRail: request.requestedRail } : {}), ...(request.privacyHint ? { privacyHint: request.privacyHint } : {}) });
+                const plan = createSettlementPlan({ operationId: `rank:${operationId}`, mandate, manifests: [manifest], requestedAmount: manifest.priceBand.minimum, recalled: memories, maxMemoryDistance: maxDistance, now, ...(request.requestedRail ? { requestedRail: request.requestedRail } : {}), ...(request.privacyHint ? { privacyHint: request.privacyHint } : {}) });
                 if (request.budgetMaximum !== undefined && BigInt(plan.maximumAmount) > BigInt(request.budgetMaximum))
                     return false;
-                return request.requestedRail ? plan.rail === request.requestedRail : mandate.version !== "supercuts.mandate.v2" || !manifest.supportedRails.includes("shielded") || plan.rail === "shielded";
+                return request.requestedRail ? planHonoursRail(plan, request.requestedRail) : mandate.version !== "supercuts.mandate.v2" || !manifest.supportedRails.includes("shielded") || plan.rail === "shielded";
             }
             catch {
                 return false;
             }
-        });
+        };
+        const payable = allowed.filter(payableWith(recalled));
+        // The counterfactual must see sellers that memory excluded, so it is computed over the memory-free payable set.
+        const baseline = allowed.filter(payableWith([]));
         const pool = payable.length ? payable : allowed;
         const scored = pool.map((manifest) => ({ manifest, card: buildScorecard(relevant, { counterparty: manifest.sellerId, capabilityClass: manifest.capability }, now) }));
         const review = (card) => Number(card.lastOutcome === "unresolved" || card.observations > 0 && card.reliability < 0.5);
         scored.sort((a, b) => review(a.card) - review(b.card) || b.card.reliability - a.card.reliability || (BigInt(a.manifest.priceBand.minimum) < BigInt(b.manifest.priceBand.minimum) ? -1 : BigInt(a.manifest.priceBand.minimum) > BigInt(b.manifest.priceBand.minimum) ? 1 : 0) || a.manifest.capabilityId.localeCompare(b.manifest.capabilityId));
         const result = { ordered: scored.map((item) => item.manifest), scorecards: scored.map((item) => ({ ...item.card, capabilityId: item.manifest.capabilityId, priceMinimum: item.manifest.priceBand.minimum })) };
-        record(this.store, "deal-ranking", operationId, { candidates: pool, scorecards: result.scorecards, chosen: result.ordered[0]?.capabilityId, createdAt: now });
+        record(this.store, "deal-ranking", operationId, { candidates: pool, baselineCandidates: baseline.length ? baseline : allowed, scorecards: result.scorecards, chosen: result.ordered[0]?.capabilityId, createdAt: now });
         return result;
     }
     /** Stores the counterfactual (same mandate, no memory, every candidate) next to the binding deal plan. */
@@ -563,7 +566,7 @@ export class Phase3App {
         const existing = get(this.store, "memory-influence", `deal:${dealOperationId}`);
         if (existing)
             return existing;
-        const influence = explainMemoryInfluence({ operationId: plan.operationId, mandate, manifests: ranking.candidates, requestedAmount: plan.openingAmount, ...request }, plan);
+        const influence = explainMemoryInfluence({ operationId: plan.operationId, mandate, manifests: ranking.baselineCandidates ?? ranking.candidates, requestedAmount: plan.openingAmount, ...request }, plan);
         const cited = [...new Set([...influence.citedBlobIds, ...ranking.scorecards.flatMap((item) => item.citedBlobIds)])].sort();
         const value = { ...influence, citedBlobIds: cited };
         record(this.store, "memory-influence", `deal:${dealOperationId}`, value);
@@ -831,10 +834,24 @@ export class Phase3App {
         const value = BigInt(actual.amount);
         if (value < BigInt(plan.manifestMinimum) || value > BigInt(plan.maximumAmount))
             fail("SETTLEMENT_PLAN_AMOUNT_EXCEEDED", "execution amount is outside the planned manifest bounds");
-        const binding = { planHash: plan.planHash, operationId, capabilityId: plan.capabilityId, manifestHash: plan.manifestHash, rail, amount: actual.amount, counterparty: actual.counterparty, asset: actual.asset, endpoint: actual.endpoint ?? null, requestId: actual.requestId, session: actual.session ?? null, requirementsHash: actual.requirementsHash ?? null };
-        const bindingHash = hash(canonicalJson({ domain: "supercuts-settlement-execution-v1", binding })), existing = this.store.db.prepare("SELECT binding_hash FROM settlement_execution_bindings WHERE operation_id=? OR plan_hash=?").get(operationId, plan.planHash);
-        if (existing && existing.binding_hash !== bindingHash)
-            fail("SETTLEMENT_PLAN_CONSUMED", "plan or operation is already bound to another execution");
+        const stableBinding = { planHash: plan.planHash, operationId, capabilityId: plan.capabilityId, manifestHash: plan.manifestHash, rail, amount: actual.amount, counterparty: actual.counterparty, asset: actual.asset, endpoint: actual.endpoint ?? null, requestId: actual.requestId, session: actual.session ?? null };
+        const binding = { ...stableBinding, requirementsHash: actual.requirementsHash ?? null };
+        // A renewed x402 challenge changes only its nonce-derived requirements hash. The plan remains
+        // consumed by the same economic payment and request; treating the ephemeral hash as the plan
+        // identity would make an expired challenge permanently strand the reserved buyer budget.
+        const bindingHash = hash(canonicalJson({ domain: "supercuts-settlement-execution-v2", binding: stableBinding })), existing = this.store.db.prepare("SELECT binding_hash,binding_json FROM settlement_execution_bindings WHERE operation_id=? OR plan_hash=?").get(operationId, plan.planHash);
+        if (existing && existing.binding_hash !== bindingHash) {
+            let old;
+            try {
+                old = JSON.parse(existing.binding_json);
+            }
+            catch (error) {
+                return fail("SETTLEMENT_PLAN_CONSUMED", "saved settlement execution binding is invalid", error);
+            }
+            const oldStable = Object.fromEntries(Object.keys(stableBinding).map((key) => [key, old[key]]));
+            if (canonicalJson(oldStable) !== canonicalJson(stableBinding))
+                fail("SETTLEMENT_PLAN_CONSUMED", "plan or operation is already bound to another execution");
+        }
         if (!existing && now >= plan.expiresAt)
             fail("SETTLEMENT_PLAN_EXPIRED", "settlement plan has expired");
         if (!existing) {
@@ -1256,7 +1273,7 @@ export class Phase3App {
 export function output(command, data) { return { schemaVersion: "supercuts.v1", ok: true, command, data }; }
 export function errorOutput(error) {
     const known = error instanceof SupercutsError ? error : new SupercutsError("INTERNAL_ERROR", error instanceof Error ? error.message : "unknown error");
-    const retryable = ["BROADCAST_UNRESOLVED", "DELIVERY_IN_PROGRESS", "DELIVERY_PENDING", "DEAL_SELLER_UNAVAILABLE", "ONBOARDING_SERVICE_UNAVAILABLE", "SELLER_DIRECTORY_UNAVAILABLE", "WALRUS_WRITE_FAILED", "WALRUS_READ_FAILED", "X402_FACILITATOR_UNAVAILABLE"].includes(known.code);
+    const retryable = ["BROADCAST_UNRESOLVED", "DELIVERY_IN_PROGRESS", "DELIVERY_PENDING", "DEAL_SELLER_UNAVAILABLE", "ONBOARDING_SERVICE_UNAVAILABLE", "SELLER_DIRECTORY_UNAVAILABLE", "WALRUS_WRITE_FAILED", "WALRUS_READ_FAILED", "X402_FACILITATOR_UNAVAILABLE", "X402_RESIGN_UNSAFE"].includes(known.code);
     const sameOperation = retryable || ["OPERATION_ID_CONFLICT", "DEAL_OPERATION_CONFLICT"].includes(known.code);
     return { schemaVersion: "supercuts.v1", ok: false, error: { code: known.code, message: known.message, recovery: recovery(known.code), retryable, retryWithSameOperationId: sameOperation } };
 }
@@ -1265,6 +1282,8 @@ function recovery(code) {
         return "repeat with --authorize after reviewing the operation";
     if (code === "PROFILE_NOT_FOUND")
         return "run supercuts init --role <role> --mock";
+    if (code === "X402_RESIGN_UNSAFE")
+        return "retry with the same operation ID; never start a second payment while the prior signed transaction can still settle";
     if (code.startsWith("POLICY_"))
         return "change the request or update the owner-controlled profile policy";
     if (code === "ARTIFACT_HASH_MISMATCH")

package/dist/proofs-install.d.ts

@@ -0,0 +1,54 @@
+export interface ProofFile {
+    path: string;
+    asset: string;
+    size: number;
+    sha256: string;
+}
+export interface ProofIndex {
+    version: "supercuts.proofs.v2";
+    githubRepo: string;
+    tag: string;
+    baseUrl: string;
+    files: ProofFile[];
+}
+export declare function bundledProofIndexPath(): string;
+export declare function loadProofIndex(path?: string): ProofIndex;
+/** `SUPERCUTS_PROOFS_DIR`, else `~/.supercuts/proofs/v2`. */
+export declare function defaultProofsDir(): string;
+export declare function proofsStatus(dir?: string, index?: ProofIndex): Promise<{
+    dir: string;
+    installed: boolean;
+    missing: string[];
+    mismatched: string[];
+}>;
+type Fetch = typeof fetch;
+/**
+ * Installs every pinned file into `dir`. Files are written to a sibling staging directory and only moved into
+ * place after every hash matches, so a failed or tampered download never leaves a half-installed tree.
+ */
+export declare function installProofs(options?: {
+    dir?: string;
+    source?: string;
+    index?: ProofIndex;
+    fetchImpl?: Fetch;
+    token?: string;
+    onProgress?: (file: ProofFile) => void;
+}): Promise<Record<string, unknown>>;
+/** Locates the SnarkJS CLI shipped as a backend dependency (pnpm does not link bins of transitive dependencies). */
+export declare function bundledSnarkjsCli(): string | undefined;
+/**
+ * Runtime prover paths. Profiles written by older releases point at a repository checkout that npm installs do
+ * not have; those paths are kept only when they exist, otherwise the installed proofs and bundled tools are used.
+ */
+export declare function resolveProverPaths(stored: {
+    artifactRoot: string;
+    snarkjsPath: string;
+    converterPath: string;
+    rapidsnarkPath?: string;
+}, artifactName: string): {
+    artifactRoot: string;
+    snarkjsPath: string;
+    converterPath: string;
+    rapidsnarkPath?: string;
+};
+export {};

package/dist/proofs-install.js

@@ -0,0 +1,241 @@
+/**
+ * Shielded proving artifacts for npm installs (`supercuts proofs install|status`).
+ *
+ * The v2 proving keys are about 370 MB, too large for the npm tarball. The package pins every runtime file by
+ * SHA-256 in `config/proofs-v2.json`; this module downloads them from the pinned GitHub Release (or a local copy
+ * or mirror), verifies each one, and installs them atomically in `~/.supercuts/proofs/v2`. A download host cannot
+ * substitute a file: anything that differs from the pinned hash is rejected before it is installed.
+ */
+import { createHash } from "node:crypto";
+import { accessSync, chmodSync, constants, createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import { fail } from "./errors.js";
+const MARKER = ".supercuts-proofs";
+const SAFE_PATH = /^(?:[a-z0-9_]+_js\/[a-z0-9_.]+|proofs\/[a-z0-9_]+\/[a-z0-9_.-]+|proving-manifest\.json)$/;
+export function bundledProofIndexPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), "../config/proofs-v2.json");
+}
+export function loadProofIndex(path = bundledProofIndexPath()) {
+    const index = JSON.parse(readFileSync(path, "utf8"));
+    if (index.version !== "supercuts.proofs.v2" ||
+        !Array.isArray(index.files) ||
+        !index.files.length)
+        fail("PROOF_INDEX_INVALID", "proof index is not a supercuts.proofs.v2 index");
+    for (const file of index.files)
+        if (!SAFE_PATH.test(file.path) ||
+            file.path.includes("..") ||
+            !/^[a-f0-9]{64}$/.test(file.sha256) ||
+            !Number.isSafeInteger(file.size) ||
+            file.size < 1 ||
+            !/^[A-Za-z0-9_.-]+$/.test(file.asset))
+            fail("PROOF_INDEX_INVALID", `proof index entry ${file.path} is invalid`);
+    return index;
+}
+/** `SUPERCUTS_PROOFS_DIR`, else `~/.supercuts/proofs/v2`. */
+export function defaultProofsDir() {
+    return process.env.SUPERCUTS_PROOFS_DIR
+        ? resolve(process.env.SUPERCUTS_PROOFS_DIR)
+        : join(homedir(), ".supercuts", "proofs", "v2");
+}
+const sha256File = async (path) => {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(path), hash);
+    return hash.digest("hex");
+};
+export async function proofsStatus(dir = defaultProofsDir(), index = loadProofIndex()) {
+    const missing = [], mismatched = [];
+    for (const file of index.files) {
+        const path = join(dir, file.path);
+        if (!existsSync(path))
+            missing.push(file.path);
+        else if (statSync(path).size !== file.size ||
+            (await sha256File(path)) !== file.sha256)
+            mismatched.push(file.path);
+    }
+    return {
+        dir,
+        installed: !missing.length && !mismatched.length,
+        missing,
+        mismatched,
+    };
+}
+async function githubAssetUrls(index, token, fetchImpl) {
+    const response = await fetchImpl(`https://api.github.com/repos/${index.githubRepo}/releases/tags/${encodeURIComponent(index.tag)}`, {
+        headers: {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${token}`,
+            "user-agent": "supercuts-proofs",
+        },
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok)
+        fail("PROOF_DOWNLOAD_FAILED", `GitHub release ${index.tag} lookup returned HTTP ${response.status}`);
+    const release = (await response.json());
+    return new Map((release.assets ?? []).map((asset) => [asset.name, asset.url]));
+}
+/**
+ * Installs every pinned file into `dir`. Files are written to a sibling staging directory and only moved into
+ * place after every hash matches, so a failed or tampered download never leaves a half-installed tree.
+ */
+export async function installProofs(options = {}) {
+    const index = options.index ?? loadProofIndex(), dir = resolve(options.dir ?? defaultProofsDir()), fetchImpl = options.fetchImpl ?? fetch;
+    const before = await proofsStatus(dir, index);
+    if (before.installed)
+        return { dir, alreadyInstalled: true, files: index.files.length };
+    const token = options.token ?? process.env.GITHUB_TOKEN;
+    const source = options.source, local = source && !/^https?:\/\//i.test(source) ? resolve(source) : undefined;
+    const assets = !source && token
+        ? await githubAssetUrls(index, token, fetchImpl)
+        : undefined;
+    // Never replace a directory this installer did not create: --dir or SUPERCUTS_PROOFS_DIR could name $HOME.
+    if (existsSync(dir) && readdirSync(dir).length && !existsSync(join(dir, MARKER)))
+        fail("PROOFS_DIR_UNSAFE", `${dir} is not empty and was not created by supercuts proofs install; choose an empty or new directory`);
+    mkdirSync(dirname(dir), { recursive: true, mode: 0o700 });
+    const lock = `${dir}.lock`;
+    try {
+        mkdirSync(lock, { mode: 0o700 });
+    }
+    catch {
+        // A lock older than the longest possible download belongs to a killed install.
+        if (Date.now() - statSync(lock).mtimeMs < 2 * 60 * 60_000)
+            fail("PROOFS_INSTALL_BUSY", `another proofs install holds ${lock}; wait for it or remove the lock if no install is running`);
+    }
+    const staging = `${dir}.partial`, previous = `${dir}.previous`;
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true, mode: 0o700 });
+    let bytes = 0;
+    try {
+        for (const file of index.files) {
+            options.onProgress?.(file);
+            const target = join(staging, file.path);
+            mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+            const existing = join(dir, file.path);
+            let input;
+            if (existsSync(existing) &&
+                !before.missing.includes(file.path) &&
+                !before.mismatched.includes(file.path))
+                input = { body: createReadStream(existing) };
+            else if (local)
+                input = { body: createReadStream(join(local, file.path)) };
+            else {
+                const assetUrl = assets?.get(file.asset);
+                if (assets && !assetUrl)
+                    fail("PROOF_DOWNLOAD_FAILED", `release ${index.tag} has no asset ${file.asset}`);
+                const url = assetUrl ??
+                    `${(source ?? index.baseUrl).replace(/\/$/, "")}/${file.asset}`;
+                const response = await fetchImpl(url, {
+                    headers: {
+                        "user-agent": "supercuts-proofs",
+                        ...(assetUrl
+                            ? {
+                                accept: "application/octet-stream",
+                                authorization: `Bearer ${token}`,
+                            }
+                            : {}),
+                    },
+                    redirect: "follow",
+                    signal: AbortSignal.timeout(30 * 60_000),
+                });
+                if (!response.ok || !response.body)
+                    fail("PROOF_DOWNLOAD_FAILED", `${file.asset} returned HTTP ${response.status}${response.status === 404 && !token ? "; set GITHUB_TOKEN while the release repository is private" : ""}`);
+                input = {
+                    body: Readable.fromWeb(response.body),
+                };
+            }
+            const hash = createHash("sha256");
+            let size = 0;
+            const meter = new Transform({
+                transform(chunk, _encoding, done) {
+                    size += chunk.length;
+                    if (size > file.size)
+                        return done(new Error("file is larger than pinned"));
+                    hash.update(chunk);
+                    done(null, chunk);
+                },
+            });
+            try {
+                await pipeline(input.body, meter, createWriteStream(target, { mode: 0o600 }));
+            }
+            catch (error) {
+                if (size > file.size)
+                    fail("ARTIFACT_HASH_MISMATCH", `${file.path} is larger than its pinned size`, error);
+                fail("PROOF_DOWNLOAD_FAILED", `${file.path} could not be read or downloaded; retry the install`, error);
+            }
+            if (size !== file.size || hash.digest("hex") !== file.sha256)
+                fail("ARTIFACT_HASH_MISMATCH", `${file.path} does not match the pinned SHA-256`);
+            bytes += size;
+        }
+        writeFileSync(join(staging, MARKER), `${index.version}\n`, { mode: 0o600 });
+        // Move the old install aside before swapping, so an interruption leaves either install recoverable.
+        rmSync(previous, { recursive: true, force: true });
+        if (existsSync(dir))
+            renameSync(dir, previous);
+        renameSync(staging, dir);
+        chmodSync(dir, 0o700);
+        rmSync(previous, { recursive: true, force: true });
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        if (!existsSync(dir) && existsSync(previous))
+            renameSync(previous, dir);
+        throw error;
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+    return { dir, installed: true, files: index.files.length, bytes };
+}
+const isExecutable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Locates the SnarkJS CLI shipped as a backend dependency (pnpm does not link bins of transitive dependencies). */
+export function bundledSnarkjsCli() {
+    try {
+        let directory = dirname(createRequire(import.meta.url).resolve("snarkjs"));
+        while (!existsSync(join(directory, "package.json")) &&
+            dirname(directory) !== directory)
+            directory = dirname(directory);
+        const cli = join(directory, "build", "cli.cjs");
+        return existsSync(cli) ? cli : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Runtime prover paths. Profiles written by older releases point at a repository checkout that npm installs do
+ * not have; those paths are kept only when they exist, otherwise the installed proofs and bundled tools are used.
+ */
+export function resolveProverPaths(stored, artifactName) {
+    const hasKeys = (root) => Boolean(root) &&
+        existsSync(join(root, "proofs", artifactName, `${artifactName}.zkey`));
+    const artifactRoot = hasKeys(stored.artifactRoot)
+        ? stored.artifactRoot
+        : hasKeys(defaultProofsDir())
+            ? defaultProofsDir()
+            : stored.artifactRoot;
+    const snarkjsPath = isExecutable(stored.snarkjsPath)
+        ? stored.snarkjsPath
+        : (bundledSnarkjsCli() ?? stored.snarkjsPath);
+    const converterPath = isExecutable(stored.converterPath)
+        ? stored.converterPath
+        : "builtin";
+    const rapidsnark = stored.rapidsnarkPath ?? process.env.SUPERCUTS_RAPIDSNARK;
+    return {
+        artifactRoot,
+        snarkjsPath,
+        converterPath,
+        ...(rapidsnark ? { rapidsnarkPath: resolve(rapidsnark) } : {}),
+    };
+}

package/dist/prover.d.ts

@@ -24,5 +24,6 @@ export declare class Groth16Prover {
         rapidSnark: boolean;
         artifacts: Record<CircuitName, string>;
     };
+    private snarkjs;
     prove(name: CircuitName, input: Record<string, unknown>): Promise<ProofResult>;
 }

package/dist/prover.js

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { fail } from "./errors.js";
+import { convertGroth16 } from "./groth16-convert.js";
 const run = promisify(execFile);
 const sha256 = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
 function executable(path) { try {
@@ -14,6 +15,9 @@ function executable(path) { try {
 catch {
     return false;
 } }
+/** SnarkJS may be a native bin or the npm package's `cli.cjs`, which runs under the current Node binary. */
+const isScript = (path) => /\.(?:c|m)?js$/.test(path);
+const toolReady = (path) => isScript(path) ? existsSync(path) : executable(path);
 export class Groth16Prover {
     config;
     constructor(config) {
@@ -31,10 +35,14 @@ export class Groth16Prover {
                 fail("ARTIFACT_HASH_MISMATCH", `${name} artifact hash differs from deployment configuration`);
             artifacts[name] = expected.zkeySha256;
         }
-        if (!executable(this.config.snarkjsPath) || !executable(this.config.converterPath))
+        if (!toolReady(this.config.snarkjsPath) || this.config.converterPath !== "builtin" && !executable(this.config.converterPath))
             fail("PROVER_TOOL_MISSING", "SnarkJS or the Arkworks converter is not executable");
         return { rapidSnark: Boolean(this.config.rapidsnarkPath && executable(this.config.rapidsnarkPath)), artifacts };
     }
+    snarkjs(args, timeout) {
+        const [command, prefix] = isScript(this.config.snarkjsPath) ? [process.execPath, [this.config.snarkjsPath]] : [this.config.snarkjsPath, []];
+        return run(command, [...prefix, ...args], { timeout, maxBuffer: 4 * 1024 * 1024 });
+    }
     async prove(name, input) {
         this.doctor();
         const directory = mkdtempSync(join(tmpdir(), `supercuts-${name}-`));
@@ -51,10 +59,13 @@ export class Groth16Prover {
             if (useRapid)
                 await run(this.config.rapidsnarkPath, [zkey, witness, proofJson, publicJson], { timeout: 10 * 60_000, maxBuffer: 4 * 1024 * 1024 });
             else
-                await run(this.config.snarkjsPath, ["groth16", "prove", zkey, witness, proofJson, publicJson], { timeout: 20 * 60_000, maxBuffer: 4 * 1024 * 1024 });
+                await this.snarkjs(["groth16", "prove", zkey, witness, proofJson, publicJson], 20 * 60_000);
             const proveMs = Date.now() - started;
-            await run(this.config.snarkjsPath, ["groth16", "verify", verificationKey, publicJson, proofJson], { timeout: 2 * 60_000, maxBuffer: 4 * 1024 * 1024 });
-            await run(this.config.converterPath, [name, verificationKey, proofJson, publicJson, converted], { timeout: 2 * 60_000, maxBuffer: 4 * 1024 * 1024 });
+            await this.snarkjs(["groth16", "verify", verificationKey, publicJson, proofJson], 2 * 60_000);
+            if (this.config.converterPath === "builtin")
+                convertGroth16(verificationKey, proofJson, publicJson, converted);
+            else
+                await run(this.config.converterPath, [name, verificationKey, proofJson, publicJson, converted], { timeout: 2 * 60_000, maxBuffer: 4 * 1024 * 1024 });
             const preparedVk = join(converted, "verifying-key.bin");
             if (sha256(preparedVk) !== this.config.expected[name].verifyingKeySha256)
                 fail("ARTIFACT_HASH_MISMATCH", "converter produced an unexpected verifying key");

package/dist/seller-setup.js

@@ -71,7 +71,7 @@ function setupSellerConfig(home, config) {
         fundingRequired: false,
         warning: "Do not faucet-fund the seller. Only a generated buyer address is funded for live purchases.",
         ...createSellerSession(home),
-        nextStep: `Run supercuts seller scaffold --home ${JSON.stringify(home)} --output <offer-dir> with the capability, origin, price, rails, and expiry options. Review the handler, then run the printed registration and service commands.`,
+        nextStep: `Run supercuts seller scaffold --home ${JSON.stringify(home)} --output <offer-dir> with the capability, origin, price, rails, and expiry options. Review the handler, then run the printed registration and service commands. Offers with the shielded rail also need the proving keys once per machine to recover and exit notes: supercuts proofs install.`,
     };
 }
 export function setupSeller(home, configPath) {

package/dist/settlement.d.ts

@@ -37,7 +37,7 @@ export interface SettlementCitation {
     provenance: SettlementMemoryProvenance;
     distance: number;
 }
-export type SettlementReasonCode = "MANDATE_DEFAULTS_APPLIED" | "MEMORY_PRIVACY_APPLIED" | "MEMORY_BUDGET_APPLIED" | "MEMORY_OUTCOME_APPLIED" | "MEMORY_LOW_RELEVANCE_IGNORED" | "MEMORY_UNTRUSTED_ADVISORY" | "OWNER_POLICY_CONFLICT" | "RISK_LOW" | "RISK_MEDIUM" | "RISK_REVIEW_REQUIRED" | "RAIL_X402_SELECTED" | "RAIL_SHIELDED_SELECTED" | "REQUESTED_AMOUNT_CLAMPED" | "OWNER_REVIEW_APPROVED" | "MEMORY_RELIABILITY_LEARNED" | "MEMORY_SELLER_DEMOTED" | "MEMORY_SPEND_LIMIT_REACHED";
+export type SettlementReasonCode = "MANDATE_DEFAULTS_APPLIED" | "MEMORY_PRIVACY_APPLIED" | "MEMORY_BUDGET_APPLIED" | "MEMORY_OUTCOME_APPLIED" | "MEMORY_LOW_RELEVANCE_IGNORED" | "MEMORY_UNTRUSTED_ADVISORY" | "OWNER_POLICY_CONFLICT" | "RISK_LOW" | "RISK_MEDIUM" | "RISK_REVIEW_REQUIRED" | "RAIL_X402_SELECTED" | "RAIL_SHIELDED_SELECTED" | "REQUESTED_AMOUNT_CLAMPED" | "OWNER_REVIEW_APPROVED" | "MEMORY_RELIABILITY_LEARNED" | "MEMORY_SELLER_DEMOTED" | "MEMORY_SPEND_LIMIT_REACHED" | "MEMORY_PRIVACY_OVERRODE_RAIL";
 export interface SettlementPlanV1 {
     version: typeof SETTLEMENT_PLAN_VERSION;
     planHash: string;
@@ -121,4 +121,6 @@ export interface MemoryInfluence {
     citedBlobIds: string[];
 }
 /** Counterfactual: what the same mandate would have paid without any recalled memory. Not part of the plan hash. */
+/** True when the plan honours the agent's requested rail, or an owner privacy memory rerouted x402 to shielded. */
+export declare function planHonoursRail(plan: Pick<SettlementPlanV1, "rail" | "reasonCodes">, requestedRail?: CapabilityRail): boolean;
 export declare function explainMemoryInfluence(input: PlanningInput, plan: SettlementPlanV1): MemoryInfluence;

package/dist/settlement.js

@@ -117,7 +117,10 @@ export function createSettlementPlan(input) {
         };
         const policies = latest("privacy_rule"), conflict = policies[0]?.provenance === "owner_policy" && new Set(policies.map((item) => item.signal.requiresShielded)).size > 1;
         const requiresShielded = input.mandate.requiredPrivacy === "shielded" || input.privacyHint === "shielded" || policies.some((item) => item.signal.requiresShielded === true);
-        const rails = manifest.supportedRails.filter((rail) => (!input.mandate.allowedRails || input.mandate.allowedRails.includes(rail)) && (!requiresShielded || rail === "shielded") && (input.mandate.version !== "supercuts.mandate.v2" || rail !== "x402" || input.mandate.allowPublicX402 === true) && (!input.requestedRail || rail === input.requestedRail));
+        // The owner's remembered privacy rule outranks the agent's x402 request when the seller and mandate allow shielded.
+        const overridesRail = input.requestedRail === "x402" && policies.some((item) => item.provenance === "owner_policy" && item.signal.requiresShielded === true) && !conflict && manifest.supportedRails.includes("shielded") && (!input.mandate.allowedRails || input.mandate.allowedRails.includes("shielded"));
+        const requestedRail = overridesRail ? "shielded" : input.requestedRail;
+        const rails = manifest.supportedRails.filter((rail) => (!input.mandate.allowedRails || input.mandate.allowedRails.includes(rail)) && (!requiresShielded || rail === "shielded") && (input.mandate.version !== "supercuts.mandate.v2" || rail !== "x402" || input.mandate.allowPublicX402 === true) && (!requestedRail || rail === requestedRail));
         if (!rails.length)
             continue;
         const budgetMemories = trusted.filter((item) => item.memory.kind === "budget_limit").map((item) => item.memory);
@@ -137,7 +140,7 @@ export function createSettlementPlan(input) {
         const quality = latest("quality")[0]?.signal.quality ?? 0.5, outcome = card.lastOutcome ?? latest("outcome")[0]?.signal.outcome;
         const risk = conflict || spendLimited || outcome === "unresolved" || reliability < 0.5 ? "review_required" : reliability >= 0.8 ? "low" : "medium";
         for (const rail of rails)
-            candidates.push({ manifest, rail, reliability, quality, maximum, risk, citations, conflict, card, reasons: ["MANDATE_DEFAULTS_APPLIED", ...(policies.length ? ["MEMORY_PRIVACY_APPLIED"] : []), ...(budgetMemories.length ? ["MEMORY_BUDGET_APPLIED"] : []), ...(spendLimited ? ["MEMORY_SPEND_LIMIT_REACHED"] : []), ...(outcome ? ["MEMORY_OUTCOME_APPLIED"] : []), ...(card.observations ? ["MEMORY_RELIABILITY_LEARNED"] : []), ...(citations.some((c) => ["agent_observation", "legacy_untrusted"].includes(c.provenance)) ? ["MEMORY_UNTRUSTED_ADVISORY"] : []), ...(ignored.length ? ["MEMORY_LOW_RELEVANCE_IGNORED"] : [])] });
+            candidates.push({ manifest, rail, reliability, quality, maximum, risk, citations, conflict, card, reasons: ["MANDATE_DEFAULTS_APPLIED", ...(policies.length ? ["MEMORY_PRIVACY_APPLIED"] : []), ...(overridesRail ? ["MEMORY_PRIVACY_OVERRODE_RAIL"] : []), ...(budgetMemories.length ? ["MEMORY_BUDGET_APPLIED"] : []), ...(spendLimited ? ["MEMORY_SPEND_LIMIT_REACHED"] : []), ...(outcome ? ["MEMORY_OUTCOME_APPLIED"] : []), ...(card.observations ? ["MEMORY_RELIABILITY_LEARNED"] : []), ...(citations.some((c) => ["agent_observation", "legacy_untrusted"].includes(c.provenance)) ? ["MEMORY_UNTRUSTED_ADVISORY"] : []), ...(ignored.length ? ["MEMORY_LOW_RELEVANCE_IGNORED"] : [])] });
     }
     candidates.sort((a, b) => Number(a.risk === "review_required") - Number(b.risk === "review_required") || b.reliability - a.reliability || b.quality - a.quality || (a.maximum < b.maximum ? -1 : a.maximum > b.maximum ? 1 : 0) || a.manifest.capabilityId.localeCompare(b.manifest.capabilityId) || (a.rail === b.rail ? 0 : input.mandate.version === "supercuts.mandate.v2" ? a.rail === "shielded" ? -1 : 1 : a.rail === "x402" ? -1 : 1));
     const selected = candidates[0] ?? fail("SETTLEMENT_PLAN_DENIED", "no capability remains within the owner mandate, privacy rules, and price bounds");
@@ -173,6 +176,10 @@ export function validateSettlementPlan(value) {
 }
 const decision = (plan) => ({ sellerId: plan.sellerId, capabilityId: plan.capabilityId, rail: plan.rail, riskLevel: plan.riskLevel, maximumAmount: plan.maximumAmount });
 /** Counterfactual: what the same mandate would have paid without any recalled memory. Not part of the plan hash. */
+/** True when the plan honours the agent's requested rail, or an owner privacy memory rerouted x402 to shielded. */
+export function planHonoursRail(plan, requestedRail) {
+    return !requestedRail || plan.rail === requestedRail || requestedRail === "x402" && plan.rail === "shielded" && plan.reasonCodes.includes("MEMORY_PRIVACY_OVERRODE_RAIL");
+}
 export function explainMemoryInfluence(input, plan) {
     let withoutMemory;
     try {

package/dist/x402-resource-service.js

@@ -64,10 +64,13 @@ export class X402ResourceService {
         return { scheme: "exact", network: this.config.network, amount: this.config.amount, asset: this.config.asset, payTo: this.config.payTo, maxTimeoutSeconds: this.config.maxTimeoutSeconds ?? 300, extra: { requestId: artifact.requestId, operationId: artifact.operationId } };
     }
     resourceUrl(requestId) { return new URL(`${this.#prefix}/${encodeURIComponent(requestId)}`, this.#origin).toString(); }
-    challenge(artifact) {
+    challenge(artifact, renewExpired) {
         // The live Sui exact facilitator requires the x402 nonce to be exactly
         // 32 random bytes (hex encoded), not merely an application nonce.
-        const requirements = this.requirements(artifact), baseHash = requirementsHash(requirements), nonce = this.#ledger.challenge(artifact.requestId, baseHash, () => randomBytes(32).toString("hex"));
+        const requirements = this.requirements(artifact), baseHash = requirementsHash(requirements), timeoutMs = requirements.maxTimeoutSeconds * 1_000;
+        const nonce = renewExpired
+            ? this.#ledger.challenge(artifact.requestId, baseHash, () => randomBytes(32).toString("hex"), timeoutMs)
+            : this.#ledger.getChallenge(artifact.requestId, baseHash)?.nonce ?? fail("X402_CHALLENGE_MISSING", "resource challenge was not persisted");
         const stored = this.#ledger.getChallenge(artifact.requestId, baseHash) ?? fail("X402_CHALLENGE_MISSING", "resource challenge was not persisted");
         const expiresAt = stored.createdAt + requirements.maxTimeoutSeconds * 1_000;
         requirements.extra = { ...requirements.extra, nonce, expiresAt };
@@ -85,14 +88,14 @@ export class X402ResourceService {
             const requestId = decodeURIComponent(url.pathname.slice(prefix.length)), artifact = this.#artifacts.get(requestId);
             if (!artifact)
                 return this.send(response, 404, Buffer.from("Not Found"));
-            const challenge = this.challenge(artifact), requirements = challenge.accepts instanceof Array ? challenge.accepts[0] : fail("X402_STATE_INVALID", "challenge omitted requirements");
             const paymentHeader = Array.isArray(request.headers["payment-signature"]) ? request.headers["payment-signature"][0] : request.headers["payment-signature"];
+            const challenge = this.challenge(artifact, !paymentHeader), requirements = challenge.accepts instanceof Array ? challenge.accepts[0] : fail("X402_STATE_INVALID", "challenge omitted requirements");
             if (!paymentHeader) {
                 await this.persist?.();
                 return this.send(response, 402, Buffer.from("Payment Required"), { "payment-required": encode(challenge) });
             }
             const stored = this.#ledger.getChallenge(artifact.requestId, requirementsHash(this.requirements(artifact))) ?? fail("X402_CHALLENGE_MISSING", "resource challenge was not persisted");
-            if (!this.#ledger.isDeliveryComplete(artifact.requestId) && Date.now() > stored.createdAt + requirements.maxTimeoutSeconds * 1_000)
+            if (!this.#ledger.hasClaim(artifact.requestId) && Date.now() > stored.createdAt + requirements.maxTimeoutSeconds * 1_000)
                 fail("X402_CHALLENGE_EXPIRED", "payment challenge has expired");
             const payload = decode(paymentHeader, "X402_PAYMENT_INVALID"), bindingValue = Array.isArray(request.headers["x-supercuts-binding"]) ? request.headers["x-supercuts-binding"][0] : request.headers["x-supercuts-binding"], binding = decode(bindingValue, "X402_REQUEST_BINDING_INVALID");
             const offered = payload.accepted;

package/dist/x402.d.ts

@@ -29,6 +29,7 @@ export declare function paymentBindingBytes(binding: Omit<PaymentBinding, "payer
 export declare class PaymentConsumptionLedger {
     private readonly store;
     constructor(store: RoleStore);
+    hasClaim(requestId: string): boolean;
     claim(payment: FinalPayment, requestId: string): void;
     recordDelivery(requestId: string, response: Uint8Array): void;
     getDelivery(requestId: string): Buffer | undefined;
@@ -36,7 +37,7 @@ export declare class PaymentConsumptionLedger {
     acquireDelivery(requestId: string, now?: number, leaseMs?: number): boolean;
     releaseDelivery(requestId: string): void;
     completeDelivery(requestId: string, response: Uint8Array): void;
-    challenge(requestId: string, requirementsHashValue: string, createNonce: () => string): string;
+    challenge(requestId: string, requirementsHashValue: string, createNonce: () => string, renewAfterMs?: number, now?: number): string;
     getChallenge(requestId: string, requirementsHashValue: string): {
         nonce: string;
         createdAt: number;

package/dist/x402.js

@@ -19,6 +19,9 @@ export class PaymentConsumptionLedger {
     constructor(store) {
         this.store = store;
     }
+    hasClaim(requestId) {
+        return Boolean(this.store.db.prepare("SELECT 1 FROM deliveries WHERE request_id = ?").get(requestId));
+    }
     claim(payment, requestId) {
         if (!payment.finalized)
             fail("PAYMENT_PENDING", "payment is not finalized");
@@ -85,16 +88,31 @@ export class PaymentConsumptionLedger {
             throw error;
         }
     }
-    challenge(requestId, requirementsHashValue, createNonce) {
-        const existing = this.store.db.prepare("SELECT nonce, requirements_hash FROM x402_challenges WHERE request_id = ?").get(requestId);
-        if (existing) {
-            if (existing.requirements_hash !== requirementsHashValue)
-                fail("X402_REQUEST_CONFLICT", "request identity was reused with different requirements");
-            return existing.nonce;
+    challenge(requestId, requirementsHashValue, createNonce, renewAfterMs, now = Date.now()) {
+        this.store.db.exec("BEGIN IMMEDIATE");
+        try {
+            const existing = this.store.db.prepare("SELECT nonce, requirements_hash, created_at FROM x402_challenges WHERE request_id = ?").get(requestId);
+            if (existing) {
+                if (existing.requirements_hash !== requirementsHashValue)
+                    fail("X402_REQUEST_CONFLICT", "request identity was reused with different requirements");
+                if (renewAfterMs !== undefined && now > existing.created_at + renewAfterMs && !this.hasClaim(requestId)) {
+                    const nonce = createNonce();
+                    this.store.db.prepare("UPDATE x402_challenges SET nonce = ?, created_at = ? WHERE request_id = ?").run(nonce, now, requestId);
+                    this.store.db.exec("COMMIT");
+                    return nonce;
+                }
+                this.store.db.exec("COMMIT");
+                return existing.nonce;
+            }
+            const nonce = createNonce();
+            this.store.db.prepare("INSERT INTO x402_challenges(request_id, nonce, requirements_hash, created_at) VALUES (?, ?, ?, ?)").run(requestId, nonce, requirementsHashValue, now);
+            this.store.db.exec("COMMIT");
+            return nonce;
+        }
+        catch (error) {
+            this.store.db.exec("ROLLBACK");
+            throw error;
         }
-        const nonce = createNonce();
-        this.store.db.prepare("INSERT INTO x402_challenges(request_id, nonce, requirements_hash, created_at) VALUES (?, ?, ?, ?)").run(requestId, nonce, requirementsHashValue, Date.now());
-        return nonce;
     }
     getChallenge(requestId, requirementsHashValue) {
         const row = this.store.db.prepare("SELECT nonce, requirements_hash, created_at FROM x402_challenges WHERE request_id = ?").get(requestId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercuts-walrus/backend",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "exports": {
@@ -44,7 +44,8 @@
     "@mysten/walrus": "1.2.37",
     "ajv": "8.17.1",
     "circomlibjs": "0.1.7",
-    "pg": "^8.23.1"
+    "pg": "^8.23.1",
+    "snarkjs": "0.7.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",