@supercuts-walrus/backend 0.1.2 → 0.1.3

package/dist/phase3.js

@@ -8,9 +8,10 @@ import { DealJournal } from "./deal.js";
 import { LiveRuntime } from "./live-runtime.js";
 import { V2ExitQueue } from "./v2-exits.js";
 import { validateCapabilityManifest } from "./capability.js";
-import { ManualMemory } from "./memwal.js";
+import { ManualMemory, openMemoryText, withMemoryDefaults } from "./memwal.js";
 import { WorkflowMemory } from "./workflow-memory.js";
-import { canonicalJson, createSettlementPlan, settlementMandateHash, settlementPlanHash, validateSettlementMemory, validateSettlementPlan } from "./settlement.js";
+import { buildScorecard } from "./memory-scorecard.js";
+import { canonicalJson, createSettlementPlan, explainMemoryInfluence, isRelevantMemory, settlementMandateHash, settlementPlanHash, validateSettlementMemory, validateSettlementPlan } from "./settlement.js";
 const PACKAGE = "0xf887433ddfd1068f6df3020cd757939b99ceb418f0d8b9924092b01c7aee846e";
 const POOL = "0x873e37b4745316f21a2780893f5fc36f87da559b08923fb4dad6237cd2e95d98";
 const V2_PACKAGE = "0x32d104c1ab422d497df4ae3a6861258694949c86428f886ca338e07bd055cf76";
@@ -56,6 +57,7 @@ function matchesPlannedEndpoint(planned, actual, requestId) {
         return false;
     }
 }
