alpha-engine-lib 0.35.0__tar.gz → 0.35.1__tar.gz

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.35.0
+Version: 0.35.1
 Summary: Shared utilities for the Alpha Engine modules: preflight, structured logging with secret-redaction, ArcticDB universe access, NYSE-calendar dates + freshness predicates, decision capture, cost telemetry, RAG, agent output schemas, SSM-backed secrets, Telegram alerts + SNS fan-out, EC2 spot-launch resilience, SSM log-capture chokepoint, SSM send-command + poll chokepoint, and Step-Functions execution-state projection. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.35.0"
+version = "0.35.1"
 description = "Shared utilities for the Alpha Engine modules: preflight, structured logging with secret-redaction, ArcticDB universe access, NYSE-calendar dates + freshness predicates, decision capture, cost telemetry, RAG, agent output schemas, SSM-backed secrets, Telegram alerts + SNS fan-out, EC2 spot-launch resilience, SSM log-capture chokepoint, SSM send-command + poll chokepoint, and Step-Functions execution-state projection. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/src/alpha_engine_lib/__init__.py

@@ -1,3 +1,3 @@
 """alpha-engine-lib — shared utilities for Alpha Engine modules."""
 
-__version__ = "0.35.0"
+__version__ = "0.35.1"

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/src/alpha_engine_lib/pipeline_status/read.py

@@ -35,7 +35,7 @@ import logging
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Annotated, Any, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -160,7 +160,21 @@ class TaskRow(BaseModel):
     # substrate-only reason). ``None`` here means "state name not in the
     # registry" and is a CI-time bug — the consumer should treat it as a
     # registry-drift signal, not a renderable placeholder.
-    archive: Optional[Any] = None  # ArchivePageRef | ArtifactReason | None
+    #
+    # The Annotated[Union[...], Field(discriminator="kind")] form is the
+    # SOTA tagged-union pattern for Pydantic V2: ``model_dump(mode="json")``
+    # serializes the ``kind`` field on each variant, and ``model_validate``
+    # routes dict input to the right class via that tag. Prior to this
+    # tagging, ``archive`` was typed ``Optional[Any]``, so a JSON round-trip
+    # left it as a plain dict — page-25's ``isinstance`` checks then
+    # misfired and rendered "Registry drift" for every state, even those
+    # with valid registry entries.
+    archive: Optional[
+        Annotated[
+            Union[ArchivePageRef, ArtifactReason],
+            Field(discriminator="kind"),
+        ]
+    ] = None
     failure_cause: Optional[str] = None  # populated only when status == FAILED
 
 

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/src/alpha_engine_lib/pipeline_status/registry.py

@@ -27,8 +27,9 @@ how the two stay in sync without a runtime coupling.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import Final, Optional
+from typing import Annotated, Final, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
 
 
 # ── Substantive-state filtering (§3.2 of the plan doc) ────────────────────
