adopt-scope 0.3.0__py3-none-any.whl

adopt_scope/__init__.py

@@ -0,0 +1,47 @@
+"""The firm -> engagement -> system -> environment hierarchy.
+
+Implementation spec §4.5. Three invariants hold across this package, and they are
+why it is a package rather than a few helpers inside the store:
+
+1. **No state transition without an event.** `lifecycle.transition` is the only
+   caller of `ScopeRecords.set_system_state`, and it writes the
+   `system_lifecycle_event` in the same transaction.
+2. **No slug mutation, ever** -- and no reissue after `ARCHIVED` or
+   `DISCONNECTED`, because reuse would silently re-point every historical URI.
+3. **`is_billable` and `data_residency_region` are recorded and never
+   interpreted** in Build 0 (owner decisions 14 and 17).
+
+`resolve()` returns ids **and** slugs: the URI builder needs slugs, the store
+needs ids, and returning only one pushes a lookup into whatever loop the caller
+happens to have written.
+"""
+
+from adopt_scope.hierarchy import ID_PREFIXES, INITIAL_LIFECYCLE_STATE, ScopeFacade
+from adopt_scope.lifecycle import LIFECYCLE_EVENT_PREFIX, RETIRED_STATES, transition
+from adopt_scope.records import ScopeRecords
+from adopt_scope.resolve import SCOPE_LEVELS, Scope, ScopeLevel, ScopeNode, ScopePath
+from adopt_scope.slug import (
+    ensure_slug_available,
+    ensure_slug_unchanged,
+    is_valid_slug,
+    validate_slug,
+)
+
+__all__ = [
+    "ID_PREFIXES",
+    "INITIAL_LIFECYCLE_STATE",
+    "LIFECYCLE_EVENT_PREFIX",
+    "RETIRED_STATES",
+    "SCOPE_LEVELS",
+    "Scope",
+    "ScopeFacade",
+    "ScopeLevel",
+    "ScopeNode",
+    "ScopePath",
+    "ScopeRecords",
+    "ensure_slug_available",
+    "ensure_slug_unchanged",
+    "is_valid_slug",
+    "transition",
+    "validate_slug",
+]

adopt_scope/hierarchy.py

