220 lines
11 KiB
Markdown
220 lines
11 KiB
Markdown
# 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).
|