orchestrata_ultimate.factory.anchors.models

Reference › orchestrata_ultimate › factory › anchors › models

models is the data model of the semantic-anchor subsystem (SPEC-033 row B15a, ADR-0012, ADR-0013, ADR-0016). An anchor is a requirement-derived constraint that a human can ratify. Anchor is a frozen dataclass holding the anchor id, requirement id, class, statement, boundary, source, status, ratifier, ratification time and a superseded_by link; changes are made by building a replacement instance. Anchor.new creates a PROPOSED anchor with a deterministic ANC- id derived by _anchor_id from the requirement, class and normalised statement.

AnchorClass has three members, DIFFERENTIAL_ORACLE, PROPERTY and EXAMPLE, and INDEPENDENCE_RANK ranks them (oracle 0, property 1, example 2; lower is stronger). The ranking reflects that an oracle is observed behaviour independent of the design author, while property and example anchors are authored by the same model that wrote the design. AnchorStatus is PROPOSED, RATIFIED or SUPERSEDED. The module reuses helpers from assumptions.models. The store, evaluation, gate, intake, source and decision phase modules import it.

At a glance

Class diagram

Dependency diagram

API

Constants

Classes

AnchorClass (enum)

Bases: StrEnum · Line 23

The three anchor classes, ranked by independence (ADR-0016).

AnchorStatus (enum)

Bases: StrEnum · Line 43

Lifecycle status of an :class:Anchor in the registry.

Anchor (dataclass)

Decorators: dataclass(frozen=True) · Line 68

A semantic anchor: a requirement-derived, human-ratifiable constraint.

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/factory/anchors/models.py

"""Data model for SPEC-033 semantic anchors (B15a, ADR-0012/0013/0016).

``Anchor`` is frozen (immutable record) — a "mutation" is done by building a
replacement instance (``dataclasses.replace``) and persisting it through
:class:`~orchestrata_ultimate.factory.anchors.store.AnchorRegistry`, mirroring
the pattern in :mod:`orchestrata_ultimate.factory.assumptions.models`. Enum
values are lowercase strings with no weasel words.

No ``@traces`` in this module: per the B15a brief, only :class:`.source.
AnchorSource` carries a §-level REQ id (REQ-033-C1, the arbiter-cascade
seam it serves) — the rest of the package has no §-level REQ id of its own.
"""

from __future__ import annotations

import hashlib
from dataclasses import dataclass
from enum import StrEnum

from orchestrata_ultimate.factory.assumptions.models import normalize


class AnchorClass(StrEnum):
    """The three anchor classes, ranked by independence (ADR-0016)."""

    DIFFERENTIAL_ORACLE = "differential_oracle"
    PROPERTY = "property"
    EXAMPLE = "example"


# Independence ranking (ADR-0016): differential oracle is genuinely
# independent of the design author (observed, not authored); property and
# example are authored, typically by the same model that authored the
# design, and so are co-conspired absent human ratification. Lower rank ==
# stronger independence (oracle=0 strongest).
INDEPENDENCE_RANK: dict[AnchorClass, int] = {
    AnchorClass.DIFFERENTIAL_ORACLE: 0,
    AnchorClass.PROPERTY: 1,
    AnchorClass.EXAMPLE: 2,
}


class AnchorStatus(StrEnum):
    """Lifecycle status of an :class:`Anchor` in the registry."""

    PROPOSED = "proposed"
    RATIFIED = "ratified"
    SUPERSEDED = "superseded"


def _anchor_id(requirement_id: str, klass: AnchorClass, statement: str) -> str:
    """Derive an ``ANC-`` id from requirement + class + normalized statement.

    ``ANC-`` + the first 12 hex chars of
    ``sha256("{requirement_id}|{klass.value}|{normalize(statement)}")``. Two
    proposals with the same requirement, class, and (normalized) statement
    collide on this id by construction -- that is the idempotency signal
    :meth:`~orchestrata_ultimate.factory.anchors.store.AnchorRegistry.propose`
    and :func:`~orchestrata_ultimate.factory.anchors.intake.import_dor_candidates`
    rely on.
    """
    combined = f"{requirement_id}|{klass.value}|{normalize(statement)}"
    digest = hashlib.sha256(combined.encode("utf-8")).hexdigest()
    return f"ANC-{digest[:12]}"


