business-as-code 2.1.3 → 2.4.0

package/src/finance/identity.ts

@@ -0,0 +1,31 @@
+/**
+ * AgentIdentity + AgentMerchant — cross-provider identity for the four
+ * agentic-commerce gaps Stripe didn't ship at Sessions 2026:
+ *   - Agent-as-buyer with delegation (B2A2D, B2A2B)
+ *   - Agent-as-merchant (Stripe makes you wire through Connect manually)
+ */
+
+export interface AgentIdentity {
+  $id: string
+  $type: 'AgentIdentity'
+  /** Worker the identity is for (Person/Agent/Role); ThingRef shape. */
+  workerRef: string
+  /**
+   * When the agent buys on behalf of someone else (B2A2D, B2A2B).
+   * Null when buying for self (B2A or A2A).
+   */
+  delegatedFor?: string
+  /** OAuth / capability scopes the identity carries. */
+  scopes: string[]
+  /** Per-provider credentials (Stripe Projects keys, Tempo wallet IDs, etc.). */
+  providerCreds: Record<string, unknown>
+}
+
+export interface AgentMerchant {
+  $id: string
+  $type: 'AgentMerchant'
+  workerRef: string
+  /** Account that receives payouts. */
+  payoutAccountRef: string
+  providerData: Record<string, unknown>
+}

package/src/finance/index.ts

@@ -0,0 +1,117 @@
+/**
+ * business-as-code/finance — the outcome-contract economic substrate.
+ *
+ * Source of truth for the economic primitives of the agentic economy:
+ * Money/Cost/Budget value types, Account/Card/Ledger/Identity payment types,
+ * Pricing, OutcomeContract, ProofPredicate, SLAPolicy, RefundContract,
+ * AuthorityBoundary, and the FinanceProvider/Merchant ports.
+ *
+ * Finance is foundational here because it is the core of the default OKRs
+ * (Revenue / Growth / Profit). `services-as-software` and `digital-tools`
+ * consume these primitives directly from here.
+ *
+ * Importable via the `business-as-code/finance` subpath export.
+ *
+ * @packageDocumentation
+ */
+
+// Money + Cost + Budget + spend-control
+export type {
+  FiatCurrency,
+  StablecoinCurrency,
+  CryptoCurrency,
+  Currency,
+  Money,
+  Cost,
+  Budget,
+  BudgetScope,
+  SpendControl,
+  CostModel,
+} from './types.js'
+
+// Account + transfer
+export type { Account, AccountSpec, TransferOpts, TransferResult } from './account.js'
+
+// Card (Issuing)
+export type { Card, CardSpec } from './card.js'
+
+// Ledger
+export type { LedgerEntry, LedgerLine } from './ledger.js'
+
+// Identity (cross-provider)
+export type { AgentIdentity, AgentMerchant } from './identity.js'
+
+// ProofPredicate union + factories
+export type { ProofPredicate } from './proof-predicate.js'
+export {
+  SchemaMatch,
+  EvaluatorPass,
+  HumanSign,
+  External,
+  LoadBearingPass,
+  OverallFloor,
+  UnmetRequirementsPass,
+  AND,
+  OR,
+} from './proof-predicate.js'
+
+// Outcome contract + proof of result
+export type {
+  OutcomeContract,
+  OutcomeContractBase,
+  OutcomeContractWithExpiresAt,
+  OutcomeContractWithTimeoutDays,
+  OutcomeContractWithTiers,
+  ProofOfResult,
+} from './outcome-contract.js'
+export { resolveOutcomeAmount } from './outcome-contract.js'
+
+// SLA policy
+export type { SLAPolicy, SLATarget } from './sla.js'
+
+// Refund contract + catalog
+export type { RefundContractRef } from './refund.js'
+export { RefundContracts } from './refund.js'
+
+// Authority boundary + catalog
+export type { AuthorityBoundaryRef } from './authority.js'
+export { AuthorityBoundaries } from './authority.js'
+
+// Pricing factories — type + value merged on the same name (Pricing.outcome(...), etc.)
+export type {
+  OutcomeTier,
+  PerInvocationTier,
+  MeteredEntry,
+  CompositeBase,
+  SubscriptionPlan,
+  PercentOfBasis,
+} from './pricing.js'
+export { Pricing, money } from './pricing.js'
+export type { Pricing as PricingValue } from './pricing.js'
+
+// Provider port + capabilities
+export type {
+  FinanceProvider,
+  ProviderCapabilities,
+  ProviderRail,
+  ChargeOpts,
+  ChargeResult,
+  RefundResult,
+  EscrowHandle,
+  ReleaseResult,
+  SubscribeOpts,
+  Subscription,
+  MeterEvent,
+} from './port.js'
+
+// Merchant / Connect provisioning (product-line + hosted checkout + payout)
+export type {
+  MerchantCapable,
+  PriceInterval,
+  ProvisionProductOpts,
+  ProvisionedProduct,
+  CheckoutOpts,
+  CheckoutSession,
+  PayoutOpts,
+  PayoutResult,
+} from './merchant.js'

