mainsequence 4.1.7__tar.gz → 4.1.8__tar.gz

{mainsequence-4.1.7 → mainsequence-4.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.1.7
+Version: 4.1.8
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.1.7 → mainsequence-4.1.8}/agent_scaffold/skills/data_publishing/data_nodes/SKILL.md

@@ -25,7 +25,7 @@ Canonical workflow:
 - modify an existing `DataNode` update process
 - review whether a DataNode change affects update identity or table contract
 - define or refactor `DataNodeConfiguration`
-- classify config fields into update identity and hash-excluded descriptive metadata
+- classify values as hashed config fields or non-config class/runtime values
 - implement or review:
   - `dependencies()`
   - `update()`
@@ -112,6 +112,16 @@ Every storage class must include `__metatable_description__`. The description
 should explain the table's intention, row grain, and downstream use, not only
 list columns or schema mechanics.
 
+Use `__metatable_extra_hash_components__` on storage classes when distinct
+DataNode storage tables could otherwise have the same storage-relevant shape.
+For example, two one-index daily tables with one float column need a stable
+component such as `{"storage_name": "daily_random_number"}` versus
+`{"storage_name": "daily_random_addition"}`.
+
+This is storage identity. Changing it creates a different storage table. Do not
+use it for labels, descriptions, runtime options, test isolation, backend UIDs,
+data-source UIDs, or updater scope.
+
 Do not put those concerns in `DataNodeConfiguration`.
 
 Minimal pattern:
@@ -132,6 +142,7 @@ class Base(DeclarativeBase):
 class PricesTable(PlatformTimeIndexMetaData, Base):
     __metatable_namespace__ = "<domain_namespace>"
     __metatable_identifier__ = "<table_identifier>"
