teleo/teleo-infrastructure
8
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 1
teleo-infrastructure/docs/workstreams/gcp-leoclean/goals.md

6.6 KiB
Raw Blame History

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.