# Session 0058.0 — Transcript

> Date: 2026-06-01
> Start: 2026-06-01T06-28 (PST implied)  •  End: 2026-06-01T06-52
> Goal: Build the flotilla **per-PR preview environments** feature
> (ohm-rfc-app-flotilla SPEC §19.2 candidate). Resolve the two open forks first
> — runtime (Cloud Run vs VM-containers) and the invariant-5 trigger — then
> promote the verb surface into §12.1 as it ships.
>
> Outcome: **Feature built, tested, and locally verified across three repos;
> committed to feature branches (local-only — not pushed/merged, and no live
> GCP provisioning, per the operator's explicit scope decisions).** Both forks
> resolved as directed: **runtime = Cloud Run**, **trigger = operator-typed
> `preview up --pr=N`** (auto-on-PR deferred — invariant 5 not reopened). The
> §19.2 candidate is promoted to a real numbered section **§15** and the verb
> surface into **§12.1**. No secret byte ever entered the session (preview env
> is synthetic / public test values only).
>
> Highlights:
> - **flotilla-core 0.2.0** — the generic preview engine: migration 009
>   (`previews` + `preview_overlay_entries` + nullable `preview_*` columns),
>   `cloudrun.py` gcloud seam, `preview.py` build-and-deploy gesture,
>   version-agnostic health, `preview up|down|list|show` + `overlay --preview`.
>   28 new tests; **343 total green**.
> - **rfc-app 0.32.0** — the Cloud Run keystone: multi-stage `Dockerfile`
>   (nginx + uvicorn on one `$PORT`) + `deploy/preview/` (synthetic seed,
>   test-secret env example). **Built locally and run**: `/api/health` →
>   `{"version":"0.32.0","status":"ok"}`, SPA serves, synthetic users seeded.
> - **ohm-rfc-app-flotilla 1.9.0** — SPEC §15 + §13.12 + §12.1 promotion + §19.2
>   stub; `scripts/preview-infra-deploy.sh` (idempotent, dry-run verified, NOT
>   run live); `register-ohm.sh` preview coords + preview overlay. Shim 7 tests
>   green; CLI smoke green.
> - Architecture honored the v1.8.0 two-layer split: generic engine →
>   flotilla-core; OHM specifics → shim; container → framework repo.

---

## Pre-session state

- `ohm-rfc-app-flotilla` is a thin shim over `flotilla-core` since v1.8.0
  (launch-app SPEC §7). flotilla-core on `main` @ v0.1.0 (315 tests); shim on
  `slice1-extract-flotilla-core` @ v1.8.0.
- SPEC §19.2 carried the "Per-PR preview environments" candidate with the DB +
  audit-trail questions already settled (SQLite-only seeded images;
  production-only §10 trail) and two forks open.
- rfc-app @ origin/main v0.31.3 — FastAPI/uvicorn + Vite SPA, single SQLite, **no
  Dockerfile**.

## Plan

Entered plan mode, read the binding files directly (SPEC §12.1/§13/§19.2, the
flotilla-core engine, rfc-app runtime layout), and asked the operator the three
genuinely-blocking decisions:
1. rfc-app image keystone → **include it now** (framework-repo change).
2. session protocol → **claim a session ID** (this transcript).
3. live GCP → **code + idempotent script, no live run**.
Plan approved; claimed **session 0058** at start.

## Turn-by-turn arc

### Arc 1 — flotilla-core engine
migration 009 (previews + preview_overlay_entries + preview_* columns);
`cloudrun.py` (builds submit / run deploy / services delete-describe, config-
guard pinned, injectable runner); `preview.py` (preview_up/down/show — zero
secret resolution, production-only trail, version-agnostic health);
`health.evaluate/probe_loop` gained `require_version`; registry + CLI wiring
(`preview` group, `overlay --preview`, `deployment {add,update,show}` preview
fields). Existing 315 tests stayed green throughout.

### Arc 2 — flotilla-core tests
test_cloudrun (argv + config-guard refusal), test_preview (happy path, zero-
secret assertion, never-writes-deploys assertion, build/deploy/unhealthy
failure paths, down-prunes-row, CLI read verbs), plus health/overlay/deployment
extensions. **343 passed.**

### Arc 3 — rfc-app keystone
Dockerfile + deploy/preview/{entrypoint,nginx.conf.template,seed.sql,
preview.env.example} + .dockerignore. First `docker build` failed: vite requires
`VITE_APP_NAME` (the framework self-names — no default). Added the build ARG;
rebuild green. Ran the container locally: `/api/health` →
`{"version":"0.32.0","status":"ok"}`, SPA title "RFC App (preview)", entrypoint
logged "applied synthetic seed", 4 synthetic users present. VERSION + package.json
+ CHANGELOG → 0.32.0.

### Arc 4 — shim spec + scripts
SPEC: new §15 (forks settled, posture, two-layer split, invariants touched),
§13.12 (OHM preview coords + preview overlay), §12.1 verbs promoted, §19.2
candidate → "shipped — see §15" stub. `scripts/preview-infra-deploy.sh` (mirrors
patchwatch-runner-deploy.sh; dry-run verified). `register-ohm.sh` preview coords
+ preview overlay seeding. VERSION → 1.9.0; pyproject floor `flotilla-core>=0.2.0`;
CHANGELOG. Reinstalled flotilla-core editable; shim CLI smoke + 7 tests green.

### Arc 5 — commit + hand off
Committed all three feature branches **locally** (no push/merge — the "ship"
gesture was explicitly out of scope this session). Wrote this transcript.

## Cut state (end of session)

| Repo | Branch | Version | State |
|---|---|---|---|
| flotilla-core | `feat/preview-environments` | 0.2.0 | committed `333e0ff`, local-only, 343 tests green |
| rfc-app | `feat/containerize-for-preview` | 0.32.0 | committed `7e07a92`, local-only, image built+run locally |
| ohm-rfc-app-flotilla | `feat/preview-environments` | 1.9.0 | committed `0656056`, local-only, 7 tests green |

No push to any origin; no PR; no live GCP provisioning; no change to OHM's live
deployment record or VM. OHM production untouched.

## §19.2 / SPEC candidates surfaced

- **Cloud Build-native repo fetch** — the v1 cut builds from the operator's
  local rfc-app checkout (`--source`); flotilla never clones (§4.2). A Cloud
  Build trigger / repo-source build would drop the local-checkout requirement.
- **Content-only (`ohm-rfc`) PR previews** — the first cut targets framework
  (rfc-app) PRs; previewing a content PR against a frozen prod framework image
  is a follow-up.
- **Auto-on-PR trigger** — stays deferred to the hosted-flotilla shift
  (invariant 5).
- **Process-supervised preview container** — uvicorn is a reparented child of
  nginx; graceful drain on instance teardown is a nicety, not needed for an
  ephemeral preview.
All recorded in SPEC §15.9 / the §19.2 stub.

## What lands on the operator's plate

1. **Review + push the three feature branches** (currently local-only) and open
   PRs if desired — flotilla-core, rfc-app, ohm-rfc-app-flotilla.
2. **To actually run a preview** (when wanted): `scripts/preview-infra-deploy.sh`
   (creates the `previews` Artifact Registry repo + operator IAM), then
   `register-ohm.sh` (or `deployment update` + `overlay set --preview`) to land
   the §13.12 coords + preview overlay onto the live record, then
   `CLOUDSDK_ACTIVE_CONFIG_NAME=wiggleverse … preview up ohm-rfc-app --pr=<N>
   --ref=<branch> --source=<local rfc-app checkout>`.
3. **No secrets needed** — previews use synthetic / public test values only.

## Prompt the operator can paste into the next Claude Code session

```
Per-PR preview environments shipped this session (flotilla-core 0.2.0 +
ohm-rfc-app-flotilla 1.9.0 + rfc-app 0.32.0 — SPEC §15), committed to
feature branches but NOT pushed/merged and NOT yet provisioned live. Pick up
from there: (1) review the three feat/ branches (flotilla-core
feat/preview-environments, rfc-app feat/containerize-for-preview,
ohm-rfc-app-flotilla feat/preview-environments), push them, and open PRs;
(2) if I want a live preview, run scripts/preview-infra-deploy.sh against
wiggleverse-ohm (pinned gcloud config), apply the §13.12 preview coords +
preview overlay to the live deployment record, then do a real
`preview up ohm-rfc-app --pr=<N> --source=<local rfc-app checkout>` end-to-end
and confirm the Cloud Run URL serves /api/health. This is an OHM driver
session once it touches live GCP / the §13 record — claim a session ID at start.
Optional follow-ups queued in SPEC §15.9: Cloud Build-native repo fetch
(drop the local-checkout requirement) and content-only (ohm-rfc) PR previews.
```