@happyvertical/smrt-sales 0.54.4 → 0.55.1

package/AGENTS.md

@@ -62,7 +62,7 @@ Business/domain models are generally `@TenantScoped({ mode: 'optional' })` with
 - **CommissionPayout, not Payout**: avoids the pre-existing global table-name collision between commerce `Payout` and legacy affiliates `Payout` (`payouts`).
 - **Table names are global**: new models were named to avoid collisions across packages (`commission_payouts`, `sales_activities`, `attribution_policies`, …).
 - **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`.
-- **Lead workflows stay generic**: call `LeadWorkflowService` for tenant-safe intake, audited follow-up, qualification, and opportunity closure with optional conversion links. 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.
+- **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.
 - **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.
 - **`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.
 - **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.

package/README.md

@@ -89,7 +89,7 @@ decimals from `0` to `1`; rounding occurs through the exported money helpers.
 ## Lead intake and lifecycle
 
 `LeadWorkflowService` is the tenant-safe, application-facing seam for generic
-intake, follow-up, qualification, and opportunity closure. Construct it with the host database inside an
+intake, follow-up, qualification, stage movement, and opportunity closure. Construct it with the host database inside an
 active `withTenant()` context; the host supplies authorization, actor/profile
 ids, and view-model mapping.
 
@@ -108,10 +108,13 @@ await workflow.scheduleNextAction({
 
 The service atomically records assignment and status audit events, human
 activities, scheduled next actions, and monotonic task completion.
-`createLead()` requires a name and email or phone, normalizes email, and supports
+`createLead()` requires a name and email or phone, normalizes email, supports an
+optional host-authorized `profileId`, and supports
 active-lead deduplication and caller-supplied idempotency keys. A terminal duplicate
 is reported for the host to resolve explicitly. `qualifyLead()` delegates to
-`LeadCollection.qualify()` and returns the linked opportunity; `closeOpportunity()`
+`LeadCollection.qualify()` and returns the linked opportunity.
+`moveOpportunityToStage()` atomically moves an open Opportunity between
+nonterminal same-pipeline stages; exact retries add no audit. `closeOpportunity()`
 selects the pipeline's won/lost stage and optionally records a won conversion
 link. CRM never creates the downstream target. Money remains integer cents via
 `expectedValueCents`; actor attribution uses `actorProfileId`.

package/agents/crm.md

@@ -10,7 +10,7 @@ money), and the Gotchas that apply before editing anything live in
 - **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.
 - **Opportunity**: qualified engagement — owner, pipeline + stage, `expectedValueCents`, `probability`, `expectedCloseAt`, outcome. Stage movement validated against the pipeline; terminal stages set `won|lost` status.
 - **SalesActivity**: activity/next-action trail for Leads and Opportunities (`subjectKind`/`subjectId`), also the audit trail for assignment, qualification, merges, and stage movement.
-- **LeadWorkflowService**: the required tenant-safe Lead mutation seam. It transactionally locks the affected Lead/Opportunity (and completion task on PostgreSQL), accepts only active same-tenant representatives, writes actor-attributed audits alongside mutations, and returns merge-aware timeline/work-state reads. It owns validated `createLead()` intake, `new | disqualified → working`, `new | working → disqualified`, human follow-up (`note | call | email | meeting`), task scheduling/completion, delegated qualification, and terminal Opportunity closure/conversion. Merging remains a collection lifecycle.
+- **LeadWorkflowService**: the required tenant-safe Lead mutation seam. It transactionally locks the affected Lead/Opportunity (and completion task on PostgreSQL), accepts only active same-tenant representatives, writes actor-attributed audits alongside mutations, and returns merge-aware timeline/work-state reads. It owns validated `createLead()` intake, `new | disqualified → working`, `new | working → disqualified`, human follow-up (`note | call | email | meeting`), task scheduling/completion, delegated qualification, nonterminal Opportunity stage movement, and terminal Opportunity closure/conversion. Merging remains a collection lifecycle.
 - **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.
 
 Workflow calls require ambient tenant context. Mutations require an actor profile
@@ -30,9 +30,16 @@ Caller idempotency keys are persisted through deterministic immutable activity
 ids, including when intake resolves to an existing active Lead; reusing a key
 with changed intent is rejected. PostgreSQL uses transaction advisory/row locks,
 while single-connection adapters serialize the entire transaction.
+The optional `profileId` is a host-authorized cross-package identity link and is
+part of that immutable retry intent; Sales stores it but does not authorize or
+load the referenced Profile.
 
 `qualifyLead()` delegates to `LeadCollection.qualify()` on the same transaction
-executor and returns whether the Opportunity was newly created. `closeOpportunity()`
+executor and returns whether the Opportunity was newly created.
+`moveOpportunityToStage()` locks an open Opportunity and atomically moves it to
+a nonterminal stage in the same tenant and pipeline. An exact stage/probability
+retry is a no-op; a conflicting same-stage probability is refused. Terminal
+stages remain exclusive to `closeOpportunity()`, which
 resolves the configured won/lost terminal stage, delegates stage movement, and
 optionally records a won conversion in the same transaction. Exact retries add
 no stage activity or conversion. `getLeadWorkState()` includes the canonical

package/dist/agreements.js

@@ -1,3 +1,3 @@
-import "./chunks/__smrt-register__-Cxp00I21.js";
+import "./chunks/__smrt-register__-CJ2_r5s0.js";
 import { a as AgreementExecutionEvent, c as AGREEMENT_EXECUTION_STATUSES, d as sanitizeSignerIntent, i as AgreementExecutionEventCollection, l as coerceAgreementDate, n as ExecutedAgreementCollection, o as AgreementExecutionCollection, r as ExecutedAgreement, s as AgreementExecution, t as AgreementExecutionService, u as sanitizeSignerEvidence } from "./chunks/agreements-BB_tNU0U.js";
 export { AGREEMENT_EXECUTION_STATUSES, AgreementExecution, AgreementExecutionCollection, AgreementExecutionEvent, AgreementExecutionEventCollection, AgreementExecutionService, ExecutedAgreement, ExecutedAgreementCollection, coerceAgreementDate, sanitizeSignerEvidence, sanitizeSignerIntent };