@umpledger/sdk 2.0.0-alpha.1

package/src/settlement/bus.ts

@@ -0,0 +1,253 @@
+import type {
+  Settlement,
+  RatedRecord, UsageEvent, PricingRule,
+} from '../types';
+import { generateId, round, hrTimestamp } from '../utils/id';
+import { WalletManager } from '../core/wallet-manager';
+import { AuditTrail } from '../core/audit-trail';
+import { PricingEngine } from '../pricing/engine';
+import { UMPError } from '../utils/errors';
+
+export interface SettlementResult {
+  settlement: Settlement;
+  auditId: string;
+}
+
+/**
+ * SettlementBus — Layer 3 primitive
+ *
+ * Executes real-time settlement between agent wallets.
+ * Supports 6 patterns: instant drawdown, escrow, waterfall,
+ * net settlement, conditional release, cross-currency atomic.
+ */
+export class SettlementBus {
+  private settlements: Map<string, Settlement> = new Map();
+  private escrows: Map<string, { amount: number; sourceWalletId: string; targetWalletId: string }> = new Map();
+
+  constructor(
+    private wallets: WalletManager,
+    private audit: AuditTrail,
+    private pricingEngine: PricingEngine,
+  ) {}
+
+  /**
+   * Execute a full transaction: meter → rate → settle in one call.
+   * This is the high-level "transact" method from the Quick Start.
+   */
+  async transact(
+    sourceAgentId: string,
+    targetAgentId: string,
+    event: UsageEvent,
+    rule: PricingRule,
+  ): Promise<SettlementResult> {
+    const startTime = Date.now();
+
+    // 1. Rate the usage event
+    const ratedRecord = this.pricingEngine.rate(rule, { event });
+
+    // 2. Execute instant drawdown settlement
+    return this.settleInstant(
+      sourceAgentId,
+      targetAgentId,
+      [ratedRecord],
+      startTime,
+    );
+  }
+
+  /**
+   * INSTANT_DRAWDOWN: Debit source, credit target atomically.
+   * Used for per-token, per-inference micro-transactions.
+   */
+  settleInstant(
+    sourceAgentId: string,
+    targetAgentId: string,
+    ratedRecords: RatedRecord[],
+    _startTime?: number,
+  ): SettlementResult {
+    const totalAmount = round(ratedRecords.reduce((sum, r) => sum + r.amount, 0));
+    const sourceWallet = this.wallets.getByAgent(sourceAgentId);
+    const targetWallet = this.wallets.getByAgent(targetAgentId);
+    const settlementId = generateId('stl');
+    const txnId = generateId('txn');
+
+    // Atomic: debit source, credit target
+    const balanceBefore = this.wallets.getBalance(sourceWallet.walletId)[0]?.available ?? 0;
+    this.wallets.debit(sourceWallet.walletId, totalAmount, targetAgentId, txnId);
+    this.wallets.credit(targetWallet.walletId, totalAmount, sourceAgentId, txnId);
+    const balanceAfter = this.wallets.getBalance(sourceWallet.walletId)[0]?.available ?? 0;
+
+    const settlement: Settlement = {
+      settlementId,
+      pattern: 'INSTANT_DRAWDOWN',
+      status: 'SETTLED',
+      sourceAgentId,
+      targetAgentId,
+      ratedRecords,
+      totalAmount,
+      currency: ratedRecords[0]?.currency ?? 'USD',
+      settledAt: hrTimestamp(),
+      auditId: '',
+    };
+
+    // Audit
+    const auditId = this.audit.record({
+      what: { operation: 'SETTLEMENT', entityType: 'transaction', entityId: txnId, amount: totalAmount },
+      who: { sourceAgentId, targetAgentId },
+      why: { contractId: ratedRecords[0]?.contractId, pricingRuleId: ratedRecords[0]?.pricingRuleId },
+      how: { policiesEvaluated: ['SPENDING_LIMIT', 'COUNTERPARTY_ALLOWLIST'], policiesPassed: ['SPENDING_LIMIT', 'COUNTERPARTY_ALLOWLIST'] },
+      result: { balanceBefore, balanceAfter, settlementAmount: totalAmount, status: 'SETTLED' },
+    });
+
+    settlement.auditId = auditId;
+    this.settlements.set(settlementId, settlement);
+
+    return { settlement, auditId };
+  }
+
+  /**
+   * ESCROW_RELEASE: Reserve funds, release upon outcome attestation.
+   * Used for outcome-based pricing and milestone payments.
+   */
+  createEscrow(
+    sourceAgentId: string,
+    targetAgentId: string,
+    amount: number,
+    transactionId: string,
+  ): string {
+    const sourceWallet = this.wallets.getByAgent(sourceAgentId);
+    const targetWallet = this.wallets.getByAgent(targetAgentId);
+    const escrowId = generateId('esc');
+
+    // Reserve in source wallet
+    this.wallets.reserve(sourceWallet.walletId, amount, targetAgentId, transactionId);
+
+    this.escrows.set(escrowId, {
+      amount,
+      sourceWalletId: sourceWallet.walletId,
+      targetWalletId: targetWallet.walletId,
+    });
+
+    this.audit.record({
+      what: { operation: 'ESCROW_CREATED', entityType: 'escrow', entityId: escrowId, amount },
+      who: { sourceAgentId, targetAgentId },
+      why: { justification: `Escrow for transaction ${transactionId}` },
+      how: { policiesEvaluated: ['SPENDING_LIMIT'], policiesPassed: ['SPENDING_LIMIT'] },
+      result: { status: 'ESCROWED' },
+    });
+
+    return escrowId;
+  }
+
+  /**
+   * Release escrowed funds to the target (full or partial).
+   */
+  releaseEscrow(escrowId: string, releaseAmount?: number): SettlementResult {
+    const escrow = this.escrows.get(escrowId);
+    if (!escrow) throw new UMPError(`Escrow not found: ${escrowId}`, 'ESCROW_NOT_FOUND');
+
+    const amount = releaseAmount ?? escrow.amount;
+    const txnId = generateId('txn');
+
+    // Release reservation from source, credit target
+    this.wallets.releaseReservation(escrow.sourceWalletId, amount, txnId);
+    this.wallets.credit(escrow.targetWalletId, amount, 'escrow', txnId);
+
+    // If partial release, update remaining
+    if (amount < escrow.amount) {
+      escrow.amount -= amount;
+    } else {
+      this.escrows.delete(escrowId);
+    }
+
+    const settlement: Settlement = {
+      settlementId: generateId('stl'),
+      pattern: 'ESCROW_RELEASE',
+      status: 'SETTLED',
+      sourceAgentId: 'escrow',
+      targetAgentId: 'escrow',
+      ratedRecords: [],
+      totalAmount: amount,
+      currency: 'USD',
+      settledAt: hrTimestamp(),
+      auditId: '',
+    };
+
+    const auditId = this.audit.record({
+      what: { operation: 'ESCROW_RELEASED', entityType: 'escrow', entityId: escrowId, amount },
+      who: { sourceAgentId: 'escrow', targetAgentId: 'escrow' },
+      why: { justification: `Escrow ${escrowId} released` },
+      how: { policiesEvaluated: ['OUTCOME_VERIFICATION'], policiesPassed: ['OUTCOME_VERIFICATION'] },
+      result: { settlementAmount: amount, status: 'SETTLED' },
+    });
+
+    settlement.auditId = auditId;
+    this.settlements.set(settlement.settlementId, settlement);
+    return { settlement, auditId };
+  }
+
+  /**
+   * WATERFALL_SPLIT: Distribute payment across multiple parties.
+   * Used for marketplace commissions and multi-party revenue share.
+   */
+  settleWaterfall(
+    sourceAgentId: string,
+    splits: Array<{ agentId: string; amount: number }>,
+    ratedRecords: RatedRecord[],
+  ): SettlementResult[] {
+    const sourceWallet = this.wallets.getByAgent(sourceAgentId);
+    const totalAmount = round(splits.reduce((sum, s) => sum + s.amount, 0));
+    const txnId = generateId('txn');
+
+    // Debit total from source
+    this.wallets.debit(sourceWallet.walletId, totalAmount, 'waterfall', txnId);
+
+    // Credit each target
+    const results: SettlementResult[] = splits.map(split => {
+      const targetWallet = this.wallets.getByAgent(split.agentId);
+      this.wallets.credit(targetWallet.walletId, split.amount, sourceAgentId, txnId);
+
+      const settlement: Settlement = {
+        settlementId: generateId('stl'),
+        pattern: 'WATERFALL_SPLIT',
+        status: 'SETTLED',
+        sourceAgentId,
+        targetAgentId: split.agentId,
+        ratedRecords,
+        totalAmount: split.amount,
+        currency: 'USD',
+        settledAt: hrTimestamp(),
+        auditId: '',
+      };
+
+      const auditId = this.audit.record({
+        what: { operation: 'WATERFALL_SPLIT', entityType: 'settlement', entityId: settlement.settlementId, amount: split.amount },
+        who: { sourceAgentId, targetAgentId: split.agentId },
+        why: { justification: `Waterfall split: ${split.amount} to ${split.agentId}` },
+        how: { policiesEvaluated: ['SPENDING_LIMIT'], policiesPassed: ['SPENDING_LIMIT'] },
+        result: { settlementAmount: split.amount, status: 'SETTLED' },
+      });
+
+      settlement.auditId = auditId;
+      this.settlements.set(settlement.settlementId, settlement);
+      return { settlement, auditId };
+    });
+
+    return results;
+  }
+
+  /**
+   * Get settlement by ID.
+   */
+  get(settlementId: string): Settlement | undefined {
+    return this.settlements.get(settlementId);
+  }
+
+  /**
+   * List settlements for an agent.
+   */
+  listByAgent(agentId: string, limit = 50): Settlement[] {
+    return Array.from(this.settlements.values())
+      .filter(s => s.sourceAgentId === agentId || s.targetAgentId === agentId)
+      .slice(-limit);
+  }
+}