@@ -100,8 +101,7 @@ PIPELINE_LABELS: Final[dict[str, str]] = {
 # ── Artifact registry types ───────────────────────────────────────────────
 
 
-@dataclass(frozen=True)
-class ArchivePageRef:
+class ArchivePageRef(BaseModel):
     """Deep-link target for a substantive Task state that produces an
     operator-readable artifact.
 
@@ -116,14 +116,19 @@ class ArchivePageRef:
 
     ``artifact_label`` is the human-readable label for the deep-link cell
     on page 25 — e.g. "Morning briefing" rather than the bare page slug.
+
+    ``kind`` is the discriminator field for the tagged-union round-trip
+    in :class:`alpha_engine_lib.pipeline_status.read.TaskRow.archive`.
     """
 
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["archive_page_ref"] = "archive_page_ref"
     page: str
     artifact_label: str
 
 
-@dataclass(frozen=True)
-class ArtifactReason:
+class ArtifactReason(BaseModel):
     """Explicit non-generic reason a substantive Task state has no archive
     page deep-link.
 
@@ -131,13 +136,26 @@ class ArtifactReason:
     a specific reason ("Substrate refresh; no per-run artifact"), never
     a generic "no artifact" placeholder. The reason text is what the
     page 25 cell renders.
+
+    ``kind`` is the discriminator field for the tagged-union round-trip
+    in :class:`alpha_engine_lib.pipeline_status.read.TaskRow.archive`.
     """
 
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["artifact_reason"] = "artifact_reason"
     reason: str
 
 
-# Type alias for the registry value — either a deep-link or an explicit reason.
-RegistryEntry = "ArchivePageRef | ArtifactReason"
+# Discriminated union for :class:`TaskRow.archive` — Pydantic V2 routes
+# dict input to the right variant via the ``kind`` tag, so
+# ``model_dump(mode="json")`` → ``model_validate`` round-trips reconstruct
+# the typed instance (instead of leaving the dict raw, which the page-25
+# ``isinstance`` checks would mis-classify as registry drift).
+RegistryEntry = Annotated[
+    Union[ArchivePageRef, ArtifactReason],
+    Field(discriminator="kind"),
+]
 
 
 # ── The registry ──────────────────────────────────────────────────────────
@@ -151,19 +169,29 @@ RegistryEntry = "ArchivePageRef | ArtifactReason"
 # (Saturday 89 / Weekday 36 / EOD 21 total states; nested Parallel branches
 # walked). Reviewed against ROADMAP L3050 + the post-2026-05-15
 # artifact-archive pages (dashboard #86: pages 16-22).
-STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
-    # ── Saturday SF (23 substantive Task steps) ──────────────────────────
+STATE_TO_ARCHIVE_PAGE: Final[dict[str, Union[ArchivePageRef, ArtifactReason]]] = {
+    # ── Saturday SF (24 substantive Task steps) ──────────────────────────
     "MorningEnrich": ArtifactReason(
-        "Daily OHLCV write to predictor/daily_closes/{date}.parquet; "
+        reason="Daily OHLCV write to predictor/daily_closes/{date}.parquet; "
         "no per-run rendered artifact — substrate for downstream stages."
     ),
     "DataPhase1": ArtifactReason(
-        "Bulk weekly write to predictor/price_cache/, archive/macro/, "
+        reason="Bulk weekly write to predictor/price_cache/, archive/macro/, "
         "ArcticDB universe library; no per-run rendered artifact — "
         "substrate refresh."
     ),
+    "Scanner": ArtifactReason(
+        reason="Standalone scanner Lambda (ROADMAP L1995 Phase 1-2, "
+        "alpha-engine-research #235): writes candidates.json for the "
+        "run_date as observe-only output, gated by "
+        "$.enable_standalone_scanner. No consumer reads it today (Phase "
+        "4 will flip RAG to read it; Phase 5 will flip Research). "
+        "Failure is non-blocking — the SF Catch routes forward to "
+        "CheckSkipRAGIngestion. Once Phase 4/5 lands, swap this entry "
+        "for an ArchivePageRef pointing at the scanner-candidates page."
+    ),
     "RAGIngestion": ArtifactReason(
-        "SEC/8-K/earnings/theses corpus refresh in rag/corpus/; "
+        reason="SEC/8-K/earnings/theses corpus refresh in rag/corpus/; "
         "substrate-only — consumed at Research time."
     ),
     "RegimeSubstrate": ArchivePageRef(
@@ -179,7 +207,7 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Morning research briefing",
     ),
     "DataPhase2": ArtifactReason(
-        "Alt-data + fundamentals refresh; substrate-only, no per-run "
+        reason="Alt-data + fundamentals refresh; substrate-only, no per-run "
         "rendered artifact."
     ),
     "EvalJudgeSubmitFirstSaturday": ArchivePageRef(
@@ -191,7 +219,7 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Eval judge (weekly batch)",
     ),
     "EvalJudgePoll": ArtifactReason(
-        "Polling state for the EvalJudge batch job; no per-run artifact — "
+        reason="Polling state for the EvalJudge batch job; no per-run artifact — "
         "see EvalJudgeProcess for the materialized rubric output."
     ),
     "EvalJudgeProcess": ArchivePageRef(
@@ -203,15 +231,15 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Eval 4-week rolling mean",
     ),
     "RationaleClustering": ArtifactReason(
-        "Rationale cluster artifact written to S3; no dedicated page yet "
+        reason="Rationale cluster artifact written to S3; no dedicated page yet "
         "(P3 follow-up — backlog)."
     ),
     "ReplayConcordance": ArtifactReason(
-        "Concordance metric written to backtest/{date}/; surfaced inline "
+        reason="Concordance metric written to backtest/{date}/; surfaced inline "
         "in Backtester evaluator report (page 21)."
     ),
     "Counterfactual": ArtifactReason(
-        "Counterfactual artifact written to backtest/{date}/; surfaced "
+        reason="Counterfactual artifact written to backtest/{date}/; surfaced "
         "inline in Backtester evaluator report (page 21)."
     ),
     "PredictorTraining": ArchivePageRef(
@@ -243,19 +271,19 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Weekly substrate health check",
     ),
     "NotifyComplete": ArtifactReason(
-        "Terminal success SNS publish to alpha-engine-alerts; "
+        reason="Terminal success SNS publish to alpha-engine-alerts; "
         "no persisted artifact (the email IS the surface)."
     ),
     "NotifyShellRunComplete": ArtifactReason(
-        "Friday-PM shell-run dry-pass terminal SNS publish; "
+        reason="Friday-PM shell-run dry-pass terminal SNS publish; "
         "no persisted artifact (the email IS the surface)."
     ),
     "HandleFailure": ArtifactReason(
-        "Terminal failure SNS publish to alpha-engine-alerts; "
+        reason="Terminal failure SNS publish to alpha-engine-alerts; "
         "no persisted artifact (the email IS the surface)."
     ),
     "PublishResearchFailureImmediate": ArtifactReason(
-        "Early-signal SNS publish fired the moment the Research branch "
+        reason="Early-signal SNS publish fired the moment the Research branch "
         "fails inside ResearchPredictorParallel — BEFORE the sibling "
         "PredictorTraining branch completes its work and the parallel "
         "aggregation joins. No persisted artifact (the email IS the "
@@ -264,7 +292,7 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         "CheckBranchOutcomes."
     ),
     "PublishPredictorFailureImmediate": ArtifactReason(
-        "Early-signal SNS publish fired the moment the PredictorTraining "
+        reason="Early-signal SNS publish fired the moment the PredictorTraining "
         "branch fails inside ResearchPredictorParallel — BEFORE the "
         "sibling Research branch's eval-judge / RollingMean / "
         "Counterfactual chain completes. No persisted artifact (the "
@@ -278,27 +306,27 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Deploy-drift assertions",
     ),
     "StartExecutorEC2": ArtifactReason(
-        "EC2 startInstances on the trading instance; no artifact — "
+        reason="EC2 startInstances on the trading instance; no artifact — "
         "operational only."
     ),
     "DescribeInstanceInfo": ArtifactReason(
-        "Boot diagnostic call against the trading instance; "
+        reason="Boot diagnostic call against the trading instance; "
         "no artifact — operational only."
     ),
     "CheckTradingDay": ArtifactReason(
-        "NYSE-holiday gate via SSM command; no artifact — gate outcome "
+        reason="NYSE-holiday gate via SSM command; no artifact — gate outcome "
         "is encoded in the SF branch taken."
     ),
     "NotifyHolidaySkip": ArtifactReason(
-        "Holiday-skip SNS publish; no persisted artifact (the email IS "
+        reason="Holiday-skip SNS publish; no persisted artifact (the email IS "
         "the surface)."
     ),
     "StopExecutorOnHoliday": ArtifactReason(
-        "EC2 stopInstances on the trading instance after a holiday-skip; "
+        reason="EC2 stopInstances on the trading instance after a holiday-skip; "
         "no artifact — operational only."
     ),
     "TradingDayCheckFailed": ArtifactReason(
-        "SF Pass state recording a holiday-skip outcome; no artifact."
+        reason="SF Pass state recording a holiday-skip outcome; no artifact."
     ),
     # MorningEnrich (weekday) — same state name as Saturday; same entry above wins.
     "PredictorInference": ArchivePageRef(
@@ -306,15 +334,15 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Predictor morning briefing",
     ),
     "CheckPredictorCoverage": ArtifactReason(
-        "Coverage-gate Lambda; outcome encoded in the SF branch taken — "
+        reason="Coverage-gate Lambda; outcome encoded in the SF branch taken — "
         "see PredictorHealthCheck for any persisted health JSON."
     ),
     "ReinvokePredictor": ArtifactReason(
-        "Re-invocation Lambda when CheckPredictorCoverage finds a gap; "
+        reason="Re-invocation Lambda when CheckPredictorCoverage finds a gap; "
         "no per-run artifact — replaces the PredictorInference output."
     ),
     "RecheckCoverage": ArtifactReason(
-        "Second coverage-gate Lambda after ReinvokePredictor; outcome "
+        reason="Second coverage-gate Lambda after ReinvokePredictor; outcome "
         "encoded in the SF branch taken."
     ),
     "PredictorHealthCheck": ArchivePageRef(
@@ -331,7 +359,7 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
     ),
     # ── EOD SF (5 substantive Task steps) ────────────────────────────────
     "PostMarketData": ArtifactReason(
-        "Polygon T+1 daily aggregate write to predictor/daily_closes/; "
+        reason="Polygon T+1 daily aggregate write to predictor/daily_closes/; "
         "substrate-only — consumed by EODReconcile."
     ),
     "CaptureSnapshot": ArchivePageRef(
@@ -347,17 +375,17 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, "ArchivePageRef | ArtifactReason"]] = {
         artifact_label="Daily substrate health check",
     ),
     "StopTradingInstance": ArtifactReason(
-        "EC2 stopInstances on the trading instance; no artifact — "
+        reason="EC2 stopInstances on the trading instance; no artifact — "
         "operational only."
     ),
     "ForceStopInstance": ArtifactReason(
-        "EC2 stopInstances fallback on a non-graceful EOD; no artifact — "
+        reason="EC2 stopInstances fallback on a non-graceful EOD; no artifact — "
         "operational only."
     ),
 }
 
 
