@elevasis/core 0.34.2 → 0.35.0

package/src/business/acquisition/api-schemas.test.ts

@@ -121,8 +121,15 @@ import {
 } from './api-schemas'
 import { createBuildPlanSnapshotFromTemplate } from './build-templates'
 import {
+  compileCrmApiOntologyValidationIndex,
   compileBusinessOntologyValidationIndex,
+  computeInterfaceReadiness,
+  compileLeadGenApiOntologyValidationIndex,
+  compileLeadGenCrmHandoffOntologyValidationIndex,
+  CRM_API_INTERFACE,
+  LEAD_GEN_CRM_HANDOFF_INTERFACE,
   CRM_PIPELINE_CATALOG_ONTOLOGY_ID,
+  LEAD_GEN_API_INTERFACE,
   LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID
 } from './ontology-validation'
 
@@ -177,11 +184,142 @@ const DEFAULT_CRM_PRIORITY_RULE_CONFIG: CrmPriorityRuleConfig = {
 // ---------------------------------------------------------------------------
 // Minimal test model fixture
 // ---------------------------------------------------------------------------
-// Builds an OrganizationModel that contains the CRM pipeline catalog exactly as
-// @repo/elevasis-core authors it in canonicalOrganizationModel (sales.crm system,
-// ontology.catalogTypes['sales.crm:catalog/crm.pipeline']).  Derived inline from
-// CRM_PIPELINE_DEFINITION so packages/core tests have no dependency on @repo/elevasis-core.
-function buildMinimalCrmModel(): OrganizationModel {
+// Builds OrganizationModel fixtures inline so packages/core tests have no
+// dependency on @repo/elevasis-core canonical tenant data.
+function buildMinimalLeadGenModel(): OrganizationModel {
+  return {
+    ...DEFAULT_ORGANIZATION_MODEL,
+    systems: {
+      sales: {
+        id: 'sales',
+        label: 'Sales',
+        order: 60,
+        systems: {
+          'lead-gen': {
+            id: 'sales.lead-gen',
+            label: 'Lead Gen',
+            order: 70,
+            apiInterface: {
+              lifecycle: 'active',
+              readinessProfile: LEAD_GEN_API_INTERFACE.readinessProfile,
+              resourceIds: ['lead-gen-api-workflow']
+            },
+            ontology: {
+              objectTypes: {
+                'sales.lead-gen:object/list': {
+                  id: 'sales.lead-gen:object/list',
+                  label: 'Lead List',
+                  ownerSystemId: 'sales.lead-gen'
+                },
+                'sales.lead-gen:object/company': {
+                  id: 'sales.lead-gen:object/company',
+                  label: 'Lead Company',
+                  ownerSystemId: 'sales.lead-gen'
+                },
+                'sales.lead-gen:object/contact': {
+                  id: 'sales.lead-gen:object/contact',
+                  label: 'Lead Contact',
+                  ownerSystemId: 'sales.lead-gen'
+                }
+              },
+              catalogTypes: {
+                'sales.lead-gen:catalog/build-template': {
+                  id: 'sales.lead-gen:catalog/build-template',
+                  label: 'Build Templates',
+                  ownerSystemId: 'sales.lead-gen',
+                  kind: 'template',
+                  appliesTo: 'sales.lead-gen:object/list',
+                  entries: {
+                    'local-services': {
+                      label: 'Local Services',
+                      order: 10,
+                      stepCatalog: 'sales.lead-gen:catalog/template-step.local-services'
+                    }
+                  }
+                },
+                'sales.lead-gen:catalog/template-step.local-services': {
+                  id: 'sales.lead-gen:catalog/template-step.local-services',
+                  label: 'Local Services Steps',
+                  ownerSystemId: 'sales.lead-gen',
+                  kind: 'template-step',
+                  appliesTo: 'sales.lead-gen:object/list',
+                  entries: {
+                    'source-companies': {
+                      label: 'Source Companies',
+                      order: 10,
+                      primaryEntity: 'company',
+                      outputs: ['company'],
+                      stageKey: 'populated',
+                      dependencyMode: 'per-record-eligibility',
+                      actionKey: 'lead-gen.company.source'
+                    },
+                    'discover-contacts': {
+                      label: 'Discover Contacts',
+                      order: 20,
+                      primaryEntity: 'contact',
+                      outputs: ['contact'],
+                      stageKey: 'discovered',
+                      dependencyMode: 'per-record-eligibility',
+                      actionKey: 'lead-gen.contact.discover'
+                    }
+                  }
+                },
+                'sales.lead-gen:catalog/company-stage': {
+                  id: 'sales.lead-gen:catalog/company-stage',
+                  label: 'Company Stages',
+                  ownerSystemId: 'sales.lead-gen',
+                  kind: 'stage',
+                  appliesTo: 'sales.lead-gen:object/company',
+                  entries: {
+                    populated: { label: 'Populated', description: 'Companies imported.', order: 10 },
+                    qualified: { label: 'Qualified', description: 'Companies qualified.', order: 20 }
+                  }
+                },
+                'sales.lead-gen:catalog/contact-stage': {
+                  id: 'sales.lead-gen:catalog/contact-stage',
+                  label: 'Contact Stages',
+                  ownerSystemId: 'sales.lead-gen',
+                  kind: 'stage',
+                  appliesTo: 'sales.lead-gen:object/contact',
+                  entries: {
+                    discovered: { label: 'Discovered', description: 'Contacts found.', order: 10 },
+                    verified: { label: 'Verified', description: 'Contacts verified.', order: 20 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    resources: {
+      'lead-gen-api-workflow': {
+        id: 'lead-gen-api-workflow',
+        kind: 'workflow',
+        systemPath: 'sales.lead-gen',
+        status: 'active',
+        order: 10,
+        ontology: {
+          actions: ['sales.lead-gen:action/api'],
+          primaryAction: 'sales.lead-gen:action/api',
+          reads: [
+            'sales.lead-gen:object/list',
+            'sales.lead-gen:object/company',
+            'sales.lead-gen:object/contact'
+          ],
+          usesCatalogs: [
+            'sales.lead-gen:catalog/build-template',
+            'sales.lead-gen:catalog/template-step.local-services',
+            'sales.lead-gen:catalog/company-stage',
+            'sales.lead-gen:catalog/contact-stage'
+          ]
+        }
+      }
+    }
+  }
+}
+
+function buildMinimalLeadGenAndCrmModel(options: { includeHandoff?: boolean } = {}): OrganizationModel {
   const crmCatalogEntries = Object.fromEntries(
     CRM_PIPELINE_DEFINITION.stages.map((stage, idx) => [
       stage.stageKey,
@@ -194,34 +332,119 @@ function buildMinimalCrmModel(): OrganizationModel {
       }
     ])
   )
-  return {
-    ...DEFAULT_ORGANIZATION_MODEL,
-    systems: {
-      sales: {
-        id: 'sales',
-        label: 'Sales',
-        order: 60,
-        systems: {
-          crm: {
-            id: 'sales.crm',
+  const model = buildMinimalLeadGenModel()
+  const salesSystem = model.systems.sales
+  if (salesSystem === undefined) throw new Error('Minimal lead-gen fixture is missing sales system')
+
+  salesSystem.systems = {
+    ...(salesSystem.systems ?? {}),
+    crm: {
+      id: 'sales.crm',
+      label: 'CRM',
+      order: 80,
+      apiInterface: {
+        lifecycle: 'active',
+        readinessProfile: CRM_API_INTERFACE.readinessProfile,
+        resourceIds: ['crm-api-workflow']
+      },
+      ontology: {
+        objectTypes: {
+          'sales.crm:object/deal': {
+            id: 'sales.crm:object/deal',
+            label: 'Deal',
+            ownerSystemId: 'sales.crm'
+          }
+        },
+        catalogTypes: {
+          'sales.crm:catalog/crm.pipeline': {
+            id: 'sales.crm:catalog/crm.pipeline',
             label: 'CRM',
-            order: 80,
-            ontology: {
-              catalogTypes: {
-                'sales.crm:catalog/crm.pipeline': {
-                  id: 'sales.crm:catalog/crm.pipeline',
-                  label: 'CRM',
-                  ownerSystemId: 'sales.crm',
-                  kind: 'pipeline',
-                  entries: crmCatalogEntries
-                }
-              }
+            ownerSystemId: 'sales.crm',
+            kind: 'pipeline',
+            entries: crmCatalogEntries
+          }
+        }
+      }
+    }
+  }
+
+  model.resources = {
+    ...model.resources,
+    'crm-api-workflow': {
+      id: 'crm-api-workflow',
+      kind: 'workflow',
+      systemPath: 'sales.crm',
+      status: 'active',
+      order: 20,
+      ontology: {
+        actions: ['sales.crm:action/api'],
+        primaryAction: 'sales.crm:action/api',
+        usesCatalogs: ['sales.crm:catalog/crm.pipeline']
+      }
+    }
+  }
+
+  if (options.includeHandoff === true) {
+    const leadGenSystem = salesSystem.systems['lead-gen']
+    if (leadGenSystem === undefined) throw new Error('Minimal fixture is missing lead-gen system')
+    model.resources = {
+      ...model.resources,
+      'lead-gen-crm-handoff-workflow': {
+        id: 'lead-gen-crm-handoff-workflow',
+        kind: 'workflow',
+        systemPath: 'sales.lead-gen',
+        status: 'active',
+        order: 30,
+        ontology: {
+          actions: ['sales.lead-gen:action/handoff'],
+          primaryAction: 'sales.lead-gen:action/handoff',
+          reads: [
+            'sales.lead-gen:object/list',
+            'sales.lead-gen:object/company',
+            'sales.lead-gen:object/contact'
+          ],
+          usesCatalogs: [
+            'sales.lead-gen:catalog/build-template',
+            'sales.lead-gen:catalog/template-step.local-services',
+            'sales.lead-gen:catalog/company-stage',
+            'sales.lead-gen:catalog/contact-stage',
+            'sales.crm:catalog/crm.pipeline'
+          ]
+        }
+      }
+    }
+    model.topology = {
+      version: 1,
+      relationships: {
+        'lead-gen-crm-handoff': {
+          from: { kind: 'resource', id: 'lead-gen-crm-handoff-workflow' },
+          kind: 'uses',
+          to: { kind: 'resource', id: 'crm-api-workflow' },
+          required: true,
+          metadata: {
+            systemInterfaceGrant: {
+              consumer: {
+                systemPath: LEAD_GEN_CRM_HANDOFF_INTERFACE.systemPath,
+                interfaceKey: LEAD_GEN_CRM_HANDOFF_INTERFACE.interfaceKey
+              },
+              provider: {
+                systemPath: CRM_API_INTERFACE.systemPath,
+                interfaceKey: CRM_API_INTERFACE.interfaceKey
+              },
+              resourceIds: ['lead-gen-crm-handoff-workflow'],
+              ontologyIds: ['sales.crm:catalog/crm.pipeline']
             }
           }
         }
       }
     }
   }
+
+  return model
+}
+
+function buildMinimalCrmModel(): OrganizationModel {
+  return buildMinimalLeadGenAndCrmModel()
 }
 
 // ---------------------------------------------------------------------------
@@ -276,10 +499,215 @@ describe('DealStageSchema', () => {
 })
 
 // ---------------------------------------------------------------------------
-// Ontology validation bridge
+// Ontology validation contracts
 // ---------------------------------------------------------------------------
 
-describe('business ontology validation bridge', () => {
+describe('business ontology validation contracts', () => {
+  it('computes structured readiness for a ready lead-gen API interface without CRM', () => {
+    const model = buildMinimalLeadGenModel()
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(true)
+    expect(readiness.readinessProfile).toBe(LEAD_GEN_API_INTERFACE.readinessProfile)
+    expect(readiness.scopedResourceIds).toEqual(['lead-gen-api-workflow'])
+    expect(readiness.issues).toEqual([])
+  })
+
+  it('lead-gen API validation passes without CRM when list/company/contact readiness exists', () => {
+    const model = buildMinimalLeadGenModel()
+    const index = compileLeadGenApiOntologyValidationIndex(model)
+
+    expect(index.ontology.catalogTypes[CRM_PIPELINE_CATALOG_ONTOLOGY_ID]).toBeUndefined()
+    expect(index.ontology.catalogTypes[LEAD_GEN_STAGE_CATALOG_ONTOLOGY_ID]).toBeDefined()
+    expect(index.leadGenStageCatalog).toBeDefined()
+  })
+
+  it('CRM API validation supplies pipeline readiness without requiring lead-gen contracts', () => {
+    const model = buildMinimalCrmModel()
+    const index = compileCrmApiOntologyValidationIndex(model)
+
+    expect(index.crmPipelineCatalog).toBeDefined()
+    expect(index.crmPipelineCatalog.entries).toHaveProperty('interested')
+  })
+
+  it('computes structured diagnostics when an interface marker is missing', () => {
+    const model = buildMinimalLeadGenAndCrmModel()
+    delete model.systems.sales?.systems?.['lead-gen']?.apiInterface
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toMatchObject([{ family: 'SYSTEM_INTERFACE_MISSING', code: 'missing-interface' }])
+  })
+
+  it('computes structured diagnostics when an interface marker is inactive', () => {
+    const model = buildMinimalLeadGenModel()
+    const apiInterface = model.systems.sales?.systems?.['lead-gen']?.apiInterface
+    if (apiInterface === undefined) throw new Error('Minimal fixture is missing lead-gen API interface')
+    apiInterface.lifecycle = 'disabled'
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([expect.objectContaining({ family: 'SYSTEM_INTERFACE_DISABLED', code: 'inactive-interface' })])
+    )
+  })
+
+  it('computes structured diagnostics when scoped API resources are absent', () => {
+    const model = buildMinimalLeadGenModel()
+    const apiInterface = model.systems.sales?.systems?.['lead-gen']?.apiInterface
+    if (apiInterface === undefined) throw new Error('Minimal fixture is missing lead-gen API interface')
+    apiInterface.resourceIds = []
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ family: 'SYSTEM_INTERFACE_NOT_READY', code: 'missing-scoped-resources' })
+      ])
+    )
+  })
+
+  it('computes structured diagnostics when a scoped API resource id is missing', () => {
+    const model = buildMinimalLeadGenModel()
+    const apiInterface = model.systems.sales?.systems?.['lead-gen']?.apiInterface
+    if (apiInterface === undefined) throw new Error('Minimal fixture is missing lead-gen API interface')
+    apiInterface.resourceIds = ['missing-lead-gen-api-workflow']
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          family: 'SYSTEM_INTERFACE_NOT_READY',
+          code: 'missing-resource',
+          ref: 'missing-lead-gen-api-workflow',
+          path: 'systems.sales.lead-gen.apiInterface.resourceIds.0'
+        })
+      ])
+    )
+  })
+
+  it('computes structured diagnostics when a scoped API resource belongs to another System', () => {
+    const model = buildMinimalLeadGenAndCrmModel()
+    const apiInterface = model.systems.sales?.systems?.['lead-gen']?.apiInterface
+    if (apiInterface === undefined) throw new Error('Minimal fixture is missing lead-gen API interface')
+    apiInterface.resourceIds = ['crm-api-workflow']
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          family: 'SYSTEM_INTERFACE_INVALID',
+          code: 'resource-system-mismatch',
+          ref: 'crm-api-workflow',
+          path: 'systems.sales.lead-gen.apiInterface.resourceIds.0'
+        })
+      ])
+    )
+  })
+
+  it('computes structured diagnostics when required ontology exists but no scoped resource binds it', () => {
+    const model = buildMinimalLeadGenModel()
+    const resource = model.resources['lead-gen-api-workflow']
+    if (resource === undefined) throw new Error('Minimal fixture is missing lead-gen API resource')
+    resource.ontology = {
+      ...resource.ontology,
+      reads: ['sales.lead-gen:object/list', 'sales.lead-gen:object/company']
+    }
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          family: 'SYSTEM_INTERFACE_NOT_READY',
+          code: 'missing-resource-binding',
+          ref: 'sales.lead-gen:object/contact'
+        })
+      ])
+    )
+  })
+
+  it('computes structured diagnostics when required content is empty', () => {
+    const model = buildMinimalLeadGenModel()
+    const catalog = model.systems.sales?.systems?.['lead-gen']?.ontology?.catalogTypes?.[
+      'sales.lead-gen:catalog/build-template'
+    ]
+    if (catalog === undefined) throw new Error('Minimal fixture is missing build-template catalog')
+    catalog.entries = {}
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([expect.objectContaining({ family: 'SYSTEM_INTERFACE_NOT_READY', code: 'empty-catalog' })])
+    )
+  })
+
+  it('computes structured diagnostics for an unknown readiness profile', () => {
+    const model = buildMinimalLeadGenModel()
+    const apiInterface = model.systems.sales?.systems?.['lead-gen']?.apiInterface
+    if (apiInterface === undefined) throw new Error('Minimal fixture is missing lead-gen API interface')
+    apiInterface.readinessProfile = 'sales.lead-gen.unknown'
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toMatchObject([{ family: 'SYSTEM_INTERFACE_INVALID', code: 'unknown-readiness-profile' }])
+  })
+
+  it('lead-gen-to-CRM handoff validation fails when the scoped topology grant is absent', () => {
+    const model = buildMinimalLeadGenAndCrmModel({ includeHandoff: true })
+    model.topology.relationships = {}
+
+    expect(() => compileLeadGenCrmHandoffOntologyValidationIndex(model)).toThrow('missing-topology-grant')
+  })
+
+  it('lead-gen-to-CRM handoff readiness reports provider interface failures as bridge diagnostics', () => {
+    const model = buildMinimalLeadGenAndCrmModel({ includeHandoff: true })
+    const crmInterface = model.systems.sales?.systems?.crm?.apiInterface
+    if (crmInterface === undefined) throw new Error('Minimal fixture is missing CRM API interface')
+    crmInterface.lifecycle = 'disabled'
+
+    const readiness = computeInterfaceReadiness(model, LEAD_GEN_CRM_HANDOFF_INTERFACE)
+
+    expect(readiness.ready).toBe(false)
+    expect(readiness.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          family: 'SYSTEM_BRIDGE_NOT_READY',
+          code: 'inactive-interface',
+          path: 'systems.sales.crm.apiInterface.lifecycle'
+        })
+      ])
+    )
+  })
+
+  it('lead-gen-to-CRM handoff validation requires the scoped topology grant and CRM pipeline readiness', () => {
+    const model = buildMinimalLeadGenAndCrmModel({ includeHandoff: true })
+    const index = compileLeadGenCrmHandoffOntologyValidationIndex(model)
+
+    expect(index.bridgeGrant).toBeDefined()
+    expect(index.leadGenStageCatalog).toBeDefined()
+    expect(index.crmPipelineCatalog).toBeDefined()
+  })
+
+  it('lead-gen-to-CRM handoff validation fails when CRM pipeline readiness is absent', () => {
+    const model = buildMinimalLeadGenAndCrmModel({ includeHandoff: true })
+    const crmSystem = model.systems.sales?.systems?.crm
+    if (crmSystem?.ontology?.catalogTypes === undefined) throw new Error('Minimal fixture is missing CRM catalog types')
+    delete crmSystem.ontology.catalogTypes['sales.crm:catalog/crm.pipeline']
+
+    expect(() => compileLeadGenCrmHandoffOntologyValidationIndex(model)).toThrow(CRM_PIPELINE_CATALOG_ONTOLOGY_ID)
+  })
+
   // compileBusinessOntologyValidationIndex now requires a model arg — no default singleton.
   // The canonical Elevasis CRM pipeline catalog is model-owned (authored in @repo/elevasis-core
   // canonicalOrganizationModel at 'sales.crm:catalog/crm.pipeline'). Tests here use a