@supercuts-walrus/backend 0.0.0-stage → 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+export interface DeploymentConfig {
+    network: "testnet";
+    chainId: string;
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    coinTypeHash: string;
+    deploymentDomain: string;
+    verifierVersion: number;
+    deploymentCheckpoint: bigint;
+    initialRoot: string;
+    tatumGrpcEndpoint: string;
+    tatumApiKey: string;
+    writeGrpcEndpoint: string;
+    walrusPublisherUrl: string;
+    walrusAggregatorUrl: string;
+    x402FacilitatorUrl: string;
+}
+export declare function parseDeploymentConfig(value: Record<string, unknown>): DeploymentConfig;
+export declare function loadStateKey(path: string): Buffer;

package/dist/config.js

@@ -0,0 +1,58 @@
+import { readFileSync, statSync } from "node:fs";
+import { fail } from "./errors.js";
+const HEX_32 = /^(?:0x)?[0-9a-f]{64}$/i;
+const SUI_ID = /^0x[0-9a-f]{64}$/i;
+export function parseDeploymentConfig(value) {
+    if (value.network !== "testnet")
+        fail("CONFIG_INVALID", "network must be the pinned testnet deployment");
+    const string = (key) => {
+        const result = value[key];
+        if (typeof result !== "string" || !result.trim())
+            fail("CONFIG_INVALID", `${key} is required`);
+        return result;
+    };
+    const checkpoint = string("deploymentCheckpoint");
+    const verifierVersion = value.verifierVersion;
+    const config = {
+        network: "testnet",
+        chainId: string("chainId"), packageId: string("packageId"), poolId: string("poolId"),
+        coinType: string("coinType"), coinTypeHash: string("coinTypeHash"),
+        deploymentDomain: string("deploymentDomain"), verifierVersion: Number(verifierVersion),
+        deploymentCheckpoint: BigInt(checkpoint), initialRoot: string("initialRoot"),
+        tatumGrpcEndpoint: string("tatumGrpcEndpoint"), tatumApiKey: string("tatumApiKey"),
+        writeGrpcEndpoint: string("writeGrpcEndpoint"), walrusPublisherUrl: string("walrusPublisherUrl"),
+        walrusAggregatorUrl: string("walrusAggregatorUrl"), x402FacilitatorUrl: string("x402FacilitatorUrl"),
+    };
+    if (![config.packageId, config.poolId].every((id) => SUI_ID.test(id)))
+        fail("CONFIG_INVALID", "packageId and poolId must be 32-byte Sui IDs");
+    if (![config.coinTypeHash, config.deploymentDomain, config.initialRoot].every((hex) => HEX_32.test(hex)))
+        fail("CONFIG_INVALID", "deployment hashes must be 32-byte hex values");
+    if (!Number.isInteger(config.verifierVersion) || config.verifierVersion < 1)
+        fail("CONFIG_INVALID", "verifierVersion must be a positive integer");
+    if (config.deploymentCheckpoint < 0n)
+        fail("CONFIG_INVALID", "deploymentCheckpoint cannot be negative");
+    for (const [name, endpoint] of Object.entries({ tatumGrpcEndpoint: config.tatumGrpcEndpoint, writeGrpcEndpoint: config.writeGrpcEndpoint, walrusPublisherUrl: config.walrusPublisherUrl, walrusAggregatorUrl: config.walrusAggregatorUrl, x402FacilitatorUrl: config.x402FacilitatorUrl })) {
+        let url;
+        try {
+            url = new URL(endpoint);
+        }
+        catch (error) {
+            return fail("CONFIG_INVALID", `${name} must be an absolute URL`, error);
+        }
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "::1"].includes(url.hostname)))
+            fail("CONFIG_INVALID", `${name} must use HTTPS except on loopback`);
+        if (url.username || url.password)
+            fail("CONFIG_INVALID", `${name} cannot contain embedded credentials`);
+    }
+    return config;
+}
+export function loadStateKey(path) {
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o077) !== 0)
+        fail("STATE_KEY_PERMISSIONS", `state key ${path} must not be group/world accessible`);
+    const raw = readFileSync(path);
+    const key = /^[0-9a-fA-F]{64}\s*$/.test(raw.toString("utf8")) ? Buffer.from(raw.toString("utf8").trim(), "hex") : raw;
+    if (key.length !== 32)
+        fail("STATE_KEY_INVALID", "state key must contain exactly 32 bytes or 64 hex characters");
+    return key;
+}

package/dist/dashboard.d.ts

