# Session 0056.0 — Transcript

> Date: 2026-06-01
> Start: 2026-06-01T04-30 (PST implied)
> End:   2026-06-01T05-30
> Status: **FINAL**
>
> Driver session. Anchored in `ohm-rfc-app-flotilla`, also created the new
> `flotilla-core` repo and edited `engineering/launch-app`. No live OHM deploy;
> no secret bytes entered the session.

---

## Launch prompt

> **Build the launch-app skill suite — Slice 1: extract flotilla-core.**
> We're building a skill suite that walks a Wiggleverse engineer from "I want to
> build an app" to a verified PRE-PROD deployment, using the engineering guide
> as its rulebook. Slice 1 = extract the generic 9-phase deploy engine out of
> `ohm-rfc-app-flotilla` into an installable `flotilla-core` package consuming a
> `deployment.toml`; de-OHM it (drop the pin.py ≥0.2.3 floor → optional config;
> generalize audit.py off rfc-app lockfiles; parameterize the data-dir /
> DB-filename / user-agent names); and **prove OHM still deploys through it
> unchanged** (SPEC §7.3 — the regression oracle). Scope guard: pre-prod,
> single environment, no slots/ramp/promote/rollback. Spec-driven, branch+PR,
> hard secrets rule, **this is a TEST RUN — do not publish a transcript unless I
> say so**, hand over the Slice 2 prompt before wrapping, and note anything in
> the SPEC that turned out wrong/underspecified once the real code was hit.

Spec read first: `engineering/launch-app/SPEC.md` (esp. §5 deployment.toml, §7
flotilla-core, §9 invariants, §10 out-of-scope), `engineering/launch-app/
ROADMAP.md` (Slice 1), `engineering/README.md` (the guide, §8 stack + §8.4
cloud profile), and the extraction source `ohm-rfc-app-flotilla` (`SPEC.md` +
the whole `ohm_rfc_app_flotilla/` package). Dogfood fixture `wiggle-snip`
inspected (same `backend/` + `frontend/` + `VERSION` standard-stack shape).

---

## Two load-bearing decisions (asked up front)

The engine was already cleanly dependency-injected at every external seam
(pin read / secret read / ssh / health probe), so de-OHM'ing was narrow —
~5 hard-coded values, not a re-architecture. The two genuine forks were the
operator's to own, so I asked before cutting code:

