@tdd_issue @tdd_issue_4466
Feature: ActorRegistry.add() accepts spec-compliant actor YAML formats
  As a developer following the specification
  I want the actor registry to accept YAML using the actors: map format
  So that spec-compliant actor definitions can be registered without error

  Background:
    Given a spec-yaml actor registry with no providers

  # ── actors: map with combined actor field ──────────────────────────

  Scenario: registry.add() accepts spec-compliant actors: map with combined actor field
    When I add a spec-compliant YAML with actors map and combined actor field
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor name should be "local/my-assistant"
    And the registered actor should exist in the actor service

  @tdd_issue @tdd_issue_4300
  Scenario: registry.add() accepts spec-compliant actors: map with separate provider and model
    When I add a spec-compliant YAML with actors map and separate provider model
    Then the actor should be registered with provider "anthropic" and model "claude-3"
    And the registered actor should exist in the actor service

  @tdd_issue @tdd_issue_4321 @tdd_issue_4300
  Scenario: registry.add() with nested-only type extracts provider/model from nested config
    When I add a YAML with type only in nested actors map and provider/model in nested config
    Then the actor should be registered with provider "custom" and model "fpga-model"
    And the registered actor name should be "local/fpga-strategist"
    And the registered actor should exist in the actor service

  # ── actors: map with unsafe flag ───────────────────────────────────

  Scenario: registry.add() preserves unsafe flag from nested spec-compliant config
    When I add a spec-compliant YAML with actors map and unsafe flag
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should be marked unsafe
    And the registered actor should exist in the actor service

  # ── agents: map (legacy) still works ───────────────────────────────

  Scenario: registry.add() continues to accept legacy agents: map format
    When I add a YAML with legacy agents map format
    Then the actor should be registered with provider "openai" and model "gpt-4o"

  # ── Top-level provider/model still works ───────────────────────────

  Scenario: registry.add() continues to accept top-level provider and model
    When I add a YAML with top-level provider and model fields
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should not be marked unsafe

  # ── Partial top-level + nested fallback ────────────────────────────

  Scenario: registry.add() with top-level provider only extracts model from nested actors map
    When I add a YAML with top-level provider only and model in nested actors map
    Then the actor should be registered with provider "top-level-provider" and model "nested-model"
    And the registered actor should exist in the actor service

  Scenario: registry.add() with top-level model only extracts provider from nested actors map
    When I add a YAML with top-level model only and provider in nested actors map
    Then the actor should be registered with provider "nested-provider" and model "top-level-model"
    And the registered actor should exist in the actor service

  # ── Top-level provider+model still picks up nested unsafe ───────────

  Scenario: registry.add() with top-level provider and model detects nested unsafe flag
    When I add a YAML with top-level provider and model and nested actors map with unsafe flag
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should be marked unsafe

  # ── Unsafe confirmation gate ───────────────────────────────────────

  Scenario: registry.add() rejects unsafe actor without confirmation
    When I attempt to add an unsafe YAML without the unsafe flag
    Then a spec-yaml ValidationError should be raised containing "unsafe"

  Scenario: registry.add() accepts unsafe actor with unsafe flag
    When I add an unsafe YAML with the unsafe flag set
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should be marked unsafe
    And the registered actor should exist in the actor service

  Scenario: registry.add() accepts unsafe actor with allow_unsafe flag
    When I add an unsafe YAML with the allow_unsafe flag set
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should be marked unsafe
    And the registered actor should exist in the actor service

  Scenario: registry.add() with allow_unsafe=True on non-unsafe YAML does not mark actor unsafe
    When I add a non-unsafe YAML with allow_unsafe flag set
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should not be marked unsafe

  # ── update=True path ───────────────────────────────────────────────

  Scenario: registry.add() with update=True overwrites an existing actor using spec-compliant YAML
    When I add a spec-compliant YAML with actors map and combined actor field
    And I add the same actor again with update=True and provider "anthropic" and model "claude-3"
    Then the actor should be registered with provider "anthropic" and model "claude-3"
    And the registered actor should exist in the actor service

  Scenario: registry.add() without update=True raises when actor already exists
    When I add a spec-compliant YAML with actors map and combined actor field
    And I attempt to add the same actor again without update=True
    Then a spec-yaml ValidationError should be raised containing "already exists"

  # ── schema_version and compiled_metadata parameters ────────────────

  Scenario: registry.add() forwards schema_version and compiled_metadata to upsert_actor
    When I add a spec-compliant YAML with schema_version "2.0" and compiled_metadata
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor schema version should be "2.0"
    And the registered actor compiled metadata should contain key "key"

  # ── registry.add() rejects YAML without a name field ────────────────

  Scenario: registry.add() rejects YAML without a name field
    When I attempt to add a YAML without a name field
    Then a spec-yaml ValidationError should be raised containing "name"

  # ── Top-level unsafe: true in add() ─────────────────────────────────

  Scenario: registry.add() rejects top-level unsafe YAML without confirmation
    When I attempt to add a YAML with top-level unsafe true and no flag
    Then a spec-yaml ValidationError should be raised containing "unsafe"

  Scenario: registry.add() accepts top-level unsafe YAML with unsafe flag
    When I add a YAML with top-level unsafe true and the unsafe flag set
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should be marked unsafe
    And the registered actor should exist in the actor service

  # ── M4: update=True creates actor when it doesn't exist ────────────

  Scenario: registry.add() with update=True creates actor when it doesn't exist
    When I add a spec-compliant YAML with actors map and combined actor field with update=True
    Then the actor should be registered with provider "openai" and model "gpt-4"
    And the registered actor should exist in the actor service

  # ── M5: v3 TOOL actor without provider/model propagates to upsert ──

  Scenario: registry.add() with v3 TOOL actor without provider or model raises an error from upsert_actor
    When I attempt to add a v3 TOOL YAML without provider or model
    Then an error should be raised from upsert_actor

  # ── M6: upsert_actor raises exception — error propagates ───────────

  Scenario: registry.add() propagates exception raised by upsert_actor
    When upsert_actor is configured to raise RuntimeError and I add a valid YAML
    Then a RuntimeError should have been propagated from add