@elevasis/core 0.23.0 → 0.24.0

package/src/business/acquisition/ontology-validation.ts

@@ -0,0 +1,309 @@
+import { DEFAULT_ORGANIZATION_MODEL } from '../../organization-model/defaults'
+import {
+  compileOrganizationOntology,
+  formatOntologyId,
+  type OntologyActionType,
+  type OntologyCatalogType,
+  type OntologyId,
+  type OntologyScope,
+  type ResolvedOntologyIndex
+} from '../../organization-model/ontology'
+import type { OrganizationModel } from '../../organization-model/types'
+import {
+  CRM_PIPELINE_DEFINITION,
+  LEAD_GEN_STAGE_CATALOG,
+  type LeadGenStageCatalogEntry,
+  type StatefulStateDefinition
+} from '../../organization-model/domains/sales'
+
+export const CRM_PIPELINE_CATALOG_ONTOLOGY_ID = formatOntologyId({
+  scope: 'sales.crm',
+  kind: 'catalog',
+  localId: 'crm.pipeline'
+})
+
+export const LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID = formatOntologyId({
+  scope: 'sales.lead-gen',
+  kind: 'catalog',
+  localId: 'lead-gen.stage-catalog'
+})
+
+const CRM_DEAL_OBJECT_ONTOLOGY_ID = formatOntologyId({
+  scope: 'sales.crm',
+  kind: 'object',
+  localId: 'crm.deal'
+})
+
+type CrmCatalogStageEntry = {
+  key: string
+  label: string
+  order: number
+  color?: string
+  states: StatefulStateDefinition[]
+}
+
+export type BusinessOntologyValidationIndex = {
+  ontology: ResolvedOntologyIndex
+  crmPipelineCatalog: OntologyCatalogType
+  leadGenStageCatalog: OntologyCatalogType
+  actionTypesByLegacyId: Record<string, OntologyActionType>
+}
+
+function createCrmPipelineCatalog(): OntologyCatalogType {
+  return {
+    id: CRM_PIPELINE_CATALOG_ONTOLOGY_ID,
+    label: CRM_PIPELINE_DEFINITION.label,
+    ownerSystemId: 'sales.crm',
+    kind: 'pipeline',
+    appliesTo: CRM_DEAL_OBJECT_ONTOLOGY_ID,
+    entries: Object.fromEntries(
+      CRM_PIPELINE_DEFINITION.stages.map((stage, index) => [
+        stage.stageKey,
+        {
+          key: stage.stageKey,
+          label: stage.label,
+          order: (index + 1) * 10,
+          ...(stage.color !== undefined ? { color: stage.color } : {}),
+          states: stage.states.map((state) => ({ ...state }))
+        } satisfies CrmCatalogStageEntry
+      ])
+    ),
+    legacyPipelineKey: CRM_PIPELINE_DEFINITION.pipelineKey,
+    legacyEntityKey: CRM_PIPELINE_DEFINITION.entityKey
+  }
+}
+
+function createLeadGenStageCatalog(): OntologyCatalogType {
+  return {
+    id: LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID,
+    label: 'Lead Gen Processing Stages',
+    ownerSystemId: 'sales.lead-gen',
+    kind: 'processing-stage-catalog',
+    entries: Object.fromEntries(
+      Object.entries(LEAD_GEN_STAGE_CATALOG).map(([key, entry]) => [
+        key,
+        {
+          ...entry
+        }
+      ])
+    ),
+    legacyCatalogKey: 'LEAD_GEN_STAGE_CATALOG'
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function mergeBridgeCatalogs(model: OrganizationModel): OrganizationModel {
+  const baseCatalogTypes = model.ontology?.catalogTypes ?? {}
+  const bridgeCatalogTypes: Record<OntologyId, OntologyCatalogType> = {}
+
+  if (baseCatalogTypes[CRM_PIPELINE_CATALOG_ONTOLOGY_ID] === undefined) {
+    bridgeCatalogTypes[CRM_PIPELINE_CATALOG_ONTOLOGY_ID] = createCrmPipelineCatalog()
+  }
+  if (baseCatalogTypes[LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID] === undefined) {
+    bridgeCatalogTypes[LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID] = createLeadGenStageCatalog()
+  }
+
+  if (Object.keys(bridgeCatalogTypes).length === 0) return model
+
+  return {
+    ...model,
+    ontology: {
+      ...(model.ontology ?? {}),
+      catalogTypes: {
+        ...baseCatalogTypes,
+        ...bridgeCatalogTypes
+      }
+    } satisfies OntologyScope
+  }
+}
+
+function compileBusinessOntologyValidationIndex(
+  model: OrganizationModel = DEFAULT_ORGANIZATION_MODEL
+): BusinessOntologyValidationIndex {
+  const compilation = compileOrganizationOntology(mergeBridgeCatalogs(model))
+  if (compilation.diagnostics.length > 0) {
+    const summary = compilation.diagnostics.map((diagnostic) => diagnostic.message).join('; ')
+    throw new Error(`Business ontology validation index failed to compile: ${summary}`)
+  }
+
+  const crmPipelineCatalog = compilation.ontology.catalogTypes[CRM_PIPELINE_CATALOG_ONTOLOGY_ID]
+  const leadGenStageCatalog = compilation.ontology.catalogTypes[LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID]
+  if (crmPipelineCatalog === undefined || leadGenStageCatalog === undefined) {
+    throw new Error('Business ontology validation index is missing CRM or lead-gen catalog bridge records')
+  }
+
+  return {
+    ontology: compilation.ontology,
+    crmPipelineCatalog,
+    leadGenStageCatalog,
+    actionTypesByLegacyId: indexActionTypesByLegacyId(compilation.ontology.actionTypes)
+  }
+}
+
+function indexActionTypesByLegacyId(
+  actionTypes: Record<OntologyId, OntologyActionType>
+): Record<string, OntologyActionType> {
+  const byLegacyId: Record<string, OntologyActionType> = {}
+  for (const actionType of Object.values(actionTypes)) {
+    const legacyActionId = actionType['legacyActionId']
+    if (typeof legacyActionId === 'string') {
+      byLegacyId[legacyActionId] = actionType
+    }
+  }
+  return byLegacyId
+}
+
+export const BUSINESS_ONTOLOGY_VALIDATION_INDEX = compileBusinessOntologyValidationIndex()
+
+function getCatalogEntries(catalog: OntologyCatalogType): Record<string, unknown> {
+  return isPlainRecord(catalog.entries) ? catalog.entries : {}
+}
+
+function asCrmStageEntry(key: string, value: unknown): CrmCatalogStageEntry {
+  const record = isPlainRecord(value) ? value : {}
+  const label = typeof record.label === 'string' ? record.label : key
+  const order = typeof record.order === 'number' ? record.order : 0
+  const color = typeof record.color === 'string' ? record.color : undefined
+  const rawStates = Array.isArray(record.states) ? record.states : []
+  const states = rawStates.flatMap((state): StatefulStateDefinition[] => {
+    if (!isPlainRecord(state) || typeof state.stateKey !== 'string') return []
+    return [
+      {
+        stateKey: state.stateKey,
+        label: typeof state.label === 'string' ? state.label : state.stateKey
+      }
+    ]
+  })
+
+  return {
+    key,
+    label,
+    order,
+    ...(color !== undefined ? { color } : {}),
+    states
+  }
+}
+
+function asLeadGenStageEntry(key: string, value: unknown): LeadGenStageCatalogEntry {
+  const record = isPlainRecord(value) ? value : {}
+  const entity = record.entity === 'contact' ? 'contact' : 'company'
+  const additionalEntities = Array.isArray(record.additionalEntities)
+    ? record.additionalEntities.filter(
+        (item): item is 'company' | 'contact' => item === 'company' || item === 'contact'
+      )
+    : undefined
+  const recordEntity =
+    record.recordEntity === 'company' || record.recordEntity === 'contact' ? record.recordEntity : undefined
+  const recordStageKey = typeof record.recordStageKey === 'string' ? record.recordStageKey : undefined
+
+  return {
+    key: typeof record.key === 'string' ? record.key : key,
+    label: typeof record.label === 'string' ? record.label : key,
+    description: typeof record.description === 'string' ? record.description : '',
+    order: typeof record.order === 'number' ? record.order : 0,
+    entity,
+    ...(additionalEntities !== undefined ? { additionalEntities } : {}),
+    ...(recordEntity !== undefined ? { recordEntity } : {}),
+    ...(recordStageKey !== undefined ? { recordStageKey } : {})
+  }
+}
+
+export const CRM_STAGE_KEYS_FROM_ONTOLOGY = Object.keys(
+  getCatalogEntries(BUSINESS_ONTOLOGY_VALIDATION_INDEX.crmPipelineCatalog)
+) as [string, ...string[]]
+
+export const CRM_STATE_KEYS_FROM_ONTOLOGY = Object.values(
+  getCatalogEntries(BUSINESS_ONTOLOGY_VALIDATION_INDEX.crmPipelineCatalog)
+).flatMap((entry, index) => {
+  const stageKey = CRM_STAGE_KEYS_FROM_ONTOLOGY[index]
+  if (stageKey === undefined) return []
+  return asCrmStageEntry(stageKey, entry).states.map((state) => state.stateKey)
+}) as [string, ...string[]]
+
+export const LEAD_GEN_STAGE_KEYS_FROM_ONTOLOGY = Object.keys(
+  getCatalogEntries(BUSINESS_ONTOLOGY_VALIDATION_INDEX.leadGenStageCatalog)
+) as [string, ...string[]]
+
+export function getCrmStatesForStage(stageKey: string): StatefulStateDefinition[] {
+  const entry = getCatalogEntries(BUSINESS_ONTOLOGY_VALIDATION_INDEX.crmPipelineCatalog)[stageKey]
+  return entry === undefined ? [] : asCrmStageEntry(stageKey, entry).states
+}
+
+export function isCrmStageKey(stageKey: string): boolean {
+  return Object.prototype.hasOwnProperty.call(
+    getCatalogEntries(BUSINESS_ONTOLOGY_VALIDATION_INDEX.crmPipelineCatalog),
+    stageKey
+  )
+}
+
+export function isCrmStateKey(stateKey: string): boolean {
+  return CRM_STATE_KEYS_FROM_ONTOLOGY.includes(stateKey)
+}
+
+export function getLeadGenStageCatalogFromOntology(): Record<string, LeadGenStageCatalogEntry> {
+  return Object.fromEntries(
+    Object.entries(getCatalogEntries(BUSINESS_ONTOLOGY_VALIDATION_INDEX.leadGenStageCatalog)).map(([key, value]) => [
+      key,
+      asLeadGenStageEntry(key, value)
+    ])
+  )
+}
+
+export function getLeadGenStageEntry(stageKey: string): LeadGenStageCatalogEntry | undefined {
+  return getLeadGenStageCatalogFromOntology()[stageKey]
+}
+
+export function isLeadGenStageKey(stageKey: string): boolean {
+  return getLeadGenStageEntry(stageKey) !== undefined
+}
+
+export function isLeadGenStageValidForEntity(stageKey: string, entity: 'company' | 'contact'): boolean {
+  const stage = getLeadGenStageEntry(stageKey)
+  return stage !== undefined && (stage.entity === entity || stage.additionalEntities?.includes(entity) === true)
+}
+
+export function isLeadGenRecordStageValidForEntity(stageKey: string, entity: 'company' | 'contact'): boolean {
+  const stage = getLeadGenStageEntry(stageKey)
+  return (
+    stage !== undefined &&
+    (stage.entity === entity || stage.additionalEntities?.includes(entity) === true || stage.recordEntity === entity)
+  )
+}
+
+export function resolveLeadGenRecordStageKey(stageKey: string, entity: 'company' | 'contact'): string {
+  const stage = getLeadGenStageEntry(stageKey)
+  return stage?.recordEntity === entity && stage.recordStageKey ? stage.recordStageKey : stageKey
+}
+
+export type BusinessActionMetadata = {
+  id: string
+  label: string
+  resourceId?: string
+}
+
+function getActionMetadata(actionKey: string): BusinessActionMetadata | undefined {
+  const actionType = BUSINESS_ONTOLOGY_VALIDATION_INDEX.actionTypesByLegacyId[actionKey]
+  if (actionType === undefined) return undefined
+
+  const resourceId = actionType['resourceId']
+  return {
+    id: actionKey,
+    label: actionType.label ?? actionKey,
+    ...(typeof resourceId === 'string' ? { resourceId } : {})
+  }
+}
+
+export function getCrmActionMetadata(actionKey: string): BusinessActionMetadata | undefined {
+  const actionType = BUSINESS_ONTOLOGY_VALIDATION_INDEX.actionTypesByLegacyId[actionKey]
+  return actionType?.ownerSystemId === 'sales.crm' ? getActionMetadata(actionKey) : undefined
+}
+
+export function isLeadGenActionKey(actionKey: string): boolean {
+  return (
+    actionKey.startsWith('lead-gen.') &&
+    BUSINESS_ONTOLOGY_VALIDATION_INDEX.actionTypesByLegacyId[actionKey] !== undefined
+  )
+}

package/src/business/acquisition/stateful.ts

@@ -1,30 +1,30 @@
-import { z } from 'zod'
-import { ActivityEventSchema, type ActivityEvent } from './activity-events'
-
-/**
- * Stateful trait — the (pipeline_key, stage_key, state_key, activity_log) quartet
- * applied to acq_deals (CRM HITL, shipped 2026-04-27) and being generalized to
- * acq_lists / acq_list_members / acq_list_companies via Track B.
- */
-export interface Stateful {
-  pipeline_key: string
-  stage_key: string
-  state_key: string
-  activity_log: ActivityEvent[]
-}
-
-export const StatefulSchema = z.object({
-  pipeline_key: z.string(),
-  stage_key: z.string(),
-  state_key: z.string(),
-  activity_log: z.array(ActivityEventSchema)
-})
-
-/** Generic transition shape — concrete per-entity transitionItem implementations satisfy this. */
-export type TransitionItem<T extends Stateful, TEvent extends ActivityEvent> = (
-  item: T,
-  transition: { stage_key?: string; state_key?: string; event: TEvent }
-) => T
-
-/** Generic action-derivation shape — concrete per-entity deriveActions implementations satisfy this. */
-export type DeriveActions<T extends Stateful, TAction> = (item: T) => TAction[]
+import { z } from 'zod'
+import { ActivityEventSchema, type ActivityEvent } from './activity-events'
+
+/**
+ * Stateful trait — the (pipeline_key, stage_key, state_key, activity_log) quartet
+ * applied to acq_deals (CRM HITL, shipped 2026-04-27) and being generalized to
+ * acq_lists / acq_list_members / acq_list_companies via Track B.
+ */
+export interface Stateful {
+  pipeline_key: string
+  stage_key: string
+  state_key: string
+  activity_log: ActivityEvent[]
+}
+
+export const StatefulSchema = z.object({
+  pipeline_key: z.string(),
+  stage_key: z.string(),
+  state_key: z.string(),
+  activity_log: z.array(ActivityEventSchema)
+})
+
+/** Generic transition shape — concrete per-entity transitionItem implementations satisfy this. */
+export type TransitionItem<T extends Stateful, TEvent extends ActivityEvent> = (
+  item: T,
+  transition: { stage_key?: string; state_key?: string; event: TEvent }
+) => T
+
+/** Generic action-derivation shape — concrete per-entity deriveActions implementations satisfy this. */
+export type DeriveActions<T extends Stateful, TAction> = (item: T) => TAction[]