1. **flotilla-core's home** → **new sibling repo** (`~/projects/wiggleverse/
   flotilla-core`, package `flotilla_core`), editable-installed into OHM's venv.
   I did NOT create the Gitea repo (operator gesture) — flagged as follow-up.
2. **How OHM consumes the core** → **keep OHM's SQLite state**. The core is
   parameterized by an `AppContext`; OHM's shim supplies OHM's historical
   state-file names so the core opens the *existing* live DB unchanged. The
   `deployment.toml` path is the **new-app** onboarding lane (wiggle-snip, later
   slices), not a forced OHM migration. This is the lowest-risk reading of
   "still deploys unchanged" and avoids relocating the operator's live overlay /
   secret refs / 51-deploy history.

Both were the recommended options.

---

## What was built

### `flotilla-core` v0.1.0 (new repo, committed `cf22fc8`)

The generic engine, de-OHM'd. New scaffolding:

- **`context.py`** — `AppContext` (app_name, data_dir_env, default_data_dir,
  db_filename, user_agent, cli_help, version, **optional `pin_floor`**, audit
  lockfile paths) + a process-global active-context (`set_context` /
  `get_context`) + a generic `DEFAULT_CONTEXT` with **no app-specific defaults**
  (SPEC §5.2/§7.2).
- **`net.py`** — shared outbound-HTTP helpers (User-Agent from the active
  context, certifi-backed SSL context, Gitea token-auth header builder),
  de-duplicating what `pin`/`health`/`audit`/`gitea` each carried.
- **`deployment_toml.py`** — the SPEC §5.1 loader (`load()` → parsed record;
  `sync_to_registry()` → register into SQLite). Full fail-closed `validate`
  (§5.3) is deferred to Slice 2.
- **`cli.build_cli(context)`** — host factory: installs the context, brands the
  Click group's help, returns the group.

De-OHM changes (SPEC §7.2):

- `pin.py`: removed `MIN_RFC_APP_VERSION = (0,2,3)`. `parse_semver` reads
  `get_context().pin_floor`; **None = accept any well-formed SemVer**. Floor is
  now optional per-app config.
- `audit.py`: lockfile paths from the context (default = guide §8 standard-stack
  layout); skippable via layer selection / omitted `app_source_repo`.
- `db.py`: data-dir env / default dir / DB filename from the context.
- User-Agent strings, package-version dist name: from the context / generalized.
- `deploy.py` / `cli.py`: the "ohm: deployed v…" success line + the "pre-0.2.3"
  health hint generalized (deployment-name label; app-agnostic wording).

Tests: the **entire** `ohm-rfc-app-flotilla` engine suite was ported and is
green against the core (306), plus new de-OHM proofs (`test_context.py`) and a
`deployment.toml` round-trip (`test_deployment_toml.py`). **315 passed.** The
ported suite keeps its OHM-flavoured fixtures via a test `AppContext` (floor
`(0,2,3)`); the de-OHM *default* (no floor, generic names) is proven separately.

### `ohm-rfc-app-flotilla` v1.8.0 (branch `slice1-extract-flotilla-core`, commit `8c03538`)

Now a **thin shim**: the whole engine package was deleted and replaced with
`context.py` (`OHM_CONTEXT`) + `cli.py` (`build_cli(OHM_CONTEXT)`) + a version
`__init__`. `OHM_CONTEXT` reproduces the historical names — data-dir env
`OHM_RFC_APP_FLOTILLA_DATA_DIR`, dir `~/.ohm-rfc-app-flotilla`, db
`ohm-rfc-app-flotilla.db`, pin floor `(0,2,3)`, rfc-app lockfile paths.
`pyproject` now depends on `flotilla-core>=0.1.0`. CHANGELOG + README updated.
Engine tests removed (they live in core); a focused regression suite
(`tests/test_ohm_shim.py`, 7 tests) proves the seam.

---

## The §7.3 proof — OHM still deploys through the core

The shim + core were editable-installed into OHM's **live operator venv**, so
`ohm-rfc-app-flotilla` now runs through the core — itself part of the proof.
Verified against the operator's **real** state at `~/.ohm-rfc-app-flotilla/`:

- `deployment show` / `overlay show` / `deploy log` read the existing DB
  **unchanged** — all 8 secret refs, 19 overlay keys, the full 51-deploy
  history (last success #51 = v0.31.3) intact; `--version` → 1.8.0.
- `CLOUDSDK_ACTIVE_CONFIG_NAME=wiggleverse … deploy ohm-rfc-app --dry-run`
  (live): resolved the **real** private-repo pin **0.31.3** (token via Secret
  Manager / ADC — the private-repo read path works), validated **all 8 secret
  refs resolve** (bytes never displayed), computed the overlay snapshot hash,
  and rendered all 9 phases with OHM's real values. The de-OHM'd `(0,2,3)` floor
  correctly accepts 0.31.3.

**Operator decision:** stop at the dry-run proof rather than restart the live
service. This matches the roadmap's stated "(or a dry-run that exercises all 9
phases)." The offline stubbed 9-phase replay (`test_ohm_shim`) + the live
dry-run together satisfy §7.3. No live actuation was performed.

No secret bytes entered the session at any point (only references and
intentionally-public `VITE_*` values were ever displayed) — §3 invariant 1 held.

---

## SPEC feedback (the real deliverable for Slices 2–5)

Written in full to `engineering/launch-app/SLICE-1-SPEC-FEEDBACK.md`. The two
that **must be settled in the SPEC before/within Slice 2**:

1. **§5.2 is too strong** — "flotilla-core reads only this file." The engine
   also owns an append-only **state store** (deploy log, health snapshots, the
   `in_progress` concurrency lock) that isn't config and can't live in
   `deployment.toml`. The SPEC currently implies the toml is the whole picture.
2. **§3.2 canonicity fork** — is `deployment.toml` re-read each deploy (toml
   canonical) or imported once (registry canonical)? Slice 1 shipped one-time
   import + kept OHM registry-canonical; Slice 2's `define-deployment` must
   choose. Recommendation: toml-canonical for new apps.

Also: §5.1 is missing a **Gitea host** and a **private-repo read-token** field
(both defaulted/accepted-optionally by the loader); §5.3's "vm.project ==
gcloud_config's project" needs a read the current gcloud guard deliberately
avoids (Slice 2's `validate` must add a read-only `gcloud config … describe`);
§5.1 collapses content-repo vs source-repo into one `repo` (fine for single-repo
new apps, can't express OHM's split); §3.3/§5.3 One-Name derivation can't be
applied to legacy/imported records (OHM's real names violate it — fine, it's
grandfathered). What held up well: the engine's DI discipline made de-OHM
mechanical; §7.2's three named targets were exactly right; the §10 scope guard
matched reality (nothing to resist adding).

---

## Open follow-ups (operator gestures / out of scope)

- Create the `flotilla-core` Gitea repo + push; pin OHM's dependency to a
  released `flotilla-core` instead of the local path.
- **Patchwatch runner image** (`runner/Dockerfile`, `pip install .`) needs
  `flotilla-core` in its build context before its next rebuild — the deployed
  image is unaffected until then. (Filed as a spawned task.)
- Merge `slice1-extract-flotilla-core` via PR (not yet pushed/PR'd).

ROADMAP updated: Slice 1 marked done; next-session brief points at the SPEC
feedback + Slice 2.

---

## Next-session prompt (Slice 2)

```
# launch-app Slice 2 — deployment.toml schema + define-deployment (SPEC §5, §6.6)

