@happyvertical/smrt-sales 0.57.33 → 0.57.35

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.57.33",
+  "packageVersion": "0.57.35",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "f94bca5eba8b84a4bdf6dbdaba9273919adfe1a56de350c6b755c31f4cf9c7d9",
-    "packageJson": "2b2a8e76f4195b2861ee028921211ef0c5be0eb631e37a273bdc3bef484c1e71",
-    "agents": "561dfe5741f74b8f105617a907b5a17446d4546f6fdef7eb754956bfd09aedd9",
+    "manifest": "9b771789fb397beb6efb642625d6fbc9cb47631a6698e08c9db40c9c4ae9358a",
+    "packageJson": "ca43423af361e16fd040e21dabf206c66922ec6f4f4e23db84e812d2e65ce72c",
+    "agents": "a96547d3b8105fd1a2d767b3c05341cf9f8ea9dec56c3c212d6239d19fb689ea",
     "moduleDoc:agents/agreements.md": "86609271b56633c1b6a3d9b1905a200cad1cb15de54adb8ca9f1200f6af8b9ce",
     "moduleDoc:agents/commissions.md": "2f41ada34b583f037d9337f9ba3f4c93fd64d1cfcd0830cb7e1c260a6b339374",
     "moduleDoc:agents/crm.md": "074eff9e3ca7ae6d86e65a1d29ac7b9b555b719b3801918678b15df7538f99e0",
@@ -2744,7 +2744,8 @@
           "type": "foreignKey",
           "required": true,
           "related": "Earner",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The affiliate who earned this commission."
         },
         {
           "name": "earningEventId",
@@ -2828,21 +2829,24 @@
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "How much was earned, in the smallest unit of the currency."
         },
         {
           "name": "currency",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency the commission is paid in."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "pending"
+          "default": "pending",
+          "description": "Where the commission stands, from pending to paid."
         },
         {
           "name": "clearingEndsAt",
@@ -2907,7 +2911,8 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A reference that stops the same commission being recorded twice."
         },
         {
           "name": "metadata",
@@ -3507,7 +3512,8 @@
           "type": "foreignKey",
           "required": true,
           "related": "Earner",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The affiliate being paid."
         },
         {
           "name": "periodStart",
@@ -3540,14 +3546,16 @@
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "The total being paid, in the smallest unit of the currency."
         },
         {
           "name": "currency",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency of the payment."
         },
         {
           "name": "payoutMethod",
@@ -3568,7 +3576,8 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "pending"
+          "default": "pending",
+          "description": "Whether the payment is waiting, being sent, completed or failed."
         },
         {
           "name": "paymentReference",
@@ -3588,7 +3597,8 @@
           "name": "paidAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the payment went out."
         },
         {
           "name": "invoiceId",
@@ -3609,7 +3619,8 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A reference that stops the same payout being made twice."
         },
         {
           "name": "sourceKind",
@@ -4478,14 +4489,16 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The name this payee is paid under."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "pending"
+          "default": "pending",
+          "description": "Whether this payee can be paid."
         },
         {
           "name": "payoutMethod",
@@ -9474,14 +9487,16 @@
           "type": "foreignKey",
           "required": true,
           "related": "Referrer",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The affiliate who sent this person."
         },
         {
           "name": "programId",
           "type": "foreignKey",
           "required": true,
           "related": "ReferralProgram",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The program this referral counts towards."
         },
         {
           "name": "policyKey",
@@ -9502,7 +9517,8 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "pending"
+          "default": "pending",
+          "description": "Whether the referral is waiting, has led to a sale or has lapsed."
         },
         {
           "name": "targetKind",
@@ -10722,21 +10738,24 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short name for the program, used in links and reports."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What you call this program."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "draft"
+          "default": "draft",
+          "description": "Whether the program is in draft, running or finished."
         },
         {
           "name": "defaultCommissionPlanKey",
@@ -11396,14 +11415,16 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The name you know this affiliate by."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "pending"
+          "default": "pending",
+          "description": "Whether this affiliate is approved to send you referrals."
         },
         {
           "name": "metadata",
@@ -13908,7 +13929,7 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 232
   },
