alpha-engine-lib 0.32.0__py3-none-any.whl

alpha_engine_lib/ssm_log_capture.py

@@ -0,0 +1,274 @@
+"""
+SSM-step log capture + S3 ship-on-exit chokepoint.
+
+Consolidation substrate for the trap-and-log-ship pattern that previously
+appeared as an inline bash EXIT trap in every long Step Functions SSM
+state across the alpha-engine fleet (MorningEnrich, DataPhase1,
+RAGIngestion, DriftDetection in alpha-engine-data; PredictorTraining in
+alpha-engine-predictor; Backtester, Parity, Evaluator in
+alpha-engine-backtester). The pre-lift form looked like::
+
+    trap 'aws s3 cp /var/log/X.log "s3://alpha-engine-research/_ssm_logs/X/$(date -u +%Y-%m-%d)/$(hostname)-$(date -u +%H%M%SZ).log" --only-show-errors || true' EXIT
+    bash infrastructure/<launcher>.sh ... 2>&1 | tee /var/log/X.log
+
+The pattern was originally added by alpha-engine-data PR #244
+(2026-05-15) to close the diagnostic gap where SSM's 24KB
+``StandardOutputContent`` cap was hiding the root cause of long-step
+failures: by the time SF Catch surfaced exit-1, the spot instance had
+self-terminated and the full ``/var/log/X.log`` was gone with it. The
+EXIT trap fires before the script's real exit propagates, ships the log
+to S3, then yields back so the real exit code reaches the SF.
+
+**Why the lift to lib (2026-05-22):** PR #253 in alpha-engine-data
+(merged 2026-05-17) switched all 8 Saturday-SF spot states from plain
+``commands`` JSON arrays to ``commands.$ States.Array(...)`` so they
+could splice ``$.run_date`` / ``$.preflight_args`` via ``States.Format``.
+Inside ``States.Array`` arg strings, ASL's documented escape for an
+inner single quote is ``\\'`` — but in practice the AWS ASL evaluator
+does NOT unescape ``\\'`` to ``'``, it passes the backslash through
+literally. The trap line ``'trap \\'cmd\\' EXIT'`` rendered into the
+SSM ``_script.sh`` as ``trap \\'cmd\\' EXIT``; bash interpreted the
+``\\'`` outside quotes as a literal apostrophe stripped of its quoting
+power, then word-split the line and passed every token after ``aws`` to
+``trap`` as a signal name. Symptom: ``trap: s3: invalid signal
+specification``, exit 127 at line 7 of ``_script.sh``. The 2026-05-22
+Friday-PM shell-run dry-pass of the Saturday SF caught this exactly as
+designed (it was the first execution under the broken pattern; no
+Saturday SF had run between #253 merge and the dry-pass).
+
+Per the ``~/Development/CLAUDE.md`` SOTA / institutional-approach rule —
+sub-sub-rule "when mirroring a pattern across repos, consider lifting
+it into ``alpha-engine-lib``... Pure-Bash primitives can stay mirrored
+unless re-expressible as a Python CLI entry callable from Bash, in
+which case the CLI re-expression is the institutional path" — this
+module is the canonical Python primitive. The SF JSON now spells a
+single ``States.Format``-rendered string (no bash trap, no bash
+quoting, no ASL escape surface) and the consumer behavior lives here
+where it can be tested independently of every state's JSON shape.
+
+**Public API:**
+
+- :func:`run` — execute an inner command, tee its merged stdout+stderr
+  to a local log file AND to the parent process's stdout, on exit
+  (any code, including subprocess crash) ship the log to S3, return
+  the inner exit code verbatim.
+- CLI: ``python -m alpha_engine_lib.ssm_log_capture run --slug <X>
+  --log /var/log/<X>.log -- <inner-cmd...>``. Designed for SF JSON;
+  a single ``States.Format`` template with ``$.preflight_args``
+  interpolated via ``{}`` produces the entire invocation as one
+  un-quoted token list — no bash trap, no inner single quotes.
+
+**S3 layout:**
+
+``s3://{bucket}/_ssm_logs/{slug}/{YYYY-MM-DD}/{hostname}-{HHMMSSZ}.log``
+
+Defaults: ``bucket=alpha-engine-research``, prefix ``_ssm_logs``. Date,
+time, and hostname are computed at exit time (so a multi-hour run that
+straddles UTC midnight gets the actual exit-side date in the key).
+
+**Failure behavior — never raises:**
+
+- Inner command's exit code is propagated verbatim. Subprocess setup
+  failure (e.g., ``FileNotFoundError`` on the binary) is logged to the
+  log file and stderr, returns 127 to match the bash convention.
+- S3 upload failures (boto3 ``ClientError``, missing creds, missing
+  log file) are logged at WARNING and swallowed. The SF Catch must
+  see the true inner exit, not a secondary log-capture failure that
+  would mask it. Matches :mod:`alpha_engine_lib.alerts`' fail-safe
+  posture.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import socket
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Final
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BUCKET: Final[str] = "alpha-engine-research"
+S3_PREFIX: Final[str] = "_ssm_logs"
+
+
+def _exit_key(slug: str, *, now: datetime | None = None, host: str | None = None) -> str:
+    """Compute the S3 key for the log upload at exit time.
+
+    Public for tests; the canonical layout is
+    ``_ssm_logs/{slug}/{YYYY-MM-DD}/{hostname}-{HHMMSSZ}.log``.
+    """
+    now = now or datetime.now(timezone.utc)
+    host = host or socket.gethostname()
+    date_str = now.strftime("%Y-%m-%d")
+    time_str = now.strftime("%H%M%SZ")
+    return f"{S3_PREFIX}/{slug}/{date_str}/{host}-{time_str}.log"
+
+
+def _ship_log_to_s3(slug: str, log_path: Path, bucket: str) -> tuple[bool, str]:
+    """Upload ``log_path`` to S3.
+
+    Returns ``(ok, detail)``. Never raises. Computes the key at call
+    time so the timestamp reflects when the trap fires, not when the
+    wrapper started.
+    """
+    key = _exit_key(slug)
+    if not log_path.exists():
+        return False, f"log file not found: {log_path}"
+    try:
+        import boto3
+
+        s3 = boto3.client("s3")
+        s3.upload_file(str(log_path), bucket, key)
+        return True, f"s3://{bucket}/{key}"
+    except Exception as exc:
+        return False, f"{type(exc).__name__}: {exc}"
+
+
+def run(
+    slug: str,
+    log_path: Path | str,
+    cmd: list[str],
+    *,
+    bucket: str | None = None,
+    env: dict[str, str] | None = None,
+) -> int:
+    """Run ``cmd``, tee output to ``log_path`` and parent stdout, ship the log on exit.
+
+    Mirrors the pre-lift inline pattern::
+
+        bash <launcher> ... 2>&1 | tee /var/log/<slug>.log
+        # plus: trap 'aws s3 cp /var/log/<slug>.log "s3://..." || true' EXIT
+
+    Args:
+        slug: log slug used in the S3 key (e.g., ``"morning-enrich"``).
+        log_path: local log path to tee to (e.g., ``"/var/log/morning-enrich.log"``).
+        cmd: inner command as a list of argv (passed to subprocess
+            directly — no shell parsing, no quoting surface).
+        bucket: S3 bucket override (default: ``alpha-engine-research``).
+        env: environment override for the subprocess (default: inherit).
+
+    Returns:
+        Inner command's exit code. ``127`` if the subprocess could not
+        start (matches bash ``command not found`` convention).
+    """
+    bucket = bucket or DEFAULT_BUCKET
+    log_path = Path(log_path)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    exit_code = 1
+    try:
+        with open(log_path, "wb") as logf:
+            proc = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                env=env if env is not None else os.environ.copy(),
+            )
+            assert proc.stdout is not None
+            fd = proc.stdout.fileno()
+            while True:
+                chunk = os.read(fd, 8192)
+                if not chunk:
+                    break
+                sys.stdout.buffer.write(chunk)
+                sys.stdout.buffer.flush()
+                logf.write(chunk)
+                logf.flush()
+            proc.wait()
+            exit_code = proc.returncode
+    except FileNotFoundError as exc:
+        msg = f"alpha_engine_lib.ssm_log_capture: cannot exec {cmd!r}: {exc}\n"
+        _append_log(log_path, msg)
+        print(msg, file=sys.stderr)
+        exit_code = 127
+    except Exception as exc:
+        msg = f"alpha_engine_lib.ssm_log_capture: subprocess setup failed: {type(exc).__name__}: {exc}\n"
+        _append_log(log_path, msg)
+        print(msg, file=sys.stderr)
+        exit_code = 127
+    finally:
+        ok, detail = _ship_log_to_s3(slug, log_path, bucket)
+        if ok:
+            logger.info("ssm_log_capture: shipped %s", detail)
+            print(f"ssm_log_capture: shipped {detail}", file=sys.stderr)
+        else:
+            logger.warning("ssm_log_capture: ship failed (%s)", detail)
+            print(f"ssm_log_capture: log ship to S3 FAILED: {detail}", file=sys.stderr)
+
+    return exit_code
+
+
+def _append_log(log_path: Path, msg: str) -> None:
+    """Best-effort append to the log file. Never raises."""
+    try:
+        with open(log_path, "ab") as logf:
+            logf.write(msg.encode("utf-8"))
+    except Exception:
+        pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m alpha_engine_lib.ssm_log_capture",
+        description=(
+            "Run an inner command with stdout/stderr tee'd to a local log "
+            "file + parent stdout, ship the log to S3 on exit, propagate "
+            "the inner exit code. The institutional replacement for the "
+            "inline `trap 'aws s3 cp ...' EXIT` pattern that broke under "
+            "ASL States.Array escape semantics (alpha-engine-data PR #244 "
+            "→ this lift)."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+
+    run_p = subparsers.add_parser(
+        "run",
+        help="Run a command with log capture + S3 ship-on-exit.",
+    )
+    run_p.add_argument(
+        "--slug",
+        required=True,
+        help=(
+            "Log slug for the S3 key (e.g., 'morning-enrich'). Identifies "
+            "the SSM step under the _ssm_logs/ tree."
+        ),
+    )
+    run_p.add_argument(
+        "--log",
+        required=True,
+        help="Local log file path (e.g., /var/log/morning-enrich.log).",
+    )
+    run_p.add_argument(
+        "--bucket",
+        default=None,
+        help=f"S3 bucket override (default: {DEFAULT_BUCKET}).",
+    )
+    run_p.add_argument(
+        "inner_cmd",
+        nargs=argparse.REMAINDER,
+        help=(
+            "Inner command after `--`, e.g., "
+            "`-- bash infrastructure/spot_data_weekly.sh --morning-enrich-only`."
+        ),
+    )
+
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.WARNING)
+
+    inner = args.inner_cmd or []
+    if inner and inner[0] == "--":
+        inner = inner[1:]
+    if not inner:
+        parser.error("inner command required after `--`")
+
+    return run(args.slug, args.log, list(inner), bucket=args.bucket)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

alpha_engine_lib/telegram.py

@@ -0,0 +1,165 @@
+"""
+Telegram push-notification client for Alpha Engine modules.
+
+Consolidation substrate for Telegram sends across consumer repos. Before this
+module, ``alpha-engine/executor/notifier.py`` was the only Telegram producer
+and duplicated token/chat_id resolution, markdown escaping, and the
+fire-and-forget request shape inline. With the executor surveillance Lambda
+arc (ROADMAP L1067, 2026-05-13), a second producer (``alpha-engine-research``)
+needs the same send path — consolidating here prevents the
+"two writers diverged silently" antipattern.
+
+**Public API:**
+
+- :func:`send_message` — primitive single-message send. Returns ``bool``,
+  never raises. Misconfigured secrets resolve to a logged warning + ``False``,
+  not an exception, so caller code can be fire-and-forget at every site.
+- :func:`send_rollup` — convenience wrapper that joins a list of findings
+  into a single bulleted message, defaulting to ``disable_notification=True``
+  (in-channel surveillance digest without push buzz).
+
+**Severity tiering via ``disable_notification``.** Telegram's
+``disable_notification`` flag delivers the message into the chat silently —
+visible in-channel but no phone-buzz notification. Use this to send a single
+channel both loud (critical alerts: daemon-down, position drawdown) and
+silent (surveillance digests: untouched buy-candidates). Critical alerts:
+``send_message(text)`` (defaults to push). Informational digests:
+``send_rollup(findings)`` (defaults to silent).
+
+**Secret resolution.** Both ``TELEGRAM_BOT_TOKEN`` and ``TELEGRAM_CHAT_ID``
+are loaded via :func:`alpha_engine_lib.secrets.get_secret` with
+``required=False``. If either is absent, the call logs a warning and returns
+``False`` — matches the legacy ``notifier.py`` behavior so callers can be
+configured-or-no-op without conditional branching.
+
+**Failure behavior.** Network errors, HTTP non-200 responses, and timeouts
+are logged at WARNING and returned as ``False``. No exceptions propagate.
+This is by design — a failed Telegram notification must never block trade
+execution or surveillance Lambda completion.
+
+**Migration arc**: ``alpha-engine-config/private-docs/ROADMAP.md`` L1067
+("Intraday data store → executor surveillance Lambda"), PR 1 of the 3-PR
+sequence.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+import requests
+
+from alpha_engine_lib.secrets import get_secret
+
+logger = logging.getLogger(__name__)
+
+TELEGRAM_API_URL: Final[str] = "https://api.telegram.org/bot{token}/sendMessage"
+TELEGRAM_TIMEOUT_SEC: Final[int] = 5
+PARSE_MODE: Final[str] = "Markdown"
+
+
+def _escape_markdown(text: str) -> str:
+    """Escape Telegram Markdown v1 special characters.
+
+    Replaces characters that Telegram interprets as formatting markers
+    (``_``, `````, ``[``, ``]``) to prevent 400 Bad Request parse errors.
+    Preserves ``*`` for bold markers which callers control via message
+    templates.
+    """
+    return (
+        text
+        .replace("_", "-")
+        .replace("`", "'")
+        .replace("[", "(")
+        .replace("]", ")")
+    )
+
+
+def send_message(text: str, *, disable_notification: bool = False) -> bool:
+    """Send a single Telegram message to the channel resolved from secrets.
+
+    Loads ``TELEGRAM_BOT_TOKEN`` + ``TELEGRAM_CHAT_ID`` via
+    :func:`alpha_engine_lib.secrets.get_secret` (required=False). Applies
+    Markdown v1 escaping, ``POST``s with a 5-second timeout. Returns ``True``
+    on HTTP 200, ``False`` on any other outcome (logged at WARNING). Never
+    raises.
+
+    :param text: The message body. Markdown v1 formatting (``*bold*``) is
+        respected; other special characters are escaped automatically.
+    :param disable_notification: If ``True``, the message is delivered into
+        the chat silently (no phone push). Use for informational/digest
+        traffic that should be visible but not buzz.
+    :returns: ``True`` if the Telegram API returned HTTP 200, ``False``
+        otherwise (missing secrets, network error, non-200 response).
+    """
+    token = get_secret("TELEGRAM_BOT_TOKEN", required=False)
+    chat_id = get_secret("TELEGRAM_CHAT_ID", required=False)
+    if not token or not chat_id:
+        logger.warning(
+            "Telegram not configured — TELEGRAM_BOT_TOKEN=%s TELEGRAM_CHAT_ID=%s",
+            "set" if token else "MISSING",
+            "set" if chat_id else "MISSING",
+        )
+        return False
+
+    payload = {
+        "chat_id": chat_id,
+        "text": _escape_markdown(text),
+        "parse_mode": PARSE_MODE,
+        "disable_notification": disable_notification,
+    }
+
+    try:
+        resp = requests.post(
+            TELEGRAM_API_URL.format(token=token),
+            json=payload,
+            timeout=TELEGRAM_TIMEOUT_SEC,
+        )
+    except requests.RequestException:
+        logger.warning("Telegram send failed (request exception)", exc_info=True)
+        return False
+
+    if resp.status_code == 200:
+        return True
+    logger.warning(
+        "Telegram API returned %d: %s",
+        resp.status_code,
+        resp.text[:200] if resp.text else "",
+    )
+    return False
+
+
+def send_rollup(
+    findings: list[str],
+    *,
+    header: str | None = None,
+    disable_notification: bool = True,
+) -> bool:
+    """Send a bulleted rollup of N findings as a single message.
+
+    Convenience wrapper for surveillance digest traffic — a list of findings
+    becomes a single message with each finding rendered as a ``-``-prefixed
+    bullet. Defaults to ``disable_notification=True`` (silent in-channel) so
+    digests don't buzz the phone; pass ``False`` to override for high-severity
+    rollups.
+
+    Empty ``findings`` is a no-op that returns ``True`` without an API call —
+    callers can pass output of a filter directly without an emptiness check.
+
+    :param findings: List of finding strings (one per bullet).
+    :param header: Optional bold header rendered above the bullets.
+    :param disable_notification: Default ``True`` (silent). Pass ``False`` to
+        push.
+    :returns: ``True`` if no findings (no-op) or Telegram returned 200,
+        ``False`` on send failure.
+    """
+    if not findings:
+        return True
+
+    lines = []
+    if header:
+        lines.append(f"*{header}*")
+    lines.extend(f"- {item}" for item in findings)
+    text = "\n".join(lines)
+
+    return send_message(text, disable_notification=disable_notification)

