@supercuts-walrus/backend 0.0.0-stage → 0.1.0

package/dist/facilitator.d.ts

@@ -0,0 +1,21 @@
+import { type Server } from "node:http";
+type Json = Record<string, unknown>;
+interface SuiClient {
+    getTransaction(options: any): Promise<any>;
+    simulateTransaction(options: any): Promise<any>;
+    executeTransaction(options: any): Promise<any>;
+    waitForTransaction(options: any): Promise<any>;
+}
+/** Non-custodial x402 v2 facilitator: it validates and relays only buyer-signed Sui bytes. */
+export declare class SuiTestnetFacilitator {
+    private readonly key;
+    private readonly client;
+    constructor(key: string, client: SuiClient);
+    private authorized;
+    verify(value: unknown): Promise<Json>;
+    settle(value: unknown): Promise<Json>;
+    createServer(): Server;
+    private handle;
+    private send;
+}
+export {};

package/dist/facilitator.js

@@ -0,0 +1,173 @@
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { Transaction } from "@mysten/sui/transactions";
+import { isValidTransactionSignature } from "@mysten/sui/verify";
+const NETWORK = "sui:testnet";
+const SUI = "0x2::sui::SUI";
+/** Sui RPC may expand a type's address to 32 bytes; policy identifiers use its canonical short form. */
+function canonicalType(value) {
+    if (typeof value !== "string")
+        return "";
+    const match = /^(0x)([0-9a-f]+)(::.+)$/i.exec(value);
+    if (!match)
+        return value;
+    return `0x${match[2].replace(/^0+/, "") || "0"}${match[3]}`.toLowerCase();
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function string(value, label, expression) {
+    if (typeof value !== "string" || !value || value.length > 16_384 || (expression && !expression.test(value)))
+        throw new Error(`${label} is invalid`);
+    return value;
+}
+function exactRequirements(value) {
+    const requirements = object(value, "paymentRequirements");
+    if (requirements.scheme !== "exact" || requirements.network !== NETWORK || requirements.asset !== SUI)
+        throw new Error("only sui:testnet native SUI exact payments are supported");
+    string(requirements.payTo, "payTo", /^0x[0-9a-f]{64}$/i);
+    string(requirements.amount, "amount", /^[1-9][0-9]*$/);
+    if (!Number.isSafeInteger(requirements.maxTimeoutSeconds) || Number(requirements.maxTimeoutSeconds) <= 0)
+        throw new Error("maxTimeoutSeconds is invalid");
+    return requirements;
+}
+function sameJson(left, right) { return JSON.stringify(left) === JSON.stringify(right); }
+async function parsePayment(value, client) {
+    const body = object(value, "request");
+    if (body.x402Version !== 2)
+        throw new Error("x402Version must be 2");
+    const paymentPayload = object(body.paymentPayload, "paymentPayload");
+    if (paymentPayload.x402Version !== 2)
+        throw new Error("payment payload x402Version must be 2");
+    const requirements = exactRequirements(body.paymentRequirements);
+    if (!sameJson(paymentPayload.accepted, requirements))
+        throw new Error("accepted requirements differ from payment requirements");
+    const payload = object(paymentPayload.payload, "payment payload");
+    const signature = string(payload.signature, "transaction signature");
+    const transactionBase64 = string(payload.transaction, "transaction");
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(transactionBase64))
+        throw new Error("transaction must be base64");
+    const transaction = Buffer.from(transactionBase64, "base64");
+    if (!transaction.length || transaction.length > 128 * 1024 || Buffer.from(transaction).toString("base64") !== transactionBase64)
+        throw new Error("transaction bytes are invalid");
+    if (!(await isValidTransactionSignature(transaction, signature)))
+        throw new Error("transaction signature is invalid");
+    let digest;
+    try {
+        digest = await Transaction.from(transaction).getDigest({ client: client });
+    }
+    catch {
+        throw new Error("transaction bytes cannot be decoded");
+    }
+    return { requirements, transaction, signature, digest };
+}
+function transaction(result) { return result?.Transaction ?? result?.FailedTransaction; }
+function assertSuccessfulPayment(result, parsed, finalized) {
+    const tx = transaction(result);
+    if (!tx)
+        throw new Error("transaction result is missing");
+    const digest = tx.digest ?? tx.effects?.transactionDigest;
+    if (digest !== parsed.digest)
+        throw new Error("transaction digest differs from the signed bytes");
+    if (!tx.status?.success)
+        throw new Error(`transaction did not complete successfully: ${String(tx.status?.error ?? "unknown error")}`);
+    if (finalized && !tx.checkpoint)
+        throw new Error("transaction has not finalized");
+    const payTo = String(parsed.requirements.payTo), amount = BigInt(String(parsed.requirements.amount));
+    const matched = (tx.balanceChanges ?? []).some((change) => change.address === payTo && canonicalType(change.coinType) === SUI.toLowerCase() && BigInt(change.amount) === amount);
+    if (!matched)
+        throw new Error("transaction does not credit the exact requested native SUI amount");
+}
+/** Non-custodial x402 v2 facilitator: it validates and relays only buyer-signed Sui bytes. */
+export class SuiTestnetFacilitator {
+    key;
+    client;
+    constructor(key, client) {
+        this.key = key;
+        this.client = client;
+        if (key.length < 24)
+            throw new Error("FACILITATOR_SHARED_KEY must be at least 24 characters");
+    }
+    authorized(request) {
+        const provided = request.headers["x-supercuts-facilitator-key"];
+        const value = Array.isArray(provided) ? provided[0] : provided;
+        if (!value)
+            return false;
+        const actual = Buffer.from(value), expected = Buffer.from(this.key);
+        return actual.length === expected.length && timingSafeEqual(actual, expected);
+    }
+    async verify(value) {
+        const parsed = await parsePayment(value, this.client);
+        let known;
+        try {
+            known = await this.client.getTransaction({ digest: parsed.digest, include: { effects: true, balanceChanges: true } });
+        }
+        catch { /* Not finalized yet; simulate the signed transaction. */ }
+        if (known) {
+            assertSuccessfulPayment(known, parsed, true);
+            return { isValid: true, network: NETWORK, transaction: parsed.digest, replayed: true };
+        }
+        const simulated = await this.client.simulateTransaction({ transaction: parsed.transaction, include: { effects: true, balanceChanges: true } });
+        assertSuccessfulPayment(simulated, parsed, false);
+        return { isValid: true, network: NETWORK, transaction: parsed.digest };
+    }
+    async settle(value) {
+        const parsed = await parsePayment(value, this.client);
+        let known;
+        try {
+            known = await this.client.getTransaction({ digest: parsed.digest, include: { effects: true, balanceChanges: true } });
+        }
+        catch { /* The digest has not reached a node yet. */ }
+        if (known) {
+            assertSuccessfulPayment(known, parsed, true);
+            return { success: true, network: NETWORK, transaction: parsed.digest, replayed: true };
+        }
+        const simulated = await this.client.simulateTransaction({ transaction: parsed.transaction, include: { effects: true, balanceChanges: true } });
+        assertSuccessfulPayment(simulated, parsed, false);
+        try {
+            await this.client.executeTransaction({ transaction: parsed.transaction, signatures: [parsed.signature], include: { effects: true, balanceChanges: true } });
+        }
+        catch { /* broadcast may have won a concurrent race */ }
+        const finalized = await this.client.waitForTransaction({ digest: parsed.digest, timeout: 60_000, include: { effects: true, balanceChanges: true } });
+        assertSuccessfulPayment(finalized, parsed, true);
+        return { success: true, network: NETWORK, transaction: parsed.digest };
+    }
+    createServer() {
+        return createServer((request, response) => void this.handle(request, response));
+    }
+    async handle(request, response) {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        if (request.method === "GET" && url.pathname === "/health")
+            return this.send(response, 200, { ok: true, network: NETWORK });
+        if (request.method === "GET" && url.pathname === "/supported")
+            return this.send(response, 200, { kinds: [{ x402Version: 2, scheme: "exact", network: NETWORK, asset: SUI }] });
+        if (request.method !== "POST" || !["/verify", "/settle"].includes(url.pathname))
+            return this.send(response, 404, { error: "NOT_FOUND" });
+        if (!this.authorized(request))
+            return this.send(response, 401, { error: "UNAUTHORIZED" });
+        try {
+            const chunks = [];
+            for await (const chunk of request) {
+                chunks.push(Buffer.from(chunk));
+                if (Buffer.concat(chunks).length > 256 * 1024)
+                    throw new Error("request too large");
+            }
+            const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            this.send(response, 200, url.pathname === "/verify" ? await this.verify(body) : await this.settle(body));
+        }
+        catch (error) {
+            this.send(response, 400, { error: "PAYMENT_INVALID", message: error instanceof Error ? error.message : "invalid request" });
+        }
+    }
+    send(response, status, body) { const encoded = Buffer.from(JSON.stringify(body)); response.writeHead(status, { "content-type": "application/json", "content-length": String(encoded.length) }); response.end(encoded); }
+}
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    const key = process.env.FACILITATOR_SHARED_KEY ?? "";
+    const grpc = process.env.SUI_TESTNET_GRPC ?? "https://fullnode.testnet.sui.io:443";
+    const port = Number(process.env.PORT ?? "3000");
+    const facilitator = new SuiTestnetFacilitator(key, new SuiGrpcClient({ network: "testnet", baseUrl: grpc }));
+    facilitator.createServer().listen(port, "0.0.0.0", () => process.stdout.write(`supercuts x402 facilitator listening on ${port}\n`));
+}