@@ -0,0 +1,5 @@
+import { type Server } from "node:http";
+export declare function serveEventDashboard(path: string, port: number, replay?: boolean): Promise<{
+    server: Server;
+    url: string;
+}>;

package/dist/dashboard.js

@@ -0,0 +1,21 @@
+import { createServer } from "node:http";
+import { readDemoEvents, recordedReplay } from "./events.js";
+const html = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Supercuts funded-run evidence</title><style>body{font:15px system-ui;margin:0;background:#0b1020;color:#eef2ff}header{position:sticky;top:0;padding:18px 24px;background:#111936;border-bottom:1px solid #334155}main{max-width:980px;margin:auto;padding:24px}.event{display:grid;grid-template-columns:9rem 10rem 1fr;gap:14px;padding:14px;border-bottom:1px solid #27334f}.mode{color:#fbbf24;font-weight:700}.complete,.allowed{color:#86efac}.failed,.rejected{color:#fca5a5}code{color:#bfdbfe;white-space:pre-wrap}</style></head><body><header><b>Supercuts</b> · <span class="mode" id="mode">loading evidence…</span></header><main id="events"></main><script>const out=document.querySelector('#events');const source=new EventSource('/events');source.onmessage=e=>{const v=JSON.parse(e.data);document.querySelector('#mode').textContent=v.mode==='live'?'LIVE FUNDED RUN':'RECORDED FUNDED RUN';const n=document.createElement('div');n.className='event';n.innerHTML='<span>#'+v.sequence+' '+v.actor+'</span><span class="'+v.status+'">'+v.stage+' · '+v.status+'</span><code></code>';n.querySelector('code').textContent=JSON.stringify(v.publicDetails,null,2);out.append(n)};</script></body></html>`;
+export function serveEventDashboard(path, port, replay = false) {
+    const server = createServer((request, response) => {
+        if (request.url === "/") {
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+            return response.end(html);
+        }
+        if (request.url === "/events") {
+            response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive", "access-control-allow-origin": "http://127.0.0.1" });
+            const source = readDemoEvents(path), events = replay ? recordedReplay(source) : source;
+            for (const event of events)
+                response.write(`data: ${JSON.stringify(event)}\n\n`);
+            return response.end();
+        }
+        response.writeHead(404);
+        response.end("Not Found");
+    });
+    return new Promise((resolve, reject) => { server.once("error", reject); server.listen(port, "127.0.0.1", () => resolve({ server, url: `http://127.0.0.1:${port}/` })); });
+}

package/dist/deal-adapter.d.ts

@@ -0,0 +1,3 @@
+import { DealEngine } from "./deal-engine.js";
+import type { Phase3App } from "./phase3.js";
+export declare function createConfiguredDealEngine(app: Phase3App): Promise<DealEngine>;

package/dist/deal-adapter.js

@@ -0,0 +1,39 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DealEngine } from "./deal-engine.js";
+import { DealJournal } from "./deal.js";
+import { fail } from "./errors.js";
+import { loadMandate } from "./mandate.js";
+import { LiveDealPorts } from "./live-deal-ports.js";
+export async function createConfiguredDealEngine(app) {
+    if (app.profile.role !== "buyer" || app.profile.mock)
+        fail("DEAL_LIVE_REQUIRED", "composite deals require a live buyer role home");
+    const mandate = loadMandate(app.home);
+    if (mandate.version !== "supercuts.mandate.v2")
+        fail("DEAL_MANDATE_VERSION", "composite deals require an owner-issued v2 mandate");
+    if (!mandate.allowedCommands.includes("deal.execute"))
+        fail("MANDATE_COMMAND_FORBIDDEN", "owner mandate does not allow composite deal execution");
+    const path = join(app.home, "deal-ports.mjs");
+    if (!existsSync(path)) {
+        if (!app.store.getSecret("live:memory-config"))
+            fail("LIVE_MEMORY_CONFIG_MISSING", "live composite deals require an owner-only Walrus Memory configuration");
+        return new DealEngine(new DealJournal(app.store), new LiveDealPorts(app, mandate), mandate);
+    }
+    if ((statSync(path).mode & 0o077) !== 0)
+        fail("DEAL_PORTS_PERMISSIONS", "deal ports adapter must be owner-only");
+    let loaded;
+    try {
+        loaded = await import(pathToFileURL(path).href);
+    }
+    catch (error) {
+        return fail("DEAL_PORTS_LOAD_FAILED", "owner deal ports adapter could not load", error);
+    }
+    if (typeof loaded.createDealPorts !== "function")
+        return fail("DEAL_PORTS_INVALID", "owner adapter must export createDealPorts");
+    const ports = await loaded.createDealPorts(app, mandate);
+    for (const method of ["readBlob", "discover", "plan", "negotiate", "pay", "deliver", "rememberOutcome", "inventory"])
+        if (typeof ports?.[method] !== "function")
+            fail("DEAL_PORTS_INVALID", `owner adapter is missing ${method}`);
+    return new DealEngine(new DealJournal(app.store), ports, mandate);
+}

