business-as-code 2.3.0 → 2.4.0

package/src/finance/pricing.ts

@@ -0,0 +1,197 @@
+/**
+ * Pricing — discriminated union with five factory variants.
+ *
+ *   outcome       — pay on delivery; tiers by complexity (S/M/L)
+ *   subscription  — recurring plan + optional metered overage
+ *   perInvocation — flat per-call with included-tier ladder
+ *   composite     — one-time base + metered events
+ *   percent-of    — proportional charge against a realised basis
+ *                   (invoice amount, collected amount, transaction volume)
+ *                   with optional cap / floor
+ *
+ * Each factory returns a typed Pricing value with discriminator on .kind.
+ */
+
+import type { Currency, Money } from './types.js'
+import type { SLATarget } from './sla.js'
+
+export interface OutcomeTier {
+  id: string
+  amount: bigint
+  currency?: Currency
+  description?: string
+}
+
+export interface PerInvocationTier {
+  id: string
+  amount: bigint
+  /** Number of invocations included before per-tier billing applies. */
+  includedPerMonth?: number
+  /** Per-invocation overage cost above included. */
+  overage?: bigint
+}
+
+/**
+ * A single metered-billing line item. `description` is genuinely optional —
+ * callers may omit it from inline literals AND from the {@link Pricing}
+ * factory calls (`Pricing.subscription` / `Pricing.composite`).
+ */
+export interface MeteredEntry {
+  event: string
+  amount: bigint
+  description?: string
+}
+
+/**
+ * Optional one-time base charge on a {@link Pricing.composite} plan. `description`
+ * is optional under `exactOptionalPropertyTypes`.
+ */
+export interface CompositeBase {
+  id: string
+  amount: bigint
+  description?: string
+}
+
+/**
+ * Recurring plan portion of a {@link Pricing.subscription}. Shared between the
+ * `Pricing` discriminated union and the {@link Pricing.subscription} factory
+ * so the two shapes never drift.
+ */
+export interface SubscriptionPlan {
+  id: string
+  amount: bigint
+  currency: Currency
+  interval: 'day' | 'week' | 'month' | 'quarter' | 'year'
+}
+
+/**
+ * Standard bases the {@link Pricing.percentOf} runtime knows how to resolve
+ * at settlement time. Adapters MAY accept arbitrary basis strings for
+ * domain-specific metering, but the canonical four cover the common cases:
+ *
+ *   invoice-amount       — face value of an outbound invoice
+ *   collected-amount     — funds actually received (post-settlement)
+ *   transaction-volume   — gross payment volume processed
+ *   <custom string>      — provider-defined; must be resolvable in the
+ *                          metering runtime
+ */
+export type PercentOfBasis =
+  | 'invoice-amount'
+  | 'collected-amount'
+  | 'transaction-volume'
+  | (string & {})
+
+export type Pricing =
+  | {
+      kind: 'outcome'
+      tiers: OutcomeTier[]
+      sla?: SLATarget
+    }
+  | {
+      kind: 'subscription'
+      plan: SubscriptionPlan
+      metered?: MeteredEntry[]
+      sla?: SLATarget
+    }
+  | {
+      kind: 'per-invocation'
+      tiers: PerInvocationTier[]
+    }
+  | {
+      kind: 'composite'
+      base: CompositeBase
+      metered: MeteredEntry[]
+    }
+  | {
+      kind: 'percent-of'
+      basis: PercentOfBasis
+      /**
+       * Rate in basis points (1/100ths of a percent). Examples: `200` = 2%,
+       * `75` = 0.75%, `1000` = 10%.
+       *
+       * The metering runtime computes the charge as
+       * `(realised_basis * rateBasisPoints) / 10000`, then clamps the
+       * result by the optional `cap` / `floor` (when present).
+       */
+      rateBasisPoints: number
+      /** Optional upper bound on the per-event charge. */
+      cap?: Money
+      /** Optional lower bound on the per-event charge. */
+      floor?: Money
+    }
+
+export const Pricing = {
+  outcome(opts: { tiers: OutcomeTier[]; sla?: SLATarget }): Pricing {
+    if (opts.sla !== undefined) {
+      return { kind: 'outcome', tiers: opts.tiers, sla: opts.sla }
+    }
+    return { kind: 'outcome', tiers: opts.tiers }
+  },
+
+  subscription(opts: {
+    plan: SubscriptionPlan
+    metered?: MeteredEntry[]
+    sla?: SLATarget
+  }): Pricing {
+    const result: Extract<Pricing, { kind: 'subscription' }> = {
+      kind: 'subscription',
+      plan: opts.plan,
+    }
+    if (opts.metered !== undefined) result.metered = opts.metered
+    if (opts.sla !== undefined) result.sla = opts.sla
+    return result
+  },
+
+  perInvocation(opts: { tiers: PerInvocationTier[] }): Pricing {
+    return { kind: 'per-invocation', tiers: opts.tiers }
+  },
+
+  composite(opts: { base: CompositeBase; metered: MeteredEntry[] }): Pricing {
+    return { kind: 'composite', base: opts.base, metered: opts.metered }
+  },
+
+  /**
+   * Percent-of-basis pricing — proportional charge against a realised
+   * basis (e.g. invoice amount, collected amount, transaction volume).
+   *
+   * The metering runtime resolves `basis` to a concrete bigint at
+   * settlement time, then computes the charge as
+   * `(realised_basis * rateBasisPoints) / 10000`, optionally clamped by
+   * `cap` / `floor`.
+   *
+   * @example AR Service: 2% of collected funds
+   * ```ts
+   * Pricing.percentOf({ basis: 'collected-amount', rateBasisPoints: 200 })
+   * ```
+   *
+   * @example Capped: 0.75% of transaction volume, max $50/event
+   * ```ts
+   * Pricing.percentOf({
+   *   basis: 'transaction-volume',
+   *   rateBasisPoints: 75,
+   *   cap: { amount: 5000n, currency: 'USD' },
+   * })
+   * ```
+   */
+  percentOf(opts: {
+    basis: PercentOfBasis
+    rateBasisPoints: number
+    cap?: Money
+    floor?: Money
+  }): Pricing {
+    const result: Extract<Pricing, { kind: 'percent-of' }> = {
+      kind: 'percent-of',
+      basis: opts.basis,
+      rateBasisPoints: opts.rateBasisPoints,
+    }
+    if (opts.cap !== undefined) result.cap = opts.cap
+    if (opts.floor !== undefined) result.floor = opts.floor
+    return result
+  },
+}
+
+/** Convenience: build a Money value from a bigint + currency. */
+export const money = (amount: bigint, currency: Currency = 'USD'): Money => ({
+  amount,
+  currency,
+})

