@supercuts-walrus/backend 0.1.0 → 0.1.2

package/dist/remote-buyer.d.ts

@@ -1,6 +1,18 @@
 import { type CapabilityManifest } from "./capability.js";
 import { type AgentMandate } from "./mandate.js";
 import type { Phase3App } from "./phase3.js";
+export declare function analysisAgreementDraft(input: {
+    sessionId: string;
+    transcriptHash: string;
+    serviceHash: string;
+    paymentAmount: string;
+    buyerPublicKey: string[];
+    counterparty: string;
+    capabilityId: string;
+    manifestHash: string;
+    now?: number;
+    scalar?: () => string;
+}): Record<string, unknown>;
 interface Entry {
     manifest: CapabilityManifest;
     blobId: string;
@@ -62,6 +74,12 @@ export declare class RemoteBuyer {
         sessionId: string;
         operationId: string;
     }): Promise<Record<string, unknown>>;
+    research(input: {
+        operationId: string;
+        runId: string;
+        topic: string;
+        budget: string;
+    }): Promise<Record<string, unknown>>;
     events(runId: string): Promise<Record<string, unknown>>;
 }
 export {};

package/dist/remote-buyer.js

@@ -5,10 +5,23 @@ import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
 import { validateCapabilityManifest, verifySignedCapability } from "./capability.js";
 import { fail } from "./errors.js";
 import { executeMandated } from "./mandate.js";
