Feature: Fast init_or_upgrade early-return behavior
  As the test harness
  I need _fast_init_or_upgrade to skip Alembic migrations for existing databases
  So that parallel test execution does not hang on redundant migrations

  Background:
    Given the fast-init template-DB patch is installed

  @mock_only
  Scenario: Non-empty database with matching prefix skips original migration
    Given a non-empty SQLite database file with a matching scenario prefix
    When I call init_or_upgrade on the fast-init database
    Then the original init_or_upgrade should not have been invoked
    And the database file content should be unchanged

  @mock_only
  Scenario: Template is copied for a new database with matching prefix
    Given a non-existent SQLite database path with a matching scenario prefix
    When I call init_or_upgrade on the fast-init database
    Then the database file should be a copy of the template
    And the original init_or_upgrade should not have been invoked

  @mock_only
  Scenario: Existing empty database with matching prefix copies template
    Given an empty SQLite database file with a matching scenario prefix
    When I call init_or_upgrade on the fast-init database
    Then the database file should be a copy of the template
    And the original init_or_upgrade should not have been invoked

  @mock_only
  Scenario: Non-matching prefix delegates to original init_or_upgrade
    Given a SQLite database URL whose filename has a non-matching prefix
    When I call init_or_upgrade on the fast-init database
    Then the original init_or_upgrade should have been invoked exactly once

  @mock_only
  Scenario: In-memory SQLite delegates to original init_or_upgrade
    Given an in-memory SQLite database URL for fast-init testing
    When I call init_or_upgrade on the fast-init database
    Then the original init_or_upgrade should have been invoked exactly once

  @mock_only
  Scenario: Non-SQLite URL delegates to original init_or_upgrade
    Given a non-SQLite database URL for fast-init testing
    When I call init_or_upgrade on the fast-init database
    Then the original init_or_upgrade should have been invoked exactly once

  @mock_only
  Scenario: Bare sqlite:// URL delegates to original init_or_upgrade
    Given a bare sqlite:// database URL for fast-init testing
    When I call init_or_upgrade on the fast-init database
    Then the original init_or_upgrade should have been invoked exactly once

  @mock_only
  Scenario: Delegation forwards runner instance and keyword arguments
    Given a non-SQLite database URL for fast-init testing
    When I call init_or_upgrade with keyword arguments on the fast-init database
    Then the original init_or_upgrade should have been invoked exactly once
    And the original should have received the runner instance and keyword arguments

  # -----------------------------------------------------------------------
  # Process-global _INITIALIZED_DBS cache (issue #735)
  # -----------------------------------------------------------------------

  @mock_only
  Scenario: Second call for the same non-empty DB skips all logic via global cache
    Given a non-empty SQLite database file with a matching scenario prefix
    And the initialized-DB cache is cleared
    When I call init_or_upgrade on the fast-init database
    And I call init_or_upgrade on the fast-init database a second time
    Then the second init_or_upgrade call should have been a cache hit
    And the database file content should be unchanged

  @mock_only
  Scenario: Second call for a newly-copied template DB skips all logic via global cache
    Given a non-existent SQLite database path with a matching scenario prefix
    And the initialized-DB cache is cleared
    When I call init_or_upgrade on the fast-init database
    And I call init_or_upgrade on the fast-init database a second time
    Then the second init_or_upgrade call should have been a cache hit
    And the database file should be a copy of the template

  @mock_only
  Scenario: Global cache is cleared between scenarios
    Given a non-empty SQLite database file with a matching scenario prefix
    And the initialized-DB cache is cleared
    When I call init_or_upgrade on the fast-init database
    Then the URL should be present in the initialized-DB cache
    When the initialized-DB cache is cleared for a new scenario
    Then the URL should not be present in the initialized-DB cache

  @mock_only
  Scenario: Non-matching prefix URLs are not added to the global cache
    Given a SQLite database URL whose filename has a non-matching prefix
    And the initialized-DB cache is cleared
    When I call init_or_upgrade on the fast-init database
    Then the URL should not be present in the initialized-DB cache