State: Slice 1 done. flotilla-core (~/projects/wiggleverse/flotilla-core,
package flotilla_core, 315 tests green) is the de-OHM'd engine + a
deployment_toml loader + cli.build_cli(context). ohm-rfc-app-flotilla v1.8.0 is
a thin shim over it (branch slice1-extract-flotilla-core — check if merged).
wiggle-snip is the dogfood fixture.

READ FIRST and act on it: engineering/launch-app/SLICE-1-SPEC-FEEDBACK.md.
Before writing Slice 2 code, correct the launch-app SPEC (own commit, guide
§3.2) for at least: §5.2 (the engine owns a STATE store separate from the
toml); §3.2/§5.1 (DECIDE toml-canonical vs registry-canonical — recommend
toml); §5.1 (add Gitea host + optional private-repo read-token); §5.3 (the
vm.project==gcloud_config-project rule needs a read-only `gcloud config …
describe`, not the existing name-only guard).

THEN build Slice 2: firm up the §5.1 schema (extend flotilla_core/
deployment_toml.py); build the fail-closed `validate` verb (§5.3 — each rule
rejects a crafted-bad record with the right message + remediation; a good one
round-trips); build `define-deployment` (the topology+names interview deriving
everything from the One Name §3.3, emitting + validating the record, following
the §8 UX contract). Tests are part of the slice.

Hard rules: no secret bytes in-session (stdin-piped commands only); cite
SPEC/guide section numbers in commits; branch + PR; still a TEST RUN — don't
publish a transcript unless told; dogfood against wiggle-snip. Scope guard:
pre-prod, single environment, no slots/ramp/promote/rollback.
```

---

## Artifacts

- `flotilla-core` @ `cf22fc8` (new repo, local) — `flotilla-core v0.1.0`.
- `ohm-rfc-app-flotilla` @ `8c03538` (branch `slice1-extract-flotilla-core`) —
  `flotilla v1.8.0: become a thin shim over flotilla-core`.
- `engineering/launch-app/SLICE-1-SPEC-FEEDBACK.md` (new); `ROADMAP.md` updated.
- No release tag, no OHM deploy-log row (no live deploy this session).