+const memoryQuery = (manifest) => `${manifest.capabilityId} ${manifest.capability} ${manifest.sellerId}`;
 function record(store, scope, id, value) {
     store.db.prepare("INSERT INTO app_records(scope,id,value,updated_at) VALUES(?,?,?,?) ON CONFLICT(scope,id) DO UPDATE SET value=excluded.value,updated_at=excluded.updated_at")
         .run(scope, id, json(value), Date.now());
@@ -118,11 +120,12 @@ export function initialize(home, args) {
     if (liveCredentials?.memory) {
         let memoryConfig;
         try {
-            memoryConfig = JSON.parse(liveCredentials.memory.toString());
+            memoryConfig = withMemoryDefaults(JSON.parse(liveCredentials.memory.toString()), role);
         }
         catch (error) {
-            return fail("LIVE_MEMORY_CONFIG_INVALID", "memory config is not valid JSON", error);
+            return fail("LIVE_MEMORY_CONFIG_INVALID", `memory config is invalid: ${error instanceof TypeError ? error.message : "not valid JSON"}`, error);
         }
+        liveCredentials.memory = Buffer.from(JSON.stringify(memoryConfig));
         let embedding;
         try {
             embedding = new URL(memoryConfig.embeddingApiBase);
@@ -403,9 +406,14 @@ export class Phase3App {
             return { blobId: String(item.blobId), distance: 0, legacy: true };
         });
     }
-    authenticatedMemory(blobId, memory) {
+    /** Trusted provenance needs local authority or this owner's memory-key signature (portable across machines). */
+    authenticatedMemory(blobId, memory, signedByOwner = false) {
         if (memory.provenance !== "owner_policy" && memory.provenance !== "verified_outcome")
             return memory;
+        if (signedByOwner && (memory.provenance !== "verified_outcome" || memory.evidenceHash)) {
+            this.registerMemoryAuthority(blobId, memory);
+            return memory;
+        }
         const authority = this.store.db.prepare("SELECT fact_hash,provenance,evidence_hash FROM memory_authority WHERE blob_id=?").get(blobId);
         if (authority?.fact_hash === hash(canonicalJson(memory)) && authority.provenance === memory.provenance && (memory.provenance !== "verified_outcome" || authority.evidence_hash === memory.evidenceHash))
             return memory;
@@ -456,31 +464,126 @@ export class Phase3App {
             }
             return existing;
         }
-        let recalled = this.recalledMockMemories();
-        if (!this.profile.mock && this.store.getSecret("live:memory-config")) {
-            const encoded = this.store.getSecret("live:memory-config");
-            let config;
+        const manifests = [primary, ...alternatives], recalled = await this.recallSettlementMemories(manifests.map(memoryQuery));
+        const input = { operationId, mandate, manifests, ...(typeof args["requested-amount"] === "string" ? { requestedAmount: args["requested-amount"] } : {}), ...(args["privacy-hint"] === "shielded" ? { privacyHint: "shielded" } : {}), ...(args["requested-rail"] === "x402" || args["requested-rail"] === "shielded" ? { requestedRail: args["requested-rail"] } : {}), recalled, maxMemoryDistance: this.profile.policy.maxMemoryDistance ?? 0.35 };
+        const plan = this.persistPlan(createSettlementPlan(input));
+        if (!get(this.store, "memory-influence", plan.planHash))
+            record(this.store, "memory-influence", plan.planHash, explainMemoryInfluence(input, plan));
+        return plan;
+    }
+    /** Recall settlement memories for several scoped queries; plaintext stays in this process. */
+    async recallSettlementMemories(queries, limit = 20) {
+        const local = this.localVerifiedOutcomes(), merge = (recalled) => [...local, ...recalled.filter((item) => !local.some((other) => other.blobId === item.blobId))]; // the local authoritative copy wins
+        const encoded = this.profile.mock ? undefined : this.store.getSecret("live:memory-config");
+        if (!encoded)
+            return merge(this.recalledMockMemories());
+        let config;
+        try {
+            config = JSON.parse(encoded.toString());
+        }
+        catch (error) {
+            return fail("LIVE_MEMORY_CONFIG_INVALID", "encrypted memory config is invalid", error);
+        }
+        const manual = new ManualMemory(this.store, config), byBlob = new Map();
+        try {
+            for (const query of [...new Set(queries)])
+                for (const item of await manual.recall(query, limit)) {
+                    const prior = byBlob.get(item.blobId);
+                    if (prior && prior.distance <= item.distance)
+                        continue;
+                    let memory;
+                    try {
+                        const opened = openMemoryText(item.text);
+                        validateSettlementMemory(opened.memory);
+                        memory = this.authenticatedMemory(item.blobId, opened.memory, Boolean(opened.signedBy && opened.signedBy === manual.signerAddress));
+                    }
+                    catch { /* malformed or legacy memory remains advisory */ }
+                    byBlob.set(item.blobId, { blobId: item.blobId, distance: item.distance, ...(memory ? { memory } : { legacy: true }) });
+                }
+        }
+        finally {
+            manual.destroy();
+        }
+        return merge([...byBlob.values()]);
+    }
+    /**
+     * Verified outcomes this runtime wrote itself, including ones still queued for Walrus. They are authoritative
+     * for spend and reliability on this machine; semantic recall alone can miss or lag them.
+     */
+    localVerifiedOutcomes() {
+        const rows = this.store.db.prepare("SELECT operation_id,blob_id FROM memory_jobs WHERE operation_id LIKE 'verified:deal:%' OR operation_id LIKE 'verified:deal-failure:%' ORDER BY created_at").all();
+        return rows.flatMap((row) => {
+            const payload = this.store.getSecret(`memory-outbox:${row.operation_id}`);
+            if (!payload)
+                return [];
             try {
-                config = JSON.parse(encoded.toString());
+                const memory = JSON.parse(payload.toString());
+                validateSettlementMemory(memory, "verified_outcome");
+                return [{ blobId: row.blob_id ?? `local:${row.operation_id}`, distance: 0, memory }];
             }
-            catch (error) {
-                return fail("LIVE_MEMORY_CONFIG_INVALID", "encrypted memory config is invalid", error);
+            catch {
+                return [];
             }
-            const manual = new ManualMemory(this.store, config);
+        });
+    }
+    /**
+     * Orders candidate sellers by what Walrus Memory has verified about them, instead of by price alone.
+     * Sellers outside the owner mandate are dropped first so memory can never widen authority.
+     */
+    async rankDealCandidates(operationId, candidates, mandate, request = {}) {
+        const permitted = candidates.filter((item) => mandate.allowedCounterparties.includes(item.sellerId) && (!mandate.allowedCapabilityIds || mandate.allowedCapabilityIds.includes(item.capabilityId)) && (!mandate.allowedCapabilityClasses || mandate.allowedCapabilityClasses.includes(item.capability)));
+        const allowed = permitted.length ? permitted : candidates;
+        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) => {
             try {
-                recalled = (await manual.recall(`${primary.capabilityId} ${primary.capability} ${primary.sellerId}`, 20)).map((item) => { let memory; try {
-                    const value = JSON.parse(item.text);
-                    validateSettlementMemory(value);
-                    memory = this.authenticatedMemory(item.blobId, value);
-                }
-                catch { /* malformed or legacy memory remains advisory */ } return { blobId: item.blobId, distance: item.distance, ...(memory ? { memory } : { legacy: true }) }; });
+                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 } : {}) });
+                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";
             }
-            finally {
-                manual.destroy();
+            catch {
+                return false;
             }
-        }
-        const plan = createSettlementPlan({ operationId, mandate, manifests: [primary, ...alternatives], ...(typeof args["requested-amount"] === "string" ? { requestedAmount: args["requested-amount"] } : {}), ...(args["privacy-hint"] === "shielded" ? { privacyHint: "shielded" } : {}), ...(args["requested-rail"] === "x402" || args["requested-rail"] === "shielded" ? { requestedRail: args["requested-rail"] } : {}), recalled, maxMemoryDistance: this.profile.policy.maxMemoryDistance ?? 0.35 });
-        return this.persistPlan(plan);
+        });
+        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 });
+        return result;
+    }
+    /** Stores the counterfactual (same mandate, no memory, every candidate) next to the binding deal plan. */
+    recordDealMemoryInfluence(dealOperationId, plan, mandate, request = {}) {
+        const ranking = get(this.store, "deal-ranking", dealOperationId);
+        if (!ranking)
+            return undefined;
+        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 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);
+        return value;
+    }
+    memoryInfluence(id) { return get(this.store, "memory-influence", id); }
+    /**
+     * Owner view of what Supercuts has learned: fresh scorecards recalled from Walrus Memory for every seller
+     * it has ranked, plus how often memory changed a payment decision. Counts and blob IDs only, never plaintext.
+     */
+    async memoryInsights() {
+        const rankings = all(this.store, "deal-ranking");
+        const manifests = [...new Map(rankings.flatMap((item) => item.candidates).map((item) => [item.capabilityId, item])).values()];
+        const recalled = manifests.length ? await this.recallSettlementMemories(manifests.map(memoryQuery)) : [], now = Date.now(), maxDistance = this.profile.policy.maxMemoryDistance ?? 0.35;
+        const relevant = recalled.filter((item) => isRelevantMemory(item, maxDistance));
+        const sellers = manifests.map((manifest) => { const card = buildScorecard(relevant, { counterparty: manifest.sellerId, capabilityClass: manifest.capability }, now); return { capabilityId: manifest.capabilityId, capabilityClass: manifest.capability, priceMinimum: manifest.priceBand.minimum, ...card }; }).sort((a, b) => b.reliability - a.reliability || a.capabilityId.localeCompare(b.capabilityId));
+        const influences = this.store.db.prepare("SELECT value FROM app_records WHERE scope='memory-influence' AND id LIKE 'deal:%'").all().map((row) => JSON.parse(row.value));
+        const jobs = this.store.db.prepare("SELECT status, COUNT(*) AS count FROM memory_jobs GROUP BY status").all();
+        const indexed = this.store.db.prepare("SELECT COUNT(*) AS count FROM memory_inventory WHERE deleted=0").get().count;
+        return { version: "supercuts.memory-insights.v1", memories: { byStatus: Object.fromEntries(jobs.map((row) => [row.status, row.count])), indexed, recalled: recalled.length }, decisions: { deals: influences.length, changedSeller: influences.filter((item) => item.changedSeller).length, changedRail: influences.filter((item) => item.changedRail).length, changedRisk: influences.filter((item) => item.changedRisk).length, changedMaximum: influences.filter((item) => item.changedMaximum).length }, sellers };
     }
     typedMemory(args, provenance) {
         const encoded = required(args, "memory");
@@ -545,7 +648,7 @@ export class Phase3App {
             manual.destroy();
         }
     }
