Skip to content

shared_registry

sqllocks_spindle.domains.shared_registry

Shared entity registry for cross-domain composition.

Defines canonical shared concepts (PERSON, LOCATION, ORGANIZATION, CALENDAR) and knows which table in each domain represents each concept. Provides methods to build cross-domain FK relationships and determine generation order for composite schemas.

Classes

SharedConcept

Bases: str, Enum

Canonical shared entity concepts that span multiple domains.

DomainEntityMapping dataclass

Maps a shared concept to a specific table and PK column within a domain.

Attributes:

Name Type Description
domain str

Domain name (e.g., "retail", "hr").
table str

Table name within that domain (e.g., "customer", "employee").
pk_column str

Primary key column of that table (e.g., "customer_id").
person_name_columns dict[str, str]

Optional columns holding person name fields (for PERSON concept — enables identity correlation).

SharedEntityRegistry

Registry of shared entity concepts and their domain-specific mappings.

Provides two key services for cross-domain composition: 1. Building RelationshipDef objects that link shared entities across domains 2. Computing the correct topological generation order (shared entities first)

Example::

registry = SharedEntityRegistry()

# Get cross-domain relationships for retail + hr
from sqllocks_spindle.domains.retail.retail import RetailDomain
from sqllocks_spindle.domains.hr.hr import HrDomain
domains = [RetailDomain(), HrDomain()]
rels = registry.build_cross_domain_relationships(domains)

# Get generation order
order = registry.get_generation_order(domains)
Attributes
concepts property

List all registered shared concepts.

Methods:
get_mappings(concept)

Get all domain mappings for a shared concept.

get_mapping_for_domain(concept, domain_name)

Get the mapping for a specific concept in a specific domain.

get_domains_for_concept(concept)

List all domain names that participate in a shared concept.

build_cross_domain_relationships(domains, shared_entities=None)

Build FK RelationshipDef objects linking shared entities across domains.

Parameters:

Name Type Description Default
domains list[Any]

List of Domain instances participating in the composition.

 required
shared_entities dict[str, dict[str, Any]] | None

Optional explicit mapping overriding defaults. Format::

{
    "person": {
        "primary": "hr.employee",
        "links": {
            "retail": "customer.employee_id",
            "financial": "account.holder_id",
        },
    },
}
None

Returns:

Type Description
list[RelationshipDef]

List of RelationshipDef objects for cross-domain FK references.
get_generation_order(domains, shared_entities=None)

Return a correct topological order: shared (primary) entities first.

This provides a hint for ordering — the actual DependencyResolver in the Spindle engine will do the final sort based on FK references within the merged schema. This method ensures shared primary tables appear before their dependents.

Parameters:

Name Type Description Default
domains list[Any]

List of Domain instances.

 required
shared_entities dict[str, dict[str, Any]] | None

Optional explicit shared entity config.

 None

Returns:

Type Description
list[str]

List of prefixed table names in recommended generation order.