f-layer 2.0.1__py3-none-any.whl

flayer/extensions/contracts.py

@@ -0,0 +1,196 @@
+"""Typed, versioned extension identities and bounded credential-free contexts."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from flayer.core.contracts import ContractError, StackIdentity, ValidateName
+from flayer.profiles.artifacts import ArtifactBundle
+from flayer.providers.contracts import CloudProvider, ValidateIdentifier
+from flayer.providers.lifecycle import LifecycleProvider
+
+PROVIDER_GROUP = "flayer.providers.v1"
+PROFILE_GROUP = "flayer.profiles.v1"
+VERSION_PATTERN = re.compile(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\Z")
+DISTRIBUTION_PATTERN = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
+TARGET_PATTERN = re.compile(
+    r"[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*"
+    r":[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*\Z"
+)
+SHA256_PATTERN = re.compile(r"[a-f0-9]{64}\Z")
+
+
+class ExtensionError(ContractError):
+    """An extension violates discovery, identity, compatibility, or loading policy."""
+
+
+class ExtensionKind(StrEnum):
+    """The two implemented extension contracts; their ABI is encoded in the group."""
+
+    PROVIDER = "provider"
+    PROFILE = "profile"
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionDescriptor:
+    """A static identity; external metadata snapshots are not package authenticity proof."""
+
+    kind: ExtensionKind
+    plugin_id: str
+    distribution: str
+    version: str
+    group: str
+    target: str
+    metadata_directory: Path | None = field(default=None, repr=False)
+    metadata_sha256: str | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        """Validate direct construction as strictly as statically decoded metadata."""
+
+        if not isinstance(self.kind, ExtensionKind):
+            raise ExtensionError("Extension kind must be an ExtensionKind member")
+
+        ValidateName(self.plugin_id, "extension.plugin_id")
+
+        if (
+            not isinstance(self.distribution, str) or len(self.distribution) > 128
+            or DISTRIBUTION_PATTERN.fullmatch(self.distribution) is None
+            or not isinstance(self.version, str) or len(self.version) > 32
+            or VERSION_PATTERN.fullmatch(self.version) is None
+        ):
+            raise ExtensionError("Extension distribution and stable release version are invalid")
+
+        expected_group = PROVIDER_GROUP if self.kind is ExtensionKind.PROVIDER else PROFILE_GROUP
+
+        if self.group != expected_group:
+            raise ExtensionError("Extension group uses an unsupported contract version")
+
+        if (
+            not isinstance(self.target, str) or len(self.target) > 256
+            or TARGET_PATTERN.fullmatch(self.target) is None
+        ):
+            raise ExtensionError("Extension target must be an exact module:attribute without extras")
+
+        if self.metadata_directory is None:
+            if self.distribution != "f-layer" or self.metadata_sha256 is not None:
+                raise ExtensionError("Only F-Layer built-ins may omit the metadata snapshot")
+
+        elif (
+            not isinstance(self.metadata_directory, Path)
+            or not self.metadata_directory.is_absolute()
+            or not self.metadata_directory.name.endswith(".dist-info")
+            or not isinstance(self.metadata_sha256, str)
+            or SHA256_PATTERN.fullmatch(self.metadata_sha256) is None
+            or self.distribution == "f-layer"
+            or self.target.split(":", 1)[0].split(".", 1)[0] == "flayer"
+        ):
+            raise ExtensionError("External extensions require a valid non-reserved metadata snapshot")
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderContext:
+    """Explicit scope, external CLI authentication reference, and bounded execution limits."""
+
+    scope_id: str
+    authentication_reference: str
+    command_timeout: float = 45.0
+    inventory_limit: int = 10000
+
+    def __post_init__(self) -> None:
+        """Reject credential bytes, malformed references, and unbounded execution settings."""
+
+        ValidateIdentifier(self.scope_id)
+        ValidateIdentifier(self.authentication_reference)
+
+        if (
+            isinstance(self.command_timeout, bool)
+            or not isinstance(self.command_timeout, (int, float))
+            or not math.isfinite(self.command_timeout)
+            or not 0 < self.command_timeout <= 300
+            or type(self.inventory_limit) is not int or not 1 <= self.inventory_limit <= 100000
+        ):
+            raise ExtensionError("Provider context requires bounded timeout and inventory limits")
+
+
+@dataclass(frozen=True, slots=True)
+class ProfileContext:
+    """Exact stack ownership context; profile configuration and artifacts stay separate."""
+
+    identity: StackIdentity
+
+    def __post_init__(self) -> None:
+        """Require the existing validated immutable ownership contract."""
+
+        if not isinstance(self.identity, StackIdentity):
+            raise ExtensionError("Profile context requires a validated StackIdentity")
+
+
+@runtime_checkable
+class ProviderExtension(Protocol):
+    """Factory for the existing read-only provider contract, without mandatory mutation."""
+
+    @property
+    def Descriptor(self) -> ExtensionDescriptor:
+        """Return the exact static identity registered before factory loading."""
+
+        ...
+
+    def CreateProvider(self, context: ProviderContext) -> CloudProvider:
+        """Construct a scoped read-only adapter without probing or mutating infrastructure."""
+
+        ...
+
+
+@runtime_checkable
+class LifecycleProviderExtension(ProviderExtension, Protocol):
+    """Optional separate factory for the existing owned resource lifecycle contract."""
+
+    def CreateLifecycleProvider(self, context: ProviderContext) -> LifecycleProvider:
+        """Construct a mutation-capable adapter without performing provider operations."""
+
+        ...
+
+
+@runtime_checkable
+class CompiledProfile(Protocol):
+    """Validated profile adapter that preserves existing artifact and lifecycle boundaries."""
+
+    @property
+    def Identity(self) -> StackIdentity:
+        """Return the exact identity validated during profile compilation."""
+
+        ...
+
+    def BuildServerBundle(self) -> ArtifactBundle:
+        """Generate owned server initialization bytes without writing or deploying them."""
+
+        ...
+
+    def RenderPlan(self, *, user_data_file: str | Path) -> str:
+        """Render lifecycle TOML after verifying the exact owned server artifact."""
+
+        ...
+
+
+@runtime_checkable
+class ProfileExtension(Protocol):
+    """Compile explicit profile configuration using its own strict versioned schema."""
+
+    @property
+    def Descriptor(self) -> ExtensionDescriptor:
+        """Return the exact static identity registered before factory loading."""
+
+        ...
+
+    def CompileProfile(
+        self, configuration: Mapping[str, object], context: ProfileContext,
+    ) -> CompiledProfile:
+        """Validate configuration and exact ownership without accessing infrastructure."""
+
+        ...

flayer/extensions/discovery.py

@@ -0,0 +1,152 @@
+"""Bounded static discovery from exact caller-selected installed distribution metadata."""
+
+from __future__ import annotations
+
+import configparser
+import hashlib
+import os
+import stat
+from collections.abc import Sequence
+from email import policy
+from email.parser import BytesParser
+from pathlib import Path
+
+from .contracts import (
+    PROFILE_GROUP,
+    PROVIDER_GROUP,
+    ExtensionDescriptor,
+    ExtensionError,
+    ExtensionKind,
+)
+
+MAX_METADATA_BYTES = 262144
+MAX_METADATA_DIRECTORIES = 128
+MAX_EXTENSIONS = 256
+METADATA_FILES = ("METADATA", "entry_points.txt", "RECORD")
+
+
+class _EntryPointsParser(configparser.ConfigParser):
+    """Preserve externally declared entry-point names instead of case-folding them."""
+
+    def optionxform(self, optionstr: str) -> str:
+        """Honor ConfigParser's callback naming contract while preserving identity."""
+
+        return optionstr
+
+
+def ReadMetadataFile(path: Path, maximum: int = MAX_METADATA_BYTES) -> bytes:
+    """Read one regular non-linked bounded file without following a final symlink."""
+
+    try:
+        descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+
+        with os.fdopen(descriptor, "rb") as stream:
+            receipt = os.fstat(stream.fileno())
+
+            if (
+                not stat.S_ISREG(receipt.st_mode) or receipt.st_nlink != 1
+                or receipt.st_size > maximum
+            ):
+                raise ExtensionError("Extension metadata or source must be a bounded regular file")
+
+            content = stream.read(maximum + 1)
+            final_receipt = os.fstat(stream.fileno())
+
+            if (
+                len(content) > maximum or len(content) != receipt.st_size
+                or (receipt.st_ino, receipt.st_size, receipt.st_mtime_ns, receipt.st_ctime_ns)
+                != (
+                    final_receipt.st_ino, final_receipt.st_size,
+                    final_receipt.st_mtime_ns, final_receipt.st_ctime_ns,
+                )
+            ):
+                raise ExtensionError("Extension metadata or source changed during its bounded read")
+
+    except OSError:
+        raise ExtensionError("Unable to read exact extension metadata or source") from None
+
+    return content
+
+
+def ReadMetadataSnapshot(directory: Path) -> tuple[tuple[bytes, ...], str]:
+    """Pin only the three explicit metadata files under one selected dist-info directory."""
+
+    try:
+        if (
+            not isinstance(directory, Path) or not directory.is_absolute()
+            or not directory.name.endswith(".dist-info") or directory.is_symlink()
+            or directory.resolve() != directory or not directory.is_dir()
+        ):
+            raise ExtensionError("Discovery requires an exact absolute non-redirected dist-info directory")
+
+    except (OSError, RuntimeError):
+        raise ExtensionError("Unable to resolve exact non-redirected extension metadata") from None
+
+    contents = tuple(ReadMetadataFile(directory / name) for name in METADATA_FILES)
+    digest = hashlib.sha256()
+
+    for name, content in zip(METADATA_FILES, contents, strict=True):
+        digest.update(name.encode("ascii") + b"\x00")
+        digest.update(len(content).to_bytes(8, "big") + content)
+
+    return contents, digest.hexdigest()
+
+
+def DiscoverExtensions(metadata_directories: Sequence[Path]) -> tuple[ExtensionDescriptor, ...]:
+    """Parse selected metadata without importing code, calling finders, or searching paths."""
+
+    if (
+        not isinstance(metadata_directories, (tuple, list))
+        or len(metadata_directories) > MAX_METADATA_DIRECTORIES
+        or any(not isinstance(directory, Path) for directory in metadata_directories)
+        or len(set(metadata_directories)) != len(metadata_directories)
+    ):
+        raise ExtensionError("Discovery requires bounded unique explicit metadata directories")
+
+    descriptors: list[ExtensionDescriptor] = []
+    identities: set[tuple[ExtensionKind, str]] = set()
+
+    for directory in metadata_directories:
+        contents, digest = ReadMetadataSnapshot(directory)
+
+        try:
+            metadata = BytesParser(policy=policy.default).parsebytes(contents[0])
+            names = metadata.get_all("Name", [])
+            versions = metadata.get_all("Version", [])
+
+            if len(names) != 1 or len(versions) != 1 or metadata.defects:
+                raise ExtensionError("Distribution metadata requires one valid Name and Version")
+
+            distribution = str(names[0]).lower().replace("_", "-").replace(".", "-")
+            version = str(versions[0])
+            parser = _EntryPointsParser(interpolation=None, strict=True, delimiters=("=",))
+            parser.read_string(contents[1].decode("utf-8"))
+
+            if parser.defaults():
+                raise ExtensionError("Entry-point metadata cannot contain default entries")
+
+            for group in parser.sections():
+                if not group.startswith("flayer."):
+                    continue
+
+                if group not in {PROVIDER_GROUP, PROFILE_GROUP}:
+                    raise ExtensionError("Entry-point metadata uses an unsupported F-Layer group")
+
+                kind = ExtensionKind.PROVIDER if group == PROVIDER_GROUP else ExtensionKind.PROFILE
+
+                for plugin_id, target in parser.items(group):
+                    descriptor = ExtensionDescriptor(
+                        kind, plugin_id, distribution, version, group, target, directory, digest,
+                    )
+                    identity = (kind, plugin_id)
+
+                    if identity in identities or len(descriptors) >= MAX_EXTENSIONS:
+                        raise ExtensionError("Extension metadata contains duplicate or excess identities")
+
+                    identities.add(identity)
+                    descriptors.append(descriptor)
+
+        except (UnicodeError, configparser.Error, ValueError):
+            raise ExtensionError("Extension metadata is malformed or incompatible") from None
+
+    return tuple(sorted(descriptors, key=lambda item: (item.kind.value, item.plugin_id)))

