@supercuts-walrus/backend 0.0.0-stage → 0.1.1

package/dist/seller-state.js

@@ -0,0 +1,60 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { backup, DatabaseSync } from "node:sqlite";
+import { fail } from "./errors.js";
+const FILES = ["profile.json", "mandate.json", "state.key", "state.sqlite"];
+function keyBytes(encoded) {
+    const key = Buffer.from(encoded, "base64url");
+    if (key.length !== 32)
+        fail("SELLER_STATE_KEY_INVALID", "seller snapshot key must contain 32 bytes");
+    return key;
+}
+export function encryptSellerSnapshot(snapshot, encodedKey) {
+    const nonce = randomBytes(12), cipher = createCipheriv("aes-256-gcm", keyBytes(encodedKey), nonce);
+    cipher.setAAD(Buffer.from(`supercuts-seller-state-v1:${snapshot.sellerId}`));
+    const ciphertext = Buffer.concat([cipher.update(JSON.stringify(snapshot)), cipher.final()]);
+    return { version: 1, sellerId: snapshot.sellerId, nonce: nonce.toString("base64url"), tag: cipher.getAuthTag().toString("base64url"), ciphertext: ciphertext.toString("base64url") };
+}
+export function decryptSellerSnapshot(value, encodedKey) {
+    try {
+        if (value.version !== 1 || !value.sellerId)
+            fail("SELLER_STATE_INVALID", "seller snapshot version or identity is invalid");
+        const decipher = createDecipheriv("aes-256-gcm", keyBytes(encodedKey), Buffer.from(value.nonce, "base64url"));
+        decipher.setAAD(Buffer.from(`supercuts-seller-state-v1:${value.sellerId}`));
+        decipher.setAuthTag(Buffer.from(value.tag, "base64url"));
+        const snapshot = JSON.parse(Buffer.concat([decipher.update(Buffer.from(value.ciphertext, "base64url")), decipher.final()]).toString());
+        if (snapshot.version !== 1 || snapshot.sellerId !== value.sellerId || !snapshot.artifacts || typeof snapshot.artifacts !== "object" || FILES.some((name) => typeof snapshot.files?.[name] !== "string"))
+            fail("SELLER_STATE_INVALID", "seller snapshot contents are invalid");
+        return snapshot;
+    }
+    catch (error) {
+        return fail("SELLER_STATE_DECRYPT_FAILED", "seller snapshot could not be authenticated", error);
+    }
+}
+export async function captureSellerHome(home, sellerId, artifacts = {}) {
+    const db = new DatabaseSync(join(home, "state.sqlite"), { readOnly: true });
+    const temporary = join(home, `snapshot-${randomBytes(8).toString("hex")}.sqlite`);
+    try {
+        await backup(db, temporary);
+        const files = {};
+        for (const name of FILES)
+            files[name] = readFileSync(name === "state.sqlite" ? temporary : join(home, name)).toString("base64url");
+        return { version: 1, sellerId, files, artifacts };
+    }
+    finally {
+        db.close();
+        if (existsSync(temporary)) {
+            const { unlinkSync } = await import("node:fs");
+            unlinkSync(temporary);
+        }
+    }
+}
+export function restoreSellerHome(home, snapshot) {
+    if (!snapshot.sellerId || snapshot.version !== 1)
+        fail("SELLER_STATE_INVALID", "seller snapshot identity is invalid");
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    chmodSync(home, 0o700);
+    for (const name of FILES)
+        writeFileSync(join(home, name), Buffer.from(snapshot.files[name], "base64url"), { mode: 0o600, flag: "wx" });
+}

package/dist/seller-stdio.d.ts

@@ -0,0 +1,6 @@
+import type { Readable, Writable } from "node:stream";
+import { SellerRuntime } from "./seller-runtime.js";
+/** Local JSONL adapter. The host owns the seller signer, payment verifier,
+ * handler, and Walrus transport; callers receive only public registration
+ * metadata and encrypted delivery references. */
+export declare function serveSellerStdio(runtime: SellerRuntime, input?: Readable, output?: Writable): Promise<void>;

package/dist/seller-stdio.js