package/dist/deal-engine.d.ts

@@ -0,0 +1,62 @@
+import { type SignedCapabilityRegistration } from "./capability.js";
+import { DealJournal, type DealView, type ExecuteDealInput } from "./deal.js";
+import type { AgentMandate } from "./mandate.js";
+import { type SettlementPlanV1 } from "./settlement.js";
+export interface DealNegotiation {
+    transcriptBlobs: Array<{
+        blobId: string;
+        ciphertextHash: string;
+    }>;
+    agreementBlobId: string;
+    agreementCiphertextHash: string;
+}
+export interface DealPayment {
+    transactionDigest: string;
+    finalized: true;
+    tatumVerified: true;
+    proveMs?: number;
+}
+export interface DealArtifact {
+    blobId: string;
+    ciphertextHash: string;
+    artifactSha256: string;
+    contentType: string;
+    metadata: Record<string, unknown>;
+    artifactBase64: string;
+}
+export interface DealOutcome {
+    payloadHash: string;
+    blobId: string;
+    indexed: boolean;
+}
+export interface DealOutcomeQueued {
+    queued: true;
+    payloadHash: string;
+}
+/** A port owns transport, signing, and finality checks. It must be safe to call
+ * again with the same child IDs after a process crash. */
+export interface DealPorts {
+    readBlob(blobId: string): Promise<Uint8Array>;
+    discover(input: ExecuteDealInput): Promise<SignedCapabilityRegistration>;
+    plan(input: ExecuteDealInput, registration: SignedCapabilityRegistration, paymentOperationId: string): Promise<SettlementPlanV1>;
+    negotiate(input: ExecuteDealInput, registration: SignedCapabilityRegistration, plan: SettlementPlanV1, agreementOperationId: string): Promise<DealNegotiation>;
+    pay(input: ExecuteDealInput, plan: SettlementPlanV1, negotiation: DealNegotiation, paymentOperationId: string): Promise<DealPayment | {
+        pending: true;
+    }>;
+    deliver(input: ExecuteDealInput, plan: SettlementPlanV1, negotiation: DealNegotiation, payment: DealPayment, deliveryOperationId: string): Promise<DealArtifact | {
+        pending: true;
+    }>;
+    rememberOutcome(input: ExecuteDealInput, plan: SettlementPlanV1, payment: DealPayment, artifact: DealArtifact, outcomeOperationId: string): Promise<DealOutcome | DealOutcomeQueued | {
+        unresolved: true;
+    }>;
+    inventory(blobId: string): Promise<boolean>;
+}
+export declare class DealEngine {
+    private readonly journal;
+    private readonly ports;
+    private readonly mandate;
+    constructor(journal: DealJournal, ports: DealPorts, mandate: AgentMandate);
+    execute(input: ExecuteDealInput): Promise<DealView>;
+    resume(operationId: string): Promise<DealView>;
+    private finishOutcome;
+}

