@elevasis/core 0.37.0 → 0.39.0

package/src/platform/registry/validation.ts

@@ -23,13 +23,15 @@ import {
   computeInterfaceReadiness,
   type SystemInterfaceReadinessIssueFamily
 } from '../../business/acquisition/ontology-validation'
+import { SYSTEM_INTERFACE_PROFILES } from '../../organization-model/domains/systems'
 import type { OmTopologyNodeRef } from '../../organization-model/domains/topology'
 import type {
   TriggerDefinition,
   ResourceRelationships,
   ExternalResourceDefinition,
   HumanCheckpointDefinition,
-  ResourceType
+  ResourceType,
+  ApiInterfaceConformanceGap
 } from './types'
 
 // ============================================================================
@@ -612,6 +614,77 @@ function addSystemInterfaceIssue(
   })
 }
 
+/**
+ * Detects systems that are API-backed (have resources with non-empty ontology
+ * bindings), CAN adopt a platform-cataloged `apiInterface` readinessProfile
+ * (system path appears in `SYSTEM_INTERFACE_PROFILES`), but have not declared
+ * `apiInterface` in the Organization Model.
+ *
+ * Originally broad-by-design (flagged any system with ontology actions/writes
+ * lacking apiInterface). Tightened in @elevasis/sdk@1.30.1 after the template
+ * surfaced the unactionable-paradox case: custom systems (e.g. `sys.operations`,
+ * `sys.notifications`) have valid `ontology.actions` bindings but cannot adopt
+ * one of the closed-catalog readiness profiles, AND the documented guidance
+ * ("Custom Systems should not declare apiInterface") is incompatible with the
+ * broad heuristic. The gate now only flags systems where adoption is even
+ * possible — i.e. the system path matches a cataloged profile's `systemPath`.
+ *
+ * A system is flagged when ALL of:
+ *   (a) `system.apiInterface === undefined`, AND
+ *   (b) at least one resource in `organizationModel.resources` has
+ *       `resource.systemPath` matching the system path AND
+ *       `resource.ontology` non-empty (has `actions` and/or `writes` defined), AND
+ *   (c) the system path appears as a cataloged `systemPath` in
+ *       `SYSTEM_INTERFACE_PROFILES` (so adopting a profile is actually possible).
+ *
+ * Returns `[]` when `organizationModel` is undefined or no gaps are found.
+ */
+export function detectMissingApiInterfaceDeclarations(
+  orgName: string,
+  organizationModel: OrganizationModel | undefined
+): ApiInterfaceConformanceGap[] {
+  if (organizationModel === undefined) return []
+
+  // Build a map of system path → resource IDs for resources with non-empty ontology.
+  const apiBoundResourcesBySystemPath = new Map<string, string[]>()
+  for (const resource of Object.values(organizationModel.resources ?? {})) {
+    const ontology = resource.ontology
+    if (ontology === undefined) continue
+    const hasOntologyBindings =
+      (ontology.actions !== undefined && ontology.actions.length > 0) ||
+      (ontology.writes !== undefined && ontology.writes.length > 0)
+    if (!hasOntologyBindings) continue
+    const existing = apiBoundResourcesBySystemPath.get(resource.systemPath)
+    if (existing) {
+      existing.push(resource.id)
+    } else {
+      apiBoundResourcesBySystemPath.set(resource.systemPath, [resource.id])
+    }
+  }
+
+  if (apiBoundResourcesBySystemPath.size === 0) return []
+
+  // Closed-catalog filter: a system is only a candidate for missing apiInterface
+  // if it could actually adopt one of the cataloged platform profiles.
+  const catalogedSystemPaths = new Set<string>(SYSTEM_INTERFACE_PROFILES.map((profile) => profile.systemPath))
+
+  const gaps: ApiInterfaceConformanceGap[] = []
+
+  for (const { path, system } of listAllSystems(organizationModel)) {
+    if (system.apiInterface !== undefined) continue
+    if (!catalogedSystemPaths.has(path)) continue
+    const resourceIds = apiBoundResourcesBySystemPath.get(path)
+    if (!resourceIds || resourceIds.length === 0) continue
+    gaps.push({
+      systemPath: path,
+      resourceIds,
+      message: `[${orgName}] System '${path}' has ${resourceIds.length} API-backed resource(s) (${resourceIds.join(', ')}) but no apiInterface declaration.`
+    })
+  }
+
+  return gaps
+}
+
 /**
  * Validates every explicitly declared API System Interface by deriving
  * readiness from its scoped resources and ontology bindings.