package/src/finance/proof-predicate.ts

@@ -0,0 +1,106 @@
+/**
+ * ProofPredicate — composable predicates that gate outcome-based settlement.
+ *
+ * Stripe's MPP Sessions ship escrow but no outcome-predicate-driven release —
+ * this module is the gap-filler. SaS's Service.outcomeContract.predicate
+ * uses these to express "definition of done."
+ *
+ * Seven leaf predicates + AND/OR composition:
+ *   - schema-match            : output matches schema
+ *   - evaluator-pass          : EvaluatorPanel approves at threshold
+ *   - human-sign              : human with signerRoles signs
+ *   - external                : external verifier (e.g. github CI + merged) approves
+ *   - load-bearing-pass       : a named subset of rubric items all pass (sb killThreshold)
+ *   - overall-floor           : N of total rubric items pass (sb killThreshold)
+ *   - unmet-requirements-pass : no `severity: 'blocking'` UnmetRequirements remain
+ *                               (sb-n7d open-blocking gate); when `categories` is
+ *                               supplied, only those categories are checked.
+ */
+
+export type ProofPredicate =
+  | { kind: 'schema-match'; schema: unknown }
+  | {
+      kind: 'evaluator-pass'
+      panelRef: string | 'self'
+      minScore: number | 'all-approved' | 'majority'
+    }
+  | { kind: 'human-sign'; signerRoles: string[]; when?: string }
+  | { kind: 'external'; verifier: string; spec: unknown }
+  | { kind: 'load-bearing-pass'; itemSet: string[] }
+  | { kind: 'overall-floor'; minPasses: number; outOfTotal: number }
+  | { kind: 'unmet-requirements-pass'; categories?: string[] }
+  | { kind: 'and'; predicates: ProofPredicate[] }
+  | { kind: 'or'; predicates: ProofPredicate[] }
+
+export const SchemaMatch = (schema: unknown): ProofPredicate => ({
+  kind: 'schema-match',
+  schema,
+})
+
+export const EvaluatorPass = (opts: {
+  panelRef: string | 'self'
+  minScore: number | 'all-approved' | 'majority'
+}): ProofPredicate => ({
+  kind: 'evaluator-pass',
+  panelRef: opts.panelRef,
+  minScore: opts.minScore,
+})
+
+export const HumanSign = (opts: { signerRoles: string[]; when?: string }): ProofPredicate => {
+  if (opts.when !== undefined) {
+    return { kind: 'human-sign', signerRoles: opts.signerRoles, when: opts.when }
+  }
+  return { kind: 'human-sign', signerRoles: opts.signerRoles }
+}
+
+export const External = (opts: { verifier: string; spec: unknown }): ProofPredicate => ({
+  kind: 'external',
+  verifier: opts.verifier,
+  spec: opts.spec,
+})
+
+export const LoadBearingPass = (itemSet: string[]): ProofPredicate => ({
+  kind: 'load-bearing-pass',
+  itemSet,
+})
+
+export const OverallFloor = (opts: { minPasses: number; outOfTotal: number }): ProofPredicate => ({
+  kind: 'overall-floor',
+  minPasses: opts.minPasses,
+  outOfTotal: opts.outOfTotal,
+})
+
+/**
+ * `UnmetRequirementsPass` — sb-n7d's open-blocking gate as a first-class
+ * predicate.
+ *
+ * Passes iff no `severity: 'blocking'` UnmetRequirement is present in the
+ * verify-time evaluation context. `severity: 'warning'` items are ignored.
+ *
+ * When `categories` is supplied, only requirements whose `category` matches
+ * one of the listed values are considered (others are ignored regardless of
+ * severity). When omitted, ALL categories are inspected.
+ *
+ * @example
+ *   // Any blocking unmet requirement fails the predicate.
+ *   UnmetRequirementsPass()
+ *
+ *   // Only blocking items in the 'compliance' or 'security' buckets fail.
+ *   UnmetRequirementsPass({ categories: ['compliance', 'security'] })
+ */
+export const UnmetRequirementsPass = (opts?: { categories?: string[] }): ProofPredicate => {
+  if (opts?.categories !== undefined) {
+    return { kind: 'unmet-requirements-pass', categories: opts.categories }
+  }
+  return { kind: 'unmet-requirements-pass' }
+}
+
+export const AND = (...predicates: ProofPredicate[]): ProofPredicate => ({
+  kind: 'and',
+  predicates,
+})
+
+export const OR = (...predicates: ProofPredicate[]): ProofPredicate => ({
+  kind: 'or',
+  predicates,
+})