package/dist/deal-engine.js

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { validateCapabilityPayload, verifySignedCapability } from "./capability.js";
+import { dealChildId } from "./deal.js";
+import { fail, SupercutsError } from "./errors.js";
+import { canonicalJson, validateSettlementPlan } from "./settlement.js";
+const hash = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
+export class DealEngine {
+    journal;
+    ports;
+    mandate;
+    constructor(journal, ports, mandate) {
+        this.journal = journal;
+        this.ports = ports;
+        this.mandate = mandate;
+        if (mandate.version !== "supercuts.mandate.v2" || mandate.role !== "buyer")
+            fail("DEAL_MANDATE_VERSION", "deal execution requires an owner-issued buyer mandate v2");
+    }
+    async execute(input) {
+        this.journal.create(input);
+        return this.resume(input.operationId);
+    }
+    async resume(operationId) {
+        const input = this.journal.input(operationId);
+        let view = this.journal.get(operationId);
+        if (view.state === "complete" || view.state === "failed" || view.state === "unresolved")
+            return view;
+        if (view.state === "outcome_pending")
+            return this.finishOutcome(operationId, input);
+        if (Date.now() > this.mandate.expiresAt)
+            fail("MANDATE_EXPIRED", "owner mandate has expired");
+        if (!this.mandate.allowedAssets.includes(input.budget.asset) || BigInt(input.budget.maximum) > BigInt(this.mandate.perDealCeiling))
+            fail("DEAL_BUDGET_DENIED", "deal budget exceeds the owner mandate");
+        if (input.requestedRail === "x402" && (this.mandate.allowPublicX402 !== true || !this.mandate.allowedRails?.includes("x402") || this.mandate.requiredPrivacy === "shielded" || input.privacyHint === "shielded"))
+            fail("DEAL_PUBLIC_RAIL_FORBIDDEN", "owner mandate did not authorize public x402");
+        if (view.state === "awaiting_approval" || view.state === "review_required")
+            return view;
+        let registration = this.journal.step(operationId, "discovery");
+        if (!registration) {
+            const started = Date.now();
+            registration = await this.ports.discover(input);
+            await verifySignedCapability(registration);
+            const manifestBytes = await this.ports.readBlob(registration.manifestBlobId);
+            let publishedManifest;
+            try {
+                publishedManifest = JSON.parse(Buffer.from(manifestBytes).toString());
+            }
+            catch (error) {
+                return fail("CAPABILITY_BLOB_INVALID", "Walrus capability blob is not JSON", error);
+            }
+            if (canonicalJson(publishedManifest) !== canonicalJson(registration.manifest))
+                fail("CAPABILITY_BLOB_MISMATCH", "Walrus manifest differs from the seller's signed capability");
+            this.journal.saveStep(operationId, "discovery", input, registration);
+            this.journal.recordTiming(operationId, "discovery", Date.now() - started);
+        }
+        else
+            await verifySignedCapability(registration);
+        if (input.capabilityId && registration.manifest.capabilityId !== input.capabilityId || input.capabilityClass && registration.manifest.capability !== input.capabilityClass || registration.manifest.asset !== input.budget.asset)
+            fail("DEAL_CAPABILITY_MISMATCH", "seller capability differs from the task selector or asset");
+        validateCapabilityPayload(registration.manifest, "input", input.input);
+        if (!this.mandate.allowedCounterparties.includes(registration.manifest.sellerId) || this.mandate.allowedCapabilityIds && !this.mandate.allowedCapabilityIds.includes(registration.manifest.capabilityId) || this.mandate.allowedCapabilityClasses && !this.mandate.allowedCapabilityClasses.includes(registration.manifest.capability))
+            fail("DEAL_SELLER_FORBIDDEN", "signed seller capability is outside the owner mandate");
+        if (view.state === "created")
+            view = this.journal.advance(operationId, "created", "discovered");
+        const paymentOperationId = dealChildId(operationId, "payment");
+        let plan = this.journal.step(operationId, "planning");
+        if (!plan) {
+            const started = Date.now();
+            plan = await this.ports.plan(input, registration, paymentOperationId);
+            validateSettlementPlan(plan);
+            if (plan.operationId !== paymentOperationId || plan.manifestHash !== registration.manifest.manifestHash || plan.asset !== input.budget.asset || BigInt(plan.maximumAmount) > BigInt(input.budget.maximum))
+                fail("DEAL_PLAN_MISMATCH", "settlement plan exceeds the deal's capability or budget");
+            this.journal.saveStep(operationId, "planning", { input, manifestHash: registration.manifest.manifestHash }, plan);
+            this.journal.recordTiming(operationId, "planning", Date.now() - started);
+        }
+        else
+            validateSettlementPlan(plan);
+        if (plan.operationId !== paymentOperationId || plan.manifestHash !== registration.manifest.manifestHash || plan.asset !== input.budget.asset || BigInt(plan.maximumAmount) > BigInt(input.budget.maximum))
+            fail("DEAL_PLAN_MISMATCH", "saved plan exceeds the deal's capability or budget");
+        if (input.requestedRail && plan.rail !== input.requestedRail || input.privacyHint === "shielded" && plan.rail !== "shielded")
+            fail("DEAL_PRIVACY_UNAVAILABLE", "planned rail differs from the requested privacy");
+        if (!input.requestedRail && registration.manifest.supportedRails.includes("shielded") && plan.rail !== "shielded")
+            fail("DEAL_PRIVACY_UNAVAILABLE", "shielded is the default rail when the seller supports it");
+        if (plan.rail === "x402" && (this.mandate.allowPublicX402 !== true || !this.mandate.allowedRails?.includes("x402") || this.mandate.requiredPrivacy === "shielded"))
+            fail("DEAL_PUBLIC_RAIL_FORBIDDEN", "owner mandate did not authorize public x402");
+        if (view.state === "discovered")
+            view = this.journal.advance(operationId, "discovered", "planned", { rail: plan.rail, planHash: plan.planHash });
+        if (plan.status === "review_required")
+            return this.journal.advance(operationId, "planned", "review_required");
+        if (Date.now() >= plan.expiresAt && ["planned", "negotiating", "agreed", "evidence_ready", "funding_required"].includes(view.state))
+            return fail("DEAL_PLAN_EXPIRED", "saved settlement plan expired before payment");
+        let negotiation = this.journal.step(operationId, "negotiation");
+        if (view.state === "planned")
+            view = this.journal.advance(operationId, "planned", "negotiating");
+        if (!negotiation) {
+            const started = Date.now();
+            negotiation = await this.ports.negotiate(input, registration, plan, dealChildId(operationId, "agreement"));
+            if (!negotiation.agreementBlobId || !/^[0-9a-f]{64}$/.test(negotiation.agreementCiphertextHash) || !Array.isArray(negotiation.transcriptBlobs) || !negotiation.transcriptBlobs.length)
+                fail("DEAL_AGREEMENT_INVALID", "seller agreement or Walrus transcript evidence is incomplete");
+            this.journal.saveStep(operationId, "negotiation", { planHash: plan.planHash }, negotiation);
+            this.journal.recordTiming(operationId, "negotiation", Date.now() - started);
+        }
+        const agreementReadStarted = Date.now();
+        for (const item of [...negotiation.transcriptBlobs, { blobId: negotiation.agreementBlobId, ciphertextHash: negotiation.agreementCiphertextHash }]) {
+            if (!item.blobId || !/^[0-9a-f]{64}$/.test(item.ciphertextHash) || createHash("sha256").update(await this.ports.readBlob(item.blobId)).digest("hex") !== item.ciphertextHash)
+                fail("WALRUS_BLOB_MISMATCH", "encrypted negotiation or agreement differs from Walrus readback");
+        }
+        this.journal.recordTiming(operationId, "agreement_readback", Date.now() - agreementReadStarted);
+        if (view.state === "negotiating")
+            view = this.journal.advance(operationId, "negotiating", "agreed");
+        this.journal.recordBlob(operationId, "agreement", negotiation.agreementCiphertextHash, negotiation.agreementBlobId);
+        if (view.state === "agreed")
+            view = this.journal.advance(operationId, "agreed", "evidence_ready");
+        let payment = this.journal.step(operationId, "payment");
+        if (view.state === "evidence_ready" || view.state === "funding_required")
+            view = this.journal.advance(operationId, view.state, "payment_pending");
+        if (!payment) {
+            let candidate;
+            const started = Date.now();
+            try {
+                candidate = await this.ports.pay(input, plan, negotiation, paymentOperationId);
+            }
+            catch (error) {
+                if (error instanceof SupercutsError && error.code === "INSUFFICIENT_SHIELDED_BALANCE")
+                    return this.journal.advance(operationId, "payment_pending", "funding_required");
+                throw error;
+            }
+            if ("pending" in candidate)
+                return this.journal.get(operationId);
+            if (candidate.finalized !== true || candidate.tatumVerified !== true || !candidate.transactionDigest)
+                fail("DEAL_PAYMENT_UNVERIFIED", "payment lacks final Sui and Tatum evidence");
+            payment = candidate;
+            this.journal.saveStep(operationId, "payment", { planHash: plan.planHash, agreementBlobId: negotiation.agreementBlobId }, payment);
+            this.journal.recordTiming(operationId, "payment", Date.now() - started);
+            if (typeof payment.proveMs === "number")
+                this.journal.recordTiming(operationId, "proof", payment.proveMs);
+        }
+        if (view.state === "payment_pending")
+            view = this.journal.advance(operationId, "payment_pending", "paid");
+        let artifact = this.journal.step(operationId, "delivery");
+        if (view.state === "paid")
+            view = this.journal.advance(operationId, "paid", "delivery_pending");
+        if (!artifact) {
+            const started = Date.now();
+            const candidate = await this.ports.deliver(input, plan, negotiation, payment, dealChildId(operationId, "delivery"));
+            if ("pending" in candidate)
+                return this.journal.get(operationId);
+            if (!candidate.blobId || !/^[0-9a-f]{64}$/.test(candidate.ciphertextHash) || !/^[0-9a-f]{64}$/.test(candidate.artifactSha256))
+                fail("DEAL_DELIVERY_UNVERIFIED", "seller delivery evidence is incomplete");
+            if (typeof candidate.artifactBase64 !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(candidate.artifactBase64))
+                fail("DEAL_DELIVERY_UNVERIFIED", "seller artifact encoding is invalid");
+            const artifactBytes = Buffer.from(candidate.artifactBase64, "base64");
+            if (!artifactBytes.length || artifactBytes.length > 512 * 1024 || createHash("sha256").update(artifactBytes).digest("hex") !== candidate.artifactSha256)
+                fail("DEAL_DELIVERY_UNVERIFIED", "seller artifact hash or size is invalid");
+            validateCapabilityPayload(registration.manifest, "output", candidate.metadata);
+            artifact = candidate;
+            this.journal.saveStep(operationId, "delivery", { paymentDigest: payment.transactionDigest }, artifact);
+            this.journal.recordTiming(operationId, "delivery", Date.now() - started);
+        }
+        if (createHash("sha256").update(Buffer.from(artifact.artifactBase64, "base64")).digest("hex") !== artifact.artifactSha256)
+            fail("DEAL_DELIVERY_UNVERIFIED", "saved artifact hash differs from delivery evidence");
+        const deliveryReadStarted = Date.now();
+        if (createHash("sha256").update(await this.ports.readBlob(artifact.blobId)).digest("hex") !== artifact.ciphertextHash)
+            fail("WALRUS_BLOB_MISMATCH", "encrypted delivery differs from Walrus readback");
+        this.journal.recordTiming(operationId, "delivery_readback", Date.now() - deliveryReadStarted);
+        this.journal.recordBlob(operationId, "delivery", artifact.ciphertextHash, artifact.blobId);
+        if (view.state === "delivery_pending")
+            view = this.journal.advance(operationId, "delivery_pending", "delivered");
+        if (view.state === "delivered")
+            view = this.journal.advance(operationId, "delivered", "outcome_pending");
+        return this.finishOutcome(operationId, input);
+    }
+    async finishOutcome(operationId, input) {
+        const view = this.journal.get(operationId);
+        if (view.evidence.outcomeMemory === "indexed")
+            return view.state === "outcome_pending" ? this.journal.advance(operationId, "outcome_pending", "complete") : view;
+        if (view.evidence.outcomeMemory === "unresolved")
+            return view;
+        const existing = this.journal.outcomeStatus(operationId);
+        if (existing?.blobId) {
+            const indexed = await this.ports.inventory(existing.blobId);
+            this.journal.recordOutcome(operationId, existing.payloadHash, existing.blobId, indexed);
+            return indexed ? this.journal.advance(operationId, "outcome_pending", "complete") : this.journal.get(operationId);
+        }
+        if (existing)
+            return view;
+        const plan = this.journal.step(operationId, "planning") ?? fail("DEAL_PLAN_MISSING", "saved deal plan is missing");
+        const payment = this.journal.step(operationId, "payment") ?? fail("DEAL_PAYMENT_UNVERIFIED", "saved deal payment is missing");
+        const artifact = this.journal.step(operationId, "delivery") ?? fail("DEAL_DELIVERY_UNVERIFIED", "saved deal delivery is missing");
+        let outcome = this.journal.step(operationId, "outcome");
+        if (!outcome) {
+            const started = Date.now();
+            const candidate = await this.ports.rememberOutcome(input, plan, payment, artifact, dealChildId(operationId, "outcome"));
+            this.journal.recordTiming(operationId, "outcome_queue", Date.now() - started);
+            if ("unresolved" in candidate) {
+                this.journal.setOutcomeUnresolved(operationId);
+                return this.journal.get(operationId);
+            }
+            if ("queued" in candidate) {
+                this.journal.queueOutcome(operationId, candidate.payloadHash);
+                return this.journal.get(operationId);
+            }
+            if (!candidate.blobId || !/^[0-9a-f]{64}$/.test(candidate.payloadHash))
+                fail("DEAL_MEMORY_INVALID", "outcome memory is incomplete");
+            outcome = candidate;
+            this.journal.saveStep(operationId, "outcome", { paymentDigest: payment.transactionDigest, artifactSha256: artifact.artifactSha256 }, outcome);
+        }
+        const indexed = await this.ports.inventory(outcome.blobId);
+        this.journal.recordOutcome(operationId, outcome.payloadHash, outcome.blobId, indexed);
+        return indexed ? this.journal.advance(operationId, "outcome_pending", "complete") : this.journal.get(operationId);
+    }
+}