@@ -0,0 +1,29 @@
+import { createInterface } from "node:readline";
+import { SupercutsError } from "./errors.js";
+/** Local JSONL adapter. The host owns the seller signer, payment verifier,
+ * handler, and Walrus transport; callers receive only public registration
+ * metadata and encrypted delivery references. */
+export async function serveSellerStdio(runtime, input = process.stdin, output = process.stdout) {
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let queue = Promise.resolve();
+    const send = (value) => { output.write(`${JSON.stringify(value)}\n`); };
+    for await (const line of lines) {
+        queue = queue.then(async () => {
+            let id = null;
+            try {
+                if (Buffer.byteLength(line) > 1024 * 1024)
+                    throw new SupercutsError("SELLER_REQUEST_INVALID", "seller stdio request exceeds 1 MiB");
+                const parsed = JSON.parse(line);
+                if (!parsed || typeof parsed.id !== "string" || !parsed.id || !["catalog", "fulfill"].includes(parsed.method))
+                    throw new SupercutsError("SELLER_REQUEST_INVALID", "seller stdio method or request ID is invalid");
+                id = parsed.id;
+                const result = parsed.method === "catalog" ? { capabilities: runtime.catalog() } : await runtime.fulfill(parsed.params);
+                send({ id, ok: true, result });
+            }
+            catch (error) {
+                send({ id, ok: false, error: { code: error instanceof SupercutsError ? error.code : "SELLER_REQUEST_FAILED", message: error instanceof SupercutsError ? error.message : "seller request failed" } });
+            }
+        });
+    }
+    await queue;
+}

package/dist/seller-v2-provision.d.ts

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

package/dist/seller-v2-provision.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { verifySignedCapability, validateCapabilityPayload } from "./capability.js";
+import { fail } from "./errors.js";
+import { SellerDatabase } from "./seller-database.js";
+import { captureSellerHome, decryptSellerSnapshot, encryptSellerSnapshot } from "./seller-state.js";
+import { Phase3App } from "./phase3.js";
+async function main() {
+    const configPath = resolve(process.argv[2] ?? fail("ARGUMENT_REQUIRED", "usage: supercuts-seller-v2-provision <owner-only-config.json>"));
+    if ((statSync(configPath).mode & 0o077) !== 0)
+        fail("SELLER_CONFIG_PERMISSIONS", "provision config must be owner-only");
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    if (!Array.isArray(config.sellers) || !config.sellers.length)
+        fail("SELLER_CONFIG_INVALID", "at least one seller is required");
+    const required = (key) => process.env[key] ?? fail("SELLER_CONFIG_MISSING", `${key} is required`);
+    const db = new SellerDatabase(required("SUPABASE_URL"), required("SUPABASE_SERVICE_ROLE_KEY"));
+    const stateKey = required("SELLER_STATE_KEY"), origin = new URL(required("SELLER_ORIGIN")).origin;
+    for (const seller of config.sellers) {
+        const stored = await db.getSnapshot(seller.sellerId);
+        let snapshot;
+        if (stored)
+            snapshot = decryptSellerSnapshot(stored.payload, stateKey);
+        else {
+            if (!seller.home)
+                fail("SELLER_STATE_MISSING", "new hosted v2 seller requires its separate local role home");
+            const home = resolve(seller.home);
+            if ((statSync(home).mode & 0o077) !== 0)
+                fail("SELLER_CONFIG_PERMISSIONS", "seller role home must be owner-only");
+            const app = new Phase3App(home);
+            try {
+                if (app.profile.role !== "seller" || app.profile.mock || app.profile.verifierVersion !== 2)
+                    fail("SELLER_POOL_VERSION_MISMATCH", "new hosted v2 seller requires a 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" || Ed25519Keypair.fromSecretKey(decoded.secretKey).toSuiAddress() !== seller.sellerId)
+                    fail("SELLER_IDENTITY_MISMATCH", "v2 seller home signer differs from configured seller ID");
+                snapshot = await captureSellerHome(home, seller.sellerId);
+            }
+            finally {
+                app.close();
+            }
+        }
+        const profile = JSON.parse(Buffer.from(snapshot.files["profile.json"], "base64url").toString());
+        if (profile.role !== "seller" || profile.mock || profile.verifierVersion !== 2)
+            fail("SELLER_POOL_VERSION_MISMATCH", "v2 capability cannot use a v1 seller snapshot; create a separate v2 role home");
+        const registrations = [];
+        for (const item of seller.capabilities) {
+            const path = resolve(item.registrationFile);
+            if ((statSync(path).mode & 0o077) !== 0)
+                fail("SELLER_CONFIG_PERMISSIONS", "registration file must be owner-only");
+            const registration = JSON.parse(readFileSync(path, "utf8"));
+            await verifySignedCapability(registration);
+            if (registration.manifest.sellerId !== seller.sellerId || new URL(registration.manifest.endpoint).origin !== origin || !new URL(registration.manifest.endpoint).pathname.startsWith("/v2/resource/"))
+                fail("SELLER_CONFIG_INVALID", "v2 registration seller or endpoint differs from the hosted service");
+            validateCapabilityPayload(registration.manifest, "output", item.outputMetadata);
+            const artifact = readFileSync(resolve(item.artifactFile));
+            if (!artifact.length || artifact.length > 10 * 1024 * 1024)
+                fail("SELLER_ARTIFACT_INVALID", "v2 artifact must be 1 byte to 10 MiB");
+            snapshot.artifacts[registration.manifest.capabilityId] = artifact.toString("base64url");
+            registrations.push({ registration, item });
+        }
+        await db.putSnapshot(encryptSellerSnapshot(snapshot, stateKey), stored?.revision);
+        for (const { registration, item } of registrations)
+            await db.putCatalog({ seller_id: seller.sellerId, capability_id: registration.manifest.capabilityId, manifest: registration.manifest, blob_id: registration.manifestBlobId, signature: registration.sellerSignature, transport_public_key: registration.transportPublicKey, preview: { genericV2: true, outputMetadata: item.outputMetadata, contentType: item.contentType ?? "application/octet-stream" } });
+        process.stdout.write(`${JSON.stringify({ ok: true, sellerId: seller.sellerId, capabilities: registrations.map(({ registration }) => registration.manifest.capabilityId), restartRequired: true })}\n`);
+    }
+}
+main().catch((error) => { process.stderr.write(`${error instanceof Error ? error.message : "v2 provisioning failed"}\n`); process.exitCode = 1; });