@@ -0,0 +1,257 @@
+"""The four-level hierarchy: creation, resolution, and the storage port.
+
+`ScopeFacade` is both the `adopt-scope` public API (implementation spec §4.5)
+and the `Store.scope()` facade (contracts §10.3). It is one class rather than
+two because a second implementation of the same rules is a second place for them
+to drift — and the rules here are the ones tenant isolation is expressed from.
+
+**Storage is a port, not a dependency.** `ScopeRecords` is implemented once over
+SQLite in `adopt_store` and once over Postgres in `plane_store`, so the escape
+suite drives the *same* facade the local CLI drives. If the facade were written
+against SQLite directly, the plane would need its own copy and the escape suite
+would be testing code the CLI never runs.
+
+**Caller-supplied ids and scope are rejected by being unrepresentable.**
+Contracts §10.3 requires that ids are generated inside the facade and scope is
+injected by it. No method below accepts an `id`, and each accepts only the
+parent it hangs from — so there is no argument to reject at runtime, and no
+future caller can find a way to pass one. That is a stronger guarantee than a
+validation branch, which only rejects what someone remembered to check.
+"""
+
+import datetime as _dt
+from typing import Final
+
+from adopt_model import Engagement, Environment, Firm, System, SystemLifecycleEvent
+from adopt_model._enums import Archetype, DeploymentMode, LifecycleState
+from adopt_obs import AdoptError, Clock, ErrorCode, SystemClock, new_id, truncate_to_millisecond
+from adopt_scope.lifecycle import transition as _transition
+from adopt_scope.records import ScopeRecords
+from adopt_scope.resolve import Scope, ScopeNode, ScopePath
+from adopt_scope.slug import ensure_slug_available, validate_slug
+
+__all__ = ["ID_PREFIXES", "INITIAL_LIFECYCLE_STATE", "ScopeFacade"]
+
+#: Contracts §1.1. Minted only through `adopt_obs.new_id`, which rejects an
+#: unregistered prefix, so a typo here fails at the first call rather than
+#: producing ids that look valid and join to nothing.
+ID_PREFIXES: Final[dict[str, str]] = {
+    "firm": "firm",
+    "engagement": "eng",
+    "system": "sys",
+    "environment": "env",
+}
+
+#: A system enters the hierarchy recorded but not yet worked. PRD F3.5 keeps the
+#: eight states distinct; nothing here collapses them.
+INITIAL_LIFECYCLE_STATE: Final[LifecycleState] = "DISCOVERED"
+
+
+def _missing(level: str, slug: str, parent: str | None) -> AdoptError:
+    where = f" under {parent!r}" if parent else ""
+    return AdoptError(
+        ErrorCode.SCOPE_SLUG_INVALID,
+        message=f"no {level} with slug {slug!r} exists{where}",
+        hint=f"Create the {level} first, or check the scope path for a typo.",
+    )
+
+
+class ScopeFacade:
+    """Create and resolve the `firm → engagement → system → environment` chain."""
+
+    def __init__(self, records: ScopeRecords, *, clock: Clock | None = None) -> None:
+        self._records = records
+        self._clock: Clock = clock if clock is not None else SystemClock()
+
+    def _now(self) -> _dt.datetime:
+        """The clock reading at the precision the store keeps.
+
+        Truncated here rather than on the way to SQL, so the row this facade
+        *returns* is the row a later read produces. An untruncated timestamp on
+        the returned model is a value that exists only in memory.
+        """
+        return truncate_to_millisecond(self._clock.now())
+
+    # -- creation ---------------------------------------------------------
+
+    def create_firm(self, *, slug: str, name: str) -> Firm:
+        """Create the root of a scope chain.
+
+        Raises:
+            AdoptError: ``SCOPE_SLUG_INVALID`` or ``SCOPE_SLUG_REUSED``.
+        """
+        validate_slug(slug, level="firm")
+        with self._records.transaction():
+            existing = self._records.find_firm(slug)
+            ensure_slug_available(slug, [existing.slug] if existing else [], level="firm")
+            row = Firm(
+                id=new_id(ID_PREFIXES["firm"]),
+                slug=slug,
+                name=name,
+                created_at=self._now(),
+            )
+            self._records.insert_firm(row)
+        return row
+
+    def create_engagement(
+        self, *, firm_id: str, slug: str, name: str, client_label: str | None = None
+    ) -> Engagement:
+        """Create an engagement under a firm.
+
+        `client_label` is free text: the client-account entity is deferred
+        (PRD F3 non-goals), and inventing one here would be a schema change.
+        """
+        validate_slug(slug, level="engagement")
+        with self._records.transaction():
+            existing = self._records.find_engagement(firm_id, slug)
+            ensure_slug_available(slug, [existing.slug] if existing else [], level="engagement")
+            row = Engagement(
+                id=new_id(ID_PREFIXES["engagement"]),
+                firm_id=firm_id,
+                slug=slug,
+                name=name,
+                client_label=client_label,
+                created_at=self._now(),
+            )
+            self._records.insert_engagement(row)
+        return row
+
+    def create_system(
+        self,
+        *,
+        engagement_id: str,
+        slug: str,
+        name: str,
+        archetype: Archetype | None = None,
+        deployment_mode: DeploymentMode | None = None,
+    ) -> System:
+        """Create a system under an engagement, in `DISCOVERED`.
+
+        The initial state is written directly rather than transitioned into:
+        there is no prior state for a `system_lifecycle_event` to record a move
+        from, and inventing one would make the event log claim a transition that
+        never happened. Every state change *after* creation writes an event.
+        """
+        validate_slug(slug, level="system")
+        with self._records.transaction():
+            existing = self._records.find_system(engagement_id, slug)
+            ensure_slug_available(slug, [existing.slug] if existing else [], level="system")
+            created = self._now()
+            row = System(
+                id=new_id(ID_PREFIXES["system"]),
+                engagement_id=engagement_id,
+                slug=slug,
+                name=name,
+                archetype=archetype,
+                lifecycle_state=INITIAL_LIFECYCLE_STATE,
+                deployment_mode=deployment_mode,
+                created_at=created,
+                updated_at=created,
+            )
+            self._records.insert_system(row)
+        return row
+
+    def create_environment(
+        self,
+        *,
+        system_id: str,
+        slug: str,
+        name: str,
+        is_billable: bool = False,
+        data_residency_region: str | None = None,
+    ) -> Environment:
+        """Create an environment under a system.
+
+        `is_billable` and `data_residency_region` are **recorded and never
+        interpreted** in Build 0 (PRD F3.6, owner decisions 14 and 17). Nothing
+        in this repository reads either column; a grep for a reader is the test.
+        """
+        validate_slug(slug, level="environment")
+        with self._records.transaction():
+            existing = self._records.find_environment(system_id, slug)
+            ensure_slug_available(slug, [existing.slug] if existing else [], level="environment")
+            row = Environment(
+                id=new_id(ID_PREFIXES["environment"]),
+                system_id=system_id,
+                slug=slug,
+                name=name,
+                is_billable=is_billable,
+                data_residency_region=data_residency_region,
+                created_at=self._now(),
+            )
+            self._records.insert_environment(row)
+        return row
+
+    # -- resolution -------------------------------------------------------
+
+    def resolve(self, path: str | ScopePath) -> Scope:
+        """Resolve a scope path to ids **and** slugs at every requested level.
+
+        Raises:
+            AdoptError: ``SCOPE_SLUG_INVALID`` when a path segment is malformed
+                or names a scope that does not exist.
+        """
+        parsed = ScopePath.parse(path) if isinstance(path, str) else path
+
+        firm = self._records.find_firm(parsed.firm)
+        if firm is None:
+            raise _missing("firm", parsed.firm, None)
+        scope = Scope(firm=ScopeNode(id=firm.id, slug=firm.slug))
+        if parsed.engagement is None:
+            return scope
+
+        engagement = self._records.find_engagement(firm.id, parsed.engagement)
+        if engagement is None:
+            raise _missing("engagement", parsed.engagement, firm.slug)
+        scope = Scope(
+            firm=scope.firm,
+            engagement=ScopeNode(id=engagement.id, slug=engagement.slug),
+        )
+        if parsed.system is None:
+            return scope
+
+        system = self._records.find_system(engagement.id, parsed.system)
+        if system is None:
+            raise _missing("system", parsed.system, engagement.slug)
+        scope = Scope(
+            firm=scope.firm,
+            engagement=scope.engagement,
+            system=ScopeNode(id=system.id, slug=system.slug),
+        )
+        if parsed.environment is None:
+            return scope
+
+        environment = self._records.find_environment(system.id, parsed.environment)
+        if environment is None:
+            raise _missing("environment", parsed.environment, system.slug)
+        return Scope(
+            firm=scope.firm,
+            engagement=scope.engagement,
+            system=scope.system,
+            environment=ScopeNode(id=environment.id, slug=environment.slug),
+        )
+
+    # -- lifecycle --------------------------------------------------------
+
+    def transition(
+        self,
+        system_id: str,
+        to_state: LifecycleState,
+        reason: str,
+        actor_id: str | None = None,
+        related_system_id: str | None = None,
+    ) -> tuple[SystemLifecycleEvent, ...]:
+        """Move a system's lifecycle state, writing its event in the same transaction.
+
+        Delegates to `adopt_scope.lifecycle.transition`, which is where the
+        no-silent-transition guarantee is implemented and property-tested.
+        """
+        return _transition(
+            self._records,
+            system_id=system_id,
+            to_state=to_state,
+            reason=reason,
+            actor_id=actor_id,
+            related_system_id=related_system_id,
+            clock=self._clock,
+        )

