orchestrata_ultimate.factory.promotion.models

Reference › orchestrata_ultimate › factory › promotion › models

models holds the frozen data shapes for fact-namespace promotion (SPEC-033 section 4, row B4a, ADR-0004, ADR-0019); behaviour lives in store. FactNamespace is a (worktree, commit) key; its key property gives the graph property value "{worktree}@{commit}", and the class method trunk builds the sentinel namespace for a promoted commit. PromotionRecord is the result of promoting a namespace into trunk: the namespace, promotion time, commit, fact count, the ledger event id and an optional watermark. RetentionPolicy sets garbage-collection limits for abandoned-worktree facts through max_age_seconds and keep_last_n. The module has no internal imports. The promotion store and the dag, queue, scheduler and worktrees modules import it.

At a glance

Class diagram

Dependency diagram

API

Classes

FactNamespace (dataclass)

Decorators: dataclass(frozen=True) · Line 13

A (worktree, commit) fact-namespace key (ADR-0004).

PromotionRecord (dataclass)

Decorators: dataclass(frozen=True) · Line 42

Result of promoting a namespace's facts into trunk (ADR-0004/0019).

RetentionPolicy (dataclass)

Decorators: dataclass(frozen=True) · Line 68

GC retention policy for abandoned-worktree facts (ADR-0004).

Source

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

"""Data model for fact-namespace promotion (SPEC-033 §4, B4a, ADR-0004/0019).

Frozen dataclasses, no behavior -- see :mod:`.store` for the graph-backed
``PromotionStore`` that operates over these shapes.
"""

from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class FactNamespace:
    """A `(worktree, commit)` fact-namespace key (ADR-0004).

    AST/trace facts are branch-dependent state: worktree A and worktree B
    hold different ASTs of overlapping modules at the same instant. Every
    fact write is tagged with this namespace's :attr:`key` so parallel
    worktrees cannot poison each other's `AST ≡ design` gate reads.
    """

    worktree: str
    commit: str

    @property
    def key(self) -> str:
        """The namespace's Neo4j-property value: ``"{worktree}@{commit}"``."""
        return f"{self.worktree}@{self.commit}"

    @classmethod
    def trunk(cls, commit: str) -> FactNamespace:
        """The TRUNK sentinel namespace for a promoted ``commit``.

        Merge is fact *promotion* (ADR-0004): a source namespace's facts are
        moved into ``FactNamespace.trunk(commit)``, never into a second
        unversioned mutable space.
        """
        return cls(worktree="trunk", commit=commit)


@dataclass(frozen=True)
class PromotionRecord:
    """Result of promoting a namespace's facts into trunk (ADR-0004/0019).

    ``namespace`` is the destination (trunk) namespace the facts now live
    under. ``watermark`` is the ADR-0019 causal-consistency token for the
    promoting transaction: an opaque value stamped onto the trunk
    ``:FactNamespace`` control node inside that same transaction, so a reader
    that can see the token is guaranteed to see every fact the promotion
    moved. Callers that need a causally-consistent gate read must park on
    :func:`orchestrata_ultimate.factory.promotion.store.await_watermark`
    with this value rather than reading immediately.

    It replaced a Neo4j bookmark on 2026-07-26: the orchgraph engine emits no
    bookmarks and silently ignores any supplied, which turned the fail-closed
    gate into a fail-open one. ``None`` only on a record built without a write.
    """

    namespace: FactNamespace
    promoted_at: str
    commit: str
    fact_count: int
    ledger_event_id: str
    watermark: str | None = None


@dataclass(frozen=True)
class RetentionPolicy:
    """GC retention policy for abandoned-worktree facts (ADR-0004).

    BOTH bounds must be violated for a namespace to be GC-eligible: it must
    be older than ``max_age_seconds`` AND fall outside the newest
    ``keep_last_n`` namespaces among the dead-worktree candidates being
    considered. Either bound alone is not sufficient -- a very recent
    namespace never gets deleted regardless of ``keep_last_n``, and an old
    namespace inside the newest N survives regardless of age.
    """

    max_age_seconds: int
    keep_last_n: int