alpha-engine-lib 0.42.0__tar.gz → 0.44.0__tar.gz

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.42.0
+Version: 0.44.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.42.0"
+version = "0.44.0"
 description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. 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.42.0 → alpha_engine_lib-0.44.0}/src/alpha_engine_lib/__init__.py

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

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/src/alpha_engine_lib/artifact_freshness.py

@@ -71,6 +71,7 @@ ships the freshness-monitor Lambda that wires the two together.
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from dataclasses import dataclass, field
 from datetime import date, datetime, timedelta, timezone
 from typing import Any, Final, Literal
@@ -596,3 +597,159 @@ def _cycle_length_seconds(spec: ArtifactSpec) -> float:
         assert spec.interval_minutes is not None
         return spec.interval_minutes * 60
     raise ValueError(f"unknown cadence {spec.cadence!r}")
+
+
+# ── Per-cycle completion rollup ───────────────────────────────────────────────
+
+
+CycleState = Literal["complete", "incomplete", "indeterminate"]
+
+
+@dataclass
+class CycleCompletion:
+    """Per-cycle completion verdict — the artifact-union judgment.
+
+    Aggregates the per-artifact :class:`CheckResult` rows for one
+    execution cycle into a single verdict over the *required* set
+    (the ``severity="critical"`` rows). Answers the question the
+    raw orchestrator status cannot on a recovery-stitched run: *did
+    this cycle actually deliver every load-bearing artifact?*
+
+    Recovery substitution is already folded in upstream — a
+    canonical-missing artifact rescued by its ``recovery_key_template``
+    arrives here as ``state="fresh"``. So this rollup judges the
+    execution UNION without re-HEADing anything.
+
+    Attributes:
+        state: ``"complete"`` ⇒ every required artifact is present +
+            valid (``fresh``, or suppressed by ``grace_period``).
+            ``"incomplete"`` ⇒ at least one required artifact is
+            ``missing`` / ``stale`` (a real delivery gap).
+            ``"indeterminate"`` ⇒ no real gap, but at least one probe
+            ``probe_failed`` (the monitor itself is broken, so the
+            cycle can't be confirmed). A real gap outranks an
+            indeterminate probe.
+        complete: ``True`` iff ``state == "complete"``.
+        cycle_label: The cycle's window label (e.g. ``"2026-W22"``),
+            for reporting. Informational — the caller passes it.
+        n_required: Count of ``severity="critical"`` artifacts judged.
+        n_satisfied: Count present + valid (``fresh`` + ``grace_period``).
+        missing / stale / probe_failed / grace_period: ``artifact_id``
+            localization lists — which artifacts landed in each state.
+        reason: Human-readable summary; routed to the report surface.
+    """
+
+    state: CycleState
+    complete: bool
+    cycle_label: str | None = None
+    n_required: int = 0
+    n_satisfied: int = 0
+    missing: list[str] = field(default_factory=list)
+    stale: list[str] = field(default_factory=list)
+    probe_failed: list[str] = field(default_factory=list)
+    grace_period: list[str] = field(default_factory=list)
+    reason: str = ""
+
+
+def cycle_completion(
+    spec_results: Iterable[tuple[ArtifactSpec, CheckResult]],
+    *,
+    cycle_label: str | None = None,
+) -> CycleCompletion:
+    """Roll per-artifact freshness results up into one cycle verdict.
+
+    ``cycle_completion(C) = ∀ required artifact a: present(a@C) ∧ valid(a@C)``
+    over the execution UNION, where the required set is the
+    ``severity="critical"`` rows. Non-critical (``warning``) artifacts
+    are excluded — they inform per-artifact alerting but never gate the
+    cycle verdict.
+
+    Pure: consumes already-computed :class:`CheckResult` rows (as
+    ``(spec, result)`` pairs so there's no positional-pairing hazard)
+    and performs no I/O. Recovery substitution and the calendar-holiday
+    short-circuit are already reflected in each ``result.state`` by
+    :func:`check_freshness`, so a holiday cycle or a recovery-rescued
+    artifact both count as satisfied here.
+
+    State precedence: a real delivery gap (``missing`` / ``stale``)
+    outranks a broken probe (``probe_failed``) — a confirmed miss is
+    more actionable than an unconfirmable one. ``grace_period`` counts
+    as satisfied (the producer is newly onboarded; suppressed by design)
+    but is surfaced in its own list so the caller can see it.
+
+    An empty required set returns ``state="complete"`` (vacuous truth) —
+    a cycle with no critical artifacts cannot be incomplete.
+    """
+    required = [(s, r) for s, r in spec_results if s.severity == "critical"]
+
+    missing: list[str] = []
+    stale: list[str] = []
+    probe_failed: list[str] = []
+    grace_period: list[str] = []
+    satisfied = 0
+
+    for spec, res in required:
+        if res.state == "fresh":
+            satisfied += 1
+        elif res.state == "grace_period":
+            satisfied += 1
+            grace_period.append(spec.artifact_id)
+        elif res.state == "stale":
+            stale.append(spec.artifact_id)
+        elif res.state == "missing":
+            missing.append(spec.artifact_id)
+        elif res.state == "probe_failed":
+            probe_failed.append(spec.artifact_id)
+
+    n_required = len(required)
+
+    if missing or stale:
+        gaps = []
+        if missing:
+            gaps.append(f"missing={missing}")
+        if stale:
+            gaps.append(f"stale={stale}")
+        return CycleCompletion(
+            state="incomplete",
+            complete=False,
+            cycle_label=cycle_label,
+            n_required=n_required,
+            n_satisfied=satisfied,
+            missing=missing,
+            stale=stale,
+            probe_failed=probe_failed,
+            grace_period=grace_period,
+            reason=(
+                f"cycle incomplete: {satisfied}/{n_required} critical artifacts "
+                f"present+valid; " + "; ".join(gaps)
+            ),
+        )
+
+    if probe_failed:
+        return CycleCompletion(
+            state="indeterminate",
+            complete=False,
+            cycle_label=cycle_label,
+            n_required=n_required,
+            n_satisfied=satisfied,
+            probe_failed=probe_failed,
+            grace_period=grace_period,
+            reason=(
+                f"cycle indeterminate: monitor probe failed for {probe_failed} — "
+                f"cannot confirm cycle ({satisfied}/{n_required} confirmed fresh)"
+            ),
+        )
+
+    grace_note = f" ({len(grace_period)} in grace period)" if grace_period else ""
+    return CycleCompletion(
+        state="complete",
+        complete=True,
+        cycle_label=cycle_label,
+        n_required=n_required,
+        n_satisfied=satisfied,
+        grace_period=grace_period,
+        reason=(
+            f"cycle complete: all {n_required} critical artifacts present+valid"
+            + grace_note
+        ),
+    )

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/src/alpha_engine_lib/transparency.py