adopt_scope/lifecycle.py

@@ -0,0 +1,157 @@
+"""Lifecycle transitions — and the guarantee that none of them is silent.
+
+PRD F3.1: *a lifecycle transition is never silent.* Implementation spec §4.5
+behaviour 3 states the mechanism: every `lifecycle_state` change writes a
+`system_lifecycle_event` **in the same transaction**, and there is no code path
+that changes state without one.
+
+That guarantee is implemented by making this module the only caller of
+`ScopeRecords.set_system_state`. The state write and the event write are adjacent
+statements inside one transaction, so there is no ordering in which one lands
+without the other — not "the caller should remember to log it", which is the
+version of this rule that silently stops being true.
+
+**Merges and splits write paired events** (F3.5, §4.5 behaviour 4). Both systems
+receive an event and each names the other in `related_system_id`, so the history
+reads correctly from either side. A one-sided merge is the failure this pairing
+exists to prevent: the surviving system's log would show an absorption and the
+absorbed system's log would show nothing at all.
+"""
+
+import datetime as _dt
+
+from adopt_model import SystemLifecycleEvent
+from adopt_model._enums import LifecycleState
+from adopt_obs import AdoptError, Clock, ErrorCode, SystemClock, new_id, truncate_to_millisecond
+from adopt_scope.records import ScopeRecords
+
+__all__ = ["LIFECYCLE_EVENT_PREFIX", "RETIRED_STATES", "transition"]
+
+#: Contracts §1.1 prefix for `system_lifecycle_event`.
+LIFECYCLE_EVENT_PREFIX: str = "sle"
+
+#: The two states after which a slug is never reissued (PRD F3.4). Named here
+#: rather than inline so the slug rule and the lifecycle rule cannot disagree
+#: about which states are terminal.
+RETIRED_STATES: frozenset[LifecycleState] = frozenset({"ARCHIVED", "DISCONNECTED"})
+
+
+def _event(
+    *,
+    system_id: str,
+    from_state: LifecycleState | None,
+    to_state: LifecycleState,
+    reason: str,
+    related_system_id: str | None,
+    actor_id: str | None,
+    occurred_at: _dt.datetime,
+) -> SystemLifecycleEvent:
+    return SystemLifecycleEvent(
+        id=new_id(LIFECYCLE_EVENT_PREFIX),
+        system_id=system_id,
+        from_state=from_state,
+        to_state=to_state,
+        reason=reason,
+        related_system_id=related_system_id,
+        occurred_at=occurred_at,
+        actor_id=actor_id,
+    )
+
+
+def transition(
+    records: ScopeRecords,
+    *,
+    system_id: str,
+    to_state: LifecycleState,
+    reason: str,
+    actor_id: str | None = None,
+    related_system_id: str | None = None,
+    clock: Clock | None = None,
+) -> tuple[SystemLifecycleEvent, ...]:
+    """Move a system to ``to_state``, writing its event in the same transaction.
+
+    When ``related_system_id`` is given the transition is a merge or a split, and
+    a **paired** event is written on the counterpart system naming this one. The
+    counterpart's own state is not changed: what its state should become is a
+    policy question item 12 owns (PRD F3 non-goals), and deciding it here would
+    be inventing merge semantics this build is explicitly not specifying.
+
+    Args:
+        records: The storage port.
+        system_id: The system whose state changes.
+        to_state: The state to move to.
+        reason: Why. Required — an unexplained transition is a gap in the audit
+            trail that nobody can reconstruct later.
+        actor_id: Who caused it, where a human or agent did.
+        related_system_id: The counterpart on a merge or split.
+        clock: Injected clock; tests pass `ManualClock`.
+
+    Returns:
+        The events written, this system's first.
+
+    Raises:
+        AdoptError: ``SCOPE_SLUG_INVALID`` when the system or its counterpart
+            does not exist. ``SCOPE_VIOLATION`` when a system is asked to
+            transition against itself.
+    """
+    active_clock = clock or SystemClock()
+
+    if related_system_id is not None and related_system_id == system_id:
+        raise AdoptError(
+            ErrorCode.SCOPE_VIOLATION,
+            message=f"system {system_id!r} cannot be its own merge or split counterpart",
+            hint="A paired event needs two distinct systems. Check the counterpart id.",
+        )
+
+    with records.transaction():
+        system = records.get_system(system_id)
+        if system is None:
+            raise AdoptError(
+                ErrorCode.SCOPE_SLUG_INVALID,
+                message=f"no system with id {system_id!r} exists",
+                hint="Resolve the scope path first; `transition` does not create systems.",
+            )
+
+        counterpart = None
+        if related_system_id is not None:
+            counterpart = records.get_system(related_system_id)
+            if counterpart is None:
+                raise AdoptError(
+                    ErrorCode.SCOPE_SLUG_INVALID,
+                    message=f"no counterpart system with id {related_system_id!r} exists",
+                    hint="A merge or split names an existing system on both sides.",
+                )
+
+        occurred_at = truncate_to_millisecond(active_clock.now())
+        from_state = system.lifecycle_state
+
+        # The state write and its event are adjacent inside one transaction.
+        # This adjacency *is* the no-silent-transition guarantee.
+        records.set_system_state(system_id, to_state, occurred_at)
+        events = [
+            _event(
+                system_id=system_id,
+                from_state=from_state,
+                to_state=to_state,
+                reason=reason,
+                related_system_id=related_system_id,
+                actor_id=actor_id,
+                occurred_at=occurred_at,
+            )
+        ]
+        if counterpart is not None:
+            events.append(
+                _event(
+                    system_id=counterpart.id,
+                    from_state=counterpart.lifecycle_state,
+                    to_state=counterpart.lifecycle_state,
+                    reason=reason,
+                    related_system_id=system_id,
+                    actor_id=actor_id,
+                    occurred_at=occurred_at,
+                )
+            )
+        for event in events:
+            records.insert_lifecycle_event(event)
+
+    return tuple(events)