package/src/finance/refund.ts

@@ -0,0 +1,52 @@
+/**
+ * RefundContract — typed refund machinery. The 7-pattern catalog (per startup-builder
+ * SERVICES.md) defines the contractual templates a Service can bind to.
+ *
+ * Stripe's Smart Disputes are consumer-chargeback-shaped; this is B2B SLA-shape.
+ */
+
+export type RefundContractRef =
+  | 'no-charge-if-not-qualified'
+  | 'quality-floor-fail'
+  | 'sla-credit-on-late-delivery'
+  | 'sla-credit-on-late-close'
+  | 'partial-credit-on-partial-delivery'
+  | 'time-bounded-money-back'
+  | 'escalate-to-dispute'
+  | (string & { __brand?: 'RefundContractRef' })
+
+/**
+ * Catalog of canonical refund contracts. Consumers reference by id; substrate
+ * resolves the contract semantics at settlement time.
+ */
+export const RefundContracts = {
+  'no-charge-if-not-qualified': {
+    description:
+      'No charge unless EvaluatorPass + downstream verification confirms work delivered.',
+    triggersAt: 'pre-charge',
+  },
+  'quality-floor-fail': {
+    description: 'Full refund when EvaluatorPanel rejects below quality floor.',
+    triggersAt: 'post-quality-review',
+  },
+  'sla-credit-on-late-delivery': {
+    description: 'Credit equal to N% of invoice when delivery exceeds OutcomeContract.expiresAt.',
+    triggersAt: 'on-timeout',
+  },
+  'sla-credit-on-late-close': {
+    description: 'Credit on monthly subscription when SLA target (e.g. close-by-day-5) breached.',
+    triggersAt: 'sla-breach',
+  },
+  'partial-credit-on-partial-delivery': {
+    description: 'Pro-rata credit when fraction of work-units delivered (e.g. tickets resolved).',
+    triggersAt: 'post-delivery',
+  },
+  'time-bounded-money-back': {
+    description: 'Full refund within N days of acceptance, no questions asked.',
+    triggersAt: 'on-customer-request',
+  },
+  'escalate-to-dispute': {
+    description: 'Route to ESCALATED_TO_HUMAN_REVIEW state; manual resolution.',
+    triggersAt: 'on-customer-dispute',
+  },
+} as const

