spec_14: add or-slot and xor-slot documentation

Add comprehensive documentation for or-slots and xor-slots to RFC 14
(Canonical Job Specification):

- Extend the slot resource type definition to explain or-slot behavior
  when multiple sibling slot resources appear at the same level
- Add new xor_slot reserved resource type with full specification
- Add comparison table contrasting or-slots vs xor-slots
- Add Section 3 with three use cases demonstrating:
  - Use Case 3.1: Or-slots for same-level alternatives
  - Use Case 3.2: Xor-slots for different hierarchy prefixes
  - Use Case 3.3: Nested xor-slots
- Update JSON schema to include xor_slot as a valid resource vertex type

Or-slots allow sibling slot resources to be evaluated as alternatives
during traversal using dynamic programming. Xor-slots expand into
distinct jobspec branches before traversal and use first-match selection.

Both features require the flexible traverser implementation.

Assisted-by: Claude <noreply@anthropic.com>

Author: Zeke Chadron Blair Morton

data/spec_14/schema.json

@@ -70,20 +70,38 @@
         }
       ]
     },
+    "resource_vertex_xor_slot": {
+      "description": "special xor_slot resource type - exclusive alternative slot that is expanded before traversal",
+      "allOf": [
+        { "$ref": "#/definitions/resource_vertex_base" },
+        {
+          "properties": {
+            "type": { "const": "xor_slot" }
+          },
+          "required": ["label"]
+        }
+      ]
+    },
     "resource_vertex_other": {
       "description": "other (non-slot) resource type",
       "allOf": [
         { "$ref": "#/definitions/resource_vertex_base" },
         {
           "properties": {
-            "type": { "not": { "const": "slot" } }
+            "type": {
+              "allOf": [
+                { "not": { "const": "slot" } },
+                { "not": { "const": "xor_slot" } }
+              ]
+            }
           }
         }
       ]
     },
     "resource_vertex": {
       "oneOf":[
         { "$ref": "#/definitions/resource_vertex_slot" },
+        { "$ref": "#/definitions/resource_vertex_xor_slot" },
         { "$ref": "#/definitions/resource_vertex_other" }
       ]
     }

spec_14.rst

@@ -244,6 +244,72 @@ Reserved Resource Types
    to the program described in the jobspec, unless otherwise specified
    in the ``exclusive`` field of the associated resource.
 
+   When multiple ``slot`` resources appear as siblings at the same hierarchical
+   level (referred to informally as "or-slots"), they represent alternative slot
+   configurations. The flexible traverser MAY select any one of the sibling slots
+   to satisfy the request. This form is useful when alternatives share the same
+   task slot label and live at the same jobspec level. The traverser uses a
+   dynamic-programming approach to choose the slot configuration that yields the
+   largest total number of satisfiable slot matches. Once a slot shape has been
+   selected, concrete resources for each matched slot are chosen according to
+   the active match policy.
+
+**xor_slot**
+   A resource type of ``type: xor_slot`` SHALL indicate an alternative
+   resource grouping that is expanded into distinct jobspec branches before
+   traversal. Exactly one of the xor-slot alternatives will be allocated or
+   reserved. Each ``xor_slot`` is converted into a normal ``slot`` candidate
+   internally, and the flexible traverser tries the expanded branches sequentially
+   until a match is found (first-match strategy).
+
+   An ``xor_slot`` SHALL follow the same structural requirements as ``slot``,
+   including the requirement for a ``label`` key and at least one edge specified
+   using ``with:``.
+
+   This type is particularly useful when alternatives carry different subtree
+   prefixes (e.g., different hierarchical paths from the root) or when exclusive
+   same-level alternatives are needed. Unlike sibling ``slot`` resources which
+   are evaluated during traversal, ``xor_slot`` resources are expanded into
+   separate candidate jobspecs before matching begins. The order of xor-slots
+   effectively encodes preference, with earlier alternatives being tried first.
+
+   Nested ``xor_slot`` resources are supported. When processing nested xor-slots,
+   the expansion produces all combinations of the xor branches, and each
+   combination is tried as a separate candidate jobspec. To limit the number of
+   candidates and prevent combinatorial explosion, implementations SHALL provide
+   a configuration option (typically ``max-xor-candidates``) that sets the
+   maximum allowed number of candidate jobspecs.
+
+   Support for ``xor_slot`` requires the use of a flexible traverser
+   implementation. The expansion of ``xor_slot`` alternatives MAY be subject
+   to implementation-defined limits to prevent combinatorial explosion.
+
+Or-Slots vs Xor-Slots
+---------------------
+
+The following table summarizes the differences between or-slots (sibling
+``slot`` resources) and xor-slots (``xor_slot`` resources):
+
+.. list-table::
+   :widths: 30 35 35
+   :header-rows: 1
+
+   * - Feature
+     - Or-slots (sibling ``slot``)
+     - Xor-slots (``xor_slot``)
+   * - Expansion timing
+     - During traversal
+     - Before traversal
+   * - Selection algorithm
+     - Dynamic programming (optimal)
+     - First-match (sequential)
+   * - Use case
+     - Same-level alternatives with shared label
+     - Different hierarchy prefixes, exclusive same-level alternatives
+   * - Nesting support
+     - No
+     - Yes
+
 Tasks
 =====
 
