State Management

Requirements

Requirement: Immutable Global State

The system SHALL provide an immutable Globals dataclass that contains all framework state and cannot be modified after creation.

Scenario: State creation during initialization

  • WHEN prepare() completes successfully

  • THEN a Globals instance is returned with all fields populated

  • AND all fields are immutable (frozen dataclass with accretive containers)

Scenario: State access by application code

  • WHEN application code accesses Globals fields

  • THEN field values are consistent with the state at initialization time

  • AND no field can be modified through the Globals reference

Scenario: State serialization

  • WHEN Globals.as_dictionary() is called

  • THEN a shallow copy of all state fields is returned as a dictionary

  • AND the returned dictionary is independent of the Globals instance

Requirement: Location Provision

The system SHALL provide methods on Globals for resolving platform-specific locations with configuration overrides.

Scenario: Default cache location

  • WHEN Globals.provide_cache_location() is called without arguments

  • THEN the platform-default cache directory is returned

  • AND the directory path is derived from platformdirs

Scenario: Location with configuration override

  • WHEN configuration contains a locations.cache entry

  • THEN Globals.provide_cache_location() uses the configured path

  • AND template variables ({user_cache}, {user_home}, {application_name}) are expanded

Scenario: Location with subpath appendages

  • WHEN Globals.provide_data_location('subdir', 'file.txt') is called

  • THEN the subpath is appended to the resolved base location

  • AND the full path is returned

Requirement: State Field Composition

The Globals dataclass SHALL contain fields for application metadata, configuration, platform directories, distribution information, and the exit stack.

Scenario: Complete state assembly

  • WHEN prepare() assembles the Globals instance

  • THEN the following fields are populated:

    • application: Information instance with name, publisher, version

    • configuration: accretive dictionary with merged configuration

    • directories: PlatformDirs instance for the application

    • distribution: Information instance with deployment mode

    • exits: the AsyncExitStack passed to prepare()