objectstate 1.2.0__tar.gz → 2.0.0__tar.gz

{objectstate-1.2.0 → objectstate-2.0.0}/.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-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objectstate
-Version: 1.2.0
+Version: 2.0.0
 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-2.0.0/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-2.0.0}/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-2.0.0}/scripts/verify_release_ready.py

@@ -211,13 +211,8 @@ def check_github_workflow():
         print("  ❌ .github/workflows/publish.yml not found")
         return False
     
-    content = workflow_file.read_text()
-    if 'PYPI_API_TOKEN' not in content:
-        print("  ❌ PYPI_API_TOKEN not referenced in workflow")
-        return False
-    
-    print("  ✅ GitHub Actions workflow configured")
-    print("     Remember to set PYPI_API_TOKEN secret in GitHub!")
+    print("  ✅ Publication workflow present")
+    print("     Authentication is checked by the workflow's publisher, not artifact readiness.")
     return True
 
 
@@ -261,7 +256,7 @@ def main():
     if passed == total:
         print("\n🎉 All checks passed! Ready for release!")
         print("\nNext steps:")
-        print("  1. Set PYPI_API_TOKEN in GitHub secrets")
+        print("  1. Verify the publication workflow's PyPI authorization")
         print("  2. Run: python scripts/update_and_release.py")
         return 0
     else:

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

@@ -73,6 +73,7 @@ from objectstate.lazy_factory import (
     is_global_config_instance,
     # Raw-value-preserving utilities
     replace_raw,
+    retain_only_authored_paths,
 )
 
 # Resolver