package/src/finance/ledger.ts

@@ -0,0 +1,26 @@
+/**
+ * LedgerEntry — double-entry record. Every entry IS an Action under the SVO substrate.
+ *
+ * Invariant: per-currency, sum(debits.amount) === sum(credits.amount).
+ * The ledger is append-only; reversals are new entries with opposite sign.
+ */
+
+import type { Money } from './types.js'
+
+export interface LedgerEntry {
+  $id: string
+  $type: 'LedgerEntry'
+  /** Reference to the underlying Action (digital-objects ActionRef shape). */
+  actionRef: string
+  debits: LedgerLine[]
+  credits: LedgerLine[]
+  /** Optional human-readable memo. */
+  memo?: string
+  /** ISO-8601 timestamp. */
+  postedAt: string
+}
+
+export interface LedgerLine {
+  accountRef: string
+  amount: Money
+}

package/src/finance/merchant.ts

@@ -0,0 +1,127 @@
+/**
+ * Merchant provisioning — the platform/Connect half of the FinanceProvider
+ * port: turn a priced Offer into a sellable product-line under a holdco, and
+ * mint a checkout for it.
+ *
+ * Motivation (added by explore.startups.studio B4, issue #222): the substrate
+ * `FinanceProvider` port modeled CHARGING (`charge`/`refund`/`subscribe`) but
+ * not the upstream provisioning a hosted-checkout flow needs:
+ *   1. provision a Product + Price under a platform account (Stripe Connect:
+ *      one platform / holdco, many product-lines), keyed to a caller-supplied
+ *      durable id (NOT a name — names are mutable),
+ *   2. open a hosted Checkout session that returns a redirectable URL,
+ *   3. report a payout against the platform balance.
+ *
+ * Stripe ships all three; the gap was only that the port did not EXPRESS them,
+ * so a consumer had to reach past the port into raw Stripe. These types close
+ * that gap so the consumer wires through the port (Stripe / Tempo / x402 are
+ * interchangeable behind it).
+ */
+
+import type { Money } from './types.js'
+import type { Pricing } from './pricing.js'
+
+/** How a provisioned Price recurs — mirrors Stripe `price.recurring.interval`. */
+export type PriceInterval = 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+/**
+ * Provision a per-product-line Product + Price under the platform/holdco
+ * account. `merchantRef` is the caller's DURABLE key for the product-line
+ * (e.g. a Startup Id) — adapters MUST round-trip it as provider metadata so a
+ * re-provision is idempotent on it, NOT on the (mutable) display name.
+ */
+export interface ProvisionProductOpts {
+  /** Caller's durable product-line key (e.g. Startup Id). The idempotency anchor. */
+  merchantRef: string
+  /** Display name for the product (mutable; never used as the key). */
+  name: string
+  /** Optional product description. */
+  description?: string
+  /** The unit price of the representative tier. */
+  price: Money
+  /** Recurring interval; omit for a one-time price. */
+  interval?: PriceInterval
+  /** The full authored Pricing architecture (carried as provider metadata for audit). */
+  pricing?: Pricing
+  /** Idempotency key for at-most-once provisioning. */
+  idempotencyKey?: string
+  /** Provider-specific opts; pass-through. */
+  providerOpts?: Record<string, unknown>
+}
+
+export interface ProvisionedProduct {
+  $id: string
+  $type: 'Product'
+  /** Echoed durable product-line key. */
+  merchantRef: string
+  /** Provider product + price ids. */
+  providerData: { provider: string; productId: string; priceId: string }
+}
+
+/** Open a hosted-checkout session for a provisioned Price. */
+export interface CheckoutOpts {
+  /** The provider price id (from {@link ProvisionedProduct}). */
+  priceId: string
+  /** Caller's durable product-line key — round-tripped onto the resulting payment. */
+  merchantRef: string
+  /** Quantity of the price to purchase (default 1). */
+  quantity?: number
+  /** Where the provider redirects on success (may carry a `{CHECKOUT_SESSION_ID}` template). */
+  successUrl: string
+  /** Where the provider redirects on cancel. */
+  cancelUrl: string
+  /** Mode of the session: one-time payment vs. recurring subscription. */
+  mode?: 'payment' | 'subscription'
+  /** Arbitrary metadata to attach to the session + resulting payment (e.g. correlation ids). */
+  metadata?: Record<string, string>
+  /** Idempotency key for at-most-once session creation. */
+  idempotencyKey?: string
+  /** Provider-specific opts; pass-through. */
+  providerOpts?: Record<string, unknown>
+}
+
+export interface CheckoutSession {
+  $id: string
+  $type: 'CheckoutSession'
+  /** The redirectable hosted-checkout URL the buyer is sent to. */
+  url: string
+  /** Caller's durable product-line key. */
+  merchantRef: string
+  status: 'open' | 'complete' | 'expired'
+  providerData: { provider: string; externalId: string }
+}
+
+export interface PayoutOpts {
+  /** Amount to pay out from the platform balance. */
+  amount: Money
+  /** The connected/destination account ref receiving the payout. */
+  destinationRef: string
+  /** Idempotency key for at-most-once payout. */
+  idempotencyKey?: string
+  providerOpts?: Record<string, unknown>
+}
+
+export interface PayoutResult {
+  $id: string
+  $type: 'Payout'
+  amount: Money
+  destinationRef: string
+  status: 'pending' | 'paid' | 'failed'
+  /** ISO-8601 timestamp. */
+  createdAt: string
+  providerData: { provider: string; externalId: string }
+}
+
+/**
+ * The merchant/platform-provisioning capability set. A FinanceProvider MAY
+ * implement these (gated by {@link ProviderCapabilities.merchant}); a
+ * charge-only adapter omits them.
+ */
+export interface MerchantCapable {
+  /** Provision (idempotently, on `merchantRef`) a Product + Price under the platform/holdco. */
+  provisionProduct(opts: ProvisionProductOpts): Promise<ProvisionedProduct>
+  /** Open a hosted-checkout session for a provisioned price; returns a redirectable URL. */
+  createCheckoutSession(opts: CheckoutOpts): Promise<CheckoutSession>
+  /** Report a payout against the platform balance to a destination account. */
+  payout?(opts: PayoutOpts): Promise<PayoutResult>
+}

