mainsequence 4.1.8__tar.gz → 4.1.9__tar.gz

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

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

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

@@ -353,7 +353,16 @@ Do not construct dependency graphs dynamically inside `update()`.
 ### 8. Foreign Keys Belong To The Storage Contract
 
 For new code, model foreign keys on the `PlatformTimeIndexMetaData` storage
-class or route the storage-contract work to the MetaTable skill.
+class or route the storage-contract work to the MetaTable skill. When a
+DataNode storage table needs a platform-managed FK, use
+`MetaTableForeignKey(TargetModel, column=...)` on the storage class. Do not use
+`ForeignKey(Target.__table__.c.uid)`, table fullnames, or explicit target UID
+maps in DataNode examples.
+
+Registration of the storage class follows the MetaTable lifecycle:
+`register()` recursively registers unresolved FK target model classes, uses the
+local process registry keyed by `storage_hash`, and writes the target
+`MetaTable.uid` into the FK contract.
 
 Do not add DataNode configuration fields just to mutate storage metadata.
 

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

@@ -152,29 +152,48 @@ Do not add a `MAINSEQUENCE_META_TABLE_REGISTER` toggle in registration examples.
 
 Foreign-key contracts reference the target `MetaTable` UID.
 
-For `PlatformManagedMetaTable`, register parent tables first and then register child tables normally. The SDK inspects SQLAlchemy foreign-key constraints and resolves each target `MetaTable` by looking up the already registered table in the same data source, schema, and physical table name.
+For `PlatformManagedMetaTable`, define foreign keys with
+`MetaTableForeignKey(TargetModel, column=...)`. Do not write raw SQLAlchemy
+table fullnames, `Parent.__table__.c.<column>` targets, or explicit target UID
+maps in the platform-managed path. Registration is the lifecycle path:
+`register()` recursively registers unresolved target model classes, stores each
+returned `MetaTable` in a local process registry keyed by `storage_hash`, and
+uses the target `MetaTable.uid` in the child FK contract.
+
+Use this pattern:
+
+```python
+account_uid: Mapped[uuid.UUID] = mapped_column(
+    Uuid,
+    MetaTableForeignKey(Account, column="uid", ondelete="RESTRICT"),
+    nullable=False,
+)
+```
+
+Every participating table must include `__metatable_description__` describing
+both the schema and the table's intention.
 
 Example registration order:
 
 ```python
-account_meta_table = Account.register(...)
 asset_meta_table = Asset.register(...)
 ```
 
-The child registration will fail if the parent table has not already been registered, because there is no target `MetaTable.uid` for the backend FK contract.
-
-Do not pass `target_meta_tables` or `target_meta_table_uid_by_fullname` in the normal platform-managed path. Use explicit FK target mappings only for edge cases where automatic lookup is ambiguous or impossible.
+The child registration registers `Account` first if it has not already been
+registered in the current process. The local registry prevents duplicate backend
+registration attempts for the same `storage_hash` and raises a clear error for
+recursive registration cycles.
 
-For `external_registered`, there is no platform-managed parent lookup through the model class. Register the parent first, then build the child registration request with the parent UID mapped by target table fullname:
+For `external_registered`, there is no platform-managed parent lookup. Register
+the parent first, then build the child registration request with
+`target_meta_tables={Account: account_meta_table}`:
 
 ```python
 account_meta_table = MetaTable.register(account_request)
 asset_request = external_registered_registration_request_from_sqlalchemy_model(
     Asset,
     data_source_uid=data_source_uid,
-    target_meta_table_uid_by_fullname={
-        Account.__table__.fullname: account_meta_table.uid,
-    },
+    target_meta_tables={Account: account_meta_table},
 )
 asset_meta_table = MetaTable.register(asset_request)
 ```

{mainsequence-4.1.8 → mainsequence-4.1.9}/mainsequence/meta_tables/__init__.py

@@ -9,6 +9,7 @@ _LAZY_IMPORTS = {
         ".sqlalchemy_contracts",
         "DEFAULT_PLATFORM_MANAGED_PROVISIONING",
     ),
+    "MetaTableForeignKey": (".sqlalchemy_contracts", "MetaTableForeignKey"),
     "PlatformManagedMetaTable": (".sqlalchemy_contracts", "PlatformManagedMetaTable"),
     "PlatformTimeIndexMetaData": (".sqlalchemy_contracts", "PlatformTimeIndexMetaData"),
     "POSTGRES_IDENTIFIER_MAX_LENGTH": (".hashing", "POSTGRES_IDENTIFIER_MAX_LENGTH"),