@elevasis/core 0.22.0 → 0.24.0

package/src/organization-model/domains/sales.ts

@@ -1,589 +1,380 @@
-import { z } from 'zod'
-import { DescriptionSchema, DisplayMetadataSchema, ModelIdSchema, ReferenceIdsSchema } from './shared'
-
-export const SalesStageSemanticClassSchema = z.enum(['open', 'active', 'nurturing', 'closed_won', 'closed_lost'])
-
-export const SalesStageSchema = DisplayMetadataSchema.extend({
-  id: ModelIdSchema,
-  order: z.number().int().min(0),
-  semanticClass: SalesStageSemanticClassSchema,
-  surfaceIds: ReferenceIdsSchema,
-  resourceIds: ReferenceIdsSchema
-})
-
-export const SalesPipelineSchema = z.object({
-  id: ModelIdSchema,
-  label: z.string().trim().min(1).max(120),
-  description: DescriptionSchema.optional(),
-  entityId: ModelIdSchema,
-  stages: z.array(SalesStageSchema).min(1)
-})
-
-export const OrganizationModelSalesSchema = z.object({
-  entityId: ModelIdSchema,
-  defaultPipelineId: ModelIdSchema,
-  pipelines: z.array(SalesPipelineSchema).min(1)
-})
-
-export const DEFAULT_ORGANIZATION_MODEL_SALES: z.infer<typeof OrganizationModelSalesSchema> = {
-  entityId: 'crm.deal',
-  defaultPipelineId: 'default',
-  pipelines: [
-    {
-      id: 'default',
-      label: 'Default Pipeline',
-      entityId: 'crm.deal',
-      stages: [
-        {
-          id: 'interested',
-          label: 'Interested',
-          color: 'blue',
-          order: 1,
-          semanticClass: 'open',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'proposal',
-          label: 'Proposal',
-          color: 'yellow',
-          order: 2,
-          semanticClass: 'active',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'closing',
-          label: 'Closing',
-          color: 'lime',
-          order: 3,
-          semanticClass: 'active',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'closed_won',
-          label: 'Closed Won',
-          color: 'green',
-          order: 4,
-          semanticClass: 'closed_won',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'closed_lost',
-          label: 'Closed Lost',
-          color: 'red',
-          order: 5,
-          semanticClass: 'closed_lost',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'nurturing',
-          label: 'Nurturing',
-          color: 'grape',
-          order: 6,
-          semanticClass: 'nurturing',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        }
-      ]
-    }
-  ]
-}
-
-// ============================================================================
-// Lead-Gen Stateful Pipeline Definitions (Decision N8, Wave 4)
-//
-// Defines the (pipeline_key, stage_key, state_key) vocabulary for the three
-// entities that carry the Stateful trait via Track B:
-//   - acq_lists         (pipeline_key='lead-gen', stage_key='lifecycle')
-//   - acq_list_members  (pipeline_key='lead-gen', stages: outreach / prospecting / qualification)
-//   - acq_list_companies (pipeline_key='lead-gen', stages: outreach / prospecting / qualification)
-//
-// DB columns (pipeline_key, stage_key, state_key) remain free-form text with no
-// CHECK constraint — new states can be introduced without a migration (Decision N8).
-// These definitions are the org-specific source of truth consumed by UI and tooling.
-//
-// State vocabularies sourced from the post-restructure sales tree (W3 canonical):
-//   outreach/:
-//     - personalized  (instantly-personalization.ts → contacts)
-//     - uploaded      (instantly-upload.ts → contacts)
-//     - interested    (instantly-reply-handler.ts → contacts, initial reply transition)
-//   prospecting/:
-//     - populated     (apify-acquire.ts, apify-scrape.ts → companies)
-//     - crawled       (apify-website-crawl.ts → companies)
-//     - extracted     (website-extract.ts → companies)
-//     - discovered    (email-discovery.ts, anymailfinder-enrich.ts → contacts)
-//     - verified      (email-verification.ts → contacts)
-//   qualification/:
-//     - qualified     (company-qualification.ts → companies)
-//
-// The 'pending' state is the W2 backfill default (coalesce(stage, 'pending')).
-// It is valid in any stage and represents "not yet processed by a workflow step".
-// ============================================================================
-
-/** One state within a stage — minimal shape: key + display label. */
-export interface StatefulStateDefinition {
-  /** Matches state_key values written by workflow steps. */
-  stateKey: string
-  label: string
-}
-
-/** One stage within a pipeline — has a stage_key and an ordered list of valid states. */
-export interface StatefulStageDefinition {
-  /** Matches stage_key values written by workflow steps. */
-  stageKey: string
-  label: string
-  /** UI color token. Consumers may map this to their design system. */
-  color?: string
-  states: StatefulStateDefinition[]
-}
-
-/**
- * Pipeline definition for a single entity participating in the Stateful trait.
- * Parallel to acq_deals' pipeline_key concept but structured for lead-gen entities.
- */
-export interface StatefulPipelineDefinition {
-  /** Matches pipeline_key values in the database (e.g. 'lead-gen'). */
-  pipelineKey: string
-  label: string
-  /** Entity this pipeline applies to (e.g. 'acq.list', 'acq.list-member', 'acq.list-company'). */
-  entityKey: string
-  stages: StatefulStageDefinition[]
-}
-
-export type CrmPriorityBucketKey = 'needs_response' | 'follow_up_due' | 'waiting' | 'stale' | 'closed_low'
-
-export interface CrmPriorityBucketDefinition {
-  bucketKey: CrmPriorityBucketKey
-  label: string
-  /** Lower ranks sort first in deal lists and pipeline columns. */
-  rank: number
-  /** UI color token. Consumers may map this to their design system. */
-  color: string
-}
-
-export interface CrmPriorityRuleConfig {
-  buckets: CrmPriorityBucketDefinition[]
-  closedStageKeys: string[]
-  followUpAfterDaysByStateKey: Record<string, number>
-  staleAfterDays: number
-}
-
-/**
- * Find a pipeline definition by pipeline_key within an array of definitions.
- * Preferred over direct array indexing since the model is array-based (not keyed).
- */
-export function findPipeline(
-  definitions: StatefulPipelineDefinition[],
-  pipelineKey: string
-): StatefulPipelineDefinition | undefined {
-  return definitions.find((def) => def.pipelineKey === pipelineKey)
-}
-
-/**
- * Returns the valid states for a given stage within a pipeline definition.
- * Returns an empty array if the stage is not found.
- */
-export function getValidStatesForStage(
-  definition: StatefulPipelineDefinition,
-  stageKey: string
-): StatefulStateDefinition[] {
-  return definition.stages.find((s) => s.stageKey === stageKey)?.states ?? []
-}
-
-// ============================================================================
-// CRM Stateful Pipeline Definition
-//
-// Defines the (pipeline_key, stage_key, state_key) vocabulary for crm.deal
-// entities. Stage keys match DEFAULT_ORGANIZATION_MODEL_SALES.pipelines[0].stages.
-//
-// State vocabularies sourced from the CRM action/handler tree:
-//   interested/:
-//     - discovery_replied     (instantly-reply-handler.ts → first/subsequent reply)
-//     - discovery_link_sent   (crm-send-booking-link.ts, crm-rebook.ts → booking link sent)
-//     - discovery_nudging     (crm-send-nudge.ts → nudge sent after link)
-//     - discovery_booking_cancelled (booking-revert.ts → Cal cancellation webhook)
-//     - reply_sent            (crm-send-reply.ts → operator reply sent)
-//     - followup_1_sent       (crm-reply-followup.ts day=3)
-//     - followup_2_sent       (crm-reply-followup.ts day=5)
-//     - followup_3_sent       (crm-reply-followup.ts day=7)
-//   proposal, closing, closed_won, closed_lost, nurturing: no observed sub-states
-// ============================================================================
-
-export const CRM_DISCOVERY_REPLIED_STATE: StatefulStateDefinition = {
-  stateKey: 'discovery_replied',
-  label: 'Discovery Replied'
-}
-export const CRM_DISCOVERY_LINK_SENT_STATE: StatefulStateDefinition = {
-  stateKey: 'discovery_link_sent',
-  label: 'Discovery Link Sent'
-}
-export const CRM_DISCOVERY_NUDGING_STATE: StatefulStateDefinition = {
-  stateKey: 'discovery_nudging',
-  label: 'Discovery Nudging'
-}
-export const CRM_DISCOVERY_BOOKING_CANCELLED_STATE: StatefulStateDefinition = {
-  stateKey: 'discovery_booking_cancelled',
-  label: 'Discovery Booking Cancelled'
-}
-export const CRM_REPLY_SENT_STATE: StatefulStateDefinition = {
-  stateKey: 'reply_sent',
-  label: 'Reply Sent'
-}
-export const CRM_FOLLOWUP_1_SENT_STATE: StatefulStateDefinition = {
-  stateKey: 'followup_1_sent',
-  label: 'Follow-up 1 Sent'
-}
-export const CRM_FOLLOWUP_2_SENT_STATE: StatefulStateDefinition = {
-  stateKey: 'followup_2_sent',
-  label: 'Follow-up 2 Sent'
-}
-export const CRM_FOLLOWUP_3_SENT_STATE: StatefulStateDefinition = {
-  stateKey: 'followup_3_sent',
-  label: 'Follow-up 3 Sent'
-}
-
-export const CRM_PIPELINE_DEFINITION: StatefulPipelineDefinition = {
-  pipelineKey: 'crm',
-  label: 'CRM',
-  entityKey: 'crm.deal',
-  stages: [
-    {
-      stageKey: 'interested',
-      label: 'Interested',
-      color: 'blue',
-      states: [
-        CRM_DISCOVERY_REPLIED_STATE,
-        CRM_DISCOVERY_LINK_SENT_STATE,
-        CRM_DISCOVERY_NUDGING_STATE,
-        CRM_DISCOVERY_BOOKING_CANCELLED_STATE,
-        CRM_REPLY_SENT_STATE,
-        CRM_FOLLOWUP_1_SENT_STATE,
-        CRM_FOLLOWUP_2_SENT_STATE,
-        CRM_FOLLOWUP_3_SENT_STATE
-      ]
-    },
-    { stageKey: 'proposal', label: 'Proposal', color: 'yellow', states: [] },
-    { stageKey: 'closing', label: 'Closing', color: 'orange', states: [] },
-    { stageKey: 'closed_won', label: 'Closed Won', color: 'green', states: [] },
-    { stageKey: 'closed_lost', label: 'Closed Lost', color: 'red', states: [] },
-    { stageKey: 'nurturing', label: 'Nurturing', color: 'grape', states: [] }
-  ]
-}
-
-export const CRM_PRIORITY_BUCKETS: CrmPriorityBucketDefinition[] = [
-  { bucketKey: 'needs_response', label: 'Needs Response', rank: 10, color: 'red' },
-  { bucketKey: 'follow_up_due', label: 'Follow-up Due', rank: 20, color: 'orange' },
-  { bucketKey: 'waiting', label: 'Waiting', rank: 30, color: 'blue' },
-  { bucketKey: 'stale', label: 'Stale', rank: 40, color: 'gray' },
-  { bucketKey: 'closed_low', label: 'Closed', rank: 50, color: 'dark' }
-]
-
-export const DEFAULT_CRM_PRIORITY_RULE_CONFIG: CrmPriorityRuleConfig = {
-  buckets: CRM_PRIORITY_BUCKETS,
-  closedStageKeys: ['closed_won', 'closed_lost'],
-  followUpAfterDaysByStateKey: {
-    discovery_link_sent: 3,
-    discovery_nudging: 2,
-    reply_sent: 3,
-    followup_1_sent: 3,
-    followup_2_sent: 5,
-    followup_3_sent: 7
-  },
-  staleAfterDays: 14
-}
-
-// ============================================================================
-// CRM Next-Action Rule Config
-//
-// Maps (state_key, ownership) → suggested action key from DEFAULT_CRM_ACTIONS.
-// Per-org overrides live at organizations.config.crm.next_actions; merged at
-// evaluator read time (same pattern as priority). The evaluator returns the
-// action's `key` string, or null for closed deals / unrecognised combinations.
-// ============================================================================
-
-export interface CrmNextActionMapping {
-  /** state_key to match, or '*' for any state. */
-  stateKey: string
-  /** ownership value to match ('us' | 'them'), or '*' for any. */
-  ownership: 'us' | 'them' | '*'
-  /** Action key from DEFAULT_CRM_ACTIONS (or a custom org-defined key). */
-  actionKey: string
-  /**
-   * When true, this mapping only fires if age >= staleAfterDays.
-   * Defaults to false.
-   */
-  requiresStale?: boolean
-}
-
-export interface CrmNextActionRuleConfig {
-  mappings: CrmNextActionMapping[]
-  /** Fallback action key when ownership === 'us' and no explicit mapping matches. */
-  ownershipUsFallback: string
-}
-
-/**
- * Default next-action rule config. Evaluated in order — first match wins.
- *
- * Mapping table (state_key, ownership) → action_key:
- *   (discovery_link_sent, 'them')  → 'send_nudge'  (after staleAfterDays)
- *   (discovery_replied,   'us')    → 'send_reply'
- *   (discovery_nudging,   'them')  → 'send_nudge'
- *   (*,                   'us')    → ownershipUsFallback ('send_reply')
- *
- * Closed deals → null (handled before mapping evaluation).
- */
-export const DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG: CrmNextActionRuleConfig = {
-  mappings: [
-    {
-      stateKey: 'discovery_link_sent',
-      ownership: 'them',
-      actionKey: 'send_nudge',
-      requiresStale: true
-    },
-    {
-      stateKey: 'discovery_replied',
-      ownership: 'us',
-      actionKey: 'send_reply'
-    },
-    {
-      stateKey: 'discovery_nudging',
-      ownership: 'them',
-      actionKey: 'send_nudge'
-    }
-  ],
-  ownershipUsFallback: 'send_reply'
-}
-
-/** Common states that appear across multiple stages. */
-const PENDING_STATE: StatefulStateDefinition = { stateKey: 'pending', label: 'Pending' }
-
-/**
- * Lead-gen pipeline definition for acq_list_members (contacts).
- * Three stages matching the post-restructure sales subdomain tree.
- *
- * Note: members visit outreach and prospecting states depending on which
- * workflow last processed them. stage_key is set per-transition by the workflow.
- */
-export const ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
-  pipelineKey: 'lead-gen',
-  label: 'Lead Generation',
-  entityKey: 'acq.list-member',
-  stages: [
-    {
-      stageKey: 'outreach',
-      label: 'Outreach',
-      states: [
-        PENDING_STATE,
-        { stateKey: 'personalized', label: 'Personalized' },
-        { stateKey: 'uploaded', label: 'Uploaded' },
-        { stateKey: 'interested', label: 'Interested' }
-      ]
-    },
-    {
-      stageKey: 'prospecting',
-      label: 'Prospecting',
-      states: [
-        PENDING_STATE,
-        { stateKey: 'discovered', label: 'Discovered' },
-        { stateKey: 'verified', label: 'Verified' }
-      ]
-    },
-    {
-      stageKey: 'qualification',
-      label: 'Qualification',
-      states: [PENDING_STATE]
-    }
-  ]
-}
-
-/**
- * Lead-gen pipeline definition for acq_list_companies.
- * Three stages matching the post-restructure sales subdomain tree.
- *
- * Note: companies visit prospecting and qualification states depending on which
- * workflow last processed them. stage_key is set per-transition by the workflow.
- */
-export const ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
-  pipelineKey: 'lead-gen',
-  label: 'Lead Generation',
-  entityKey: 'acq.list-company',
-  stages: [
-    {
-      stageKey: 'outreach',
-      label: 'Outreach',
-      states: [PENDING_STATE, { stateKey: 'uploaded', label: 'Uploaded' }]
-    },
-    {
-      stageKey: 'prospecting',
-      label: 'Prospecting',
-      states: [
-        PENDING_STATE,
-        { stateKey: 'populated', label: 'Populated' },
-        { stateKey: 'extracted', label: 'Extracted' }
-      ]
-    },
-    {
-      stageKey: 'qualification',
-      label: 'Qualification',
-      states: [PENDING_STATE, { stateKey: 'qualified', label: 'Qualified' }]
-    }
-  ]
-}
-
-/**
- * All lead-gen pipeline definitions indexed by entity key.
- * Use findPipeline() to locate a definition by pipeline_key within any of these arrays.
- */
-export const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefinition[]> = {
-  'acq.list-member': [ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE],
-  'acq.list-company': [ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE]
-}
-
-// ============================================================================
-// Lead-Gen Stage Catalog (OM Spine processing-state model)
-//
-// Canonical set of processing stage keys for acq_companies.processing_state and
-// acq_contacts.processing_state. These keys coordinate build templates, workflow
-// factory validation, API filters, and UI progress projections.
-//
-// State is sparse: absent keys mean "not attempted"; present keys hold terminal
-// status entries such as success, no_result, skipped, or error.
-//
-// Historical sources:
-//   ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE  → personalized, uploaded, interested,
-//                                          discovered, verified
-//   ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE → populated, extracted, qualified
-//   Design plan hint (lead-gen-domain-cleanup.mdx §4) → scraped, enriched
-//
-// ============================================================================
-
-/** One entry in the lead-gen stage catalog. */
-export interface LeadGenStageCatalogEntry {
-  /** Matches the status key written into processing_state jsonb (e.g. 'scraped'). */
-  key: string
-  /** Human-readable label for UI display. */
-  label: string
-  /** Short description of what this stage represents. */
-  description: string
-  /** Canonical pipeline order for UI sorting. Lower = earlier in the funnel. */
-  order: number
-  /** Which entity's processing_state jsonb carries this stage status. */
-  entity: 'company' | 'contact'
-  /** Additional entities allowed to write/read this processing_state key. */
-  additionalEntities?: Array<'company' | 'contact'>
-  /**
-   * Optional read-side override for Records views when a company-scoped step
-   * produces records on a different entity.
-   */
-  recordEntity?: 'company' | 'contact'
-  /** Stage key to read from recordEntity.processing_state for Records views. */
-  recordStageKey?: string
-}
-
-/**
- * Canonical lead-gen processing stage catalog.
- * Keys are the stage names written by workflow steps into processing_state jsonb.
- *
- * Ordered roughly by pipeline progression (prospecting → outreach → qualification).
- */
-export const LEAD_GEN_STAGE_CATALOG: Record<string, LeadGenStageCatalogEntry> = {
-  // Prospecting — company population
-  scraped: {
-    key: 'scraped',
-    label: 'Scraped',
-    description: 'Company was scraped from a source directory (Apify actor run).',
-    order: 1,
-    entity: 'company'
-  },
-  populated: {
-    key: 'populated',
-    label: 'Companies found',
-    description: 'Companies have been found and added to the lead-gen list.',
-    order: 2,
-    entity: 'company'
-  },
-  crawled: {
-    key: 'crawled',
-    label: 'Websites crawled',
-    description:
-      'Company websites have been crawled (e.g. via Apify) and raw page content stored for downstream LLM analysis.',
-    order: 2.5,
-    entity: 'company'
-  },
-  extracted: {
-    key: 'extracted',
-    label: 'Websites analyzed',
-    description: 'Company websites have been analyzed for business signals.',
-    order: 3,
-    entity: 'company'
-  },
-  enriched: {
-    key: 'enriched',
-    label: 'Enriched',
-    description: 'Company or contact enriched with third-party data (e.g. Tomba, Anymailfinder).',
-    order: 4,
-    entity: 'company'
-  },
-  'decision-makers-enriched': {
-    key: 'decision-makers-enriched',
-    label: 'Decision-makers found',
-    description: 'Decision-maker contacts discovered and attached to a qualified company.',
-    order: 6,
-    entity: 'company',
-    recordEntity: 'contact',
-    recordStageKey: 'discovered'
-  },
-
-  // Prospecting — contact discovery
-  discovered: {
-    key: 'discovered',
-    label: 'Decision-makers found',
-    description: 'Decision-maker contact details have been found.',
-    order: 5,
-    entity: 'contact'
-  },
-  verified: {
-    key: 'verified',
-    label: 'Emails verified',
-    description: 'Contact email addresses have been checked for deliverability.',
-    order: 7,
-    entity: 'contact'
-  },
-
-  // Qualification
-  qualified: {
-    key: 'qualified',
-    label: 'Companies qualified',
-    description: 'Companies have been scored against the qualification criteria.',
-    order: 8,
-    entity: 'company'
-  },
-
-  // Outreach
-  personalized: {
-    key: 'personalized',
-    label: 'Personalized',
-    description: 'Outreach message personalized for the contact (Instantly personalization workflow).',
-    order: 9,
-    entity: 'contact'
-  },
-  uploaded: {
-    key: 'uploaded',
-    label: 'Reviewed and exported',
-    description: 'Approved records have been reviewed and exported for handoff.',
-    order: 10,
-    entity: 'company',
-    additionalEntities: ['contact']
-  },
-  interested: {
-    key: 'interested',
-    label: 'Interested',
-    description: 'Contact replied with a positive signal (Instantly reply-handler transition).',
-    order: 11,
-    entity: 'contact'
-  }
-}
+import { z } from 'zod'
+import { DescriptionSchema, DisplayMetadataSchema, ModelIdSchema, ReferenceIdsSchema } from './shared'
+
+export { LEAD_GEN_STAGE_CATALOG, type LeadGenStageCatalogEntry } from '../catalogs/lead-gen'
+
+// Phase 4 cut: OrganizationModelSalesSchema and DEFAULT_ORGANIZATION_MODEL_SALES removed.
+// Pipeline/stage data moved into system.content as (schema:pipeline) and (schema:stage)
+// content nodes on the owning system (e.g. sales.crm). Use getAllPipelines() /
+// getStagesInPipeline() from migration-helpers to read pipeline data portably.
+//
+// SalesStageSemanticClassSchema, SalesStageSchema, SalesPipelineSchema are retained
+// below as TypeScript types used by CRM business logic and the Stateful pipeline definitions.
+
+export const SalesStageSemanticClassSchema = z.enum(['open', 'active', 'nurturing', 'closed_won', 'closed_lost'])
+
+export const SalesStageSchema = DisplayMetadataSchema.extend({
+  id: ModelIdSchema,
+  order: z.number().int().min(0),
+  semanticClass: SalesStageSemanticClassSchema,
+  surfaceIds: ReferenceIdsSchema,
+  resourceIds: ReferenceIdsSchema
+})
+
+export const SalesPipelineSchema = z.object({
+  id: ModelIdSchema,
+  label: z.string().trim().min(1).max(120),
+  description: DescriptionSchema.optional(),
+  entityId: ModelIdSchema,
+  stages: z.array(SalesStageSchema).min(1)
+})
+
+// ============================================================================
+// Lead-Gen Stateful Pipeline Definitions (Decision N8, Wave 4)
+//
+// Defines the (pipeline_key, stage_key, state_key) vocabulary for the three
+// entities that carry the Stateful trait via Track B:
+//   - acq_lists         (pipeline_key='lead-gen', stage_key='lifecycle')
+//   - acq_list_members  (pipeline_key='lead-gen', stages: outreach / prospecting / qualification)
+//   - acq_list_companies (pipeline_key='lead-gen', stages: outreach / prospecting / qualification)
+//
+// DB columns (pipeline_key, stage_key, state_key) remain free-form text with no
+// CHECK constraint — new states can be introduced without a migration (Decision N8).
+// These definitions are the org-specific source of truth consumed by UI and tooling.
+//
+// State vocabularies sourced from the post-restructure sales tree (W3 canonical):
+//   outreach/:
+//     - personalized  (instantly-personalization.ts → contacts)
+//     - uploaded      (instantly-upload.ts → contacts)
+//     - interested    (instantly-reply-handler.ts → contacts, initial reply transition)
+//   prospecting/:
+//     - populated     (apify-acquire.ts, apify-scrape.ts → companies)
+//     - crawled       (apify-website-crawl.ts → companies)
+//     - extracted     (website-extract.ts → companies)
+//     - discovered    (email-discovery.ts, anymailfinder-enrich.ts → contacts)
+//     - verified      (email-verification.ts → contacts)
+//   qualification/:
+//     - qualified     (company-qualification.ts → companies)
+//
+// The 'pending' state is the W2 backfill default (coalesce(stage, 'pending')).
+// It is valid in any stage and represents "not yet processed by a workflow step".
+// ============================================================================
+
+/** One state within a stage — minimal shape: key + display label. */
+export interface StatefulStateDefinition {
+  /** Matches state_key values written by workflow steps. */
+  stateKey: string
+  label: string
+}
+
+/** One stage within a pipeline — has a stage_key and an ordered list of valid states. */
+export interface StatefulStageDefinition {
+  /** Matches stage_key values written by workflow steps. */
+  stageKey: string
+  label: string
+  /** UI color token. Consumers may map this to their design system. */
+  color?: string
+  states: StatefulStateDefinition[]
+}
+
+/**
+ * Pipeline definition for a single entity participating in the Stateful trait.
+ * Parallel to acq_deals' pipeline_key concept but structured for lead-gen entities.
+ */
+export interface StatefulPipelineDefinition {
+  /** Matches pipeline_key values in the database (e.g. 'lead-gen'). */
+  pipelineKey: string
+  label: string
+  /** Entity this pipeline applies to (e.g. 'acq.list', 'acq.list-member', 'acq.list-company'). */
+  entityKey: string
+  stages: StatefulStageDefinition[]
+}
+
+export type CrmPriorityBucketKey = 'needs_response' | 'follow_up_due' | 'waiting' | 'stale' | 'closed_low'
+
+export interface CrmPriorityBucketDefinition {
+  bucketKey: CrmPriorityBucketKey
+  label: string
+  /** Lower ranks sort first in deal lists and pipeline columns. */
+  rank: number
+  /** UI color token. Consumers may map this to their design system. */
+  color: string
+}
+
+export interface CrmPriorityRuleConfig {
+  buckets: CrmPriorityBucketDefinition[]
+  closedStageKeys: string[]
+  followUpAfterDaysByStateKey: Record<string, number>
+  staleAfterDays: number
+}
+
+/**
+ * Find a pipeline definition by pipeline_key within an array of definitions.
+ * Preferred over direct array indexing since the model is array-based (not keyed).
+ */
+export function findPipeline(
+  definitions: StatefulPipelineDefinition[],
+  pipelineKey: string
+): StatefulPipelineDefinition | undefined {
+  return definitions.find((def) => def.pipelineKey === pipelineKey)
+}
+
+/**
+ * Returns the valid states for a given stage within a pipeline definition.
+ * Returns an empty array if the stage is not found.
+ */
+export function getValidStatesForStage(
+  definition: StatefulPipelineDefinition,
+  stageKey: string
+): StatefulStateDefinition[] {
+  return definition.stages.find((s) => s.stageKey === stageKey)?.states ?? []
+}
+
+// ============================================================================
+// CRM Stateful Pipeline Definition
+//
+// Defines the (pipeline_key, stage_key, state_key) vocabulary for crm.deal
+// entities. Stage keys match DEFAULT_ORGANIZATION_MODEL_SALES.pipelines[0].stages.
+//
+// State vocabularies sourced from the CRM action/handler tree:
+//   interested/:
+//     - discovery_replied     (instantly-reply-handler.ts → first/subsequent reply)
+//     - discovery_link_sent   (crm-send-booking-link.ts, crm-rebook.ts → booking link sent)
+//     - discovery_nudging     (crm-send-nudge.ts → nudge sent after link)
+//     - discovery_booking_cancelled (booking-revert.ts → Cal cancellation webhook)
+//     - reply_sent            (crm-send-reply.ts → operator reply sent)
+//     - followup_1_sent       (crm-reply-followup.ts day=3)
+//     - followup_2_sent       (crm-reply-followup.ts day=5)
+//     - followup_3_sent       (crm-reply-followup.ts day=7)
+//   proposal, closing, closed_won, closed_lost, nurturing: no observed sub-states
+// ============================================================================
+
+export const CRM_DISCOVERY_REPLIED_STATE: StatefulStateDefinition = {
+  stateKey: 'discovery_replied',
+  label: 'Discovery Replied'
+}
+export const CRM_DISCOVERY_LINK_SENT_STATE: StatefulStateDefinition = {
+  stateKey: 'discovery_link_sent',
+  label: 'Discovery Link Sent'
+}
+export const CRM_DISCOVERY_NUDGING_STATE: StatefulStateDefinition = {
+  stateKey: 'discovery_nudging',
+  label: 'Discovery Nudging'
+}
+export const CRM_DISCOVERY_BOOKING_CANCELLED_STATE: StatefulStateDefinition = {
+  stateKey: 'discovery_booking_cancelled',
+  label: 'Discovery Booking Cancelled'
+}
+export const CRM_REPLY_SENT_STATE: StatefulStateDefinition = {
+  stateKey: 'reply_sent',
+  label: 'Reply Sent'
+}
+export const CRM_FOLLOWUP_1_SENT_STATE: StatefulStateDefinition = {
+  stateKey: 'followup_1_sent',
+  label: 'Follow-up 1 Sent'
+}
+export const CRM_FOLLOWUP_2_SENT_STATE: StatefulStateDefinition = {
+  stateKey: 'followup_2_sent',
+  label: 'Follow-up 2 Sent'
+}
+export const CRM_FOLLOWUP_3_SENT_STATE: StatefulStateDefinition = {
+  stateKey: 'followup_3_sent',
+  label: 'Follow-up 3 Sent'
+}
+
+export const CRM_PIPELINE_DEFINITION: StatefulPipelineDefinition = {
+  pipelineKey: 'crm',
+  label: 'CRM',
+  entityKey: 'crm.deal',
+  stages: [
+    {
+      stageKey: 'interested',
+      label: 'Interested',
+      color: 'blue',
+      states: [
+        CRM_DISCOVERY_REPLIED_STATE,
+        CRM_DISCOVERY_LINK_SENT_STATE,
+        CRM_DISCOVERY_NUDGING_STATE,
+        CRM_DISCOVERY_BOOKING_CANCELLED_STATE,
+        CRM_REPLY_SENT_STATE,
+        CRM_FOLLOWUP_1_SENT_STATE,
+        CRM_FOLLOWUP_2_SENT_STATE,
+        CRM_FOLLOWUP_3_SENT_STATE
+      ]
+    },
+    { stageKey: 'proposal', label: 'Proposal', color: 'yellow', states: [] },
+    { stageKey: 'closing', label: 'Closing', color: 'orange', states: [] },
+    { stageKey: 'closed_won', label: 'Closed Won', color: 'green', states: [] },
+    { stageKey: 'closed_lost', label: 'Closed Lost', color: 'red', states: [] },
+    { stageKey: 'nurturing', label: 'Nurturing', color: 'grape', states: [] }
+  ]
+}
+
+export const CRM_PRIORITY_BUCKETS: CrmPriorityBucketDefinition[] = [
+  { bucketKey: 'needs_response', label: 'Needs Response', rank: 10, color: 'red' },
+  { bucketKey: 'follow_up_due', label: 'Follow-up Due', rank: 20, color: 'orange' },
+  { bucketKey: 'waiting', label: 'Waiting', rank: 30, color: 'blue' },
+  { bucketKey: 'stale', label: 'Stale', rank: 40, color: 'gray' },
+  { bucketKey: 'closed_low', label: 'Closed', rank: 50, color: 'dark' }
+]
+
+export const DEFAULT_CRM_PRIORITY_RULE_CONFIG: CrmPriorityRuleConfig = {
+  buckets: CRM_PRIORITY_BUCKETS,
+  closedStageKeys: ['closed_won', 'closed_lost'],
+  followUpAfterDaysByStateKey: {
+    discovery_link_sent: 3,
+    discovery_nudging: 2,
+    reply_sent: 3,
+    followup_1_sent: 3,
+    followup_2_sent: 5,
+    followup_3_sent: 7
+  },
+  staleAfterDays: 14
+}
+
+// ============================================================================
+// CRM Next-Action Rule Config
+//
+// Maps (state_key, ownership) → suggested action key from DEFAULT_CRM_ACTIONS.
+// Per-org overrides live at organizations.config.crm.next_actions; merged at
+// evaluator read time (same pattern as priority). The evaluator returns the
+// action's `key` string, or null for closed deals / unrecognised combinations.
+// ============================================================================
+
+export interface CrmNextActionMapping {
+  /** state_key to match, or '*' for any state. */
+  stateKey: string
+  /** ownership value to match ('us' | 'them'), or '*' for any. */
+  ownership: 'us' | 'them' | '*'
+  /** Action key from DEFAULT_CRM_ACTIONS (or a custom org-defined key). */
+  actionKey: string
+  /**
+   * When true, this mapping only fires if age >= staleAfterDays.
+   * Defaults to false.
+   */
+  requiresStale?: boolean
+}
+
+export interface CrmNextActionRuleConfig {
+  mappings: CrmNextActionMapping[]
+  /** Fallback action key when ownership === 'us' and no explicit mapping matches. */
+  ownershipUsFallback: string
+}
+
+/**
+ * Default next-action rule config. Evaluated in order — first match wins.
+ *
+ * Mapping table (state_key, ownership) → action_key:
+ *   (discovery_link_sent, 'them')  → 'send_nudge'  (after staleAfterDays)
+ *   (discovery_replied,   'us')    → 'send_reply'
+ *   (discovery_nudging,   'them')  → 'send_nudge'
+ *   (*,                   'us')    → ownershipUsFallback ('send_reply')
+ *
+ * Closed deals → null (handled before mapping evaluation).
+ */
+export const DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG: CrmNextActionRuleConfig = {
+  mappings: [
+    {
+      stateKey: 'discovery_link_sent',
+      ownership: 'them',
+      actionKey: 'send_nudge',
+      requiresStale: true
+    },
+    {
+      stateKey: 'discovery_replied',
+      ownership: 'us',
+      actionKey: 'send_reply'
+    },
+    {
+      stateKey: 'discovery_nudging',
+      ownership: 'them',
+      actionKey: 'send_nudge'
+    }
+  ],
+  ownershipUsFallback: 'send_reply'
+}
+
+/** Common states that appear across multiple stages. */
+const PENDING_STATE: StatefulStateDefinition = { stateKey: 'pending', label: 'Pending' }
+
+/**
+ * Lead-gen pipeline definition for acq_list_members (contacts).
+ * Three stages matching the post-restructure sales subdomain tree.
+ *
+ * Note: members visit outreach and prospecting states depending on which
+ * workflow last processed them. stage_key is set per-transition by the workflow.
+ */
+export const ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
+  pipelineKey: 'lead-gen',
+  label: 'Lead Generation',
+  entityKey: 'acq.list-member',
+  stages: [
+    {
+      stageKey: 'outreach',
+      label: 'Outreach',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'personalized', label: 'Personalized' },
+        { stateKey: 'uploaded', label: 'Uploaded' },
+        { stateKey: 'interested', label: 'Interested' }
+      ]
+    },
+    {
+      stageKey: 'prospecting',
+      label: 'Prospecting',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'discovered', label: 'Discovered' },
+        { stateKey: 'verified', label: 'Verified' }
+      ]
+    },
+    {
+      stageKey: 'qualification',
+      label: 'Qualification',
+      states: [PENDING_STATE]
+    }
+  ]
+}
+
+/**
+ * Lead-gen pipeline definition for acq_list_companies.
+ * Three stages matching the post-restructure sales subdomain tree.
+ *
+ * Note: companies visit prospecting and qualification states depending on which
+ * workflow last processed them. stage_key is set per-transition by the workflow.
+ */
+export const ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
+  pipelineKey: 'lead-gen',
+  label: 'Lead Generation',
+  entityKey: 'acq.list-company',
+  stages: [
+    {
+      stageKey: 'outreach',
+      label: 'Outreach',
+      states: [PENDING_STATE, { stateKey: 'uploaded', label: 'Uploaded' }]
+    },
+    {
+      stageKey: 'prospecting',
+      label: 'Prospecting',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'populated', label: 'Populated' },
+        { stateKey: 'extracted', label: 'Extracted' }
+      ]
+    },
+    {
+      stageKey: 'qualification',
+      label: 'Qualification',
+      states: [PENDING_STATE, { stateKey: 'qualified', label: 'Qualified' }]
+    }
+  ]
+}
+
+/**
+ * All lead-gen pipeline definitions indexed by entity key.
+ * Use findPipeline() to locate a definition by pipeline_key within any of these arrays.
+ */
+export const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefinition[]> = {
+  'acq.list-member': [ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE],
+  'acq.list-company': [ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE]
+}