package/dist/deal-wire.d.ts

@@ -0,0 +1,16 @@
+import type { Phase3App } from "./phase3.js";
+export declare const wireHash: (value: Uint8Array | string) => string;
+export declare const wireJsonHash: (value: unknown) => string;
+export declare function wireKey(app: Phase3App, peerPublicKey: string, sessionId: string): Buffer;
+export declare function wireEncrypt(key: Uint8Array, sessionId: string, kind: string, value: unknown): string;
+export declare function wireDecrypt<T>(key: Uint8Array, sessionId: string, kind: string, ciphertext: string): T;
+export declare class WalrusDealBlobs {
+    #private;
+    private readonly http;
+    constructor(app: Phase3App, http?: typeof fetch);
+    read(blobId: string): Promise<Uint8Array>;
+    publish(bytes: Uint8Array): Promise<{
+        blobId: string;
+        ciphertextHash: string;
+    }>;
+}

package/dist/deal-wire.js

@@ -0,0 +1,65 @@
+import { createHash, createPrivateKey, createPublicKey, diffieHellman, hkdfSync } from "node:crypto";
+import { fail } from "./errors.js";
+import { decryptSessionMessage, encryptSessionMessage } from "./negotiation.js";
+import { canonicalJson } from "./settlement.js";
+export const wireHash = (value) => createHash("sha256").update(value).digest("hex");
+export const wireJsonHash = (value) => wireHash(canonicalJson(value));
+export function wireKey(app, peerPublicKey, sessionId) {
+    const privateDer = app.store.getSecret("identity:x25519-private") ?? fail("IDENTITY_MISSING", "role transport key is missing");
+    let publicKey;
+    try {
+        publicKey = createPublicKey({ key: Buffer.from(peerPublicKey, "base64url"), format: "der", type: "spki" });
+    }
+    catch (error) {
+        return fail("DEAL_TRANSPORT_KEY_INVALID", "peer transport key is invalid", error);
+    }
+    if (publicKey.asymmetricKeyType !== "x25519")
+        fail("DEAL_TRANSPORT_KEY_INVALID", "peer transport key must be X25519");
+    const shared = diffieHellman({ privateKey: createPrivateKey({ key: privateDer, format: "der", type: "pkcs8" }), publicKey });
+    return Buffer.from(hkdfSync("sha256", shared, Buffer.from(sessionId), Buffer.from("supercuts-deal-wire-v1"), 32));
+}
+export function wireEncrypt(key, sessionId, kind, value) {
+    return encryptSessionMessage(key, sessionId, `${sessionId}:${kind}`, Buffer.from(canonicalJson(value)));
+}
+export function wireDecrypt(key, sessionId, kind, ciphertext) {
+    try {
+        return JSON.parse(decryptSessionMessage(key, sessionId, `${sessionId}:${kind}`, ciphertext).toString());
+    }
+    catch (error) {
+        return fail("DEAL_MESSAGE_INVALID", "encrypted deal message could not be decoded", error);
+    }
+}
+export class WalrusDealBlobs {
+    http;
+    #publisher;
+    #aggregator;
+    constructor(app, http = fetch) {
+        this.http = http;
+        this.#publisher = app.profile.live?.walrusPublisherUrl ?? fail("LIVE_WALRUS_CONFIG_MISSING", "Walrus publisher is required");
+        this.#aggregator = app.profile.live?.walrusAggregatorUrl ?? fail("LIVE_WALRUS_CONFIG_MISSING", "Walrus aggregator is required");
+    }
+    async read(blobId) {
+        if (!/^[A-Za-z0-9_-]{1,256}$/.test(blobId))
+            fail("WALRUS_BLOB_INVALID", "Walrus blob ID is invalid");
+        const response = await this.http(`${this.#aggregator.replace(/\/$/, "")}/v1/blobs/${encodeURIComponent(blobId)}`, { signal: AbortSignal.timeout(60_000), redirect: "error" });
+        if (!response.ok)
+            fail("WALRUS_READ_FAILED", `Walrus aggregator returned ${response.status}`);
+        const bytes = Buffer.from(await response.arrayBuffer());
+        if (bytes.length > 1024 * 1024)
+            fail("WALRUS_BLOB_TOO_LARGE", "deal blob exceeds 1 MiB");
+        return bytes;
+    }
+    async publish(bytes) {
+        if (!bytes.length || bytes.length > 1024 * 1024)
+            fail("WALRUS_BLOB_INVALID", "deal blob must contain 1..1048576 bytes");
+        const response = await this.http(`${this.#publisher.replace(/\/$/, "")}/v1/blobs?epochs=5`, { method: "PUT", body: Buffer.from(bytes), signal: AbortSignal.timeout(60_000), redirect: "error" });
+        if (!response.ok)
+            fail("WALRUS_PUBLISH_FAILED", `Walrus publisher returned ${response.status}`);
+        const result = await response.json();
+        const blobId = result.newlyCreated?.blobObject?.blobId ?? result.alreadyCertified?.blobId ?? result.alreadyRegistered?.blobId ?? fail("WALRUS_PUBLISH_FAILED", "Walrus publisher omitted blob ID");
+        const fetched = await this.read(blobId);
+        if (!Buffer.from(fetched).equals(Buffer.from(bytes)))
+            fail("WALRUS_BLOB_MISMATCH", "deal blob failed Walrus readback");
+        return { blobId, ciphertextHash: wireHash(bytes) };
+    }
+}