package/src/finance/outcome-contract.ts

@@ -0,0 +1,157 @@
+/**
+ * OutcomeContract — definition-of-done + escrow + release condition.
+ * Distinct from OutputContract (technical schema; lives in services-as-software).
+ *
+ * The predicate is evaluated against the runtime state of a Service invocation;
+ * when it passes, escrow releases funds to the seller.
+ */
+
+import type { OutcomeTier } from './pricing.js'
+import type { Money } from './types.js'
+import type { ProofPredicate } from './proof-predicate.js'
+
+/**
+ * Fields shared by all {@link OutcomeContract} variants.
+ *
+ * Split from the timeout + amount fields so the discriminated union below can
+ * express "exactly one of `expiresAt` / `timeoutDays`" AND "exactly one of
+ * `amount` / `tiers`" at the type level.
+ */
+export interface OutcomeContractBase {
+  $id: string
+  $type: 'OutcomeContract'
+  /** Worker (Person/Agent/Role) that bought the outcome. */
+  buyer: string
+  /** Worker (Person/Agent/Role) that sold/delivers the outcome. */
+  seller: string
+  /** Service this contract is bound to. */
+  serviceRef: string
+  predicate: ProofPredicate
+  /** Account holding escrowed funds until predicate passes. */
+  escrowAccountRef?: string
+  onTimeout?: 'auto-cancel' | 'auto-refund' | 'escalate'
+}
+
+/**
+ * Variant carrying an absolute ISO-8601 *timestamp* (e.g.
+ * `'2026-05-12T00:00:00Z'`). The runtime treats this as the wall-clock
+ * deadline. Carries a single {@link Money} `amount`.
+ */
+export interface OutcomeContractWithExpiresAt extends OutcomeContractBase {
+  /**
+   * Absolute ISO-8601 timestamp — the contract expires (and `onTimeout` fires)
+   * exactly at this instant. For relative durations from contract creation,
+   * use {@link OutcomeContractWithTimeoutDays.timeoutDays} instead.
+   */
+  expiresAt: string
+  timeoutDays?: never
+  amount: Money
+  tiers?: never
+  selectedTierId?: never
+}
+
+/**
+ * Variant carrying a relative-duration deadline measured in whole days from
+ * contract creation. The runtime computes
+ * `expiresAt = createdAt + timeoutDays * 24h`. Carries a single {@link Money}
+ * `amount`.
+ */
+export interface OutcomeContractWithTimeoutDays extends OutcomeContractBase {
+  /**
+   * Whole days from contract creation until expiry. Mutually exclusive with
+   * {@link OutcomeContractWithExpiresAt.expiresAt}.
+   */
+  timeoutDays: number
+  expiresAt?: never
+  amount: Money
+  tiers?: never
+  selectedTierId?: never
+}
+
+/**
+ * Variant carrying a multi-tier `OutcomeTier[]` mirror of
+ * `Pricing.outcome.tiers`. Used when the Service quotes a tiered price (e.g.
+ * S/M/L by feature complexity) and the headline contract figure should be
+ * computed lazily from the chosen tier rather than baked at declaration time.
+ *
+ * At runtime, `Service.invoke` selects a tier based on input characteristics
+ * and sets `selectedTierId`; the headline {@link Money} amount is then
+ * computed by `tiers.find(t => t.id === selectedTierId)?.amount`.
+ *
+ * Carries `timeoutDays` (the tiered variant currently couples with relative-
+ * duration deadlines; absolute-deadline + tiers can be added later if a
+ * catalog Service needs both).
+ */
+export interface OutcomeContractWithTiers extends OutcomeContractBase {
+  /**
+   * Whole days from contract creation until expiry. Mutually exclusive with
+   * {@link OutcomeContractWithExpiresAt.expiresAt}.
+   */
+  timeoutDays: number
+  expiresAt?: never
+  /**
+   * Mirror of `Pricing.outcome.tiers` — one entry per quoted complexity tier
+   * (e.g. S / M / L). The runtime resolves the headline amount from the
+   * selected tier at invocation time.
+   */
+  tiers: OutcomeTier[]
+  /**
+   * Tier id selected by the runtime at invocation time (e.g. `'S'`). Omitted
+   * at declaration time — `Service.invoke` sets it based on input
+   * characteristics, then a lazy getter computes the headline {@link Money}
+   * amount as `tiers.find(t => t.id === selectedTierId)?.amount`.
+   */
+  selectedTierId?: string
+  /**
+   * The runtime computes the headline amount from the selected tier — never
+   * declared inline on this variant.
+   */
+  amount?: never
+}
+
+/**
+ * Discriminated union — exactly one of `expiresAt` / `timeoutDays` is required,
+ * and exactly one of `amount` / `tiers` is required.
+ *
+ * Use {@link OutcomeContractWithExpiresAt} for absolute deadlines + a single
+ * {@link Money} amount; use {@link OutcomeContractWithTimeoutDays} for
+ * relative durations from contract creation + a single {@link Money} amount;
+ * use {@link OutcomeContractWithTiers} when the Service quotes a tiered price
+ * (S/M/L) and the runtime selects a tier per-invocation.
+ */
+export type OutcomeContract =
+  | OutcomeContractWithExpiresAt
+  | OutcomeContractWithTimeoutDays
+  | OutcomeContractWithTiers
+
+/**
+ * Resolve the headline {@link Money} amount on an {@link OutcomeContract},
+ * lazily computing from `tiers[selectedTierId]` for the
+ * {@link OutcomeContractWithTiers} variant.
+ *
+ * Returns `undefined` for the tiers variant when no tier has been selected
+ * yet (e.g. pre-invocation, at declaration / publish time).
+ */
+export function resolveOutcomeAmount(contract: OutcomeContract): Money | undefined {
+  if (contract.tiers !== undefined) {
+    if (contract.selectedTierId === undefined) return undefined
+    const tier = contract.tiers.find((t) => t.id === contract.selectedTierId)
+    if (!tier) return undefined
+    return { amount: tier.amount, currency: tier.currency ?? 'USD' }
+  }
+  return contract.amount
+}
+
+export interface ProofOfResult {
+  $id: string
+  $type: 'ProofOfResult'
+  contractRef: string
+  /** Worker (Person/Agent/Role) that signed the proof. */
+  signedBy: string
+  /** ISO-8601 timestamp. */
+  signedAt: string
+  /** Action that produced the verifiable output. */
+  outputRef?: string
+  /** Cryptographic signature where applicable. */
+  signature?: string
+}

