flayer.providers.lifecycle

Module source

flayer.providers.lifecycle

Immutable lifecycle requests and explicit, ownership-bound mutation contracts.

JsonValue module-attribute

JsonValue: TypeAlias = str | int | bool | None | tuple['JsonValue', ...]

MAX_PARAMETER_DEPTH module-attribute

MAX_PARAMETER_DEPTH = 10

MAX_PARAMETER_VALUES module-attribute

MAX_PARAMETER_VALUES = 2048

LOGICAL_ID_LABEL module-attribute

LOGICAL_ID_LABEL = 'flayer-resource'

SPEC_DIGEST_LABEL module-attribute

SPEC_DIGEST_LABEL = 'flayer-spec'

OPERATION_ID_LABEL module-attribute

OPERATION_ID_LABEL = 'flayer-operation'

ResourceSpec dataclass

ResourceSpec(logical_id: str, kind: ResourceKind, name: str, parameters: tuple[tuple[str, JsonValue], ...] = (), dependencies: tuple[str, ...] = ())

A desired logical resource with immutable options and explicit dependencies.

logical_id instance-attribute

logical_id: str

kind instance-attribute

kind: ResourceKind

name instance-attribute

name: str

parameters class-attribute instance-attribute

parameters: tuple[tuple[str, JsonValue], ...] = field(default=(), repr=False)

dependencies class-attribute instance-attribute

dependencies: tuple[str, ...] = ()

OwnershipLabels

OwnershipLabels(identity: StackIdentity) -> tuple[tuple[str, str], ...]

Bind one logical resource to the complete stack ownership boundary.

Source code in installed/flayer/providers/lifecycle.py

def OwnershipLabels(self, identity: StackIdentity) -> tuple[tuple[str, str], ...]:
    """Bind one logical resource to the complete stack ownership boundary."""

    labels = identity.OwnershipLabels()
    labels[LOGICAL_ID_LABEL] = self.logical_id
    content = (self.logical_id, self.kind.value, self.name, self.parameters, self.dependencies)
    digest = hashlib.sha256(json.dumps(content, sort_keys=True).encode("utf-8")).hexdigest()
    labels[SPEC_DIGEST_LABEL] = digest[:40]

    return tuple(sorted(labels.items()))

MutationError

MutationError(code: ProviderErrorCode, operation: str, outcome_unknown: bool)

Bases: ProviderError

A sanitized mutation failure that distinguishes an uncertain remote outcome.

Retain only a stable failure category and whether submission may have occurred.

Source code in installed/flayer/providers/lifecycle.py

def __init__(
    self, code: ProviderErrorCode, operation: str, outcome_unknown: bool
) -> None:
    """Retain only a stable failure category and whether submission may have occurred."""

    if type(outcome_unknown) is not bool:
        raise ValueError("Mutation outcome uncertainty requires a boolean")

    self.outcome_unknown = outcome_unknown
    super().__init__(code, operation)
    self.retryable = self.retryable and not outcome_unknown

outcome_unknown instance-attribute

outcome_unknown = outcome_unknown

retryable instance-attribute

retryable = self.retryable and not outcome_unknown

LifecycleProvider

Bases: Protocol

Mutation boundary with exact scope, stable reconciliation and owned deletion.

Identity property

Identity: ProviderIdentity

Return the provider and explicit scope used by every observation and command.

Capabilities property

Capabilities: frozenset[ProviderCapability]

Advertise implemented mutation operations independently of account permissions.

ValidateSpec

ValidateSpec(spec: ResourceSpec) -> None

Reject unsupported resource options without accessing infrastructure.

Source code in installed/flayer/providers/lifecycle.py

def ValidateSpec(self, spec: ResourceSpec) -> None:
    """Reject unsupported resource options without accessing infrastructure."""

    ...

FindResource

FindResource(spec: ResourceSpec, identity: StackIdentity) -> ProviderResource | None

Find the unique complete ownership-label match or reject ambiguous inventory.

Source code in installed/flayer/providers/lifecycle.py

def FindResource(
    self, spec: ResourceSpec, identity: StackIdentity
) -> ProviderResource | None:
    """Find the unique complete ownership-label match or reject ambiguous inventory."""

    ...

GetResource

GetResource(reference: ResourceReference) -> ProviderResource

Observe an exact reference with scope validation and sanitized failures.

Source code in installed/flayer/providers/lifecycle.py

def GetResource(self, reference: ResourceReference) -> ProviderResource:
    """Observe an exact reference with scope validation and sanitized failures."""

    ...

CreateResource

CreateResource(spec: ResourceSpec, identity: StackIdentity, dependencies: Mapping[str, ProviderResource], operation_id: str) -> ProviderResource

Create once from validated owned dependencies; never retry uncertain creation.

Source code in installed/flayer/providers/lifecycle.py

def CreateResource(
    self, spec: ResourceSpec, identity: StackIdentity,
    dependencies: Mapping[str, ProviderResource], operation_id: str,
) -> ProviderResource:
    """Create once from validated owned dependencies; never retry uncertain creation."""

    ...

DeleteResource

DeleteResource(reference: ResourceReference, identity: StackIdentity, logical_id: str, operation_id: str | None = None) -> None

Re-read exact scope and complete ownership immediately before deleting by ID.

Source code in installed/flayer/providers/lifecycle.py

def DeleteResource(
    self, reference: ResourceReference, identity: StackIdentity, logical_id: str,
    operation_id: str | None = None,
) -> None:
    """Re-read exact scope and complete ownership immediately before deleting by ID."""

    ...