@supercuts-walrus/backend 0.1.1 → 0.1.3

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.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "exports": {
@@ -25,10 +25,12 @@
     "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",
+    "config",
     "README.md"
   ],
   "license": "Apache-2.0",