@totemsdk/edge-adapters 0.2.0 → 0.3.0

package/dist/purchase-authority.d.ts

@@ -0,0 +1,42 @@
+/**
+ * purchase-authority.ts — AuthorityPort adapter over @totemsdk/agent-policy.
+ *
+ * Maps a machine-commerce TradeAgreement + PurchaseIntent to an AgentProposal
+ * and evaluates it through a ComposablePolicy (or any AgentPolicy).
+ *
+ * Architectural boundary preserved:
+ *   TradeProposal  = machine ↔ machine bargaining (peer-to-peer)
+ *   AgentProposal  = agent → trusted local authority (wallet/policy)
+ *
+ * The machine negotiation strategy never receives a private key. This adapter
+ * is the trusted boundary that decides whether the local authority approves
+ * the economic commitment.
+ */
+import type { AgentPolicy, PolicyMiddleware } from '@totemsdk/agent-policy';
+import type { EdgeOperationResult } from '@totemsdk/edge';
+import type { PurchaseIntent, TradeAgreement } from '@totemsdk/edge';
+type PolicyLike = AgentPolicy | PolicyMiddleware;
+export interface PurchaseAuthorityAdapterConfig {
+    /** The local policy (ComposablePolicy, AgentPolicy, or PolicyMiddleware). */
+    policy: PolicyLike;
+    /** Agent identifier used in the AgentProposal (e.g. 'edge-purchase-agent'). */
+    agentId?: string;
+    /** Optional risk level for the proposal. */
+    risk?: 'low' | 'medium' | 'high';
+}
+/**
+ * Create an AuthorityPort adapter over an agent-policy.
+ *
+ * approve() builds an AgentProposal from the agreement + intent and evaluates
+ * it through the policy. Returns `{ allowed, reason }`.
+ */
+export declare function createPurchaseAuthorityAdapter(config: PurchaseAuthorityAdapterConfig): {
+    approve(params: {
+        agreement: TradeAgreement;
+        intent: PurchaseIntent;
+    }): Promise<EdgeOperationResult<{
+        allowed: boolean;
+        reason?: string;
+    }>>;
+};
+export {};

package/dist/purchase-authority.js

