@happyvertical/smrt-sales 0.40.0 → 0.40.2

package/dist/smrt-knowledge.json

@@ -1,17 +1,18 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-15T06:00:05.222Z",
+  "generatedAt": "2026-07-15T07:44:10.429Z",
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.40.0",
+  "packageVersion": "0.40.2",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "d064ad9d003895cb4cba97babf183f8293e7299d531aed09bdac959011808d80",
-    "packageJson": "a5de39608fc5e0b58b181cd794117d1fc58b7cb2e859fdd2292f5ec8ce6f22e7",
-    "agents": "c5fc29e1fc3076ba7ed4207638cde96876f220c4661b831ccfa3e03b5b291a5c"
+    "manifest": "624ac5707cc54575942ba85317caa3be35e1c1092911220059752c36614209c5",
+    "packageJson": "72e8823437b4bad3c5b474063cd3fdf9f7f5d6d8a3df14bc42555c4157ee14bf",
+    "agents": "c9058f7518134426831d1e292e6bba9e661e5f5be1d72d9bd33df2a4148d9489"
   },
   "exports": [
     ".",
+    "./agreements",
     "./commissions",
     "./crm",
     "./manifest",
@@ -20,6 +21,8 @@
     "./svelte"
   ],
   "dependencies": {
+    "@happyvertical/signatures": "catalog:",
+    "@happyvertical/smrt-assets": "workspace:*",
     "@happyvertical/smrt-core": "workspace:*",
     "@happyvertical/smrt-tenancy": "workspace:*",
     "@happyvertical/smrt-ui": "workspace:*",
@@ -35,6 +38,7 @@
     "vitest": "^4.1.9"
   },
   "smrtDependencies": [
+    "@happyvertical/smrt-assets",
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-ui",
@@ -46,6 +50,726 @@
   "tags": [],
   "risks": [],
   "objects": [
+    {
+      "name": "AgreementExecutionCollection",
+      "qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionCollection",
+      "collection": "agreementexecutions",
+      "tableName": "agreement_execution_collections",
+      "packageName": "@happyvertical/smrt-sales",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "bindEvidenceArtifact",
+        "bindProviderRequest",
+        "claimCreateAttempt",
+        "compareAndSetLifecycle",
+        "completeCreateAttempt",
+        "failCreateAttempt",
+        "findByIdempotencyKey",
+        "findByProviderRequest",
+        "findBySource",
+        "incrementAttemptCount",
+        "updateLastError"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "AgreementExecutionEventCollection",
+      "qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionEventCollection",
+      "collection": "agreementexecutionevents",
+      "tableName": "agreement_execution_event_collections",
+      "packageName": "@happyvertical/smrt-sales",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByDedupeKey",
+        "findByExecution",
+        "findProviderEventsByExecution",
+        "recordVerified"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ExecutedAgreementCollection",
+      "qualifiedName": "@happyvertical/smrt-sales:ExecutedAgreementCollection",
+      "collection": "executedagreements",
+      "tableName": "executed_agreement_collections",
+      "packageName": "@happyvertical/smrt-sales",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "createImmutable",
+        "effectiveForSource",
+        "findByExecution",
+        "findVersionsBySource"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "AgreementExecution",
+      "qualifiedName": "@happyvertical/smrt-sales:AgreementExecution",
+      "collection": "agreementexecutions",
+      "tableName": "agreement_executions",
+      "packageName": "@happyvertical/smrt-sales",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "provider",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "providerAccountRef",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "credentialRef",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "idempotencyKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceKind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceVersion",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "sourceAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceSizeBytes",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "requestIntentSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "title",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signerIntent",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "providerRequestId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "providerRequestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "cancellationReason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "lastProviderEventAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "lastReconciledAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "completedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "effectiveFrom",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "effectiveTo",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "supersedesExecutedAgreementId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signedDocumentAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "signedDocumentSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signedDocumentSizeBytes",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "signedDocumentMediaType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signedDocumentFilename",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auditTrailAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "auditTrailSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auditTrailSizeBytes",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "auditTrailMediaType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auditTrailFilename",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "attemptCount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "createLeaseId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "createLeaseExpiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "lastError",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "sourceAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "signedDocumentAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "auditTrailAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getSignerIntent",
+        "initialize",
+        "save"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "AgreementExecutionEvent",
+      "qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionEvent",
+      "collection": "agreementexecutionevents",
+      "tableName": "agreement_execution_events",
+      "packageName": "@happyvertical/smrt-sales",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "executionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgreementExecution",
+          "columnType": "UUID"
+        },
+        {
+          "name": "provider",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "providerEventId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "eventOrigin",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "operationId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "dedupeKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "orderingKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "eventType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "occurredAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "receivedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "payloadSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signerEvidence",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "payload",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "executionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgreementExecution",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "initialize",
+        "save"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ExecutedAgreement",
+      "qualifiedName": "@happyvertical/smrt-sales:ExecutedAgreement",
+      "collection": "executedagreements",
+      "tableName": "executed_agreements",
+      "packageName": "@happyvertical/smrt-sales",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "executionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgreementExecution",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceKind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceVersion",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "sourceAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceSizeBytes",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "signedDocumentAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "signedDocumentSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signedDocumentSizeBytes",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "signedDocumentMediaType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signedDocumentFilename",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auditTrailAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "auditTrailSha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auditTrailSizeBytes",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "auditTrailMediaType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auditTrailFilename",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signerEvidence",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "acceptedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "effectiveFrom",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "effectiveTo",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "supersedesExecutedAgreementId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "ExecutedAgreement",
+          "columnType": "UUID"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "executionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgreementExecution",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "signedDocumentAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "auditTrailAssetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "supersedesExecutedAgreementId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "ExecutedAgreement",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "initialize",
+        "isEffectiveAt",
+        "save"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "executedagreements.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
+          "path": "/executedagreements",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "executedagreements.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
+          "path": "/executedagreements/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "mcp",
+          "name": "executedagreement_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
+        },
+        {
+          "kind": "mcp",
+          "name": "executedagreement_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "CommissionAdjustmentCollection",
       "qualifiedName": "@happyvertical/smrt-sales:CommissionAdjustmentCollection",
@@ -3519,29 +4243,18 @@
           "columnType": "TEXT"
         },
         {
-          "name": "contractRef",
-          "type": "crossPackageRef",
+          "name": "executionId",
+          "type": "foreignKey",
           "required": false,
-          "related": "@happyvertical/smrt-commerce:Contract",
+          "related": "AgreementExecution",
           "columnType": "UUID"
         },
         {
-          "name": "executedArtifactUrl",
-          "type": "text",
-          "required": false,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "executedArtifactHash",
-          "type": "text",
-          "required": false,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "acceptanceEvidence",
-          "type": "text",
+          "name": "executedAgreementId",
+          "type": "foreignKey",
           "required": false,
-          "columnType": "TEXT"
+          "related": "ExecutedAgreement",
+          "columnType": "UUID"
         },
         {
           "name": "metadata",
@@ -3566,23 +4279,30 @@
           "columnType": "UUID"
         },
         {
-          "name": "contractRef",
-          "type": "crossPackageRef",
+          "name": "executionId",
+          "type": "foreignKey",
           "required": false,
-          "related": "@happyvertical/smrt-commerce:Contract",
+          "related": "AgreementExecution",
+          "columnType": "UUID"
+        },
+        {
+          "name": "executedAgreementId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "ExecutedAgreement",
           "columnType": "UUID"
         }
       ],
       "methods": [
         "activate",
-        "getAcceptanceEvidence",
+        "bindExecutedAgreement",
+        "bindExecution",
         "getMetadata",
         "initialize",
         "isActive",
         "isDraft",
         "isEffectiveAt",
         "save",
-        "setAcceptanceEvidence",
         "setMetadata",
         "supersede",
         "terminate"
@@ -3656,7 +4376,6 @@
         }
       ],
       "relationshipFeatures": [
-        "crossPackageRef",
         "foreignKey",
         "uuidColumns"
       ],