package/src/finance/port.ts

@@ -0,0 +1,144 @@
+/**
+ * FinanceProvider — port for adapter implementations (Stripe, Tempo, x402,
+ * Privy, Lightspark). Every method is optional and gated by ProviderCapabilities;
+ * adapters declare which capabilities they support.
+ *
+ * Adapter implementations are forthcoming and ship outside the substrate —
+ * none are bundled here.
+ */
+
+import type { Currency, Money, Cost } from './types.js'
+import type { Account, AccountSpec, TransferOpts, TransferResult } from './account.js'
+import type { Card, CardSpec } from './card.js'
+import type { OutcomeContract, ProofOfResult } from './outcome-contract.js'
+import type { StablecoinCurrency } from './types.js'
+import type { MerchantCapable } from './merchant.js'
+
+export type ProviderRail =
+  | 'mpp'
+  | 'spt'
+  | 'x402'
+  | 'streaming'
+  | 'card'
+  | 'wire'
+  | 'ach'
+  | 'lightning'
+  | 'on-chain'
+
+export interface ProviderCapabilities {
+  payments: boolean
+  refunds: boolean
+  issuing: boolean
+  treasury: boolean
+  escrow: boolean
+  subscriptions: boolean
+  metering: boolean
+  /** Platform/Connect product-line provisioning + hosted checkout (see MerchantCapable). */
+  merchant: boolean
+  multiCurrency: boolean
+  currencies: Currency[]
+  stablecoins: StablecoinCurrency[]
+  rails: ProviderRail[]
+}
+
+export interface ChargeOpts {
+  /** Counterparty Worker paying the charge (ThingRef shape). */
+  buyer: string
+  amount: Money
+  /** Service or invocation reference for attribution. */
+  ref?: string
+  /** Idempotency key for at-most-once semantics. */
+  idempotencyKey?: string
+  /** Provider-specific opts; pass-through. */
+  providerOpts?: Record<string, unknown>
+}
+
+export interface ChargeResult {
+  $id: string
+  $type: 'Charge'
+  amount: Money
+  status: 'pending' | 'authorized' | 'captured' | 'failed' | 'refunded'
+  /** ISO-8601 timestamp. */
+  createdAt: string
+  providerData: { provider: string; externalId: string }
+}
+
+export interface RefundResult {
+  $id: string
+  $type: 'Refund'
+  chargeId: string
+  amount: Money
+  /** ISO-8601 timestamp. */
+  createdAt: string
+}
+
+export interface EscrowHandle {
+  $id: string
+  contractRef: string
+  state: 'held' | 'released' | 'expired' | 'cancelled'
+  providerData: { provider: string; externalId: string }
+}
+
+export interface ReleaseResult {
+  $id: string
+  escrowHandle: string
+  releasedAt: string
+  /** ISO-8601 timestamp. */
+  amount: Money
+}
+
+export interface SubscribeOpts {
+  buyer: string
+  planRef: string
+  /** Provider-specific opts; pass-through. */
+  providerOpts?: Record<string, unknown>
+}
+
+export interface Subscription {
+  $id: string
+  $type: 'Subscription'
+  buyer: string
+  planRef: string
+  state: 'active' | 'paused' | 'cancelled' | 'past-due'
+  /** ISO-8601 timestamp. */
+  startedAt: string
+  providerData: { provider: string; externalId: string }
+}
+
+export interface MeterEvent {
+  /** Subscription or customer this event meters against. */
+  subscriptionRef: string
+  event: string
+  quantity: bigint
+  /** ISO-8601 timestamp. */
+  occurredAt: string
+}
+
+export interface FinanceProvider extends Partial<MerchantCapable> {
+  readonly name: string
+  readonly capabilities: ProviderCapabilities
+
+  // Charge / refund
+  charge(opts: ChargeOpts): Promise<ChargeResult>
+  refund(chargeId: string, amount?: Money): Promise<RefundResult>
+
+  // Cards (optional)
+  issueCard?(spec: CardSpec): Promise<Card>
+  lockCard?(cardId: string): Promise<void>
+
+  // Treasury (optional)
+  openAccount?(spec: AccountSpec): Promise<Account>
+  balance?(accountId: string): Promise<Money>
+  transfer?(opts: TransferOpts): Promise<TransferResult>
+
+  // Outcome / escrow (optional; built on MPP Sessions / x402 escrow / native)
+  escrow?(contract: OutcomeContract): Promise<EscrowHandle>
+  release?(escrowHandle: string, proof: ProofOfResult): Promise<ReleaseResult>
+
+  // Subscriptions / metering (optional)
+  subscribe?(opts: SubscribeOpts): Promise<Subscription>
+  meter?(event: MeterEvent): Promise<void>
+
+  // Cost capture — provider-side cost reporting (e.g. LLM provider per-token)
+  captureCost?(cost: Omit<Cost, '$id' | '$type'>): Promise<Cost>
+}