@elevasis/core 0.21.0 → 0.22.0

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

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ClientDetailResponseSchema,
+  ClientListResponseSchema,
+  ClientStatusResponseSchema,
+  ListClientsQuerySchema
+} from './api-schemas'
+
+const VALID_UUID = '00000000-0000-4000-8000-000000000001'
+const ISO_TS = '2026-05-08T00:00:00.000Z'
+
+describe('client API schemas', () => {
+  it('coerces list pagination and accepts status/search filters', () => {
+    const result = ListClientsQuerySchema.safeParse({
+      status: 'active',
+      search: 'Acme',
+      limit: '10',
+      offset: '20'
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({
+        status: 'active',
+        search: 'Acme',
+        limit: 10,
+        offset: 20
+      })
+    }
+  })
+
+  it('rejects unknown list query fields', () => {
+    expect(ListClientsQuerySchema.safeParse({ includeDeals: true }).success).toBe(false)
+  })
+
+  it('accepts client list responses', () => {
+    expect(
+      ClientListResponseSchema.safeParse({
+        data: [
+          {
+            id: VALID_UUID,
+            organizationId: VALID_UUID,
+            name: 'Acme',
+            status: 'active',
+            sourceDealId: null,
+            primaryCompanyId: null,
+            primaryContactId: null,
+            convertedAt: null,
+            metadata: {},
+            createdAt: ISO_TS,
+            updatedAt: ISO_TS
+          }
+        ],
+        total: 1,
+        limit: 50,
+        offset: 0
+      }).success
+    ).toBe(true)
+  })
+
+  it('accepts client detail lineage refs', () => {
+    expect(
+      ClientDetailResponseSchema.safeParse({
+        id: VALID_UUID,
+        organizationId: VALID_UUID,
+        name: 'Acme',
+        status: 'onboarding',
+        sourceDealId: VALID_UUID,
+        primaryCompanyId: VALID_UUID,
+        primaryContactId: VALID_UUID,
+        convertedAt: ISO_TS,
+        metadata: { source: 'closed_won' },
+        createdAt: ISO_TS,
+        updatedAt: ISO_TS,
+        lineage: {
+          deals: [
+            {
+              id: VALID_UUID,
+              contactEmail: 'lead@example.com',
+              stageKey: 'closed_won',
+              stateKey: null,
+              updatedAt: ISO_TS
+            }
+          ],
+          projects: [{ id: VALID_UUID, name: 'Delivery', kind: 'client_engagement', status: 'active', updatedAt: ISO_TS }],
+          companies: [{ id: VALID_UUID, name: 'Acme Co', domain: 'acme.test', status: 'active' }],
+          contacts: [
+            {
+              id: VALID_UUID,
+              email: 'lead@example.com',
+              firstName: 'Ada',
+              lastName: null,
+              title: 'CEO',
+              companyId: VALID_UUID,
+              status: 'active'
+            }
+          ]
+        }
+      }).success
+    ).toBe(true)
+  })
+
+  it('accepts client portfolio status responses', () => {
+    expect(
+      ClientStatusResponseSchema.safeParse({
+        totalClients: 1,
+        byStatus: { active: 1, onboarding: 0, paused: 0, completed: 0, churned: 0 },
+        linkedDeals: 1,
+        linkedProjects: 1,
+        linkedCompanies: 1,
+        linkedContacts: 1
+      }).success
+    ).toBe(true)
+  })
+})

package/src/business/clients/api-schemas.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod'
+import { UuidSchema } from '../../platform/utils/validation'
+
+export const ClientStatusSchema = z.enum(['active', 'onboarding', 'paused', 'completed', 'churned'])
+
+export const ClientIdParamsSchema = z
+  .object({
+    clientId: UuidSchema
+  })
+  .strict()
+
+export const ListClientsQuerySchema = z
+  .object({
+    status: ClientStatusSchema.optional(),
+    search: z.string().trim().min(1).max(255).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+
+export const ClientRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: ClientStatusSchema
+})
+
+export const ClientResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  name: z.string(),
+  status: ClientStatusSchema,
+  sourceDealId: z.string().nullable(),
+  primaryCompanyId: z.string().nullable(),
+  primaryContactId: z.string().nullable(),
+  convertedAt: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
+
+export const ClientDealRefSchema = z.object({
+  id: z.string(),
+  contactEmail: z.string(),
+  stageKey: z.string().nullable(),
+  stateKey: z.string().nullable(),
+  updatedAt: z.string()
+})
+
+export const ClientProjectRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  kind: z.string(),
+  status: z.string(),
+  updatedAt: z.string()
+})
+
+export const ClientCompanyRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  status: z.string()
+})
+
+export const ClientContactRefSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  title: z.string().nullable(),
+  companyId: z.string().nullable(),
+  status: z.string()
+})
+
+export const ClientLineageSchema = z.object({
+  deals: z.array(ClientDealRefSchema),
+  projects: z.array(ClientProjectRefSchema),
+  companies: z.array(ClientCompanyRefSchema),
+  contacts: z.array(ClientContactRefSchema)
+})
+
+export const ClientDetailResponseSchema = ClientResponseSchema.extend({
+  lineage: ClientLineageSchema
+})
+
+export const ClientListResponseSchema = z.object({
+  data: z.array(ClientResponseSchema),
+  total: z.number().int().min(0),
+  limit: z.number().int().min(1),
+  offset: z.number().int().min(0)
+})
+
+export const ClientStatusResponseSchema = z.object({
+  totalClients: z.number().int().min(0),
+  byStatus: z.record(ClientStatusSchema, z.number().int().min(0)),
+  linkedDeals: z.number().int().min(0),
+  linkedProjects: z.number().int().min(0),
+  linkedCompanies: z.number().int().min(0),
+  linkedContacts: z.number().int().min(0)
+})
+
+export const CreateClientRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255),
+    status: ClientStatusSchema.optional(),
+    sourceDealId: UuidSchema.nullable().optional(),
+    primaryCompanyId: UuidSchema.nullable().optional(),
+    primaryContactId: UuidSchema.nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).nullable().optional()
+  })
+  .strict()
+
+export const UpdateClientRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255).optional(),
+    status: ClientStatusSchema.optional(),
+    sourceDealId: UuidSchema.nullable().optional(),
+    primaryCompanyId: UuidSchema.nullable().optional(),
+    primaryContactId: UuidSchema.nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).nullable().optional()
+  })
+  .strict()
+  .refine((data) => Object.keys(data).length > 0, {
+    message: 'At least one field must be provided'
+  })
+
+export const ClientSchemas = {
+  ClientStatus: ClientStatusSchema,
+  ClientIdParams: ClientIdParamsSchema,
+  ListClientsQuery: ListClientsQuerySchema,
+  ClientRef: ClientRefSchema,
+  ClientResponse: ClientResponseSchema,
+  ClientDealRef: ClientDealRefSchema,
+  ClientProjectRef: ClientProjectRefSchema,
+  ClientCompanyRef: ClientCompanyRefSchema,
+  ClientContactRef: ClientContactRefSchema,
+  ClientLineage: ClientLineageSchema,
+  ClientDetailResponse: ClientDetailResponseSchema,
+  ClientListResponse: ClientListResponseSchema,
+  ClientStatusResponse: ClientStatusResponseSchema,
+  CreateClientRequest: CreateClientRequestSchema,
+  UpdateClientRequest: UpdateClientRequestSchema
+}
+
+export type ClientStatus = z.infer<typeof ClientStatusSchema>
+export type ClientIdParams = z.infer<typeof ClientIdParamsSchema>
+export type ListClientsQuery = z.infer<typeof ListClientsQuerySchema>
+export type ClientRef = z.infer<typeof ClientRefSchema>
+export type ClientResponse = z.infer<typeof ClientResponseSchema>
+export type ClientDealRef = z.infer<typeof ClientDealRefSchema>
+export type ClientProjectRef = z.infer<typeof ClientProjectRefSchema>
+export type ClientCompanyRef = z.infer<typeof ClientCompanyRefSchema>
+export type ClientContactRef = z.infer<typeof ClientContactRefSchema>
+export type ClientLineage = z.infer<typeof ClientLineageSchema>
+export type ClientDetailResponse = z.infer<typeof ClientDetailResponseSchema>
+export type ClientListResponse = z.infer<typeof ClientListResponseSchema>
+export type ClientStatusResponse = z.infer<typeof ClientStatusResponseSchema>
+export type CreateClientRequest = z.infer<typeof CreateClientRequestSchema>
+export type UpdateClientRequest = z.infer<typeof UpdateClientRequestSchema>