package/dist/seller-watch.d.ts

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

package/dist/seller-watch.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { fail } from "./errors.js";
+import { parseArgs } from "./phase3.js";
+const args = parseArgs(process.argv.slice(2));
+const required = (name) => typeof args[name] === "string" ? args[name] : fail("ARGUMENT_REQUIRED", `--${name} is required`);
+const origin = new URL(required("seller-url")), sellerId = required("seller-id"), runId = required("run-id");
+if (origin.protocol !== "https:" && !(origin.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(origin.hostname)))
+    fail("SELLER_ORIGIN_INVALID", "seller URL must use HTTPS except on loopback");
+let stopped = false, seen = 0;
+process.on("SIGINT", () => { stopped = true; });
+process.on("SIGTERM", () => { stopped = true; });
+const line = (value) => process.stdout.write(`${value}\n`);
+try {
+    const catalogResponse = await fetch(new URL("/v1/catalog", origin), { signal: AbortSignal.timeout(90_000) });
+    if (!catalogResponse.ok)
+        fail("SELLER_SERVICE_UNAVAILABLE", `catalog returned ${catalogResponse.status}`);
+    const catalog = await catalogResponse.json();
+    const offered = catalog.capabilities?.filter((item) => item.manifest.sellerId === sellerId).map((item) => item.manifest.capabilityId) ?? [];
+    if (!offered.length)
+        fail("SELLER_ID_UNKNOWN", "seller does not appear in the remote catalog");
+    line(`[${sellerId.slice(0, 10)}] online · ${offered.join(", ")}`);
+    while (!stopped) {
+        try {
+            const response = await fetch(new URL(`/v1/events?runId=${encodeURIComponent(runId)}`, origin), { signal: AbortSignal.timeout(30_000) });
+            if (!response.ok)
+                throw new Error(`events returned ${response.status}`);
+            const body = await response.json();
+            const events = body.events ?? [];
+            for (const event of events.slice(seen))
+                if (event.seller_id === sellerId) {
+                    const details = event.details ?? {}, summary = [details.capabilityId, details.sessionId, details.transcriptHash, details.artifactSha256].filter((item) => typeof item === "string").map((item) => item.length > 18 ? `${item.slice(0, 18)}…` : item).join(" · ");
+                    line(`${event.created_at}  ${event.stage}  ${event.status}${summary ? `  ${summary}` : ""}`);
+                }
+            seen = events.length;
+        }
+        catch (error) {
+            line(`waiting for seller events: ${error instanceof Error ? error.message : "connection failed"}`);
+        }
+        await new Promise((done) => setTimeout(done, 2000));
+    }
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : "seller watch failed"}\n`);
+    process.exitCode = 1;
+}

package/dist/settlement.d.ts

@@ -0,0 +1,95 @@
+import type { CapabilityManifest, CapabilityRail } from "./capability.js";
+export declare const SETTLEMENT_PLAN_VERSION: "supercuts.settlement-plan.v1";
+export declare const SETTLEMENT_MEMORY_VERSION: "supercuts.settlement-memory.v1";
+export type SettlementRisk = "low" | "medium" | "review_required";
+export type SettlementMemoryProvenance = "owner_policy" | "verified_outcome" | "agent_observation" | "legacy_untrusted";
+export type SettlementMemoryKind = "privacy_rule" | "budget_limit" | "reliability" | "quality" | "outcome";
+export interface SettlementMemoryScope {
+    counterparty?: string;
+    capabilityId?: string;
+    capabilityClass?: string;
+    network?: "sui:testnet";
+    asset?: string;
+}
+export interface SettlementMemoryV1 {
+    version: typeof SETTLEMENT_MEMORY_VERSION;
+    kind: SettlementMemoryKind;
+    provenance: SettlementMemoryProvenance;
+    scope: SettlementMemoryScope;
+    createdAt: number;
+    evidenceHash?: string;
+    observation?: string;
+    signal: {
+        requiresShielded?: boolean;
+        maximumAmount?: string;
+        reliability?: number;
+        quality?: number;
+        outcome?: "succeeded" | "failed" | "unresolved";
+    };
+}
+export interface SettlementCitation {
+    blobId: string;
+    kind: SettlementMemoryKind | "legacy";
+    provenance: SettlementMemoryProvenance;
+    distance: number;
+}
+export type SettlementReasonCode = "MANDATE_DEFAULTS_APPLIED" | "MEMORY_PRIVACY_APPLIED" | "MEMORY_BUDGET_APPLIED" | "MEMORY_OUTCOME_APPLIED" | "MEMORY_LOW_RELEVANCE_IGNORED" | "MEMORY_UNTRUSTED_ADVISORY" | "OWNER_POLICY_CONFLICT" | "RISK_LOW" | "RISK_MEDIUM" | "RISK_REVIEW_REQUIRED" | "RAIL_X402_SELECTED" | "RAIL_SHIELDED_SELECTED" | "REQUESTED_AMOUNT_CLAMPED" | "OWNER_REVIEW_APPROVED";
+export interface SettlementPlanV1 {
+    version: typeof SETTLEMENT_PLAN_VERSION;
+    planHash: string;
+    operationId: string;
+    status: "approved" | "review_required";
+    mandateHash: string;
+    manifestHash: string;
+    capabilityId: string;
+    capabilityClass: string;
+    sellerId: string;
+    endpoint: string;
+    network: "sui:testnet";
+    asset: string;
+    rail: CapabilityRail;
+    openingAmount: string;
+    maximumAmount: string;
+    manifestMinimum: string;
+    manifestMaximum: string;
+    riskLevel: SettlementRisk;
+    createdAt: number;
+    expiresAt: number;
+    citations: SettlementCitation[];
+    reasonCodes: SettlementReasonCode[];
+    approvedFromPlanHash?: string;
+}
+export interface PlanningMandate {
+    version: "supercuts.mandate.v1" | "supercuts.mandate.v2";
+    allowedCounterparties: string[];
+    allowedAssets: string[];
+    perDealCeiling: string;
+    requiredPrivacy: "any" | "shielded";
+    expiresAt: number;
+    allowedCapabilityIds?: string[];
+    allowedCapabilityClasses?: string[];
+    allowedRails?: CapabilityRail[];
+    allowPublicX402?: boolean;
+}
+export interface RecalledSettlementMemory {
+    blobId: string;
+    distance: number;
+    memory?: SettlementMemoryV1;
+    legacy?: boolean;
+}
+export declare function canonicalJson(value: unknown): string;
+export declare const settlementMandateHash: (mandate: PlanningMandate) => string;
+export declare function settlementPlanHash(plan: Omit<SettlementPlanV1, "planHash">): string;
+export declare function validateSettlementMemory(value: unknown, assignedProvenance?: SettlementMemoryProvenance): asserts value is SettlementMemoryV1;
+export declare function createSettlementPlan(input: {
+    operationId: string;
+    mandate: PlanningMandate;
+    manifests: CapabilityManifest[];
+    requestedAmount?: string;
+    privacyHint?: "any" | "shielded";
+    requestedRail?: CapabilityRail;
+    recalled?: RecalledSettlementMemory[];
+    maxMemoryDistance?: number;
+    now?: number;
+}): SettlementPlanV1;
+export declare function validateSettlementPlan(value: unknown): asserts value is SettlementPlanV1;

package/dist/settlement.js

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { fail } from "./errors.js";
+export const SETTLEMENT_PLAN_VERSION = "supercuts.settlement-plan.v1";
+export const SETTLEMENT_MEMORY_VERSION = "supercuts.settlement-memory.v1";
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+    if (typeof value === "number" && !Number.isFinite(value))
+        fail("SETTLEMENT_JSON_INVALID", "settlement records must contain finite JSON values");
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        fail("SETTLEMENT_JSON_INVALID", "settlement records must be JSON-compatible");
+    return encoded;
+}
+const digest = (domain, value) => createHash("sha256").update(canonicalJson({ domain, value })).digest("hex");
+export const settlementMandateHash = (mandate) => digest("supercuts-settlement-mandate-v1", mandate);
+export function settlementPlanHash(plan) { return digest("supercuts-settlement-plan-v1", plan); }
+const unsigned = (value) => typeof value === "string" && /^(?:0|[1-9][0-9]*)$/.test(value);
+const object = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const exactKeys = (value, keys) => { if (Object.keys(value).some((key) => !keys.includes(key)))
+    fail("SETTLEMENT_MEMORY_INVALID", "record contains unknown fields"); };
+export function validateSettlementMemory(value, assignedProvenance) {
+    if (!object(value))
+        fail("SETTLEMENT_MEMORY_INVALID", "settlement memory must be an object");
+    const raw = value;
+    exactKeys(raw, ["version", "kind", "provenance", "scope", "createdAt", "evidenceHash", "observation", "signal"]);
+    if (raw.version !== SETTLEMENT_MEMORY_VERSION || !["privacy_rule", "budget_limit", "reliability", "quality", "outcome"].includes(String(raw.kind)))
+        fail("SETTLEMENT_MEMORY_INVALID", "settlement memory version or kind is invalid");
+    if (!["owner_policy", "verified_outcome", "agent_observation", "legacy_untrusted"].includes(String(raw.provenance)))
+        fail("SETTLEMENT_MEMORY_INVALID", "settlement memory provenance is invalid");
+    if (assignedProvenance && raw.provenance !== assignedProvenance)
+        fail("SETTLEMENT_MEMORY_PROVENANCE", "memory provenance is assigned by Supercuts");
+    if (!Number.isSafeInteger(raw.createdAt) || Number(raw.createdAt) < 0 || !object(raw.scope) || !object(raw.signal))
+        fail("SETTLEMENT_MEMORY_INVALID", "memory timestamp, scope, or signal is invalid");
+    if (raw.observation !== undefined && (typeof raw.observation !== "string" || !raw.observation.trim() || raw.observation.length > 512))
+        fail("SETTLEMENT_MEMORY_INVALID", "memory observation must be a short non-empty string");
+    const scope = raw.scope, signal = raw.signal;
+    exactKeys(scope, ["counterparty", "capabilityId", "capabilityClass", "network", "asset"]);
+    exactKeys(signal, ["requiresShielded", "maximumAmount", "reliability", "quality", "outcome"]);
+    for (const item of Object.values(scope))
+        if (typeof item !== "string" || !item || item.length > 1024)
+            fail("SETTLEMENT_MEMORY_INVALID", "memory scope fields must be non-empty strings");
+    if (scope.network !== undefined && scope.network !== "sui:testnet")
+        fail("SETTLEMENT_MEMORY_INVALID", "memory network must be sui:testnet");
+    if (signal.requiresShielded !== undefined && typeof signal.requiresShielded !== "boolean" || signal.maximumAmount !== undefined && !unsigned(signal.maximumAmount))
+        fail("SETTLEMENT_MEMORY_INVALID", "memory privacy or amount signal is invalid");
+    for (const score of [signal.reliability, signal.quality])
+        if (score !== undefined && (typeof score !== "number" || !Number.isFinite(score) || score < 0 || score > 1))
+            fail("SETTLEMENT_MEMORY_INVALID", "memory scores must be finite values in [0,1]");
+    if (signal.outcome !== undefined && !["succeeded", "failed", "unresolved"].includes(signal.outcome))
+        fail("SETTLEMENT_MEMORY_INVALID", "memory outcome is invalid");
+    const required = { privacy_rule: "requiresShielded", budget_limit: "maximumAmount", reliability: "reliability", quality: "quality", outcome: "outcome" };
+    if (signal[required[raw.kind]] === undefined)
+        fail("SETTLEMENT_MEMORY_INVALID", "memory kind does not have its required signal");
+    if (raw.provenance === "verified_outcome" && (typeof raw.evidenceHash !== "string" || !/^[0-9a-f]{64}$/.test(raw.evidenceHash)))
+        fail("SETTLEMENT_MEMORY_EVIDENCE_REQUIRED", "verified outcomes require a SHA-256 evidence hash");
+    if (raw.evidenceHash !== undefined && (typeof raw.evidenceHash !== "string" || !/^[0-9a-f]{64}$/.test(raw.evidenceHash)))
+        fail("SETTLEMENT_MEMORY_INVALID", "evidence hash must be SHA-256 hex");
+}
+function specificity(scope, manifest) {
+    if (scope.network && scope.network !== "sui:testnet" || scope.asset && scope.asset !== manifest.asset || scope.counterparty && scope.counterparty !== manifest.sellerId || scope.capabilityClass && scope.capabilityClass !== manifest.capability || scope.capabilityId && scope.capabilityId !== manifest.capabilityId)
+        return -1;
+    return scope.capabilityId ? 4 : scope.capabilityClass ? 3 : scope.counterparty ? 2 : 1;
+}
+export function createSettlementPlan(input) {
+    const now = input.now ?? Date.now(), maxDistance = input.maxMemoryDistance ?? 0.35;
+    if (!input.operationId || input.operationId.length > 256 || !input.manifests.length)
+        fail("SETTLEMENT_PLAN_INVALID", "planning requires an operation ID and at least one capability");
+    if (input.requestedAmount !== undefined && !unsigned(input.requestedAmount))
+        fail("SETTLEMENT_PLAN_INVALID", "requestedAmount must be canonical unsigned base units");
+    if (!Number.isFinite(maxDistance) || maxDistance < 0 || maxDistance > 1 || now >= input.mandate.expiresAt)
+        fail("SETTLEMENT_PLAN_DENIED", "planning limits or owner mandate are invalid");
+    const ignored = (input.recalled ?? []).filter((item) => !Number.isFinite(item.distance) || item.distance < 0 || item.distance > maxDistance);
+    const recalled = (input.recalled ?? []).filter((item) => Number.isFinite(item.distance) && item.distance >= 0 && item.distance <= maxDistance);
+    for (const item of recalled)
+        if (item.memory)
+            validateSettlementMemory(item.memory);
+    const candidates = [];
+    for (const manifest of input.manifests) {
+        if (manifest.expiresAt <= now || input.mandate.allowedCapabilityIds && !input.mandate.allowedCapabilityIds.includes(manifest.capabilityId) || input.mandate.allowedCapabilityClasses && !input.mandate.allowedCapabilityClasses.includes(manifest.capability) || !input.mandate.allowedCounterparties.includes(manifest.sellerId) || !input.mandate.allowedAssets.includes(manifest.asset))
+            continue;
+        const matching = recalled.filter((item) => item.memory && specificity(item.memory.scope, manifest) >= 0);
+        const citations = recalled.map((item) => ({ blobId: item.blobId, kind: item.memory?.kind ?? "legacy", provenance: item.memory?.provenance ?? "legacy_untrusted", distance: item.distance }));
+        const trusted = matching.filter((item) => item.memory && ["owner_policy", "verified_outcome"].includes(item.memory.provenance));
+        const latest = (kind, provenance) => {
+            let values = trusted.filter((item) => item.memory.kind === kind && (!provenance || item.memory.provenance === provenance));
+            if (!provenance && values.some((item) => item.memory.provenance === "owner_policy"))
+                values = values.filter((item) => item.memory.provenance === "owner_policy");
+            const best = Math.max(-1, ...values.map((item) => specificity(item.memory.scope, manifest)));
+            const sorted = values.filter((item) => specificity(item.memory.scope, manifest) === best).sort((a, b) => b.memory.createdAt - a.memory.createdAt || b.blobId.localeCompare(a.blobId));
+            if (!sorted.length)
+                return [];
+            return sorted.filter((item) => item.memory.createdAt === sorted[0].memory.createdAt).map((item) => item.memory);
+        };
+        const policies = latest("privacy_rule"), conflict = policies[0]?.provenance === "owner_policy" && new Set(policies.map((item) => item.signal.requiresShielded)).size > 1;
+        const requiresShielded = input.mandate.requiredPrivacy === "shielded" || input.privacyHint === "shielded" || policies.some((item) => item.signal.requiresShielded === true);
+        const rails = manifest.supportedRails.filter((rail) => (!input.mandate.allowedRails || input.mandate.allowedRails.includes(rail)) && (!requiresShielded || rail === "shielded") && (input.mandate.version !== "supercuts.mandate.v2" || rail !== "x402" || input.mandate.allowPublicX402 === true) && (!input.requestedRail || rail === input.requestedRail));
+        if (!rails.length)
+            continue;
+        const budgets = trusted.filter((item) => item.memory.kind === "budget_limit").map((item) => BigInt(item.memory.signal.maximumAmount));
+        const maximum = [BigInt(manifest.priceBand.maximum), BigInt(input.mandate.perDealCeiling), ...budgets].reduce((a, b) => a < b ? a : b);
+        if (maximum < BigInt(manifest.priceBand.minimum))
+            continue;
+        const reliability = latest("reliability")[0]?.signal.reliability ?? 0.5, quality = latest("quality")[0]?.signal.quality ?? 0.5, outcome = latest("outcome")[0]?.signal.outcome;
+        const risk = conflict || outcome === "failed" || outcome === "unresolved" || reliability < 0.5 ? "review_required" : reliability >= 0.8 ? "low" : "medium";
+        for (const rail of rails)
+            candidates.push({ manifest, rail, reliability, quality, maximum, risk, citations, conflict, reasons: ["MANDATE_DEFAULTS_APPLIED", ...(policies.length ? ["MEMORY_PRIVACY_APPLIED"] : []), ...(budgets.length ? ["MEMORY_BUDGET_APPLIED"] : []), ...(outcome ? ["MEMORY_OUTCOME_APPLIED"] : []), ...(citations.some((c) => ["agent_observation", "legacy_untrusted"].includes(c.provenance)) ? ["MEMORY_UNTRUSTED_ADVISORY"] : []), ...(ignored.length ? ["MEMORY_LOW_RELEVANCE_IGNORED"] : [])] });
+    }
+    candidates.sort((a, b) => b.reliability - a.reliability || b.quality - a.quality || (a.maximum < b.maximum ? -1 : a.maximum > b.maximum ? 1 : 0) || a.manifest.capabilityId.localeCompare(b.manifest.capabilityId) || (a.rail === b.rail ? 0 : input.mandate.version === "supercuts.mandate.v2" ? a.rail === "shielded" ? -1 : 1 : a.rail === "x402" ? -1 : 1));
+    const selected = candidates[0] ?? fail("SETTLEMENT_PLAN_DENIED", "no capability remains within the owner mandate, privacy rules, and price bounds");
+    const minimum = BigInt(selected.manifest.priceBand.minimum), desired = input.requestedAmount === undefined ? minimum : BigInt(input.requestedAmount), opening = desired < minimum ? minimum : desired > selected.maximum ? selected.maximum : desired;
+    const reasons = [...selected.reasons, ...(selected.conflict ? ["OWNER_POLICY_CONFLICT"] : []), ...(opening !== desired ? ["REQUESTED_AMOUNT_CLAMPED"] : []), selected.rail === "shielded" ? "RAIL_SHIELDED_SELECTED" : "RAIL_X402_SELECTED", selected.risk === "low" ? "RISK_LOW" : selected.risk === "medium" ? "RISK_MEDIUM" : "RISK_REVIEW_REQUIRED"];
+    const withoutHash = { version: SETTLEMENT_PLAN_VERSION, operationId: input.operationId, status: selected.risk === "review_required" ? "review_required" : "approved", mandateHash: settlementMandateHash(input.mandate), manifestHash: selected.manifest.manifestHash, capabilityId: selected.manifest.capabilityId, capabilityClass: selected.manifest.capability, sellerId: selected.manifest.sellerId, endpoint: selected.manifest.endpoint, network: "sui:testnet", asset: selected.manifest.asset, rail: selected.rail, openingAmount: opening.toString(), maximumAmount: selected.maximum.toString(), manifestMinimum: selected.manifest.priceBand.minimum, manifestMaximum: selected.manifest.priceBand.maximum, riskLevel: selected.risk, createdAt: now, expiresAt: Math.min(now + 300_000, input.mandate.expiresAt, selected.manifest.expiresAt), citations: selected.citations.sort((a, b) => a.blobId.localeCompare(b.blobId)), reasonCodes: [...new Set(reasons)] };
+    return { ...withoutHash, planHash: settlementPlanHash(withoutHash) };
+}
+export function validateSettlementPlan(value) {
+    if (!object(value) || value.version !== SETTLEMENT_PLAN_VERSION)
+        fail("SETTLEMENT_PLAN_INVALID", "settlement plan has an invalid version");
+    const allowed = new Set(["version", "planHash", "operationId", "status", "mandateHash", "manifestHash", "capabilityId", "capabilityClass", "sellerId", "endpoint", "network", "asset", "rail", "openingAmount", "maximumAmount", "manifestMinimum", "manifestMaximum", "riskLevel", "createdAt", "expiresAt", "citations", "reasonCodes", "approvedFromPlanHash"]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        fail("SETTLEMENT_PLAN_INVALID", "settlement plan contains unknown fields");
+    const plan = value, { planHash, ...unsignedPlan } = plan;
+    if (typeof planHash !== "string" || !/^[0-9a-f]{64}$/.test(planHash) || settlementPlanHash(unsignedPlan) !== planHash)
+        fail("SETTLEMENT_PLAN_HASH_MISMATCH", "settlement plan hash does not match its canonical record");
+    for (const amount of [plan.openingAmount, plan.maximumAmount, plan.manifestMinimum, plan.manifestMaximum])
+        if (!unsigned(amount))
+            fail("SETTLEMENT_PLAN_INVALID", "settlement plan contains a non-canonical amount");
+    if (!Number.isSafeInteger(plan.createdAt) || !Number.isSafeInteger(plan.expiresAt) || plan.expiresAt <= plan.createdAt || BigInt(plan.openingAmount) > BigInt(plan.maximumAmount) || BigInt(plan.maximumAmount) > BigInt(plan.manifestMaximum) || BigInt(plan.openingAmount) < BigInt(plan.manifestMinimum))
+        fail("SETTLEMENT_PLAN_INVALID", "settlement plan bounds or timestamps are invalid");
+    if (!["approved", "review_required"].includes(plan.status) || !["low", "medium", "review_required"].includes(plan.riskLevel) || !["x402", "shielded"].includes(plan.rail))
+        fail("SETTLEMENT_PLAN_INVALID", "settlement plan decision fields are invalid");
+    for (const field of [plan.operationId, plan.mandateHash, plan.manifestHash, plan.capabilityId, plan.capabilityClass, plan.sellerId, plan.endpoint, plan.asset])
+        if (typeof field !== "string" || !field || field.length > 2048)
+            fail("SETTLEMENT_PLAN_INVALID", "settlement plan string fields are invalid");
+    if (plan.network !== "sui:testnet" || !/^[0-9a-f]{64}$/.test(plan.mandateHash) || !/^[0-9a-f]{64}$/.test(plan.manifestHash) || plan.approvedFromPlanHash !== undefined && !/^[0-9a-f]{64}$/.test(plan.approvedFromPlanHash))
+        fail("SETTLEMENT_PLAN_INVALID", "settlement plan hashes or network are invalid");
+    if (!Array.isArray(plan.reasonCodes) || !Array.isArray(plan.citations) || plan.citations.some((citation) => !object(citation) || Object.keys(citation).some((key) => !["blobId", "kind", "provenance", "distance"].includes(key)) || typeof citation.blobId !== "string" || !citation.blobId || typeof citation.distance !== "number" || !Number.isFinite(citation.distance) || citation.distance < 0 || citation.distance > 1))
+        fail("SETTLEMENT_PLAN_INVALID", "settlement plan citations or reasons are invalid");
+}

package/dist/store.d.ts

@@ -0,0 +1,36 @@
+import { DatabaseSync } from "node:sqlite";
+export type OperationStatus = "draft" | "reserved" | "proof_persisted" | "broadcast" | "finalized" | "confirmed" | "delivered" | "unresolved";
+export interface StoredOperation {
+    id: string;
+    status: OperationStatus;
+    payloadHash: string;
+    txDigest?: string;
+    updatedAt: number;
+}
+export interface StoredMessage {
+    id: string;
+    sessionId: string;
+    sequence: number;
+    ciphertextHash: string;
+    blobId?: string;
+}
+export declare class RoleStore {
+    #private;
+    readonly db: DatabaseSync;
+    constructor(path: string, key: Buffer);
+    close(): void;
+    putSecret(name: string, value: Uint8Array): void;
+    putSecretOnce(name: string, value: Uint8Array): void;
+    getSecret(name: string): Buffer | undefined;
+    beginOperation(id: string, payloadHash: string): void;
+    getOperation(id: string): StoredOperation | undefined;
+    transitionOperation(id: string, next: OperationStatus, txDigest?: string): void;
+    reserveNote(noteCommitment: string, operationId: string): void;
+    claimOnce(scope: string, value: string, result?: string): boolean;
+    prepareMessage(message: StoredMessage): void;
+    attachMessageBlob(id: string, ciphertextHash: string, blobId: string): void;
+    getMessage(id: string): StoredMessage | undefined;
+    putNote(commitment: string, role: "input" | "payment" | "change", operationId?: string, leafIndex?: bigint, nullifier?: string): void;
+    markNoteSpent(nullifier: string): void;
+    hasUnspentNote(commitment: string): boolean;
+}