↓ Skip to main content
dxaws

The Registry Module Planning Session (part 2): Manager Interface Surface

·773 words·4 mins
Dxaws
Table of Contents

Introduction
#

In the previous post we defined the conceptual model for the registry.

Now we begin defining the manager interface — the public surface through which other modules interact with the registry.

Design Goals for the Manager
#

The registry will follow the same basic design principles as other modules in the dxaws ecosystem. The manager is not only the public interface to the module, but it also manages the work through the other parts of the module, namely the planner, executor and providers. We want to spend a bit of time thinking about the design of the interface to this module since it will be difficult to change down the road. Some other considerations for the module in general will include:

  • idempotency
  • minimal required inputs
  • location-independent
  • graph-aware
  • lifecycle-aware
  • permission-aware
  • has safe defaults
  • composable across modules

Specifically, the manager will be responsible for:

  • object registration
  • relationship management
  • lifecycle transitions
  • assignment workflow
  • permission grants
  • location updates
  • control mode enforcement
  • graph queries

Proposed Interface Categories
#

Object Operations
#

register_object()
get_object()
list_objects()
update_metadata()
set_location()
set_control_mode()

Relationship Operations
#

link_objects()
unlink_objects()
list_children()
list_parents()

Lifecycle Operations
#

transition_state()
get_state()
validate_transition()

Assignment Operations
#

assign_object()
unassign_object()
reserve_object()
release_object()

Permission Operations
#

register_principal()
grant_role()
revoke_role()
check_access()
list_grants()

Query Operations
#

get_effective_permissions()
get_object_graph()
get_owned_objects()
get_assigned_objects()

Idempotency Expectations
#

Nothing surprising here. If we make a call like:

register_object(type="site", id="0001")

it should behave safely if called multiple times. The behaviour we expect is that this call will either register the object OR will return details about the object (or both).

Object Identity Expectations
#

All manager operations operate on object identifiers. Recall from part one of this document that:

dxaws:<object-type>:<id>

Examples:

dxaws:site:0001
dxaws:bucket:0007
dxaws:principal:tenant-acme

We purposely do not include region or location in our id. This means that we can move the object between different regions or even different providers without chnaging the id.

That said, we can also create a syntax with the provider/account/region information which looks something like this:

dxaws:website:0001@aws/123456789012/ca-central-1

The portion before the @ symbol is the stable object identifier. Everything after the @ symbol is location context and may change over time without changing object identity.

The extended identifier form is intended for display, logging, and human-readable references. Write operations such as register_object() should use the canonical object identifier and provide location data as separate structured input.

To register a new object, we would use something like:

register_object(
    object_type="website",
    location={
        "provider": "aws",
        "account_id": "123456789012",
        "region": "ca-central-1",
    },
)

—OR—

register_object(
    object_type="bucket",
    metadata={
        "versioning_enabled": True
    }
)

NOTE: the object id is generated internally

The location suffix is optional. Many control-plane objects such as sites, principals, and logical groupings may not have a single fixed runtime location. In these cases the identifier remains simply:

dxaws:website:0001

Location data can still be stored as metadata in the registry even when it is not shown inline with the identifier.

This allows identifiers to remain stable while still providing a concise human-readable way to reference where an object currently lives when needed.

Relationship Semantics
#

Relationships describe how objects connect within the registry graph. The manager provides a minimal interface for expressing these connections without embedding provider-specific knowledge.

Example:

link_objects(
    parent=site_id,
    child=bucket_id,
    relationship="owns"
)

Common relationship types may include:

  • owns
  • uses
  • manages
  • assigned_to
  • depends_on

Relationship semantics are intentionally flexible. Specific modules may enforce additional constraints on allowed relationships between object types.

Examples:

  • site owns bucket
  • site owns distribution
  • distribution uses certificate
  • certificate validated_by dns_record

The registry is responsible for recording relationships but does not enforce provider-specific constraints. The planner may apply validation rules where appropriate.

Relationship operations should be idempotent. Repeated calls to create the same relationship should not produce duplicate edges in the graph.

Lifecycle Transition Philosophy
#

Lifecycle transitions represent changes in the control-plane state of an object.

Examples of lifecycle states include:

  • available
  • reserved
  • assigned
  • active
  • suspended
  • retired

Transitions should be:

  • explicit
  • auditable
  • reversible where possible
  • validated by the planner

Example:

transition_state(site_id, "reserved")

The manager should reject invalid transitions unless explicitly supported.

Lifecycle state does not necessarily imply infrastructure state. An object may exist in the registry before underlying infrastructure is created or after infrastructure has been removed.

This allows the registry to support pre-provisioning workflows, warm pools, and delayed cleanup strategies.

Assignment Semantics
#

Assignment connects principals to objects.

Example:

assign_object(
    object_id=site_id,
    principal_id=tenant_id
)

Assignment allows the platform to:

  • pre-provision infrastructure
  • allocate resources dynamically
  • reassign resources between principals
  • maintain stable object identities

Assignment does not necessarily imply ownership of underlying infrastructure resources.

Ownership may depend on control mode and location.

Example workflow:

reserve_object(site_id)
assign_object(site_id, tenant_id)
transition_state(site_id, "active")

Separating assignment from ownership allows the platform to support multi-tenant workflows, staged provisioning, and controlled transfer of resources between principals.