package/src/business/clients/index.ts

@@ -0,0 +1 @@
+export * from './api-schemas'

package/src/business/deals/api-schemas.ts

@@ -42,6 +42,10 @@ export {
   DealLookupResponseSchema,
   ConversationMessageSchema,
   DealConversationSchema,
+  DealLineageListRefSchema,
+  DealLineageProjectRefSchema,
+  DealLineageClientRefSchema,
+  DealLineageSchema,
   DealDetailResponseSchema,
   DealNoteResponseSchema,
   DealNoteListResponseSchema,
@@ -71,6 +75,10 @@ export {
   type DealLookupItem,
   type DealLookupResponse,
   type ConversationMessage,
+  type DealLineageListRef,
+  type DealLineageProjectRef,
+  type DealLineageClientRef,
+  type DealLineage,
   type DealDetailResponse,
   type DealNoteResponse,
   type DealNoteListResponse,

package/src/business/index.ts

@@ -5,8 +5,11 @@
  * Note: PDF has its own subpath exports (./pdf, ./pdf/browser, ./pdf/server, ./pdf/sections)
  */
 
-// Acquisition types (lead database domain types)
-export * from './acquisition/index'
+// Acquisition types (lead database domain types)
+export * from './acquisition/index'
+
+// Client hub schemas
+export * from './clients/index'
 
 // SEO types (seo_pages, seo_metrics, chart types)
 export * from './seo/index'

package/src/business/projects/types.ts

@@ -75,6 +75,24 @@ export interface ProjectDetail extends ProjectRow {
   milestones: MilestoneRow[]
   tasks: TaskRow[]
   company: { id: string; name: string; domain: string | null } | null
+  deal: ProjectSourceDealRef | null
+  client: ProjectClientRef | null
+}
+
+export interface ProjectSourceDealRef {
+  id: string
+  clientId?: string | null
+  contactEmail: string
+  stageKey: string | null
+  stateKey: string | null
+  sourceListId: string | null
+  updatedAt: string
+}
+
+export interface ProjectClientRef {
+  id: string
+  name: string
+  status: string
 }
 
 export interface MilestoneWithTasks extends MilestoneRow {
@@ -104,6 +122,7 @@ export interface Project {
   status: ProjectStatus
   description: string | null
   dealId: string | null
+  clientId: string | null
   clientCompanyId: string | null
   startDate: string | null
   targetEndDate: string | null

package/src/execution/engine/__tests__/fixtures/test-agents.ts

@@ -11,10 +11,11 @@ export function createPlatformToolAgent(): AgentDefinition {
     config: {
       resourceId: 'platform-tool-agent',
       name: 'Platform Tool Agent',
-      description: 'Test agent with platform tools for approval workflows',
-      systemPrompt: 'You help with approvals and notifications',
-      type: 'agent',
-      status: 'dev',
+      description: 'Test agent with platform tools for approval workflows',
+      systemPrompt: 'You help with approvals and notifications',
+      type: 'agent',
+      kind: 'utility',
+      status: 'dev',
       version: '1.0.0'
     },
     contract: {
@@ -68,10 +69,11 @@ export function createKnowledgeMapAgent(): AgentDefinition {
     config: {
       resourceId: 'knowledge-agent',
       name: 'Knowledge Map Agent',
-      description: 'Test agent with knowledge map for dynamic capability loading',
-      systemPrompt: 'You can load knowledge nodes as needed',
-      type: 'agent',
-      status: 'dev',
+      description: 'Test agent with knowledge map for dynamic capability loading',
+      systemPrompt: 'You can load knowledge nodes as needed',
+      type: 'agent',
+      kind: 'utility',
+      status: 'dev',
       version: '1.0.0'
     },
     contract: {

package/src/execution/engine/agent/core/__tests__/agent.test.ts

@@ -19,9 +19,10 @@ describe('Agent Execution', () => {
 
   // Helper: Create minimal agent definition with mock provider
   const createAgentDefinition = (overrides?: Partial<AgentDefinition>): AgentDefinition => {
-    const config: AgentConfig = {
-      type: 'agent',
-      resourceId: 'test-agent',
+    const config: AgentConfig = {
+      type: 'agent',
+      kind: 'utility',
+      resourceId: 'test-agent',
       name: 'Test Agent',
       description: 'Agent for testing',
       environment: 'dev',
@@ -165,9 +166,10 @@ describe('Agent Execution', () => {
 
     it('respects maxIterations constraint', async () => {
       const definition = createAgentDefinition({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Agent for testing',
           environment: 'dev',
@@ -418,9 +420,10 @@ describe('Agent Execution', () => {
 
     it('handles maxIterations edge case (zero iterations)', async () => {
       const definition = createAgentDefinition({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Agent for testing',
           environment: 'dev',
@@ -442,9 +445,10 @@ describe('Agent Execution', () => {
 
     it('handles negative maxIterations', async () => {
       const definition = createAgentDefinition({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Agent for testing',
           environment: 'dev',

package/src/execution/engine/agent/core/__tests__/error-passthrough.test.ts

@@ -35,9 +35,10 @@ vi.mock('../../memory/processor', () => ({
 const mockAdapterFactory: LLMAdapterFactory = vi.fn() as unknown as LLMAdapterFactory
 
 const createTestAgent = (): Agent => {
-  const config: AgentConfig = {
-    type: 'agent',
-    resourceId: 'test-agent',
+  const config: AgentConfig = {
+    type: 'agent',
+    kind: 'utility',
+    resourceId: 'test-agent',
     name: 'Test Agent',
     description: 'Agent for error passthrough testing',
     environment: 'dev',

package/src/execution/engine/agent/core/types.ts

@@ -3,9 +3,10 @@
  * Types for autonomous agents with tools, memory, and constraints
  */
 
-import type { Contract, ExecutionContext } from '../../base/types'
-import type { ResourceDefinition } from '../../../../platform/registry/types'
-import { Tool } from '../../tools/types'
+import type { Contract, ExecutionContext } from '../../base/types'
+import type { ResourceDefinition } from '../../../../platform/registry/types'
+import type { AgentResourceEntry } from '../../../../organization-model/domains/resources'
+import { Tool } from '../../tools/types'
 import type { AgentMemory } from '../memory/types'
 import type { LLMAdapter } from '../../llm/types'
 import type { ModelConfig } from '../../llm/model-info'
@@ -27,17 +28,22 @@ export type { AgentMemory }
  * Uses `any` for optional params so both the real createLLMAdapter (with typed
  * AIUsageCollector/AICallContext) and the worker proxy (which ignores them) satisfy the type.
  */
-export type LLMAdapterFactory = (
-  config: ModelConfig,
-  ...args: any[]
-) => LLMAdapter
-
-// Agent configuration
-export interface AgentConfig extends ResourceDefinition {
-  type: 'agent'
-
-  // Agent behavior
-  systemPrompt: string // System prompt defining agent behavior
+export type LLMAdapterFactory = (
+  config: ModelConfig,
+  ...args: any[]
+) => LLMAdapter
+
+export type AgentKind = 'orchestrator' | 'specialist' | 'utility' | 'system'
+
+// Agent configuration
+export interface AgentConfig extends ResourceDefinition {
+  type: 'agent'
+  /** OM descriptor backing canonical identity and governance metadata. */
+  resource?: AgentResourceEntry
+  kind: AgentKind
+
+  // Agent behavior
+  systemPrompt: string // System prompt defining agent behavior
 
   // Execution constraints (simplified for v1)
   constraints?: AgentConstraints
@@ -83,7 +89,11 @@ export interface AgentConfig extends ResourceDefinition {
   memoryPreferences?: string
 
   // Lifecycle callbacks for observability (optional) - DEFERRED
-}
+}
+
+export type DescriptorBackedAgentConfig = Omit<AgentConfig, 'resourceId' | 'type' | 'resource'> & {
+  resource: AgentResourceEntry
+}
 
 // Execution constraints to prevent runaway agents
 export interface AgentConstraints {

package/src/execution/engine/agent/index.ts

@@ -7,10 +7,12 @@
 export { Agent } from './core/agent'
 
 // Types
-export type {
-  AgentConfig,
-  AgentConstraints,
-  AgentDefinition,
+export type {
+  AgentKind,
+  AgentConfig,
+  DescriptorBackedAgentConfig,
+  AgentConstraints,
+  AgentDefinition,
   IterationContext,
   LLMAdapterFactory
 } from './core/types'

package/src/execution/engine/agent/reasoning/__tests__/request-builder.test.ts

@@ -8,9 +8,10 @@ import { z } from 'zod'
 describe('buildReasoningRequest', () => {
   // Helper: Create minimal iteration context
   const createMockContext = (overrides?: Partial<IterationContext>): IterationContext => {
-    const config: AgentConfig = {
-      type: 'agent',
-      resourceId: 'test-agent',
+    const config: AgentConfig = {
+      type: 'agent',
+      kind: 'utility',
+      resourceId: 'test-agent',
       name: 'Test Agent',
       description: 'Test agent',
       version: '1.0.0',
@@ -95,9 +96,10 @@ describe('buildReasoningRequest', () => {
 
     it('should set includeMessageAction to true when sessionCapable is true', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -113,9 +115,10 @@ describe('buildReasoningRequest', () => {
 
     it('should set includeMessageAction to false when sessionCapable is false', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -142,9 +145,10 @@ describe('buildReasoningRequest', () => {
 
     it('should include hardened security rules when sessionCapable is true', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -161,9 +165,10 @@ describe('buildReasoningRequest', () => {
 
     it('should omit security section when securityLevel is none', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -179,9 +184,10 @@ describe('buildReasoningRequest', () => {
 
     it('should allow explicit hardened override on non-session agent', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',

package/src/execution/engine/index.ts

@@ -14,6 +14,7 @@ export {
   type WorkflowStepDefinition,
   type StepHandler,
   type WorkflowConfig,
+  type DescriptorBackedWorkflowConfig,
   type WorkflowDefinition,
   type NextConfig,
   type LinearNext,
@@ -59,7 +60,9 @@ export {
 // Agent exports (from agent module)
 export {
   Agent,
+  type AgentKind,
   type AgentConfig,
+  type DescriptorBackedAgentConfig,
   type AgentConstraints,
   type AgentMemory,
   type AgentDefinition,

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

@@ -7,16 +7,23 @@ import type { z } from 'zod'
 
 import type { ExecutionContext } from '../base/types'
 import type { ResourceDefinition } from '../../../platform/registry/types'
+import type { WorkflowResourceEntry } from '../../../organization-model/domains/resources'
 import type { ResourceMetricsConfig } from '../../../operations/observability/types'
 import type { ExecutionInterface } from '../interface/types'
 
 // Workflow configuration
 export interface WorkflowConfig extends ResourceDefinition {
   type: 'workflow'
+  /** OM descriptor backing canonical identity and governance metadata. */
+  resource?: WorkflowResourceEntry
   /** Lead-gen capability key for registry derivation (e.g. 'lead-gen.company.apollo-import') */
   capabilityKey?: string
 }
 
+export type DescriptorBackedWorkflowConfig = Omit<WorkflowConfig, 'resourceId' | 'type' | 'resource'> & {
+  resource: WorkflowResourceEntry
+}
+
 // Workflow step definition
 export interface WorkflowStepDefinition {
   id: string