@elevasis/core 0.13.0 → 0.14.0

package/src/execution/engine/workflow/types.ts

@@ -82,6 +82,17 @@ export interface WorkflowDefinition {
    * If provided, workflow appears in Execution Runner UI
    */
   interface?: ExecutionInterface
+
+  /**
+   * Lead-gen processing stage this workflow implements (optional).
+   * Must match a key in the platform lead-gen stage catalog.
+   * Used by org-os graph derivation to surface workflow→stage edges and
+   * by pipeline_config validation to confirm each catalog stage has an
+   * implementing workflow before a list is activated.
+   *
+   * Example: stageImplemented: 'verified' on the email-verification workflow.
+   */
+  stageImplemented?: string
 }
 
 /**

package/src/organization-model/contracts.ts

@@ -9,7 +9,7 @@ export const MONITORING_FEATURE_ID = 'monitoring' as const
 export const SETTINGS_FEATURE_ID = 'settings' as const
 export const SEO_FEATURE_ID = 'seo' as const
 
-export const SALES_PIPELINE_SURFACE_ID = 'crm.pipeline' as const
-export const PROSPECTING_LISTS_SURFACE_ID = 'lead-gen.lists' as const
-export const OPERATIONS_COMMAND_VIEW_SURFACE_ID = 'operations.command-view' as const
-export const SETTINGS_ROLES_SURFACE_ID = 'settings.roles' as const
+export const SALES_PIPELINE_SURFACE_ID = 'crm.pipeline' as const
+export const PROSPECTING_LISTS_SURFACE_ID = 'lead-gen.lists' as const
+export const OPERATIONS_COMMAND_VIEW_SURFACE_ID = 'operations.command-view' as const
+export const SETTINGS_ROLES_SURFACE_ID = 'settings.roles' as const

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

@@ -1,11 +1,11 @@
 import { z } from 'zod'
-import {
-  OPERATIONS_COMMAND_VIEW_SURFACE_ID,
-  PROJECTS_VIEW_CAPABILITY_ID,
-  PROJECTS_FEATURE_ID,
-  PROJECTS_INDEX_SURFACE_ID,
-  SETTINGS_ROLES_SURFACE_ID
-} from '../contracts'
+import {
+  OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+  PROJECTS_VIEW_CAPABILITY_ID,
+  PROJECTS_FEATURE_ID,
+  PROJECTS_INDEX_SURFACE_ID,
+  SETTINGS_ROLES_SURFACE_ID
+} from '../contracts'
 import { DescriptionSchema, IconNameSchema, LabelSchema, ModelIdSchema, PathSchema, ReferenceIdsSchema } from './shared'
 
 export const SurfaceTypeSchema = z.enum(['page', 'dashboard', 'graph', 'detail', 'list', 'settings'])
@@ -15,10 +15,10 @@ export const SurfaceDefinitionSchema = z.object({
   label: LabelSchema,
   path: PathSchema,
   surfaceType: SurfaceTypeSchema,
-  description: DescriptionSchema.optional(),
-  enabled: z.boolean().default(true),
-  devOnly: z.boolean().optional(),
-  icon: IconNameSchema.optional(),
+  description: DescriptionSchema.optional(),
+  enabled: z.boolean().default(true),
+  devOnly: z.boolean().optional(),
+  icon: IconNameSchema.optional(),
   featureId: ModelIdSchema.optional(),
   featureIds: ReferenceIdsSchema,
   entityIds: ReferenceIdsSchema,
@@ -92,16 +92,16 @@ export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationM
       resourceIds: [],
       capabilityIds: [PROJECTS_VIEW_CAPABILITY_ID]
     },
-    {
-      id: OPERATIONS_COMMAND_VIEW_SURFACE_ID,
-      label: 'Command View',
-      path: '/operations/command-view',
-      surfaceType: 'graph',
-      enabled: true,
-      devOnly: true,
-      featureId: 'operations',
-      featureIds: ['operations'],
-      entityIds: [],
+    {
+      id: OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+      label: 'Command View',
+      path: '/operations/command-view',
+      surfaceType: 'graph',
+      enabled: true,
+      devOnly: true,
+      featureId: 'operations',
+      featureIds: ['operations'],
+      entityIds: [],
       resourceIds: [],
       capabilityIds: ['operations.command-view']
     },
@@ -261,45 +261,45 @@ export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationM
       resourceIds: [],
       capabilityIds: []
     },
-    {
-      id: 'settings.appearance',
-      label: 'Appearance',
-      path: '/settings/appearance',
+    {
+      id: 'settings.appearance',
+      label: 'Appearance',
+      path: '/settings/appearance',
+      surfaceType: 'settings',
+      enabled: true,
+      featureId: 'settings',
+      featureIds: ['settings'],
+      entityIds: [],
+      resourceIds: [],
+      capabilityIds: []
+    },
+    {
+      id: SETTINGS_ROLES_SURFACE_ID,
+      label: 'My Roles',
+      path: '/settings/roles',
       surfaceType: 'settings',
       enabled: true,
       featureId: 'settings',
       featureIds: ['settings'],
       entityIds: [],
-      resourceIds: [],
-      capabilityIds: []
-    },
-    {
-      id: SETTINGS_ROLES_SURFACE_ID,
-      label: 'My Roles',
-      path: '/settings/roles',
-      surfaceType: 'settings',
-      enabled: true,
-      featureId: 'settings',
-      featureIds: ['settings'],
-      entityIds: [],
-      resourceIds: [],
-      capabilityIds: []
-    },
-    {
-      id: 'settings.organization',
-      label: 'Organization',
-      path: '/settings/organization',
+      resourceIds: [],
+      capabilityIds: []
+    },
+    {
+      id: 'settings.organization',
+      label: 'Organization',
+      path: '/settings/organization',
       surfaceType: 'settings',
       enabled: true,
       featureId: 'settings',
       featureIds: ['settings'],
       entityIds: [],
-      resourceIds: [],
-      capabilityIds: []
-    },
-    {
-      id: 'settings.credentials',
-      label: 'Credentials',
+      resourceIds: [],
+      capabilityIds: []
+    },
+    {
+      id: 'settings.credentials',
+      label: 'Credentials',
       path: '/settings/credentials',
       surfaceType: 'settings',
       enabled: true,
@@ -355,12 +355,12 @@ export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationM
     },
     {
       id: 'primary-operations',
-      label: 'Operations',
-      placement: 'primary',
-      surfaceIds: [
-        OPERATIONS_COMMAND_VIEW_SURFACE_ID,
-        'operations.overview',
-        'operations.resources',
+      label: 'Operations',
+      placement: 'primary',
+      surfaceIds: [
+        OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+        'operations.overview',
+        'operations.resources',
         'operations.command-queue',
         'operations.sessions',
         'operations.task-scheduler'
@@ -385,12 +385,12 @@ export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationM
       label: 'Settings',
       placement: 'bottom',
       surfaceIds: [
-        'settings.account',
-        'settings.appearance',
-        SETTINGS_ROLES_SURFACE_ID,
-        'settings.organization',
-        'settings.credentials',
-        'settings.api-keys',
+        'settings.account',
+        'settings.appearance',
+        SETTINGS_ROLES_SURFACE_ID,
+        'settings.organization',
+        'settings.credentials',
+        'settings.api-keys',
         'settings.webhooks',
         'settings.deployments'
       ]

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

@@ -92,3 +92,275 @@ export const DEFAULT_ORGANIZATION_MODEL_SALES: z.infer<typeof OrganizationModelS
     }
   ]
 }
+
+// ============================================================================
+// 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)
+//     - 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
+  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[]
+}
+
+/**
+ * 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)
+}
+
+/** 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]
+    },
+    {
+      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 (Slice C — flag-based processing model)
+//
+// Canonical set of processing stage keys for the flag-based model that replaces
+// the stateful trait on acq_list_members and acq_list_companies. Each key maps
+// to a flag in the processing_state jsonb column (bare boolean per Decision #7).
+//
+// 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
+//
+// Wave 2 will validate pipeline_config.stages[].key against this catalog at
+// list-create/update time. Each lead-gen workflow in operations will declare
+// stageImplemented: '<key>' in its WorkflowDefinition (Slice D-2).
+// ============================================================================
+
+/** One entry in the lead-gen stage catalog. */
+export interface LeadGenStageCatalogEntry {
+  /** Matches the flag 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 flag. */
+  entity: 'company' | 'contact'
+}
+
+/**
+ * Canonical lead-gen processing stage catalog.
+ * Keys are the flag 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: 'Populated',
+    description: 'Company record populated with structured data from scrape results.',
+    order: 2,
+    entity: 'company'
+  },
+  extracted: {
+    key: 'extracted',
+    label: 'Extracted',
+    description: 'Website content extracted and parsed for company intelligence.',
+    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'
+  },
+
+  // Prospecting — contact discovery
+  discovered: {
+    key: 'discovered',
+    label: 'Discovered',
+    description: 'Contact email address discovered via an email-discovery workflow.',
+    order: 5,
+    entity: 'contact'
+  },
+  verified: {
+    key: 'verified',
+    label: 'Verified',
+    description: 'Contact email address verified as deliverable (email verification workflow).',
+    order: 6,
+    entity: 'contact'
+  },
+
+  // Qualification
+  qualified: {
+    key: 'qualified',
+    label: 'Qualified',
+    description: 'Company passed the ICP qualification rubric (company-qualification workflow).',
+    order: 7,
+    entity: 'company'
+  },
+
+  // Outreach
+  personalized: {
+    key: 'personalized',
+    label: 'Personalized',
+    description: 'Outreach message personalized for the contact (Instantly personalization workflow).',
+    order: 8,
+    entity: 'contact'
+  },
+  uploaded: {
+    key: 'uploaded',
+    label: 'Uploaded',
+    description: 'Contact uploaded to an Instantly campaign for outreach.',
+    order: 9,
+    entity: 'contact'
+  },
+  interested: {
+    key: 'interested',
+    label: 'Interested',
+    description: 'Contact replied with a positive signal (Instantly reply-handler transition).',
+    order: 10,
+    entity: 'contact'
+  }
+}

package/src/organization-model/published.ts

@@ -1,6 +1,6 @@
 export { OrganizationModelSchema } from './schema'
-export { FeatureSchema, NodeIdPathSchema, NodeIdStringSchema, UiPositionSchema } from './domains/features'
-export { LinkSchema } from './graph/link'
+export { FeatureSchema, NodeIdPathSchema, NodeIdStringSchema, UiPositionSchema } from './domains/features'
+export { LinkSchema } from './graph/link'
 export { TechStackEntrySchema } from './domains/shared'
 export {
   PROJECTS_FEATURE_ID,
@@ -11,12 +11,12 @@ export {
   OPERATIONS_FEATURE_ID,
   MONITORING_FEATURE_ID,
   SETTINGS_FEATURE_ID,
-  SEO_FEATURE_ID,
-  SALES_PIPELINE_SURFACE_ID,
-  PROSPECTING_LISTS_SURFACE_ID,
-  OPERATIONS_COMMAND_VIEW_SURFACE_ID,
-  SETTINGS_ROLES_SURFACE_ID
-} from './contracts'
+  SEO_FEATURE_ID,
+  SALES_PIPELINE_SURFACE_ID,
+  PROSPECTING_LISTS_SURFACE_ID,
+  OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+  SETTINGS_ROLES_SURFACE_ID
+} from './contracts'
 export { DEFAULT_ORGANIZATION_MODEL } from './defaults'
 export {
   DEFAULT_ORGANIZATION_MODEL_STATUSES,
@@ -57,25 +57,25 @@ export type {
   OrganizationModelCustomerFirmographics,
   OrganizationModelCustomers,
   OrganizationModelCustomerSegment,
-  OrganizationModelFeature,
-  OrganizationModelGoals,
-  OrganizationModelKeyResult,
-  OrganizationModelObjective,
+  OrganizationModelFeature,
+  OrganizationModelGoals,
+  OrganizationModelKeyResult,
+  OrganizationModelObjective,
   OrganizationModelOfferings,
   OrganizationModelOperationEntry,
   OrganizationModelOperationSemanticClass,
   OrganizationModelOperations,
-  OrganizationModelPricingModel,
-  OrganizationModelProduct,
-  OrganizationModelRole,
+  OrganizationModelPricingModel,
+  OrganizationModelProduct,
+  OrganizationModelRole,
   OrganizationModelTechStackEntry,
   OrganizationModelRoles,
-  OrganizationModelStatuses,
-  OrganizationModelStatusEntry,
-  OrganizationModelStatusSemanticClass,
-  NodeIdPath,
-  NodeIdString
-} from './types'
+  OrganizationModelStatuses,
+  OrganizationModelStatusEntry,
+  OrganizationModelStatusSemanticClass,
+  NodeIdPath,
+  NodeIdString
+} from './types'
 
 export type {
   FoundationBranding,

package/src/organization-model/resolve.ts

@@ -31,11 +31,24 @@ function deepMerge<T>(base: T, override: DeepPartial<T> | undefined): T {
   return result as T
 }
 
-export function defineOrganizationModel<T extends DeepPartial<OrganizationModel>>(model: T): T {
-  return model
-}
-
-export function resolveOrganizationModel(override?: DeepPartial<OrganizationModel>): OrganizationModel {
-  const merged = deepMerge(DEFAULT_ORGANIZATION_MODEL, override)
-  return OrganizationModelSchema.parse(merged)
-}
+export function defineOrganizationModel<T extends DeepPartial<OrganizationModel>>(model: T): T {
+  return model
+}
+
+export function resolveOrganizationModel(
+  override?: DeepPartial<OrganizationModel>,
+  organizationId?: string
+): OrganizationModel {
+  const merged = deepMerge(DEFAULT_ORGANIZATION_MODEL, override)
+  const model = OrganizationModelSchema.parse(merged)
+
+  if (!model.sales?.pipelines || model.sales.pipelines.length === 0) {
+    const orgLabel = organizationId ? `Organization ${organizationId}` : 'Organization'
+    throw new Error(
+      `${orgLabel} has no sales pipeline configuration. ` +
+        `This indicates an incomplete provisioning state. Run org provisioning to seed defaults.`
+    )
+  }
+
+  return model
+}

package/src/platform/constants/versions.ts

@@ -1,3 +1,3 @@
 export const VERSION = {
-  CURRENT: '1.6.17'
+  CURRENT: '1.7.0'
 }