@dataclass(frozen=True)
class Anchor:
    """A semantic anchor: a requirement-derived, human-ratifiable constraint.

    ``anchor_id`` is deterministic (:func:`_anchor_id`). ``statement`` is the
    given/when/expect text for an :attr:`AnchorClass.EXAMPLE`, the quantified
    property text for a :attr:`AnchorClass.PROPERTY`, or the oracle's
    observed-behaviour reference for a :attr:`AnchorClass.DIFFERENTIAL_ORACLE`.
    ``boundary`` is empty unless the anchor pins a boundary value/edge.
    ``source`` is provenance -- e.g. ``"dor:REQ-.../step2-3"`` for a B23
    import, ``"observed:<ref>"`` for an oracle, ``"authored:<identity>"`` for
    a human-authored example/property.

    Constructor invariants (enforced in :meth:`__post_init__`, so they also
    hold across every :func:`dataclasses.replace` -- e.g. ratify/supersede):

    - A :attr:`AnchorClass.DIFFERENTIAL_ORACLE` anchor's ``source`` MUST start
      with ``"observed:"`` -- an oracle is OBSERVED prior behaviour, never
      authored text (ADR-0016's core distinction).
    - A :attr:`AnchorStatus.RATIFIED` anchor MUST carry a non-empty
      ``ratified_by``.
    - A :attr:`AnchorStatus.SUPERSEDED` anchor MUST carry a non-empty
      ``superseded_by``.
    """

    anchor_id: str
    requirement_id: str
    klass: AnchorClass
    statement: str
    boundary: str = ""
    source: str = ""
    status: AnchorStatus = AnchorStatus.PROPOSED
    ratified_by: str = ""
    ratified_at: str = ""
    superseded_by: str | None = None

    def __post_init__(self) -> None:
        if (
            self.klass == AnchorClass.DIFFERENTIAL_ORACLE
            and not self.source.startswith("observed:")
        ):
            raise ValueError(
                "a DIFFERENTIAL_ORACLE anchor's source must start with "
                f"'observed:' (an oracle is observed prior behaviour, never "
                f"authored text -- ADR-0016); got source={self.source!r}"
            )
        if self.status == AnchorStatus.RATIFIED and not self.ratified_by:
            raise ValueError(
                "a RATIFIED anchor must carry a non-empty ratified_by "
                "(ratification is the human act -- ADR-0013)"
            )
        if self.status == AnchorStatus.SUPERSEDED and not self.superseded_by:
            raise ValueError("a SUPERSEDED anchor must carry a non-empty superseded_by")

    @classmethod
    def new(
        cls,
        requirement_id: str,
        klass: AnchorClass,
        statement: str,
        boundary: str = "",
        source: str = "",
    ) -> Anchor:
        """Build a fresh ``PROPOSED`` anchor with a deterministic id.

        Args:
            requirement_id: The requirement this anchor is derived from.
            klass: The anchor's class (ADR-0016 ranking).
            statement: The example/property/oracle text (see class docstring).
            boundary: Boundary value/edge this anchor pins, if any.
            source: Provenance string (see class docstring). Required to
                start with ``"observed:"`` when ``klass`` is
                ``DIFFERENTIAL_ORACLE`` -- enforced in ``__post_init__``.
        """
        return cls(
            anchor_id=_anchor_id(requirement_id, klass, statement),
            requirement_id=requirement_id,
            klass=klass,
            statement=statement,
            boundary=boundary,
            source=source,
            status=AnchorStatus.PROPOSED,
            ratified_by="",
            ratified_at="",
            superseded_by=None,
        )