package/dist/finality.d.ts

@@ -0,0 +1,2 @@
+export declare function assertSuiFinality(result: unknown, digest: string): string;
+export declare function assertTatumFinality(result: unknown, digest: string, expectedCheckpoint: string): void;

package/dist/finality.js

@@ -0,0 +1,27 @@
+import { fail } from "./errors.js";
+function checkpoint(value) {
+    const raw = value && typeof value === "object" ? value.sequenceNumber : value;
+    if (raw === undefined || raw === null)
+        return undefined;
+    try {
+        const parsed = BigInt(raw);
+        return parsed >= 0n ? parsed.toString() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function assertSuiFinality(result, digest) {
+    const envelope = result;
+    const tx = envelope?.Transaction ?? envelope?.FailedTransaction;
+    const observed = tx?.digest ?? tx?.effects?.transactionDigest;
+    const sequence = checkpoint(tx?.checkpoint);
+    if (!tx || observed !== digest || tx.effects?.transactionDigest && tx.effects.transactionDigest !== digest || tx.status?.success !== true || !sequence)
+        return fail("TRANSACTION_FINALITY_FAILED", "Sui did not confirm the journaled successful transaction at a checkpoint");
+    return sequence;
+}
+export function assertTatumFinality(result, digest, expectedCheckpoint) {
+    const tx = result?.transaction;
+    if (tx?.digest !== digest || checkpoint(tx.checkpoint) !== expectedCheckpoint || tx.effects?.status?.success !== true)
+        fail("TATUM_TRANSACTION_MISMATCH", "Tatum did not confirm the same successful finalized transaction");
+}

package/dist/hosted-exit-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hosted-exit-cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { DemoEventLog, readDemoEvents } from "./events.js";
+import { fail } from "./errors.js";
+import { queueHostedExit } from "./hosted-exit.js";
+import { errorOutput, parseArgs } from "./phase3.js";
+import { SellerDatabase } from "./seller-database.js";
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const required = (name) => typeof args[name] === "string" ? args[name] : fail("ARGUMENT_REQUIRED", `--${name} is required`);
+    const secret = (name) => process.env[name] ?? fail("SELLER_CONFIG_MISSING", `${name} is required in the owner environment`);
+    const runPath = resolve(required("run-json"));
+    if ((statSync(runPath).mode & 0o077) !== 0)
+        fail("DEMO_PERMISSIONS", "run.json must be owner-only");
+    const run = JSON.parse(readFileSync(runPath, "utf8"));
+    const runId = run.runId || fail("DEMO_RUN_INVALID", "run.json is missing runId"), eventPath = run.eventPath || fail("DEMO_RUN_INVALID", "run.json is missing the event path"), sellerId = run.addresses?.confidentialSeller || fail("DEMO_RUN_INVALID", "run.json is missing the confidential seller");
+    const path = resolve(eventPath);
+    if (!existsSync(path) || (statSync(path).mode & 0o077) !== 0)
+        fail("DEMO_EVENTS_MISSING", "owner-only buyer event stream must exist before seller exit");
+    const events = readDemoEvents(path);
+    if (!events.length || events.some((event) => event.runId !== runId))
+        fail("DEMO_EVENTS_INVALID", "event stream belongs to another run");
+    const sessionId = required("session-id");
+    if (!events.some((event) => event.stage === "artifact-delivery" && event.status === "complete" && event.publicDetails.kind === "competitor-analysis" && event.publicDetails.sessionId === sessionId))
+        fail("DEMO_DELIVERY_MISSING", "buyer has not recorded the confidential artifact delivery for this session");
+    const windowStart = Number(required("window-start")), windowEnd = Number(required("window-end"));
+    if (!Number.isSafeInteger(windowStart) || !Number.isSafeInteger(windowEnd) || windowEnd <= windowStart || windowEnd - windowStart > 7 * 24 * 60 * 60_000)
+        fail("EXIT_WINDOW_INVALID", "owner exit window must be valid and last no more than seven days");
+    const db = new SellerDatabase(secret("SUPABASE_URL"), secret("SUPABASE_SERVICE_ROLE_KEY"));
+    const queued = await queueHostedExit(db, secret("SELLER_STATE_KEY"), { sellerId, runId, sessionId, windowStart, windowEnd });
+    if (!events.some((event) => event.actor === "confidential-seller" && event.stage === "delayed-exit" && event.publicDetails.operationId === queued.operationId)) {
+        new DemoEventLog(path, runId).append({ actor: "confidential-seller", stage: "delayed-exit", status: "complete", publicDetails: { state: "queued", sessionId, operationId: queued.operationId, amount: queued.amount, executeAt: queued.executeAt, windowEnd: queued.windowEnd }, evidenceHashes: [], explorerLinks: [] });
+    }
+    return { runId, eventPath: path, sessionId, sellerId: queued.sellerId, operationId: queued.operationId, status: queued.status, amount: queued.amount, executeAt: queued.executeAt, windowEnd: queued.windowEnd };
+}
+main().then((data) => process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.demo.v1", ok: true, command: "hosted-exit", data })}\n`)).catch((error) => { process.stdout.write(`${JSON.stringify(errorOutput(error))}\n`); process.exitCode = 1; });

package/dist/hosted-exit.d.ts

@@ -0,0 +1,24 @@
+import { SellerDatabase } from "./seller-database.js";
+export declare const hostedExitOperationId: (sessionId: string) => string;
+export interface HostedExitView {
+    sellerId: string;
+    runId: string;
+    sessionId: string;
+    operationId: string;
+    status: "queued" | "submitted" | "finalized";
+    amount: string;
+    executeAt: number;
+    windowEnd: number;
+}
+export declare function queueHostedExit(db: SellerDatabase, stateKey: string, input: {
+    sellerId: string;
+    runId: string;
+    sessionId: string;
+    windowStart: number;
+    windowEnd: number;
+}): Promise<HostedExitView>;
+export declare function inspectHostedExit(db: SellerDatabase, stateKey: string, input: {
+    sellerId: string;
+    runId: string;
+    sessionId: string;
+}): Promise<HostedExitView>;

package/dist/hosted-exit.js

@@ -0,0 +1,70 @@
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fail } from "./errors.js";
+import { executeMandated, loadMandate } from "./mandate.js";
+import { Phase3App } from "./phase3.js";
+import { captureSellerHome, decryptSellerSnapshot, encryptSellerSnapshot, restoreSellerHome } from "./seller-state.js";
+import { V2ExitQueue } from "./v2-exits.js";
+const STANDARD_EXIT_MIST = 1000000n;
+const validId = (value) => /^[a-zA-Z0-9._:-]{1,128}$/.test(value);
+export const hostedExitOperationId = (sessionId) => `remote-exit-${sessionId}`;
+async function withSeller(db, stateKey, sellerId, use) {
+    const stored = await db.getSnapshot(sellerId) ?? fail("SELLER_STATE_MISSING", "confidential seller snapshot is missing");
+    const snapshot = decryptSellerSnapshot(stored.payload, stateKey);
+    if (snapshot.sellerId !== sellerId)
+        fail("SELLER_IDENTITY_MISMATCH", "seller snapshot belongs to another role");
+    const root = mkdtempSync(join(tmpdir(), "supercuts-hosted-exit-")), home = join(root, "seller");
+    let app;
+    try {
+        restoreSellerHome(home, snapshot);
+        app = new Phase3App(home);
+        if (app.profile.role !== "seller" || app.profile.mock || app.profile.verifierVersion !== 2)
+            fail("LIVE_PROFILE_REQUIRED", "hosted exit needs the confidential seller's live v2 role");
+        const encoded = app.store.getSecret("live:sui-private-key")?.toString() ?? fail("LIVE_CREDENTIAL_MISSING", "seller signer is missing from its own snapshot");
+        const decoded = decodeSuiPrivateKey(encoded);
+        if (decoded.scheme !== "ED25519" || Ed25519Keypair.fromSecretKey(decoded.secretKey).toSuiAddress().toLowerCase() !== sellerId.toLowerCase())
+            fail("SELLER_IDENTITY_MISMATCH", "seller snapshot signer differs from the configured seller");
+        return await use(app, home, stored.revision, snapshot.artifacts);
+    }
+    finally {
+        app?.close();
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+function matchingPayment(app, sessionId, runId) {
+    const delivery = app.store.db.prepare("SELECT run_id FROM remote_deliveries WHERE session_id=?").get(sessionId);
+    if (!delivery || delivery.run_id !== runId)
+        fail("DELIVERY_NOT_FOUND", "seller has no delivered analysis for this run and session");
+    const note = app.store.db.prepare("SELECT commitment FROM notes WHERE operation_id=? AND role='payment'").get(sessionId) ?? fail("NOTE_NOT_FOUND", "seller has not recovered the matching payment note");
+    return note.commitment;
+}
+function view(app, sellerId, runId, sessionId) {
+    const commitment = matchingPayment(app, sessionId, runId);
+    const operationId = hostedExitOperationId(sessionId);
+    const queued = new V2ExitQueue(app.store).get(operationId) ?? fail("DEMO_EVIDENCE_MISMATCH", "seller has no queued standard exit");
+    if (queued.commitment !== commitment || queued.exactExit || queued.amount !== STANDARD_EXIT_MIST || !app.store.getSecret(`v2-exit-request:${operationId}`))
+        fail("DEMO_EVIDENCE_MISMATCH", "seller has no prepared standard exit for the recovered payment note");
+    return { sellerId, runId, sessionId, operationId, status: queued.status, amount: queued.amount.toString(), executeAt: queued.executeAt, windowEnd: queued.windowEnd };
+}
+export async function queueHostedExit(db, stateKey, input) {
+    if (!validId(input.runId) || !validId(input.sessionId) || !/^0x[0-9a-f]{64}$/i.test(input.sellerId))
+        fail("SELLER_REQUEST_INVALID", "seller, run, or session ID is invalid");
+    return withSeller(db, stateKey, input.sellerId, async (app, home, revision, artifacts) => {
+        const commitment = matchingPayment(app, input.sessionId, input.runId), operationId = hostedExitOperationId(input.sessionId);
+        if (!new V2ExitQueue(app.store).get(operationId)) {
+            if (!Number.isSafeInteger(input.windowStart) || input.windowStart < Date.now() + 60_000)
+                fail("EXIT_WINDOW_INVALID", "standard delayed exit must start at least one minute from now");
+            await executeMandated(app, loadMandate(home), "wallet.exit.queue", { "operation-id": operationId, commitment, amount: STANDARD_EXIT_MIST.toString(), "window-start": String(input.windowStart), "window-end": String(input.windowEnd) });
+            await db.putSnapshot(encryptSellerSnapshot(await captureSellerHome(home, input.sellerId, artifacts), stateKey), revision);
+        }
+        return view(app, input.sellerId, input.runId, input.sessionId);
+    });
+}
+export async function inspectHostedExit(db, stateKey, input) {
+    if (!validId(input.runId) || !validId(input.sessionId) || !/^0x[0-9a-f]{64}$/i.test(input.sellerId))
+        fail("SELLER_REQUEST_INVALID", "seller, run, or session ID is invalid");
+    return withSeller(db, stateKey, input.sellerId, async (app) => view(app, input.sellerId, input.runId, input.sessionId));
+}

package/dist/hosted-seller-import.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hosted-seller-import.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { fail } from "./errors.js";
+import { HostedSellerRepository } from "./hosted-seller-repository.js";
+import { Phase3App } from "./phase3.js";
+import { SellerDatabase } from "./seller-database.js";
+import { decryptSellerSnapshot, restoreSellerHome } from "./seller-state.js";
+const required = (name) => process.env[name] ?? fail("SELLER_CONFIG_MISSING", `${name} is required`);
+async function main() {
+    if (process.argv[2] !== "--writes-paused")
+        fail("SELLER_IMPORT_MAINTENANCE_REQUIRED", "pause hosted seller writes and pass --writes-paused");
+    const legacy = new SellerDatabase(required("SUPABASE_URL"), required("SUPABASE_SERVICE_ROLE_KEY"));
+    const repo = new HostedSellerRepository(required("SUPABASE_DB_URL"), required("SELLER_STATE_KEY"));
+    try {
+        const catalog = await legacy.listCatalog();
+        const sellerIds = [...new Set(catalog.map((row) => String(row.seller_id)))].sort();
+        if (!sellerIds.length)
+            fail("SELLER_STATE_MISSING", "catalog contains no hosted sellers");
+        const claimsBefore = await legacy.listPaymentClaims();
+        await repo.verifyLegacyCollections(catalog, claimsBefore);
+        const results = [];
+        const revisions = new Map();
+        for (const sellerId of sellerIds) {
+            const stored = await legacy.getSnapshot(sellerId) ?? fail("SELLER_STATE_MISSING", `snapshot is missing for ${sellerId}`);
+            revisions.set(sellerId, stored.revision);
+            const snapshot = decryptSellerSnapshot(stored.payload, required("SELLER_STATE_KEY"));
+            const root = mkdtempSync(join(tmpdir(), "supercuts-seller-verify-")), home = join(root, "seller");
+            let app;
+            try {
+                restoreSellerHome(home, snapshot);
+                app = new Phase3App(home);
+                if (app.profile.mock || app.profile.role !== "seller")
+                    fail("LIVE_PROFILE_REQUIRED", "import requires a live seller profile");
+                const encoded = app.store.getSecret("live:sui-private-key")?.toString() ?? fail("LIVE_CREDENTIAL_MISSING", "seller signer is missing");
+                const decoded = decodeSuiPrivateKey(encoded);
+                if (decoded.scheme !== "ED25519" || Ed25519Keypair.fromSecretKey(decoded.secretKey).toSuiAddress().toLowerCase() !== sellerId.toLowerCase())
+                    fail("SELLER_IDENTITY_MISMATCH", "snapshot signer differs from catalog seller");
+            }
+            finally {
+                app?.close();
+                rmSync(root, { recursive: true, force: true });
+            }
+            const imported = await repo.importSnapshot(snapshot, stored.revision);
+            const verified = await repo.verifyImport(sellerId);
+            if (verified.sourceHash !== imported.sourceHash || Object.values(verified.records).reduce((sum, count) => sum + count, 0) !== imported.records || verified.artifacts !== imported.artifacts)
+                fail("SELLER_IMPORT_MISMATCH", "seller readback differs from source snapshot");
+            results.push({ sellerId, capabilities: catalog.filter((row) => row.seller_id === sellerId).length, records: imported.records, artifacts: imported.artifacts, rowTypes: verified.records });
+        }
+        const claimsAfter = await legacy.listPaymentClaims();
+        if (JSON.stringify(claimsBefore) !== JSON.stringify(claimsAfter))
+            fail("SELLER_IMPORT_MISMATCH", "payment claims changed during migration");
+        if (JSON.stringify(catalog) !== JSON.stringify(await legacy.listCatalog()))
+            fail("SELLER_IMPORT_MISMATCH", "catalog changed during migration");
+        await repo.verifyLegacyCollections(catalog, claimsAfter);
+        for (const sellerId of sellerIds) {
+            const current = await legacy.getSnapshot(sellerId);
+            if (!current || current.revision !== revisions.get(sellerId))
+                fail("SELLER_IMPORT_MISMATCH", "seller snapshot changed during migration");
+        }
+        process.stdout.write(`${JSON.stringify({ ok: true, sellers: results, paymentClaims: claimsAfter.length, serviceCutoverReady: false })}\n`);
+    }
+    finally {
+        await repo.close();
+    }
+}
+main().catch((error) => { process.stderr.write(`${error instanceof Error ? error.message : "seller import failed"}\n`); process.exitCode = 1; });

package/dist/hosted-seller-repository.d.ts

@@ -0,0 +1,31 @@
+import type { SellerSnapshot } from "./seller-state.js";
+/** Direct Postgres connection used only by owner-side migration and seller processes. */
+export declare class HostedSellerRepository {
+    #private;
+    private readonly wrappingKey;
+    constructor(connectionString: string, wrappingKey: string);
+    close(): Promise<void>;
+    verifyLegacyCollections(catalog: Array<Record<string, unknown>>, claims: Array<{
+        digest: string;
+        request_id: string;
+        seller_id: string;
+    }>): Promise<void>;
+    /** Durable intent; the caller performs the network action after this returns. */
+    claimOperation(sellerId: string, operationId: string, action: string, inputHash: string): Promise<"prepared" | "unresolved" | "confirmed">;
+    transitionOperation(sellerId: string, operationId: string, status: "unresolved" | "confirmed", evidenceHash?: string): Promise<void>;
+    /** Payment digest and request ID are both unique across all hosted sellers. */
+    claimPayment(digest: string, requestId: string, sellerId: string): Promise<void>;
+    /** Import is one transaction. Replays must match the original source exactly. */
+    importSnapshot(snapshot: SellerSnapshot, sourceRevision: number): Promise<{
+        records: number;
+        artifacts: number;
+        sourceHash: string;
+    }>;
+    private insertRecords;
+    /** Readback authenticates every encrypted row and returns only safe counts. */
+    verifyImport(sellerId: string): Promise<{
+        sourceHash: string;
+        records: Record<string, number>;
+        artifacts: number;
+    }>;
+}