#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
#  SPDX-License-Identifier: Apache-2.0
$schema: "https://json-schema.org/draft-07/schema#"
title: OverlayAgentPatch
# 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 ../agent.schema.yaml's own spec
# properties (single source of truth; see that file's `x-merge` blocks).
#
# Fields below whose overlay-patch shape is IDENTICAL to the base schema's
# just $ref into agent.schema.yaml's own property node -- one pointer, so the
# TYPE can never drift out of sync the way context_policy/params once did
# here (context_policy was dead: no consumer anywhere in the repo; params
# was a real field nothing declared on the base schema -- fixed by adding
# it to agent.schema.yaml directly). tools_remove was removed as a concept
# entirely: `tools: {"$op": {"remove": [...]}}` (list_ops, already native to
# spec.tools) already expresses the same subtraction without a second,
# separately-named attribute for the same operation.
#
# Fields whose overlay-patch shape is genuinely NOT the same as the base
# field (accepts the {"$op": {...}} list-ops sugar, or -- for design_pattern
# -- a stricter params/config shape than the base's permissive one) keep
# their own hand-written definition here; that's real, irreducible
# information, not duplication. Adding a new SIMPLE overlay-patchable field
# still needs one line here (a $ref pointer) alongside its definition in
# agent.schema.yaml -- JSON Schema has no "any property the base schema
# declares" wildcard -- but the type body itself never needs to be copied.
type: object
additionalProperties: false
patternProperties:
  "^x-": {}
properties:
  params:
    $ref: "../agent.schema.yaml#/properties/spec/properties/params"
  context:
    # Not a plain $ref: overlay-time patches accept the {"$op": {...}} sugar
    # per chunk name (add/remove/replace/clear a chunk's fragment list) --
    # a genuine shape difference from the base schema's plain ContextChunk map.
    $ref: "./overlay-collection-ops-context.schema.yaml"
  memory:
    $ref: "../agent.schema.yaml#/properties/spec/properties/memory"
  working_memory:
    $ref: "../agent.schema.yaml#/properties/spec/properties/working_memory"
  checkpoint:
    $ref: "../agent.schema.yaml#/properties/spec/properties/checkpoint"
  context_manager:
    $ref: "../agent.schema.yaml#/properties/spec/properties/context_manager"
  assembler:
    $ref: "../agent.schema.yaml#/properties/spec/properties/assembler"
  llm:
    $ref: "../agent.schema.yaml#/properties/spec/properties/llm"
  models:
    $ref: "./overlay-collection-ops-models.schema.yaml"
  description:
    $ref: "../agent.schema.yaml#/properties/spec/properties/description"
  tools_ref:
    $ref: "../agent.schema.yaml#/properties/spec/properties/tools_ref"
  behavior:
    $ref: "../agent.schema.yaml#/properties/spec/properties/behavior"
  context_sources:
    $ref: "../agent.schema.yaml#/properties/spec/properties/context_sources"
  memory_seed:
    $ref: "./overlay-collection-ops-memory-seed.schema.yaml"
  tools:
    $ref: "./overlay-collection-ops-tool.schema.yaml"
  skills:
    $ref: "./overlay-collection-ops-string.schema.yaml"
  design_pattern:
    # Object form is tighter than the base schema (design-pattern-config fragment).
    # String shorthand (plugin name) is the same as agent spec.
    # `$op.merge` keeps type/ref and only patches params (production overlays).
    oneOf:
      - type: "null"
      - type: string
        minLength: 1
      - type: object
        additionalProperties: false
        properties:
          type:
            type: string
          ref:
            type: string
          params:
            $ref: "./design-pattern-config.schema.yaml"
          config:
            $ref: "./design-pattern-config.schema.yaml"
          $op:
            type: object
            additionalProperties: false
            minProperties: 1
            properties:
              merge:
                type: object
                additionalProperties: false
                properties:
                  type:
                    type: string
                  params:
                    $ref: "./design-pattern-config.schema.yaml"
              replace:
                type: object
                additionalProperties: false
                properties:
                  type:
                    type: string
                  params:
                    $ref: "./design-pattern-config.schema.yaml"
              clear:
                type: boolean
                const: true
  budget:
    $ref: "../agent.schema.yaml#/properties/spec/properties/budget"
  control:
    oneOf:
      - type: "null"
      - $ref: "./overlay-collection-ops-control.schema.yaml"
  governance:
    oneOf:
      - type: "null"
      - $ref: "./overlay-collection-ops-governance.schema.yaml"
  hitl_contract:
    $ref: "../agent.schema.yaml#/properties/spec/properties/hitl_contract"
  user_io_contract:
    $ref: "../agent.schema.yaml#/properties/spec/properties/user_io_contract"
  observability:
    oneOf:
      - type: "null"
      - $ref: "./overlay-collection-ops-observability.schema.yaml"