chore: enable pipelines

.act/Dockerfile

@@ -0,0 +1,20 @@
+# Custom act runner image: Ubuntu 24.04 + OpenSSL 1.1 compat.
+# act's built-in ImageOS mapping downloads OTP binaries built for Ubuntu 20.04
+# (linked against libcrypto.so.1.1) even when using a 24.04 container image.
+# This adds the OpenSSL 1.1 compat library so OTP 28 loads correctly.
+#
+# checkov:skip=CKV_DOCKER_2: act runner image, not a production container — no healthcheck needed
+# checkov:skip=CKV_DOCKER_3: act runner requires root to simulate GitHub Actions runner
+FROM catthehacker/ubuntu:act-24.04
+# hadolint ignore=DL3008,DL3059
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libssl1.1 2>/dev/null || \
+    ( ARCH=$(dpkg --print-architecture) && \
+      if [ "$ARCH" = "arm64" ]; then \
+        echo "deb http://ports.ubuntu.com/ubuntu-ports focal-security main" >> /etc/apt/sources.list; \
+      else \
+        echo "deb http://security.ubuntu.com/ubuntu focal-security main" >> /etc/apt/sources.list; \
+      fi && \
+      apt-get update && \
+      apt-get install -y --no-install-recommends libssl1.1 ) && \
+    rm -rf /var/lib/apt/lists/*

.act/event.json

@@ -0,0 +1,13 @@
+{
+  "pull_request": {
+    "base": {
+      "ref": "main"
+    },
+    "head": {
+      "ref": "chore/enable-pipelines"
+    }
+  },
+  "repository": {
+    "default_branch": "main"
+  }
+}

.actrc

@@ -0,0 +1,5 @@
+-P ubuntu-latest=stacks-act-runner
+--pull=false
+--env GITHUB_TOKEN
+--env-file .act/.env
+-e .act/event.json

.claude/hooks/post-tool-lint.sh

@@ -49,10 +49,24 @@ run_check() {
 # Must appear before the extension-specific dispatch block.
 # ---------------------------------------------------------------------------
 if command -v gitleaks > /dev/null 2>&1; then
-  run_check \
-    "gitleaks detect --no-git --source ${FILE_PATH}" \
-    "Run: gitleaks detect --no-git --source ${FILE_PATH}" \
-    gitleaks detect --no-git --source "$FILE_PATH" --log-level error
+  # Skip .env files — they are gitignored by design and intentionally contain
+  # real secrets. The .gitleaks.toml path allowlist covers them in git-mode
+  # scans; --no-git --source on a bare file path bypasses that allowlist.
+  case "$BASENAME" in
+    .env|.env.local)
+      : # SKIP: gitignored env file
+      ;;
+    *)
+      _gitleaks_config=()
+      if [[ -f "${REPO_ROOT}/.gitleaks.toml" ]]; then
+        _gitleaks_config=(--config "${REPO_ROOT}/.gitleaks.toml")
+      fi
+      run_check \
+        "gitleaks detect --no-git --source ${FILE_PATH}" \
+        "Run: gitleaks detect --no-git --source ${FILE_PATH}" \
+        gitleaks detect --no-git --source "$FILE_PATH" --log-level error "${_gitleaks_config[@]}"
+      ;;
+  esac
 else
   : # SKIP: gitleaks not installed
 fi

.dockerignore

@@ -39,18 +39,23 @@ LICENSE
 README.md
 *.md
 
-# Scripts (not needed inside container)
+# Scripts — exclude all except proto generation (needed by Dockerfile.core build)
 scripts
+!scripts/gen-ecto-proto.sh
+!scripts/gen_python_proto.py
 
-# Proto — raw schemas not needed, but proto/gen/elm/ has committed Elm decoders required for build
-proto/stacks
-proto/buf.yaml
-proto/buf.gen.yaml
+# Proto — exclude generated outputs but keep source schemas + buf config (needed for codegen)
+proto/gen
 
 # Test fixtures / images (only e2e needs them, not runtime)
 e2e
 images
 
+# Built static assets — generated by build.js on the runner before fly deploy.
+# Must be explicitly included because they are gitignored (build outputs),
+# and Fly's remote builder may exclude gitignored files from the context.
+!apps/core/priv/static/
+
 # Editor / OS
 .DS_Store
 .vscode

.env.example

@@ -62,21 +62,6 @@ VISION_HMAC_SECRET=generate-a-strong-random-secret
 # Together AI API key for LLM features (used by vision sidecar)
 VISION_TOGETHER_API_KEY=together-api-key-for-llm
 
-# =============================================================================
-# Object storage (Cloudflare R2 — S3-compatible)
-# =============================================================================
-
-# Cloudflare account ID (used to construct the R2 endpoint URL)
-R2_ACCOUNT_ID=your_cloudflare_account_id
-
-# Access credentials for the R2 storage bucket
-# Create via: Cloudflare dashboard → R2 → Manage R2 API tokens
-R2_ACCESS_KEY_ID=your_r2_access_key
-R2_SECRET_ACCESS_KEY=your_r2_secret_key
-
-# Bucket name for uploaded book images
-R2_BUCKET_NAME=stacks-images
-
 # =============================================================================
 # Scraper (Rust microservice)
 # =============================================================================
@@ -117,9 +102,9 @@ STACKS_DBT_DB_PASSWORD=your-strong-password
 # Listed here for reference only.
 # OPEN_LIBRARY_BASE_URL=https://openlibrary.org
 
-# Google Books API key — currently hardcoded in ISBNResolver, not read from env.
-# Listed here for reference; wire through runtime.exs when API key rotation is needed.
-# GOOGLE_BOOKS_API_KEY=your-google-books-api-key
+# Google Books API key (ISBN resolution fallback — optional, raises rate limit from 1k/day to quota)
+# Obtain from: https://console.cloud.google.com/apis/credentials (Public data → API key, restrict to Books API)
+GOOGLE_BOOKS_API_KEY=your-google-books-api-key
 
 # Brave Search API key for source discovery
 BRAVE_SEARCH_API_KEY=your-brave-search-api-key
@@ -137,19 +122,27 @@ FLY_API_TOKEN=your-fly-api-token
 # =============================================================================
 # Neon (preview DB branching — only needed for deploy-preview.sh / CI)
 # =============================================================================
-
-# Neon project ID — found in the Neon console under Project Settings.
-# Used by deploy-preview.sh to fork a DB branch per PR.
-# Obtain from: https://console.neon.tech → your project → Settings → General
-NEON_PROJECT_ID=your-neon-project-id
-
-# Neon API key — used to create and delete preview branches via the Neon API.
+#
+# The Stacks uses two Neon projects with zero copy-on-write lineage:
+#   - `thestacks`         — production data. Prod Fly app only.
+#   - `thestacks-staging` — staging branch + every preview/<pr> branch.
+# Previews are CoW children of `staging` inside `thestacks-staging`, so they
+# inherit migrations + dev fixtures with zero chance of leaking prod data.
+# See docs/deployment/NEON_BRANCH_TOPOLOGY.md for the full architecture.
+
+# Neon project ID for the `thestacks-staging` project (NOT the prod project).
+# Previews are created as branches inside this project.
+# Obtain from: https://console.neon.tech → thestacks-staging → Settings → General
+NEON_STAGING_PROJECT_ID=your-neon-staging-project-id
+
+# Neon API key scoped to the staging project (or an account-level key).
+# Used by deploy-preview.sh to create/delete preview branches.
 # Obtain from: https://console.neon.tech → Account → API Keys → New API Key
-NEON_API_KEY=your-neon-api-key
+NEON_STAGING_API_KEY=your-neon-staging-api-key
 
-# Name of the Neon branch used as parent for preview branches.
-# Preview branches inherit this branch's data (fixture data only — no production data).
-# Default: staging. See docs/deployment/NEON_BRANCH_TOPOLOGY.md for the branch hierarchy.
+# Name of the parent branch for preview creation inside `thestacks-staging`.
+# Default: `staging` — a branch containing migrations + the dev fixture set.
+# See docs/deployment/NEON_BRANCH_TOPOLOGY.md.
 NEON_PARENT_BRANCH=staging
 
 # =============================================================================

.envrc

@@ -0,0 +1 @@
+use flake

.github/actions/check-slo-gate/action.yml

@@ -0,0 +1,45 @@
+name: "Check SLO gate (post-deploy health)"
+description: >
+  Wraps scripts/check-slo-gate.sh. Scrapes /internal/metrics for the
+  PROBE_WINDOW_SECONDS window (default 600s = 10 min), runs
+  probe-production.sh in parallel, computes SLIs against thresholds.
+  Exit 0 iff every SLI is healthy. Same SLI definitions used at both
+  deploy-time gating AND post-rollback verification — operators can
+  also re-run the underlying script manually to distinguish
+  genuinely-unhealthy state from probe flakiness.
+inputs:
+  out-path:
+    description: "Path to write the gate-observations.json artifact."
+    required: false
+    default: gate-observations.json
+  probe-window-seconds:
+    description: >
+      Window size in seconds. Default 600 (10 min). Use the same value
+      across deploy-time and post-rollback verification so the SLI
+      definitions stay aligned.
+    required: false
+    default: "600"
+  force-breach:
+    description: >
+      For testing only. When set to a known SLI name (e.g.
+      "beam_memory_mb"), forces that SLI to report breached=true
+      regardless of actual measurements. Used by the workflow's
+      force_rollback dispatch input to exercise the rollback path
+      without a real regression.
+    required: false
+    default: ""
+runs:
+  using: composite
+  steps:
+    - id: check-slo-gate
+      name: Run SLO gate script
+      shell: bash
+      # Inputs flow through env: rather than inline ${{...}} interpolation
+      # so a malicious value cannot escape the bash context. Defense in
+      # depth — same env-indirection pattern used by the rollback action.
+      env:
+        OUT_PATH: ${{ inputs.out-path }}
+        PROBE_WINDOW_SECONDS: ${{ inputs.probe-window-seconds }}
+        FORCE_BREACH: ${{ inputs.force-breach }}
+      run: |
+        bash "${{ github.action_path }}/../../../scripts/check-slo-gate.sh" --out "$OUT_PATH"

.github/actions/rollback-production/README.md

@@ -0,0 +1,176 @@
+# `rollback-production` composite action
+
+Wraps `scripts/rollback-production.sh` so its secret dependencies are
+**declarative inputs** — every secret the script reads is named at the
+call site instead of inherited silently from the surrounding `env:`
+block. Reusable from `deploy-production.yml`'s SLO-gate failure path
+and from any future `workflow_dispatch` operator-initiated rollback.
+
+## What it does
+
+Three rollback legs, **executed in this order**:
+
+1. **Core image** — `fly deploy --image $CORE_PREV_IMAGE` against
+   `$CORE_APP`, then waits on `/api/health` via `fly proxy`.
+2. **Neon DB** (optional) — `POST /branches/{id}/restore` resets the
+   prod branch to the captured pre-migrate LSN. The pre-rollback state
+   is preserved as a `pre-rollback-<sha7>-<ts>` Neon branch (free
+   safety net).
+3. **Modal vision** (optional) — clones `origin-remote` at
+   `$MODAL_PREV_COMMIT`, runs `modal deploy apps/vision/modal_app.py`
+   to revert the Modal app to the previous revision.
+
+### Ordering invariant
+
+Core image first, then DB, then vision. This is forced by what each
+direction guarantees (see
+[`docs/runbooks/vision-service-rollback.md`](../../../docs/runbooks/vision-service-rollback.md)
+for the long form):
+
+- **Image N-1 ↔ schema N** is **safe** by construction. The
+  `migration-safety` lint enforces expand-contract migrations, so
+  the post-migrate schema is forward-compatible with the previous
+  image. New columns are unused; no read/write conflicts.
+- **Image N ↔ schema N-1** is **unsafe**: image N may write columns
+  that don't exist in the older schema → INSERT/UPDATE failures.
+
+So we revert the image *first* (entering the safe corner), then the
+DB, then vision (which is stateless w.r.t. the DB schema).
+
+## Inputs
+
+### Required
+
+| Input | Used by | Example |
+|---|---|---|
+| `core-prev-image` | core leg | `registry.fly.io/thestacks-core@sha256:abc…` |
+| `fly-api-token` | core leg (`fly deploy`) | `${{ secrets.FLY_API_TOKEN }}` |
+| `rollback-reason` | audit log + stdout | `"SLO gate breached: vision_fuse_open=1"` |
+| `failed-sha` | audit log (`metadata.failed_sha`) | `${{ github.sha }}` |
+| `triggered-by` | audit log (`metadata.triggered_by`) | `slo-gate` \| `manual` \| `step-failure` \| `migration-failure` |
+| `database-url` | audit log INSERT | `${{ secrets.DATABASE_URL }}` |
+| `cloak-key` | audit-metadata encryption | `${{ secrets.CLOAK_KEY }}` |
+
+### Optional (with defaults)
+
+| Input | Default | Notes |
+|---|---|---|
+| `core-app` | `thestacks-core` | Fly app name. |
+| `modal-app` | `thestacks-vision` | Modal prod app name. |
+| `modal-prev-commit` | `""` | Empty = skip Modal rollback (bootstrap, see below). |
+| `modal-token-id` | `""` | **Required when** `modal-prev-commit` is set; else unused. |
+| `modal-token-secret` | `""` | **Required when** `modal-prev-commit` is set. |
+| `origin-remote` | `https://github.com/erinversfeld/thestacks.git` | Git remote for Modal commit checkout. |
+| `neon-project-id` | `""` | **Required when** `pre-migrate-lsn` is set. |
+| `neon-api-key` | `""` | **Required when** `pre-migrate-lsn` is set. |
+| `neon-branch-id` | `""` | **Required when** `pre-migrate-lsn` is set. |
+| `pre-migrate-lsn` | `""` | Empty = skip DB rollback (image-only — see below). |
+
+### Outputs
+
+| Output | Values |
+|---|---|
+| `core-rolled-back` | `true` (rolled back), `false` (skipped — image already current), `error` (leg failed). |
+| `modal-rolled-back` | `true`, `false` (skipped — `modal-prev-commit` empty), `error`. |
+| `db-rolled-back` | `true`, `false` (skipped — `pre-migrate-lsn` empty), `error`. |
+
+## Bootstrap edge cases
+
+Both Modal and DB rollback are optional **by design**. The first
+deploy on a brand-new prod stack and certain operator-suppressed
+flows produce empty inputs that exit cleanly rather than failing:
+
+- **No `main-<sha>` tag yet** → `modal-prev-commit` is empty. The
+  script prints `WARN rollback: MODAL_PREV_COMMIT is unset` and
+  completes a **core+DB-only rollback**. Output:
+  `modal-rolled-back=false`. Subsequent deploys (after `tag-main.yml`
+  stamps a tag) will roll vision back normally.
+- **No pre-migrate LSN captured** → `pre-migrate-lsn` is empty (e.g.
+  the deploy ran without migrations, or operator override). The
+  script prints `WARN rollback: PRE_MIGRATE_LSN unset` and completes
+  a **core+vision-only rollback** (image-only DB-wise). Output:
+  `db-rolled-back=false`.
+
+Neither case is a failure — both are documented partial-rollback
+paths.
+
+## Failure modes
+
+The action exits non-zero (and `log-audit` does **not** run, leaving
+audit-row absence as a signal that the rollback didn't complete) on:
+
+| Cause | Detection | Output |
+|---|---|---|
+| Required env missing | `validate-inputs` step's bash assertions | exit 1 before script runs |
+| `fly deploy` fails | script exits 1 with `FAIL rollback: fly deploy (core) failed` | `core-rolled-back=error` |
+| Neon restore HTTP non-2xx | script exits 1 with `FAIL rollback: Neon restore returned HTTP <code>` | `db-rolled-back=error` |
+| Modal deploy fails | script exits 1 with `FAIL rollback: modal deploy …` | `modal-rolled-back=error` |
+| `validate-inputs` fails (e.g. `pre-migrate-lsn` set without Neon vars) | bash `exit 1` | all three outputs `error` |
+
+`emit-outputs` always runs (`if: always()`) so the workflow can read
+the per-leg status even on failure. The audit row is the source of
+truth for "did rollback complete?" — its **absence** indicates the
+action exited before reaching `log-audit`.
+
+## How to invoke from `workflow_dispatch`
+
+The Phase 4 workflow change adds a `manual_rollback` boolean to
+`deploy-production.yml`'s `workflow_dispatch:` inputs. When set, the
+workflow short-circuits the deploy + gate steps and goes straight to
+this composite action:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      manual_rollback:
+        description: "Roll back the prod stack without running a deploy first."
+        type: boolean
+        default: false
+
+jobs:
+  rollback:
+    if: ${{ inputs.manual_rollback }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Resolve previous-state SHAs
+        id: prev
+        run: |
+          PREV_TAG=$(git tag --list 'main-*' --sort=-creatordate | head -1)
+          # …extract CORE_PREV_IMAGE + MODAL_PREV_COMMIT from the tag…
+      - name: Rollback production stack
+        uses: ./.github/actions/rollback-production
+        with:
+          core-prev-image: ${{ steps.prev.outputs.core-image }}
+          modal-prev-commit: ${{ steps.prev.outputs.modal-commit }}
+          modal-token-id: ${{ secrets.MODAL_TOKEN_ID }}
+          modal-token-secret: ${{ secrets.MODAL_TOKEN_SECRET }}
+          fly-api-token: ${{ secrets.FLY_API_TOKEN }}
+          neon-project-id: ${{ secrets.NEON_PROJECT_ID }}
+          neon-api-key: ${{ secrets.NEON_API_KEY }}
+          neon-branch-id: ${{ steps.prev.outputs.neon-branch-id }}
+          pre-migrate-lsn: ""  # manual rollbacks skip DB by default
+          rollback-reason: "Manual rollback by @${{ github.actor }}"
+          failed-sha: ${{ github.sha }}
+          triggered-by: manual
+          database-url: ${{ secrets.DATABASE_URL }}
+          cloak-key: ${{ secrets.CLOAK_KEY }}
+```
+
+For the full operator procedure (when to manual-rollback, what to
+expect, post-rollback checks) see the runbook at
+[`docs/runbooks/manual-rollback.md`](../../../docs/runbooks/manual-rollback.md)
+(landing in Phase 6 of Issue #137).
+
+## See also
+
+- [`docs/runbooks/vision-service-rollback.md`](../../../docs/runbooks/vision-service-rollback.md)
+  — rationale for the core → DB → vision ordering invariant.
+- [`scripts/rollback-production.sh`](../../../scripts/rollback-production.sh)
+  — the script this action wraps; canonical env-var contract.
+- [`apps/core/lib/stacks/audit.ex`](../../../apps/core/lib/stacks/audit.ex)
+  — `Stacks.Audit.log_rollback/1`, the audit + telemetry helper invoked
+  by the `log-audit` step.
+- Issue [#137](../../../issues/137-rollback-action-composite.md) —
+  full design rationale and DoD checklist.