@@ -4433,6 +5152,34 @@
     }
   ],
   "surfaces": [
+    {
+      "kind": "api",
+      "name": "executedagreements.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
+      "path": "/executedagreements",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "executedagreements.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
+      "path": "/executedagreements/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "mcp",
+      "name": "executedagreement_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
+    },
+    {
+      "kind": "mcp",
+      "name": "executedagreement_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
+    },
     {
       "kind": "api",
       "name": "commissions.list",
@@ -5746,12 +6493,12 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 30,
-    "crossPackageRefFields": 9,
+    "foreignKeyFields": 35,
+    "crossPackageRefFields": 14,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 108
+    "uuidColumns": 127
   },
-  "agentDoc": "# @happyvertical/smrt-sales\n\nModular sales: CRM (Leads, Opportunities, Pipelines), referral intake with versioned attribution policies, a neutral commissions financial core with immutable term snapshots, and reusable Svelte surfaces. One installable package, four modules with distinct subpath exports:\n\n- `@happyvertical/smrt-sales/crm`\n- `@happyvertical/smrt-sales/referrals`\n- `@happyvertical/smrt-sales/commissions`\n- `@happyvertical/smrt-sales/svelte`\n\nThe root export re-exports every TS module. Internal module dependency order is `crm → commissions` and `referrals → commissions` (by string references only); `commissions` never imports from `crm`/`referrals` and never assumes advertising, Referral, Lead, or Opportunity semantics.\n\n## Validation\n\nRun `pnpm --filter @happyvertical/smrt-sales test` and `pnpm --filter @happyvertical/smrt-sales typecheck` for package changes. PostgreSQL-sensitive changes must also run `pnpm --filter @happyvertical/smrt-sales test:postgres`; the command uses the repository's disposable PostgreSQL harness and is registered in the PostgreSQL CI shard.\n\n## Roles vs. money\n\nReferrers and Sales Representatives are **distinct roles** and stay that way. Both connect to money through one neutral financial account:\n\n- **Earner** (commissions): payout identity — method, threshold, currency, status. Referenced by every Commission and CommissionPayout.\n- **SalesRepresentative** (crm) and **Referrer** (referrals): role models, each holding `profileId` (cross-package string ref to smrt-profiles) and `earnerId`.\n\n## Modules\n\n### commissions — neutral financial core\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. 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\n### crm\n\n- **SalesRepresentative**: role model (`profileId`, `earnerId`, `status`).\n- **Lead**: identified prospect with owner assignment, generic acquisition source (`sourceKind`/`sourceId`), preserved `acquisitionContext` JSON, and audited merge (`mergedIntoId`; merges preserve activity + acquisition history on both sides).\n- **PipelineDefinition / PipelineStage**: configurable ordered stages with default `new → qualified → discovery → proposal → negotiation → closed_won | closed_lost` (seeded via `ensureDefaultPipeline()`); stages carry `probability` and `isWon`/`isLost` terminal flags.\n- **Opportunity**: qualified engagement — owner, pipeline + stage, `expectedValueCents`, `probability`, `expectedCloseAt`, outcome. Stage movement validated against the pipeline; terminal stages set `won|lost` status.\n- **SalesActivity**: activity/next-action trail for Leads and Opportunities (`subjectKind`/`subjectId`), also the audit trail for assignment, qualification, merges, and stage movement.\n- **OpportunityConversion**: idempotent conversion links (`targetKind`/`targetId` — client, project, contract, subscription, …) with a composite natural key. CRM never creates downstream records itself and never mutates referral or commission state.\n\n### referrals\n\n- **Referrer**: role model (`profileId`, `earnerId`, `status`).\n- **ReferralProgram**: program defaults — default commission plan key, default attribution policy key, eligibility defaults.\n- **AttributionPolicy**: versioned `(tenant_id, policy_key, version)` policy (per-tenant keys) — attribution `windowDays`, credit mode (`first_touch|last_touch|assigned|split`), split shares, self-referral/existing-client eligibility, eligible services/campaigns/regions, conflict behavior. Immutable once active; amendments bump `version`.\n- **ReferralLink**: shareable link/code per Referrer+Program. Codes are crypto-random, uniqueness-checked, with click counting.\n- **ReferralTouch**: immutable attribution evidence (`click|code_entry|manual_assignment|partner_entry`) with subject hints and evidence JSON.\n- **Referral**: the introduction — generic qualifying target (`targetKind`/`targetId`: lead, opportunity, client, project, subscription, …), resolved policy version, credit fraction (splits create sibling Referrals sharing `splitGroupId`), lifecycle `pending → attributed → qualified | disqualified | expired | under_review`.\n- **AttributionException**: conflict review queue. Conclusive policy resolves automatically; ambiguity creates an exception; overrides require a `resolutionReason` and are audited.\n- **ReferralAgreement**: versioned per-Referrer terms binding — pins `commissionPlanKey`/`planVersion`, effective dating, optional cross-package string refs to a commerce Contract and executed-artifact evidence (e-signature execution lives downstream).\n- **ReferralTermSnapshot**: immutable at qualification — freezes agreement/plan/policy version refs plus the calculation inputs needed to reproduce every later earning.\n- **Services**: `AttributionService` (resolve touches → Referral(s) or exception; typed refusals `existing_client_ineligible | no_active_policy | no_eligible_touches`; `override()` requires a reason, audits via a resolved AttributionException, pins the displaced credit's policy version, and throws `QualifiedReferralOverrideError` on qualified referrals), `ReferralQualificationService` (eligibility + frozen snapshot + transition; `requalify()` is the explicit apply-amendment path), `ReferralCommissionService` (bridge: qualified Referral + EarningEvent → Commissions through the snapshot with `termsSnapshotKind = REFERRAL_TERMS_SNAPSHOT_KIND`; occurrence limits counted per `(termsSnapshotId, componentKey)`; fully idempotent on replay).\n\n### svelte\n\nProps-driven presentational components (no data fetching, no model-class imports, Provider-free smrt-ui primitives, `--smrt-*` tokens only): CRM — `SalesDashboard`, `LeadList`, `OpportunityBoard`, `OpportunityDetail`; referrer portal — `ReferralLinkManager`, `ReferralStatusList`, `ReferrerEarningsSummary`, `CommissionBreakdown` (trace-explained amounts), `PayoutHistoryList`, `ExecutedAgreementsList`; operator — `AttributionConflictQueue` (award editor + required resolution reason), `PayoutBatchReview`, `CommissionExpenseSummary` (explicitly distinct from client invoices). Monetary props stay integer cents; `format.ts` converts at render. View-model prop types are exported interfaces (never inline intersected generics in `$props()`); pure helpers (dashboard math, award validation mirroring the service, payout action gating) are unit-tested while components are svelte-check-gated.\n\n## Currency\n\n**All monetary fields are integer cents** with `*Cents` suffixes; rates are decimal (`0`–`1`). Rounding happens once per calculation step via `roundCents()` (half-away-from-zero) and every Commission stores its `calculationTrace` so amounts are reproducible. Convert at display/commerce boundaries with `centsToAmount()`/`amountToCents()`.\n\n## Tenancy\n\nEvery model is `@TenantScoped({ mode: 'optional' })` with `@tenantId({ nullable: true })`. This deliberately departs from legacy smrt-affiliates (which was cross-tenant by design for ad networks): sales programs, earners, and payouts are tenant-owned; `tenantId: null` remains available for global/operator-level rows.\n\n## Cross-package references (plain strings)\n\n`profileId` → smrt-profiles Profile; `invoiceId` (CommissionPayout) → smrt-commerce Invoice; `contractRef` (ReferralAgreement) → smrt-commerce Contract. No static imports of sibling domain packages.\n\n## smrt-affiliates migration\n\n`@happyvertical/smrt-affiliates` is now a deprecated compatibility package that re-exports this package's commissions core under the legacy names (`Partner` → `Earner`, `Payout` → `CommissionPayout`, `Commission`, collections, enums) with `@deprecated` guidance and **no duplicate persistence model**. The data/API mapping lives in `packages/affiliates/MIGRATION.md`.\n\n## Gotchas\n\n- **Cents vs. rates**: `*Cents` fields are INTEGER (`= 0` defaults); `rate`/`probability`/`shareFraction` are DECIMAL (`= 0.0` defaults). Don't mix the two conventions on one field.\n- **Versioned terms are rows, not edits**: CommissionPlan / AttributionPolicy / ReferralAgreement amendments insert `version + 1`; active versions are save-guarded immutable.\n- **Idempotency is dedupeKey-based**: EarningEvent, Commission, and CommissionPayout carry natural keys (`conflictColumns`) — retried ingestion/settlement upserts instead of duplicating.\n- **Adjustments never rewrite**: correcting an earned/paid Commission means appending a CommissionAdjustment, not editing the Commission.\n- **CommissionPayout, not Payout**: avoids the pre-existing global table-name collision between commerce `Payout` and legacy affiliates `Payout` (`payouts`).\n- **Table names are global**: new models were named to avoid collisions across packages (`commission_payouts`, `sales_activities`, `attribution_policies`, …).\n- **Svelte module is svelte-check-gated**: no runtime component tests; `typecheck` runs `svelte-check` via `scripts/svelte-check-a11y.mjs`. Ship raw `.svelte` via `svelte-package`.\n- **Model transition methods don't save**: `markEarned()/approve()/markPayable()/markPaid()` (Commission) and the payout transitions mutate + stamp timestamps only — callers save; the settlement/payout services do both.\n- **`reject()` alone strands rows**: the model method only flips status — always reject through `transitionPayoutForSource`, which releases the batch's membership in the same transaction; stamped rows on a rejected payout would be unsettleable forever.\n- **The payout source stamp is derived data, never authorization**: `sourceKind`/`sourceId` on CommissionPayout index the history listing; both the listing and the lifecycle service re-verify actual membership and fail closed when the stamp cannot be proven.\n- **`sweepClearing` treats `clearingEndsAt: null` as immediately sweepable** (no clearing configured ⇒ nothing to wait for).\n- **Agreement freeze scope**: activating a ReferralAgreement freezes referrer/program/version/plan refs/clearingDays/approvalMode/effectiveFrom; `effectiveTo` (end-dating) and the evidence fields (`contractRef`, artifact url/hash, `acceptanceEvidence`) stay writable — e-signature completes downstream.\n- **Circular FK pair by design**: `Referral.snapshotId ↔ ReferralTermSnapshot.referralId`. Fine on SQLite (and no cross-table DDL constraints are emitted for these string FKs); keep an eye on strict-DDL environments.\n- **Attribution resolution is single-writer per (target, program)**: `resolve()` is idempotent against PERSISTED state, but two workers resolving the same target concurrently can both pass the existence check and create duplicate credit — the collection layer has no cross-row transaction (the same stance as payout batching, which relies on disjoint scopes for concurrency). Run intake resolution serially per target (it naturally is, in a request handler); duplicates are visible in the portal and correctable via `override()`.\n- **`ObjectRegistry.getConfig(X)` needs the class module imported** (decorator side effects) — manifest-only registration doesn't carry api/mcp/conflictColumns; tests asserting surface configs need a side-effect import of the module barrel.\n"
+  "agentDoc": "# @happyvertical/smrt-sales\n\nModular sales: provider-neutral agreement execution, CRM, referral intake, a neutral commissions financial core, and reusable Svelte surfaces. One installable package with distinct subpath exports:\n\n- `@happyvertical/smrt-sales/agreements`\n- `@happyvertical/smrt-sales/crm`\n- `@happyvertical/smrt-sales/referrals`\n- `@happyvertical/smrt-sales/commissions`\n- `@happyvertical/smrt-sales/svelte`\n\nThe root export re-exports every TS module. `agreements` depends on the provider-neutral `@happyvertical/signatures` contract and `smrt-assets`; provider credentials stay in the injected SDK adapter/secret store. `referrals` binds its versioned terms to `agreements`.\n\n## Validation\n\nRun `pnpm --filter @happyvertical/smrt-sales test` and `pnpm --filter @happyvertical/smrt-sales typecheck` for package changes. PostgreSQL-sensitive changes must also run `pnpm --filter @happyvertical/smrt-sales test:postgres`; the command uses the repository's disposable PostgreSQL harness and is registered in the PostgreSQL CI shard.\n\n## Roles vs. money\n\nReferrers and Sales Representatives are **distinct roles** and stay that way. Both connect to money through one neutral financial account:\n\n- **Earner** (commissions): payout identity — method, threshold, currency, status. Referenced by every Commission and CommissionPayout.\n- **SalesRepresentative** (crm) and **Referrer** (referrals): role models, each holding `profileId` (cross-package string ref to smrt-profiles) and `earnerId`.\n\n## Modules\n\n### agreements — verified execution evidence\n\n- **AgreementExecution**: private required-tenant orchestration state keyed by `(tenant_id, idempotency_key)`, with a collision-checked provider request/status, an expiring create-operation lease, source version/hash/size/Asset, intended signer identity/auth method, cancellation/expiry, reconciliation, exact staged artifact metadata, and secret-store references only.\n- **AgreementExecutionEvent**: private append-only evidence for verified webhooks and operator/provider operations. Provider events are deduped by tenant/provider replay key; explicit occurrence/first-receipt timestamps and the exact payload/hash are retained, while signature headers are never stored. A later receipt time for the same verified provider event is an idempotent replay. Stale, regressive, or conflicting terminal events are audited without regressing lifecycle state or creating executed evidence.\n- **ExecutedAgreement**: immutable read-only source version plus signed-document and audit-trail Asset ids/hashes/sizes/filenames/media types, completed signer evidence, acceptance/effective dates, and supersession reference. Amendments create new records.\n- **AgreementExecutionService**: accepts an SDK `SignatureProvider` and shared `AssetRuntimeLike`; enforces ambient tenant equality, expiring remote-attempt fencing, create idempotency, verified webhook ingestion/replay, tenant-fenced lifecycle compare-and-set with monotonic provider-event ordering, partial audit/failure updates that cannot overwrite lifecycle state, cancellation/expiry/reconciliation, exact artifact hashing, and immutable finalization. An expired create lease may be reclaimed only when the provider advertises atomic idempotency; otherwise a create with no confirmed request id must be reconciled/adopted before retry.\n\n### commissions — neutral financial core\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. 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\n### crm\n\n- **SalesRepresentative**: role model (`profileId`, `earnerId`, `status`).\n- **Lead**: identified prospect with owner assignment, generic acquisition source (`sourceKind`/`sourceId`), preserved `acquisitionContext` JSON, and audited merge (`mergedIntoId`; merges preserve activity + acquisition history on both sides).\n- **PipelineDefinition / PipelineStage**: configurable ordered stages with default `new → qualified → discovery → proposal → negotiation → closed_won | closed_lost` (seeded via `ensureDefaultPipeline()`); stages carry `probability` and `isWon`/`isLost` terminal flags.\n- **Opportunity**: qualified engagement — owner, pipeline + stage, `expectedValueCents`, `probability`, `expectedCloseAt`, outcome. Stage movement validated against the pipeline; terminal stages set `won|lost` status.\n- **SalesActivity**: activity/next-action trail for Leads and Opportunities (`subjectKind`/`subjectId`), also the audit trail for assignment, qualification, merges, and stage movement.\n- **OpportunityConversion**: idempotent conversion links (`targetKind`/`targetId` — client, project, contract, subscription, …) with a composite natural key. CRM never creates downstream records itself and never mutates referral or commission state.\n\n### referrals\n\n- **Referrer**: role model (`profileId`, `earnerId`, `status`).\n- **ReferralProgram**: program defaults — default commission plan key, default attribution policy key, eligibility defaults.\n- **AttributionPolicy**: versioned `(tenant_id, policy_key, version)` policy (per-tenant keys) — attribution `windowDays`, credit mode (`first_touch|last_touch|assigned|split`), split shares, self-referral/existing-client eligibility, eligible services/campaigns/regions, conflict behavior. Immutable once active; amendments bump `version`.\n- **ReferralLink**: shareable link/code per Referrer+Program. Codes are crypto-random, uniqueness-checked, with click counting.\n- **ReferralTouch**: immutable attribution evidence (`click|code_entry|manual_assignment|partner_entry`) with subject hints and evidence JSON.\n- **Referral**: the introduction — generic qualifying target (`targetKind`/`targetId`: lead, opportunity, client, project, subscription, …), resolved policy version, credit fraction (splits create sibling Referrals sharing `splitGroupId`), lifecycle `pending → attributed → qualified | disqualified | expired | under_review`.\n- **AttributionException**: conflict review queue. Conclusive policy resolves automatically; ambiguity creates an exception; overrides require a `resolutionReason` and are audited.\n- **ReferralAgreement**: versioned per-Referrer terms binding — pins `commissionPlanKey`/`planVersion`, effective dating, and an immutable `ExecutedAgreement` before activation. Amendments are fresh unsigned drafts and never inherit execution evidence.\n- **ReferralTermSnapshot**: immutable at qualification — freezes agreement/plan/policy version refs plus the calculation inputs needed to reproduce every later earning.\n- **Services**: `ReferralAgreementExecutionService` binds generated Referral Agreement versions to the generic execution service and activates/supersedes them transactionally with future-effective amendment support; `AttributionService`, `ReferralQualificationService`, and `ReferralCommissionService` retain their existing attribution/qualification/earning responsibilities.\n\n### svelte\n\nProps-driven presentational components (no data fetching, no model-class imports, Provider-free smrt-ui primitives, `--smrt-*` tokens only): CRM — `SalesDashboard`, `LeadList`, `OpportunityBoard`, `OpportunityDetail`; referrer portal — `ReferralLinkManager`, `ReferralStatusList`, `ReferrerEarningsSummary`, `CommissionBreakdown` (trace-explained amounts), `PayoutHistoryList`, `ExecutedAgreementsList`; operator — `AttributionConflictQueue` (award editor + required resolution reason), `PayoutBatchReview`, `CommissionExpenseSummary` (explicitly distinct from client invoices). Monetary props stay integer cents; `format.ts` converts at render. View-model prop types are exported interfaces (never inline intersected generics in `$props()`); pure helpers (dashboard math, award validation mirroring the service, payout action gating) are unit-tested while components are svelte-check-gated.\n\n## Currency\n\n**All monetary fields are integer cents** with `*Cents` suffixes; rates are decimal (`0`–`1`). Rounding happens once per calculation step via `roundCents()` (half-away-from-zero) and every Commission stores its `calculationTrace` so amounts are reproducible. Convert at display/commerce boundaries with `centsToAmount()`/`amountToCents()`.\n\n## Tenancy\n\nEvery model is `@TenantScoped({ mode: 'optional' })` with `@tenantId({ nullable: true })`. This deliberately departs from legacy smrt-affiliates (which was cross-tenant by design for ad networks): sales programs, earners, and payouts are tenant-owned; `tenantId: null` remains available for global/operator-level rows.\n\n## Cross-package references (plain strings)\n\n`profileId` → smrt-profiles Profile; `invoiceId` (CommissionPayout) → smrt-commerce Invoice; agreement artifacts → smrt-assets Asset ids. No static imports of unrelated sibling domain packages.\n\n## smrt-affiliates migration\n\n`@happyvertical/smrt-affiliates` is now a deprecated compatibility package that re-exports this package's commissions core under the legacy names (`Partner` → `Earner`, `Payout` → `CommissionPayout`, `Commission`, collections, enums) with `@deprecated` guidance and **no duplicate persistence model**. The data/API mapping lives in `packages/affiliates/MIGRATION.md`.\n\n## Gotchas\n\n- **Cents vs. rates**: `*Cents` fields are INTEGER (`= 0` defaults); `rate`/`probability`/`shareFraction` are DECIMAL (`= 0.0` defaults). Don't mix the two conventions on one field.\n- **Versioned terms are rows, not edits**: CommissionPlan / AttributionPolicy / ReferralAgreement amendments insert `version + 1`; active versions are save-guarded immutable.\n- **Idempotency is dedupeKey-based**: EarningEvent, Commission, and CommissionPayout carry natural keys (`conflictColumns`) — retried ingestion/settlement upserts instead of duplicating.\n- **Adjustments never rewrite**: correcting an earned/paid Commission means appending a CommissionAdjustment, not editing the Commission.\n- **CommissionPayout, not Payout**: avoids the pre-existing global table-name collision between commerce `Payout` and legacy affiliates `Payout` (`payouts`).\n- **Table names are global**: new models were named to avoid collisions across packages (`commission_payouts`, `sales_activities`, `attribution_policies`, …).\n- **Svelte module is svelte-check-gated**: no runtime component tests; `typecheck` runs `svelte-check` via `scripts/svelte-check-a11y.mjs`. Ship raw `.svelte` via `svelte-package`.\n- **Model transition methods don't save**: `markEarned()/approve()/markPayable()/markPaid()` (Commission) and the payout transitions mutate + stamp timestamps only — callers save; the settlement/payout services do both.\n- **`reject()` alone strands rows**: the model method only flips status — always reject through `transitionPayoutForSource`, which releases the batch's membership in the same transaction; stamped rows on a rejected payout would be unsettleable forever.\n- **The payout source stamp is derived data, never authorization**: `sourceKind`/`sourceId` on CommissionPayout index the history listing; both the listing and the lifecycle service re-verify actual membership and fail closed when the stamp cannot be proven.\n- **`sweepClearing` treats `clearingEndsAt: null` as immediately sweepable** (no clearing configured ⇒ nothing to wait for).\n- **Agreement freeze scope**: activating a ReferralAgreement requires and freezes its execution/evidence refs along with its commercial terms. `effectiveTo` remains writable for explicit end-dating; signed bytes, hashes, signer evidence, and audit trail exist only on immutable ExecutedAgreement/Asset records.\n- **Circular FK pair by design**: `Referral.snapshotId ↔ ReferralTermSnapshot.referralId`. Fine on SQLite (and no cross-table DDL constraints are emitted for these string FKs); keep an eye on strict-DDL environments.\n- **Attribution resolution is single-writer per (target, program)**: `resolve()` is idempotent against PERSISTED state, but two workers resolving the same target concurrently can both pass the existence check and create duplicate credit — the collection layer has no cross-row transaction (the same stance as payout batching, which relies on disjoint scopes for concurrency). Run intake resolution serially per target (it naturally is, in a request handler); duplicates are visible in the portal and correctable via `override()`.\n- **`ObjectRegistry.getConfig(X)` needs the class module imported** (decorator side effects) — manifest-only registration doesn't carry api/mcp/conflictColumns; tests asserting surface configs need a side-effect import of the module barrel.\n"
 }