package/dist/deal.d.ts

@@ -0,0 +1,79 @@
+import type { RoleStore } from "./store.js";
+export declare const DEAL_VERSION: "supercuts.deal.v2";
+export type DealState = "created" | "discovered" | "planned" | "awaiting_approval" | "review_required" | "funding_required" | "negotiating" | "agreed" | "evidence_ready" | "payment_pending" | "paid" | "delivery_pending" | "delivered" | "outcome_pending" | "complete" | "failed" | "unresolved";
+export interface ExecuteDealInput {
+    operationId: string;
+    capabilityId?: string;
+    capabilityClass?: string;
+    input: Record<string, unknown>;
+    budget: {
+        asset: string;
+        maximum: string;
+    };
+    privacyHint?: "any" | "shielded";
+    requestedRail?: "shielded" | "x402";
+}
+export interface DealView {
+    version: typeof DEAL_VERSION;
+    dealId: string;
+    operationId: string;
+    state: DealState;
+    rail?: "shielded" | "x402";
+    visibility?: "shielded-direct-payment" | "public-x402";
+    planHash?: string;
+    paymentDigest?: string;
+    deliveryHash?: string;
+    evidence: {
+        agreement: "pending" | "verified";
+        payment: "pending" | "finalized";
+        delivery: "pending" | "verified";
+        outcomeMemory: "pending" | "indexed" | "unresolved";
+    };
+    nextAction?: "resume" | "check_memory" | "reconcile_memory" | "fund_buyer" | "owner_approval" | "owner_review";
+    timingsMs?: Record<string, number>;
+}
+export interface DealEvidenceView {
+    version: "supercuts.deal-evidence.v1";
+    dealId: string;
+    transcriptBlobIds: string[];
+    agreementBlobId?: string;
+    deliveryBlobId?: string;
+    outcomeMemoryBlobId?: string;
+    ciphertextReadback: "pending" | "verified" | "unresolved";
+    inventory: "pending" | "indexed" | "missing" | "unresolved";
+    paymentFinalized: boolean;
+    paymentDigest?: string;
+}
+export interface DealDelivery {
+    dealId: string;
+    contentType: string;
+    artifactSha256: string;
+    artifact: Uint8Array;
+}
+export declare function validateDealInput(value: unknown): asserts value is ExecuteDealInput;
+export declare function dealChildId(operationId: string, step: "plan" | "agreement" | "payment" | "delivery" | "outcome"): string;
+export declare class DealJournal {
+    private readonly store;
+    constructor(store: RoleStore);
+    create(input: ExecuteDealInput): DealView;
+    get(operationId: string): DealView;
+    input(operationId: string): ExecuteDealInput;
+    saveStep(operationId: string, step: string, input: unknown, result: unknown): void;
+    step<T>(operationId: string, step: string): T | undefined;
+    recordBlob(operationId: string, kind: "agreement" | "delivery", ciphertextHash: string, blobId: string): void;
+    recordOutcome(operationId: string, payloadHash: string, blobId: string, indexed: boolean): void;
+    outcomeStatus(operationId: string): {
+        payloadHash: string;
+        blobId: string | null;
+        status: string;
+    } | undefined;
+    queueOutcome(operationId: string, payloadHash: string): void;
+    setOutcomeUnresolved(operationId: string): void;
+    recordTiming(operationId: string, stage: string, durationMs: number): void;
+    evidence(dealId: string): DealEvidenceView;
+    delivery(dealId: string): DealDelivery;
+    advance(operationId: string, expected: DealState, next: DealState, result?: {
+        rail?: "shielded" | "x402";
+        planHash?: string;
+    }): DealView;
+}