orchestrata_ultimate.factory.promotion

Reference › orchestrata_ultimate › factory › promotion › init

Package marker for fact-namespace promotion and abandoned-worktree garbage collection (SPEC-033 section 4, row B4a). It defines no code of its own; see the package page.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

No internal imports and no importers.

API

No public API: the module defines no classes, functions or constants.

Source

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

"""Fact-namespace promotion + abandoned-worktree GC (SPEC-033 §4, B4a).

AST/trace facts are branch-dependent state: parallel worktrees hold
different ASTs of overlapping modules at the same instant. With a single
unversioned fact space, concurrent branches poison each other's gate reads
(ADR-0004). This package keys every fact write by `(worktree, commit)`,
makes merge a **fact promotion** into the trunk namespace (never a
free-standing write from the agent's own git), and garbage-collects facts
left behind by abandoned worktrees.

No ``@traces`` decorators in this package: like ``factory.enforcement``
(see its ``__init__.py``), SPEC-033 §4 defines no ``REQ-033-*`` ids --
requirement-id authoring for §4 is a spec change outside this lane.

Modules
-------
models  ``FactNamespace`` (the `(worktree, commit)` key), ``PromotionRecord``
        (promotion result, incl. the ADR-0019 causal-consistency bookmark),
        and ``RetentionPolicy`` (GC's dual age/keep-last-N bound). Frozen
        dataclasses, no behavior.
store   ``PromotionStore`` -- namespaced fact writes/reads, ``promote()``
        (fact-promotion into trunk + a governed ledger event, ADR-0004/0033),
        ``gc()`` (abandoned-worktree retention), and the ``await_watermark``
        /``WatermarkTimeout`` causal-consistency helper (ADR-0019).
"""

from __future__ import annotations