@@ -0,0 +1,76 @@
+/**
+ * purchase-authority.ts — AuthorityPort adapter over @totemsdk/agent-policy.
+ *
+ * Maps a machine-commerce TradeAgreement + PurchaseIntent to an AgentProposal
+ * and evaluates it through a ComposablePolicy (or any AgentPolicy).
+ *
+ * Architectural boundary preserved:
+ *   TradeProposal  = machine ↔ machine bargaining (peer-to-peer)
+ *   AgentProposal  = agent → trusted local authority (wallet/policy)
+ *
+ * The machine negotiation strategy never receives a private key. This adapter
+ * is the trusted boundary that decides whether the local authority approves
+ * the economic commitment.
+ */
+function isMiddleware(p) {
+    return 'evaluate' in p && typeof p.evaluate === 'function';
+}
+/**
+ * Create an AuthorityPort adapter over an agent-policy.
+ *
+ * approve() builds an AgentProposal from the agreement + intent and evaluates
+ * it through the policy. Returns `{ allowed, reason }`.
+ */
+export function createPurchaseAuthorityAdapter(config) {
+    const { policy } = config;
+    const agentId = config.agentId ?? 'edge-purchase-agent';
+    const risk = config.risk ?? 'medium';
+    return {
+        async approve(params) {
+            try {
+                const { agreement, intent } = params;
+                const proposal = {
+                    id: `edge-purchase:${agreement.agreementId}`,
+                    agentId,
+                    intent: {
+                        type: 'payment',
+                        amount: agreement.terms.price,
+                        tokenId: agreement.terms.tokenId,
+                        recipient: agreement.seller,
+                        reason: `purchase ${intent.resource} from ${agreement.seller}`,
+                        risk,
+                        metadata: {
+                            agreementId: agreement.agreementId,
+                            negotiationId: agreement.negotiationId,
+                            resource: intent.resource,
+                        },
+                    },
+                    explanation: `Machine purchase of ${intent.resource} for ${agreement.terms.price} ${agreement.terms.tokenId ?? '0x00'} from ${agreement.seller}`,
+                    confidence: 1,
+                    createdAt: Date.now(),
+                };
+                if (isMiddleware(policy)) {
+                    const result = await policy.evaluate(proposal);
+                    return {
+                        ok: true,
+                        data: {
+                            allowed: result.outcome === 'approved',
+                            reason: result.reason,
+                        },
+                    };
+                }
+                const allowed = await policy.canAutoApprove(proposal);
+                return {
+                    ok: true,
+                    data: {
+                        allowed,
+                        reason: allowed ? undefined : 'Purchase requires user approval per configured policy',
+                    },
+                };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    };
+}

package/dist/purchase-lookup.d.ts

@@ -0,0 +1,44 @@
+/**
+ * purchase-lookup.ts — PurchaseLookupPort adapter over @totemsdk/lookup-client.
+ *
+ * Maps a machine-commerce `resource` (e.g. "compute", "storage") to a
+ * capability query on the Lookup Node, returning signed manifests for the
+ * buyer's discovery flow.
+ *
+ * Discovery is publication, not authority: the buyer MUST still verify each
+ * returned manifest's signature, identity binding, expiry, and capabilities
+ * before negotiation/payment. This adapter only fetches candidates.
+ */
+import type { LookupClient } from '@totemsdk/lookup-client';
+import type { EdgeOperationResult } from '@totemsdk/edge';
+export interface PurchaseLookupAdapterConfig {
+    client: LookupClient;
+    /** Optional provider address filter (authorAddress for apps). */
+    provider?: string;
+    /** Optional max price filter (agents). */
+    maxPricePerCall?: number;
+    /** Optional max latency filter (agents). */
+    maxLatencyMs?: number;
+    /** Optional result limit. */
+    limit?: number;
+}
+/**
+ * Create a PurchaseLookupPort adapter over a LookupClient.
+ *
+ * `resource` is treated as a capability name for agent manifests (the
+ * machine-commerce case). If the resource matches a known app category, it
+ * falls back to app queries. Returns `{ id, manifest: Uint8Array, nodeId }`
+ * candidates for the buyer's manifest-verification pipeline.
+ */
+export declare function createPurchaseLookupAdapter(config: PurchaseLookupAdapterConfig): {
+    query(params: {
+        resource: string;
+        provider?: string;
+    }): Promise<EdgeOperationResult<{
+        results: Array<{
+            id: string;
+            manifest: Uint8Array;
+            nodeId: string;
+        }>;
+    }>>;
+};

package/dist/purchase-lookup.js

@@ -0,0 +1,57 @@
+/**
+ * purchase-lookup.ts — PurchaseLookupPort adapter over @totemsdk/lookup-client.
+ *
+ * Maps a machine-commerce `resource` (e.g. "compute", "storage") to a
+ * capability query on the Lookup Node, returning signed manifests for the
+ * buyer's discovery flow.
+ *
+ * Discovery is publication, not authority: the buyer MUST still verify each
+ * returned manifest's signature, identity binding, expiry, and capabilities
+ * before negotiation/payment. This adapter only fetches candidates.
+ */
+/**
+ * Create a PurchaseLookupPort adapter over a LookupClient.
+ *
+ * `resource` is treated as a capability name for agent manifests (the
+ * machine-commerce case). If the resource matches a known app category, it
+ * falls back to app queries. Returns `{ id, manifest: Uint8Array, nodeId }`
+ * candidates for the buyer's manifest-verification pipeline.
+ */
+export function createPurchaseLookupAdapter(config) {
+    const { client } = config;
+    return {
+        async query(params) {
+            try {
+                const provider = params.provider ?? config.provider;
+                const limit = config.limit ?? 20;
+                // Agent capability query (machine-commerce primary path).
+                const agents = await client.queryAgents({
+                    capabilityName: params.resource,
+                    maxPricePerCall: config.maxPricePerCall,
+                    maxLatencyMs: config.maxLatencyMs,
+                    limit,
+                });
+                const results = agents.map((a) => ({
+                    id: a.capabilityId,
+                    manifest: a.manifest,
+                    nodeId: a.nodeId,
+                }));
+                // If no agent results and a provider is specified, also try app query
+                // filtered by author address (provider = operator).
+                if (results.length === 0 && provider) {
+                    const apps = await client.queryApps({
+                        authorAddress: provider,
+                        limit,
+                    });
+                    for (const a of apps) {
+                        results.push({ id: a.appId, manifest: a.manifest, nodeId: a.nodeId });
+                    }
+                }
+                return { ok: true, data: { results } };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    };
+}

package/dist/purchase-payment.d.ts

@@ -0,0 +1,78 @@
+/**
+ * purchase-payment.ts — PurchasePaymentPort adapter with an atomic claim.
+ *
+ * Wraps any EdgePaymentPort (L1 Minima, L2 Omnia, hosted) and adds a stable
+ * idempotency-key claim so a retry after a lost response never double-pays.
+ *
+ * The idempotency key is the stable purchase operation identity
+ * (`purchaseId:agreementId:payment`) supplied by the purchasing layer. The
+ * wrapper records an atomic pending marker (claim) *before* it invokes the
+ * underlying payment port; only the caller that wins the claim pays. A retry
+ * with the same key returns the prior result without re-invoking the port, and
+ * a concurrent duplicate never double-pays — it either replays the completed
+ * outcome or surfaces `PAYMENT_STATE_UNKNOWN` for an in-flight claim.
+ *
+ * Final exactly-once still depends on the payment system's own reconciliation:
+ * if the process dies between the port accepting the payment and the outcome
+ * being recorded, the key stays `pending`, and retries return
+ * `PAYMENT_STATE_UNKNOWN` rather than risking a second payment. The owner
+ * reconciles that window against the payment ledger.
+ */
+import type { EdgeOperationResult } from '@totemsdk/edge';
+import { type CasStore, type StorageAdapterWithCapabilities, type WriteAckMode } from '@totemsdk/storage';
+export interface PaymentResult {
+    txpowId?: string;
+}
+export interface PaymentPortLike {
+    pay(params: {
+        recipient: string;
+        amount: string;
+        tokenId?: string;
+        memo?: string;
+        idempotencyKey?: string;
+    }): Promise<EdgeOperationResult<PaymentResult>>;
+}
+/**
+ * Idempotency claim record. `pending` is written atomically before the port
+ * call; `completed` records the outcome. A `pending` key is never re-claimed
+ * automatically — that is the double-pay guard.
+ */
+export type PurchasePaymentClaimRecord = {
+    phase: 'pending';
+    claimedAt: number;
+} | {
+    phase: 'completed';
+    result: EdgeOperationResult<PaymentResult>;
+    completedAt: number;
+};
+/** The durable idempotency store must support conditional (CAS) writes. */
+export type PurchasePaymentStore = StorageAdapterWithCapabilities & CasStore;
+export interface PurchasePaymentAdapterConfig {
+    /** The underlying payment port (L1/L2/hosted). */
+    port: PaymentPortLike;
+    /**
+     * Optional claim store. When omitted, a dev in-memory store is used (no
+     * crash guarantees and no cross-instance dedup). A durable CAS-capable
+     * store (e.g. a `@totemsdk/storage` FileStore/SqliteStore) makes retries
+     * safe across restarts and processes. No silent downgrade: a supplied
+     * store is asserted CAS-capable and `durably-acknowledged` unless
+     * `requireAckMode` opts into a weaker acknowledgment.
+     */
+    store?: PurchasePaymentStore;
+    /** Key namespace prefix; default `totem_payment:v1:`. */
+    namespace?: string;
+    /** Required write acknowledgment for a supplied store; default `durably-acknowledged`. */
+    requireAckMode?: WriteAckMode;
+}
+/**
+ * Create a PurchasePaymentPort with an atomic idempotency-key claim.
+ */
+export declare function createPurchasePaymentAdapter(config: PurchasePaymentAdapterConfig): {
+    pay(params: {
+        recipient: string;
+        amount: string;
+        tokenId?: string;
+        memo?: string;
+        idempotencyKey?: string;
+    }): Promise<EdgeOperationResult<PaymentResult>>;
+};

package/dist/purchase-payment.js

@@ -0,0 +1,105 @@
+/**
+ * purchase-payment.ts — PurchasePaymentPort adapter with an atomic claim.
+ *
+ * Wraps any EdgePaymentPort (L1 Minima, L2 Omnia, hosted) and adds a stable
+ * idempotency-key claim so a retry after a lost response never double-pays.
+ *
+ * The idempotency key is the stable purchase operation identity
+ * (`purchaseId:agreementId:payment`) supplied by the purchasing layer. The
+ * wrapper records an atomic pending marker (claim) *before* it invokes the
+ * underlying payment port; only the caller that wins the claim pays. A retry
+ * with the same key returns the prior result without re-invoking the port, and
+ * a concurrent duplicate never double-pays — it either replays the completed
+ * outcome or surfaces `PAYMENT_STATE_UNKNOWN` for an in-flight claim.
+ *
+ * Final exactly-once still depends on the payment system's own reconciliation:
+ * if the process dies between the port accepting the payment and the outcome
+ * being recorded, the key stays `pending`, and retries return
+ * `PAYMENT_STATE_UNKNOWN` rather than risking a second payment. The owner
+ * reconciles that window against the payment ledger.
+ */
+import { MemoryStore, assertCapabilities, } from '@totemsdk/storage';
+const DEFAULT_NAMESPACE = 'totem_payment:v1:';
+/** In-process serialization so concurrent claims never double-pay on one store. */
+const locks = new WeakMap();
+function withPaymentLock(store, fn) {
+    const tail = locks.get(store);
+    const next = tail ? tail.then(fn, fn) : fn();
+    const settled = next.catch(() => undefined);
+    locks.set(store, settled);
+    return next;
+}
+/**
+ * Create a PurchasePaymentPort with an atomic idempotency-key claim.
+ */
+export function createPurchasePaymentAdapter(config) {
+    const { port } = config;
+    const namespace = config.namespace ?? DEFAULT_NAMESPACE;
+    const store = config.store ??
+        new MemoryStore(); // dev mode — volatile, process-local
+    if (config.store) {
+        // No silent downgrade: a consumer-supplied store must be able to claim
+        // (CAS) and acknowledge durable writes unless explicitly opted out.
+        assertCapabilities(store, {
+            conditional: true,
+            acknowledge: config.requireAckMode ?? 'durably-acknowledged',
+        });
+    }
+    const keyFor = (idempotencyKey) => namespace + idempotencyKey;
+    return {
+        async pay(params) {
+            const key = params.idempotencyKey;
+            if (!key) {
+                // No idempotency possible without a stable key — pass straight through.
+                return port.pay(params);
+            }
+            // The whole claim→pay→complete path is serialized per store so that N
+            // concurrent same-key callers resolve consistently: the winner pays, and
+            // every loser replays the completed outcome rather than racing the
+            // in-flight window.
+            return withPaymentLock(store, async () => {
+                const claimKey = keyFor(key);
+                // Atomic claim: exactly one caller wins `pending`; concurrent duplicates
+                // either replay a completed outcome or get PAYMENT_STATE_UNKNOWN.
+                const claim = await store.conditionalUpdate(claimKey, (current) => {
+                    if (current === null || current === undefined) {
+                        return { next: { phase: 'pending', claimedAt: Date.now() } };
+                    }
+                    return { abort: 'already-claimed' };
+                });
+                if (!claim.applied) {
+                    const existing = await store.get(claimKey);
+                    if (existing && existing.phase === 'completed') {
+                        return existing.result;
+                    }
+                    return {
+                        ok: false,
+                        errorCode: 'PAYMENT_STATE_UNKNOWN',
+                        error: `payment for idempotency key '${key}' is already in flight`,
+                    };
+                }
+                let result;
+                try {
+                    result = await port.pay(params);
+                }
+                catch (err) {
+                    result = {
+                        ok: false,
+                        errorCode: 'PAYMENT_STATE_UNKNOWN',
+                        error: `payment port threw: ${err.message}`,
+                    };
+                }
+                // Record the outcome only if we still own the pending claim.
+                await store.conditionalUpdate(claimKey, (current) => {
+                    if (current !== null && current !== undefined && current.phase === 'pending') {
+                        return {
+                            next: { phase: 'completed', result, completedAt: Date.now() },
+                        };
+                    }
+                    return { abort: 'gone' };
+                });
+                return result;
+            });
+        },
+    };
+}

package/dist/sqlite-commerce-store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * sqlite-commerce-store.ts — Production SQLite-backed CommerceStore.
+ *
+ * Implements the five durable commerce contracts over ONE SQLite database:
+ *   NegotiationStore, PurchaseStore, ReplayLedger, PrincipalNegotiationStore,
+ *   OutboxStore.
+ *
+ * The database connection, journal/busy pragmas, transaction lifecycle, and
+ * CAS kinematics are owned by the shared `SqliteStore` primitive from
+ * `@totemsdk/storage/sqlite` (RFC-007 §4.2). All consumer mutations run through
+ * `transactionalSync` (atomic multi-statement batches) or the generalized
+ * `transitionAndEnqueue` (revision-CAS update + outbox-style enqueue in one
+ * commit). Table schemas and row shapes are unchanged ("records unchanged in
+ * shape").
+ *
+ * The critical guarantee — `transitionAndEnqueue` (negotiation CAS + outbox
+ * enqueue) — maps to ONE transaction on the shared primitive:
+ *
+ *   BEGIN
+ *   UPDATE negotiations SET ... WHERE negotiation_id=? AND revision=?
+ *   INSERT INTO outbox (...) VALUES (...)
+ *   COMMIT   (or ROLLBACK on CAS miss — nothing is enqueued)
+ *
+ * Uses WAL mode + busy_timeout for concurrent runtime use. Does NOT persist
+ * private keys — only stable references/IDs.
+ *
+ * All statements use positional `?` parameters so the same SQL runs on the
+ * real better-sqlite3 native binding and the node:sqlite jest mock.
+ */
+import type { NegotiationStore, PrincipalNegotiationStore, PurchaseStore } from '@totemsdk/edge';
+import type { ReplayLedger } from '@totemsdk/edge';
+import type { OutboxStore } from '@totemsdk/edge';
+/** Aggregated durable commerce store. */
+export interface CommerceStore {
+    negotiations: NegotiationStore;
+    purchases: PurchaseStore;
+    replay: ReplayLedger;
+    principals: PrincipalNegotiationStore;
+    outbox: OutboxStore;
+}
+export interface SQLiteCommerceStoreConfig {
+    /** File path, or ':memory:' for ephemeral. */
+    filename: string;
+    /** WAL mode (default true). */
+    wal?: boolean;
+    /** Busy timeout ms (default 5000). */
+    busyTimeoutMs?: number;
+}
+export declare class SQLiteCommerceStore implements CommerceStore {
+    readonly negotiations: NegotiationStore;
+    readonly purchases: PurchaseStore;
+    readonly replay: ReplayLedger;
+    readonly principals: PrincipalNegotiationStore;
+    readonly outbox: OutboxStore;
+    private readonly store;
+    constructor(config: SQLiteCommerceStoreConfig);
+    close(): void;
+    private createNegotiationStore;
+    private createPurchaseStore;
+    private createReplayLedger;
+    private createPrincipalStore;
+    private createOutboxStore;
+}
+/**
+ * Create a SQLite-backed CommerceStore.
+ *
+ * @param config filename (or ':memory:') + WAL/busy options.
+ */
+export declare function createSQLiteCommerceStore(config: SQLiteCommerceStoreConfig): SQLiteCommerceStore;