-def lookup_registry(state_name: str) -> Optional["ArchivePageRef | ArtifactReason"]:
+def lookup_registry(state_name: str) -> Optional[Union[ArchivePageRef, ArtifactReason]]:
     """Return the registry entry for ``state_name`` (None if absent).
 
     ``None`` here signals "this state is not in the registry" — distinct

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/src/alpha_engine_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.35.0
+Version: 0.35.1
 Summary: Shared utilities for the Alpha Engine modules: preflight, structured logging with secret-redaction, ArcticDB universe access, NYSE-calendar dates + freshness predicates, decision capture, cost telemetry, RAG, agent output schemas, SSM-backed secrets, Telegram alerts + SNS fan-out, EC2 spot-launch resilience, SSM log-capture chokepoint, SSM send-command + poll chokepoint, and Step-Functions execution-state projection. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/tests/test_pipeline_status_read.py

@@ -462,3 +462,76 @@ def test_region_from_arn_returns_none_for_malformed():
     assert _region_from_arn("not-an-arn") is None
     assert _region_from_arn("arn:aws:states") is None
     assert _region_from_arn("arn:aws:states::123:stateMachine:x") is None
+
+
+# ── Archive-union JSON round-trip (regression for "registry drift" false positive) ──
+
+
+def _entered_and_succeeded(name: str, t0: datetime, t1: datetime) -> list[dict]:
+    return [
+        _entered(name, t0),
+        {
+            "type": "TaskStateExited",
+            "timestamp": t1,
+            "stateExitedEventDetails": {"name": name},
+        },
+    ]
+
+
+def test_task_row_archive_round_trips_through_json_for_archive_page_ref():
+    """The dashboard's st.cache_data wraps read_pipeline_state by doing
+    ``model_dump(mode="json")`` → cache → ``model_validate(dict)``. Before
+    this regression-guard, ``TaskRow.archive`` was typed ``Optional[Any]``,
+    so the JSON round-trip flattened ArchivePageRef instances to plain
+    dicts; page-25's ``isinstance(archive, ArchivePageRef)`` then misfired
+    and rendered ``⚠️ Registry drift`` for every state with a valid
+    registry entry. The discriminated-union typing
+    (``Annotated[Union[...], Field(discriminator='kind')]``) reconstructs
+    the typed instance on validate; this test guards the contract."""
+    t0 = datetime(2026, 5, 24, 9, 0, tzinfo=timezone.utc)
+    t1 = datetime(2026, 5, 24, 9, 5, tzinfo=timezone.utc)
+    client = _make_sfn_mock(
+        history_response={"events": _entered_and_succeeded("Research", t0, t1)}
+    )
+
+    run = read_pipeline_state(SATURDAY_ARN, client=client)
+    research_task = next(t for t in run.tasks if t.state_name == "Research")
+    assert isinstance(research_task.archive, ArchivePageRef)
+
+    # The actual code path that broke production: JSON round-trip.
+    round_tripped = PipelineRun.model_validate(run.model_dump(mode="json"))
+    round_tripped_task = next(
+        t for t in round_tripped.tasks if t.state_name == "Research"
+    )
+    assert isinstance(round_tripped_task.archive, ArchivePageRef), (
+        "TaskRow.archive must reconstruct as ArchivePageRef on JSON "
+        "round-trip — otherwise page 25's isinstance check falls through "
+        "to the registry-drift sentinel for every state."
+    )
+    assert round_tripped_task.archive.page == "17_Research_Briefing_Archive"
+
+
+def test_task_row_archive_round_trips_through_json_for_artifact_reason():
+    """Mirrors the ArchivePageRef round-trip but for the ArtifactReason
+    variant (substrate-only states like NotifyComplete + Scanner). Both
+    variants must reconstruct correctly on JSON round-trip; the
+    discriminated union differentiates them via the ``kind`` field."""
+    t0 = datetime(2026, 5, 24, 9, 0, tzinfo=timezone.utc)
+    t1 = datetime(2026, 5, 24, 9, 0, 1, tzinfo=timezone.utc)
+    client = _make_sfn_mock(
+        history_response={"events": _entered_and_succeeded("NotifyComplete", t0, t1)}
+    )
+
+    run = read_pipeline_state(SATURDAY_ARN, client=client)
+    notify_task = next(t for t in run.tasks if t.state_name == "NotifyComplete")
+    assert isinstance(notify_task.archive, ArtifactReason)
+
+    round_tripped = PipelineRun.model_validate(run.model_dump(mode="json"))
+    round_tripped_task = next(
+        t for t in round_tripped.tasks if t.state_name == "NotifyComplete"
+    )
+    assert isinstance(round_tripped_task.archive, ArtifactReason), (
+        "TaskRow.archive must reconstruct as ArtifactReason on JSON "
+        "round-trip — same regression class as the ArchivePageRef test."
+    )
+    assert "Terminal success" in round_tripped_task.archive.reason

{alpha_engine_lib-0.35.0 → alpha_engine_lib-0.35.1}/tests/test_pipeline_status_registry.py

@@ -104,6 +104,7 @@ def test_registry_covers_known_saturday_substantive_states():
     required = {
         "MorningEnrich",
         "DataPhase1",
+        "Scanner",
         "RAGIngestion",
         "RegimeSubstrate",
         "Research",
@@ -116,6 +117,7 @@ def test_registry_covers_known_saturday_substantive_states():
         "Parity",
         "Evaluator",
         "DriftDetection",
+        "SaturdayHealthCheck",
         "WeeklySubstrateHealthCheck",
         "NotifyComplete",
         "HandleFailure",
@@ -166,15 +168,23 @@ def test_lookup_registry_returns_entry_for_known_state():
 
 
 def test_archive_page_ref_is_frozen():
-    """ArchivePageRef + ArtifactReason are frozen dataclasses — mutation
-    is forbidden so consumers can rely on registry stability across
-    a process lifetime."""
+    """ArchivePageRef + ArtifactReason are frozen Pydantic models —
+    mutation is forbidden so consumers can rely on registry stability
+    across a process lifetime. Pydantic V2 raises ValidationError with
+    ``type='frozen_instance'`` on attribute set; older stdlib-dataclass
+    consumers would have seen TypeError / FrozenInstanceError, both
+    accepted here so the test survives the dataclass → BaseModel
+    transition without spurious churn."""
+    from pydantic import ValidationError
+
     ref = registry.ArchivePageRef(page="x", artifact_label="y")
-    with pytest.raises((TypeError, AttributeError)):
+    with pytest.raises((TypeError, AttributeError, ValidationError)):
         ref.page = "z"  # type: ignore[misc]
 
 
 def test_artifact_reason_is_frozen():
+    from pydantic import ValidationError
+
     reason = registry.ArtifactReason(reason="x")
-    with pytest.raises((TypeError, AttributeError)):
+    with pytest.raises((TypeError, AttributeError, ValidationError)):
         reason.reason = "y"  # type: ignore[misc]