@supercuts-walrus/backend 0.1.2 → 0.1.3

package/dist/live-runtime.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
-import { fail } from "./errors.js";
+import { fail, SupercutsError } from "./errors.js";
 import { assertSuiFinality, assertTatumFinality } from "./finality.js";
 import { LivePoolIndex } from "./live-index.js";
 import { ProtocolEngine } from "./protocol-engine.js";
@@ -90,7 +90,17 @@ export class LiveRuntime {
         return new LiveRuntime(profile, store, new TatumLedger(profile.live.tatumGrpcEndpoint, tatumKey), Ed25519Keypair.fromSecretKey(decoded.secretKey), engine);
     }
     async doctor(proofsRequired = true) {
-        const artifacts = proofsRequired ? this.prover.doctor() : { rapidSnark: false, artifacts: {} };
+        // Shielded proofs need separately installed artifacts; a public x402 buyer or seller stays usable without them.
+        let artifacts = { rapidSnark: false, artifacts: {} }, shieldedProofs = "ready", shieldedProofsReason;
+        try {
+            artifacts = this.prover.doctor();
+        }
+        catch (error) {
+            if (!(error instanceof SupercutsError) || !["PROVING_ARTIFACT_MISSING", "ARTIFACT_HASH_MISMATCH", "PROVER_TOOL_MISSING"].includes(error.code))
+                throw error;
+            shieldedProofs = "unavailable";
+            shieldedProofsReason = error.code;
+        }
         const [service, suiObject] = await Promise.all([this.tatum.getServiceInfo(), this.client.getObject({ objectId: this.profile.poolId, include: { json: true } })]);
         if (!suiObject.object)
             fail("POOL_OBJECT_MISSING", "pinned Testnet pool object is unavailable; check the Sui write RPC and deployment config");
@@ -98,9 +108,11 @@ export class LiveRuntime {
             fail("TATUM_UNAVAILABLE", "Tatum read RPC did not return service information; check its endpoint and owner-only API key");
         const babySeed = this.store.getSecret("identity:babyjub-seed") ?? fail("IDENTITY_MISSING", "BabyJub identity is missing");
         const identity = this.engine.identity(babySeed);
-        const fixes = [];
-        if (proofsRequired && !artifacts.rapidSnark)
-            fixes.push("Set an executable RapidSnark path in the role profile for v2 proofs.");
+        const fixes = [], shieldedFixes = [];
+        if (shieldedProofs === "unavailable")
+            shieldedFixes.push(`Shielded payments are unavailable (${shieldedProofsReason}): install the hash-pinned v2 proving artifacts, SnarkJS, and the converter. Public x402 payments do not need them.`);
+        else if (!artifacts.rapidSnark)
+            shieldedFixes.push("Set an executable RapidSnark path in the role profile for v2 proofs.");
         if (!this.profile.live.walrusPublisherUrl)
             fixes.push("Configure the Walrus publisher URL for capability and transcript writes.");
         if (!this.profile.live.walrusAggregatorUrl)
@@ -117,7 +129,7 @@ export class LiveRuntime {
                 fixes.push(`Walrus ${name} is unreachable; check the configured URL and network access.`);
             }
         }
-        return { role: this.profile.role, network: "testnet", packageId: this.profile.packageId, poolId: this.profile.poolId, asset: this.profile.coinType, verifierVersion: this.profile.verifierVersion, keyPermissions: "owner-only", rpc: this.profile.live.writeGrpcEndpoint, healthy: true, readyForDemo: fixes.length === 0, fixes, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), memoryConfigured: Boolean(this.store.getSecret("live:memory-config")), proofsRequired, rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
+        return { role: this.profile.role, network: "testnet", packageId: this.profile.packageId, poolId: this.profile.poolId, asset: this.profile.coinType, verifierVersion: this.profile.verifierVersion, keyPermissions: "owner-only", rpc: this.profile.live.writeGrpcEndpoint, healthy: true, readyForDemo: fixes.length === 0 && (!proofsRequired || shieldedFixes.length === 0), fixes: [...fixes, ...(proofsRequired ? shieldedFixes : [])], publicFixes: fixes, shieldedProofs, shieldedFixes, readyForPublicRail: fixes.length === 0, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), memoryConfigured: Boolean(this.store.getSecret("live:memory-config")), proofsRequired, rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
     }
     async balance() {
         const state = await this.index.sync();
@@ -619,8 +631,14 @@ export class LiveRuntime {
         const paymentPayload = { x402Version: 2, resource, accepted: requirements, payload: { signature: signed.signature, transaction: Buffer.from(signed.transaction).toString("base64") } };
         const paid = await fetch(paymentUrl, { redirect: "error", headers: { "payment-signature": Buffer.from(JSON.stringify(paymentPayload)).toString("base64"), "x-supercuts-binding": Buffer.from(JSON.stringify({ ...unsignedBinding, payerSignature })).toString("base64") }, signal: AbortSignal.timeout(60_000) });
         const response = Buffer.from(await paid.arrayBuffer());
-        if (!paid.ok)
-            fail("X402_DELIVERY_FAILED", x402ResourceFailure(paid.status, response));
+        if (!paid.ok) {
+            const detail = x402ResourceFailure(paid.status, response);
+            // Settlement status is unknown: the facilitator may have broadcast before failing. Resume reuses the journaled signed
+            // transaction for this operation ID, and Sui executes one digest at most once, so retrying cannot pay twice.
+            if (paid.status >= 502 && paid.status <= 504 || /X402_FACILITATOR_UNAVAILABLE/.test(detail))
+                fail("X402_FACILITATOR_UNAVAILABLE", `${detail}; settlement status is unknown and the payment may already be on chain. Resume with the same operation ID: the same signed transaction is reused and cannot be paid twice`);
+            fail("X402_DELIVERY_FAILED", detail);
+        }
         const settlementHeader = paid.headers.get("payment-response") ?? fail("X402_SETTLEMENT_INVALID", "payment-response header is missing");
         let settlement;
         try {

package/dist/main-module.d.ts

@@ -0,0 +1,5 @@
+/**
+ * True when this module is the process entry point. Package managers (pnpm in particular) launch bins
+ * through symlinks, so compare resolved real paths rather than raw `argv[1]` strings.
+ */
+export declare function isMainModule(importMetaUrl: string, entry?: string | undefined): boolean;

package/dist/main-module.js

@@ -0,0 +1,16 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * True when this module is the process entry point. Package managers (pnpm in particular) launch bins
+ * through symlinks, so compare resolved real paths rather than raw `argv[1]` strings.
+ */
+export function isMainModule(importMetaUrl, entry = process.argv[1]) {
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(importMetaUrl));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mcp.js

@@ -98,6 +98,8 @@ function logTool(name, data) {
         const plan = journal.step(String(data.operationId), "planning");
         if (plan)
             append("supercuts", "settlement-plan", { phase: "after-memory", planHash: plan.planHash, capabilityId: plan.capabilityId, rail: plan.rail, openingAmount: plan.openingAmount, maximumAmount: plan.maximumAmount, riskLevel: plan.riskLevel, reasonCodes: plan.reasonCodes, blobIds: plan.citations.map((item) => item.blobId) });
+        if (plan && evidence.memoryInfluence)
+            append("supercuts", "memory-influence", { planHash: plan.planHash, changedSeller: evidence.memoryInfluence.changedSeller, changedRail: evidence.memoryInfluence.changedRail, changedRisk: evidence.memoryInfluence.changedRisk, changedMaximum: evidence.memoryInfluence.changedMaximum, withoutMemory: evidence.memoryInfluence.withoutMemory, withMemory: evidence.memoryInfluence.withMemory, scorecards: evidence.memoryRanking, blobIds: evidence.memoryInfluence.citedBlobIds });
         append("supercuts", "deal-lifecycle", { dealId: data.dealId, state: data.state, rail: data.rail, agreement: data.evidence?.agreement, payment: data.evidence?.payment, delivery: data.evidence?.delivery, outcomeMemory: data.evidence?.outcomeMemory, agreementBlobId: evidence.agreementBlobId, deliveryBlobId: evidence.deliveryBlobId, outcomeMemoryBlobId: evidence.outcomeMemoryBlobId, paymentDigest: evidence.paymentDigest });
     }
 }

package/dist/memory-scorecard.d.ts

@@ -0,0 +1,32 @@
+import type { RecalledSettlementMemory, SettlementMemoryScope, SettlementMemoryV1 } from "./settlement.js";
+/** Learned view of one counterparty, derived only from trusted Walrus Memory outcomes. */
+export interface SellerScorecard {
+    counterparty: string;
+    observations: number;
+    successes: number;
+    failures: number;
+    unresolved: number;
+    /** Recency-weighted Beta(1,1) posterior mean; 0.5 when nothing has been learned. */
+    reliability: number;
+    lastOutcome?: "succeeded" | "failed" | "unresolved";
+    lastOutcomeAt?: number;
+    medianLatencyMs?: number;
+    citedBlobIds: string[];
+}
+export declare const DEFAULT_HALF_LIFE_MS: number;
+/** True when every field the filter names matches the memory scope. */
+export declare function scopeWithin(scope: SettlementMemoryScope, filter: SettlementMemoryScope): boolean;
+/**
+ * Trusted deal-level outcome memories for the filter, deduplicated by evidence (one deal may be recalled twice).
+ * Only completed deals and verified seller faults carry `signal.rail`; stage events (agreement, settlement,
+ * delivery) stay as evidence but are not counted as additional deals.
+ */
+export declare function trustedOutcomes(recalled: readonly RecalledSettlementMemory[], filter: SettlementMemoryScope): Array<{
+    blobId: string;
+    memory: SettlementMemoryV1;
+}>;
+export declare function buildScorecard(recalled: readonly RecalledSettlementMemory[], filter: SettlementMemoryScope & {
+    counterparty: string;
+}, now: number, halfLifeMs?: number): SellerScorecard;
+/** Sum of verified paid amounts since `since` within the filter scope; a paid-but-failed deal still spent money. */
+export declare function spentSince(recalled: readonly RecalledSettlementMemory[], filter: SettlementMemoryScope, since: number): bigint;

package/dist/memory-scorecard.js

@@ -0,0 +1,76 @@
+export const DEFAULT_HALF_LIFE_MS = 7 * 86_400_000;
+const TRUSTED = new Set(["owner_policy", "verified_outcome"]);
+/** True when every field the filter names matches the memory scope. */
+export function scopeWithin(scope, filter) {
+    return Object.entries(filter).every(([key, value]) => value === undefined || scope[key] === value);
+}
+/**
+ * Trusted deal-level outcome memories for the filter, deduplicated by evidence (one deal may be recalled twice).
+ * Only completed deals and verified seller faults carry `signal.rail`; stage events (agreement, settlement,
+ * delivery) stay as evidence but are not counted as additional deals.
+ */
+export function trustedOutcomes(recalled, filter) {
+    const seen = new Set(), result = [];
+    for (const item of recalled) {
+        const memory = item.memory;
+        if (!memory ||
+            memory.kind !== "outcome" ||
+            memory.signal.rail === undefined ||
+            !TRUSTED.has(memory.provenance) ||
+            !memory.signal.outcome ||
+            !scopeWithin(memory.scope, filter))
+            continue;
+        const key = memory.evidenceHash ?? item.blobId;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push({ blobId: item.blobId, memory });
+    }
+    return result.sort((a, b) => a.memory.createdAt - b.memory.createdAt ||
+        a.blobId.localeCompare(b.blobId));
+}
+export function buildScorecard(recalled, filter, now, halfLifeMs = DEFAULT_HALF_LIFE_MS) {
+    const outcomes = trustedOutcomes(recalled, filter);
+    let alpha = 1, beta = 1, successes = 0, failures = 0, unresolved = 0;
+    const latencies = [];
+    for (const { memory } of outcomes) {
+        const weight = Math.pow(0.5, Math.max(0, now - memory.createdAt) / halfLifeMs);
+        if (memory.signal.outcome === "succeeded") {
+            successes++;
+            alpha += weight;
+        }
+        else if (memory.signal.outcome === "failed") {
+            failures++;
+            beta += weight;
+        }
+        else {
+            unresolved++;
+            beta += weight / 2;
+        }
+        if (memory.signal.latencyMs !== undefined)
+            latencies.push(memory.signal.latencyMs);
+    }
+    latencies.sort((a, b) => a - b);
+    const last = outcomes.at(-1)?.memory;
+    return {
+        counterparty: filter.counterparty,
+        observations: outcomes.length,
+        successes,
+        failures,
+        unresolved,
+        reliability: alpha / (alpha + beta),
+        ...(last
+            ? { lastOutcome: last.signal.outcome, lastOutcomeAt: last.createdAt }
+            : {}),
+        ...(latencies.length
+            ? { medianLatencyMs: latencies[Math.floor((latencies.length - 1) / 2)] }
+            : {}),
+        citedBlobIds: outcomes.map((item) => item.blobId),
+    };
+}
+/** Sum of verified paid amounts since `since` within the filter scope; a paid-but-failed deal still spent money. */
+export function spentSince(recalled, filter, since) {
+    return trustedOutcomes(recalled, filter)
+        .filter(({ memory }) => memory.signal.amount !== undefined && memory.createdAt >= since)
+        .reduce((total, { memory }) => total + BigInt(memory.signal.amount), 0n);
+}

package/dist/memwal.d.ts

@@ -1,5 +1,17 @@
 import { MemoryFact } from "./memory.js";
 import { type SettlementMemoryV1 } from "./settlement.js";
+export declare const SIGNED_MEMORY_FORMAT: "supercuts.signed-memory.v1";
+/** Sui address that signs this owner's trusted memories; derived from the owner-only memory key. */
+export declare function memorySignerAddress(secret: string): string;
+/** Plain-language line placed before the JSON so embeddings rank the record near scope queries. Not signed. */
+export declare function describeMemory(memory: SettlementMemoryV1): string;
+/** Wraps a trusted memory in a signed envelope so its authority survives a move to another machine. */
+export declare function sealMemoryText(memory: SettlementMemoryV1, secret: string): string;
+/** Opens recalled memory text. `signedBy` is set only when the envelope signature verifies. */
+export declare function openMemoryText(text: string): {
+    memory: unknown;
+    signedBy?: string;
+};
 import { RoleStore } from "./store.js";
 export interface ManualMemoryConfig {
     key: string;
@@ -15,10 +27,26 @@ export interface ManualMemoryConfig {
     walrusAggregatorUrl: string;
     walrusPublisherUrl: string;
 }
+/** Public Walrus Mainnet Memory and local-adapter values; owners only need to supply their own account secrets. */
+export declare const MEMORY_MAINNET_DEFAULTS: {
+    readonly serverUrl: "https://relayer.memory.walrus.xyz";
+    readonly packageId: "0xe7c16fbea0560e7057e2bf7422feaa4fb313749fc69c9e9092fac7a33b81d7f5";
+    readonly registryId: "0x8bf82c9e09e36b8d1c38298f68b7cb68e7b8762887e7592add9986d5e9cf199f";
+    readonly embeddingApiKey: "local-adapter";
+    readonly embeddingApiBase: "http://127.0.0.1:8787/v1";
+    readonly embeddingModel: "embeddinggemma-1536";
+    readonly walrusAggregatorUrl: "https://aggregator.walrus-mainnet.walrus.space";
+    readonly walrusPublisherUrl: "https://publisher.walrus-testnet.walrus.space";
+};
+/** Completes an owner memory config: `key`, `accountId`, and `suiPrivateKey` are required; the rest default. */
+export declare function withMemoryDefaults(raw: Partial<ManualMemoryConfig>, role: string): ManualMemoryConfig;
 /** Client-managed memory facade; plaintext never crosses the relayer boundary. */
 export declare class ManualMemory {
     private readonly store;
     private readonly client;
+    private readonly signingKey;
+    /** Address whose signature marks a recalled memory as this owner's own trusted record. */
+    readonly signerAddress: string | undefined;
     constructor(store: RoleStore, config: ManualMemoryConfig);
     remember(fact: MemoryFact | SettlementMemoryV1): Promise<string>;
     recall(query: string, limit?: number): Promise<Array<{

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

@@ -21,8 +21,9 @@ export async function onboardingDoctor(home, sellerConfig) {
             fail("LIVE_PROFILE_REQUIRED", "onboarding doctor requires a live Testnet role home");
         if (app.profile.role === "buyer") {
             const runtime = await app.execute("doctor", {});
-            if (runtime.data.readyForDemo === false)
-                fail("ONBOARDING_RUNTIME_NOT_READY", "live runtime doctor reports missing prerequisites");
+            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)
@@ -81,7 +83,7 @@ export async function onboardingDoctor(home, sellerConfig) {
             }
             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");
+                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;