@happyvertical/smrt-sales 0.57.9 → 0.57.11

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.57.9",
+  "packageVersion": "0.57.11",
   "objects": {
     "@happyvertical/smrt-sales:AgreementCollection": {
       "name": "agreementcollection",
@@ -4670,7 +4670,7 @@
       "collectionExportName": "EarnerCollectionCollection",
       "schema": {
         "tableName": "earners",
-        "ddl": "CREATE TABLE IF NOT EXISTS \"earners\" (\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"tenant_id\" UUID,\n  \"profile_id\" UUID,\n  \"display_name\" TEXT DEFAULT '',\n  \"status\" TEXT DEFAULT 'pending',\n  \"payout_method\" TEXT DEFAULT 'bank_transfer',\n  \"payout_threshold_cents\" INTEGER DEFAULT 5000,\n  \"payout_schedule_key\" TEXT DEFAULT 'manual',\n  \"currency\" TEXT DEFAULT 'USD',\n  \"metadata\" TEXT DEFAULT '{}'\n);",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"earners\" (\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"tenant_id\" UUID,\n  \"kind\" TEXT DEFAULT 'person',\n  \"profile_id\" UUID,\n  \"display_name\" TEXT DEFAULT '',\n  \"status\" TEXT DEFAULT 'pending',\n  \"payout_method\" TEXT DEFAULT 'bank_transfer',\n  \"payout_destination\" TEXT DEFAULT '{}',\n  \"payout_threshold_cents\" INTEGER DEFAULT 5000,\n  \"payout_schedule_key\" TEXT DEFAULT 'manual',\n  \"currency\" TEXT DEFAULT 'USD',\n  \"metadata\" TEXT DEFAULT '{}'\n);",
         "columns": {
           "id": {
             "type": "UUID",
@@ -4703,6 +4703,12 @@
             "notNull": false,
             "unique": false
           },
+          "kind": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "person"
+          },
           "profile_id": {
             "type": "UUID",
             "referenceKind": "crossPackageRef",
@@ -4727,6 +4733,12 @@
             "unique": false,
             "default": "bank_transfer"
           },
+          "payout_destination": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "{}"
+          },
           "payout_threshold_cents": {
             "type": "INTEGER",
             "notNull": false,
@@ -4777,7 +4789,7 @@
             ]
           }
         ],
-        "version": "b1c567fb"
+        "version": "f9c840f9"
       },
       "importPath": "@happyvertical/smrt-sales/commissions"
     },
@@ -7248,6 +7260,11 @@
             }
           }
         },
+        "kind": {
+          "type": "text",
+          "required": false,
+          "default": "person"
+        },
         "profileId": {
           "type": "crossPackageRef",
           "required": false,
@@ -7268,6 +7285,11 @@
           "required": false,
           "default": "bank_transfer"
         },