-    enqueueVerifiedOutcome(event, operationId, evidence, planHash, fallback) {
+    enqueueVerifiedOutcome(event, operationId, evidence, planHash, fallback, telemetry = {}) {
         const plan = planHash ? this.storedPlan(planHash) : undefined, jobId = `verified:${event}:${operationId}`, evidenceHash = hash(canonicalJson(evidence));
         const prior = this.store.getSecret(`memory-outbox:${jobId}`);
         if (prior) {
@@ -555,7 +658,7 @@ export class Phase3App {
                 fail("MEMORY_OPERATION_CONFLICT", "verified outcome ID identifies different evidence or scope");
             return;
         }
-        const memory = { version: "supercuts.settlement-memory.v1", kind: "outcome", provenance: "verified_outcome", scope: { ...(plan ? { capabilityId: plan.capabilityId, capabilityClass: plan.capabilityClass, counterparty: plan.sellerId, network: plan.network, asset: plan.asset } : { ...(fallback?.counterparty ? { counterparty: fallback.counterparty } : {}), ...(fallback?.asset ? { asset: fallback.asset } : {}), network: "sui:testnet" }) }, createdAt: Date.now(), evidenceHash, signal: { outcome: String(evidence.status ?? "") === "unresolved" ? "unresolved" : String(evidence.status ?? "") === "failed" ? "failed" : "succeeded" } };
+        const memory = { version: "supercuts.settlement-memory.v1", kind: "outcome", provenance: "verified_outcome", scope: { ...(plan ? { capabilityId: plan.capabilityId, capabilityClass: plan.capabilityClass, counterparty: plan.sellerId, network: plan.network, asset: plan.asset } : { ...(fallback?.counterparty ? { counterparty: fallback.counterparty } : {}), ...(fallback?.asset ? { asset: fallback.asset } : {}), network: "sui:testnet" }) }, createdAt: Date.now(), evidenceHash, signal: { outcome: String(evidence.status ?? "") === "unresolved" ? "unresolved" : String(evidence.status ?? "") === "failed" ? "failed" : "succeeded", ...telemetry } };
         validateSettlementMemory(memory, "verified_outcome");
         const factHash = hash(canonicalJson(memory));
         if (this.profile.mock) {
@@ -567,11 +670,21 @@ export class Phase3App {
         this.store.putSecretOnce(`memory-outbox:${jobId}`, Buffer.from(canonicalJson(memory)));
         this.store.db.prepare("INSERT OR IGNORE INTO memory_jobs(operation_id,kind,fact_hash,blob_id,status,created_at) VALUES(?,?,?,NULL,'pending',?)").run(jobId, memory.kind, factHash, Date.now());
     }
+    /** Queues a verified seller fault as a Walrus outcome memory so later discovery demotes that seller. */
+    recordVerifiedDealFailure(operationId, planHash, fault) {
+        if (this.profile.mock || this.profile.role !== "buyer")
+            fail("DEAL_LIVE_REQUIRED", "verified deal failures require a live buyer role");
+        if (this.store.getSecret(`memory-outbox:verified:deal-failure:${operationId}`))
+            return;
+        const plan = this.storedPlan(planHash);
+        this.enqueueVerifiedOutcome("deal-failure", operationId, { status: "failed", stage: fault.stage, code: fault.code, ...(fault.paymentDigest ? { paymentDigest: fault.paymentDigest } : {}) }, planHash, undefined, { rail: plan.rail, ...(fault.paymentDigest ? { amount: plan.openingAmount } : {}) });
+    }
     recordVerifiedDealOutcome(operationId, planHash, paymentDigest, artifactSha256) {
         if (this.profile.mock || this.profile.role !== "buyer")
             fail("DEAL_LIVE_REQUIRED", "verified deal outcome requires a live buyer role");
         const jobId = `verified:deal:${operationId}`;
-        this.enqueueVerifiedOutcome("deal", operationId, { status: "succeeded", paymentDigest, artifactSha256 }, planHash);
+        const plan = this.storedPlan(planHash), timings = this.store.db.prepare("SELECT COALESCE(SUM(duration_ms),0) AS total FROM deal_timings WHERE operation_id=? AND stage IN ('negotiation','payment','delivery')").get(operationId);
+        this.enqueueVerifiedOutcome("deal", operationId, { status: "succeeded", paymentDigest, artifactSha256 }, planHash, undefined, { amount: plan.openingAmount, rail: plan.rail, ...(Number.isSafeInteger(timings.total) && timings.total > 0 ? { latencyMs: timings.total } : {}) });
         const payload = this.store.getSecret(`memory-outbox:${jobId}`) ?? fail("DEAL_MEMORY_INVALID", "verified outcome payload is missing");
         return { payloadHash: hash(payload), queued: true };
     }
@@ -645,7 +758,7 @@ export class Phase3App {
             const query = [memory.scope.capabilityId, memory.scope.counterparty, memory.signal.outcome].filter(Boolean).join(" ");
             const recalled = await manual.recall(query, 100);
             blobId = recalled.find((item) => { try {
-                return canonicalJson(JSON.parse(item.text)) === canonicalJson(memory);
+                return canonicalJson(openMemoryText(item.text).memory) === canonicalJson(memory);
             }
             catch {
                 return false;
@@ -945,9 +1058,9 @@ export class Phase3App {
             if (command === "memory.recall") {
                 const recalled = await manual.recall(required(args, "query"));
                 const citations = recalled.filter((item) => item.distance <= (this.profile.policy.maxMemoryDistance ?? 0.35)).map((item) => { try {
-                    const memory = JSON.parse(item.text);
+                    const opened = openMemoryText(item.text), memory = opened.memory;
                     validateSettlementMemory(memory);
-                    const trusted = this.authenticatedMemory(item.blobId, memory);
+                    const trusted = this.authenticatedMemory(item.blobId, memory, Boolean(opened.signedBy && opened.signedBy === manual.signerAddress));
                     return { blobId: item.blobId, kind: trusted.kind, provenance: trusted.provenance, distance: item.distance };
                 }
                 catch {

package/dist/seam.js

@@ -112,6 +112,7 @@ process.stdin.on("end", async () => {
     catch (error) {
         const shaped = errorOutput(error);
         const code = String(shaped.error.code ?? "INTERNAL_ERROR");
-        return write(envelope(request.requestId, { ok: false, error: { ...shaped.error, retryable: ["DELIVERY_IN_PROGRESS", "MEMORY_JOB_PENDING", "TATUM_TIMEOUT"].includes(code) } }), 1);
+        const retryable = ["DELIVERY_IN_PROGRESS", "MEMORY_JOB_PENDING", "TATUM_TIMEOUT", "X402_FACILITATOR_UNAVAILABLE"].includes(code);
+        return write(envelope(request.requestId, { ok: false, error: { ...shaped.error, retryable, ...(retryable ? { recovery: "transient: retry or resume later with the same operation ID; never start a second payment", retryWithSameOperationId: true } : {}) } }), 1);
     }
 });

package/dist/seller-service.js

@@ -17,6 +17,7 @@ import { captureSellerHome, decryptSellerSnapshot, encryptSellerSnapshot, restor
 import { X402ResourceService } from "./x402-resource-service.js";
 import { LiveSellerTransport } from "./live-seller-transport.js";
 import { registerDirectoryCapability } from "./seller-directory.js";
+import { isMainModule } from "./main-module.js";
 const isV2 = (row) => row.preview.genericV2 === true;
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 const validId = (value, name) => typeof value === "string" && /^[a-zA-Z0-9._:-]{1,128}$/.test(value) ? value : fail("SELLER_REQUEST_INVALID", `${name} is invalid`);
@@ -399,7 +400,7 @@ export class SellerService {
     close() { for (const slot of this.#slots.values())
         slot.app.close(); rmSync(this.#root, { recursive: true, force: true }); }
 }
-if (process.argv[1] && import.meta.url.endsWith(process.argv[1])) {
+if (isMainModule(import.meta.url)) {
     const required = (key) => process.env[key] ?? fail("SELLER_CONFIG_MISSING", `${key} is required`);
     const port = Number(process.env.PORT ?? "3000");
     const origin = required("SELLER_ORIGIN");

package/dist/seller-setup.js

@@ -5,13 +5,14 @@ import { createInterface } from "node:readline/promises";
 import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
 import { fail } from "./errors.js";
+import { TESTNET_DEFAULTS, withTestnetDefaults } from "./testnet-defaults.js";
 import { initialize } from "./phase3.js";
 function ownerFile(path) {
     if ((statSync(path).mode & 0o077) !== 0)
         fail("SETUP_PERMISSIONS", `${path} must be owner-only`);
 }
 function validateConfig(config) {
-    config.deploymentConfig ||= join(dirname(fileURLToPath(import.meta.url)), "../config/phase1.testnet.json");
+    withTestnetDefaults(config);
     for (const key of ["deploymentConfig", "tatumKeyFile", "writeGrpc", "tatumGrpc", "walrusPublisher", "walrusAggregator"]) {
         if (typeof config[key] !== "string" || !config[key])
             fail("SETUP_INVALID", `${key} is required`);
@@ -81,14 +82,15 @@ export async function promptSellerSetup(home) {
         fail("SETUP_INPUT_REQUIRED", "interactive seller setup requires a terminal; use --config with an owner-only JSON file");
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     try {
-        const ask = async (label) => (await rl.question(`${label}: `)).trim();
+        const ask = async (label, fallback) => (await rl.question(fallback ? `${label} [${fallback}]: ` : `${label}: `)).trim() || fallback || "";
+        process.stderr.write("Press Enter to accept a bracketed default. Credentials are read from owner-only files, never typed here.\n");
         const config = {
             deploymentConfig: await ask("Pinned v2 Testnet deployment config path (blank for bundled config)"),
-            tatumKeyFile: await ask("Owner-only Tatum key file path"),
-            writeGrpc: await ask("Sui write gRPC URL"),
-            tatumGrpc: await ask("Tatum read gRPC URL"),
-            walrusPublisher: await ask("Walrus publisher URL"),
-            walrusAggregator: await ask("Walrus aggregator URL"),
+            tatumKeyFile: await ask("Owner-only Tatum API key file path"),
+            writeGrpc: await ask("Sui write gRPC URL", TESTNET_DEFAULTS.writeGrpc),
+            tatumGrpc: await ask("Tatum read gRPC URL", TESTNET_DEFAULTS.tatumGrpc),
+            walrusPublisher: await ask("Walrus publisher URL", TESTNET_DEFAULTS.walrusPublisher),
+            walrusAggregator: await ask("Walrus aggregator URL", TESTNET_DEFAULTS.walrusAggregator),
         };
         const snarkjs = await ask("SnarkJS executable path (blank for deployment-relative default)");
         const converter = await ask("Groth16 converter path (blank for deployment-relative default)");

package/dist/settlement.d.ts

@@ -25,6 +25,10 @@ export interface SettlementMemoryV1 {
         reliability?: number;
         quality?: number;
         outcome?: "succeeded" | "failed" | "unresolved";
+        amount?: string;
+        latencyMs?: number;
+        rail?: CapabilityRail;
+        periodMs?: number;
     };
 }
 export interface SettlementCitation {
@@ -33,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";
+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 interface SettlementPlanV1 {
     version: typeof SETTLEMENT_PLAN_VERSION;
     planHash: string;
@@ -81,7 +85,7 @@ export declare function canonicalJson(value: unknown): string;
 export declare const settlementMandateHash: (mandate: PlanningMandate) => string;
 export declare function settlementPlanHash(plan: Omit<SettlementPlanV1, "planHash">): string;
 export declare function validateSettlementMemory(value: unknown, assignedProvenance?: SettlementMemoryProvenance): asserts value is SettlementMemoryV1;
-export declare function createSettlementPlan(input: {
+export interface PlanningInput {
     operationId: string;
     mandate: PlanningMandate;
     manifests: CapabilityManifest[];
@@ -91,5 +95,30 @@ export declare function createSettlementPlan(input: {
     recalled?: RecalledSettlementMemory[];
     maxMemoryDistance?: number;
     now?: number;
-}): SettlementPlanV1;
+}
+/**
+ * Trusted typed memories (owner policy or verified outcome) are matched by their structured scope, so a
+ * semantic distance cutoff would only drop real evidence: embeddings of JSON records rank far from scope
+ * queries. Advisory and legacy text still needs semantic relevance.
+ */
+export declare function isRelevantMemory(item: RecalledSettlementMemory, maxDistance: number): boolean;
+export declare function createSettlementPlan(input: PlanningInput): SettlementPlanV1;
 export declare function validateSettlementPlan(value: unknown): asserts value is SettlementPlanV1;
+export interface MemoryDecision {
+    sellerId: string;
+    capabilityId: string;
+    rail: CapabilityRail;
+    riskLevel: SettlementRisk;
+    maximumAmount: string;
+}
+export interface MemoryInfluence {
+    changedSeller: boolean;
+    changedRail: boolean;
+    changedRisk: boolean;
+    changedMaximum: boolean;
+    withoutMemory?: MemoryDecision;
+    withMemory: MemoryDecision;
+    citedBlobIds: string[];
+}
+/** Counterfactual: what the same mandate would have paid without any recalled memory. Not part of the plan hash. */
+export declare function explainMemoryInfluence(input: PlanningInput, plan: SettlementPlanV1): MemoryInfluence;

package/dist/settlement.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { fail } from "./errors.js";
+import { buildScorecard, spentSince } from "./memory-scorecard.js";
 export const SETTLEMENT_PLAN_VERSION = "supercuts.settlement-plan.v1";
 export const SETTLEMENT_MEMORY_VERSION = "supercuts.settlement-memory.v1";
 export function canonicalJson(value) {
@@ -38,7 +39,7 @@ export function validateSettlementMemory(value, assignedProvenance) {
         fail("SETTLEMENT_MEMORY_INVALID", "memory observation must be a short non-empty string");
     const scope = raw.scope, signal = raw.signal;
     exactKeys(scope, ["counterparty", "capabilityId", "capabilityClass", "network", "asset"]);
-    exactKeys(signal, ["requiresShielded", "maximumAmount", "reliability", "quality", "outcome"]);
+    exactKeys(signal, ["requiresShielded", "maximumAmount", "reliability", "quality", "outcome", "amount", "latencyMs", "rail", "periodMs"]);
     for (const item of Object.values(scope))
         if (typeof item !== "string" || !item || item.length > 1024)
             fail("SETTLEMENT_MEMORY_INVALID", "memory scope fields must be non-empty strings");
@@ -51,6 +52,13 @@ export function validateSettlementMemory(value, assignedProvenance) {
             fail("SETTLEMENT_MEMORY_INVALID", "memory scores must be finite values in [0,1]");
     if (signal.outcome !== undefined && !["succeeded", "failed", "unresolved"].includes(signal.outcome))
         fail("SETTLEMENT_MEMORY_INVALID", "memory outcome is invalid");
+    if (signal.amount !== undefined && !unsigned(signal.amount) || signal.rail !== undefined && !["x402", "shielded"].includes(signal.rail))
+        fail("SETTLEMENT_MEMORY_INVALID", "memory payment amount or rail is invalid");
+    for (const value of [signal.latencyMs, signal.periodMs])
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+            fail("SETTLEMENT_MEMORY_INVALID", "memory durations must be non-negative integers");
+    if (signal.periodMs !== undefined && (raw.kind !== "budget_limit" || signal.periodMs === 0))
+        fail("SETTLEMENT_MEMORY_INVALID", "only budget limits may declare a positive period");
     const required = { privacy_rule: "requiresShielded", budget_limit: "maximumAmount", reliability: "reliability", quality: "quality", outcome: "outcome" };
     if (signal[required[raw.kind]] === undefined)
         fail("SETTLEMENT_MEMORY_INVALID", "memory kind does not have its required signal");
@@ -64,6 +72,18 @@ function specificity(scope, manifest) {
         return -1;
     return scope.capabilityId ? 4 : scope.capabilityClass ? 3 : scope.counterparty ? 2 : 1;
 }
+/**
+ * Trusted typed memories (owner policy or verified outcome) are matched by their structured scope, so a
+ * semantic distance cutoff would only drop real evidence: embeddings of JSON records rank far from scope
+ * queries. Advisory and legacy text still needs semantic relevance.
+ */
+export function isRelevantMemory(item, maxDistance) {
+    if (!Number.isFinite(item.distance) || item.distance < 0)
+        return false;
+    if (item.memory && (item.memory.provenance === "owner_policy" || item.memory.provenance === "verified_outcome"))
+        return true;
+    return item.distance <= maxDistance;
+}
 export function createSettlementPlan(input) {
     const now = input.now ?? Date.now(), maxDistance = input.maxMemoryDistance ?? 0.35;
     if (!input.operationId || input.operationId.length > 256 || !input.manifests.length)
@@ -72,8 +92,9 @@ export function createSettlementPlan(input) {
         fail("SETTLEMENT_PLAN_INVALID", "requestedAmount must be canonical unsigned base units");
     if (!Number.isFinite(maxDistance) || maxDistance < 0 || maxDistance > 1 || now >= input.mandate.expiresAt)
         fail("SETTLEMENT_PLAN_DENIED", "planning limits or owner mandate are invalid");
-    const ignored = (input.recalled ?? []).filter((item) => !Number.isFinite(item.distance) || item.distance < 0 || item.distance > maxDistance);
-    const recalled = (input.recalled ?? []).filter((item) => Number.isFinite(item.distance) && item.distance >= 0 && item.distance <= maxDistance);
+    const relevant = (item) => isRelevantMemory(item, maxDistance);
+    const ignored = (input.recalled ?? []).filter((item) => !relevant(item));
+    const recalled = (input.recalled ?? []).filter(relevant);
     for (const item of recalled)
         if (item.memory)
             validateSettlementMemory(item.memory);
@@ -99,19 +120,30 @@ export function createSettlementPlan(input) {
         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));
         if (!rails.length)
             continue;
-        const budgets = trusted.filter((item) => item.memory.kind === "budget_limit").map((item) => BigInt(item.memory.signal.maximumAmount));
-        const maximum = [BigInt(manifest.priceBand.maximum), BigInt(input.mandate.perDealCeiling), ...budgets].reduce((a, b) => a < b ? a : b);
-        if (maximum < BigInt(manifest.priceBand.minimum))
+        const budgetMemories = trusted.filter((item) => item.memory.kind === "budget_limit").map((item) => item.memory);
+        const budgets = budgetMemories.filter((item) => item.signal.periodMs === undefined).map((item) => BigInt(item.signal.maximumAmount));
+        // Periodic owner budgets subtract the verified spend that Walrus Memory remembers for the same scope.
+        const remaining = budgetMemories.filter((item) => item.signal.periodMs !== undefined).map((item) => { const limit = BigInt(item.signal.maximumAmount), spent = spentSince(recalled, item.scope, now - item.signal.periodMs); return limit > spent ? limit - spent : 0n; });
+        const minimumPrice = BigInt(manifest.priceBand.minimum);
+        let maximum = [BigInt(manifest.priceBand.maximum), BigInt(input.mandate.perDealCeiling), ...budgets, ...remaining].reduce((a, b) => a < b ? a : b);
+        const spendLimited = maximum < minimumPrice && remaining.some((value) => value < minimumPrice) && [BigInt(manifest.priceBand.maximum), BigInt(input.mandate.perDealCeiling), ...budgets].every((value) => value >= minimumPrice);
+        if (maximum < minimumPrice && !spendLimited)
             continue;
-        const reliability = latest("reliability")[0]?.signal.reliability ?? 0.5, quality = latest("quality")[0]?.signal.quality ?? 0.5, outcome = latest("outcome")[0]?.signal.outcome;
-        const risk = conflict || outcome === "failed" || outcome === "unresolved" || reliability < 0.5 ? "review_required" : reliability >= 0.8 ? "low" : "medium";
+        if (spendLimited)
+            maximum = minimumPrice;
+        const card = buildScorecard(recalled, { counterparty: manifest.sellerId, capabilityClass: manifest.capability }, now);
+        const explicit = latest("reliability")[0];
+        const reliability = explicit?.provenance === "owner_policy" ? explicit.signal.reliability : card.observations ? card.reliability : explicit?.signal.reliability ?? 0.5;
+        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, reasons: ["MANDATE_DEFAULTS_APPLIED", ...(policies.length ? ["MEMORY_PRIVACY_APPLIED"] : []), ...(budgets.length ? ["MEMORY_BUDGET_APPLIED"] : []), ...(outcome ? ["MEMORY_OUTCOME_APPLIED"] : []), ...(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"] : []), ...(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) => 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));
+    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");
     const minimum = BigInt(selected.manifest.priceBand.minimum), desired = input.requestedAmount === undefined ? minimum : BigInt(input.requestedAmount), opening = desired < minimum ? minimum : desired > selected.maximum ? selected.maximum : desired;
-    const reasons = [...selected.reasons, ...(selected.conflict ? ["OWNER_POLICY_CONFLICT"] : []), ...(opening !== desired ? ["REQUESTED_AMOUNT_CLAMPED"] : []), selected.rail === "shielded" ? "RAIL_SHIELDED_SELECTED" : "RAIL_X402_SELECTED", selected.risk === "low" ? "RISK_LOW" : selected.risk === "medium" ? "RISK_MEDIUM" : "RISK_REVIEW_REQUIRED"];
+    const demoted = candidates.some((item) => item.manifest.sellerId !== selected.manifest.sellerId && item.card.observations > 0 && item.reliability < selected.reliability);
+    const reasons = [...selected.reasons, ...(demoted ? ["MEMORY_SELLER_DEMOTED"] : []), ...(selected.conflict ? ["OWNER_POLICY_CONFLICT"] : []), ...(opening !== desired ? ["REQUESTED_AMOUNT_CLAMPED"] : []), selected.rail === "shielded" ? "RAIL_SHIELDED_SELECTED" : "RAIL_X402_SELECTED", selected.risk === "low" ? "RISK_LOW" : selected.risk === "medium" ? "RISK_MEDIUM" : "RISK_REVIEW_REQUIRED"];
     const withoutHash = { version: SETTLEMENT_PLAN_VERSION, operationId: input.operationId, status: selected.risk === "review_required" ? "review_required" : "approved", mandateHash: settlementMandateHash(input.mandate), manifestHash: selected.manifest.manifestHash, capabilityId: selected.manifest.capabilityId, capabilityClass: selected.manifest.capability, sellerId: selected.manifest.sellerId, endpoint: selected.manifest.endpoint, network: "sui:testnet", asset: selected.manifest.asset, rail: selected.rail, openingAmount: opening.toString(), maximumAmount: selected.maximum.toString(), manifestMinimum: selected.manifest.priceBand.minimum, manifestMaximum: selected.manifest.priceBand.maximum, riskLevel: selected.risk, createdAt: now, expiresAt: Math.min(now + 300_000, input.mandate.expiresAt, selected.manifest.expiresAt), citations: selected.citations.sort((a, b) => a.blobId.localeCompare(b.blobId)), reasonCodes: [...new Set(reasons)] };
     return { ...withoutHash, planHash: settlementPlanHash(withoutHash) };
 }
@@ -139,3 +171,16 @@ export function validateSettlementPlan(value) {
     if (!Array.isArray(plan.reasonCodes) || !Array.isArray(plan.citations) || plan.citations.some((citation) => !object(citation) || Object.keys(citation).some((key) => !["blobId", "kind", "provenance", "distance"].includes(key)) || typeof citation.blobId !== "string" || !citation.blobId || typeof citation.distance !== "number" || !Number.isFinite(citation.distance) || citation.distance < 0 || citation.distance > 1))
         fail("SETTLEMENT_PLAN_INVALID", "settlement plan citations or reasons are invalid");
 }
+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. */
+export function explainMemoryInfluence(input, plan) {
+    let withoutMemory;
+    try {
+        withoutMemory = decision(createSettlementPlan({ ...input, recalled: [], now: plan.createdAt }));
+    }
+    catch {
+        withoutMemory = undefined;
+    }
+    const withMemory = decision(plan);
+    return { changedSeller: withoutMemory?.sellerId !== withMemory.sellerId, changedRail: withoutMemory?.rail !== withMemory.rail, changedRisk: withoutMemory?.riskLevel !== withMemory.riskLevel, changedMaximum: withoutMemory?.maximumAmount !== withMemory.maximumAmount, ...(withoutMemory ? { withoutMemory } : {}), withMemory, citedBlobIds: plan.citations.map((item) => item.blobId) };
+}

package/dist/testnet-defaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Public Sui Testnet, Walrus Testnet, and hosted Supercuts endpoints used when an owner leaves a setup field blank.
+ * None of these values are credentials; owners can still override every one in setup JSON or the prompts.
+ */
+export declare const TESTNET_DEFAULTS: {
+    readonly writeGrpc: "https://fullnode.testnet.sui.io:443";
+    readonly tatumGrpc: "https://sui-testnet-grpc.gateway.tatum.io:443";
+    readonly walrusPublisher: "https://publisher.walrus-testnet.walrus.space";
+    readonly walrusAggregator: "https://aggregator.walrus-testnet.walrus.space";
+    readonly directoryUrl: "https://supercuts-sellers-testnet.onrender.com";
+};
+/** Pinned experimental v2 Testnet deployment metadata shipped inside the npm package. */
+export declare function bundledDeploymentConfig(): string;
+/** Fills blank endpoint fields with the public Testnet defaults. */
+export declare function withTestnetDefaults<T extends {
+    deploymentConfig?: string;
+    writeGrpc?: string;
+    tatumGrpc?: string;
+    walrusPublisher?: string;
+    walrusAggregator?: string;
+}>(config: T): T;

package/dist/testnet-defaults.js

@@ -0,0 +1,26 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Public Sui Testnet, Walrus Testnet, and hosted Supercuts endpoints used when an owner leaves a setup field blank.
+ * None of these values are credentials; owners can still override every one in setup JSON or the prompts.
+ */
+export const TESTNET_DEFAULTS = {
+    writeGrpc: "https://fullnode.testnet.sui.io:443",
+    tatumGrpc: "https://sui-testnet-grpc.gateway.tatum.io:443",
+    walrusPublisher: "https://publisher.walrus-testnet.walrus.space",
+    walrusAggregator: "https://aggregator.walrus-testnet.walrus.space",
+    directoryUrl: "https://supercuts-sellers-testnet.onrender.com",
+};
+/** Pinned experimental v2 Testnet deployment metadata shipped inside the npm package. */
+export function bundledDeploymentConfig() {
+    return join(dirname(fileURLToPath(import.meta.url)), "../config/phase1.testnet.json");
+}
+/** Fills blank endpoint fields with the public Testnet defaults. */
+export function withTestnetDefaults(config) {
+    config.deploymentConfig ||= bundledDeploymentConfig();
+    config.writeGrpc ||= TESTNET_DEFAULTS.writeGrpc;
+    config.tatumGrpc ||= TESTNET_DEFAULTS.tatumGrpc;
+    config.walrusPublisher ||= TESTNET_DEFAULTS.walrusPublisher;
+    config.walrusAggregator ||= TESTNET_DEFAULTS.walrusAggregator;
+    return config;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercuts-walrus/backend",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "exports": {
@@ -25,7 +25,8 @@
     "supercuts-seller-v2-provision": "dist/seller-v2-provision.js",
     "supercuts-hosted-exit": "dist/hosted-exit-cli.js",
     "supercuts-hosted-seller-import": "dist/hosted-seller-import.js",
-    "supercuts-seller-directory": "dist/seller-directory-cli.js"
+    "supercuts-seller-directory": "dist/seller-directory-cli.js",
+    "supercuts-embedding-adapter": "dist/embedding-adapter.js"
   },
   "files": [
     "dist",