adopt_scope/records.py

@@ -0,0 +1,58 @@
+"""The storage port the scope facade is written against.
+
+Its own module so that `hierarchy` and `lifecycle` can both depend on it without
+depending on each other. The alternative — a function-local import to break the
+cycle — hides a real dependency from every tool that reads imports, including the
+twelve contracts in `importlinter.ini`.
+
+Implemented twice and only twice: over SQLite in `adopt_store.facades.scope`, and
+over Postgres in `plane_store.facades.scope`. That is what lets the tenant-escape
+suite drive the *same* facade the local CLI drives, rather than a parallel copy
+whose behaviour is asserted nowhere.
+"""
+
+import datetime as _dt
+from contextlib import AbstractContextManager
+from typing import Protocol
+
+from adopt_model import Engagement, Environment, Firm, System, SystemLifecycleEvent
+from adopt_model._enums import LifecycleState
+
+__all__ = ["ScopeRecords"]
+
+
+class ScopeRecords(Protocol):
+    """Row in, row out. No SQL, connection or cursor crosses this boundary.
+
+    Every `find_*` deliberately ignores `lifecycle_state`: a slug belonging to an
+    `ARCHIVED` or `DISCONNECTED` scope must still be found, or it would be
+    reissued and every URI ever emitted for the earlier scope would silently
+    re-point (implementation spec §4.5 behaviour 2).
+    """
+
+    def transaction(self) -> AbstractContextManager[None]:
+        """A unit of work. Nested use joins the outermost transaction."""
+        ...
+
+    def insert_firm(self, row: Firm) -> None: ...
+    def insert_engagement(self, row: Engagement) -> None: ...
+    def insert_system(self, row: System) -> None: ...
+    def insert_environment(self, row: Environment) -> None: ...
+    def insert_lifecycle_event(self, row: SystemLifecycleEvent) -> None: ...
+
+    def find_firm(self, slug: str) -> Firm | None: ...
+    def find_engagement(self, firm_id: str, slug: str) -> Engagement | None: ...
+    def find_system(self, engagement_id: str, slug: str) -> System | None: ...
+    def find_environment(self, system_id: str, slug: str) -> Environment | None: ...
+
+    def get_system(self, system_id: str) -> System | None: ...
+
+    def set_system_state(
+        self, system_id: str, to_state: LifecycleState, updated_at: _dt.datetime
+    ) -> None:
+        """Advance a system's stored state.
+
+        Called from `adopt_scope.lifecycle.transition` and nowhere else, because
+        that is the only place the paired `system_lifecycle_event` is written.
+        """
+        ...

