#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
#  SPDX-License-Identifier: Apache-2.0
$schema: "https://json-schema.org/draft-07/schema#"
title: OverlayMasPatch
# Structural (type-shape) validation ONLY for `mas-ctl validate <overlay.yaml>`.
# Merge BEHAVIOR (which fields are patchable, how they merge) is no longer
# read from this file at all -- ctl/src/mas/ctl/overlay/merge.py reads
# x-merge annotations straight off ../mas.schema.yaml's own spec properties
# (single source of truth; see that file's `x-merge` blocks). Same pattern
# as overlay-agent-patch.schema.yaml -- see that file's header comment.
#
# `governance` was removed from here: merge_mas_overlay special-cases the
# key (excludes it from the generic x-merge dispatch) but has never had a
# merge implementation for it -- patching spec.governance via a MAS-targeted
# overlay was a silent no-op with zero test coverage. Agent-level governance
# (a different, real, working mechanism) is unaffected.
type: object
additionalProperties: false
patternProperties:
  "^x-": {}
properties:
  agency:
    $ref: "../mas.schema.yaml#/properties/spec/properties/agency"
  workflow:
    $ref: "../mas.schema.yaml#/properties/spec/properties/workflow"
  telemetry:
    $ref: "../mas.schema.yaml#/properties/spec/properties/telemetry"
  params:
    $ref: "../mas.schema.yaml#/properties/spec/properties/params"
  capabilities:
    $ref: "../mas.schema.yaml#/properties/spec/properties/capabilities"
  intent:
    $ref: "../mas.schema.yaml#/properties/spec/properties/intent"
  agents:
    # Not a plain $ref: two genuinely different accepted shapes (per-agent
    # override map, or a {"$op": {...}} collection op) that only make sense
    # in overlay context -- irreducible, not duplication.
    oneOf:
      - type: object
        properties:
          $entry:
            description: >
              Patch the agent named by spec.workflow.entry (after this overlay's
              workflow patch) without hardcoding the agency id. Specialists are
              untouched.
            $ref: "./agent-patch.schema.yaml"
          $all:
            description: Patch every agent in spec.agency.agents.
            $ref: "./agent-patch.schema.yaml"
          $not-entry:
            description: Patch every agency agent except spec.workflow.entry.
            $ref: "./agent-patch.schema.yaml"
          $delegates:
            description: >
              Patch agents listed on workflow.nodes[entry].delegates_to.
            $ref: "./agent-patch.schema.yaml"
        additionalProperties:
          oneOf:
            # A MAS overlay may patch an agent through its wrapped `spec`
            # shape, while existing overlays also use direct agent-patch fields
            # such as `tools` and `context`.
            - type: object
              additionalProperties: false
              properties:
                ref:
                  type: string
                spec:
                  $ref: "./agent-patch.schema.yaml"
            - $ref: "./agent-patch.schema.yaml"
      - type: object
        additionalProperties: false
        required: [$op]
        properties:
          $op:
            type: object
            additionalProperties: false
            minProperties: 1
            properties:
              replace:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required: [id, ref]
                  properties:
                    id:
                      type: string
                    ref:
                      type: string
              add:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required: [id, ref]
                  properties:
                    id:
                      type: string
                    ref:
                      type: string
              remove:
                type: array
                items:
                  type: string
              clear:
                type: boolean
                const: true