-  "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\nPer-module semantics live in sibling module docs — read the one for the module\nyou are editing. This file keeps what holds in every module.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `agreements` | verified execution evidence — private orchestration state, append-only provider events, immutable executed agreements, and the provider-neutral execution service | [agents/agreements.md](agents/agreements.md) |\n| `commissions` | the neutral financial core — earners, versioned plans, earning events, commissions, adjustments, balances, and payout settlement | [agents/commissions.md](agents/commissions.md) |\n| `crm` | leads, configurable pipelines, opportunities, tenant-safe Lead follow-up, activity trail, and idempotent conversion links | [agents/crm.md](agents/crm.md) |\n| `referrals` | referrers, programs, versioned attribution policies, links/touches, referrals, exception review, and term snapshots | [agents/referrals.md](agents/referrals.md) |\n| `svelte` | props-driven presentational surfaces for CRM, the referrer portal, and operator review | [agents/svelte.md](agents/svelte.md) |\n\n## Currency\n\n**All monetary fields are integer cents** with `*Cents` suffixes; that scale is a Sales contract, not an implicit framework currency rule. Fresh PostgreSQL/DuckDB INTEGER columns are BIGINT, while JavaScript hydration rejects values outside the safe-integer range. 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\nBusiness/domain models are generally `@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, while `tenantId: null` remains available for intentional global/operator-level rows. Immutable tenant-bound execution evidence (`AgreementExecution`, `AgreementExecutionEvent`, `ExecutedAgreement`) and private orchestration fences (`CommissionAdjustmentOperation`) instead use required tenancy with a non-null owner; never weaken those rows to optional tenancy.\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- **Optional same-package foreign keys use null**: execution, supersession, earning-event, and payout references that are absent persist as `null`, never `''`; their physical database constraints remain enabled when a real id is present.\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- **Adjustment retries use the service**: CommissionAdjustment has no public operation field and rejects an untyped `operationId` constructor option; ordinary legacy creates without one remain compatible. `CommissionAdjustmentService` transactionally claims the private operation fence with insert-on-conflict-no-op, creates the explicit mapped adjustment id only for the winner, then verifies the persisted intent; the same globally unique operation UUID cannot be reused by another tenant.\n- **Manifest objects must remain root-importable**: generated consumer registration imports every manifest-advertised model and collection from `@happyvertical/smrt-sales`. The `CommissionAdjustmentOperation` and `ReferralClickOperation` model/collection values are therefore root and owning-subpath exports for runtime loading, while their `api: false`, `mcp: false`, and `cli: false` decorators keep them off generated application surfaces. Publish-pack validation imports the actual CLI-generated register against the packed tarball.\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 validation includes interaction contracts**: intake and inbox components have runtime component tests; `typecheck` also runs `svelte-check` via `scripts/svelte-check-a11y.mjs`. Ship raw `.svelte` via `svelte-package`.\n- **Lead workflows stay generic**: call `LeadWorkflowService` for tenant-safe intake, audited follow-up, qualification, nonterminal Opportunity stage movement, and terminal closure with optional conversion links. Optional intake `profileId` is stored and fingerprinted but remains host-authorized. The service delegates CRM lifecycles to their owning collections; hosts supply authorization and create downstream records. `LeadCreateForm`, `LeadList`, and `LeadDetail` are props/callback only. See [agents/crm.md](agents/crm.md) for dedupe, retry, and inbox contracts.\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- **recordClick inside your transaction participates, never nests**: a nested adapter `transaction()` takes an independent pooled connection (happyvertical/sdk#1108) — it deadlocks undetectably on locks the caller's transaction holds (PostgreSQL sees a promise-wait, not a lock-wait) and refuses caller-created uncommitted links as `unknown_code`. Pass the caller's transaction database as `RecordClickInput.transaction` or bind the collection to it (`{ db: tx, _reuseInitializedDb: true, _deferRuntimeInitialization: true }` — detected and honored automatically); a pool-level database passed as `transaction` is refused with typed reason `invalid_transaction`. Participating results are bound to the caller's transaction — carry ids across the commit boundary; the pool-bound default still self-transacts and rehydrates after commit.\n- **Click retries reuse one key**: pass the exact same non-empty, well-formed-Unicode `recordClick.idempotencyKey` (maximum 256 UTF-8 bytes) on transport/database retry. Omitting it remains source-compatible but creates and returns a one-shot UUID; it cannot deduplicate a later independent invocation. `maxEvidenceBytes` guards creation; changing it cannot turn an already-committed exact replay into failure. Replay validation is against the immutable operation/touch snapshot, not mutable current link fields: later link edits preserve exact replay, the result link is current, and the touch evidence is the original snapshot. The private optional-tenant `ReferralClickOperation` table is the serialization fence and must be included in schema migration. Never pre-bound caller evidence: Sales owns the authoritative final-envelope byte check.\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\n- **Governed sales use the owned service factory**: `SalesGovernanceService`\n  accepts allowlisted PostgreSQL connection configuration only, owns its\n  adapter and transaction executors, and guards private state/model writes.\n  DuckDB support remains blocked on SDK #1452; SQLite is also rejected until\n  same-process BUSY recovery is proven. Quote issue/sign always recheck\n  current seller, host policy/inventory and exact finance approval; see\n  [agents/crm.md](agents/crm.md#governed-sellers-quotes-and-canonical-advertiser-registration).\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\nPer-module semantics live in sibling module docs — read the one for the module\nyou are editing. This file keeps what holds in every module.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `agreements` | verified execution evidence — private orchestration state, append-only provider events, immutable executed agreements, and the provider-neutral execution service | [agents/agreements.md](agents/agreements.md) |\n| `commissions` | the neutral financial core — earners, versioned plans, earning events, commissions, adjustments, balances, and payout settlement | [agents/commissions.md](agents/commissions.md) |\n| `crm` | leads, configurable pipelines, opportunities, tenant-safe Lead follow-up, activity trail, and idempotent conversion links | [agents/crm.md](agents/crm.md) |\n| `referrals` | referrers, programs, versioned attribution policies, links/touches, referrals, exception review, and term snapshots | [agents/referrals.md](agents/referrals.md) |\n| `svelte` | props-driven presentational surfaces for CRM, the referrer portal, and operator review | [agents/svelte.md](agents/svelte.md) |\n\n## Currency\n\n**All monetary fields are integer cents** with `*Cents` suffixes; that scale is a Sales contract, not an implicit framework currency rule. Fresh PostgreSQL/DuckDB INTEGER columns are BIGINT, while JavaScript hydration rejects values outside the safe-integer range. 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\nBusiness/domain models are generally `@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, while `tenantId: null` remains available for intentional global/operator-level rows. Immutable tenant-bound execution evidence (`AgreementExecution`, `AgreementExecutionEvent`, `ExecutedAgreement`) and private orchestration fences (`CommissionAdjustmentOperation`) instead use required tenancy with a non-null owner; never weaken those rows to optional tenancy.\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- **Optional same-package foreign keys use null**: execution, supersession, earning-event, and payout references that are absent persist as `null`, never `''`; their physical database constraints remain enabled when a real id is present.\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- **Adjustment retries use the service**: CommissionAdjustment has no public operation field and rejects an untyped `operationId` constructor option; ordinary legacy creates without one remain compatible. `CommissionAdjustmentService` transactionally claims the private operation fence with insert-on-conflict-no-op, creates the explicit mapped adjustment id only for the winner, then verifies the persisted intent; the same globally unique operation UUID cannot be reused by another tenant.\n- **Manifest objects must remain root-importable**: generated consumer registration imports every manifest-advertised model and collection from `@happyvertical/smrt-sales`. The `CommissionAdjustmentOperation` and `ReferralClickOperation` model/collection values are therefore root and owning-subpath exports for runtime loading, while their `api: false`, `mcp: false`, and `cli: false` decorators keep them off generated application surfaces. Publish-pack validation imports the actual CLI-generated register against the packed tarball.\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 validation includes interaction contracts**: intake and inbox components have runtime component tests; `typecheck` also runs `svelte-check` via `scripts/svelte-check-a11y.mjs`. Ship raw `.svelte` via `svelte-package`.\n- **Lead workflows stay generic**: call `LeadWorkflowService` for tenant-safe intake, audited follow-up, qualification, nonterminal Opportunity stage movement, and terminal closure with optional conversion links. Optional intake `profileId` is stored and fingerprinted but remains host-authorized. The service delegates CRM lifecycles to their owning collections; hosts supply authorization and create downstream records. `LeadCreateForm`, `LeadList`, and `LeadDetail` are props/callback only. See [agents/crm.md](agents/crm.md) for dedupe, retry, and inbox contracts.\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- **recordClick inside your transaction participates, never nests**: a nested adapter `transaction()` takes an independent pooled connection (happyvertical/sdk#1108) — it deadlocks undetectably on locks the caller's transaction holds (PostgreSQL sees a promise-wait, not a lock-wait) and refuses caller-created uncommitted links as `unknown_code`. Pass the caller's transaction database as `RecordClickInput.transaction` or bind the collection to it (`{ db: tx, _reuseInitializedDb: true, _deferRuntimeInitialization: true }` — detected and honored automatically); a pool-level database passed as `transaction` is refused with typed reason `invalid_transaction`. Participating results are bound to the caller's transaction — carry ids across the commit boundary; the pool-bound default still self-transacts and rehydrates after commit.\n- **Click retries reuse one key**: pass the exact same non-empty, well-formed-Unicode `recordClick.idempotencyKey` (maximum 256 UTF-8 bytes) on transport/database retry. Omitting it remains source-compatible but creates and returns a one-shot UUID; it cannot deduplicate a later independent invocation. `maxEvidenceBytes` guards creation; changing it cannot turn an already-committed exact replay into failure. Replay validation is against the immutable operation/touch snapshot, not mutable current link fields: later link edits preserve exact replay, the result link is current, and the touch evidence is the original snapshot. The private optional-tenant `ReferralClickOperation` table is the serialization fence and must be included in schema migration. Never pre-bound caller evidence: Sales owns the authoritative final-envelope byte check.\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\n- **Governed sales use the owned service factory**: `SalesGovernanceService`\n  accepts allowlisted PostgreSQL connection configuration only, owns its\n  adapter and transaction executors, and guards private state/model writes.\n  DuckDB support remains blocked on SDK #1452; SQLite is also rejected until\n  same-process BUSY recovery is proven. Quote issue/sign always recheck\n  current seller, host policy/inventory and exact finance approval; see\n  [agents/crm.md](agents/crm.md#governed-sellers-quotes-and-canonical-advertiser-registration).\n\n- **Recipe `affiliates.referrals`** (`src/referrals/recipes.ts`, help in `src/referrals/referrals.recipe.md`): the affiliate feature for catalog hosts (referrers, programs, referrals, commissions, payouts). It lives here because `@happyvertical/smrt-affiliates` is a model-less shim and a recipe needs models of its own package. Fields it shows carry `@field({ description })` in plain words.\n",
   "moduleDocs": [
     {
       "path": "agents/agreements.md",
@@ -13937,6 +13958,389 @@
     }
   ],
   "recipes": [
+    {
+      "id": "affiliates.referrals",
+      "className": "AffiliatesReferralsRecipe",
+      "label": "Affiliates",
+      "summary": "Reward partners for the customers they send you, and pay them what they earn.",
+      "synonyms": [
+        "referrals",
+        "referral program",
+        "partners",
+        "commissions",
+        "payouts",
+        "refer a friend"
+      ],
+      "models": [
+        "@happyvertical/smrt-sales:Referrer",
+        "@happyvertical/smrt-sales:ReferralProgram",
+        "@happyvertical/smrt-sales:Referral",
+        "@happyvertical/smrt-sales:Earner",
+        "@happyvertical/smrt-sales:Commission",
+        "@happyvertical/smrt-sales:CommissionPayout"
+      ],
+      "nav": [
+        {
+          "label": "Affiliates",
+          "model": "@happyvertical/smrt-sales:Referrer",
+          "icon": "users",
+          "description": "The partners and customers who send people your way.",
+          "noun": "affiliate"
+        },
+        {
+          "label": "Programs",
+          "model": "@happyvertical/smrt-sales:ReferralProgram",
+          "icon": "layers",
+          "description": "The offers that decide what a referral earns.",
+          "noun": "program"
+        },
+        {
+          "label": "Referrals",
+          "model": "@happyvertical/smrt-sales:Referral",
+          "icon": "repeat",
+          "description": "Each person sent to you, and whether it led to a sale."
+        },
+        {
+          "label": "Commissions",
+          "model": "@happyvertical/smrt-sales:Commission",
+          "icon": "receipt",
+          "description": "What each affiliate has earned and where it stands."
+        },
+        {
+          "label": "Payouts",
+          "model": "@happyvertical/smrt-sales:CommissionPayout",
+          "icon": "bank",
+          "description": "Payments made to affiliates for what they earned."
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "grow",
+        "label": "Grow",
+        "icon": "tag",
+        "description": "Bring in new customers and reward the people who help."
+      },
+      "options": {
+        "@happyvertical/smrt-sales:Referrer": {
+          "fields": {
+            "displayName": {
+              "label": "Name",
+              "order": 1
+            },
+            "status": {
+              "order": 2
+            },
+            "profileId": {
+              "label": "Person",
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "earnerId": {
+              "label": "Payee",
+              "visibility": "advanced"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:ReferralProgram": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "key": {
+              "label": "Short name",
+              "order": 2
+            },
+            "status": {
+              "order": 3
+            },
+            "defaultCommissionPlanKey": {
+              "visibility": "advanced"
+            },
+            "defaultAttributionPolicyKey": {
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:Referral": {
+          "fields": {
+            "referrerId": {
+              "label": "Affiliate",
+              "order": 1
+            },
+            "programId": {
+              "label": "Program",
+              "order": 2
+            },
+            "status": {
+              "order": 3
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "policyKey": {
+              "visibility": "hidden"
+            },
+            "policyVersion": {
+              "visibility": "hidden"
+            },
+            "targetKind": {
+              "visibility": "advanced"
+            },
+            "targetId": {
+              "visibility": "advanced"
+            },
+            "creditFraction": {
+              "visibility": "advanced"
+            },
+            "splitGroupId": {
+              "visibility": "hidden"
+            },
+            "primaryTouchId": {
+              "visibility": "hidden"
+            },
+            "attributedAt": {
+              "visibility": "advanced"
+            },
+            "qualifiedAt": {
+              "visibility": "advanced"
+            },
+            "expiresAt": {
+              "visibility": "advanced"
+            },
+            "snapshotId": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:Earner": {
+          "fields": {
+            "displayName": {
+              "label": "Name",
+              "order": 1
+            },
+            "status": {
+              "order": 2
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "kind": {
+              "visibility": "advanced"
+            },
+            "profileId": {
+              "visibility": "advanced"
+            },
+            "payoutMethod": {
+              "visibility": "advanced"
+            },
+            "payoutDestination": {
+              "visibility": "advanced"
+            },
+            "payoutThresholdCents": {
+              "visibility": "advanced"
+            },
+            "payoutScheduleKey": {
+              "visibility": "advanced"
+            },
+            "currency": {
+              "visibility": "advanced"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:Commission": {
+          "fields": {
+            "earnerId": {
+              "label": "Affiliate",
+              "order": 1
+            },
+            "amountCents": {
+              "label": "Amount",
+              "order": 2
+            },
+            "currency": {
+              "order": 3
+            },
+            "status": {
+              "order": 4
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "earningEventId": {
+              "visibility": "hidden"
+            },
+            "planKey": {
+              "visibility": "advanced"
+            },
+            "planVersion": {
+              "visibility": "hidden"
+            },
+            "componentKey": {
+              "visibility": "hidden"
+            },
+            "termsSnapshotKind": {
+              "visibility": "hidden"
+            },
+            "termsSnapshotId": {
+              "visibility": "hidden"
+            },
+            "basis": {
+              "visibility": "advanced"
+            },
+            "baseAmountCents": {
+              "visibility": "advanced"
+            },
+            "rate": {
+              "visibility": "advanced"
+            },
+            "shareFraction": {
+              "visibility": "hidden"
+            },
+            "splitGroupId": {
+              "visibility": "hidden"
+            },
+            "clearingEndsAt": {
+              "visibility": "advanced"
+            },
+            "earnedAt": {
+              "visibility": "advanced"
+            },
+            "approvedAt": {
+              "visibility": "advanced"
+            },
+            "payableAt": {
+              "visibility": "advanced"
+            },
+            "paidAt": {
+              "visibility": "advanced"
+            },
+            "payoutId": {
+              "visibility": "advanced"
+            },
+            "sourceKind": {
+              "visibility": "hidden"
+            },
+            "sourceId": {
+              "visibility": "hidden"
+            },
+            "calculationTrace": {
+              "visibility": "hidden"
+            },
+            "dedupeKey": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:CommissionPayout": {
+          "fields": {
+            "earnerId": {
+              "label": "Affiliate",
+              "order": 1
+            },
+            "totalAmountCents": {
+              "label": "Total",
+              "order": 2
+            },
+            "currency": {
+              "order": 3
+            },
+            "status": {
+              "order": 4
+            },
+            "paidAt": {
+              "order": 5
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "periodStart": {
+              "visibility": "advanced"
+            },
+            "periodEnd": {
+              "visibility": "advanced"
+            },
+            "commissionTotalCents": {
+              "visibility": "advanced"
+            },
+            "adjustmentTotalCents": {
+              "visibility": "advanced"
+            },
+            "payoutMethod": {
+              "visibility": "advanced"
+            },
+            "payoutDestination": {
+              "visibility": "advanced"
+            },
+            "paymentReference": {
+              "visibility": "advanced"
+            },
+            "providerRef": {
+              "visibility": "hidden"
+            },
+            "invoiceId": {
+              "visibility": "hidden"
+            },
+            "notes": {
+              "visibility": "advanced"
+            },
+            "idempotencyKey": {
+              "visibility": "hidden"
+            },
+            "sourceKind": {
+              "visibility": "hidden"
+            },
+            "sourceId": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nAffiliates lets partners and customers send people your way and earn a reward\nwhen it leads to a sale. You set up a program that says what a referral earns,\nsign up the people who will refer, record each person they send, and see what\neach affiliate has earned and what has been paid out.\n\n## Tasks\n\n### Sign up an affiliate\n\n1. Open the list of affiliates and choose **New**.\n2. Type their **{field:Referrer.displayName}**.\n3. Save. They stay pending until you approve them by setting the **{field:Referrer.status}**.\n\n### Set up a program\n\n1. Open the programs and choose **New**.\n2. Give the program a **{field:ReferralProgram.name}** your affiliates will understand.\n3. Set the **{field:ReferralProgram.status}** to active when you are ready to start.\n4. Save.\n\n### Record a referral\n\n1. Open the referrals and choose **New**.\n2. Pick the **{field:Referral.referrerId}** who sent the person and the **{field:Referral.programId}** it belongs to.\n3. Save. The referral stays pending until it leads to a sale.\n\n### Check what an affiliate has earned\n\n1. Open the commissions and find the affiliate.\n2. Read the **{field:Commission.amountCents}** and the **{field:Commission.status}** of each one.\n3. A commission moves from pending to approved, then payable, then paid as it is worked through.\n\n### Check a payout\n\nPayouts are made by the commission payout service, not by hand in the app. You\ncan see what has been paid.\n\n1. Open the payouts.\n2. Read the **{field:CommissionPayout.earnerId}**, the **{field:CommissionPayout.totalAmountCents}** and the **{field:CommissionPayout.status}**.\n3. A payout is waiting, approved, being sent, then completed. It shows failed or rejected if the money did not go out.\n",
+        "fieldRefs": [
+          "Commission.amountCents",
+          "Commission.status",
+          "CommissionPayout.earnerId",
+          "CommissionPayout.status",
+          "CommissionPayout.totalAmountCents",
+          "Referral.programId",
+          "Referral.referrerId",
+          "ReferralProgram.name",
+          "ReferralProgram.status",
+          "Referrer.displayName",
+          "Referrer.status"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: node:crypto; and its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    },
     {
       "id": "sales.pipeline",
       "className": "SalesPipelineRecipe",