@supercuts-walrus/backend 0.0.0-stage → 0.1.0

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;
+}

package/dist/store.js

@@ -0,0 +1,193 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { fail } from "./errors.js";
+const statuses = new Set(["draft", "reserved", "proof_persisted", "broadcast", "finalized", "confirmed", "delivered", "unresolved"]);
+function encrypt(key, value, aad) {
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(Buffer.from(aad));
+    return { nonce, value: Buffer.concat([cipher.update(value), cipher.final()]), tag: cipher.getAuthTag() };
+}
+function decrypt(key, encrypted, aad) {
+    try {
+        const cipher = createDecipheriv("aes-256-gcm", key, encrypted.nonce);
+        cipher.setAAD(Buffer.from(aad));
+        cipher.setAuthTag(encrypted.tag);
+        return Buffer.concat([cipher.update(encrypted.value), cipher.final()]);
+    }
+    catch (error) {
+        return fail("STATE_DECRYPT_FAILED", `could not decrypt ${aad}`, error);
+    }
+}
+export class RoleStore {
+    db;
+    #key;
+    constructor(path, key) {
+        if (key.length !== 32)
+            fail("STATE_KEY_INVALID", "role-store key must contain exactly 32 bytes");
+        this.#key = Buffer.from(key);
+        const directory = dirname(path);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if ((statSync(directory).mode & 0o077) !== 0)
+            fail("STATE_DIRECTORY_PERMISSIONS", `${directory} must not be group/world accessible`);
+        if (existsSync(path) && (statSync(path).mode & 0o077) !== 0)
+            fail("STATE_PERMISSIONS", `${path} must not be group/world accessible`);
+        this.db = new DatabaseSync(path);
+        // SQLite may create the main database before its first transaction. Ensure
+        // the database and any persistent WAL sidecars cannot expose encrypted
+        // ciphertext or public operation metadata to another local account.
+        for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+            if (existsSync(candidate))
+                chmodSync(candidate, 0o600);
+        }
+        this.db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS secrets (name TEXT PRIMARY KEY, nonce BLOB NOT NULL, tag BLOB NOT NULL, value BLOB NOT NULL);
+      CREATE TABLE IF NOT EXISTS operations (id TEXT PRIMARY KEY, status TEXT NOT NULL, payload_hash TEXT NOT NULL, tx_digest TEXT, updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS reservations (note_commitment TEXT PRIMARY KEY, operation_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS replay_ledger (scope TEXT NOT NULL, value TEXT NOT NULL, result TEXT, PRIMARY KEY(scope, value));
+      CREATE TABLE IF NOT EXISTS checkpoints (stream TEXT PRIMARY KEY, checkpoint TEXT NOT NULL, cursor BLOB, root TEXT NOT NULL, leaf_index TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS messages (id TEXT PRIMARY KEY, session_id TEXT NOT NULL, sequence INTEGER NOT NULL, ciphertext_hash TEXT NOT NULL, blob_id TEXT, UNIQUE(session_id, sequence));
+      CREATE TABLE IF NOT EXISTS deliveries (request_id TEXT PRIMARY KEY, payment_key TEXT NOT NULL, response BLOB NOT NULL, finalized INTEGER NOT NULL);
+      CREATE UNIQUE INDEX IF NOT EXISTS deliveries_payment_key ON deliveries(payment_key);
+      CREATE TABLE IF NOT EXISTS x402_challenges (request_id TEXT PRIMARY KEY, nonce TEXT NOT NULL, requirements_hash TEXT NOT NULL, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS delivery_jobs (request_id TEXT PRIMARY KEY, status TEXT NOT NULL, lease_until INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS notes (commitment TEXT PRIMARY KEY, operation_id TEXT, role TEXT NOT NULL, leaf_index TEXT, nullifier TEXT, spent INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS memory_jobs (operation_id TEXT PRIMARY KEY, kind TEXT NOT NULL, fact_hash TEXT NOT NULL, blob_id TEXT, status TEXT NOT NULL, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS memory_authority (blob_id TEXT PRIMARY KEY, fact_hash TEXT NOT NULL, provenance TEXT NOT NULL, evidence_hash TEXT, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS memory_inventory (blob_id TEXT PRIMARY KEY, memory_id TEXT NOT NULL, namespace TEXT NOT NULL, status TEXT NOT NULL, expires_at TEXT, deleted INTEGER NOT NULL DEFAULT 0, updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS memory_inventory_cursor (namespace TEXT PRIMARY KEY, cursor TEXT, updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS deal_operations (operation_id TEXT PRIMARY KEY, deal_id TEXT NOT NULL UNIQUE, input_hash TEXT NOT NULL, state TEXT NOT NULL, rail TEXT, plan_hash TEXT, payment_operation_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS deal_steps (operation_id TEXT NOT NULL, step TEXT NOT NULL, input_hash TEXT NOT NULL, state TEXT NOT NULL, result_hash TEXT, updated_at INTEGER NOT NULL, PRIMARY KEY(operation_id,step), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS deal_blobs (operation_id TEXT NOT NULL, kind TEXT NOT NULL, ciphertext_hash TEXT NOT NULL, blob_id TEXT, status TEXT NOT NULL, PRIMARY KEY(operation_id,kind), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS deal_memory_outbox (operation_id TEXT NOT NULL, event_kind TEXT NOT NULL, payload_hash TEXT NOT NULL, blob_id TEXT, status TEXT NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY(operation_id,event_kind), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS deal_timings (operation_id TEXT NOT NULL, stage TEXT NOT NULL, duration_ms INTEGER NOT NULL, PRIMARY KEY(operation_id,stage), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS settlement_plans (plan_hash TEXT PRIMARY KEY, operation_id TEXT NOT NULL UNIQUE, plan_json TEXT NOT NULL, status TEXT NOT NULL, expires_at INTEGER NOT NULL, consumed_at INTEGER, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS settlement_execution_bindings (operation_id TEXT PRIMARY KEY, plan_hash TEXT NOT NULL UNIQUE, binding_hash TEXT NOT NULL, binding_json TEXT NOT NULL, created_at INTEGER NOT NULL, FOREIGN KEY(plan_hash) REFERENCES settlement_plans(plan_hash));
+      CREATE TABLE IF NOT EXISTS settlement_agreement_bindings (session_id TEXT PRIMARY KEY, plan_hash TEXT NOT NULL UNIQUE, binding_hash TEXT NOT NULL, created_at INTEGER NOT NULL, FOREIGN KEY(plan_hash) REFERENCES settlement_plans(plan_hash));
+      CREATE TABLE IF NOT EXISTS settlement_decision_traces (plan_hash TEXT PRIMARY KEY, mandate_hash TEXT NOT NULL, manifest_hash TEXT NOT NULL, risk_level TEXT NOT NULL, reason_codes TEXT NOT NULL, citations TEXT NOT NULL, created_at INTEGER NOT NULL, FOREIGN KEY(plan_hash) REFERENCES settlement_plans(plan_hash));
+    `);
+        const memoryColumns = this.db.prepare("PRAGMA table_info(memory_jobs)").all();
+        if (!memoryColumns.some((column) => column.name === "fact_hash"))
+            this.db.exec("ALTER TABLE memory_jobs ADD COLUMN fact_hash TEXT");
+        if (!memoryColumns.some((column) => column.name === "claimed_at"))
+            this.db.exec("ALTER TABLE memory_jobs ADD COLUMN claimed_at INTEGER");
+        for (const candidate of [path, `${path}-wal`, `${path}-shm`])
+            if (existsSync(candidate))
+                chmodSync(candidate, 0o600);
+    }
+    close() { this.db.close(); }
+    putSecret(name, value) {
+        const encrypted = encrypt(this.#key, Buffer.from(value), `secret:${name}`);
+        this.db.prepare("INSERT OR REPLACE INTO secrets(name, nonce, tag, value) VALUES (?, ?, ?, ?)")
+            .run(name, encrypted.nonce, encrypted.tag, encrypted.value);
+    }
+    putSecretOnce(name, value) {
+        const existing = this.getSecret(name);
+        if (existing) {
+            if (!existing.equals(Buffer.from(value)))
+                fail("SECRET_ID_CONFLICT", `secret ${name} already contains different bytes`);
+            return;
+        }
+        this.putSecret(name, value);
+    }
+    getSecret(name) {
+        const row = this.db.prepare("SELECT nonce, tag, value FROM secrets WHERE name = ?").get(name);
+        return row ? decrypt(this.#key, row, `secret:${name}`) : undefined;
+    }
+    beginOperation(id, payloadHash) {
+        const existing = this.getOperation(id);
+        if (existing) {
+            if (existing.payloadHash !== payloadHash)
+                fail("OPERATION_ID_CONFLICT", `operation ${id} already has a different payload`);
+            return;
+        }
+        this.db.prepare("INSERT INTO operations(id, status, payload_hash, updated_at) VALUES (?, 'draft', ?, ?)").run(id, payloadHash, Date.now());
+    }
+    getOperation(id) {
+        const row = this.db.prepare("SELECT id, status, payload_hash, tx_digest, updated_at FROM operations WHERE id = ?").get(id);
+        return row ? { id: row.id, status: row.status, payloadHash: row.payload_hash, ...(row.tx_digest ? { txDigest: row.tx_digest } : {}), updatedAt: row.updated_at } : undefined;
+    }
+    transitionOperation(id, next, txDigest) {
+        if (!statuses.has(next))
+            fail("OPERATION_STATUS_INVALID", `unknown operation status ${next}`);
+        const row = this.db.prepare("SELECT status, tx_digest FROM operations WHERE id = ?").get(id);
+        const current = row?.status ?? fail("OPERATION_NOT_FOUND", `operation ${id} does not exist`);
+        if (row?.tx_digest && txDigest && row.tx_digest !== txDigest)
+            fail("OPERATION_DIGEST_CONFLICT", "operation cannot transition with a different transaction digest");
+        if (current === next)
+            return;
+        const allowed = {
+            draft: ["reserved", "unresolved"], reserved: ["proof_persisted", "unresolved"],
+            proof_persisted: ["broadcast", "unresolved"], broadcast: ["finalized", "unresolved"],
+            finalized: ["confirmed", "unresolved"], confirmed: ["delivered", "unresolved"], delivered: [],
+            unresolved: ["broadcast", "finalized", "confirmed"],
+        };
+        if (!allowed[current].includes(next))
+            fail("OPERATION_TRANSITION_INVALID", `${current} cannot transition to ${next}`);
+        this.db.prepare("UPDATE operations SET status = ?, tx_digest = COALESCE(?, tx_digest), updated_at = ? WHERE id = ?")
+            .run(next, txDigest ?? null, Date.now(), id);
+    }
+    reserveNote(noteCommitment, operationId) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const existing = this.db.prepare("SELECT operation_id FROM reservations WHERE note_commitment = ?").get(noteCommitment);
+            if (existing && existing.operation_id !== operationId)
+                fail("NOTE_RESERVED", "note is already reserved by another operation");
+            this.db.prepare("INSERT OR IGNORE INTO reservations(note_commitment, operation_id, created_at) VALUES (?, ?, ?)").run(noteCommitment, operationId, Date.now());
+            if (this.getOperation(operationId)?.status === "draft")
+                this.transitionOperation(operationId, "reserved");
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    claimOnce(scope, value, result) {
+        const info = this.db.prepare("INSERT OR IGNORE INTO replay_ledger(scope, value, result) VALUES (?, ?, ?)").run(scope, value, result ?? null);
+        return info.changes === 1;
+    }
+    prepareMessage(message) {
+        const existing = this.getMessage(message.id);
+        if (existing) {
+            if (existing.sessionId !== message.sessionId || existing.sequence !== message.sequence || existing.ciphertextHash !== message.ciphertextHash) {
+                fail("MESSAGE_ID_CONFLICT", `message ${message.id} already identifies different ciphertext`);
+            }
+            return;
+        }
+        try {
+            this.db.prepare("INSERT INTO messages(id, session_id, sequence, ciphertext_hash, blob_id) VALUES (?, ?, ?, ?, NULL)")
+                .run(message.id, message.sessionId, message.sequence, message.ciphertextHash);
+        }
+        catch (error) {
+            fail("MESSAGE_SEQUENCE_CONFLICT", "session sequence is already occupied", error);
+        }
+    }
+    attachMessageBlob(id, ciphertextHash, blobId) {
+        const row = this.getMessage(id) ?? fail("MESSAGE_NOT_FOUND", `message ${id} was not prepared`);
+        if (row.ciphertextHash !== ciphertextHash)
+            fail("CIPHERTEXT_TAMPERED", "uploaded ciphertext differs from the durable message");
+        if (row.blobId && row.blobId !== blobId)
+            fail("MESSAGE_BLOB_CONFLICT", "message already resolved to another blob");
+        this.db.prepare("UPDATE messages SET blob_id = ? WHERE id = ?").run(blobId, id);
+    }
+    getMessage(id) {
+        const row = this.db.prepare("SELECT id, session_id, sequence, ciphertext_hash, blob_id FROM messages WHERE id = ?").get(id);
+        return row ? { id: row.id, sessionId: row.session_id, sequence: row.sequence, ciphertextHash: row.ciphertext_hash, ...(row.blob_id ? { blobId: row.blob_id } : {}) } : undefined;
+    }
+    putNote(commitment, role, operationId, leafIndex, nullifier) {
+        const existing = this.db.prepare("SELECT operation_id, role, leaf_index, nullifier FROM notes WHERE commitment = ?").get(commitment);
+        const values = { operationId: operationId ?? null, role, leafIndex: leafIndex?.toString() ?? null, nullifier: nullifier ?? null };
+        if (existing && (existing.operation_id !== values.operationId || existing.role !== role || (existing.leaf_index && values.leafIndex && existing.leaf_index !== values.leafIndex) || (existing.nullifier && values.nullifier && existing.nullifier !== values.nullifier)))
+            fail("NOTE_ID_CONFLICT", "note commitment is already associated with different recovery data");
+        this.db.prepare("INSERT INTO notes(commitment, operation_id, role, leaf_index, nullifier, spent) VALUES (?, ?, ?, ?, ?, 0) ON CONFLICT(commitment) DO UPDATE SET leaf_index=COALESCE(notes.leaf_index, excluded.leaf_index), nullifier=COALESCE(notes.nullifier, excluded.nullifier)")
+            .run(commitment, values.operationId, role, values.leafIndex, values.nullifier);
+    }
+    markNoteSpent(nullifier) { this.db.prepare("UPDATE notes SET spent = 1 WHERE nullifier = ?").run(nullifier); }
+    hasUnspentNote(commitment) {
+        return Boolean(this.db.prepare("SELECT 1 AS found FROM notes WHERE commitment = ? AND spent = 0").get(commitment));
+    }
+}

package/dist/sui.d.ts

@@ -0,0 +1,49 @@
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { Transaction } from "@mysten/sui/transactions";
+export interface TransferCall {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    poolModule?: "pool" | "pool_v2";
+    expiryMs: bigint;
+    newIndex: bigint;
+    dealCommitment: Uint8Array;
+    dealNullifier: Uint8Array;
+    inputNullifier: Uint8Array;
+    paymentCommitment: Uint8Array;
+    changeCommitment: Uint8Array;
+    newRoot: Uint8Array;
+    proof: Uint8Array;
+}
+export interface DepositCall {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    poolModule?: "pool" | "pool_v2";
+    amount: bigint;
+    newIndex: bigint;
+    noteCommitment: Uint8Array;
+    newRoot: Uint8Array;
+    proof: Uint8Array;
+}
+export interface WithdrawCall {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    amount: bigint;
+    recipient: string;
+    root: Uint8Array;
+    noteNullifier: Uint8Array;
+    proof: Uint8Array;
+}
+export interface WithdrawV2Call extends WithdrawCall {
+    exactExit: boolean;
+    changeCommitment: Uint8Array;
+    newRoot: Uint8Array;
+    newIndex: bigint;
+}
+export declare function buildDeposit(call: DepositCall): Transaction;
+export declare function buildPrivateTransfer(call: TransferCall): Transaction;
+export declare function buildWithdraw(call: WithdrawCall): Transaction;
+export declare function buildWithdrawV2(call: WithdrawV2Call): Transaction;
+export declare function writeClient(endpoint: string): SuiGrpcClient;