+    __metatable_extra_hash_components__ = {"storage_name": "<stable_storage_name>"}
     __metatable_description__ = (
         "Daily close prices keyed by asset unique identifier for portfolio and "
         "risk analytics."
@@ -183,12 +194,21 @@ Do not accept `test_node`. It has been removed. Use explicit
 Pattern:
 
 ```python
+from typing import ClassVar
+
+from pydantic import Field
+
 from mainsequence.meta_tables import DataNode, DataNodeConfiguration
 from mainsequence.meta_tables import PlatformTimeIndexMetaData
 
 
 class PricesConfig(DataNodeConfiguration):
-    shard_id: str
+    shard_id: str = Field(
+        ...,
+        description="Stable updater partition for this price job.",
+        examples=["us_equities_daily"],
+    )
+    reference_dimension: ClassVar[str] = "unique_identifier"
 
 
 class PricesUpdate(DataNode):
@@ -216,23 +236,45 @@ class PricesUpdate(DataNode):
 ### 3. Configuration Is Update-Scoped By Default
 
 Every `DataNodeConfiguration` field participates in `update_hash` by default.
+Declare values that change output values, dependencies, source choice, or
+updater scope as normal config fields.
 
-Do not use:
+Every config field must be declared with `Field(...)`. Include a clear
+`description` and add `examples=[...]` whenever a realistic example helps. The
+description must explain what the value means for the update process, not repeat
+the Python type.
 
-- `json_schema_extra={"update_only": True}`
-- `json_schema_extra={"runtime_only": True}`
-- `json_schema_extra={"ignore_from_storage_hash": True}`
-- `_ARGS_IGNORE_IN_STORAGE_HASH`
+Values that must not affect `update_hash` should not be Pydantic config fields.
+Use `ClassVar[...]` for class-level invariants and implementation constants, or
+keep runtime controls in environment/runtime configuration outside the
+DataNode config.
 
-Those are removed. The only supported opt-out is:
+If a value genuinely must remain a Pydantic field while not affecting
+`update_hash`, the only supported field-level opt-out is
+`json_schema_extra={"hash_excluded": True}`:
 
 ```python
-Field(..., json_schema_extra={"hash_excluded": True})
+from pydantic import Field
+
+from mainsequence.meta_tables import DataNodeConfiguration
+
+
+class PricesConfig(DataNodeConfiguration):
+    shard_id: str = Field(
+        ...,
+        description="Stable updater partition for this price job.",
+        examples=["us_equities_daily"],
+    )
+    display_label: str | None = Field(
+        default=None,
+        description="Optional human-facing label for UI display only.",
+        examples=["US equities daily prices"],
+        json_schema_extra={"hash_excluded": True},
+    )
 ```
 
-Use `hash_excluded` only for descriptive metadata that must not affect update
-identity. If a field changes output values, dependencies, source choice, or
-updater scope, it must remain a normal config field.
+Do not invent other metadata-marker exceptions. Scope, dependency, source, and
+output-affecting fields must remain hashed config fields.
 
 ### 4. `hash_namespace` Is Isolation Only
 
@@ -330,11 +372,10 @@ When reviewing an existing DataNode, look for:
 - missing `__metatable_description__` on the storage table
 - dependency storage table passed as an ad hoc constructor argument
 - schema or published table metadata hidden in DataNode configuration
-- `update_only`, `runtime_only`, or `ignore_from_storage_hash`
 - `test_node=True`
 - missing explicit `storage_table`
 - accidental storage registration inside the DataNode
-- wrong meaning/scope/hash-excluded split
+- wrong split between hashed config fields and non-config class/runtime values
 - misuse of `hash_namespace`
 - non-incremental `update()` behavior
 - hidden dependency creation inside `update()`

{mainsequence-4.1.7 → mainsequence-4.1.8}/agent_scaffold/skills/data_publishing/meta_tables/SKILL.md

@@ -103,12 +103,23 @@ Always declare `__metatable_description__` on the model. The description must
 explain the table's business intention, row grain, and expected use, not only
 the schema. Column-level descriptions stay in `mapped_column(info={...})`.
 
+Use `__metatable_extra_hash_components__` when two backend-managed tables could
+otherwise produce the same storage hash because their storage-relevant shape is
+identical or intentionally generic. The value must be stable and deterministic,
+usually a small mapping such as `{"storage_name": "account_holdings"}`.
+
+This attribute is part of storage identity. Changing it defines a different
+table. Do not use it for labels, descriptions, runtime options, test isolation,
+backend UIDs, data-source UIDs, or updater scope. Use `hash_namespace` for test
+or experiment isolation.
+
 Register through the class API:
 
 ```python
 class Account(PlatformManagedMetaTable, Base):
     __metatable_namespace__ = "sdk-examples"
     __metatable_identifier__ = "Account"
+    __metatable_extra_hash_components__ = {"storage_name": "account"}
     __metatable_description__ = (
         "Customer account master records used to scope balances, holdings, and "
         "account-level limits."

{mainsequence-4.1.7 → mainsequence-4.1.8}/mainsequence/meta_tables/data_nodes/data_nodes.py

@@ -420,13 +420,6 @@ class DataNode(DataAccessMixin, ABC):
         """
         super().__init_subclass__(**kwargs)
 
-        if "_ARGS_IGNORE_IN_STORAGE_HASH" in cls.__dict__:
-            raise TypeError(
-                f"{cls.__name__} uses removed class attribute _ARGS_IGNORE_IN_STORAGE_HASH; "
-                "move those fields into DataNodeConfiguration. Configuration fields "
-                "participate in update hashing by default."
-            )
-
         # Get the original __init__ from the new subclass
         original_init = cls.__init__
 

{mainsequence-4.1.7 → mainsequence-4.1.8}/mainsequence/meta_tables/pydantic_metadata.py

@@ -20,24 +20,6 @@ def serialize_pydantic_model(
 
     for field_name, field_info in value.__class__.model_fields.items():
         extra = field_info.json_schema_extra or {}
-        if "ignore_from_storage_hash" in extra:
-            raise ValueError(
-                f"{value.__class__.__name__}.{field_name} uses removed metadata "
-                "'ignore_from_storage_hash'. All configuration fields participate in "
-                'update hashing by default; use json_schema_extra={"hash_excluded": True} '
-                "only for fields that should not affect update identity."
-            )
-        if "update_only" in extra:
-            raise ValueError(
-                f"{value.__class__.__name__}.{field_name} uses removed metadata "
-                "'update_only'. All configuration fields are update-scoped by default."
-            )
-        if "runtime_only" in extra:
-            raise ValueError(
-                f"{value.__class__.__name__}.{field_name} uses removed metadata "
-                "'runtime_only'; use json_schema_extra={\"hash_excluded\": True} instead."
-            )
-
         is_hash_excluded = extra.get("hash_excluded", False)
         if not isinstance(is_hash_excluded, bool):
             raise ValueError(

{mainsequence-4.1.7 → mainsequence-4.1.8}/mainsequence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.1.7
+Version: 4.1.8
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.1.7 → mainsequence-4.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "4.1.7"
+version = "4.1.8"
 description = "Main Sequence SDK "
 readme = "README.md"
 requires-python = ">=3.11"

{mainsequence-4.1.7 → mainsequence-4.1.8}/tests/test_build_operations_hashing.py

@@ -101,22 +101,6 @@ def test_normal_config_value_changes_update_hash(monkeypatch):
     assert storage_hash_a != storage_hash_b
 
 
-def test_update_only_metadata_is_rejected():
-    class NodeConfig(BaseModel):
-        shard_id: str = Field(..., json_schema_extra={"update_only": True})
-
-    with pytest.raises(ValueError, match="update_only"):
-        build_operations.serialize_argument(NodeConfig(shard_id="desk_a"))
-
-
-def test_runtime_only_metadata_is_rejected():
-    class NodeConfig(BaseModel):
-        label: str = Field(..., json_schema_extra={"runtime_only": True})
-
-    with pytest.raises(ValueError, match="runtime_only"):
-        build_operations.serialize_argument(NodeConfig(label="Close"))
-
-
 def test_hash_excluded_metadata_does_not_affect_hashes(monkeypatch):
     monkeypatch.setattr(build_operations, "POD_PROJECT", None, raising=False)
 
@@ -264,30 +248,6 @@ def test_plain_dict_with_pydantic_model_import_path_key_is_not_treated_as_wrappe
     assert build_operations.hash_signature(payload_a) != build_operations.hash_signature(payload_b)
 
 
-def test_removed_storage_hash_metadata_is_rejected():
-    class RemovedStorageHashConfig(BaseModel):
-        shard_id: str = Field(..., json_schema_extra={"ignore_from_storage_hash": True})
-
-    with pytest.raises(ValueError, match="ignore_from_storage_hash"):
-        build_operations.serialize_argument(RemovedStorageHashConfig(shard_id="desk_a"))
-
-
-def test_removed_storage_hash_class_attribute_is_rejected():
-    with pytest.raises(TypeError, match="_ARGS_IGNORE_IN_STORAGE_HASH"):
-
-        class RemovedStorageHashDataNode(DataNode):
-            _ARGS_IGNORE_IN_STORAGE_HASH = ["asset_list"]
-
-            def __init__(self, *args, **kwargs):
-                super().__init__(*args, **kwargs)
-
-            def dependencies(self):
-                return {}
-
-            def update(self):
-                return None
-
-
 def test_data_node_configuration_overrides_offset_start():
     class NodeConfig(DataNodeConfiguration):
         pass