adopt_scope/resolve.py

@@ -0,0 +1,112 @@
+"""The resolved scope chain: ids **and** slugs, at every level.
+
+`resolve()` returns both because the two consumers need different halves — the
+identity URI builder needs slugs (CR-05: a URI that depends on an internal ULID
+stops resolving the moment the store leaves our hands) and the store needs ids
+(a ULID is the join key). Returning one and making the caller look up the other
+is how a lookup ends up in a loop that runs per identity.
+
+A `Scope` is resolved to whatever depth was asked for. `firm` is always present;
+the three levels below it are `None` when the caller resolved above them. That
+is deliberately not modelled as four separate classes: every consumer walks the
+same chain, and a partial chain is a normal state rather than an error.
+"""
+
+from dataclasses import dataclass
+from typing import Final, Literal
+
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = [
+    "SCOPE_LEVELS",
+    "Scope",
+    "ScopeLevel",
+    "ScopeNode",
+    "ScopePath",
+]
+
+ScopeLevel = Literal["firm", "engagement", "system", "environment"]
+
+#: Outermost first. The order the path grammar and every parent walk follow.
+SCOPE_LEVELS: Final[tuple[ScopeLevel, ...]] = ("firm", "engagement", "system", "environment")
+
+_PATH_SEPARATOR: Final[str] = "/"
+
+
+@dataclass(frozen=True, slots=True)
+class ScopeNode:
+    """One level of the chain, carrying both of its names."""
+
+    id: str
+    slug: str
+
+
+@dataclass(frozen=True, slots=True)
+class Scope:
+    """A resolved chain. Only `firm` is guaranteed present."""
+
+    firm: ScopeNode
+    engagement: ScopeNode | None = None
+    system: ScopeNode | None = None
+    environment: ScopeNode | None = None
+
+    @property
+    def depth(self) -> int:
+        """How many levels resolved, 1-4."""
+        levels = (self.firm, self.engagement, self.system, self.environment)
+        return sum(1 for level in levels if level is not None)
+
+    def slugs(self) -> tuple[str, ...]:
+        """The resolved slugs, outermost first — the URI builder's input."""
+        levels = (self.firm, self.engagement, self.system, self.environment)
+        return tuple(level.slug for level in levels if level is not None)
+
+    def path(self) -> str:
+        """The canonical `firm/engagement/system/environment` rendering."""
+        return _PATH_SEPARATOR.join(self.slugs())
+
+
+@dataclass(frozen=True, slots=True)
+class ScopePath:
+    """A parsed scope path: between one and four slugs, outermost first.
+
+    Parsing is separated from resolution so that a malformed path fails before
+    any query runs, and so the same grammar serves the CLI and the facade.
+    """
+
+    firm: str
+    engagement: str | None = None
+    system: str | None = None
+    environment: str | None = None
+
+    @classmethod
+    def parse(cls, path: str) -> "ScopePath":
+        """Parse ``firm[/engagement[/system[/environment]]]``.
+
+        Raises:
+            AdoptError: ``SCOPE_SLUG_INVALID`` when the path is empty, has more
+                than four segments, or contains an empty segment.
+        """
+        segments = path.strip().split(_PATH_SEPARATOR) if path.strip() else []
+        if not segments or len(segments) > len(SCOPE_LEVELS) or any(not s for s in segments):
+            raise AdoptError(
+                ErrorCode.SCOPE_SLUG_INVALID,
+                message=f"scope path {path!r} is not one to four non-empty slugs",
+                hint=(
+                    "A scope path is `firm`, `firm/engagement`, "
+                    "`firm/engagement/system` or `firm/engagement/system/environment`."
+                ),
+            )
+        padded = (*segments, *(None,) * (len(SCOPE_LEVELS) - len(segments)))
+        # const-sync: ok -- positional indexes into the four scope levels, not SCHEMA_VERSION.
+        return cls(firm=segments[0], engagement=padded[1], system=padded[2], environment=padded[3])
+
+    def levels(self) -> tuple[tuple[ScopeLevel, str], ...]:
+        """The requested levels in order, stopping at the first absent one."""
+        values = (self.firm, self.engagement, self.system, self.environment)
+        resolved: list[tuple[ScopeLevel, str]] = []
+        for level, value in zip(SCOPE_LEVELS, values, strict=True):
+            if value is None:
+                break
+            resolved.append((level, value))
+        return tuple(resolved)

