# ============================================================================
# CleverAgents Resource Type Configuration Schema
# ============================================================================
#
# Formal YAML schema definition for resource type configuration files.
# Resource types define the schema-level constraints for categories of
# resources (e.g., git-checkout, fs-directory, fs-mount).
#
# Built-in resource types (git-checkout, fs-directory, fs-mount) are
# unnamespaced. Custom resource types must follow namespace/name format.
#
# Schema Version: 1
# ============================================================================

schema_version: "1"

# ----------------------------------------------------------------------------
# Top-Level Fields
# ----------------------------------------------------------------------------

fields:
  # ─── Identity ─────────────────────────────────────────────────
  name:
    type: string
    required: true
    description: >
      Resource type name. Built-in types use simple names (e.g.,
      git-checkout). Custom types use namespace/name format
      (e.g., myorg/custom-db).

  description:
    type: string
    required: false
    description: >
      Human-readable description of the resource type.

  # ─── Inheritance ──────────────────────────────────────────────
  inherits:
    type: string
    required: false
    description: >
      Parent resource type name. See ADR-042.

  # ─── Classification ────────────────────────────────────────────
  resource_kind:
    type: string
    required: true
    enum: [physical, virtual]
    description: >
      Classification of resources of this type as physical
      (tangible assets like files/directories) or virtual
      (derived/computed assets like branches).

  sandbox_strategy:
    type: string
    required: true
    enum: [git_worktree, copy_on_write, transaction_rollback, snapshot, none]
    description: >
      Default sandbox isolation strategy for resources of this type.

  # ─── Behavior ──────────────────────────────────────────────────
  user_addable:
    type: boolean
    required: false
    default: true
    description: >
      Whether users can manually add resources of this type
      via the CLI.

  built_in:
    type: boolean
    required: false
    default: false
    description: >
      Whether this is a built-in resource type. Built-in types
      can use unnamespaced names.

  # ─── CLI Arguments ─────────────────────────────────────────────
  cli_args:
    type: array
    required: false
    description: >
      CLI arguments accepted when adding a resource of this type.
      Each argument maps to a --<name> flag.
    items:
      type: object
      required_fields: [name]
      additional_properties: false
      fields:
        name:
          type: string
          required: true
          pattern: "^[a-z][a-z0-9_-]*$"
          description: "CLI argument name (lowercase, maps to --<name>)."
        type:
          type: string
          required: false
          enum: [string, integer, float, boolean, path]
          default: string
          description: "Data type of the argument."
        required:
          type: boolean
          required: false
          default: true
          description: "Whether the argument must be provided."
        description:
          type: string
          required: false
          description: "Human-readable description shown in help text."
        default:
          type: any
          required: false
          description: "Default value when argument is not provided."
        validation_pattern:
          type: string
          required: false
          description: "Regex pattern for string/path argument validation."

  # ─── DAG Constraints ───────────────────────────────────────────
  parent_types:
    type: array
    required: false
    items:
      type: string
    description: >
      Allowed parent resource type names in the resource DAG.

  child_types:
    type: array
    required: false
    items:
      type: string
    description: >
      Allowed child resource type names in the resource DAG.

  # ─── Auto-Discovery ────────────────────────────────────────────
  auto_discovery:
    type: object
    required: false
    description: >
      Handler-specific auto-discovery configuration.

  # ─── Equivalence (Virtual Types) ────────────────────────────────
  equivalence:
    type: object
    required: false
    description: >
      Equivalence rules for virtual resource deduplication.
      Required for virtual resource types.

  # ─── Handler ────────────────────────────────────────────────────
  handler:
    type: string
    required: false
    description: >
      Handler implementation reference (module:class or plugin name).

  # ─── Capabilities ──────────────────────────────────────────────
  capabilities:
    type: object
    required: false
    description: >
      Capability flags for resources of this type.
    fields:
      read:
        type: boolean
        default: true
        description: "Whether resources can be read."
      write:
        type: boolean
        default: true
        description: "Whether resources can be modified."
      sandbox:
        type: boolean
        default: true
        description: "Whether resources support sandbox isolation."
      checkpoint:
        type: boolean
        default: false
        description: "Whether resources support checkpoint/rollback."

# ----------------------------------------------------------------------------
# Constraints
# ----------------------------------------------------------------------------

required: [name, resource_kind, sandbox_strategy]
additional_properties: false

# ----------------------------------------------------------------------------
# Conditional Requirements
# ----------------------------------------------------------------------------
# - Virtual resource types (resource_kind: virtual) MUST include an
#   'equivalence' configuration block.
# - Custom types (built_in: false) MUST use namespace/name format.