@@ -721,6 +787,144 @@ Jobspec YAML
    .. literalinclude:: data/spec_14/use_case_2.9.yaml
       :language: yaml
 
+Section 3: Alternative Resource Configurations
+===============================================
+
+The following use cases demonstrate or-slots and xor-slots, which allow
+expressing alternative resource configurations within a single jobspec.
+These require the use of a flexible traverser implementation.
+
+Use Case 3.1
+   Request alternative slot configurations (or-slots)
+
+Specific Example
+   Request either a GPU-capable slot with 8 cores or a larger CPU-only
+   slot with 10 cores. Sibling ``slot`` resources at the same level
+   represent alternatives that are evaluated during traversal using
+   dynamic programming to maximize the number of satisfiable slots.
+
+Jobspec YAML
+   .. code-block:: yaml
+
+      version: 1
+      resources:
+        - type: slot
+          count: 1
+          label: default
+          with:
+            - type: core
+              count: 8
+            - type: gpu
+              count: 1
+        - type: slot
+          count: 1
+          label: default
+          with:
+            - type: core
+              count: 10
+      attributes:
+        system:
+          duration: 3600
+      tasks:
+        - command: [ "app" ]
+          slot: default
+          count:
+            per_slot: 1
+
+Use Case 3.2
+   Request exclusive alternative branches (xor-slots)
+
+Specific Example
+   Request either a socket-local GPU configuration or a node-scoped
+   memory configuration. The ``xor_slot`` type causes these alternatives
+   to be expanded into separate candidate jobspecs before matching begins.
+   The flexible traverser tries each candidate sequentially until one matches.
+
+Jobspec YAML
+   .. code-block:: yaml
+
+      version: 1
+      resources:
+        - type: xor_slot
+          count: 1
+          label: default
+          with:
+            - type: socket
+              count: 1
+              with:
+                - type: core
+                  count: 8
+                - type: gpu
+                  count: 1
+        - type: xor_slot
+          count: 1
+          label: default
+          with:
+            - type: node
+              count: 1
+              with:
+                - type: socket
+                  count: 1
+                  with:
+                    - type: core
+                      count: 6
+                    - type: memory
+                      count: 2
+      attributes:
+        system:
+          duration: 3600
+      tasks:
+        - command: [ "app" ]
+          slot: default
+          count:
+            per_slot: 1
+
+Use Case 3.3
+   Nested xor-slots with multiple hierarchy levels
+
+Specific Example
+   Request a slot with nested xor alternatives. This demonstrates
+   that ``xor_slot`` resources can be nested, allowing complex
+   alternative resource hierarchies to be expressed.
+
+Jobspec YAML
+   .. code-block:: yaml
+
+      version: 1
+      resources:
+        - type: node
+          count: 1
+          with:
+            - type: xor_slot
+              count: 1
+              label: default
+              with:
+                - type: socket
+                  count: 2
+                  with:
+                    - type: xor_slot
+                      count: 1
+                      label: accel
+                      with:
+                        - type: core
+                          count: 4
+                        - type: gpu
+                          count: 1
+                    - type: xor_slot
+                      count: 1
+                      label: accel
+                      with:
+                        - type: core
+                          count: 8
+      attributes:
+        system:
+          duration: 3600
+      tasks:
+        - command: [ "app" ]
+          slot: default
+          count:
+            per_slot: 1
+
 References
 **********