+export function analysisAgreementDraft(input) {
+    const scalar = input.scalar ?? (() => BigInt(`0x${randomBytes(16).toString("hex")}`).toString());
+    return {
+        sessionId: input.sessionId, rail: "shielded", dealId: scalar(), revision: "1",
+        transcriptRootLo: BigInt(`0x${input.transcriptHash.slice(0, 32)}`).toString(),
+        transcriptRootHi: BigInt(`0x${input.transcriptHash.slice(32)}`).toString(),
+        serviceDigestLo: BigInt(`0x${input.serviceHash.slice(0, 32)}`).toString(),
+        serviceDigestHi: BigInt(`0x${input.serviceHash.slice(32)}`).toString(),
+        settlementNonceLo: scalar(), settlementNonceHi: scalar(), paymentAmount: input.paymentAmount,
+        blinding: scalar(), expiry: String((input.now ?? Date.now()) + 30 * 60_000),
+        buyerPublicKey: input.buyerPublicKey, counterparty: input.counterparty,
+        capabilityId: input.capabilityId, manifestHash: input.manifestHash,
+    };
+}
 import { decryptSessionMessage, encryptSessionMessage } from "./negotiation.js";
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 const num = (value, name) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : fail("SELLER_PREVIEW_INVALID", `${name} must be between zero and one`);
-const halves = (content) => { const hash = sha256(content); return [BigInt(`0x${hash.slice(0, 32)}`).toString(), BigInt(`0x${hash.slice(32)}`).toString()]; };
 export class RemoteBuyer {
     app;
     mandate;
@@ -192,10 +205,15 @@ export class RemoteBuyer {
             fail("BUYER_PRIVACY_REQUIRED", "saved owner privacy rule did not select shielded settlement");
         const publicKey = this.app.store.getSecret("identity:x25519-public")?.toString("base64url") ?? fail("IDENTITY_MISSING", "buyer delivery key is missing");
         const identity = (await this.app.execute("doctor", {})).data;
-        const [transcriptRootLo, transcriptRootHi] = [BigInt(`0x${String(negotiated.transcriptHash).slice(0, 32)}`).toString(), BigInt(`0x${String(negotiated.transcriptHash).slice(32)}`).toString()];
-        const [serviceDigestLo, serviceDigestHi] = halves(JSON.stringify({ capabilityId: input.capabilityId, briefHash: input.briefHash, artifactSha256, deliveryPublicKey: publicKey }));
-        const scalar = () => BigInt(`0x${randomBytes(16).toString("hex")}`).toString();
-        const draft = { dealId: scalar(), revision: "1", transcriptRootLo, transcriptRootHi, serviceDigestLo, serviceDigestHi, settlementNonceLo: scalar(), settlementNonceHi: scalar(), paymentAmount: entry.manifest.priceBand.minimum, blinding: scalar(), expiry: String(Date.now() + 30 * 60_000), buyerPublicKey: identity.babyJubPublicKey, counterparty: entry.manifest.sellerId, capabilityId: entry.manifest.capabilityId, manifestHash: entry.manifest.manifestHash };
+        const serviceHash = sha256(JSON.stringify({ capabilityId: input.capabilityId, briefHash: input.briefHash, artifactSha256, deliveryPublicKey: publicKey }));
+        this.app.store.db.exec("CREATE TABLE IF NOT EXISTS remote_buyer_agreements(session_id TEXT PRIMARY KEY,context_hash TEXT NOT NULL,draft_json TEXT NOT NULL,created_at INTEGER NOT NULL)");
+        const contextHash = sha256(JSON.stringify({ capabilityId: input.capabilityId, operationId: input.operationId, sessionId: input.sessionId, runId: input.runId, briefHash: input.briefHash, transcriptHash: negotiated.transcriptHash, serviceHash, artifactSha256 }));
+        const priorDraft = this.app.store.db.prepare("SELECT context_hash AS contextHash,draft_json AS draftJson FROM remote_buyer_agreements WHERE session_id=?").get(input.sessionId);
+        if (priorDraft && priorDraft.contextHash !== contextHash)
+            fail("AGREEMENT_SESSION_CONFLICT", "analysis session identifies a different agreement context");
+        const draft = priorDraft ? JSON.parse(priorDraft.draftJson) : analysisAgreementDraft({ sessionId: input.sessionId, transcriptHash: String(negotiated.transcriptHash), serviceHash, paymentAmount: entry.manifest.priceBand.minimum, buyerPublicKey: identity.babyJubPublicKey, counterparty: entry.manifest.sellerId, capabilityId: entry.manifest.capabilityId, manifestHash: entry.manifest.manifestHash });
+        if (!priorDraft)
+            this.app.store.db.prepare("INSERT INTO remote_buyer_agreements(session_id,context_hash,draft_json,created_at) VALUES(?,?,?,?)").run(input.sessionId, contextHash, JSON.stringify(draft), Date.now());
         const signed = await this.request("/v1/agreement", { method: "POST", body: JSON.stringify({ capabilityId: input.capabilityId, sessionId: input.sessionId, runId: input.runId, briefHash: input.briefHash, deliveryPublicKey: publicKey, agreement: Buffer.from(JSON.stringify(draft)).toString("base64url") }) });
         if (signed.artifactSha256 !== artifactSha256 || signed.capabilityId !== input.capabilityId || signed.sessionId !== input.sessionId)
             fail("AGREEMENT_BINDING_MISMATCH", "seller response changed the prepared artifact or session");
@@ -227,5 +245,41 @@ export class RemoteBuyer {
         const recorded = (await this.app.execute("resource.fetch", { "request-id": input.sessionId, "operation-id": input.operationId, response: artifact.toString("base64url") })).data;
         return { status: "delivered", sessionId: input.sessionId, artifactSha256: response.artifactSha256, body: artifact.toString("utf8"), record: { deliveryStatus: recorded.deliveryStatus, responseHash: recorded.responseHash } };
     }
+    async research(input) {
+        if (!input.operationId || input.operationId.length > 256 || !/^[1-9][0-9]*$/.test(input.budget))
+            fail("BUYER_WORKFLOW_INVALID", "research requires a stable operation ID and positive total budget");
+        this.app.store.db.exec("CREATE TABLE IF NOT EXISTS remote_research_workflows(operation_id TEXT PRIMARY KEY,input_hash TEXT NOT NULL,created_at INTEGER NOT NULL,updated_at INTEGER NOT NULL,completed_at INTEGER)");
+        const inputHash = sha256(JSON.stringify({ runId: input.runId, topic: input.topic, budget: input.budget })), existing = this.app.store.db.prepare("SELECT input_hash AS inputHash,completed_at AS completedAt FROM remote_research_workflows WHERE operation_id=?").get(input.operationId);
+        if (existing && existing.inputHash !== inputHash)
+            fail("DEAL_OPERATION_CONFLICT", "research operation ID identifies another topic, budget, or run");
+        if (!existing)
+            this.app.store.db.prepare("INSERT INTO remote_research_workflows(operation_id,input_hash,created_at,updated_at) VALUES(?,?,?,?)").run(input.operationId, inputHash, Date.now(), Date.now());
+        const checkpoint = async (stage, action) => {
+            const key = `research:${input.operationId}:${stage}`, prior = this.app.store.getSecret(key);
+            if (prior)
+                return JSON.parse(prior.toString());
+            const value = await action();
+            this.app.store.putSecretOnce(key, Buffer.from(JSON.stringify(value)));
+            this.app.store.db.prepare("UPDATE remote_research_workflows SET updated_at=? WHERE operation_id=?").run(Date.now(), input.operationId);
+            return value;
+        };
+        const child = (stage) => `research:${stage}:${sha256(`${input.operationId}:${stage}`).slice(0, 40)}`;
+        const ranked = await checkpoint("selection", () => this.rankBriefs({ topic: input.topic, budget: input.budget }));
+        const winnerCapabilityId = String(ranked.winner?.capabilityId ?? "");
+        const analysisCapabilityId = String(ranked.analysisCapabilityId ?? "");
+        if (!winnerCapabilityId || !analysisCapabilityId)
+            fail("ANALYSIS_UNAVAILABLE", "ranked catalog has no affordable brief and matching analysis");
+        const brief = await checkpoint("brief", () => this.purchaseBrief({ capabilityId: winnerCapabilityId, operationId: child("brief-payment"), requestId: child("brief-request"), runId: input.runId, task: `Sui research: ${input.topic}`, budget: input.budget }));
+        const briefHash = String(brief.artifactSha256);
+        const sessionId = child("analysis-session"), paymentOperationId = child("analysis-payment");
+        const agreement = await checkpoint("agreement", () => this.agreement({ capabilityId: analysisCapabilityId, operationId: paymentOperationId, sessionId, runId: input.runId, briefHash }));
+        const settlement = await checkpoint("settlement", () => this.settleAnalysis({ sessionId, operationId: paymentOperationId }));
+        const analysis = await checkpoint("delivery", async () => {
+            const value = await this.delivery({ sessionId, operationId: paymentOperationId });
+            return value.status === "delivered" ? value : fail("DELIVERY_PENDING", "analysis payment is finalized and seller delivery is still pending; resume the same research operation");
+        });
+        this.app.store.db.prepare("UPDATE remote_research_workflows SET completed_at=COALESCE(completed_at,?),updated_at=? WHERE operation_id=?").run(Date.now(), Date.now(), input.operationId);
+        return { operationId: input.operationId, state: "complete", replayed: Boolean(existing?.completedAt), selection: ranked, brief, agreement, settlement, analysis };
+    }
     async events(runId) { return this.request(`/v1/events?runId=${encodeURIComponent(runId)}`); }
 }

package/dist/role-lock.d.ts

@@ -0,0 +1,8 @@
+export interface RoleHomeLease {
+    acquired: boolean;
+    ownerPid?: number;
+    release(): void;
+}
+/** Best-effort process lease. SQLite still owns data integrity; this prevents
+ * multiple long-running role workers from operating one role home at once. */
+export declare function acquireRoleHomeLease(home: string): RoleHomeLease;

package/dist/role-lock.js

@@ -0,0 +1,54 @@
+import { closeSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+function active(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Best-effort process lease. SQLite still owns data integrity; this prevents
+ * multiple long-running role workers from operating one role home at once. */
+export function acquireRoleHomeLease(home) {
+    const path = join(home, ".mcp.lock"), token = randomUUID();
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            writeSync(fd, `${JSON.stringify({ pid: process.pid, token, startedAt: Date.now() })}\n`);
+            closeSync(fd);
+            let released = false;
+            return { acquired: true, release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        const value = JSON.parse(readFileSync(path, "utf8"));
+                        if (value.token === token)
+                            unlinkSync(path);
+                    }
+                    catch { /* already removed */ }
+                } };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let ownerPid;
+            try {
+                ownerPid = Number(JSON.parse(readFileSync(path, "utf8")).pid);
+            }
+            catch { /* stale malformed lock */ }
+            if (ownerPid !== undefined && active(ownerPid))
+                return { acquired: false, ownerPid, release: () => { } };
+            try {
+                unlinkSync(path);
+            }
+            catch { /* another process won the cleanup race */ }
+        }
+    }
+    return { acquired: false, release: () => { } };
+}