flayer/extensions/registry.py

@@ -0,0 +1,347 @@
+"""Explicit registry and opt-in loading of metadata-pinned, owned extension sources."""
+
+from __future__ import annotations
+
+import base64
+import csv
+import hashlib
+import importlib.abc
+import importlib.util
+import io
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from types import ModuleType
+
+from .builtins import BuiltinDescriptors, LoadBuiltin
+from .contracts import (
+    ExtensionDescriptor,
+    ExtensionError,
+    ExtensionKind,
+    ProfileExtension,
+    ProviderExtension,
+)
+from .discovery import (
+    MAX_EXTENSIONS,
+    DiscoverExtensions,
+    ReadMetadataFile,
+    ReadMetadataSnapshot,
+)
+
+MAX_MODULE_BYTES = 1048576
+MAX_MODULE_DEPTH = 16
+_LOADED_SOURCES: dict[str, tuple[ModuleType, Path, str]] = {}
+
+
+@dataclass(frozen=True, slots=True)
+class _ModuleSource:
+    """Verified immutable Python bytes owned by one selected distribution RECORD."""
+
+    name: str
+    path: Path
+    content: bytes = field(repr=False)
+    package: bool = False
+
+
+class _SnapshotImporter(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """Serve only already verified selected-chain imports from immutable source snapshots."""
+
+    def __init__(
+        self, sources: tuple[_ModuleSource, ...], created: list[tuple[str, ModuleType]],
+    ) -> None:
+        """Bind the exact source chain and cleanup receipts for one explicit load attempt."""
+
+        self._sources = {source.name: source for source in sources}
+        self._created = created
+
+    def find_spec(
+        self, fullname: str, path: Sequence[str] | None, target: ModuleType | None = None,
+    ) -> importlib.machinery.ModuleSpec | None:
+        """Honor Python's finder callback only for exact selected source identities."""
+
+        source = self._sources.get(fullname)
+
+        if source is None:
+            return None
+
+        return importlib.util.spec_from_file_location(
+            fullname, source.path, loader=self,
+            submodule_search_locations=[str(source.path.parent)] if source.package else None,
+        )
+
+    def create_module(self, spec: importlib.machinery.ModuleSpec) -> ModuleType | None:
+        """Honor Python's loader callback with the standard module construction behavior."""
+
+        return None
+
+    def exec_module(self, module: ModuleType) -> None:
+        """Execute selected verified bytes and register exact module-object provenance."""
+
+        source = self._sources[module.__name__]
+        self._created.append((source.name, module))
+        exec(compile(source.content, str(source.path), "exec"), module.__dict__)
+        _LOADED_SOURCES[source.name] = (
+            module, source.path, hashlib.sha256(source.content).hexdigest(),
+        )
+        _RequireReceipt(source, module)
+
+
+def _ReadSources(descriptor: ExtensionDescriptor) -> tuple[_ModuleSource, ...]:
+    """Validate exact metadata and every parent/target source before any plugin execution."""
+
+    directory = descriptor.metadata_directory
+
+    if directory is None:
+        raise ExtensionError("External loading requires a selected metadata directory")
+
+    contents, digest = ReadMetadataSnapshot(directory)
+
+    if digest != descriptor.metadata_sha256 or descriptor not in DiscoverExtensions((directory,)):
+        raise ExtensionError("Selected extension metadata changed after discovery")
+
+    records: dict[str, tuple[str, str]] = {}
+
+    try:
+        for row in csv.reader(io.StringIO(contents[2].decode("utf-8")), strict=True):
+            if (
+                len(row) != 3 or not row[0] or row[0] in records
+                or PurePosixPath(row[0]).is_absolute() or "\\" in row[0]
+            ):
+                raise ExtensionError("Distribution RECORD contains malformed or duplicate paths")
+
+            records[row[0]] = (row[1], row[2])
+
+    except (UnicodeError, csv.Error):
+        raise ExtensionError("Distribution RECORD is malformed") from None
+
+    module = descriptor.target.split(":", 1)[0]
+    parts = module.split(".")
+
+    if len(parts) > MAX_MODULE_DEPTH:
+        raise ExtensionError("Extension import target exceeds the supported package depth")
+
+    sources: list[_ModuleSource] = []
+
+    for index in range(1, len(parts) + 1):
+        stem = "/".join(parts[:index])
+        candidates: tuple[str, ...] = (stem + "/__init__.py",)
+
+        if index == len(parts):
+            candidates += (stem + ".py",)
+
+        matches = tuple(candidate for candidate in candidates if candidate in records)
+
+        if len(matches) != 1:
+            raise ExtensionError("Extension target and parent packages require exact RECORD ownership")
+
+        relative = matches[0]
+        path = directory.parent / relative
+
+        try:
+            if path.resolve() != path or not path.is_relative_to(directory.parent):
+                raise ExtensionError("Extension source cannot redirect outside its selected installation")
+
+        except (OSError, RuntimeError):
+            raise ExtensionError("Unable to resolve exact non-redirected extension source") from None
+
+        content = ReadMetadataFile(path, MAX_MODULE_BYTES)
+        source_digest = base64.urlsafe_b64encode(hashlib.sha256(content).digest()).decode().rstrip("=")
+
+        if records[relative] != ("sha256=" + source_digest, str(len(content))):
+            raise ExtensionError("Extension source does not match its exact RECORD hash and size")
+
+        sources.append(_ModuleSource(
+            ".".join(parts[:index]), path, content, relative.endswith("/__init__.py"),
+        ))
+
+    return tuple(sources)
+
+
+def _LoadFactory(descriptor: ExtensionDescriptor) -> ProviderExtension | ProfileExtension:
+    """Execute verified selected sources directly, rejecting ambient module shadowing."""
+
+    sources = _ReadSources(descriptor)
+
+    for source in sources:
+        existing = sys.modules.get(source.name)
+
+        if existing is not None:
+            _RequireReceipt(source, existing)
+
+    created: list[tuple[str, ModuleType]] = []
+    importer = _SnapshotImporter(sources, created)
+    sys.meta_path.insert(0, importer)
+
+    try:
+        for source in sources:
+            existing = sys.modules.get(source.name)
+
+            if existing is not None:
+                _RequireReceipt(source, existing)
+
+                continue
+
+            spec = importer.find_spec(source.name, None)
+
+            if spec is None:
+                raise ExtensionError("Unable to construct the selected extension module")
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[source.name] = module
+            importer.exec_module(module)
+
+            if "." in source.name:
+                parent_name, _, child_name = source.name.rpartition(".")
+                setattr(sys.modules[parent_name], child_name, module)
+
+        factory: object = sys.modules[sources[-1].name]
+
+        for attribute in descriptor.target.split(":", 1)[1].split("."):
+            factory = getattr(factory, attribute)
+
+        if not callable(factory):
+            raise ExtensionError("Selected entry-point target is not a callable factory")
+
+        return _ValidateExtension(factory(), descriptor)
+
+    except (Exception, SystemExit):
+        for name, module in reversed(created):
+            if sys.modules.get(name) is module:
+                del sys.modules[name]
+
+            receipt = _LOADED_SOURCES.get(name)
+
+            if receipt is not None and receipt[0] is module:
+                del _LOADED_SOURCES[name]
+
+            if "." in name:
+                parent_name, _, child_name = name.rpartition(".")
+                parent = sys.modules.get(parent_name)
+
+                if parent is not None and parent.__dict__.get(child_name) is module:
+                    del parent.__dict__[child_name]
+
+        raise ExtensionError("Selected extension factory failed to load") from None
+
+    finally:
+        if importer in sys.meta_path:
+            sys.meta_path.remove(importer)
+
+
+def _RequireReceipt(source: _ModuleSource, module: ModuleType) -> None:
+    """Reject cached code unless this loader executed this exact verified byte snapshot."""
+
+    receipt = _LOADED_SOURCES.get(source.name)
+
+    if (
+        receipt is None or receipt[0] is not module or receipt[1] != source.path
+        or receipt[2] != hashlib.sha256(source.content).hexdigest()
+        or sys.modules.get(source.name) is not module
+        or module.__dict__.get("__file__") != str(source.path)
+        or getattr(module.__dict__.get("__spec__"), "origin", None) != str(source.path)
+    ):
+        raise ExtensionError("An unverified cached module shadows the selected extension source")
+
+
+def _ValidateExtension(
+    loaded: object, descriptor: ExtensionDescriptor,
+) -> ProviderExtension | ProfileExtension:
+    """Check exact identity and callable protocol before a factory transaction commits."""
+
+    expected = ProviderExtension if descriptor.kind is ExtensionKind.PROVIDER else ProfileExtension
+    method = "CreateProvider" if descriptor.kind is ExtensionKind.PROVIDER else "CompileProfile"
+
+    try:
+        if (
+            not isinstance(loaded, expected) or loaded.Descriptor != descriptor
+            or not callable(getattr(loaded, method, None))
+        ):
+            raise ExtensionError("Loaded extension does not match its declared identity and contract")
+
+    except (Exception, SystemExit):
+        raise ExtensionError("Loaded extension does not match its declared identity and contract") from None
+
+    return loaded
+
+
+class ExtensionRegistry:
+    """A bounded explicit catalog; neither construction nor lookup imports external code."""
+
+    def __init__(
+        self, descriptors: Sequence[ExtensionDescriptor] = (), *, include_builtins: bool = True,
+    ) -> None:
+        """Validate complete registration before publishing any catalog entries."""
+
+        if type(include_builtins) is not bool or not isinstance(descriptors, (tuple, list)):
+            raise ExtensionError("Registry requires explicit bounded descriptor registration")
+
+        entries = (*BuiltinDescriptors(), *descriptors) if include_builtins else tuple(descriptors)
+
+        if len(entries) > MAX_EXTENSIONS:
+            raise ExtensionError("Registry exceeds its extension bound")
+
+        registered: dict[tuple[ExtensionKind, str], ExtensionDescriptor] = {}
+
+        for descriptor in entries:
+            if not isinstance(descriptor, ExtensionDescriptor):
+                raise ExtensionError("Registry accepts only validated ExtensionDescriptor objects")
+
+            identity = (descriptor.kind, descriptor.plugin_id)
+
+            if identity in registered:
+                raise ExtensionError("Duplicate extension identity would shadow a registered extension")
+
+            if descriptor.metadata_directory is None and descriptor not in BuiltinDescriptors():
+                raise ExtensionError("Registry rejects invented or incompatible built-in identities")
+
+            registered[identity] = descriptor
+
+        self._descriptors = registered
+        self._loaded: dict[ExtensionDescriptor, ProviderExtension | ProfileExtension] = {}
+
+    def Descriptors(self) -> tuple[ExtensionDescriptor, ...]:
+        """Return immutable descriptors in deterministic kind and identifier order."""
+
+        return tuple(sorted(self._descriptors.values(), key=lambda item: (item.kind.value, item.plugin_id)))
+
+    def Get(self, kind: ExtensionKind, plugin_id: str) -> ExtensionDescriptor:
+        """Select one registered identity without imports or capability probes."""
+
+        if not isinstance(kind, ExtensionKind) or not isinstance(plugin_id, str):
+            raise ExtensionError("Registry lookup requires an exact extension kind and identifier")
+
+        descriptor = self._descriptors.get((kind, plugin_id))
+
+        if descriptor is None:
+            raise ExtensionError("Extension identity is not registered")
+
+        return descriptor
+
+    def Load(
+        self, descriptor: ExtensionDescriptor, *, allowed: Sequence[ExtensionDescriptor] = (),
+    ) -> ProviderExtension | ProfileExtension:
+        """Load an exact registered factory; external code requires an exact descriptor pin."""
+
+        if (
+            not isinstance(descriptor, ExtensionDescriptor)
+            or self.Get(descriptor.kind, descriptor.plugin_id) != descriptor
+            or not isinstance(allowed, (tuple, list)) or len(allowed) > MAX_EXTENSIONS
+            or any(not isinstance(item, ExtensionDescriptor) for item in allowed)
+            or len(set(allowed)) != len(allowed)
+        ):
+            raise ExtensionError("Loading requires an exact registered descriptor and bounded unique pins")
+
+        if descriptor.metadata_directory is not None and descriptor not in allowed:
+            raise ExtensionError("External loading requires an explicit exact descriptor allowlist")
+
+        if descriptor in self._loaded:
+            return self._loaded[descriptor]
+
+        loaded = (
+            _ValidateExtension(LoadBuiltin(descriptor), descriptor)
+            if descriptor.metadata_directory is None else _LoadFactory(descriptor)
+        )
+        self._loaded[descriptor] = loaded
+
+        return loaded