objectstate 1.2.0__tar.gz → 1.3.1__tar.gz

{objectstate-1.2.0 → objectstate-1.3.1}/.github/workflows/publish.yml

@@ -4,6 +4,12 @@ on:
   push:
     tags:
       - 'v*'
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing release tag to publish
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -13,6 +19,8 @@ jobs:
   build-and-publish:
     name: Build and publish to PyPI
     runs-on: ubuntu-latest
+    env:
+      RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
     environment:
       name: pypi
       url: https://pypi.org/p/objectstate
@@ -20,6 +28,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ env.RELEASE_TAG }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -42,6 +52,7 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
+          tag_name: ${{ env.RELEASE_TAG }}
           files: dist/*
           generate_release_notes: true
         env:

{objectstate-1.2.0 → objectstate-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objectstate
-Version: 1.2.0
+Version: 1.3.1
 Summary: Generic lazy dataclass configuration framework with dual-axis inheritance and contextvars-based resolution
 Project-URL: Homepage, https://github.com/OpenHCSDev/objectstate
 Project-URL: Documentation, https://objectstate.readthedocs.io
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: dill>=0.4.0
-Requires-Dist: python-introspect>=0.1.6
+Requires-Dist: python-introspect<0.3,>=0.2.0
 Provides-Extra: dev
 Requires-Dist: black==26.5.1; extra == 'dev'
 Requires-Dist: mypy==2.3.0; extra == 'dev'

objectstate-1.3.1/docs/performance/canonical-context-type-resolution-20261005.json

@@ -0,0 +1,45 @@
+{
+  "status": "PASS_PRIVATE_SAVED_CONSUMER_ONLY",
+  "baseline": "Installed ObjectState 1.3.0 from merged 7db151907a52a95743fbeae5a64220b28bc56690, PythonIntrospect 0.2.0",
+  "change": "resolve_with_provenance queries the existing canonical type-keyed maps admitted by extract_all_configs instead of scanning every value and reconstructing each owner type.",
+  "controls": {
+    "passed": 27,
+    "command": "PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m pytest -q -o addopts= -p no:cacheprovider tests/test_context_manager.py tests/test_object_state_restore.py tests/test_callable_baseline.py tests/test_placeholder.py",
+    "laws": "Canonical map admission, duplicate/invalid declarations, MRO/None/provenance, real constructors/default factories, callable identity, detached mutable alias graphs"
+  },
+  "one_pair": [
+    {
+      "case": "Illumination Example3",
+      "first_job": true,
+      "steps": 10,
+      "baseline_seconds": 0.08565246313810349,
+      "candidate_seconds": 0.0676199309527874,
+      "saved_seconds": 0.018032532185316086
+    },
+    {
+      "case": "Original 3D monolayer",
+      "first_job": false,
+      "steps": 31,
+      "baseline_seconds": 0.2247260957956314,
+      "candidate_seconds": 0.19058690778911114,
+      "saved_seconds": 0.03413918800652027
+    }
+  ],
+  "parity": "Exact typed configuration/steps, provenance, canonical source and ancestor scopes PASS",
+  "guards": "Before/after source, actual eight installed dependency trees and wheel metadata, four native ABIs, authored input sources and helper hashes PASS; all owned processes terminal",
+  "preserved": "Context constructors/merges and extraction epochs, selected live field reads, same-type scope precedence, MRO class-first precedence, None inheritance, AttributeError behavior, fallback provenance and direct-owner default factories",
+  "limits": [
+    "ONE saved-owner pair, not a whole compiler, ordinary runtime or total speedup measurement.",
+    "Normal full Registry READY, document parsing, orchestrator initialization, graph/provider admission and execution were outside the clocks.",
+    "3D follows Illumination in each process; it is not an independent cold first-job observation.",
+    "This generalized cleanup is not the dominant performance route; the first-case 18 ms saving does not close the remaining total target gap.",
+    "Arbitrary corruption of the admitted map/type keys or in-operation instance __class__ rebinding was not established equivalent. Mutable field values remain live.",
+    "The public resolver accepting manually supplied maps is unchanged. No new cache, value snapshot or installed dependency mutation."
+  ],
+  "custody": {
+    "private_packet": "20261005/canonical-context-type-resolution-v1",
+    "baseline_resolver_sha256": "17fcda62912050bdcdd018bee2fca5f81c2f4940c5f27f2af3dc19b7691e1fb0",
+    "candidate_resolver_sha256": "e8e939bfb97ad2d07cb0f4893e43229fc30926274e7bdc7a4491264feeaeae97",
+    "version_change": "1.3.1 is a separate patch release; immutable 1.3.0 tags and installed wheel are untouched."
+  }
+}

{objectstate-1.2.0 → objectstate-1.3.1}/pyproject.toml

@@ -25,7 +25,7 @@ keywords = ["configuration", "dataclass", "lazy", "inheritance", "contextvars",
 
 dependencies = [
     "dill>=0.4.0",
-    "python-introspect>=0.1.6",
+    "python-introspect>=0.2.0,<0.3",
 ]
 
 [project.optional-dependencies]

{objectstate-1.2.0 → objectstate-1.3.1}/src/objectstate/__init__.py

@@ -216,7 +216,7 @@ __all__ = [
     'ObjectStateEditSession',
 ]
 
-__version__ = "1.2.0"
+__version__ = "1.3.1"
 __author__ = 'OpenHCS Team'
 __description__ = 'Generic configuration framework for lazy dataclass resolution'
 

{objectstate-1.2.0 → objectstate-1.3.1}/src/objectstate/dual_axis_resolver.py

@@ -324,24 +324,23 @@ def resolve_with_provenance(container_type: type, field_name: str) -> Tuple[Any,
         if _debug and field_name == 'well_filter':
             logger.debug(f"🔍   Phase 1 - Layer scope={scope_id!r}, checking same-type only (inner to outer)")
 
-        for config_instance in layer_configs.values():
-            instance_base = _normalize_to_base(type(config_instance))
-            if _debug and field_name in ('well_filter', 'enabled') and instance_base == container_base:
-                logger.debug(f"🔍     FOUND same-type config: {instance_base.__name__} @ scope={scope_id}")
-            if instance_base == container_base:  # Same-type only, no MRO
-                try:
-                    value = object.__getattribute__(config_instance, field_name)
-                    if _debug and field_name in ('well_filter', 'enabled'):
-                        logger.debug(f"🔍     {container_base.__name__}.{field_name} @ scope={scope_id} = {value!r} (from object.__getattribute__)")
-                    if value is not None:
-                        # Found concrete value in hierarchy - return immediately
-                        if _debug and field_name in ('well_filter', 'enabled'):
-                            logger.debug(f"🔍     FOUND concrete value in hierarchy at scope={scope_id!r}, returning {value!r}")
-                        return value, scope_id, container_base
-                    # Don't set fallback here - let Phase 2 walk MRO to find
-                    # the highest type that defines this field
-                except AttributeError:
-                    continue
+        # extract_all_configs admits one instance per canonical owner type.
+        config_instance = layer_configs.get(container_base)
+        if config_instance is None:
+            continue
+        try:
+            value = object.__getattribute__(config_instance, field_name)
+            if _debug and field_name in ('well_filter', 'enabled'):
+                logger.debug(f"🔍     {container_base.__name__}.{field_name} @ scope={scope_id} = {value!r} (from object.__getattribute__)")
+            if value is not None:
+                # Found concrete value in hierarchy - return immediately
+                if _debug and field_name in ('well_filter', 'enabled'):
+                    logger.debug(f"🔍     FOUND concrete value in hierarchy at scope={scope_id!r}, returning {value!r}")
+                return value, scope_id, container_base
+            # Don't set fallback here - let Phase 2 walk MRO to find
+            # the highest type that defines this field
+        except AttributeError:
+            continue
 
     # PHASE 2: MRO fallback - no concrete value in hierarchy, try MRO inheritance
     #
@@ -367,25 +366,24 @@ def resolve_with_provenance(container_type: type, field_name: str) -> Tuple[Any,
 
         # Walk scopes from inner→outer for this MRO type
         for scope_id, layer_configs in reversed(all_layer_configs):
-            for config_instance in layer_configs.values():
-                instance_base = _normalize_to_base(type(config_instance))
-                if instance_base != mro_type:
-                    continue
+            config_instance = layer_configs.get(mro_type)
+            if config_instance is None:
+                continue
 
-                saw_type_anywhere = True
-                last_scope_for_type = scope_id  # update as we walk inner→outer (last = outermost)
+            saw_type_anywhere = True
+            last_scope_for_type = scope_id  # update as we walk inner→outer (last = outermost)
 
-                try:
-                    value = object.__getattribute__(config_instance, field_name)
-                except AttributeError:
-                    continue
+            try:
+                value = object.__getattribute__(config_instance, field_name)
+            except AttributeError:
+                continue
 
-                if _debug and field_name == 'well_filter':
-                    logger.debug(f"🔍     MRO: {mro_type.__name__}.{field_name} @ {scope_id!r} = {value!r}")
+            if _debug and field_name == 'well_filter':
+                logger.debug(f"🔍     MRO: {mro_type.__name__}.{field_name} @ {scope_id!r} = {value!r}")
 
-                if value is not None:
-                    # Found MRO-inherited value
-                    return value, scope_id, mro_type
+            if value is not None:
+                # Found MRO-inherited value
+                return value, scope_id, mro_type
 
         # No non-None found for this MRO type across any scope.
         # Record fallback for the FIRST MRO type that exists anywhere.

{objectstate-1.2.0 → objectstate-1.3.1}/src/objectstate/object_state.py

@@ -529,7 +529,7 @@ class ObjectState:
             Dictionary mapping dotted parameter paths to their descriptions (value may be None).
             E.g., {'well_filter_config.well_filter': 'Filter wells by...'}
         """
-        return dict(self._parameter_descriptions)
+        return self._parameter_structure.descriptions
 
     def type_for_path(self, field_path: str) -> ParameterOwner:
         """Return the ObjectState-recorded type for a dotted field path.
@@ -769,27 +769,13 @@ class ObjectState:
 
         Returns dict mapping param_name -> info object with .param_type, .default_value, and .description attributes.
         """
-        from types import SimpleNamespace
-
-        exclude_params = exclude_params or []
-        result = {}
-
         # NOTE: python_introspect is a required dependency; fail loud if missing.
         # UnifiedParameterAnalyzer is responsible for correctness guarantees:
         # - defaults come from type/signature (never from instance)
         # - current instance values are accessed in a lazy-safe way (if needed)
         from python_introspect import UnifiedParameterAnalyzer
 
-        ua_info = UnifiedParameterAnalyzer.analyze(obj, exclude_params=exclude_params)
-        for name, info in ua_info.items():
-            if name in exclude_params:
-                continue
-            result[name] = SimpleNamespace(
-                param_type=getattr(info, "param_type", Any),
-                default_value=getattr(info, "default_value", None),
-                description=getattr(info, "description", None),
-            )
-        return result
+        return UnifiedParameterAnalyzer.analyze(obj, exclude_params=exclude_params)
 
     @staticmethod
     def _get_nested_dataclass_type(param_type: Any) -> type | None:
@@ -1219,7 +1205,10 @@ class ObjectState:
         raw_value = self.parameters.get(path.value, MISSING)
         resolved_value = self.get_resolved_value(path.value)
         saved_resolved_value = self.get_saved_resolved_value(path.value)
-        signature_default_value = self._signature_defaults.get(path.value, MISSING)
+        declaration = self._parameter_structure.declarations.get(path.value)
+        signature_default_value = (
+            declaration.default_value if declaration is not None else MISSING
+        )
 
         return build_subfield_semantic_index(
             owner_field_path=path,
@@ -1557,22 +1546,6 @@ class ObjectState:
     ) -> None:
         self._parameter_structure.direct_paths = value
 
-    @property
-    def _signature_defaults(self) -> dict[str, Any]:
-        return self._parameter_structure.defaults
-
-    @_signature_defaults.setter
-    def _signature_defaults(self, value: dict[str, Any]) -> None:
-        self._parameter_structure.defaults = value
-
-    @property
-    def _parameter_descriptions(self) -> dict[str, str | None]:
-        return self._parameter_structure.descriptions
-
-    @_parameter_descriptions.setter
-    def _parameter_descriptions(self, value: dict[str, str | None]) -> None:
-        self._parameter_structure.descriptions = value
-
     @property
     def _exclude_param_names(self) -> list[str]:
         return self._parameter_structure.exclusions
@@ -1893,16 +1866,17 @@ class ObjectState:
 
         # Use signature defaults (CLASS defaults), not instance values
         # This ensures reset goes back to None for lazy fields, not saved concrete values
-        default_value = self._signature_defaults.get(param_name)
+        declaration = self._parameter_structure.declarations.get(param_name)
+        default_value = declaration.default_value if declaration is not None else None
         self.update_parameter(param_name, default_value)
 
     def signature_default(self, param_name: str) -> Any:
         """Return the signature default recorded for one flat parameter path."""
-        if param_name not in self._signature_defaults:
+        if param_name not in self._parameter_structure.declarations:
             raise KeyError(
                 f"No signature default recorded for parameter {param_name!r}."
             )
-        return self._signature_defaults[param_name]
+        return self._parameter_structure.declarations[param_name].default_value
 
     def get_current_values(self) -> dict[str, Any]:
         """
@@ -2014,14 +1988,13 @@ class ObjectState:
         """Compute signature-diff set from parameters vs defaults.
 
         Any field that differs from its signature default is included.
-        Nested dataclass container fields are implicitly excluded since
-        they don't have entries in _signature_defaults (only leaf fields do).
+        Defaults come from the same declarations used for reset, including
+        declared nested containers.
         """
         result = set()
         for k, v in self.parameters.items():
-            if k in self._signature_defaults:
-                # Direct dict key access - no special behavior to avoid
-                sig_default = self._signature_defaults[k]
+            if k in self._parameter_structure.declarations:
+                sig_default = self._parameter_structure.declarations[k].default_value
                 is_diff = v != sig_default
                 if is_diff:
                     result.add(k)
@@ -2577,10 +2550,7 @@ class ObjectState:
                 except AttributeError:
                     current_value = info.default_value
 
-            # Store description entry for the dotted path. Even if the specific
-            # parameter has no description, ensure the dotted key exists so
-            # callers can rely on presence of the full path (value may be None).
-            structure.descriptions[dotted_path] = getattr(info, 'description', None)
+            structure.declarations[dotted_path] = info
 
             # Check if this is a nested dataclass
             # First try from type annotation, then fall back to checking actual value
@@ -2599,13 +2569,6 @@ class ObjectState:
                 # Store the nested dataclass instance in parameters (needed for UI rendering)
                 parameters[dotted_path] = current_value
 
-                # Container resets follow the same declared-default authority as
-                # leaf resets. Lazy dataclass fields retain their intentional
-                # ``None`` default, while callable parameters with concrete
-                # dataclass defaults can be restored after an authored override
-                # is removed.
-                structure.defaults[dotted_path] = info.default_value
-
                 # Recurse into nested dataclass for child fields
                 cls._extract_all_parameters_flat(
                     current_value, parameters, structure, prefix=dotted_path, exclude_params=[]
@@ -2615,9 +2578,6 @@ class ObjectState:
                 parameters[dotted_path] = current_value
                 # Store the owner target that has this field.
                 structure.owner_paths[dotted_path] = owner_target
-                # Store signature default for reset functionality (flattened)
-                # info.default_value is now guaranteed to be the CLASS signature default
-                structure.defaults[dotted_path] = info.default_value
 
     def _replace_parameter_structure(
         self,

{objectstate-1.2.0 → objectstate-1.3.1}/src/objectstate/parameter_structure.py

@@ -6,6 +6,8 @@ import copy
 from dataclasses import dataclass, field, fields, is_dataclass, replace
 from typing import Any
 
+from python_introspect import ParameterInfo
+
 from objectstate.field_access import DottedFieldPath
 from objectstate.parameter_owner import ParameterOwner
 
@@ -18,11 +20,22 @@ class ParameterStructure:
     direct_paths: dict[DottedFieldPath, tuple[DottedFieldPath, ...]] = field(
         default_factory=dict
     )
-    defaults: dict[str, Any] = field(default_factory=dict)
-    descriptions: dict[str, str | None] = field(default_factory=dict)
+    declarations: dict[str, ParameterInfo] = field(default_factory=dict)
     exclusions: list[str] = field(default_factory=list)
     excluded_values: dict[str, Any] = field(default_factory=dict)
 
+    @property
+    def defaults(self) -> dict[str, Any]:
+        """Derive editor reset values from admitted parameter declarations."""
+
+        return {path: info.default_value for path, info in self.declarations.items()}
+
+    @property
+    def descriptions(self) -> dict[str, str | None]:
+        """Request presentation help only when a consumer reads it."""
+
+        return {path: info.description for path, info in self.declarations.items()}
+
     def is_container_parameter(
         self, name: str, value: Any, parameters: dict[str, Any]
     ) -> bool:

{objectstate-1.2.0 → objectstate-1.3.1}/tests/test_construction_history.py

@@ -148,7 +148,8 @@ def test_same_scope_callable_owner_and_schema_restore_without_replacing_state():
         assert ObjectStateRegistry.get_by_scope("callable") is state
         assert state.object_instance is function
         assert set(state.parameters) == parameters
-        assert set(state._signature_defaults) == parameters
+        for name in parameters:
+            state.signature_default(name)
         assert set(state._path_to_type) == parameters