package/dist/seller-catalog-generate.js

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

package/dist/seller-directory-cli.js

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

package/dist/seller-live-cli.js

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

package/dist/seller-package.d.ts

@@ -0,0 +1,9 @@
+export declare function packageHostedSeller(input: {
+    home: string;
+    spec: string;
+    artifact: string;
+    metadata: string;
+    registration: string;
+    bundle: string;
+    contentType?: string;
+}): Promise<Record<string, unknown>>;

package/dist/seller-package.js

@@ -0,0 +1,50 @@
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { createCapabilityManifest, validateCapabilityPayload } from "./capability.js";
+import { fail } from "./errors.js";
+import { executeMandated, loadMandate } from "./mandate.js";
+import { Phase3App } from "./phase3.js";
+const ownerFile = (path) => {
+    const value = resolve(path);
+    if ((statSync(value).mode & 0o077) !== 0)
+        fail("SELLER_CONFIG_PERMISSIONS", `${value} must be owner-only`);
+    return value;
+};
+export async function packageHostedSeller(input) {
+    if (![input.home, input.spec, input.artifact, input.metadata, input.registration, input.bundle].every((value) => typeof value === "string" && value.length > 0))
+        fail("ARGUMENT_REQUIRED", "seller package requires --home, --spec, --artifact, --metadata, --registration, and --bundle");
+    const specPath = ownerFile(input.spec), artifactPath = ownerFile(input.artifact), metadataPath = ownerFile(input.metadata);
+    const artifact = readFileSync(artifactPath);
+    if (!artifact.length || artifact.length > 10 * 1024 * 1024)
+        fail("SELLER_ARTIFACT_INVALID", "hosted artifact must contain 1 byte to 10 MiB");
+    const spec = JSON.parse(readFileSync(specPath, "utf8"));
+    const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+    const home = resolve(input.home), app = new Phase3App(home);
+    try {
+        if (app.profile.role !== "seller" || app.profile.mock || app.profile.verifierVersion !== 2)
+            fail("SELLER_POOL_VERSION_MISMATCH", "hosted packaging requires a separate live v2 seller role home");
+        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")
+            fail("SIGNER_UNSUPPORTED", "seller requires an ED25519 signer");
+        const signer = Ed25519Keypair.fromSecretKey(decoded.secretKey), manifest = createCapabilityManifest({ ...spec, sellerId: signer.toSuiAddress() });
+        validateCapabilityPayload(manifest, "output", metadata);
+        const published = await executeMandated(app, loadMandate(home), "capability.publish", { "operation-id": `publish-${manifest.manifestHash}`, manifest });
+        const manifestBlobId = String(published.blobId ?? "");
+        if (!manifestBlobId)
+            fail("WALRUS_PUBLISH_FAILED", "capability publication omitted a Walrus blob ID");
+        const transportPublicKey = app.store.getSecret("identity:x25519-public")?.toString("base64url") ?? fail("IDENTITY_MISSING", "seller transport key is missing");
+        const sellerSignature = (await signer.signPersonalMessage(Buffer.from(`${manifest.manifestHash}:${transportPublicKey}`))).signature;
+        const registration = { manifest, manifestBlobId, transportPublicKey, sellerSignature };
+        const registrationPath = resolve(input.registration), bundlePath = resolve(input.bundle);
+        writeFileSync(registrationPath, `${JSON.stringify(registration, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        const bundle = { sellers: [{ sellerId: manifest.sellerId, home, capabilities: [{ registrationFile: registrationPath, artifactFile: artifactPath, outputMetadata: metadata, contentType: input.contentType ?? "application/octet-stream" }] }] };
+        writeFileSync(bundlePath, `${JSON.stringify(bundle, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        return { sellerId: manifest.sellerId, capabilityId: manifest.capabilityId, manifestHash: manifest.manifestHash, manifestBlobId, registrationFile: registrationPath, provisioningBundle: bundlePath, nextCommand: `supercuts-seller-v2-provision ${JSON.stringify(bundlePath)}` };
+    }
+    finally {
+        app.close();
+    }
+}

package/dist/seller-provision.js

@@ -48,6 +48,8 @@ async function main() {
                         catch (error) {
                             return fail("BRIEF_INVALID", "market brief must be JSON", error);
                         }
+                        if (report.reviewStatus !== "approved")
+                            fail("ARTIFACT_REVIEW_REQUIRED", "market brief must be owner-reviewed before provisioning");
                         if (typeof report.title !== "string" || typeof report.body !== "string" || !Array.isArray(report.citations) || report.citations.length < 2 || report.citations.some((value) => typeof value !== "string" || !/^https:\/\//.test(value)))
                             fail("BRIEF_INVALID", "market brief needs a title, body, and at least two HTTPS citations");
                     }
@@ -56,7 +58,19 @@ async function main() {
                 for (const [briefHash, artifactPath] of Object.entries(capability.variants ?? {})) {
                     if (!/^[0-9a-f]{64}$/.test(briefHash))
                         fail("SELLER_CONFIG_INVALID", "variant brief hash is invalid");
-                    artifacts[`${manifest.capabilityId}:${briefHash}`] = readFileSync(resolve(artifactPath)).toString("base64url");
+                    const body = readFileSync(resolve(artifactPath));
+                    if (manifest.capability === "sui.competitor-analysis") {
+                        let report;
+                        try {
+                            report = JSON.parse(body.toString());
+                        }
+                        catch (error) {
+                            return fail("ANALYSIS_INVALID", "competitor analysis must be JSON", error);
+                        }
+                        if (report.reviewStatus !== "approved")
+                            fail("ARTIFACT_REVIEW_REQUIRED", "competitor analysis must be owner-reviewed before provisioning");
+                    }
+                    artifacts[`${manifest.capabilityId}:${briefHash}`] = body.toString("base64url");
                 }
                 if (!capability.artifact && !Object.keys(capability.variants ?? {}).length)
                     fail("SELLER_ARTIFACT_MISSING", "capability needs a prepared artifact or brief variants");

package/dist/seller-research.d.ts

@@ -0,0 +1,50 @@
+export type SellerResearchKind = "market-brief" | "competitor-analysis";
+export interface SellerResearchDraft {
+    title: string;
+    body: string;
+    citations: string[];
+    preview: {
+        summary: string;
+        relevance: number;
+        sourceQuality: number;
+        freshnessDays: number;
+    };
+    reviewStatus: "draft-needs-owner-review";
+    research: {
+        model: string;
+        generatedAt: string;
+        sourceCount: number;
+        topic: string;
+        kind: SellerResearchKind;
+    };
+}
+export interface SellerResearchOptions {
+    apiKey?: string;
+    model?: string;
+    fetch?: typeof globalThis.fetch;
+    maxSearches?: number;
+    maxTokens?: number;
+    allowedDomains?: string[];
+    now?: Date;
+}
+/** Generates an owner-review draft. It never publishes or mutates a live seller. */
+export declare class ClaudeSellerResearcher {
+    #private;
+    readonly model: string;
+    constructor(options?: SellerResearchOptions);
+    research(input: {
+        kind: SellerResearchKind;
+        topic: string;
+        context?: Record<string, unknown>;
+    }): Promise<SellerResearchDraft>;
+}
+export declare function generateSellerResearch(input: {
+    kind: string;
+    topic: string;
+    output: string;
+    contextFile?: string;
+    allowedDomains?: string;
+    apiKey?: string;
+    model?: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<Record<string, unknown>>;

package/dist/seller-research.js

@@ -0,0 +1,210 @@
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fail } from "./errors.js";
+const asObject = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : fail("SELLER_RESEARCH_INVALID", "Claude research output must be an object");
+const submittedTool = (blocks) => {
+    for (const block of blocks)
+        if (block?.type === "tool_use" && block.name === "submit_research") {
+            if (block.input && typeof block.input === "object" && !Array.isArray(block.input))
+                return block;
+            if (typeof block.input === "string")
+                try {
+                    const input = JSON.parse(block.input);
+                    if (input && typeof input === "object" && !Array.isArray(input))
+                        return { ...block, input };
+                }
+                catch { }
+        }
+    return undefined;
+};
+const normalizedUrl = (value) => { const url = new URL(value); url.hash = ""; if (url.pathname !== "/")
+    url.pathname = url.pathname.replace(/\/$/, ""); return url.toString(); };
+function sourceUrls(value, found = new Set()) {
+    if (Array.isArray(value))
+        for (const item of value)
+            sourceUrls(item, found);
+    else if (value && typeof value === "object")
+        for (const [key, item] of Object.entries(value)) {
+            if (key === "url" && typeof item === "string") {
+                try {
+                    if (new URL(item).protocol === "https:")
+                        found.add(normalizedUrl(item));
+                }
+                catch { }
+            }
+            sourceUrls(item, found);
+        }
+    return found;
+}
+function validateDraft(value, evidence, allowedDomains) {
+    const draft = asObject(value), preview = asObject(draft.preview);
+    if (typeof draft.title !== "string" || draft.title.trim().length < 8 || draft.title.length > 180)
+        fail("SELLER_RESEARCH_INVALID", "research title must contain 8 to 180 characters");
+    if (typeof draft.body !== "string" || draft.body.trim().length < 800 || draft.body.length > 16_000)
+        fail("SELLER_RESEARCH_INVALID", "research body must contain 800 to 16,000 characters");
+    if (!Array.isArray(draft.citations))
+        fail("SELLER_RESEARCH_INVALID", "research citations must be an array");
+    if (draft.citations.length < 3 || draft.citations.length > 32)
+        fail("SELLER_RESEARCH_INVALID", `research must contain 3 to 32 citations; received ${draft.citations.length}`);
+    let citations = draft.citations.map((item) => {
+        if (typeof item !== "string")
+            return fail("SELLER_RESEARCH_INVALID", "every citation must be an HTTPS URL");
+        let url;
+        try {
+            url = new URL(item);
+        }
+        catch (error) {
+            return fail("SELLER_RESEARCH_INVALID", "every citation must be a valid URL", error);
+        }
+        if (url.protocol !== "https:" || url.username || url.password)
+            fail("SELLER_RESEARCH_INVALID", "every citation must be a public HTTPS URL without credentials");
+        if (allowedDomains.length && !allowedDomains.some((domain) => url.hostname === domain || url.hostname.endsWith(`.${domain}`)))
+            fail("SELLER_RESEARCH_SOURCE_UNAPPROVED", `citation host ${url.hostname} is outside --allowed-domains`);
+        const normalized = normalizedUrl(item);
+        if (!evidence.has(normalized))
+            fail("SELLER_RESEARCH_SOURCE_UNVERIFIED", "Claude cited a URL that was not returned by web search");
+        return normalized;
+    });
+    if (new Set(citations).size !== citations.length)
+        fail("SELLER_RESEARCH_INVALID", "research citations must be unique");
+    let reportBody = draft.body.trim();
+    const markers = [...reportBody.matchAll(/\[([1-9][0-9]*)\]/g)].map((match) => Number(match[1]));
+    if (markers.some((index) => index > citations.length))
+        fail("SELLER_RESEARCH_INVALID", "research body contains an out-of-range citation marker");
+    const used = [...new Set(markers)].sort((a, b) => a - b);
+    if (used.length < 3)
+        fail("SELLER_RESEARCH_INVALID", "research body must reference at least three listed sources inline");
+    if (used.length !== citations.length) {
+        const remap = new Map(used.map((oldIndex, newIndex) => [oldIndex, newIndex + 1]));
+        reportBody = reportBody.replace(/\[([1-9][0-9]*)\]/g, (_marker, raw) => `[${remap.get(Number(raw))}]`);
+        citations = used.map((index) => citations[index - 1]);
+    }
+    if (typeof preview.summary !== "string" || preview.summary.trim().length < 30 || preview.summary.length > 400)
+        fail("SELLER_RESEARCH_INVALID", "preview summary must contain 30 to 400 characters");
+    for (const key of ["relevance", "sourceQuality"])
+        if (typeof preview[key] !== "number" || !Number.isFinite(preview[key]) || preview[key] < 0 || preview[key] > 1)
+            fail("SELLER_RESEARCH_INVALID", `preview ${key} must be in [0,1]`);
+    if (!Number.isInteger(preview.freshnessDays) || preview.freshnessDays < 0 || preview.freshnessDays > 365)
+        fail("SELLER_RESEARCH_INVALID", "preview freshnessDays must be an integer in [0,365]");
+    return { title: draft.title.trim(), body: reportBody, citations, preview: { summary: preview.summary.trim(), relevance: preview.relevance, sourceQuality: preview.sourceQuality, freshnessDays: preview.freshnessDays } };
+}
+/** Generates an owner-review draft. It never publishes or mutates a live seller. */
+export class ClaudeSellerResearcher {
+    model;
+    #apiKey;
+    #fetch;
+    #maxSearches;
+    #maxTokens;
+    #allowedDomains;
+    #now;
+    constructor(options = {}) {
+        this.#apiKey = options.apiKey ?? process.env.CLAUDE_API_KEY ?? "";
+        if (!this.#apiKey)
+            fail("CLAUDE_CREDENTIAL_MISSING", "CLAUDE_API_KEY is required to generate a seller research draft");
+        this.model = options.model ?? process.env.CLAUDE_RESEARCH_MODEL ?? process.env.CLAUDE_MODEL ?? "claude-haiku-5-5";
+        this.#fetch = options.fetch ?? fetch;
+        this.#maxSearches = options.maxSearches ?? 8;
+        this.#maxTokens = options.maxTokens ?? 5_000;
+        this.#allowedDomains = (options.allowedDomains ?? []).map((item) => item.trim().toLowerCase()).filter(Boolean);
+        this.#now = options.now ?? new Date();
+        if (!Number.isInteger(this.#maxSearches) || this.#maxSearches < 3 || this.#maxSearches > 12 || !Number.isInteger(this.#maxTokens) || this.#maxTokens < 1_500 || this.#maxTokens > 8_192)
+            fail("CLAUDE_LIMIT_INVALID", "seller research bounds are invalid");
+        if (this.#allowedDomains.some((item) => !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(item)))
+            fail("SELLER_RESEARCH_INVALID", "allowed domains must be bare DNS names");
+    }
+    async research(input) {
+        if (!["market-brief", "competitor-analysis"].includes(input.kind) || !input.topic.trim() || input.topic.length > 500)
+            fail("SELLER_RESEARCH_INVALID", "research needs a valid kind and a topic of at most 500 characters");
+        const context = input.context ? JSON.stringify(input.context) : "none";
+        if (context.length > 40_000)
+            fail("SELLER_RESEARCH_INVALID", "matching brief context is too large");
+        const schema = {
+            type: "object", additionalProperties: false,
+            properties: {
+                title: { type: "string", maxLength: 180 }, body: { type: "string", maxLength: 16000 }, citations: { type: "array", minItems: 3, maxItems: 32, items: { type: "string" } },
+                preview: { type: "object", additionalProperties: false, properties: { summary: { type: "string", maxLength: 400 }, relevance: { type: "number", minimum: 0, maximum: 1 }, sourceQuality: { type: "number", minimum: 0, maximum: 1 }, freshnessDays: { type: "integer", minimum: 0, maximum: 365 } }, required: ["summary", "relevance", "sourceQuality", "freshnessDays"] },
+            }, required: ["title", "body", "citations", "preview"],
+        };
+        const webSearch = { type: "web_search_20250305", name: "web_search", max_uses: this.#maxSearches, allowed_callers: ["direct"] };
+        if (this.#allowedDomains.length)
+            webSearch.allowed_domains = this.#allowedDomains;
+        const system = `<role>You are the research desk for a paid Sui ecosystem intelligence seller.</role>
+<quality_bar>Use web search before writing. Prefer primary sources, official documentation, project announcements, repositories, and dated first-party metrics. Cross-check material claims across independent sources. Separate observed facts from analysis, name dates and measurement windows, surface uncertainty and counter-evidence, and never invent a fact, quotation, number, or URL. The report must be useful to a technically sophisticated buyer, not promotional copy.</quality_bar>
+<format>After research and a final self-check, call submit_research exactly once. Write a cohesive 800-16000 character report. Include inline source markers such as [1] that correspond in order to the citations array. Use only HTTPS URLs actually returned by web_search. Provide at least 3 unique sources and include additional material sources when useful. Preview scores are seller estimates, not independent guarantees.</format>`;
+        const prompt = `<today>${this.#now.toISOString().slice(0, 10)}</today><kind>${input.kind}</kind><topic>${input.topic.trim()}</topic><matching_brief_context>${context}</matching_brief_context><instructions>Research the topic broadly enough to identify market structure, concrete evidence, important competitors or alternatives, risks, and what would change the conclusion. For competitor analysis, directly compare the purchased brief's thesis with named competing projects or approaches. Before submission, verify every citation was observed in search results and every quantitative claim is qualified by date and source.</instructions>`;
+        const request = async (payload) => {
+            let response;
+            try {
+                response = await this.#fetch("https://api.anthropic.com/v1/messages", { method: "POST", headers: { "content-type": "application/json", "anthropic-version": "2023-06-01", "x-api-key": this.#apiKey }, body: JSON.stringify(payload), signal: AbortSignal.timeout(90_000) });
+            }
+            catch (error) {
+                return fail("CLAUDE_UNAVAILABLE", "Claude research request failed closed", error);
+            }
+            if (!response.ok) {
+                await response.arrayBuffer();
+                return fail("CLAUDE_UNAVAILABLE", `Claude research returned status ${response.status}`);
+            }
+            try {
+                return await response.json();
+            }
+            catch (error) {
+                return fail("CLAUDE_OUTPUT_INVALID", "Claude research returned invalid JSON", error);
+            }
+        };
+        const submitTool = { name: "submit_research", description: "Submit the source-checked seller research draft for owner review.", input_schema: schema };
+        let messages = [{ role: "user", content: prompt }], selected;
+        const blocks = [];
+        for (let turn = 0; turn < 3; turn++) {
+            const body = await request({ model: this.model, max_tokens: this.#maxTokens, system, messages, tools: [webSearch, submitTool] });
+            const current = Array.isArray(body.content) ? body.content : [];
+            blocks.push(...current);
+            selected = submittedTool(current);
+            if (selected || current.some((block) => block?.type === "text" && typeof block.text === "string" && block.text.trim()))
+                break;
+            if (!current.length || turn === 2)
+                break;
+            // Anthropic can pause a server-side search turn. Replay its opaque content
+            // unchanged so the model can synthesize the already-returned evidence.
+            messages = [...messages, { role: "assistant", content: current }, { role: "user", content: "Continue the paused research turn using the returned search evidence, then submit the structured draft." }];
+        }
+        const searchFailure = blocks.some((block) => block?.type === "web_search_tool_result" && (block.is_error === true || block.content?.type === "web_search_tool_result_error"));
+        if (searchFailure)
+            fail("SELLER_RESEARCH_SEARCH_FAILED", "Claude web search failed; no draft was written");
+        const evidence = sourceUrls(blocks);
+        if (evidence.size < 3)
+            fail("SELLER_RESEARCH_SOURCE_UNVERIFIED", "Claude returned fewer than three verifiable web-search sources");
+        if (selected)
+            try {
+                const draft = validateDraft(selected.input, evidence, this.#allowedDomains);
+                return { ...draft, reviewStatus: "draft-needs-owner-review", research: { model: this.model, generatedAt: this.#now.toISOString(), sourceCount: evidence.size, topic: input.topic.trim(), kind: input.kind } };
+            }
+            catch { }
+        const researchedText = blocks.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n").slice(0, 30_000) || (selected ? JSON.stringify(selected.input).slice(0, 30_000) : "");
+        if (!researchedText)
+            fail("CLAUDE_OUTPUT_INVALID", "Claude returned search evidence without a research answer");
+        const editorSystem = `<role>You are a strict research editor.</role><instructions>Convert or repair the supplied web-researched answer into the submit_research schema. Preserve material uncertainty, dates, comparisons, and counter-evidence. Use only URLs in verified_sources, include at least 3 unique citations and all additional material sources, and do not add facts or sources. The body must be 800-16000 characters and use [1], [2], and subsequent inline markers corresponding to citation order. Ensure preview is an object with summary, relevance, sourceQuality, and integer freshnessDays. Call submit_research exactly once.</instructions>`;
+        const edited = await request({ model: this.model, max_tokens: this.#maxTokens, system: editorSystem, messages: [{ role: "user", content: JSON.stringify({ kind: input.kind, topic: input.topic.trim(), researchedAnswer: researchedText, verifiedSources: [...evidence].slice(0, 32) }) }], tools: [submitTool], tool_choice: { type: "tool", name: "submit_research" } });
+        const editedBlocks = Array.isArray(edited.content) ? edited.content : [];
+        selected = submittedTool(editedBlocks);
+        if (!selected)
+            fail("CLAUDE_OUTPUT_INVALID", "Claude did not submit a structured research draft");
+        const draft = validateDraft(selected.input, evidence, this.#allowedDomains);
+        return { ...draft, reviewStatus: "draft-needs-owner-review", research: { model: this.model, generatedAt: this.#now.toISOString(), sourceCount: evidence.size, topic: input.topic.trim(), kind: input.kind } };
+    }
+}
+export async function generateSellerResearch(input) {
+    const kind = input.kind;
+    const output = resolve(input.output || fail("ARGUMENT_REQUIRED", "seller research requires --output"));
+    let context;
+    if (input.contextFile) {
+        const path = resolve(input.contextFile);
+        if ((statSync(path).mode & 0o077) !== 0)
+            fail("SELLER_CONFIG_PERMISSIONS", "research context file must be owner-only");
+        context = asObject(JSON.parse(readFileSync(path, "utf8")));
+    }
+    const allowedDomains = input.allowedDomains?.split(",").map((item) => item.trim()).filter(Boolean);
+    const researcher = new ClaudeSellerResearcher({ ...(input.apiKey ? { apiKey: input.apiKey } : {}), ...(input.model ? { model: input.model } : {}), ...(input.fetch ? { fetch: input.fetch } : {}), ...(allowedDomains?.length ? { allowedDomains } : {}) });
+    const draft = await researcher.research({ kind, topic: input.topic, ...(context ? { context } : {}) });
+    writeFileSync(output, `${JSON.stringify(draft, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    return { output, kind, topic: input.topic, model: researcher.model, citations: draft.citations.length, reviewStatus: draft.reviewStatus, nextStep: "Review every claim and citation, then set reviewStatus to approved before catalog generation or seller packaging." };
+}

package/dist/seller-scaffold.d.ts

@@ -0,0 +1 @@
+export declare function scaffoldSeller(input: Record<string, string | boolean>): Record<string, unknown>;