[MORPH-8427] document systems component update semantics

Author: Joshua Sachs

components/examples/systemRequest.json

@@ -6,6 +6,15 @@
     "layout": { "id": 1 },
     "enabled": true,
     "externalId": "ext-1234",
-    "config": {}
+    "config": {},
+    "components": [
+      {
+        "typeCode": "primary-node",
+        "name": "Primary Node",
+        "config": {
+          "hostname": "node1.example.com"
+        }
+      }
+    ]
   }
 }

components/examples/systemUpdateRequest.json

@@ -1,7 +1,19 @@
 {
   "system": {
-    "name": "my-system-renamed",
     "description": "Updated description",
-    "enabled": true
+    "components": [
+      {
+        "id": 10,
+        "name": "Primary Node Renamed",
+        "externalId": "ext-comp-10"
+      },
+      {
+        "typeCode": "storage-controller",
+        "name": "Storage Controller",
+        "config": {
+          "hostname": "storage1.example.com"
+        }
+      }
+    ]
   }
 }

components/schemas/systemComponentRequest.yaml

@@ -1,12 +1,17 @@
 type: object
 description: |
-  A component payload for use in uninitialized create and initialize requests.
-  Components are matched to layout component type definitions by `typeCode`.
-  Unmatched `typeCode` values are silently ignored.
+  A component payload for Systems create, update, and initialize requests.
+  Components can be matched by `id` or `typeCode`, depending on the endpoint behavior.
+  For create or new-component creation flows, `typeCode` identifies the component type to create.
 properties:
+  id:
+    type: integer
+    format: int64
+    description: Existing system component id. When supplied, endpoints that support component updates match by id first.
+    example: 10
   typeCode:
     type: string
-    description: The code of the layout component type this entry applies to.
+    description: The code of the component type this entry applies to.
     example: primary-node
   name:
     type: string
@@ -20,5 +25,3 @@ properties:
     type: object
     description: Arbitrary configuration data for the component.
     additionalProperties: true
-required:
-  - typeCode

components/schemas/systemCreate.yaml

@@ -1,4 +1,8 @@
 type: object
+description: |
+  Request body for creating a provider-backed system.
+  Standard create supports optional `components[]`. When supplied, component entries are
+  processed after the parent system is created and provider lifecycle begins.
 properties:
   name:
     type: string
@@ -38,6 +42,14 @@ properties:
     type: object
     description: Arbitrary configuration data for the system.
     additionalProperties: true
+  components:
+    type: array
+    description: |
+      Optional component payloads for create. Existing components are matched by `id` first,
+      then by `typeCode` when exactly one existing component matches. New components can be
+      created by supplying a valid `typeCode`.
+    items:
+      $ref: systemComponentRequest.yaml
 required:
   - name
   - type

components/schemas/systemInitialize.yaml

@@ -37,7 +37,9 @@ properties:
   components:
     type: array
     description: |
-      Optional component overrides. Components are matched by `id` first, then by `typeCode`.
-      Updates name, externalId, and config on matched skeleton components.
+      Optional component overrides. Components are matched by `id` first, then by `typeCode`
+      when exactly one existing component matches. Updates name, externalId, and config on
+      matched components, and can create a new component when a valid `typeCode` is supplied
+      with no existing match.
     items:
       $ref: systemComponentRequest.yaml

components/schemas/systemUpdate.yaml

@@ -2,6 +2,9 @@ type: object
 description: |
   Request body for updating an existing system. All fields are optional — only supplied
   fields are applied. The system's existing `type` cannot be changed via this endpoint.
+  If `components` is omitted, the existing component set is left unchanged.
+  If `components` is present, it is authoritative: the submitted array is treated as the
+  desired final component set, and existing components omitted from the array are removed.
 properties:
   name:
     type: string
@@ -39,3 +42,12 @@ properties:
         format: int64
         description: ID of the new system type layout.
         example: 2
+  components:
+    type: array
+    description: |
+      Optional authoritative component payloads. Components are matched by `id` first, then
+      by `typeCode` when exactly one existing component matches. New components can be created
+      by supplying a valid `typeCode`. When this field is present, omitted existing components
+      are removed from the system.
+    items:
+      $ref: systemComponentRequest.yaml

paths/api@infrastructure@systems.yaml

@@ -27,7 +27,12 @@ get:
 
 post:
   summary: Create a System
-  description: This endpoint creates a new system.
+  description: |
+    Creates a new provider-backed system.
+
+    Standard create supports optional `system.components[]` payloads. When supplied,
+    component entries are applied as part of the create lifecycle after the parent system
+    record is created.
   operationId: addSystem
   tags:
     - Systems

paths/api@infrastructure@systems@id.yaml

@@ -30,6 +30,22 @@ put:
   description: |
     Updates an existing system. All request body fields are optional — only supplied
     fields are applied. The system's `type` cannot be changed via this endpoint.
+
+    If `system.components` is omitted, the system's existing components are left unchanged.
+    If `system.components` is present, it is authoritative: the submitted array is treated
+    as the desired final component set, and existing components omitted from the array are removed.
+
+    **Component matching behavior** for `components[]` entries:
+
+    1. Match by `id` — if a payload supplies an `id`, the component with that id is updated.
+    2. Fallback to `typeCode` — if no `id` is supplied (or the id is not found), the system's
+       existing components are searched by `typeCode`. The fallback only applies when **exactly
+       one** existing component matches; if multiple components share the same `typeCode` the
+       entry is skipped (ambiguous — supply `id` to disambiguate).
+    3. New component creation — if no existing component matches and the `typeCode` is a valid
+       component type code, a new component is created.
+    4. Unknown `typeCode` — if no existing component matches and the `typeCode` does not
+       correspond to a known component type, the entry is silently skipped.
   operationId: updateSystem
   tags:
     - Systems

paths/api@infrastructure@systems@id@initialize.yaml

@@ -5,6 +5,8 @@ put:
     or `failed` status. This is the counterpart to `POST /api/infrastructure/systems/uninitialized`.
 
     Any fields supplied in the request body are applied to the system before provider invocation.
+    Unlike normal `PUT /api/infrastructure/systems/{id}` updates, initialize does not use
+    authoritative omission-based component removal semantics.
 
     **Component matching behavior** for `components[]` entries: