@elevasis/core 0.34.1 → 0.35.0

package/src/platform/registry/__tests__/validation.test.ts

@@ -4,8 +4,13 @@
  */
 
 import { afterEach, describe, it, expect, vi } from 'vitest'
-import { z } from 'zod'
-import { validateExecutionInterface, validateResourceGovernance, RegistryValidationError } from '../validation'
+import { z } from 'zod'
+import {
+  validateExecutionInterface,
+  validateDeclaredSystemInterfaceReadiness,
+  validateResourceGovernance,
+  RegistryValidationError
+} from '../validation'
 import { ResourceRegistry } from '../resource-registry'
 import type { WorkflowDefinition } from '../../../execution/engine/workflow/types'
 import type { AgentDefinition } from '../../../execution/engine/agent/core/types'
@@ -277,7 +282,7 @@ describe('validateExecutionInterface', () => {
   })
 })
 
-describe('validateResourceGovernance', () => {
+describe('validateResourceGovernance', () => {
   afterEach(() => {
     vi.unstubAllEnvs()
   })
@@ -409,10 +414,10 @@ describe('validateResourceGovernance', () => {
     ...extras
   })
 
-  it('passes when code resources are descriptor-backed and match active OM Resources and Systems', () => {
-    const result = validateResourceGovernance(
-      'test-org',
-      {
+  it('passes when code resources are descriptor-backed and match active OM Resources and Systems', () => {
+    const result = validateResourceGovernance(
+      'test-org',
+      {
         version: '1.0.0',
         workflows: [createGovernedWorkflow()]
       },
@@ -420,13 +425,38 @@ describe('validateResourceGovernance', () => {
       { mode: 'strict' }
     )
 
-    expect(result.valid).toBe(true)
-    expect(result.issues).toEqual([])
-  })
-
-  it('throws in strict mode when an active OM resource has no code-side resource', () => {
-    expect(() =>
-      validateResourceGovernance(
+    expect(result.valid).toBe(true)
+    expect(result.issues).toEqual([])
+  })
+
+  it('allows active platform agents to be registered outside the SDK deployment bundle', () => {
+    const platformAgentResource: ResourceEntry = {
+      id: 'command-center-assistant',
+      kind: 'agent',
+      systemPath: 'sys.lead-gen',
+      status: 'active',
+      agentKind: 'platform',
+      sessionCapable: true,
+      order: 20
+    }
+
+    const result = validateResourceGovernance(
+      'test-org',
+      {
+        version: '1.0.0',
+        workflows: [createGovernedWorkflow()]
+      },
+      createModel([workflowResource, platformAgentResource]),
+      { mode: 'strict' }
+    )
+
+    expect(result.valid).toBe(true)
+    expect(result.issues).toEqual([])
+  })
+
+  it('throws in strict mode when an active OM resource has no code-side resource', () => {
+    expect(() =>
+      validateResourceGovernance(
         'test-org',
         {
           version: '1.0.0',
@@ -685,6 +715,189 @@ describe('validateResourceGovernance', () => {
     expect(result.valid).toBe(true)
   })
 
+  it('rejects sibling-System ontology refs without an exact scoped topology grant', () => {
+    const crmDealOntologyId = 'sys.crm:object/deal'
+    const resourceWithForeignRead: ResourceEntry = {
+      ...workflowResource,
+      ontology: {
+        actions: ['sys.lead-gen:action/import-leads'],
+        primaryAction: 'sys.lead-gen:action/import-leads',
+        reads: [crmDealOntologyId]
+      }
+    }
+
+    expect(() =>
+      validateResourceGovernance(
+        'test-org',
+        {
+          version: '1.0.0',
+          workflows: [createGovernedWorkflow(resourceWithForeignRead)]
+        },
+        createModel([resourceWithForeignRead], [systemA, systemB], {
+          ontology: {
+            ...validOntology,
+            objectTypes: {
+              ...validOntology.objectTypes,
+              [crmDealOntologyId]: {
+                id: crmDealOntologyId,
+                label: 'Deal'
+              }
+            }
+          },
+          topology: {
+            version: 1,
+            relationships: {
+              'lead-gen-uses-crm': {
+                from: { kind: 'system', id: 'sys.lead-gen' },
+                kind: 'uses',
+                to: { kind: 'system', id: 'sys.crm' }
+              }
+            }
+          }
+        }),
+        { mode: 'strict' }
+      )
+    ).toThrow(
+      "Resource 'lead-import' in system 'sys.lead-gen' references ontology 'sys.crm:object/deal' from system 'sys.crm' without scoped topology grant"
+    )
+  })
+
+  it('reports scoped topology grant diagnostics in warn-only mode', () => {
+    const warnings: string[] = []
+    const crmDealOntologyId = 'sys.crm:object/deal'
+    const resourceWithForeignRead: ResourceEntry = {
+      ...workflowResource,
+      ontology: {
+        actions: ['sys.lead-gen:action/import-leads'],
+        primaryAction: 'sys.lead-gen:action/import-leads',
+        reads: [crmDealOntologyId]
+      }
+    }
+
+    const result = validateResourceGovernance(
+      'test-org',
+      {
+        version: '1.0.0',
+        workflows: [createGovernedWorkflow(resourceWithForeignRead)]
+      },
+      createModel([resourceWithForeignRead], [systemA, systemB], {
+        ontology: {
+          ...validOntology,
+          objectTypes: {
+            ...validOntology.objectTypes,
+            [crmDealOntologyId]: {
+              id: crmDealOntologyId,
+              label: 'Deal'
+            }
+          }
+        }
+      }),
+      {
+        mode: 'warn-only',
+        onWarning: (issue) => warnings.push(issue.message)
+      }
+    )
+
+    expect(result.valid).toBe(false)
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        type: 'ontology-topology-grant-missing',
+        resourceId: 'lead-import',
+        message: expect.stringContaining("system 'sys.lead-gen'")
+      })
+    ])
+    expect(warnings[0]).toContain("ontology 'sys.crm:object/deal'")
+    expect(warnings[0]).toContain("from system 'sys.crm'")
+    expect(warnings[0]).toContain('systemInterfaceGrant(sys.lead-gen -> sys.crm')
+  })
+
+  it('accepts sibling-System ontology refs with an exact scoped topology grant', () => {
+    const crmDealOntologyId = 'sys.crm:object/deal'
+    const resourceWithForeignRead: ResourceEntry = {
+      ...workflowResource,
+      ontology: {
+        actions: ['sys.lead-gen:action/import-leads'],
+        primaryAction: 'sys.lead-gen:action/import-leads',
+        reads: [crmDealOntologyId]
+      }
+    }
+
+    const result = validateResourceGovernance(
+      'test-org',
+      {
+        version: '1.0.0',
+        workflows: [createGovernedWorkflow(resourceWithForeignRead)]
+      },
+      createModel([resourceWithForeignRead], [systemA, systemB], {
+        ontology: {
+          ...validOntology,
+          objectTypes: {
+            ...validOntology.objectTypes,
+            [crmDealOntologyId]: {
+              id: crmDealOntologyId,
+              label: 'Deal'
+            }
+          }
+        },
+        topology: {
+          version: 1,
+          relationships: {
+            'lead-import-reads-crm-deal': {
+              from: { kind: 'resource', id: 'lead-import' },
+              kind: 'uses',
+              to: { kind: 'ontology', id: crmDealOntologyId },
+              metadata: {
+                systemInterfaceGrant: {
+                  consumer: { systemPath: 'sys.lead-gen', interfaceKey: 'api' },
+                  provider: { systemPath: 'sys.crm', interfaceKey: 'api' },
+                  resourceIds: ['lead-import'],
+                  ontologyIds: [crmDealOntologyId]
+                }
+              }
+            }
+          }
+        }
+      }),
+      { mode: 'strict' }
+    )
+
+    expect(result.valid).toBe(true)
+  })
+
+  it('continues to accept same-System and global ontology refs without topology grants', () => {
+    const resourceWithSameAndGlobalRefs: ResourceEntry = {
+      ...workflowResource,
+      ontology: {
+        actions: ['sys.lead-gen:action/import-leads'],
+        primaryAction: 'sys.lead-gen:action/import-leads',
+        reads: ['sys.lead-gen:object/company', 'global:object/account']
+      }
+    }
+
+    const result = validateResourceGovernance(
+      'test-org',
+      {
+        version: '1.0.0',
+        workflows: [createGovernedWorkflow(resourceWithSameAndGlobalRefs)]
+      },
+      createModel([resourceWithSameAndGlobalRefs], [systemA], {
+        ontology: {
+          ...validOntology,
+          objectTypes: {
+            ...validOntology.objectTypes,
+            'global:object/account': {
+              id: 'global:object/account',
+              label: 'Account'
+            }
+          }
+        }
+      }),
+      { mode: 'strict' }
+    )
+
+    expect(result.valid).toBe(true)
+  })
+
   it('reports dangling required topology refs', () => {
     expect(() =>
       validateResourceGovernance(
@@ -743,7 +956,33 @@ describe('validateResourceGovernance', () => {
       )
     ).toThrow("Code-side resource 'lead-import' authors raw resourceId/type values")
   })
-})
+})
+
+describe('validateDeclaredSystemInterfaceReadiness', () => {
+  it('scans flat system.apiInterface markers', () => {
+    let error: unknown
+    try {
+      validateDeclaredSystemInterfaceReadiness('test-org', {
+        systems: {
+          sales: {
+            id: 'sales',
+            label: 'Sales',
+            order: 10,
+            apiInterface: {
+              lifecycle: 'active',
+              readinessProfile: 'sales.unknown.api'
+            }
+          }
+        }
+      })
+    } catch (caught) {
+      error = caught
+    }
+
+    expect(error).toBeInstanceOf(RegistryValidationError)
+    expect((error as RegistryValidationError).field).toBe('systems.sales.apiInterface.readinessProfile')
+  })
+})
 
 describe('ResourceRegistry - ExecutionInterface validation integration', () => {
   it('should throw on registry construction when interface misses required field', () => {

package/src/platform/registry/index.ts

@@ -11,21 +11,34 @@ export { ResourceRegistry } from './resource-registry'
 export type { DeploymentSpec, OrganizationRegistry, RemoteOrgConfig, SystemConfig } from './resource-registry'
 
 // Validation utilities
-export {
-  validateDeploymentSpec,
-  validateRelationships,
-  validateExecutionInterface,
-  validateResourceGovernance,
-  RegistryValidationError
-} from './validation'
-export type {
-  ResourceGovernanceModel,
-  ResourceGovernanceValidationIssue,
-  ResourceGovernanceValidationIssueType,
-  ResourceGovernanceValidationOptions,
-  ResourceGovernanceValidationResult,
-  ResourceValidatorMode
-} from './validation'
+export {
+  validateDeploymentSpec,
+  validateRelationships,
+  validateExecutionInterface,
+  validateResourceGovernance,
+  validateDeclaredSystemInterfaceReadiness,
+  RegistryValidationError
+} from './validation'
+export {
+  computeInterfaceReadiness,
+  SystemInterfaceReadinessError
+} from '../../business/acquisition/ontology-validation'
+export type {
+  ResourceGovernanceModel,
+  ResourceGovernanceValidationIssue,
+  ResourceGovernanceValidationIssueType,
+  ResourceGovernanceValidationOptions,
+  ResourceGovernanceValidationResult,
+  ResourceValidatorMode,
+  SystemInterfaceReadinessValidationIssue,
+  SystemInterfaceReadinessValidationResult
+} from './validation'
+export type {
+  SystemInterfaceReadinessIssue,
+  SystemInterfaceReadinessIssueFamily,
+  SystemInterfaceReadinessRequest,
+  SystemInterfaceReadinessResult
+} from '../../business/acquisition/ontology-validation'
 
 export { bindResourceDescriptor } from './types'
 

package/src/platform/registry/validation.ts

@@ -15,9 +15,14 @@ import type { OrganizationModel } from '../../organization-model/types'
 import { listAllSystems } from '../../organization-model/helpers'
 import {
   compileOrganizationOntology,
+  parseOntologyId,
   type OntologyKind,
   type ResolvedOntologyIndex
 } from '../../organization-model/ontology'
+import {
+  computeInterfaceReadiness,
+  type SystemInterfaceReadinessIssueFamily
+} from '../../business/acquisition/ontology-validation'
 import type { OmTopologyNodeRef } from '../../organization-model/domains/topology'
 import type {
   TriggerDefinition,
@@ -55,6 +60,7 @@ export type ResourceGovernanceValidationIssueType =
   | 'descriptor-mismatch'
   | 'missing-ontology-actions'
   | 'ontology-reference-missing'
+  | 'ontology-topology-grant-missing'
   | 'primary-action-mismatch'
   | 'topology-reference-missing'
 
@@ -87,6 +93,22 @@ export interface ResourceGovernanceValidationOptions {
   onWarning?: (issue: ResourceGovernanceValidationIssue) => void
 }
 
+export interface SystemInterfaceReadinessValidationIssue {
+  type: SystemInterfaceReadinessIssueFamily
+  orgName: string
+  systemPath: string
+  interfaceKey: string
+  code: string
+  path?: string
+  ref?: string
+  message: string
+}
+
+export interface SystemInterfaceReadinessValidationResult {
+  valid: boolean
+  issues: SystemInterfaceReadinessValidationIssue[]
+}
+
 function getResourceValidatorMode(explicitMode?: ResourceValidatorMode): ResourceValidatorMode {
   if (explicitMode) return explicitMode
   const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
@@ -150,6 +172,10 @@ function getRuntimeResources(resources: DeploymentSpec): Array<{
   ]
 }
 
+function isStaticPlatformAgentResource(resource: ResourceEntry): boolean {
+  return resource.kind === 'agent' && resource.agentKind === 'platform'
+}
+
 function hasOntologySources(organizationModel: ResourceGovernanceModel): boolean {
   return (
     organizationModel.ontology !== undefined ||
@@ -197,7 +223,8 @@ function addOntologyBindingIssues(
   issues: ResourceGovernanceValidationIssue[],
   orgName: string,
   resource: ResourceEntry,
-  ontologyIndex: ResolvedOntologyIndex | undefined
+  ontologyIndex: ResolvedOntologyIndex | undefined,
+  organizationModel: ResourceGovernanceModel
 ): void {
   const binding = resource.ontology
   if (binding === undefined) return
@@ -261,6 +288,88 @@ function addOntologyBindingIssues(
   validateRefs('writes', 'object', binding.writes)
   validateRefs('usesCatalogs', 'catalog', binding.usesCatalogs)
   validateRefs('emits', 'event', binding.emits)
+  addOntologyTopologyGrantIssues(issues, orgName, resource, organizationModel)
+}
+
+function addOntologyTopologyGrantIssues(
+  issues: ResourceGovernanceValidationIssue[],
+  orgName: string,
+  resource: ResourceEntry,
+  organizationModel: ResourceGovernanceModel
+): void {
+  const binding = resource.ontology
+  if (binding === undefined) return
+
+  const refs = [
+    ...(binding.actions ?? []),
+    ...(binding.primaryAction !== undefined ? [binding.primaryAction] : []),
+    ...(binding.reads ?? []),
+    ...(binding.writes ?? []),
+    ...(binding.usesCatalogs ?? []),
+    ...(binding.emits ?? [])
+  ]
+
+  for (const ontologyId of new Set(refs)) {
+    const parsed = parseOntologyId(ontologyId)
+    if (parsed.isGlobal || parsed.scope === resource.systemPath) continue
+    if (hasScopedTopologyGrant(organizationModel, resource, parsed.scope, ontologyId)) continue
+
+    const missingGrant = `systemInterfaceGrant(${resource.systemPath} -> ${parsed.scope}, resourceIds: ["${resource.id}"], ontologyIds: ["${ontologyId}"])`
+    addGovernanceIssue(
+      issues,
+      'ontology-topology-grant-missing',
+      orgName,
+      resource.id,
+      `[${orgName}] Resource '${resource.id}' in system '${resource.systemPath}' references ontology '${ontologyId}' from system '${parsed.scope}' without scoped topology grant '${missingGrant}'.`
+    )
+  }
+}
+
+function hasScopedTopologyGrant(
+  organizationModel: ResourceGovernanceModel,
+  resource: ResourceEntry,
+  targetSystemPath: string,
+  ontologyId: string
+): boolean {
+  return Object.values(organizationModel.topology?.relationships ?? {}).some((relationship) => {
+    if (relationship.kind !== 'uses') return false
+
+    const grant = relationship.metadata?.['systemInterfaceGrant']
+    if (!isSystemInterfaceGrantRecord(grant)) return false
+
+    return (
+      grant.consumer.systemPath === resource.systemPath &&
+      grant.provider.systemPath === targetSystemPath &&
+      grant.resourceIds.includes(resource.id) &&
+      grant.ontologyIds.includes(ontologyId)
+    )
+  })
+}
+
+function isSystemInterfaceGrantRecord(value: unknown): value is {
+  consumer: { systemPath: string; interfaceKey: string }
+  provider: { systemPath: string; interfaceKey: string }
+  resourceIds: string[]
+  ontologyIds: string[]
+} {
+  if (typeof value !== 'object' || value === null) return false
+  const grant = value as {
+    consumer?: { systemPath?: unknown; interfaceKey?: unknown }
+    provider?: { systemPath?: unknown; interfaceKey?: unknown }
+    resourceIds?: unknown
+    ontologyIds?: unknown
+  }
+
+  return (
+    typeof grant.consumer?.systemPath === 'string' &&
+    typeof grant.consumer.interfaceKey === 'string' &&
+    typeof grant.provider?.systemPath === 'string' &&
+    typeof grant.provider.interfaceKey === 'string' &&
+    Array.isArray(grant.resourceIds) &&
+    grant.resourceIds.every((id) => typeof id === 'string') &&
+    Array.isArray(grant.ontologyIds) &&
+    grant.ontologyIds.every((id) => typeof id === 'string')
+  )
 }
 
 function addTopologyIssues(
@@ -376,6 +485,10 @@ export function validateResourceGovernance(
 
     const runtimeResource = runtimeResourcesById.get(resource.id)
     if (!runtimeResource) {
+      if (isStaticPlatformAgentResource(resource)) {
+        continue
+      }
+
       addGovernanceIssue(
         issues,
         'missing-code-resource',
@@ -416,7 +529,7 @@ export function validateResourceGovernance(
       )
     }
 
-    addOntologyBindingIssues(issues, orgName, resource, ontologyIndex)
+    addOntologyBindingIssues(issues, orgName, resource, ontologyIndex, organizationModel)
   }
 
   for (const runtimeResource of runtimeResources) {
@@ -474,6 +587,70 @@ export function validateResourceGovernance(
   }
 }
 
+function addSystemInterfaceIssue(
+  issues: SystemInterfaceReadinessValidationIssue[],
+  orgName: string,
+  systemPath: string,
+  interfaceKey: string,
+  issue: {
+    family: SystemInterfaceReadinessIssueFamily
+    code: string
+    path?: string
+    ref?: string
+    message: string
+  }
+): void {
+  issues.push({
+    type: issue.family,
+    orgName,
+    systemPath,
+    interfaceKey,
+    code: issue.code,
+    path: issue.path,
+    ref: issue.ref,
+    message: `[${orgName}] ${issue.family}:${issue.code}: ${issue.message}`
+  })
+}
+
+/**
+ * Validates every explicitly declared API System Interface by deriving
+ * readiness from its scoped resources and ontology bindings.
+ *
+ * Contract-absent models remain valid until they opt in with
+ * `systems.*.apiInterface`.
+ */
+export function validateDeclaredSystemInterfaceReadiness(
+  orgName: string,
+  organizationModel: ResourceGovernanceModel | undefined
+): SystemInterfaceReadinessValidationResult {
+  const issues: SystemInterfaceReadinessValidationIssue[] = []
+  if (organizationModel === undefined) return { valid: true, issues }
+
+  const model = organizationModel as OrganizationModel
+
+  for (const { path, system } of listAllSystems(model)) {
+    if (system.apiInterface === undefined) continue
+
+    const interfaceKey = 'api'
+    const result = computeInterfaceReadiness(model, { systemPath: path, interfaceKey })
+    for (const issue of result.issues) {
+      addSystemInterfaceIssue(issues, orgName, path, interfaceKey, issue)
+    }
+  }
+
+  if (issues.length > 0) {
+    const first = issues[0]
+    throw new RegistryValidationError(
+      first.orgName,
+      `${first.systemPath}/${first.interfaceKey}`,
+      first.path ?? 'organizationModel.systems.apiInterface',
+      first.message
+    )
+  }
+
+  return { valid: true, issues }
+}
+
 // ============================================================================
 // Resource Validation
 // ============================================================================
@@ -540,6 +717,7 @@ export function validateDeploymentSpec(orgName: string, resources: DeploymentSpe
   })
 
   validateResourceGovernance(orgName, resources)
+  validateDeclaredSystemInterfaceReadiness(orgName, resources.organizationModel)
 }
 
 /**

package/src/reference/_generated/contracts.md

@@ -303,6 +303,36 @@ export type OrganizationModelSystemKind = z.infer<typeof SystemKindSchema>
 export type OrganizationModelSystemLifecycle = z.infer<typeof SystemLifecycleSchema>
 ```
 
+### `OrganizationModelSystemInterfaceKey`
+
+```typescript
+export type OrganizationModelSystemInterfaceKey = z.infer<typeof SystemInterfaceKeySchema>
+```
+
+### `OrganizationModelSystemInterfaceLifecycle`
+
+```typescript
+export type OrganizationModelSystemInterfaceLifecycle = z.infer<typeof SystemInterfaceLifecycleSchema>
+```
+
+### `OrganizationModelSystemInterfaceReadinessProfile`
+
+```typescript
+export type OrganizationModelSystemInterfaceReadinessProfile = z.infer<typeof SystemInterfaceReadinessProfileSchema>
+```
+
+### `OrganizationModelSystemApiInterface`
+
+```typescript
+export type OrganizationModelSystemApiInterface = z.infer<typeof SystemApiInterfaceSchema>
+```
+
+### `OrganizationModelSystemInterfaceRef`
+
+```typescript
+export type OrganizationModelSystemInterfaceRef = z.infer<typeof SystemInterfaceRefSchema>
+```
+
 ### `OrganizationModelSystemStatus`
 
 ```typescript
@@ -466,6 +496,20 @@ export type OrganizationModelTopologyRelationship = z.infer<typeof OmTopologyRel
 export type OrganizationModelTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
 ```
 
+### `OrganizationModelTopologySystemInterfaceGrant`
+
+```typescript
+export type OrganizationModelTopologySystemInterfaceGrant = z.infer<typeof OmTopologySystemInterfaceGrantSchema>
+```
+
+### `OrganizationModelTopologySystemInterfaceGrantMetadata`
+
+```typescript
+export type OrganizationModelTopologySystemInterfaceGrantMetadata = z.infer<
+  typeof OmTopologySystemInterfaceGrantMetadataSchema
+>
+```
+
 ### `OrganizationModelActions`
 
 ```typescript