@@ -100,9 +101,6 @@ from objectstate.context_manager import (
     register_hierarchy_relationship,
     unregister_hierarchy_relationship,
     get_ancestors_from_hierarchy,
-    # Scope key utilities
-    get_root_from_scope_key,
-    is_scope_affected,
     # Context stack building (framework-agnostic)
     build_context_stack,
     # Threading utility for context propagation
@@ -181,8 +179,6 @@ __all__ = [
     'extract_all_configs',
     'get_base_global_config',
     'get_context_type_stack',
-    'get_root_from_scope_key',
-    'is_scope_affected',
     'build_context_stack',
     'spawn_thread_with_context',
     # Placeholder
@@ -216,13 +212,14 @@ __all__ = [
     'ObjectStateEditSession',
 ]
 
-__version__ = "1.2.0"
+__version__ = "2.0.0"
 __author__ = 'OpenHCS Team'
 __description__ = 'Generic configuration framework for lazy dataclass resolution'
 
 
 # Object state management
 from objectstate.object_state_registry import ObjectStateRegistry
+from objectstate.scope_key import ScopeKey
 from objectstate.object_state import ObjectState
 from objectstate.object_state_metadata import (
     ObjectStateMetadataContract,
@@ -259,6 +256,8 @@ __all__ += [
     # Object state
     'ObjectState',
     'ObjectStateRegistry',
+    'ScopeKey',
+    'retain_only_authored_paths',
     'ObjectStateMetadataContract',
     'ObjectStateMetadataContractRegistry',
     'ObjectStateMetadataStore',

{objectstate-1.2.0 → objectstate-2.0.0}/src/objectstate/context_manager.py

@@ -329,56 +329,6 @@ def _is_global_type(t):
 _known_hierarchy: dict = {}
 
 
-def get_root_from_scope_key(scope_key: str) -> str:
-    """Extract root (plate path) from scope_key for visibility checks.
-
-    scope_key format:
-    - Pipeline-level: just plate path (e.g., "/path/to/plate")
-    - Step-level: plate_path::step_token (e.g., "/path/to/plate::step_a")
-    - Global: empty string
-
-    Returns the portion before "::" (or the whole string if no "::" present).
-    """
-    if not scope_key:
-        return ""
-    return scope_key.split("::")[0]
-
-
-def is_scope_affected(target_scope_id: str | None, editing_scope_id: str | None) -> bool:
-    """Check if target scope is affected by edit at editing scope.
-
-    Uses scope_id hierarchy - no type introspection needed:
-    - None/"" (global) → affects all
-    - "plate_path" (pipeline) → affects same plate + all its steps
-    - "plate_path::token" (step) → affects only that step
-
-    Args:
-        target_scope_id: The scope being checked for affectedness (None = global)
-        editing_scope_id: The scope where the edit occurred (None = global)
-
-    Returns:
-        True if target should refresh when editing_scope changes
-    """
-    # Normalize None to empty string
-    target = target_scope_id or ""
-    editing = editing_scope_id or ""
-
-    # Global edit affects all
-    if not editing:
-        return True
-
-    # Different plate roots = not affected
-    target_root = get_root_from_scope_key(target)
-    editing_root = get_root_from_scope_key(editing)
-    if target_root != editing_root:
-        return False
-
-    # Same root: parent affects children, not vice versa
-    # editing="plate" affects target="plate::step" ✓
-    # editing="plate::step" affects target="plate" ✗
-    return target == editing or target.startswith(editing + "::")
-
-
 def _normalize_type_for_hierarchy(t):
     """Normalize a type for hierarchy registry, but preserve lazy-global distinction.
 

{objectstate-1.2.0 → objectstate-2.0.0}/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-2.0.0/src/objectstate/inspection.py

@@ -0,0 +1,162 @@
+"""Read-only inspection of registered ObjectStates and their fields."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from objectstate.object_state import ObjectState
+from objectstate.object_state_registry import ObjectStateRegistry
+
+logger = logging.getLogger(__name__)
+
+DIRTY_MARKER = "*"
+"""Marks a field (or a group of fields) whose value differs from the saved value."""
+
+SIGNATURE_DIFF_MARKER = "_"
+"""Marks a field whose raw value differs from its declared signature default."""
+
+
+def field_markers(*, dirty: bool, signature_diff: bool) -> tuple[str, ...]:
+    """The markers views prefix to a field, or to a group of fields, in this order."""
+
+    return tuple(
+        marker
+        for marker, present in ((DIRTY_MARKER, dirty), (SIGNATURE_DIFF_MARKER, signature_diff))
+        if present
+    )
+
+
+def state_markers(state: ObjectState) -> tuple[str, ...]:
+    """The markers of a whole ObjectState: any dirty field, any signature difference."""
+
+    return field_markers(
+        dirty=bool(state.dirty_fields),
+        signature_diff=bool(state.signature_diff_fields),
+    )
+
+
+def type_name(value: object) -> str:
+    return "None" if value is None else type(value).__name__
+
+
+def type_qualname(value_type: type | Callable[..., object]) -> str:
+    return f"{value_type.__module__}.{value_type.__qualname__}"
+
+
+@dataclass(frozen=True, slots=True)
+class FieldProvenance:
+    """The ancestor scope and declaring type a field's inherited value comes from."""
+
+    source_scope_id: str | None
+    source_type: type
+    field_name: str
+
+    @property
+    def source_field_path(self) -> str | None:
+        """The field's path in the source scope's own state, if that scope is registered."""
+
+        source_state = ObjectStateRegistry.get_by_scope(self.source_scope_id)
+        if source_state is None:
+            return None
+        return source_state.project_ui_visible_field_path(self.source_type, self.field_name)
+
+
+@dataclass(frozen=True, slots=True)
+class FieldInspection:
+    """One field of one ObjectState: raw and resolved value, edit state and provenance."""
+
+    state: ObjectState
+    field_path: str
+    raw_value: object
+    resolved_value: object
+    resolved_value_available: bool
+    provenance: FieldProvenance | None
+
+    @classmethod
+    def of(cls, state: ObjectState, field_path: str):
+        """Inspect ``field_path``; a value that fails to resolve is reported unavailable."""
+
+        resolved_value = None
+        resolved_value_available = False
+        try:
+            resolved_value = state.get_resolved_value(field_path)
+            resolved_value_available = True
+        except Exception:
+            logger.debug(
+                "Failed to resolve ObjectState field %s on scope %r.",
+                field_path,
+                state.scope_id,
+                exc_info=True,
+            )
+        provenance = None
+        match state.get_provenance(field_path):
+            case (source_scope_id, source_type) if source_type is not None:
+                provenance = FieldProvenance(
+                    source_scope_id=source_scope_id,
+                    source_type=source_type,
+                    field_name=field_path.rsplit(".", 1)[-1],
+                )
+        return cls(
+            state=state,
+            field_path=field_path,
+            raw_value=state.parameters[field_path],
+            resolved_value=resolved_value,
+            resolved_value_available=resolved_value_available,
+            provenance=provenance,
+        )
+
+    @property
+    def dirty(self) -> bool:
+        return self.field_path in self.state.dirty_fields
+
+    @property
+    def signature_diff(self) -> bool:
+        return self.field_path in self.state.signature_diff_fields
+
+    @property
+    def last_changed(self) -> bool:
+        return self.field_path == self.state.last_changed_field
+
+    @property
+    def raw_value_is_none(self) -> bool:
+        return self.raw_value is None
+
+    @property
+    def resolved_value_is_none(self) -> bool:
+        return self.resolved_value_available and self.resolved_value is None
+
+    @property
+    def inherited_value(self) -> bool:
+        """The field holds no value of its own and inherits a resolved one."""
+
+        return self.raw_value is None and self.resolved_value_available and (
+            self.resolved_value is not None
+        )
+
+    @property
+    def semantic_markers(self) -> tuple[str, ...]:
+        return field_markers(dirty=self.dirty, signature_diff=self.signature_diff)
+
+    @property
+    def field_name(self) -> str:
+        return self.field_path.rsplit(".", 1)[-1]
+
+    @property
+    def container_path(self) -> str:
+        return self.field_path.rsplit(".", 1)[0] if "." in self.field_path else ""
+
+    @property
+    def raw_value_type(self) -> str:
+        return type_name(self.raw_value)
+
+    @property
+    def resolved_value_type(self) -> str | None:
+        return type_name(self.resolved_value) if self.resolved_value_available else None
+
+    @property
+    def declaring_type(self) -> str:
+        """Qualified name of the dataclass that declares this field."""
+
+        return type_qualname(self.state.type_for_path(self.field_path))

{objectstate-1.2.0 → objectstate-2.0.0}/src/objectstate/lazy_factory.py

@@ -250,6 +250,49 @@ def replace_raw(instance, **changes):
     return type(instance)(**field_values)
 
 
+
+def retain_only_authored_paths(value, authored_field_paths) -> Any:
+    """Copy a lazy dataclass, marking only ``authored_field_paths`` as explicitly set.
+
+    An ObjectState rebuild constructs every nested lazy dataclass from all its
+    flattened fields, so every constructor keyword reads as explicit. Clean
+    source generation needs the authored paths ObjectState already tracks
+    (its signature-diff fields); this applies them to the lazy metadata without
+    changing any field value.
+    """
+
+    from objectstate.field_access import DottedFieldPath
+
+    paths = tuple(DottedFieldPath(path) for path in authored_field_paths)
+    return _copy_with_only_authored_paths(value, DottedFieldPath(""), paths)
+
+
+def _copy_with_only_authored_paths(value, prefix, authored_field_paths):
+    from objectstate.field_access import DataclassFieldAccess
+
+    field_values = {}
+    for field_definition in fields(value):
+        field_value = DataclassFieldAccess.raw_value(value, field_definition.name)
+        if isinstance(field_value, LazyDataclass):
+            field_value = _copy_with_only_authored_paths(
+                field_value,
+                prefix.child(field_definition.name),
+                authored_field_paths,
+            )
+        field_values[field_definition.name] = field_value
+
+    projected = type(value)(**field_values)
+    object.__setattr__(
+        projected,
+        "_explicitly_set_fields",
+        {
+            field_definition.name
+            for field_definition in fields(projected)
+            if prefix.child(field_definition.name).contains_any(authored_field_paths)
+        },
+    )
+    return projected
+
 # ContextEventCoordinator removed - replaced with contextvars-based context system