package/src/finance/sla.ts

@@ -0,0 +1,33 @@
+/**
+ * SLAPolicy — service-level agreement with auto-credit / auto-refund / escalate
+ * on breach. The SaS book's "outcome-pricing requires you to stand behind quality"
+ * substrate.
+ */
+
+export interface SLATarget {
+  metric:
+    | 'latency-ms'
+    | 'accuracy'
+    | 'on-time'
+    | 'completeness'
+    | 'first-contact-resolution'
+    | 'csat'
+    | string
+  /** Threshold value or expression (e.g. 'day-5', 0.95, 1000). */
+  threshold: number | string
+}
+
+export interface SLAPolicy {
+  $id: string
+  $type: 'SLAPolicy'
+  serviceRef: string
+  targets: SLATarget[]
+  onBreach: {
+    /** Percent of charge to credit back (0-100). */
+    creditPercent?: number
+    /** Percent of charge to refund (0-100). */
+    refundPercent?: number
+    /** Worker (Person/Agent/Role) to escalate to. */
+    escalateTo?: string
+  }
+}

package/src/finance/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Core value types — Money, Cost, Budget, SpendControl, CostModel.
+ *
+ * Money uses bigint in smallest currency unit (cents/satoshis/wei) for precision.
+ * Refs use plain string with brand comment; cross-package nominal types deferred.
+ */
+
+export type FiatCurrency = 'USD' | 'EUR' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | string
+export type StablecoinCurrency = 'USDC' | 'PYUSD' | 'USDT' | 'USDG' | 'USDSui' | 'CASH' | string
+export type CryptoCurrency = 'BTC' | 'ETH' | 'SOL'
+export type Currency = FiatCurrency | StablecoinCurrency | CryptoCurrency
+
+export interface Money {
+  amount: bigint
+  currency: Currency
+}
+
+/** Cost incurred by an Action — every cascade Function call captures one. */
+export interface Cost {
+  $id: string
+  $type: 'Cost'
+  /** Reference to the underlying Action (digital-objects ActionRef shape). */
+  actionRef: string
+  amount: Money
+  /** Provider that incurred the cost: 'openai' | 'anthropic' | 'stripe' | ... */
+  provider: string
+  category: 'inference' | 'compute' | 'storage' | 'api' | 'human' | 'rail-fee' | 'other'
+  /** ISO-8601 timestamp. */
+  capturedAt: string
+}
+
+/** Where a Budget applies. */
+export type BudgetScope =
+  | { kind: 'worker'; ref: string }
+  | { kind: 'function'; ref: string }
+  | { kind: 'goal'; ref: string }
+  | { kind: 'experiment'; ref: string }
+  | { kind: 'tenant'; ref: string }
+
+export interface Budget {
+  $id: string
+  $type: 'Budget'
+  scope: BudgetScope
+  cap: Money
+  period: 'daily' | 'weekly' | 'monthly' | 'one-time'
+  /** ISO-8601 timestamp; absent for one-time budgets. */
+  resetAt?: string
+}
+
+export interface SpendControl {
+  budgetRef: string
+  /** 0-1 fraction of cap — warn when soft threshold crossed. */
+  soft?: number
+  /** 0-1 fraction of cap — block/escalate when hard threshold crossed. */
+  hard: number
+  onBreach: 'block' | 'escalate' | 'warn'
+  /** Worker to escalate to (Person/Agent/Role); ThingRef shape. */
+  escalateTo?: string
+}
+
+/** Declared cost model on a Function or Service. */
+export interface CostModel {
+  /** Per-invocation flat cost (cents in smallest unit). */
+  perInvocation?: bigint
+  /** Per-transaction cost (e.g. per-token, per-row). */
+  perTx?: bigint
+  /** Per round of agent execution (e.g. per-dev-agent-round). */
+  perAgentRound?: bigint
+  /** Per external API call. */
+  perApiCall?: bigint
+  /** Per-symbol or per-unit-of-output. */
+  perUnit?: bigint
+  /** Hourly rate for human work. */
+  perHour?: bigint
+}