alpha_engine_lib/trading_calendar.py

@@ -0,0 +1,236 @@
+"""
+trading_calendar.py — NYSE trading day check with holiday awareness.
+
+Lightweight implementation that doesn't require exchange_calendars or
+pandas_market_calendars. Maintains a static list of NYSE holidays through 2030.
+
+Usage:
+    python trading_calendar.py              # check today
+    python trading_calendar.py 2026-04-03   # check specific date
+
+Exit codes:
+    Always exits 0 — Step Function checks stdout markers, not exit code.
+
+Stdout markers:
+    "TRADING DAY"  = NYSE is open (proceed with pipeline)
+    "MARKET_CLOSED" = weekend or holiday (skip pipeline)
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import date, datetime, time, timedelta
+from zoneinfo import ZoneInfo
+
+# NYSE observed holidays through 2030.
+# Source: https://www.nyse.com/markets/hours-calendars
+# Updated annually — add new years as they're published.
+NYSE_HOLIDAYS: set[date] = {
+    # 2025
+    date(2025, 1, 1),    # New Year's Day
+    date(2025, 1, 20),   # MLK Day
+    date(2025, 2, 17),   # Presidents' Day
+    date(2025, 4, 18),   # Good Friday
+    date(2025, 5, 26),   # Memorial Day
+    date(2025, 6, 19),   # Juneteenth
+    date(2025, 7, 4),    # Independence Day
+    date(2025, 9, 1),    # Labor Day
+    date(2025, 11, 27),  # Thanksgiving
+    date(2025, 12, 25),  # Christmas
+    # 2026
+    date(2026, 1, 1),    # New Year's Day
+    date(2026, 1, 19),   # MLK Day
+    date(2026, 2, 16),   # Presidents' Day
+    date(2026, 4, 3),    # Good Friday
+    date(2026, 5, 25),   # Memorial Day
+    date(2026, 6, 19),   # Juneteenth
+    date(2026, 7, 3),    # Independence Day (observed, July 4 is Saturday)
+    date(2026, 9, 7),    # Labor Day
+    date(2026, 11, 26),  # Thanksgiving
+    date(2026, 12, 25),  # Christmas
+    # 2027
+    date(2027, 1, 1),    # New Year's Day
+    date(2027, 1, 18),   # MLK Day
+    date(2027, 2, 15),   # Presidents' Day
+    date(2027, 3, 26),   # Good Friday
+    date(2027, 5, 31),   # Memorial Day
+    date(2027, 6, 18),   # Juneteenth (observed, June 19 is Saturday)
+    date(2027, 7, 5),    # Independence Day (observed, July 4 is Sunday)
+    date(2027, 9, 6),    # Labor Day
+    date(2027, 11, 25),  # Thanksgiving
+    date(2027, 12, 24),  # Christmas (observed, Dec 25 is Saturday)
+    # 2028
+    date(2028, 1, 17),   # MLK Day
+    date(2028, 2, 21),   # Presidents' Day
+    date(2028, 4, 14),   # Good Friday
+    date(2028, 5, 29),   # Memorial Day
+    date(2028, 6, 19),   # Juneteenth
+    date(2028, 7, 4),    # Independence Day
+    date(2028, 9, 4),    # Labor Day
+    date(2028, 11, 23),  # Thanksgiving
+    date(2028, 12, 25),  # Christmas
+    # 2029
+    date(2029, 1, 1),    # New Year's Day
+    date(2029, 1, 15),   # MLK Day
+    date(2029, 2, 19),   # Presidents' Day
+    date(2029, 3, 30),   # Good Friday
+    date(2029, 5, 28),   # Memorial Day
+    date(2029, 6, 19),   # Juneteenth
+    date(2029, 7, 4),    # Independence Day
+    date(2029, 9, 3),    # Labor Day
+    date(2029, 11, 22),  # Thanksgiving
+    date(2029, 12, 25),  # Christmas
+    # 2030
+    date(2030, 1, 1),    # New Year's Day
+    date(2030, 1, 21),   # MLK Day
+    date(2030, 2, 18),   # Presidents' Day
+    date(2030, 4, 19),   # Good Friday
+    date(2030, 5, 27),   # Memorial Day
+    date(2030, 6, 19),   # Juneteenth
+    date(2030, 7, 4),    # Independence Day
+    date(2030, 9, 2),    # Labor Day
+    date(2030, 11, 28),  # Thanksgiving
+    date(2030, 12, 25),  # Christmas
+}
+
+
+def is_trading_day(d: date | None = None) -> bool:
+    """Return True if the given date is an NYSE trading day."""
+    if d is None:
+        d = date.today()
+    if d.weekday() > 4:  # Saturday=5, Sunday=6
+        return False
+    if d in NYSE_HOLIDAYS:
+        return False
+    return True
+
+
+def next_trading_day(d: date | None = None) -> date:
+    """Return the next NYSE trading day after the given date."""
+    if d is None:
+        d = date.today()
+    d = d + timedelta(days=1)
+    while not is_trading_day(d):
+        d = d + timedelta(days=1)
+    return d
+
+
+def previous_trading_day(d: date | None = None) -> date:
+    """Return the most recent NYSE trading day strictly before the given date."""
+    if d is None:
+        d = date.today()
+    d = d - timedelta(days=1)
+    while not is_trading_day(d):
+        d = d - timedelta(days=1)
+    return d
+
+
+def add_trading_days(start: date, n: int) -> date:
+    """Add ``n`` NYSE trading days to ``start`` (n >= 0).
+
+    Skips weekends + NYSE holidays. ``add_trading_days(d, 0) == d``
+    (no rounding to a trading day if ``d`` itself is not one — only
+    the forward steps land on trading days).
+
+    Use ``subtract_trading_days`` for negative offsets.
+    """
+    if n < 0:
+        raise ValueError(f"add_trading_days requires n >= 0, got {n}")
+    current = start
+    for _ in range(n):
+        current = next_trading_day(current)
+    return current
+
+
+def subtract_trading_days(start: date, n: int) -> date:
+    """Subtract ``n`` NYSE trading days from ``start`` (n >= 0)."""
+    if n < 0:
+        raise ValueError(f"subtract_trading_days requires n >= 0, got {n}")
+    current = start
+    for _ in range(n):
+        current = previous_trading_day(current)
+    return current
+
+
+def count_trading_days(start: date, end: date) -> int:
+    """Count NYSE trading days strictly between ``start`` and ``end``.
+
+    Half-open interval ``(start, end]`` — same convention as
+    ``add_trading_days``: ``count_trading_days(d, add_trading_days(d, n)) == n``
+    for any ``n >= 0`` and ``d`` (whether or not ``d`` is a trading day).
+
+    Returns 0 when ``end <= start``.
+    """
+    if end <= start:
+        return 0
+    total = 0
+    current = start
+    while current < end:
+        current = current + timedelta(days=1)
+        if is_trading_day(current):
+            total += 1
+    return total
+
+
+# NYSE regular-session close (early-close holidays like the day after
+# Thanksgiving close at 1 PM ET; we keep 4 PM as the conservative
+# threshold — consumers waiting on post-close data should not assume
+# anything before 4 PM ET).
+_NYSE_CLOSE_ET = time(16, 0)
+_NYSE_TZ = ZoneInfo("America/New_York")
+
+
+def last_closed_trading_day(now: datetime | None = None) -> date:
+    """Return the most recent NYSE trading day whose session has actually closed.
+
+    Unified "last closed trading day" semantic for data consumers in
+    both pre-open and post-close contexts:
+
+      - Monday 9 AM ET    → Fri (Monday's session has not closed yet)
+      - Monday 4:30 PM ET → Mon (Monday's session has closed)
+      - Sunday 10 AM ET   → Fri (nothing has closed since Fri)
+      - Tue after MLK Day → Fri before MLK Day (MLK is not a trading day)
+
+    Morning consumers naturally land on the prior trading day (market
+    hasn't closed yet); EOD consumers naturally land on the same day
+    (market has closed). Both consumers ask the same question and get
+    the correct answer without knowing which context they're in.
+
+    Accepts either a naive datetime (assumed in NYSE local time) or a
+    timezone-aware datetime (converted to NYSE time for comparison).
+    Defaults to now in NYSE time.
+    """
+    if now is None:
+        now = datetime.now(_NYSE_TZ)
+    elif now.tzinfo is None:
+        now = now.replace(tzinfo=_NYSE_TZ)
+    else:
+        now = now.astimezone(_NYSE_TZ)
+
+    today = now.date()
+    if is_trading_day(today) and now.time() >= _NYSE_CLOSE_ET:
+        return today
+    d = today - timedelta(days=1)
+    while not is_trading_day(d):
+        d = d - timedelta(days=1)
+    return d
+
+
+if __name__ == "__main__":
+    check_date = date.today()
+    if len(sys.argv) > 1:
+        check_date = date.fromisoformat(sys.argv[1])
+
+    trading = is_trading_day(check_date)
+    day_name = check_date.strftime("%A")
+
+    if trading:
+        print(f"{check_date} ({day_name}): TRADING DAY")
+        sys.exit(0)
+    else:
+        reason = "weekend" if check_date.weekday() > 4 else "NYSE holiday"
+        nxt = next_trading_day(check_date)
+        print(f"{check_date} ({day_name}): MARKET_CLOSED ({reason}) — next trading day: {nxt}")
+        # Exit 0 so SSM reports Success — Step Function checks stdout marker
+        # instead of exit code to distinguish holidays from script crashes.
+        sys.exit(0)