ADR-0004: Per-Lambda PR preview deploys + promote-on-merge

• Status: Accepted (infrastructure shipped — Phase 3)
• Date proposed: 2026-04-10
• Date accepted: 2026-04-17
• Supersedes: none (first versioned Lambda deploy policy)
• Related: deployment-cleanup Phase 3 (#150), Phase 4 shared-lib extraction

Context

Vercel gives the Next.js app a preview deploy per PR, so reviewers can click a URL and see the change before it lands on main. Our Lambdas have no such workflow — the old lambda-deploy.yml only ran on push to main, which meant:

• Code review decisions had to be made blind to the packaged bundle.
• No smoke-invocation against real Lambda before the change reached prod.
• Bundle bloat was invisible until someone happened to deploy locally.
• Rollback required manually running lambda/<name>/rollback.sh against an alias, which only existed for propflow-inbound-processor.

We have four Lambdas today:

propflow-inbox-poller was retired in ADR-0011.

Decision

Add a per-Lambda GitHub Actions workflow that runs in two stages:

1. pr-preview job on pull_request whenever a file the Lambda bundles has changed:

   • Build the bundle, zip it.
   • Ensure a propflow-<name>-preview Lambda exists (clone config from the prod function on first run — same role / runtime / memory / env vars). The preview function has no trigger (no SQS, no EventBridge, no SES), so invoking it cannot touch production data paths.
   • aws lambda publish-version — captures an immutable preview version.
   • Smoke-invoke lambda/<name>/fixtures/*.json against the preview version.
   • Post a sticky PR comment with ARN, version, bundle size, and per-fixture smoke results.

2. prod-promote job on push to main:

   • Rebuild (see Known gap below).
   • update-function-code on the prod function.
   • publish-version — immutable prod version.
   • Smoke-invoke the new version before flipping the alias.
   • If smoke passes AND a :live alias exists, flip it. If no alias, the update-function-code above is already "live" (the EventBridge / SES trigger targets $LATEST). This is a soft migration path for adding aliases to the other Lambdas later.
   • Post-promote smoke against the alias (or the new version).
   • On any failure, emit a workflow annotation and do NOT flip the alias.

Known gaps (post-Phase-3)

• Promote rebuilds instead of reusing the PR version. The tested preview bundle is not carried through merge, so the promote job rebuilds the same commit. Phase 4 will stamp the green preview version on the PR (commit status or label) and make promote a aws lambda update-alias against the already-published version. Tagged TODO(phase4) in each workflow.
• Only propflow-inbound-processor has a :live alias. The workflows handle both cases, so we can add aliases to the other Lambdas incrementally without a workflow change.
• Fixtures for smoke. lambda/inbound-processor/fixtures/ exists with an empty-SQS event as the baseline. The other Lambdas need fixture packs (empty event, one-property event, error-path event). Tracked in Phase 3 follow-up cards. The composite action treats a missing fixtures dir as "skipped" so PRs don't fail while fixtures are being written.
• No Telegram notification on prod-promote failure yet. The existing src/lib/messaging/telegram-dispatch.ts is wired for product alerts, not CI. Workflow annotations are the primary surface today; adding a Telegram secret + job step is a Phase 3.1 follow-up.
• Path filters are broad. Until the Phase 4 shared-lib extraction lands, deploy-clara.yml triggers on most of src/lib/**. After the extraction to agents/clara/**, tighten these.

Consequences

• Every PR that touches Lambda-bundled code now publishes a real Lambda version that a reviewer can invoke manually (via AWS console or CLI) if they want to probe behavior beyond the fixtures.
• Prod deploys fail closed: a bad bundle fails the pre-flip smoke and the alias is never pointed at it. The previous version keeps serving.
• Five new AWS Lambda functions (propflow-<name>-preview) will be created on first PR run per Lambda. They carry the tag propflow-purpose=pr-preview so we can bulk-cleanup later.
• The legacy .github/workflows/lambda-deploy.yml stays one week as a break-glass manual fallback (workflow_dispatch only — the on: push trigger was removed so it doesn't double-deploy).

Rollback plan

If the new workflows misbehave:

1. Delete or disable the per-Lambda workflows (gh workflow disable).
2. Re-enable the on: push trigger in lambda-deploy.yml.
3. Manually run bash lambda/<name>/deploy.sh from a clean main checkout for the other Lambdas (these scripts still exist — we intentionally did not delete them in Phase 3).

References

• .github/workflows/deploy-clara.yml and siblings
• .github/actions/lambda-smoke/action.yml
• docs/architecture/lambda-ci-cd.md — operator-facing doc
• deployment-cleanup Phase 3 tracking issue #150