adopt_scope/slug.py

@@ -0,0 +1,114 @@
+"""Slug validation, uniqueness and immutability.
+
+A slug is the only part of a scope row the identity URI is built from, which is
+what makes an exported bundle resolvable after the store leaves our hands
+(CR-05). Three rules follow from that and are enforced here rather than by
+whoever writes the next facade:
+
+1. **A slug matches `SLUG_PATTERN` and its length bounds.** The pattern permits
+   a single character; `SLUG_MIN_CHARS` does not. Both are checked, because the
+   pattern is the character class and the bounds are the length policy, and a
+   value satisfying one but not the other is still not a slug.
+2. **A slug is set once.** `name` is free to change at any time; a slug is not,
+   because every historical URI already contains it.
+3. **A slug is never reissued -- and the availability check deliberately ignores
+   lifecycle state.** Implementation spec §4.5 behaviour 2 states the rule that
+   way round for a reason: consulting lifecycle state is what would let an
+   `ARCHIVED` system's slug be handed to a new system, silently re-pointing
+   every URI ever emitted for the old one. There is therefore one check and one
+   error code for both cases, and no branch on state exists to get wrong.
+
+Every function here is pure. The caller supplies the sibling slugs already taken,
+which keeps this module free of any storage dependency and lets the SQLite and
+Postgres realizations share one rule set instead of two.
+"""
+
+import re
+from collections.abc import Iterable
+from typing import Final
+
+from adopt_const import SLUG_MAX_CHARS, SLUG_MIN_CHARS, SLUG_PATTERN
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = [
+    "ensure_slug_available",
+    "ensure_slug_unchanged",
+    "is_valid_slug",
+    "validate_slug",
+]
+
+#: Compiled once. The pattern itself lives in `adopt_const` and is never
+#: restated here -- a second copy of a format rule is a second thing to update.
+_SLUG_RE: Final[re.Pattern[str]] = re.compile(SLUG_PATTERN)
+
+
+def is_valid_slug(value: str) -> bool:
+    """Whether ``value`` satisfies both the character class and the length bounds."""
+    return bool(_SLUG_RE.match(value)) and SLUG_MIN_CHARS <= len(value) <= SLUG_MAX_CHARS
+
+
+def validate_slug(value: str, *, level: str) -> None:
+    """Raise ``SCOPE_SLUG_INVALID`` unless ``value`` is a well-formed slug.
+
+    Args:
+        value: The proposed slug.
+        level: The scope level being named, quoted back in the message so the
+            failure says which of the four levels rejected the value.
+
+    Raises:
+        AdoptError: ``SCOPE_SLUG_INVALID``.
+    """
+    if is_valid_slug(value):
+        return
+    raise AdoptError(
+        ErrorCode.SCOPE_SLUG_INVALID,
+        message=f"{level} slug {value!r} is not a valid slug",
+        hint=(
+            f"A slug is {SLUG_MIN_CHARS}-{SLUG_MAX_CHARS} characters of lowercase "
+            f"letters, digits and hyphens, starting and ending with a letter or "
+            f"digit ({SLUG_PATTERN}). Slugs are lowercase because they appear in "
+            f"identity URIs, which compare byte-exact and never case-fold."
+        ),
+    )
+
+
+def ensure_slug_available(value: str, taken: Iterable[str], *, level: str) -> None:
+    """Raise ``SCOPE_SLUG_REUSED`` when a sibling already holds ``value``.
+
+    ``taken`` must contain **every** sibling slug ever assigned under the parent,
+    including those belonging to `ARCHIVED` and `DISCONNECTED` scopes. Filtering
+    it by lifecycle state is the defect this function exists to make impossible.
+
+    Raises:
+        AdoptError: ``SCOPE_SLUG_REUSED``.
+    """
+    if value not in set(taken):
+        return
+    raise AdoptError(
+        ErrorCode.SCOPE_SLUG_REUSED,
+        message=f"{level} slug {value!r} is already assigned under this parent",
+        hint=(
+            "Slugs are never reissued, including after ARCHIVED or DISCONNECTED. "
+            "Reuse would silently re-point every identity URI ever emitted for the "
+            "earlier scope. Choose a different slug."
+        ),
+    )
+
+
+def ensure_slug_unchanged(current: str, proposed: str, *, level: str) -> None:
+    """Raise ``SCOPE_SLUG_IMMUTABLE`` when a write would change an assigned slug.
+
+    Raises:
+        AdoptError: ``SCOPE_SLUG_IMMUTABLE``.
+    """
+    if current == proposed:
+        return
+    raise AdoptError(
+        ErrorCode.SCOPE_SLUG_IMMUTABLE,
+        message=f"{level} slug {current!r} cannot be renamed to {proposed!r}",
+        hint=(
+            "A slug is set once at creation. `name` is freely mutable and is what "
+            "should carry a change of wording; the slug is load-bearing in every "
+            "identity URI already emitted."
+        ),
+    )