@@ -64,7 +64,13 @@ class CheckResult:
 
     row_id: str
     cadence: str
-    status: str  # "ok" | "fail" | "not_yet_effective" | "error"
+    # "ok" | "fail" | "degraded" | "not_yet_effective" | "error"
+    # "degraded" = non-fatal: either a diagnostic row (non_fatal: true, e.g.
+    # pipeline_execution success_rate — observability, not a gate) or a present
+    # artifact carrying a benign producer status (non_fatal_statuses, e.g.
+    # no_recent_sf_run = no upstream data this cycle, not a missing diagnostic).
+    # Degraded does NOT count as a failure: no SNS alert, exit 0, CW value 1.0.
+    status: str
     detail: str
     effective_date: str
     artifact: str | None = None
@@ -157,13 +163,16 @@ def _check_row(
 
     sub: list[str] = []
     artifact_hint: str | None = None
+    degraded_detail: str | None = None
     for src in row["sources"]:
         try:
-            ok, detail, artifact = _check_source(
+            ok, detail, artifact, status_hint = _check_source(
                 src, today, s3_client, cloudwatch_client
             )
         except Exception as exc:  # pragma: no cover — defensive
-            ok, detail, artifact = False, f"checker error: {exc!r}", None
+            ok, detail, artifact, status_hint = (
+                False, f"checker error: {exc!r}", None, None
+            )
         if artifact and artifact_hint is None:
             artifact_hint = artifact
         if ok:
@@ -175,8 +184,28 @@ def _check_row(
                 effective_date=str(eff),
                 artifact=artifact_hint,
             )
+        if status_hint == "degraded" and degraded_detail is None:
+            degraded_detail = detail
         sub.append(detail)
 
+    # All sources failed. Classify non-fatal degradation vs hard fail:
+    #  - row-level ``non_fatal: true`` → diagnostic/observability row demoted
+    #    from a gate (Phase 1c: pipeline_execution success_rate).
+    #  - any source signalled "degraded" → present artifact carrying a benign
+    #    producer status (Phase 1a: e.g. no_recent_sf_run = no upstream data
+    #    this cycle, not a missing diagnostic).
+    # Either way the cycle isn't "broken" — surface it without failing the gate.
+    if row.get("non_fatal") or degraded_detail is not None:
+        return CheckResult(
+            row_id=row["id"],
+            cadence=row["cadence"],
+            status="degraded",
+            detail=degraded_detail or "; ".join(sub),
+            effective_date=str(eff),
+            artifact=artifact_hint,
+            sub_failures=sub,
+        )
+
     return CheckResult(
         row_id=row["id"],
         cadence=row["cadence"],
@@ -198,12 +227,22 @@ def _check_source(
     today: date,
     s3_client: Any,
     cloudwatch_client: Any,
-) -> tuple[bool, str, str | None]:
+) -> tuple[bool, str, str | None, str | None]:
+    """Run a source handler, normalized to ``(ok, detail, artifact, status_hint)``.
+
+    Handlers may return a 3-tuple (the common case) or a 4-tuple whose 4th
+    element is a ``status_hint`` ("degraded") used to mark a non-fatal
+    non-pass. Normalizing here keeps handlers that don't care unchanged.
+    """
     kind = src["kind"]
     handler = _SOURCE_HANDLERS.get(kind)
     if handler is None:
-        return False, f"unsupported source kind: {kind}", None
-    return handler(src, today, s3_client, cloudwatch_client)
+        return False, f"unsupported source kind: {kind}", None, None
+    result = handler(src, today, s3_client, cloudwatch_client)
+    if len(result) == 4:
+        return result
+    ok, detail, artifact = result
+    return ok, detail, artifact, None
 
 
 def _resolve_key(src: dict, today: date) -> tuple[str, str]:
@@ -293,7 +332,7 @@ def _resolve_and_age(
 
 def _check_s3_json(
     src: dict, today: date, s3_client: Any, _cw: Any
-) -> tuple[bool, str, str | None]:
+) -> tuple[bool, str, str | None] | tuple[bool, str, str | None, str | None]:
     bucket = src.get("bucket", DEFAULT_BUCKET)
     key, age, status = _resolve_and_age(src, today, s3_client)
     if key is None:
@@ -322,6 +361,22 @@ def _check_s3_json(
     except Exception as exc:
         return False, f"json parse error on s3://{bucket}/{key}: {exc!r}", key
 
+    # Phase 1a: a present artifact carrying a benign producer status is a
+    # legitimate cycle state (no upstream data), NOT a missing diagnostic and
+    # NOT a hard failure. Short-circuit BEFORE evaluating asserts so we don't
+    # report a misleading "coverage 0% < 99". Always-emit (producer side) is
+    # what makes this distinguishable from absence.
+    non_fatal_statuses = src.get("non_fatal_statuses", [])
+    prod_status = payload.get("status") if isinstance(payload, dict) else None
+    if non_fatal_statuses and prod_status in non_fatal_statuses:
+        return (
+            False,
+            f"degraded: producer status='{prod_status}' — no upstream data "
+            f"this cycle (s3://{bucket}/{key})",
+            key,
+            "degraded",
+        )
+
     failures: list[str] = []
     for required in src.get("assert_keys_present", []):
         if required not in payload:
@@ -636,8 +691,9 @@ def emit_cloudwatch_metrics(results: list[CheckResult], cloudwatch_client: Any =
 
     metric_data = []
     for r in results:
-        # 1 = ok or not_yet_effective (counts as healthy), 0 = fail
-        value = 1.0 if r.status in ("ok", "not_yet_effective") else 0.0
+        # 1 = ok / not_yet_effective / degraded (all non-failing), 0 = fail.
+        # Degraded is non-fatal so it must not trip the SubstrateRowOK alarm.
+        value = 1.0 if r.status in ("ok", "not_yet_effective", "degraded") else 0.0
         metric_data.append({
             "MetricName": "SubstrateRowOK",
             "Dimensions": [{"Name": "RowID", "Value": r.row_id}],
@@ -646,10 +702,12 @@ def emit_cloudwatch_metrics(results: list[CheckResult], cloudwatch_client: Any =
         })
     n_ok = sum(1 for r in results if r.status == "ok")
     n_fail = sum(1 for r in results if r.status == "fail")
+    n_degraded = sum(1 for r in results if r.status == "degraded")
     n_pending = sum(1 for r in results if r.status == "not_yet_effective")
     metric_data.extend([
         {"MetricName": "SubstrateChecksOK", "Value": float(n_ok), "Unit": "Count"},
         {"MetricName": "SubstrateChecksFailed", "Value": float(n_fail), "Unit": "Count"},
+        {"MetricName": "SubstrateChecksDegraded", "Value": float(n_degraded), "Unit": "Count"},
         {"MetricName": "SubstrateChecksPending", "Value": float(n_pending), "Unit": "Count"},
     ])
 
@@ -664,15 +722,22 @@ def format_report(results: list[CheckResult]) -> str:
     lines = ["Substrate Health Report", "=" * 50]
     n_ok = sum(1 for r in results if r.status == "ok")
     n_fail = sum(1 for r in results if r.status == "fail")
+    n_degraded = sum(1 for r in results if r.status == "degraded")
     n_pending = sum(1 for r in results if r.status == "not_yet_effective")
     n_total = len(results)
-    pct = (100.0 * n_ok / max(1, n_total - n_pending)) if n_total > n_pending else 0.0
+    # Gating denominator excludes pending (not yet effective) AND degraded
+    # (non-fatal, can't be scored pass/fail this cycle).
+    n_gating = n_total - n_pending - n_degraded
+    pct = (100.0 * n_ok / n_gating) if n_gating > 0 else 100.0
     lines.append(
-        f"OK: {n_ok}  Failed: {n_fail}  Pending: {n_pending}  "
-        f"({pct:.1f}% of effective rows passing)"
+        f"OK: {n_ok}  Failed: {n_fail}  Degraded: {n_degraded}  "
+        f"Pending: {n_pending}  ({pct:.1f}% of gating rows passing)"
     )
     lines.append("")
-    icon = {"ok": "OK ", "fail": "FAIL", "not_yet_effective": "PEND", "error": "ERR "}
+    icon = {
+        "ok": "OK ", "fail": "FAIL", "degraded": "DEGR",
+        "not_yet_effective": "PEND", "error": "ERR ",
+    }
     for r in results:
         lines.append(f"  [{icon.get(r.status, '?')}] {r.row_id:30s} {r.detail}")
     failures = [r for r in results if r.status == "fail"]
@@ -681,6 +746,12 @@ def format_report(results: list[CheckResult]) -> str:
         lines.append("ACTIONS NEEDED:")
         for r in failures:
             lines.append(f"  - {r.row_id}: {r.detail}")
+    degraded = [r for r in results if r.status == "degraded"]
+    if degraded:
+        lines.append("")
+        lines.append("DEGRADED (non-fatal — observability, no action gate):")
+        for r in degraded:
+            lines.append(f"  - {r.row_id}: {r.detail}")
     return "\n".join(lines)
 
 

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/src/alpha_engine_lib/transparency_inventory.yaml

@@ -24,9 +24,23 @@ inventory:
   - id: pipeline_execution
     cadence: weekly
     effective_date: 2026-04-01
+    # non_fatal (Phase 1c, 2026-05-29): raw CloudWatch SF success_rate is a
+    # FIRST-PASS / OPERATOR-TOIL diagnostic, NOT a health gate. On a young,
+    # recovery-stitched system a cycle that needs N executions (1 scheduled
+    # fail + recovery reruns) to produce a complete, valid artifact set is a
+    # healthy cycle with an efficiency cost — counting every manual recovery /
+    # smoke / postfix run against a 99% SLA produces false alarms (Sat 40% /
+    # weekday 71% on 2026-05-29, both already-recovered incidents). Cycle
+    # health is judged by the per-artifact deliverable rows below (the
+    # asset-based / data-contract gate); this row stays for visibility but a
+    # low success_rate degrades, it does not fail. See
+    # private-docs/artifact-completion-monitoring-design-260529.md (Move 1) +
+    # feedback_judge_recovery_sf_by_artifact_union_not_execution_status.
+    non_fatal: true
     description: >-
-      SF success rate ≥ 99% across Saturday + weekday + EOD pipelines,
-      with per-stage durations recorded.
+      First-pass SF success rate across Saturday + weekday + EOD pipelines
+      (operator-toil diagnostic, NOT a gate — recovery-stitched cycles are
+      healthy; deliverable rows below are authoritative).
     sources:
       - kind: cloudwatch
         namespace: AWS/States
@@ -64,6 +78,17 @@ inventory:
         # The most recent date's artifact is the authoritative one.
         key_pattern: backtest/{date}/decision_capture_coverage.json
         max_age_days: 8
+        # non_fatal_statuses (Phase 1a, 2026-05-29): the backtester always
+        # emits this artifact now (alpha-engine-backtester #265), so absence
+        # means the diagnostic never ran (a real failure), while a present
+        # artifact with status=no_recent_sf_run means the upstream Saturday SF
+        # produced no agent captures this cycle (research failed / recovery
+        # was predictor-only) — a legitimate recovery-stitched state, not a
+        # coverage regression. Degrade rather than fail; a genuinely dead
+        # research pipeline is caught independently by the research_signals
+        # freshness row. See artifact-completion-monitoring-design-260529.md.
+        non_fatal_statuses:
+          - no_recent_sf_run
         assert:
           - path: coverage_pct
             op: gte

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/src/alpha_engine_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.42.0
+Version: 0.44.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/tests/test_artifact_freshness.py

@@ -41,7 +41,9 @@ from alpha_engine_lib.artifact_freshness import (
     ArtifactSpec,
     CADENCE_SYMBOLS,
     CheckResult,
+    CycleCompletion,
     check_freshness,
+    cycle_completion,
     resolve_current_cycle,
     resolve_dedup_key,
 )
@@ -510,3 +512,114 @@ def test_cadence_symbols_match_documented_set():
     assert CADENCE_SYMBOLS == frozenset(
         {"saturday_sf", "weekday_sf", "eod_sf", "continuous"}
     )
+
+
+# ── Per-cycle completion rollup (Phase 1b) ──────────────────────────────────
+
+
+def _critical(artifact_id: str) -> ArtifactSpec:
+    return _spec(artifact_id=artifact_id, severity="critical")
+
+
+def _warning(artifact_id: str) -> ArtifactSpec:
+    return _spec(artifact_id=artifact_id, severity="warning")
+
+
+def _res(state: str) -> CheckResult:
+    return CheckResult(state=state, reason=f"test {state}")
+
+
+class TestCycleCompletion:
+    def test_all_critical_fresh_is_complete(self):
+        pairs = [
+            (_critical("a"), _res("fresh")),
+            (_critical("b"), _res("fresh")),
+            (_critical("c"), _res("fresh")),
+        ]
+        v = cycle_completion(pairs, cycle_label="2026-W22")
+        assert isinstance(v, CycleCompletion)
+        assert v.state == "complete"
+        assert v.complete is True
+        assert v.n_required == 3
+        assert v.n_satisfied == 3
+        assert v.cycle_label == "2026-W22"
+
+    def test_one_missing_is_incomplete(self):
+        v = cycle_completion([
+            (_critical("a"), _res("fresh")),
+            (_critical("b"), _res("missing")),
+        ])
+        assert v.state == "incomplete"
+        assert v.complete is False
+        assert v.missing == ["b"]
+        assert v.n_satisfied == 1
+
+    def test_one_stale_is_incomplete(self):
+        v = cycle_completion([
+            (_critical("a"), _res("fresh")),
+            (_critical("b"), _res("stale")),
+        ])
+        assert v.state == "incomplete"
+        assert v.stale == ["b"]
+
+    def test_probe_failed_only_is_indeterminate(self):
+        v = cycle_completion([
+            (_critical("a"), _res("fresh")),
+            (_critical("b"), _res("probe_failed")),
+        ])
+        assert v.state == "indeterminate"
+        assert v.complete is False
+        assert v.probe_failed == ["b"]
+
+    def test_real_gap_outranks_probe_failure(self):
+        """A confirmed miss is more actionable than an unconfirmable probe."""
+        v = cycle_completion([
+            (_critical("a"), _res("missing")),
+            (_critical("b"), _res("probe_failed")),
+        ])
+        assert v.state == "incomplete"
+        assert v.missing == ["a"]
+        assert v.probe_failed == ["b"]  # still localized, but doesn't set the verdict
+
+    def test_grace_period_counts_as_satisfied(self):
+        v = cycle_completion([
+            (_critical("a"), _res("fresh")),
+            (_critical("b"), _res("grace_period")),
+        ])
+        assert v.state == "complete"
+        assert v.complete is True
+        assert v.n_satisfied == 2
+        assert v.grace_period == ["b"]
+
+    def test_warning_severity_excluded_from_required_set(self):
+        """A missing WARNING artifact must not fail the cycle — only
+        critical rows gate the completion verdict."""
+        v = cycle_completion([
+            (_critical("a"), _res("fresh")),
+            (_warning("b"), _res("missing")),
+        ])
+        assert v.state == "complete"
+        assert v.n_required == 1
+        assert v.missing == []
+
+    def test_empty_required_set_is_vacuously_complete(self):
+        v = cycle_completion([(_warning("a"), _res("missing"))])
+        assert v.state == "complete"
+        assert v.complete is True
+        assert v.n_required == 0
+
+    def test_mixed_states_incomplete_localizes_all_gaps(self):
+        v = cycle_completion([
+            (_critical("a"), _res("fresh")),
+            (_critical("b"), _res("grace_period")),
+            (_critical("c"), _res("missing")),
+            (_critical("d"), _res("stale")),
+            (_critical("e"), _res("probe_failed")),
+        ])
+        assert v.state == "incomplete"
+        assert v.n_required == 5
+        assert v.n_satisfied == 2  # fresh + grace_period
+        assert v.missing == ["c"]
+        assert v.stale == ["d"]
+        assert v.probe_failed == ["e"]
+        assert v.grace_period == ["b"]

{alpha_engine_lib-0.42.0 → alpha_engine_lib-0.44.0}/tests/test_transparency.py

@@ -955,3 +955,112 @@ def test_format_report_lists_actions_for_failed_rows():
     out = format_report(results)
     assert "ACTIONS NEEDED" in out
     assert "b: missing column" in out
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — degraded (non-fatal) status: non_fatal_statuses + non_fatal row
+# ---------------------------------------------------------------------------
+
+
+def _s3_json_row(extra_src=None):
+    src = {
+        "kind": "s3_json",
+        "bucket": "b",
+        "key": "k.json",
+        "max_age_days": 4,
+        "assert": [{"path": "coverage_pct", "op": "gte", "value": 99}],
+    }
+    if extra_src:
+        src.update(extra_src)
+    return {
+        "version": 1,
+        "inventory": [{
+            "id": "agent_decisions", "cadence": "daily",
+            "effective_date": "2026-01-01", "description": "x",
+            "sources": [src],
+        }],
+    }
+
+
+def test_s3_json_non_fatal_status_degrades_not_fails():
+    """A present artifact carrying a benign producer status (no_recent_sf_run)
+    degrades — it is NOT a coverage failure and NOT a missing diagnostic."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps(
+        {"status": "no_recent_sf_run", "coverage_pct": 0.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "degraded"
+    assert "no_recent_sf_run" in res[0].detail
+
+
+def test_s3_json_non_fatal_status_ok_passes_normally():
+    """status=ok + coverage passing → ok (non_fatal_statuses doesn't interfere)."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps(
+        {"status": "ok", "coverage_pct": 100.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "ok"
+
+
+def test_s3_json_status_not_in_non_fatal_set_still_fails():
+    """A failing status NOT in non_fatal_statuses (here: low coverage) still
+    fails — only the listed benign statuses degrade."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps(
+        {"status": "ok", "coverage_pct": 50.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "fail"
+
+
+def test_missing_artifact_still_fails_even_with_non_fatal_statuses():
+    """Absence is a real failure: always-emit (producer) means a missing
+    object = diagnostic never ran, distinct from a benign present status."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()  # nothing put
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "fail"
+
+
+def test_row_non_fatal_degrades_on_source_failure():
+    """A row marked non_fatal: true degrades instead of failing when its
+    source fails (Phase 1c: pipeline_execution success_rate is a diagnostic)."""
+    inv = _s3_json_row()
+    inv["inventory"][0]["non_fatal"] = True
+    inv["inventory"][0]["id"] = "pipeline_execution"
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps({"coverage_pct": 10.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "degraded"
+
+
+def test_format_report_separates_degraded_from_actions():
+    from alpha_engine_lib.transparency import CheckResult, format_report
+    results = [
+        CheckResult("ok_row", "daily", "ok", "fine", "2026-01-01"),
+        CheckResult("bad_row", "daily", "fail", "broke", "2026-01-01"),
+        CheckResult("degr_row", "daily", "degraded", "no upstream data", "2026-01-01"),
+    ]
+    report = format_report(results)
+    assert "Degraded: 1" in report
+    assert "[DEGR] degr_row" in report
+    # degraded must NOT appear under ACTIONS NEEDED
+    actions = report.split("ACTIONS NEEDED:")[1].split("DEGRADED")[0]
+    assert "degr_row" not in actions
+    assert "bad_row" in actions
+    assert "DEGRADED (non-fatal" in report
+
+
+def test_real_inventory_pipeline_execution_is_non_fatal():
+    inv = load_inventory()
+    row = next(r for r in inv["inventory"] if r["id"] == "pipeline_execution")
+    assert row.get("non_fatal") is True
+
+
+def test_real_inventory_agent_decisions_degrades_on_no_recent_sf_run():
+    inv = load_inventory()
+    row = next(r for r in inv["inventory"] if r["id"] == "agent_decisions")
+    src = next(s for s in row["sources"] if s["kind"] == "s3_json")
+    assert "no_recent_sf_run" in src.get("non_fatal_statuses", [])