+        "payoutDestination": {
+          "type": "text",
+          "required": false,
+          "default": "{}"
+        },
         "payoutThresholdCents": {
           "type": "integer",
           "required": false,
@@ -7335,6 +7357,60 @@
           "returnType": "void",
           "isStatic": false,
           "isPublic": true
+        },
+        "isOrganisation": {
+          "name": "isOrganisation",
+          "async": false,
+          "parameters": [],
+          "returnType": "boolean",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "isTreasury": {
+          "name": "isTreasury",
+          "async": false,
+          "parameters": [],
+          "returnType": "boolean",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "getPayoutDestination": {
+          "name": "getPayoutDestination",
+          "async": false,
+          "parameters": [],
+          "returnType": "PayoutDestination | null",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "setPayoutDestination": {
+          "name": "setPayoutDestination",
+          "async": false,
+          "parameters": [
+            {
+              "name": "destination",
+              "type": "PayoutDestination | null",
+              "optional": false,
+              "unionBranches": [
+                {
+                  "type": "PayoutDestination"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          ],
+          "returnType": "void",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "save": {
+          "name": "save",
+          "async": true,
+          "parameters": [],
+          "returnType": "Promise<this>",
+          "isStatic": false,
+          "isPublic": true
         }
       },
       "decoratorConfig": {
@@ -7370,7 +7446,7 @@
       "collectionExportName": "EarnerCollection",
       "schema": {
         "tableName": "earners",
-        "ddl": "CREATE TABLE IF NOT EXISTS \"earners\" (\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"tenant_id\" UUID,\n  \"profile_id\" UUID,\n  \"display_name\" TEXT DEFAULT '',\n  \"status\" TEXT DEFAULT 'pending',\n  \"payout_method\" TEXT DEFAULT 'bank_transfer',\n  \"payout_threshold_cents\" INTEGER DEFAULT 5000,\n  \"payout_schedule_key\" TEXT DEFAULT 'manual',\n  \"currency\" TEXT DEFAULT 'USD',\n  \"metadata\" TEXT DEFAULT '{}'\n);",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"earners\" (\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"tenant_id\" UUID,\n  \"kind\" TEXT DEFAULT 'person',\n  \"profile_id\" UUID,\n  \"display_name\" TEXT DEFAULT '',\n  \"status\" TEXT DEFAULT 'pending',\n  \"payout_method\" TEXT DEFAULT 'bank_transfer',\n  \"payout_destination\" TEXT DEFAULT '{}',\n  \"payout_threshold_cents\" INTEGER DEFAULT 5000,\n  \"payout_schedule_key\" TEXT DEFAULT 'manual',\n  \"currency\" TEXT DEFAULT 'USD',\n  \"metadata\" TEXT DEFAULT '{}'\n);",
         "columns": {
           "id": {
             "type": "UUID",
@@ -7403,6 +7479,12 @@
             "notNull": false,
             "unique": false
           },
+          "kind": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "person"
+          },
           "profile_id": {
             "type": "UUID",
             "referenceKind": "crossPackageRef",
@@ -7427,6 +7509,12 @@
             "unique": false,
             "default": "bank_transfer"
           },
+          "payout_destination": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "{}"
+          },
           "payout_threshold_cents": {
             "type": "INTEGER",
             "notNull": false,
@@ -7477,7 +7565,7 @@
             ]
           }
         ],
-        "version": "b1c567fb"
+        "version": "f9c840f9"
       },
       "importPath": "@happyvertical/smrt-sales/commissions"
     },

package/dist/referrals.js

@@ -1,3 +1,3 @@
-import "./chunks/__smrt-register__-Czzs3Vof.js";
-import { A as ReferralClickOperation, B as ATTRIBUTION_RESOLUTION_MODES, C as ReferralTouchCollection, D as ReferralCollection, E as assertHttpTargetUrl, F as validateAttributionPolicyTerms, G as REFERRAL_STATUSES, H as REFERRAL_AGREEMENT_STATUSES, I as ATTRIBUTION_CONFLICT_BEHAVIORS, J as AttributionExceptionCollection, K as REFERRAL_TOUCH_KINDS, L as ATTRIBUTION_CREDIT_MODES, M as ReferralAgreement, N as AttributionPolicyCollection, O as Referral, P as AttributionPolicy, R as ATTRIBUTION_EXCEPTION_STATUSES, S as generateReferralCode, T as ReferralLink, U as REFERRAL_LINK_STATUSES, V as REFERRAL_AGREEMENT_APPROVAL_MODES, W as REFERRAL_PROGRAM_STATUSES, Y as AttributionException, _ as REFERRAL_CODE_ALPHABET, a as ReferralAgreementExecutionService, b as ReferralClickValidationError, c as ReferrerCollection, d as ReferralTermSnapshot, f as ReferralProgramCollection, g as MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES, h as MAX_CODE_GENERATION_ATTEMPTS, i as REFERRAL_AGREEMENT_SOURCE_KIND, j as ReferralAgreementCollection, k as ReferralClickOperationCollection, l as Referrer, m as DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES, n as REFERRAL_TERMS_SNAPSHOT_KIND, o as AttributionService, p as ReferralProgram, q as REFERRER_STATUSES, r as ReferralCommissionService, s as QualifiedReferralOverrideError, t as ReferralQualificationService, u as ReferralTermSnapshotCollection, v as REFERRAL_CODE_LENGTH, w as ReferralTouch, x as ReferralLinkCollection, y as ReferralClickReplayConflictError, z as ATTRIBUTION_POLICY_STATUSES } from "./chunks/referrals-CYgrGkEo.js";
+import "./chunks/__smrt-register__-uEzmP44h.js";
+import { A as ReferralClickOperation, B as ATTRIBUTION_RESOLUTION_MODES, C as ReferralTouchCollection, D as ReferralCollection, E as assertHttpTargetUrl, F as validateAttributionPolicyTerms, G as REFERRAL_STATUSES, H as REFERRAL_AGREEMENT_STATUSES, I as ATTRIBUTION_CONFLICT_BEHAVIORS, J as AttributionExceptionCollection, K as REFERRAL_TOUCH_KINDS, L as ATTRIBUTION_CREDIT_MODES, M as ReferralAgreement, N as AttributionPolicyCollection, O as Referral, P as AttributionPolicy, R as ATTRIBUTION_EXCEPTION_STATUSES, S as generateReferralCode, T as ReferralLink, U as REFERRAL_LINK_STATUSES, V as REFERRAL_AGREEMENT_APPROVAL_MODES, W as REFERRAL_PROGRAM_STATUSES, Y as AttributionException, _ as REFERRAL_CODE_ALPHABET, a as ReferralAgreementExecutionService, b as ReferralClickValidationError, c as ReferrerCollection, d as ReferralTermSnapshot, f as ReferralProgramCollection, g as MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES, h as MAX_CODE_GENERATION_ATTEMPTS, i as REFERRAL_AGREEMENT_SOURCE_KIND, j as ReferralAgreementCollection, k as ReferralClickOperationCollection, l as Referrer, m as DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES, n as REFERRAL_TERMS_SNAPSHOT_KIND, o as AttributionService, p as ReferralProgram, q as REFERRER_STATUSES, r as ReferralCommissionService, s as QualifiedReferralOverrideError, t as ReferralQualificationService, u as ReferralTermSnapshotCollection, v as REFERRAL_CODE_LENGTH, w as ReferralTouch, x as ReferralLinkCollection, y as ReferralClickReplayConflictError, z as ATTRIBUTION_POLICY_STATUSES } from "./chunks/referrals-BRdTkEFt.js";
 export { ATTRIBUTION_CONFLICT_BEHAVIORS, ATTRIBUTION_CREDIT_MODES, ATTRIBUTION_EXCEPTION_STATUSES, ATTRIBUTION_POLICY_STATUSES, ATTRIBUTION_RESOLUTION_MODES, AttributionException, AttributionExceptionCollection, AttributionPolicy, AttributionPolicyCollection, AttributionService, DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES, MAX_CODE_GENERATION_ATTEMPTS, MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES, QualifiedReferralOverrideError, REFERRAL_AGREEMENT_APPROVAL_MODES, REFERRAL_AGREEMENT_SOURCE_KIND, REFERRAL_AGREEMENT_STATUSES, REFERRAL_CODE_ALPHABET, REFERRAL_CODE_LENGTH, REFERRAL_LINK_STATUSES, REFERRAL_PROGRAM_STATUSES, REFERRAL_STATUSES, REFERRAL_TERMS_SNAPSHOT_KIND, REFERRAL_TOUCH_KINDS, REFERRER_STATUSES, Referral, ReferralAgreement, ReferralAgreementCollection, ReferralAgreementExecutionService, ReferralClickOperation, ReferralClickOperationCollection, ReferralClickReplayConflictError, ReferralClickValidationError, ReferralCollection, ReferralCommissionService, ReferralLink, ReferralLinkCollection, ReferralProgram, ReferralProgramCollection, ReferralQualificationService, ReferralTermSnapshot, ReferralTermSnapshotCollection, ReferralTouch, ReferralTouchCollection, Referrer, ReferrerCollection, assertHttpTargetUrl, generateReferralCode, validateAttributionPolicyTerms };

package/dist/smrt-knowledge.json

@@ -3,15 +3,15 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.57.9",
+  "packageVersion": "0.57.11",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "28af5ca67cbfcffb5166fb3350b790f158cac6b035c37ed56b51da3746a38428",
-    "packageJson": "1771e55b4acb9b0af79b8d3df41f56a7d9f49e015e7bff72f9a07039ba45e785",
+    "manifest": "ed4d64dff91b735232ab51a66907f074e338d1b10b8a94fd0ec5a2f705f08ecf",
+    "packageJson": "bee8a154154e9918a3d2bad81b47c8a6c4722d0b775a50fd127bc3a5ce983d10",
     "agents": "3100099d7cef116237e4deb4f83e32d836f3cc26e0f68a7dd55f14de942eda11",
     "moduleDoc:agents/agreements.md": "eb6ff147a0f60ee627d3337e8e9394d06fda955b4a4fff228537a9bd2803f886",
-    "moduleDoc:agents/commissions.md": "b649ef658d41f9c27287281f6d3c9ee06dec2aede89da070a3ebfc7b4c289798",
+    "moduleDoc:agents/commissions.md": "ba06d133f2cbee14ea9a5f18b632f155e3484c4cd721ed5ac993436397198cf8",
     "moduleDoc:agents/crm.md": "b2c01c33e6ac559ba32073a089760d885095969d2ad749c30428c76e6aa2cc71",
     "moduleDoc:agents/referrals.md": "ef48c88e63155e3d08b9003f4643bc66ebb1942f1fb713252dc042ddcaad38e5",
     "moduleDoc:agents/svelte.md": "819f690b91cf93980f6f79e89da8d9629ca6e5c565494e3fd2ca3be7587ad6de"
@@ -4415,6 +4415,13 @@
           "required": false,
           "columnType": "UUID"
         },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "person"
+        },
         {
           "name": "profileId",
           "type": "crossPackageRef",
@@ -4443,6 +4450,13 @@
           "columnType": "TEXT",
           "default": "bank_transfer"
         },
+        {
+          "name": "payoutDestination",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "{}"
+        },
         {
           "name": "payoutThresholdCents",
           "type": "integer",
@@ -4483,20 +4497,33 @@
       ],
       "methods": [
         "getMetadata",
+        "getPayoutDestination",
         "isActive",
+        "isOrganisation",
         "isPending",
         "isSuspended",
-        "setMetadata"
+        "isTreasury",
+        "save",
+        "setMetadata",
+        "setPayoutDestination"
       ],
       "methodSignatures": [
         {
           "name": "getMetadata",
           "returns": "Record<string, unknown>"
         },
+        {
+          "name": "getPayoutDestination",
+          "returns": "PayoutDestination | null"
+        },
         {
           "name": "isActive",
           "returns": "boolean"
         },
+        {
+          "name": "isOrganisation",
+          "returns": "boolean"
+        },
         {
           "name": "isPending",
           "returns": "boolean"
@@ -4505,12 +4532,28 @@
           "name": "isSuspended",
           "returns": "boolean"
         },
+        {
+          "name": "isTreasury",
+          "returns": "boolean"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        },
         {
           "name": "setMetadata",
           "params": [
             "data: Record<string, unknown>"
           ],
           "returns": "void"
+        },
+        {
+          "name": "setPayoutDestination",
+          "params": [
+            "destination: PayoutDestination | null"
+          ],
+          "returns": "void"
         }
       ],
       "tenant": {
@@ -4616,6 +4659,30 @@
           "operation": "setMetadata",
           "objectName": "@happyvertical/smrt-sales:Earner"
         },
+        {
+          "kind": "cli",
+          "name": "earner_isOrganisation",
+          "operation": "isOrganisation",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
+        {
+          "kind": "cli",
+          "name": "earner_isTreasury",
+          "operation": "isTreasury",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
+        {
+          "kind": "cli",
+          "name": "earner_getPayoutDestination",
+          "operation": "getPayoutDestination",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
+        {
+          "kind": "cli",
+          "name": "earner_setPayoutDestination",
+          "operation": "setPayoutDestination",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
         {
           "kind": "mcp",
           "name": "earner_list",
@@ -4643,6 +4710,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-sales:Earner"
         },
+        {
+          "kind": "api",
+          "operation": "getPayoutDestination",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
         {
           "kind": "api",
           "operation": "isActive",
@@ -4650,6 +4724,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-sales:Earner"
         },
+        {
+          "kind": "api",
+          "operation": "isOrganisation",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
         {
           "kind": "api",
           "operation": "isPending",
@@ -4664,12 +4745,33 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-sales:Earner"
         },
+        {
+          "kind": "api",
+          "operation": "isTreasury",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-sales:Earner"
+        },
         {
           "kind": "api",
           "operation": "setMetadata",
           "code": "not-included",
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-sales:Earner"
+        },
+        {
+          "kind": "api",
+          "operation": "setPayoutDestination",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-sales:Earner"
         }
       ],
       "relationshipFeatures": [
@@ -11820,6 +11922,30 @@
       "operation": "setMetadata",
       "objectName": "@happyvertical/smrt-sales:Earner"
     },
+    {
+      "kind": "cli",
+      "name": "earner_isOrganisation",
+      "operation": "isOrganisation",
+      "objectName": "@happyvertical/smrt-sales:Earner"
+    },
+    {
+      "kind": "cli",
+      "name": "earner_isTreasury",
+      "operation": "isTreasury",
+      "objectName": "@happyvertical/smrt-sales:Earner"
+    },
+    {
+      "kind": "cli",
+      "name": "earner_getPayoutDestination",
+      "operation": "getPayoutDestination",
+      "objectName": "@happyvertical/smrt-sales:Earner"
+    },
+    {
+      "kind": "cli",
+      "name": "earner_setPayoutDestination",
+      "operation": "setPayoutDestination",
+      "objectName": "@happyvertical/smrt-sales:Earner"
+    },
     {
       "kind": "mcp",
       "name": "earner_list",
@@ -13486,7 +13612,7 @@
     {
       "path": "agents/commissions.md",
       "module": "commissions",
-      "content": "# smrt-sales/commissions — neutral financial core\n\nPer-module semantics for `@happyvertical/smrt-sales/commissions`. Package orientation, the\ncross-module invariants (currency, tenancy, cross-package refs, roles vs.\nmoney), and the Gotchas that apply before editing anything live in\n[../AGENTS.md](../AGENTS.md) — read that first.\n\n- **Earner**: `profileId`, `status` (`pending|active|suspended`), `payoutMethod` (`bank_transfer|check|paypal|credit|other`), `payoutThresholdCents`, `payoutScheduleKey` (open string: `manual`, `monthly`, …), `currency`, `metadata`.\n- **EarnerSourceAttribution** (#1986): indexed external attribution mapping `(sourceKind, sourceId) → earnerId` with `status` (`active|inactive`) — the queryable replacement for stashing associations in `Earner.metadata`. Natural key `(tenant_id, source_kind, source_id)` (one mapping per key per tenant; a re-`create` upserts/re-points; the adapters' null-aware upsert dedups NULL-tenant keys too, but duplicate global rows minted outside the model layer remain representable). The attribution kind space is consumer-defined and need not match earning-event source kinds. `EarnerAttributionService` is the public API: `registerAttribution` (idempotent; reports `created`/`previousEarnerId`; also the documented metadata-migration backfill primitive — loop earners, register each association, verify, drop the metadata key) and `resolveActiveEarnerBySource`/`resolveActiveEarnersBySources` (single/batched; 2 queries bounded by the REQUESTED ids, never a scan of active earners; fail-closed typed reasons `no_mapping|mapping_inactive|ambiguous_mapping|earner_not_found|earner_not_active` — more than one ACTIVE row for a key refuses rather than guessing). In tenant context mappings resolve within that tenant only; without context, lookups span all rows and cross-tenant duplicates surface as `ambiguous_mapping`.\n- **CommissionPlan**: versioned calculation terms. Natural key `(tenant_id, plan_key, version)` (per-tenant keys; the adapters' null-aware upsert dedups NULL-tenant keys through the model layer, though duplicate global rows minted via raw SQL remain representable); `status` (`draft|active|superseded|retired`); `effectiveFrom`. Components are a JSON-string array (`getComponents()`): each component has `key`, `trigger` (earning-event kind or `*`), `basis` (`fixed|gross|net|margin|custom`), `rate` or `fixedAmountCents`, `recurrence` (`one_time` or `recurring` with optional `maxOccurrences`/`windowMonths`). **Immutable once active** — amendments create a new row with `version + 1`; prior versions are never rewritten. `latestActiveByKey(key, at?)` resolves the highest active version **already in effect at `at`** — a future-dated amendment can be activated ahead of time without governing earlier qualifications (same rule on `AttributionPolicyCollection`).\n- **EarningEvent**: immutable commercial-event evidence (`conversion`, `agreement_execution`, `invoice_payment`, `collected_revenue`, `recognized_margin`, or any extensible kind). Carries `sourceKind`/`sourceId` (generic earning source), `grossAmountCents`/`netAmountCents`/`marginCents`, `currency`, `occurredAt`, and a `dedupeKey` natural key for idempotent ingestion. No update/delete surface, plus a save-time immutability guard: hydrated edits, blind id overwrites, and fresh creates onto an existing dedupe key all throw (the upsert would rotate the row id and orphan referencing Commissions) — idempotent ingestion goes through `getOrCreateByDedupeKey()`.\n- **Commission**: one earning record per earner per plan component per event occurrence. Integer-cents amounts (`baseAmountCents`, `amountCents`), decimal `rate`, `basis`, snapshot references (`planKey`/`planVersion`, generic `termsSnapshotKind`/`termsSnapshotId`), a JSON `calculationTrace` sufficient to reproduce the amount, split support (`splitGroupId`, `shareFraction`), and a `dedupeKey` for idempotent creation. Lifecycle `pending → earned → approved → payable → paid`, enforced by a save-time transition guard with an authoritative prior-status re-read (commerce pattern).\n- **CommissionAdjustment**: append-only corrections (`refund|credit|chargeback|dispute|correction`), signed `amountCents`, required `reason`, immutable once created. `CommissionAdjustmentService.createAdjustment()` is the tenant-required idempotent creation door: callers provide a stable operation UUID; the database creates exactly one row, exact retries return it, and changed tenant/commission/earner/kind/cents/currency/reason/operator/metadata fail with a typed replay conflict. Parent Commission plus denormalized tenant/Earner/currency and operator UUID are validated before insert. The financial row deliberately exposes no operation field. A private, required-tenant `CommissionAdjustmentOperation` table uses the globally unique operation UUID as its primary id, maps it to the adjustment UUID, and is inserted in the same transaction as the adjustment. Claims tolerate either primary-key or tenant/slug/context uniqueness arbitration without aborting the transaction; only the tenant-scoped operation UUID lookup and immutable intent comparison authorize a replay. Existing adjustment schemas and legacy direct creates remain unchanged. Earned/paid Commissions are never rewritten — adjustments append to them.\n- **Payable balance**: computed, not stored — `CommissionBalanceService` sums payable Commissions plus unsettled Adjustments per Earner/currency.\n- **CommissionPayout**: settlement batch per Earner. `pending → approved → processing → completed | failed` (`resetFromFailed()` is the only exit from failed), plus the terminal operator decline `rejected` reachable from pending/approved (#1987 — reject through `transitionPayoutForSource`, which also RELEASES the batch's membership so the rows settle through a future batch; `reject()` on the model mutates status only). Settles rows via the collections' **conditional `claimForPayout`** (model-layer get/save/re-read — tenancy- and dialect-safe; a row owned by another batch is never re-claimed) and stores totals recomputed from the VERIFIED claimed membership; idempotent via `idempotencyKey` natural key (default `${earnerId}:${currency}:${YYYY-MM-DD}`) — a clean replay touches nothing, while a pending payout whose totals disagree with its stamped rows (interrupted claim pass) is repaired on replay (the claim pass re-checks the payout is still pending first). Each batch/repair pass also derives the payout's **single-source stamp** (`sourceKind`/`sourceId`, indexed): set when every claimed commission — and every claimed adjustment through its parent commission — shares exactly one non-empty source; empty for mixed/unknown/empty membership. `completePayout` flips member commissions to `paid` BEFORE the terminal transition, so a mid-loop failure stays retryable. Enforces `totalAmountCents = commissionTotalCents + adjustmentTotalCents` at save; retains `paymentReference`/`providerRef`; optional `invoiceId` cross-package string ref to a commerce Invoice. Generated surface is read-only on ALL doors (api/mcp/cli `list`/`get`) — writes go through `CommissionPayoutService`. `createPayoutBatch` settles the whole earner+currency by default, or a **scoped** subset: pass `sourceKind`+`sourceId` to settle just one earning source (e.g. one ad network), or `commissionIds` for an explicit set (each validated payable+unsettled+earner+currency; requires its own `idempotencyKey`) — adjustments are narrowed to the same scope, and the default idempotency key folds the source in. Scoping is how concurrent per-source batches settle safely: batches scoped to different sources (or disjoint `commissionIds`) gather **disjoint** row sets and never contend. The collection layer has no cross-row transaction, so OVERLAPPING concurrent scopes (a source batch + the earner-wide batch, intersecting id sets, or a batch replay racing a lifecycle transition of the same payout) must be serialized by the caller — `claimForPayout` still won't double-own a row, but a shared commission and its adjustment could split across the two batches.\n- **Source-scoped payout history** (#1985): `CommissionPayoutService.getSourcePayoutHistory({ sourceKind, sourceId, limit?, offset? })` — one page of the payouts belonging to ONE earning source, newest first (`created_at DESC, id DESC`), offset contract (`nextOffset` advances by the scanned count; `null` when exhausted). Candidates come from the indexed stamp, so work is bounded by page size (a sparse source never scans the global history); each page is re-verified against actual membership in three batched queries (no per-payout N+1) — every member commission and every adjustment's parent must carry exactly the requested source and agree on earner/currency/tenant; unprovable rows (mixed-source, missing parents, memberless artifacts, released/rejected batches) are excluded fail-closed and reported in `excluded` with reasons. Adjustment-only payouts prove ownership through parent commissions and list normally. Payouts minted before the stamp existed are invisible until backfilled with `restampPayoutSource(payoutId)` (idempotent, any status).\n- **Source-authorized lifecycle transitions** (#1987): `CommissionPayoutService.transitionPayoutForSource({ payoutId, sourceKind, sourceId, action, expectedStatus?, paymentReference?, reason? })` — atomic alternative to load-verify-transition. Actions `approve | mark_processing | complete | fail | reject`. Everything runs on one transaction database: the payout row is locked (PostgreSQL `SELECT … FOR UPDATE`, replica-safe; single-connection engines serialize transitions per database in-process), membership is re-verified under the lock (every commission and every adjustment through its parent must carry exactly the requested source and matching earner/currency/tenant — else typed fail-closed refusals with no payout/member data), and only authorized calls receive status-derived `already_applied` or `status_conflict` outcomes. Totals are then recomputed under the lock (drift refuses the money-forward actions with `totals_drift`; repair = `createPayoutBatch` replay while pending; `fail`/`reject` proceed despite drift — reject IS the remedy), and the transition plus member writes commit or roll back together (`complete` flips members to paid in the same transaction; `reject` releases membership then declines). Outcomes: `transitioned`, `already_applied` (idempotent echo — terminal completion NEVER rewrites `paymentReference`/`providerRef`/`paidAt`), or `refused` with `{ reason, detail }`. Concurrent duplicate calls for actions that retain membership resolve as one `transitioned` + `already_applied` echoes; `reject` releases its membership evidence, so serialized replays fail `membership_empty` rather than expose rejected state. `expectedStatus` adds optimistic-concurrency strictness after authorization. Memberless batch artifacts cannot pass the source-authorized door (`membership_empty`) — they stay operator-level.\n"
+      "content": "# smrt-sales/commissions — neutral financial core\n\nPer-module semantics for `@happyvertical/smrt-sales/commissions`. Package orientation, the\ncross-module invariants (currency, tenancy, cross-package refs, roles vs.\nmoney), and the Gotchas that apply before editing anything live in\n[../AGENTS.md](../AGENTS.md) — read that first.\n\n- **Earner**: `kind` (`person|organisation|treasury`, default `person`; organisation and treasury earners need no person Profile, so `profileId` stays empty unless the host links an organisation Profile), `profileId`, `status` (`pending|active|suspended`), `payoutMethod` (`bank_transfer|check|paypal|credit|other|stripe_connect|crypto`), `payoutDestination` (typed JSON descriptor via `getPayoutDestination()`/`setPayoutDestination()`: Stripe Connect `connectedAccountId` (`acct_…`) or crypto `network`/`asset`/`address`/`memo?`; unknown fields are refused so secrets cannot ride along; its `method` must equal `payoutMethod`, and an `active` Stripe Connect/crypto earner must have one — enforced at save; `createPayoutBatch` refuses to create a NEW Stripe Connect/crypto batch, including a `payoutMethod` override, unless the earner's destination has that method; an existing idempotency key still replays/repairs its batch after the preference changes), `payoutThresholdCents`, `payoutScheduleKey` (open string: `manual`, `monthly`, …), `currency`, `metadata`. Descriptors only: nothing in this package calls a payment provider. Map an organisation earner to the host's own organisation id through `EarnerSourceAttribution`.\n- **EarnerSourceAttribution** (#1986): indexed external attribution mapping `(sourceKind, sourceId) → earnerId` with `status` (`active|inactive`) — the queryable replacement for stashing associations in `Earner.metadata`. Natural key `(tenant_id, source_kind, source_id)` (one mapping per key per tenant; a re-`create` upserts/re-points; the adapters' null-aware upsert dedups NULL-tenant keys too, but duplicate global rows minted outside the model layer remain representable). The attribution kind space is consumer-defined and need not match earning-event source kinds. `EarnerAttributionService` is the public API: `registerAttribution` (idempotent; reports `created`/`previousEarnerId`; also the documented metadata-migration backfill primitive — loop earners, register each association, verify, drop the metadata key) and `resolveActiveEarnerBySource`/`resolveActiveEarnersBySources` (single/batched; 2 queries bounded by the REQUESTED ids, never a scan of active earners; fail-closed typed reasons `no_mapping|mapping_inactive|ambiguous_mapping|earner_not_found|earner_not_active` — more than one ACTIVE row for a key refuses rather than guessing). In tenant context mappings resolve within that tenant only; without context, lookups span all rows and cross-tenant duplicates surface as `ambiguous_mapping`.\n- **CommissionPlan**: versioned calculation terms. Natural key `(tenant_id, plan_key, version)` (per-tenant keys; the adapters' null-aware upsert dedups NULL-tenant keys through the model layer, though duplicate global rows minted via raw SQL remain representable); `status` (`draft|active|superseded|retired`); `effectiveFrom`. Components are a JSON-string array (`getComponents()`): each component has `key`, `trigger` (earning-event kind or `*`), `basis` (`fixed|gross|net|margin|custom`), `rate` or `fixedAmountCents`, `recurrence` (`one_time` or `recurring` with optional `maxOccurrences`/`windowMonths`). **Immutable once active** — amendments create a new row with `version + 1`; prior versions are never rewritten. `latestActiveByKey(key, at?)` resolves the highest active version **already in effect at `at`** — a future-dated amendment can be activated ahead of time without governing earlier qualifications (same rule on `AttributionPolicyCollection`).\n- **Waterfall pool steps** (#3834): a v2 step with `pool: { metric?, residual?, zeroWeight? }` splits its amount across the members of the pool its `recipient` descriptor resolves to (through the normal recipient registry). Membership comes from an injected `WaterfallPoolMembershipResolver`, weights from an injected `MetricProvider` (omitted `metric` ⇒ equal weights, no provider call). `calculateWaterfall` stays synchronous and never calls providers: `prepareWaterfallPools()` (async) resolves pools at the authoritative event and the result is passed as `pools`; `calculateWaterfallWithPools()` does both. Weights must be non-negative safe integers (hosts scale fractional metrics); members are canonicalized to `(kind, id)` order and duplicates, non-member metric rows, and repeated rows are refused; members the provider omits weigh zero. Allocation is exact BigInt `floor(amount × weight ÷ total)`; the residual goes to the remainder sink (default) or, with `residual: 'largest_remainder'`, one unit at a time by largest fractional remainder, then larger weight, then `kind`, then `id` (UTF-16 code-unit order). An empty pool, or an all-zero pool under the default `zeroWeight: 'remainder_sink'`, sends the whole step to the sink; `zeroWeight: 'equal'` splits equally instead. The trace freezes `frozenInputs.poolsByStep` (pool identity, metric, ISO period, members, weights) so replay never re-reads metrics; frozen and prepared snapshots must match their frozen recipient and the step's declared `metric` (`null` for equal weights), and a prepared snapshot (or `null` unresolved marker) must equal what the step's descriptor resolves to at calculation, so pools prepared for another plan are refused. Replay trusts the evidence it is given — like frozen `recipientByStep`, an internally consistent edit to stored evidence is undetectable without keyed integrity, so hosts store it immutably. Pool-free plans emit no `poolsByStep` key or step `pool` field, so their traces are unchanged. A pool step cannot be the application-fee offset recipient. Each member trace carries `shareFraction` for hosts that persist member allocations as Commissions under one `splitGroupId` (for example `${earningEventId}:${stepKey}`).\n- **EarningEvent**: immutable commercial-event evidence (`conversion`, `agreement_execution`, `invoice_payment`, `collected_revenue`, `recognized_margin`, or any extensible kind). Carries `sourceKind`/`sourceId` (generic earning source), `grossAmountCents`/`netAmountCents`/`marginCents`, `currency`, `occurredAt`, and a `dedupeKey` natural key for idempotent ingestion. No update/delete surface, plus a save-time immutability guard: hydrated edits, blind id overwrites, and fresh creates onto an existing dedupe key all throw (the upsert would rotate the row id and orphan referencing Commissions) — idempotent ingestion goes through `getOrCreateByDedupeKey()`.\n- **Commission**: one earning record per earner per plan component per event occurrence. Integer-cents amounts (`baseAmountCents`, `amountCents`), decimal `rate`, `basis`, snapshot references (`planKey`/`planVersion`, generic `termsSnapshotKind`/`termsSnapshotId`), a JSON `calculationTrace` sufficient to reproduce the amount, split support (`splitGroupId`, `shareFraction`), and a `dedupeKey` for idempotent creation. Lifecycle `pending → earned → approved → payable → paid`, enforced by a save-time transition guard with an authoritative prior-status re-read (commerce pattern).\n- **CommissionAdjustment**: append-only corrections (`refund|credit|chargeback|dispute|correction`), signed `amountCents`, required `reason`, immutable once created. `CommissionAdjustmentService.createAdjustment()` is the tenant-required idempotent creation door: callers provide a stable operation UUID; the database creates exactly one row, exact retries return it, and changed tenant/commission/earner/kind/cents/currency/reason/operator/metadata fail with a typed replay conflict. Parent Commission plus denormalized tenant/Earner/currency and operator UUID are validated before insert. The financial row deliberately exposes no operation field. A private, required-tenant `CommissionAdjustmentOperation` table uses the globally unique operation UUID as its primary id, maps it to the adjustment UUID, and is inserted in the same transaction as the adjustment. Claims tolerate either primary-key or tenant/slug/context uniqueness arbitration without aborting the transaction; only the tenant-scoped operation UUID lookup and immutable intent comparison authorize a replay. Existing adjustment schemas and legacy direct creates remain unchanged. Earned/paid Commissions are never rewritten — adjustments append to them.\n- **Payable balance**: computed, not stored — `CommissionBalanceService` sums payable Commissions plus unsettled Adjustments per Earner/currency.\n- **CommissionPayout**: settlement batch per Earner. `pending → approved → processing → completed | failed` (`resetFromFailed()` is the only exit from failed), plus the terminal operator decline `rejected` reachable from pending/approved (#1987 — reject through `transitionPayoutForSource`, which also RELEASES the batch's membership so the rows settle through a future batch; `reject()` on the model mutates status only). Settles rows via the collections' **conditional `claimForPayout`** (model-layer get/save/re-read — tenancy- and dialect-safe; a row owned by another batch is never re-claimed) and stores totals recomputed from the VERIFIED claimed membership; idempotent via `idempotencyKey` natural key (default `${earnerId}:${currency}:${YYYY-MM-DD}`) — a clean replay touches nothing, while a pending payout whose totals disagree with its stamped rows (interrupted claim pass) is repaired on replay (the claim pass re-checks the payout is still pending first). Each batch/repair pass also derives the payout's **single-source stamp** (`sourceKind`/`sourceId`, indexed): set when every claimed commission — and every claimed adjustment through its parent commission — shares exactly one non-empty source; empty for mixed/unknown/empty membership. `completePayout` flips member commissions to `paid` BEFORE the terminal transition, so a mid-loop failure stays retryable. Enforces `totalAmountCents = commissionTotalCents + adjustmentTotalCents` at save; retains `paymentReference`/`providerRef`; optional `invoiceId` cross-package string ref to a commerce Invoice. Generated surface is read-only on ALL doors (api/mcp/cli `list`/`get`) — writes go through `CommissionPayoutService`. `createPayoutBatch` settles the whole earner+currency by default, or a **scoped** subset: pass `sourceKind`+`sourceId` to settle just one earning source (e.g. one ad network), or `commissionIds` for an explicit set (each validated payable+unsettled+earner+currency; requires its own `idempotencyKey`) — adjustments are narrowed to the same scope, and the default idempotency key folds the source in. Scoping is how concurrent per-source batches settle safely: batches scoped to different sources (or disjoint `commissionIds`) gather **disjoint** row sets and never contend. The collection layer has no cross-row transaction, so OVERLAPPING concurrent scopes (a source batch + the earner-wide batch, intersecting id sets, or a batch replay racing a lifecycle transition of the same payout) must be serialized by the caller — `claimForPayout` still won't double-own a row, but a shared commission and its adjustment could split across the two batches.\n- **Source-scoped payout history** (#1985): `CommissionPayoutService.getSourcePayoutHistory({ sourceKind, sourceId, limit?, offset? })` — one page of the payouts belonging to ONE earning source, newest first (`created_at DESC, id DESC`), offset contract (`nextOffset` advances by the scanned count; `null` when exhausted). Candidates come from the indexed stamp, so work is bounded by page size (a sparse source never scans the global history); each page is re-verified against actual membership in three batched queries (no per-payout N+1) — every member commission and every adjustment's parent must carry exactly the requested source and agree on earner/currency/tenant; unprovable rows (mixed-source, missing parents, memberless artifacts, released/rejected batches) are excluded fail-closed and reported in `excluded` with reasons. Adjustment-only payouts prove ownership through parent commissions and list normally. Payouts minted before the stamp existed are invisible until backfilled with `restampPayoutSource(payoutId)` (idempotent, any status).\n- **Source-authorized lifecycle transitions** (#1987): `CommissionPayoutService.transitionPayoutForSource({ payoutId, sourceKind, sourceId, action, expectedStatus?, paymentReference?, reason? })` — atomic alternative to load-verify-transition. Actions `approve | mark_processing | complete | fail | reject`. Everything runs on one transaction database: the payout row is locked (PostgreSQL `SELECT … FOR UPDATE`, replica-safe; single-connection engines serialize transitions per database in-process), membership is re-verified under the lock (every commission and every adjustment through its parent must carry exactly the requested source and matching earner/currency/tenant — else typed fail-closed refusals with no payout/member data), and only authorized calls receive status-derived `already_applied` or `status_conflict` outcomes. Totals are then recomputed under the lock (drift refuses the money-forward actions with `totals_drift`; repair = `createPayoutBatch` replay while pending; `fail`/`reject` proceed despite drift — reject IS the remedy), and the transition plus member writes commit or roll back together (`complete` flips members to paid in the same transaction; `reject` releases membership then declines). Outcomes: `transitioned`, `already_applied` (idempotent echo — terminal completion NEVER rewrites `paymentReference`/`providerRef`/`paidAt`), or `refused` with `{ reason, detail }`. Concurrent duplicate calls for actions that retain membership resolve as one `transitioned` + `already_applied` echoes; `reject` releases its membership evidence, so serialized replays fail `membership_empty` rather than expose rejected state. `expectedStatus` adds optimistic-concurrency strictness after authorization. Memberless batch artifacts cannot pass the source-authorized door (`membership_empty`) — they stay operator-level.\n"
     },
     {
       "path": "agents/crm.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-sales",
-  "version": "0.57.9",
+  "version": "0.57.11",
   "smrtJsdoc": "strict",
   "description": "Modular sales for the SMRT framework: agreement execution, CRM, referral intake, neutral commissions, and reusable Svelte surfaces",
   "type": "module",
@@ -42,18 +42,18 @@
     "./manifest.json": "./dist/manifest.json"
   },
   "dependencies": {
-    "@happyvertical/signatures": "^0.105.2",
-    "@happyvertical/smrt-assets": "0.57.9",
-    "@happyvertical/smrt-core": "0.57.9",
-    "@happyvertical/smrt-tenancy": "0.57.9",
-    "@happyvertical/smrt-ui": "0.57.9",
-    "@happyvertical/sql": "^0.105.2"
+    "@happyvertical/signatures": "^0.105.5",
+    "@happyvertical/smrt-assets": "0.57.11",
+    "@happyvertical/smrt-core": "0.57.11",
+    "@happyvertical/smrt-tenancy": "0.57.11",
+    "@happyvertical/smrt-ui": "0.57.11",
+    "@happyvertical/sql": "^0.105.5"
   },
   "peerDependencies": {
     "svelte": "^5.57.0"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.9",
+    "@happyvertical/smrt-vitest": "0.57.11",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",