adopt_scope-0.3.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: adopt-scope
+Version: 0.3.0
+Summary: The firm-engagement-system-environment hierarchy, slugs, lifecycle events.
+Project-URL: Homepage, https://github.com/onboardux/onboard-core
+Project-URL: Source, https://github.com/onboardux/onboard-core
+Project-URL: Issues, https://github.com/onboardux/onboard-core/issues
+Author: The Adopt Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: adopt-const
+Requires-Dist: adopt-model
+Requires-Dist: adopt-obs

adopt_scope-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+adopt_scope/__init__.py,sha256=mF61QJMkdUB5kAZ4Ic9XmJC032b77ofFTpnrFpP46Bg,1655
+adopt_scope/hierarchy.py,sha256=yleZRSKCmn0nPqIpFs1NYPPGLWObb0EEw1BTy06oaVo,10367
+adopt_scope/lifecycle.py,sha256=8JZE_8lJBw4_uO_UkX0mVQirEUm65rqEdy78RluaPH0,6179
+adopt_scope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adopt_scope/records.py,sha256=H2fBK6p4ZnWvo_V90zQdoLJpfoedoR5P6nYcniK2nrk,2464
+adopt_scope/resolve.py,sha256=yBTSOcPmER6487Ph8lXKWDd2qNghF7co9zui31YAg-Q,4284
+adopt_scope/slug.py,sha256=9CFWFqHBZIU8Gn9Pswii2jQEOX4fWwg8ce62Q-Muh2o,4651
+adopt_scope-0.3.0.dist-info/METADATA,sha256=NQ3rqja88zOewH0qE8fLGUX-fM-L_SKKmiae0dEnJi4,540
+adopt_scope-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+adopt_scope-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+adopt_scope-0.3.0.dist-info/licenses/NOTICE,sha256=2_mgo6v6IM9fAn52L5-wXFpISnC6PVU_geTutoRhbWk,1897
+adopt_scope-0.3.0.dist-info/RECORD,,

adopt_scope-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

adopt_scope-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

adopt_scope-0.3.0.dist-info/licenses/NOTICE

@@ -0,0 +1,39 @@
+Adopt — Adoption-Phase Platform, shared substrate (`adopt-core`)
+Copyright 2026 The Adopt Authors
+
+This product includes software developed by The Adopt Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+--------------------------------------------------------------------------------
+Attribution note
+--------------------------------------------------------------------------------
+
+The copyright holder is recorded here as "The Adopt Authors" pending the legal
+entity name. The owner must settle that attribution before the 0.3.0 tag,
+because published package metadata cannot be changed retroactively for a
+release that has already left the machine. The product name itself is settled:
+handoff-index CR-50 keeps `Adopt` distinct from the `onboard` URI namespace.
+
+--------------------------------------------------------------------------------
+Third-party dependencies
+--------------------------------------------------------------------------------
+
+Every third-party dependency linked into this distribution is permissively
+licensed. The complete list, with licence hash, security status, usage mode,
+owner and re-verification date, is maintained in `licence-verifications.md` and
+enforced by `scripts/licence_gate.py`.
+
+Copyleft-licensed tools are invoked as subprocesses only and are never linked
+into this distribution. They are declared in `subprocess-deps.toml` together
+with their invocation sites.