# GCP-native Leo goal

## Outcome

Run Leo's Hermes `leoclean` runtime as a fresh GCP service, backed by the V3
LivingIP knowledge base in canonical Cloud SQL, and route Telegram directly to
that verified GCP service.

This is not a VPS lift-and-shift. The existing VPS is never copied into or run
inside GCP. It remains untouched as a temporary comparison and rollback source
until the GCP service has passed soak and restore testing.

## Target architecture

- An immutable `leoclean` image is pulled from Artifact Registry by digest.
- A dedicated GCP service runs Hermes with the `leoclean` profile.
- Cloud SQL PostgreSQL 16 is the canonical V3 knowledge authority.
- Secret Manager supplies only the scoped `leoclean_kb_runtime` credential.
- Leo reads canonical knowledge and stages proposals only through
  `kb_stage.stage_leoclean_proposal(...)`.
- Telegram delivery terminates at the verified GCP service.
- The protected Observatory remains a separate follow-up surface over
  canonical, proposal, vector, and runtime receipts.

## Current state

- Current main/base: `3d35a7fafb41b61a94cb75de9c231afdc08b7f2b`.
- PRs #220, #221, #226, #227, #228, #229, #230, and #231 are merged. Main
  therefore contains the source-first V3 rebuild foundation, the PostgreSQL
  least-privilege boundary, the exact-revision publication workflow, the
  hardened no-send installer with automatic transaction rollback, and the
  container-bound `verify-database` command.
- The exact-main GCP preflight passed for `3d35a7f`: `teleo-staging-1` and the
  private PostgreSQL 16 Cloud SQL endpoint were reachable, Artifact Registry was
  immutable, and neither the VM nor Cloud SQL had a public attachment.
- Manual publication run #4 passed for that exact revision. The retained GitHub
  artifact archive hashes to
  `sha256:dbe7a34f2c03e2240de54c40afe0aefae00013dff51e17913140fa38f6e119ea`.
  Its self-hashed publication journal records `fresh_push`, not reuse or
  reconciliation, and binds release hash
  `3e7b00d5ac12308cfc35e3b507258b659e6d95926f3c6241f67240d44105b72f`.
- Artifact Registry independently reports immutable manifest digest
  `sha256:c69781400eecd5d2a932b9c7c988ed460365b8bc3f592fe95e51e4c1edf7b230`
  and config digest
  `sha256:c5fc9e715bcbee7d4fcc512b0c38aa4acee589836fbc11dbe9c6c34194959438`,
  with the expected revision, input, artifact, identity, runtime, and target
  labels. The release descriptor and build/push receipt validate against current
  package code.
- A read-only IAM check confirms the scoped runtime secret exists with one
  enabled version, grants `roles/secretmanager.secretAccessor` only to
  `sa-teleo-staging-vm`, and the administrator secret does not grant that VM
  access. The VM also has repository-level Artifact Registry reader and no
  detected project-level role.
- The native PostgreSQL `leoclean_kb_runtime` role and password match remain
  unproven. Cloud SQL control-plane user listing is not authoritative for native
  PostgreSQL roles; the container-bound permission verifier is the intended
  proof.
- Branch `feat/leoclean-iap-installer-runner` now contains the local review
  candidate for the fixed-target IAP transfer/pull/install/restart/verify
  runner and receipt-bound post-success rollback. It remains unmerged and has
  not been used against GCP. The proportional suite passes 308 tests; the full
  suite passes 3,013 tests with 3 skips when the repository's Python 3.11
  environment is first on `PATH`.
- Installation of the no-send service, effective running-process identity,
  database permissions, restart behavior, and post-success rollback remain
  unproven.
- The source-first V3 reconstruction code is on main, but no canonical GCP
  promotion is implied by that merge.
- Telegram still does not route to GCP. The VPS, production traffic, and
  canonical proposal approvals remain untouched.

## Execution order

1. Completed: merge the container-bound database verifier, run its disposable
   PostgreSQL and OCI fail-closed tests, publish the exact-main candidate, retain
   the complete artifact, and cross-check its receipts and registry digests.
2. Local implementation complete; review and merge the narrow fixed-target IAP
   transfer/install/restart/verify runner plus receipt-bound post-success
   rollback. It consumes only the finalized release artifact and expected
   hashes, pulls only the immutable digest, preserves ephemeral credential
   cleanup, and emits sanitized self-hashed receipts.
3. Prove or provision `leoclean_kb_runtime`. The VM already has access only to
   the scoped secret; verify that secret matches the native role, allowed reads,
   transaction-rolled-back function-only proposal staging, and denied writes or
   escalation.
4. Install the exact immutable image as a separate no-send GCP service. Bind
   systemd, PID/invocation, full container ID, image/config digests, and the
   container database receipt; restart once and then execute the reviewed
   post-success rollback proof.
5. Reconstruct or reconcile the V3 knowledge database into a separately
   identified canonical candidate and prove row/hash/source receipts before
   any promotion.
6. Bind the GCP runtime to the verified V3 canonical database and run database
   and behavioral parity checks without Telegram sends.
7. Switch Telegram delivery to the GCP service only after a separate human
   authorization, prove real response receipts, soak, restart, and restore
   behavior, and retain an immediate rollback path.
8. Revoke obsolete runtime credentials after soak. VPS destruction remains a
   separate explicit decision.

## Authority and rollback boundaries

- Database role provisioning can be rolled back independently by revoking
  the runtime role and removing its scoped secret access.
- Service deployment can be rolled back independently to the prior immutable
  image or stopped without changing canonical data.
- V3 database promotion requires a pre-promotion backup and exact reconciliation
  receipt; it does not imply Telegram cutover.
- Telegram routing is the final reversible switch and happens only after the
  no-send service, V3 data, restart, and rollback proofs pass.
- Canonical proposal approval, Observatory deployment, vector-backend choice,
  and irreversible VPS deletion are not part of the current deployment slice.

## Human gates

The container verifier and deployment runner each require exact-revision human
review before merge. Publication, GCP role/IAM mutation, live no-send service
installation, V3 canonical promotion, and Telegram cutover remain
distinct critical gates. Evidence from tests or agent review is advisory; the
exact revision and live receipts must be presented to the human development
lead at each gate.