@supercuts-walrus/backend 0.1.1 → 0.1.3

package/dist/memwal.js

@@ -1,13 +1,91 @@
+import { createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
 import { MemWalManual } from "@mysten-incubation/memwal/manual";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519PublicKey } from "@mysten/sui/keypairs/ed25519";
 import { MemWal } from "@mysten-incubation/memwal";
 import { validateMemoryFact } from "./memory.js";
-import { SETTLEMENT_MEMORY_VERSION, validateSettlementMemory } from "./settlement.js";
+import { canonicalJson, SETTLEMENT_MEMORY_VERSION, validateSettlementMemory } from "./settlement.js";
+export const SIGNED_MEMORY_FORMAT = "supercuts.signed-memory.v1";
+const PKCS8_ED25519 = Buffer.from("302e020100300506032b657004220420", "hex"), SPKI_ED25519 = Buffer.from("302a300506032b6570032100", "hex");
+const memoryMessage = (memory) => Buffer.from(`supercuts-memory-v1\n${canonicalJson(memory)}`);
+function memorySeed(secret) {
+    const decoded = decodeSuiPrivateKey(secret);
+    if (decoded.scheme !== "ED25519")
+        throw new TypeError("memory signing requires an ED25519 key");
+    return Buffer.from(decoded.secretKey);
+}
+function memoryPublicKey(secret) {
+    return Buffer.from(createPublicKey(createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, memorySeed(secret)]), format: "der", type: "pkcs8" })).export({ format: "der", type: "spki" })).subarray(SPKI_ED25519.length);
+}
+/** Sui address that signs this owner's trusted memories; derived from the owner-only memory key. */
+export function memorySignerAddress(secret) { return new Ed25519PublicKey(memoryPublicKey(secret)).toSuiAddress(); }
+/** Plain-language line placed before the JSON so embeddings rank the record near scope queries. Not signed. */
+export function describeMemory(memory) {
+    const scope = [memory.scope.capabilityId, memory.scope.capabilityClass, memory.scope.counterparty ? `seller ${memory.scope.counterparty}` : undefined].filter(Boolean).join(" ");
+    const signal = memory.signal;
+    const fact = memory.kind === "outcome" ? `deal ${signal.outcome ?? "recorded"}${signal.rail ? ` via ${signal.rail}` : ""}${signal.amount ? ` for ${signal.amount} MIST` : ""}${signal.latencyMs !== undefined ? ` in ${Math.round(signal.latencyMs / 1000)}s` : ""}`
+        : memory.kind === "privacy_rule" ? (signal.requiresShielded ? "owner requires shielded settlement" : "owner allows public settlement")
+            : memory.kind === "budget_limit" ? `owner budget limit ${signal.maximumAmount} MIST${signal.periodMs ? ` per ${Math.round(signal.periodMs / 3_600_000)}h` : " per deal"}`
+                : `${memory.kind} ${signal.reliability ?? signal.quality ?? ""}`.trim();
+    return `Supercuts ${memory.provenance.replace("_", " ")}: ${fact}${scope ? ` for ${scope}` : ""}.`;
+}
+/** Wraps a trusted memory in a signed envelope so its authority survives a move to another machine. */
+export function sealMemoryText(memory, secret) {
+    const key = createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, memorySeed(secret)]), format: "der", type: "pkcs8" });
+    return JSON.stringify({ format: SIGNED_MEMORY_FORMAT, summary: describeMemory(memory), memory, publicKey: memoryPublicKey(secret).toString("base64"), signature: edSign(null, memoryMessage(memory), key).toString("base64") });
+}
+/** Opens recalled memory text. `signedBy` is set only when the envelope signature verifies. */
+export function openMemoryText(text) {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== "object" || value.format !== SIGNED_MEMORY_FORMAT)
+        return { memory: value };
+    try {
+        const raw = Buffer.from(String(value.publicKey), "base64");
+        if (raw.length !== 32)
+            return { memory: value.memory };
+        const key = createPublicKey({ key: Buffer.concat([SPKI_ED25519, raw]), format: "der", type: "spki" });
+        return edVerify(null, memoryMessage(value.memory), key, Buffer.from(String(value.signature), "base64")) ? { memory: value.memory, signedBy: new Ed25519PublicKey(raw).toSuiAddress() } : { memory: value.memory };
+    }
+    catch {
+        return { memory: value.memory };
+    }
+}
+/** Public Walrus Mainnet Memory and local-adapter values; owners only need to supply their own account secrets. */
+export const MEMORY_MAINNET_DEFAULTS = {
+    serverUrl: "https://relayer.memory.walrus.xyz",
+    packageId: "0xe7c16fbea0560e7057e2bf7422feaa4fb313749fc69c9e9092fac7a33b81d7f5",
+    registryId: "0x8bf82c9e09e36b8d1c38298f68b7cb68e7b8762887e7592add9986d5e9cf199f",
+    embeddingApiKey: "local-adapter",
+    embeddingApiBase: "http://127.0.0.1:8787/v1",
+    embeddingModel: "embeddinggemma-1536",
+    walrusAggregatorUrl: "https://aggregator.walrus-mainnet.walrus.space",
+    walrusPublisherUrl: "https://publisher.walrus-testnet.walrus.space",
+};
+/** Completes an owner memory config: `key`, `accountId`, and `suiPrivateKey` are required; the rest default. */
+export function withMemoryDefaults(raw, role) {
+    for (const field of ["key", "accountId", "suiPrivateKey"])
+        if (typeof raw[field] !== "string" || !raw[field])
+            throw new TypeError(`memory config requires ${field}`);
+    return { ...MEMORY_MAINNET_DEFAULTS, namespace: `supercuts:${role}`, ...Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== undefined && value !== "")) };
+}
 /** Client-managed memory facade; plaintext never crosses the relayer boundary. */
 export class ManualMemory {
     store;
     client;
+    signingKey;
+    /** Address whose signature marks a recalled memory as this owner's own trusted record. */
+    signerAddress;
     constructor(store, config) {
         this.store = store;
+        try {
+            this.signingKey = config.suiPrivateKey;
+            this.signerAddress = memorySignerAddress(config.suiPrivateKey);
+        }
+        catch {
+            this.signingKey = undefined;
+            this.signerAddress = undefined;
+            process.stderr.write("MEMORY_SIGNING_UNAVAILABLE: trusted memories will rely on local authority only\n");
+        }
         let embedding;
         try {
             embedding = new URL(config.embeddingApiBase);
@@ -24,7 +102,8 @@ export class ManualMemory {
             validateSettlementMemory(fact);
         else
             validateMemoryFact(fact);
-        const text = JSON.stringify(fact);
+        const trusted = fact.version === SETTLEMENT_MEMORY_VERSION && ["owner_policy", "verified_outcome"].includes(fact.provenance);
+        const text = trusted && this.signingKey ? sealMemoryText(fact, this.signingKey) : JSON.stringify(fact);
         const result = await this.client.rememberManual(text);
         this.store.putSecret(`memory:${result.blob_id}`, Buffer.from(text));
         return result.blob_id;

package/dist/onboarding-doctor.js

@@ -19,10 +19,11 @@ export async function onboardingDoctor(home, sellerConfig) {
     try {
         if (app.profile.mock)
             fail("LIVE_PROFILE_REQUIRED", "onboarding doctor requires a live Testnet role home");
-        const runtime = await app.execute("doctor", {});
-        if (runtime.data.readyForDemo === false)
-            fail("ONBOARDING_RUNTIME_NOT_READY", "live runtime doctor reports missing prerequisites");
         if (app.profile.role === "buyer") {
+            const runtime = await app.execute("doctor", {});
+            if (runtime.data.publicFixes?.length)
+                fail("ONBOARDING_RUNTIME_NOT_READY", `live runtime doctor reports missing prerequisites: ${runtime.data.publicFixes.join(" ")}`);
+            const shieldedProofsReady = runtime.data.shieldedProofs === "ready";
             const mandate = loadMandate(home);
             if (mandate.version !== "supercuts.mandate.v2")
                 fail("DEAL_MANDATE_VERSION", "buyer needs a v2 standing mandate");
@@ -48,13 +49,14 @@ export async function onboardingDoctor(home, sellerConfig) {
             ]);
             const nativeSuiMist = String(balance.balance), shieldedMist = String(shielded.data.available ?? "0");
             const checks = [
-                { id: "runtime", status: "ready", detail: "Pinned deployment, prover, RPC, and Walrus prerequisites verified." },
+                { id: "runtime", status: "ready", detail: "Pinned deployment, RPC, and Walrus prerequisites verified." },
+                { id: "shielded-proofs", status: shieldedProofsReady ? "ready" : "unavailable", detail: shieldedProofsReady ? "Pinned v2 proving artifacts verified." : String(runtime.data.shieldedFixes?.[0] ?? "Shielded proving artifacts are not installed.") },
                 { id: "public-balance", status: BigInt(nativeSuiMist) > 0n ? "ready" : "action_required", detail: BigInt(nativeSuiMist) > 0n ? `${nativeSuiMist} MIST available.` : "Fund only this generated buyer address before a public payment." },
                 { id: "shielded-balance", status: BigInt(shieldedMist) > 0n ? "ready" : "action_required", detail: BigInt(shieldedMist) > 0n ? `${shieldedMist} MIST available in the experimental pool.` : "Create a buyer-owned pool deposit before a shielded deal." },
                 { id: "seller-approval", status: mandate.allowedCounterparties.length > 0 ? "ready" : "action_required", detail: mandate.allowedCounterparties.length > 0 ? `${mandate.allowedCounterparties.length} seller identity or identities approved.` : "Review and approve a signed seller capability locally." },
                 ...(directoryListings !== undefined ? [{ id: "directory", status: directoryListings > 0 ? "ready" : "action_required", detail: `${directoryListings} live directory listing or listings.` }] : []),
             ];
-            return { role: "buyer", healthy: true, readyForPublicPayment: BigInt(nativeSuiMist) > 0n && mandate.allowedCounterparties.length > 0, readyForShieldedPayment: BigInt(shieldedMist) > 0n && mandate.allowedCounterparties.length > 0, runtime: runtime.data, checks, approvedSellers: mandate.allowedCounterparties.length, nativeSuiMist, shieldedMist, funded: BigInt(nativeSuiMist) > 0n, ...(directoryListings !== undefined ? { directoryListings } : {}) };
+            return { role: "buyer", healthy: true, readyForPublicPayment: BigInt(nativeSuiMist) > 0n && mandate.allowedCounterparties.length > 0, readyForShieldedPayment: shieldedProofsReady && BigInt(shieldedMist) > 0n && mandate.allowedCounterparties.length > 0, runtime: runtime.data, checks, approvedSellers: mandate.allowedCounterparties.length, nativeSuiMist, shieldedMist, funded: BigInt(nativeSuiMist) > 0n, ...(directoryListings !== undefined ? { directoryListings } : {}) };
         }
         if (app.profile.role === "seller") {
             if (!sellerConfig)
@@ -68,15 +70,20 @@ export async function onboardingDoctor(home, sellerConfig) {
             const served = await json(new URL("/v2/catalog", config.origin));
             if (!Array.isArray(served.capabilities))
                 fail("SELLER_CATALOG_INVALID", "seller endpoint has no valid catalog");
+            let proofsRequired = false;
             for (const item of config.capabilities) {
                 const registrationPath = resolve(item.registrationFile);
                 if ((statSync(registrationPath).mode & 0o077) !== 0)
                     fail("SELLER_CONFIG_PERMISSIONS", "registration file must be owner-only");
                 const registration = JSON.parse(readFileSync(registrationPath, "utf8"));
+                proofsRequired ||= registration.manifest.supportedRails.includes("shielded");
                 await verifySignedCapability(registration);
                 if (!served.capabilities.some((entry) => JSON.stringify(entry) === JSON.stringify(registration)))
                     fail("SELLER_CATALOG_INVALID", "seller endpoint does not serve its configured registration");
             }
+            const runtime = await app.execute("doctor", { "proofs-required": proofsRequired });
+            if (runtime.data.readyForDemo === false)
+                fail("ONBOARDING_RUNTIME_NOT_READY", `live runtime doctor reports missing prerequisites: ${(runtime.data.fixes ?? []).join(" ")}`);
             return { role: "seller", healthy: true, runtime: runtime.data, capabilities: config.capabilities.length, origin: config.origin };
         }
         return fail("ROLE_FORBIDDEN", "onboarding doctor supports buyer and seller homes");

package/dist/phase3.d.ts

@@ -1,5 +1,8 @@
 import { RoleStore } from "./store.js";
 import { type LiveRuntimeProfile } from "./live-runtime.js";
+import { type CapabilityManifest, type CapabilityRail } from "./capability.js";
+import { type SellerScorecard } from "./memory-scorecard.js";
+import { type MemoryInfluence, type PlanningMandate, type SettlementPlanV1 } from "./settlement.js";
 export type Role = "buyer" | "seller" | "auditor";
 export interface Profile {
     version: 1 | 2;
@@ -63,12 +66,52 @@ export declare class Phase3App {
     private storedPlan;
     private persistPlan;
     private recalledMockMemories;
+    /** Trusted provenance needs local authority or this owner's memory-key signature (portable across machines). */
     private authenticatedMemory;
     private registerMemoryAuthority;
     private planSettlement;
+    /** Recall settlement memories for several scoped queries; plaintext stays in this process. */
+    private recallSettlementMemories;
+    /**
+     * 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.
+     */
+    private localVerifiedOutcomes;
+    /**
+     * 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.
+     */
+    rankDealCandidates(operationId: string, candidates: CapabilityManifest[], mandate: PlanningMandate, request?: {
+        budgetMaximum?: string;
+        requestedRail?: CapabilityRail;
+        privacyHint?: "any" | "shielded";
+    }): Promise<{
+        ordered: CapabilityManifest[];
+        scorecards: Array<SellerScorecard & {
+            capabilityId: string;
+            priceMinimum: string;
+        }>;
+    }>;
+    /** Stores the counterfactual (same mandate, no memory, every candidate) next to the binding deal plan. */
+    recordDealMemoryInfluence(dealOperationId: string, plan: SettlementPlanV1, mandate: PlanningMandate, request?: {
+        requestedRail?: CapabilityRail;
+        privacyHint?: "any" | "shielded";
+    }): MemoryInfluence | undefined;
+    memoryInfluence(id: string): MemoryInfluence | undefined;
+    /**
+     * 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.
+     */
+    memoryInsights(): Promise<Record<string, unknown>>;
     private typedMemory;
     private rememberTyped;
     private enqueueVerifiedOutcome;
+    /** Queues a verified seller fault as a Walrus outcome memory so later discovery demotes that seller. */
+    recordVerifiedDealFailure(operationId: string, planHash: string, fault: {
+        stage: string;
+        code: string;
+        paymentDigest?: string;
+    }): void;
     recordVerifiedDealOutcome(operationId: string, planHash: string, paymentDigest: string, artifactSha256: string): {
         payloadHash: string;
         queued: true;

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;
@@ -760,7 +873,7 @@ export class Phase3App {
             return output(command, await this.liveMemory(command, args));
         const runtime = await LiveRuntime.create(this.profile, this.store);
         if (command === "doctor")
-            return output(command, await runtime.doctor());
+            return output(command, await runtime.doctor(args["proofs-required"] !== false));
         if (command === "status")
             return output(command, { role: this.profile.role, network: this.profile.network, mock: false, runtime: "testnet-live" });
         if (command === "capability.publish")
@@ -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 {
@@ -1143,7 +1256,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", "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"].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 } };
 }
@@ -1164,6 +1277,8 @@ function recovery(code) {
         return "reconcile or resume with the same operation ID; never create a replacement payment";
     if (code === "DELIVERY_PENDING")
         return "resume the same root operation ID; completed selection, payment, and agreement stages will not run again";
+    if (code === "DEAL_SELLER_UNAVAILABLE")
+        return "check the seller /health endpoint, then resume the same root operation ID";
     if (code === "X402_FACILITATOR_UNAVAILABLE")
         return "the signed transaction remains journaled; resume the same operation ID after facilitator health recovers";
     if (code === "OPERATION_ID_CONFLICT" || code === "DEAL_OPERATION_CONFLICT")

package/dist/role-lock.d.ts

@@ -4,5 +4,5 @@ export interface RoleHomeLease {
     release(): void;
 }
 /** Best-effort process lease. SQLite still owns data integrity; this prevents
- * multiple MCP event/memory workers from operating one role home at once. */
+ * multiple long-running role workers from operating one role home at once. */
 export declare function acquireRoleHomeLease(home: string): RoleHomeLease;

package/dist/role-lock.js

@@ -13,7 +13,7 @@ function active(pid) {
     }
 }
 /** Best-effort process lease. SQLite still owns data integrity; this prevents
- * multiple MCP event/memory workers from operating one role home at once. */
+ * multiple long-running role workers from operating one role home at once. */
 export function acquireRoleHomeLease(home) {
     const path = join(home, ".mcp.lock"), token = randomUUID();
     for (let attempt = 0; attempt < 2; attempt++) {

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-catalog-generate.js

@@ -35,8 +35,8 @@ try {
         if (item.data.reviewStatus !== "approved")
             fail("ARTIFACT_REVIEW_REQUIRED", `${item.path} must be owner-reviewed before live provisioning`);
     for (const brief of [briefA, briefB]) {
-        if (typeof brief.data.title !== "string" || typeof brief.data.body !== "string" || !Array.isArray(brief.data.citations) || brief.data.citations.length < 2 || typeof brief.data.preview !== "object")
-            fail("BRIEF_INVALID", "brief reports need title, body, two citations, and preview metadata");
+        if (typeof brief.data.title !== "string" || typeof brief.data.body !== "string" || !Array.isArray(brief.data.citations) || brief.data.citations.length < 2 || brief.data.citations.some((value) => typeof value !== "string" || !/^https:\/\//.test(value)) || new Set(brief.data.citations).size !== brief.data.citations.length || typeof brief.data.preview !== "object")
+            fail("BRIEF_INVALID", "brief reports need title, body, unique HTTPS citations, and preview metadata");
         for (const key of ["relevance", "sourceQuality"])
             if (typeof brief.data.preview[key] !== "number" || brief.data.preview[key] < 0 || brief.data.preview[key] > 1)
                 fail("BRIEF_INVALID", `preview ${key} must be in [0,1]`);
@@ -44,8 +44,8 @@ try {
             fail("BRIEF_INVALID", "preview freshnessDays is invalid");
     }
     for (const analysis of [analysisA, analysisB])
-        if (typeof analysis.data.title !== "string" || typeof analysis.data.body !== "string")
-            fail("ANALYSIS_INVALID", "analysis reports need a title and body");
+        if (typeof analysis.data.title !== "string" || typeof analysis.data.body !== "string" || analysis.data.citations !== undefined && (!Array.isArray(analysis.data.citations) || analysis.data.citations.some((value) => typeof value !== "string" || !/^https:\/\//.test(value))))
+            fail("ANALYSIS_INVALID", "analysis reports need a title, body, and HTTPS citations when provided");
     const expiresAt = Date.now() + 7 * 24 * 60 * 60 * 1000;
     const capability = (id, sellerId, description, rails, amount) => createCapabilityManifest({ capabilityId: id, sellerId, capability: id === "competitor-analysis" ? "sui.competitor-analysis" : "sui.market-brief", description, inputSchema: { type: "object", properties: { topic: { type: "string" } } }, outputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" }, citations: { type: "array" } } }, supportedRails: rails, priceBand: { minimum: amount, maximum: amount }, asset: "0x2::sui::SUI", endpoint: new URL(`/resource/${id}`, origin).toString(), expiresAt });
     const publicA = run.addresses.publicSeller ?? fail("SELLER_CONFIG_INVALID", "first brief seller is missing"), publicB = run.addresses.secondPublicSeller ?? fail("SELLER_CONFIG_INVALID", "second brief seller is missing"), analysisSeller = run.addresses.confidentialSeller ?? fail("SELLER_CONFIG_INVALID", "analysis seller is missing");

package/dist/seller-directory-cli.js

@@ -3,6 +3,7 @@ import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { verifySignedCapability } from "./capability.js";
 import { fail } from "./errors.js";
+import { errorOutput } from "./phase3.js";
 async function main() {
     const [command, file, directory] = process.argv.slice(2);
     if (command !== "publish" || !file || !directory)
@@ -21,4 +22,4 @@ async function main() {
         fail("SELLER_DIRECTORY_UNAVAILABLE", String(result.message ?? `directory returned HTTP ${response.status}`));
     process.stdout.write(`${JSON.stringify(result)}\n`);
 }
-main().catch((error) => { process.stderr.write(`${error instanceof Error ? error.message : "directory publication failed"}\n`); process.exitCode = 1; });
+main().catch((error) => { process.stdout.write(`${JSON.stringify(errorOutput(error))}\n`); process.exitCode = 1; });

package/dist/seller-live-cli.js

@@ -5,6 +5,7 @@ import { pathToFileURL } from "node:url";
 import { fail } from "./errors.js";
 import { Phase3App, errorOutput } from "./phase3.js";
 import { LiveSellerTransport } from "./live-seller-transport.js";
+import { acquireRoleHomeLease } from "./role-lock.js";
 async function main() {
     const home = process.argv[2], configPath = process.argv[3];
     if (!home || !configPath)
@@ -12,8 +13,15 @@ async function main() {
     if ((statSync(configPath).mode & 0o077) !== 0)
         fail("SELLER_CONFIG_PERMISSIONS", "seller config must be owner-only");
     const config = JSON.parse(readFileSync(configPath, "utf8"));
+    if (config.facilitatorUrlEnv)
+        config.facilitatorUrl = process.env[config.facilitatorUrlEnv] ?? fail("SELLER_FACILITATOR_REQUIRED", `environment variable ${config.facilitatorUrlEnv} is required`);
+    if (config.facilitatorKeyEnv)
+        config.facilitatorKey = process.env[config.facilitatorKeyEnv] ?? fail("SELLER_FACILITATOR_REQUIRED", `environment variable ${config.facilitatorKeyEnv} is required`);
     if (!Array.isArray(config.capabilities) || !config.capabilities.length)
         fail("SELLER_CONFIG_INVALID", "seller config must name registered capabilities and handlers");
+    const lease = acquireRoleHomeLease(resolve(home));
+    if (!lease.acquired)
+        fail("ROLE_HOME_BUSY", `seller home is already in use${lease.ownerPid ? ` by process ${lease.ownerPid}` : ""}`);
     const app = new Phase3App(home), transport = new LiveSellerTransport(app, config);
     try {
         for (const item of config.capabilities) {
@@ -41,11 +49,12 @@ async function main() {
             fail("SELLER_CONFIG_INVALID", "seller listenPort must be a valid TCP port");
         await new Promise((done) => server.listen(port, host, done));
         process.stdout.write(`${JSON.stringify({ ok: true, service: "supercuts-seller-live", origin: config.origin, capabilities: transport.runtime.catalog().map((item) => item.manifest.capabilityId) })}\n`);
-        const stop = () => server.close(() => { app.close(); process.exit(0); });
+        const stop = () => server.close(() => { lease.release(); app.close(); process.exit(0); });
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
     }
     catch (error) {
+        lease.release();
         app.close();
         throw error;
     }