feat(freshness-monitor): Phase 3 Lambda — every-15min absence-driven artifact probe

[cipher813]

Summary

Phase 3 of the artifact-freshness-monitor arc (plan doc at ~/Development/alpha-engine-docs/private/artifact-freshness-monitor-260527.md; ROADMAP P1 entry in alpha-engine-config #342 + status update in #344). The absence-driven complement to flow-doctor / SF Catch / substrate-health-check (all event-driven). Closes the silent absence-of-artifact bug class — the 2026-05-17→27 pit_parity.json (load-bearing artifact silently absent for 11 days) + the sibling factor-profiles orphan + missing-signals.json incidents.

Depends on:

• alpha-engine-lib #83 (merged, v0.40.0 tag cut) — the artifact_freshness substrate
• alpha-engine-config #344 (merged) — the ARTIFACT_REGISTRY.yaml SoT + PR-time validator

Changes

infrastructure/lambdas/freshness-monitor/ (new Lambda):

• index.py — EventBridge cron handler (every 15min):

  1. load_registry(s3, REGISTRY_BUCKET, REGISTRY_KEY) — fetches _freshness_monitor/ARTIFACT_REGISTRY.yaml from S3, merges defaults block into each entry, instantiates ArtifactSpec.
  2. Walks every spec, calls alpha_engine_lib.artifact_freshness.check_freshness per row, isolates per-spec exceptions (_check_one wraps with a probe_failed fallback so a bad row doesn't sink the pass).
  3. Emits _freshness_monitor/check_results.json (dashboard surface in Phase 5) + _freshness_monitor/heartbeat.json (self-heartbeat per plan §3 invariant 9 — the monitor monitors itself).
  4. For misses past SLA (state ∈ {missing, stale, probe_failed}), routes to alpha_engine_lib.alerts.publish with dedup_key=resolve_dedup_key(spec, now) — collapses 4×/hour retries to one alert per cycle per artifact.
  5. probe_failed always escalates to severity=critical regardless of spec — the monitor itself is broken; operator must know (plan §3 invariant 6).
  6. OBSERVE-mode gate: MNEMON_FRESHNESS_MONITOR_ENABLED env var (default unset = false) suppresses alerts but emits results. Phase 6 cutover flips via aws lambda update-function-configuration without redeploying — mirrors mnemon 0.7.0rc4 pattern from 2026-05-24.

• requirements.txt — pinned to alpha-engine-lib@v0.40.0 + pyyaml.

• iam-policy.json — Logs + Telegram SSM params + alpha-engine-alerts SNS publish + S3 HeadObject/GetObject on alpha-engine-research + S3 PutObject scoped to _freshness_monitor/ + _alerts/_dedup/.

• deploy.sh — --bootstrap (IAM role + Lambda + EventBridge cron cron(*/15 * * * ? *) + cron permission), code-update path, registry upload from local alpha-engine-config clone to S3. Validates registry locally via alpha-engine-config/scripts/validate_artifact_registry.py BEFORE upload — malformed YAML never reaches S3. Mirrors the sf-telegram-notifier deploy.sh shape; managed outside CFN per the existing operator-deployed-only Lambda pattern.

• test_handler.py — 12 unit tests covering:

  • load_registry (defaults merge, per-entry override, ISO-string date coercion, missing-artifacts raise)
  • Handler OBSERVE-mode does not alert but emits heartbeat
  • Handler alerts-enabled fires alerts with resolved dedup_key
  • probe_failed routes to critical severity regardless of spec
  • Per-spec exception (e.g., unsupported placeholder) classified as probe_failed without sinking the rest of the pass
  • Env-flip cutover (OBSERVE → production) without code change
  • _maybe_alert per-state coverage (fresh skip, within-SLA-grace skip, missing-past-SLA fires, probe_failed bumps severity)

Deploy plan (post-merge, operator-driven)

# First-time bootstrap (creates IAM role + Lambda + EventBridge cron + uploads registry)
bash infrastructure/lambdas/freshness-monitor/deploy.sh --bootstrap

# Subsequent code or registry updates
bash infrastructure/lambdas/freshness-monitor/deploy.sh

Bootstrap default state: MNEMON_FRESHNESS_MONITOR_ENABLED=false (OBSERVE). Cutover (Phase 6) flips via:

aws lambda update-function-configuration \
  --function-name alpha-engine-freshness-monitor \
  --environment 'Variables={LOG_LEVEL=INFO,MNEMON_FRESHNESS_MONITOR_ENABLED=true}'

Soak plan (Phase 6)

≥2 weekly cycles in OBSERVE mode. Earliest cutover ~2026-06-13 if this PR lands before Sat 5/30 (so the next 5/30 + 6/6 Saturday SFs exercise the probe under realistic load); more realistically ~2026-06-20.

During soak: dashboard surface (Phase 5) populates with real check_results; operator validates alert payloads against known-good Saturday firings (no false alarms on holidays, recovery-SF substitution working, dedup window collapsing retry storms correctly).

Acceptance (plan §7)

• pytest test_handler.py — 12 passing
• Post-deploy: first cron firing within 15min emits _freshness_monitor/heartbeat.json to S3
• Post-deploy: simulated pit_parity-class silent failure (mock: rename the expected S3 key) fires Telegram with correct dedup key within ~15min
• Post-deploy: NYSE-holiday Monday (next is 2026-06-19 Juneteenth) produces zero alerts for weekday_sf artifacts despite cron firing
• Phase 5 dashboard PR consumes check_results.json

Test plan

• pytest infrastructure/lambdas/freshness-monitor/test_handler.py -v — 12 passing
• Local smoke: bash infrastructure/lambdas/freshness-monitor/deploy.sh --dry-run (after merge of feat(schema): signals.schema.json market_regime to 3-class — Phase 1C #344 is in operator's local checkout)
• Post-deploy smoke: --smoke flag invokes once and confirms heartbeat lands

Composes with

• alpha-engine-lib #83 — the artifact_freshness substrate (ArtifactSpec, check_freshness, resolve_dedup_key)
• alpha-engine-config #344 — the registry SoT
• [[feedback_no_silent_fails]] — operationalizes the rule for the absence-of-artifact case
• [[feedback_sota_institutional_default_no_shortcuts]] — registry-as-config (Google SRE Ch. 4 SLI/SLO pattern) + S3-loaded substrate over hardcoded specs
• [[feedback_lift_invariants_to_chokepoint_after_second_recurrence]] — Phase 4 CI-guard cascade ships next, mirroring the test_schema_contract.py chokepoint pattern across the 4 producing repos

🤖 Generated with Claude Code