package/src/settlement/index.ts

@@ -0,0 +1,2 @@
+export { SettlementBus } from './bus';
+export type { SettlementResult } from './bus';

package/src/terms/contract-manager.ts

@@ -0,0 +1,142 @@
+import type {
+  Contract, ContractStatus,
+  CreateContractOptions, PricingRule,
+} from '../types';
+import { generateId, hrTimestamp } from '../utils/id';
+import { ContractNotFoundError, UMPError } from '../utils/errors';
+
+/**
+ * ContractManager — Layer 1/2 bridge
+ *
+ * Manages commercial agreements between agents.
+ * Supports pre-negotiated, template-based, and dynamic negotiation.
+ */
+export class ContractManager {
+  private contracts: Map<string, Contract> = new Map();
+
+  /**
+   * Create a new contract between two agents.
+   */
+  create(sourceAgentId: string, options: CreateContractOptions): Contract {
+    const contractId = generateId('ctr');
+    const now = hrTimestamp();
+
+    // Assign rule IDs to any rules that don't have them
+    const rules: PricingRule[] = options.pricingRules.map(r => ({
+      ...r,
+      ruleId: (r as PricingRule).ruleId || generateId('rul'),
+    })) as PricingRule[];
+
+    const contract: Contract = {
+      contractId,
+      mode: options.mode || 'TEMPLATE',
+      status: 'ACTIVE',
+      parties: {
+        sourceAgentId,
+        targetAgentId: options.targetAgentId,
+      },
+      pricingRules: rules,
+      effectiveFrom: options.effectiveFrom || now,
+      effectiveUntil: options.effectiveUntil,
+      metadata: options.metadata || {},
+      createdAt: now,
+    };
+
+    this.contracts.set(contractId, contract);
+    return contract;
+  }
+
+  /**
+   * Get contract by ID.
+   */
+  get(contractId: string): Contract {
+    const contract = this.contracts.get(contractId);
+    if (!contract) throw new ContractNotFoundError(contractId);
+    return contract;
+  }
+
+  /**
+   * Find active contract between two agents.
+   */
+  findActive(sourceAgentId: string, targetAgentId: string): Contract | undefined {
+    const now = new Date();
+    for (const c of this.contracts.values()) {
+      if (
+        c.status === 'ACTIVE' &&
+        c.parties.sourceAgentId === sourceAgentId &&
+        c.parties.targetAgentId === targetAgentId &&
+        c.effectiveFrom <= now &&
+        (!c.effectiveUntil || c.effectiveUntil > now)
+      ) {
+        return c;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Dynamic negotiation: propose terms.
+   * Returns a DRAFT contract that the counterparty can accept or counter.
+   */
+  propose(sourceAgentId: string, options: CreateContractOptions): Contract {
+    const contract = this.create(sourceAgentId, { ...options, mode: 'DYNAMIC' });
+    contract.status = 'PROPOSED';
+    return contract;
+  }
+
+  /**
+   * Accept a proposed contract — transitions to ACTIVE.
+   */
+  accept(contractId: string): Contract {
+    const contract = this.get(contractId);
+    if (contract.status !== 'PROPOSED') {
+      throw new UMPError(`Cannot accept contract in status: ${contract.status}`, 'INVALID_STATE');
+    }
+    contract.status = 'ACTIVE';
+    return contract;
+  }
+
+  /**
+   * Counter-propose: create a new proposal based on an existing one with modified terms.
+   */
+  counter(
+    contractId: string,
+    counterAgentId: string,
+    modifiedRules: Omit<PricingRule, 'ruleId'>[],
+  ): Contract {
+    const original = this.get(contractId);
+    original.status = 'EXPIRED'; // superseded
+
+    return this.propose(counterAgentId, {
+      targetAgentId: original.parties.sourceAgentId, // reverse direction
+      pricingRules: modifiedRules,
+      metadata: {
+        ...original.metadata,
+        counterTo: contractId,
+      },
+    });
+  }
+
+  /**
+   * Terminate a contract.
+   */
+  terminate(contractId: string): Contract {
+    const contract = this.get(contractId);
+    contract.status = 'TERMINATED';
+    return contract;
+  }
+
+  /**
+   * List contracts for an agent.
+   */
+  listByAgent(agentId: string, status?: ContractStatus): Contract[] {
+    return Array.from(this.contracts.values()).filter(c => {
+      const partyMatch =
+        c.parties.sourceAgentId === agentId ||
+        c.parties.targetAgentId === agentId;
+      if (!partyMatch) return false;
+      if (status && c.status !== status) return false;
+      return true;
+    });
+  }
+}

package/src/terms/index.ts

@@ -0,0 +1,2 @@
+export { ContractManager } from './contract-manager';
+export { MeteringEngine } from './metering';

package/src/terms/metering.ts

@@ -0,0 +1,106 @@
+import type { UsageEvent, OutcomeAttestation } from '../types';
+import { generateId, hrTimestamp } from '../utils/id';
+
+/**
+ * MeteringEngine — Layer 2 primitive
+ *
+ * Captures usage events with cryptographic integrity.
+ * Supports idempotent event submission, deduplication, and
+ * outcome attestation for result-based billing.
+ */
+export class MeteringEngine {
+  private events: Map<string, UsageEvent> = new Map();
+  private seenIds: Set<string> = new Set(); // idempotency guard
+
+  /**
+   * Record a usage event.
+   * Idempotent: resubmitting the same eventId is a no-op.
+   */
+  record(event: Omit<UsageEvent, 'eventId' | 'timestamp'> & { eventId?: string }): UsageEvent {
+    const eventId = event.eventId || generateId('evt');
+
+    // Idempotency: skip if already recorded
+    if (this.seenIds.has(eventId)) {
+      return this.events.get(eventId)!;
+    }
+
+    const fullEvent: UsageEvent = {
+      ...event,
+      eventId,
+      timestamp: hrTimestamp(),
+    };
+
+    this.events.set(eventId, fullEvent);
+    this.seenIds.add(eventId);
+    return fullEvent;
+  }
+
+  /**
+   * Record a batch of usage events.
+   */
+  recordBatch(events: Array<Omit<UsageEvent, 'eventId' | 'timestamp'>>): UsageEvent[] {
+    return events.map(e => this.record(e));
+  }
+
+  /**
+   * Create an outcome attestation for result-based billing.
+   */
+  attestOutcome(data: {
+    outcomeType: OutcomeAttestation['outcomeType'];
+    claimedBy: string;
+    evidence: OutcomeAttestation['evidence'];
+    verificationMethod: OutcomeAttestation['verificationMethod'];
+    confidenceScore: number;
+    disputeWindow?: number;
+  }): OutcomeAttestation {
+    return {
+      outcomeId: generateId('out'),
+      outcomeType: data.outcomeType,
+      claimedBy: data.claimedBy,
+      evidence: data.evidence,
+      verificationMethod: data.verificationMethod,
+      verifiedBy: undefined,
+      confidenceScore: data.confidenceScore,
+      attestationStatus: 'CLAIMED',
+      disputeWindow: data.disputeWindow || 24 * 60 * 60 * 1000, // 24h default
+    };
+  }
+
+  /**
+   * Get events for a contract within a time range.
+   */
+  getByContract(contractId: string, from?: Date, to?: Date): UsageEvent[] {
+    let results = Array.from(this.events.values())
+      .filter(e => e.contractId === contractId);
+
+    if (from) results = results.filter(e => e.timestamp >= from);
+    if (to) results = results.filter(e => e.timestamp <= to);
+
+    return results.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+  }
+
+  /**
+   * Get events for a specific agent (as source or target).
+   */
+  getByAgent(agentId: string, limit = 100): UsageEvent[] {
+    return Array.from(this.events.values())
+      .filter(e => e.sourceAgentId === agentId || e.targetAgentId === agentId)
+      .slice(-limit);
+  }
+
+  /**
+   * Get a specific event by ID.
+   */
+  get(eventId: string): UsageEvent | undefined {
+    return this.events.get(eventId);
+  }
+
+  /**
+   * Get total metered quantity for a contract.
+   */
+  totalQuantity(contractId: string): number {
+    return Array.from(this.events.values())
+      .filter(e => e.contractId === contractId)
+      .reduce((sum, e) => sum + e.quantity, 0);
+  }
+}