Migration / Control Tower

01 — Platform

A fleet, nota pipeline.

Specialized agents interpret legacy evidence and propose actions. Deterministic services enforce authorization, idempotency, budgets, validation results, approval integrity and legal state transitions.

Runs on

  • Cloud Run
  • Cloud Run Jobs
  • Pub/Sub
  • Firestore
  • BigQuery
  • Cloud SQL
  • Cloud Storage
  • Secret Manager
  • IAM
  • Vertex AI · Gemini
  • Artifact Registry
  • Cloud Build
  • Cloud Trace
  • Cloud Logging
  • Cloud Monitoring
  • Firebase Auth
  • Oracle JET
  • Terraform

Eighteen services and frameworks, one service identity per stage. Nothing here is aspirational — every one is in the deployed topology.

P.01The fleet

Every agent has one job and no authority beyond it.

Agents are discovered by capability through approved, versioned AgentCards instead of being hard-coded into the workflow. Publisher and approver identities must differ, preventing an agent package from approving itself into the fleet.

  • Catalogs schemas, SQL, DAGs, connection posture and ownership evidence.

    Source facts come from a capability-declaring adapter, not from a model. The adapter owns connection validation and the extraction of database facts, so table names, schema facts, connection health and measured row counts cannot be invented or replaced by generated text.

    Produces

    • Schema inventory
    • SQL and stored procedures
    • Scheduling artifacts
    • Connection posture
    • Ownership evidence

  • Reconstructs dependencies across databases, transformations and schedules.

    Hidden dependencies are what make a local change break a downstream report. Lineage separates dependencies that are proven from those that are only proposed, and that distinction survives into the interface rather than being flattened into a single graph.

    Produces

    • Asset relationships
    • Upstream and downstream impact
    • Proven vs. proposed edges
    • PII-aware impact map

  • Classifies PII, dialect risk, criticality and policy exposure.

    The policy engine receives structured identity, action, resource class and run context. It never receives free-text legacy content, so a hostile table comment has no channel into an authorization decision.

    Produces

    • PII classification
    • Dialect incompatibility
    • Criticality scoring
    • Policy exposure

  • Builds ordered targets, mappings, validation checks and remediation notes.

    The plan defines executable scope and wave order. Its hash is what a human approval is later bound to — change the plan and the prior approval is no longer valid for it.

    Produces

    • Ordered targets
    • Column mappings
    • Validation checks
    • Budgets
    • Recovery options

  • Runs schema, count, hash, aggregate, duplicate and null-profile checks.

    Validation frequently stops at row counts. Here it does not: deterministic validators compare source and target across six check families, and a run cannot advance toward approval until every required check passes.

    Produces

    • Schema equivalence
    • Row counts
    • Content hashes
    • Aggregates
    • Duplicates
    • Null profiles

  • Consumes human approval, performs the governed cutover, and monitors health.

    The Cutover agent can consume a valid token but cannot issue one. Publisher and approver identities must differ, and the token is cryptographically bound to the exact plan hash it was issued against.

    Produces

    • Approval consumption
    • Governed cutover
    • Row-count health
    • Hash health
    • Monitoring

  • Finds affected reports and downstream consumers through wildcard capability discovery.

    Cost is measured where it can be measured and declared unavailable where it cannot. Estimates based on measured usage are never presented as actual billed amounts.

    Produces

    • Affected reports
    • Downstream consumers
    • Usage-based estimates
    • Explicit unavailability

P.02Lifecycle

Nine steps, none of them optional.

  1. 01

    Register

    Register an estate using credential references rather than storing secret values.

  2. 02

    Discover

    Discover schemas, SQL, procedures, schedules, owners and connection posture.

  3. 03

    Reconstruct

    Reconstruct lineage and calculate migration risk.

  4. 04

    Plan

    Generate an ordered plan with mappings, validation checks, budgets and recovery options.

  5. 05

    Execute

    Execute bounded movement through Cloud Run Jobs.

  6. 06

    Validate

    Validate source and target using deterministic evidence.

  7. 07

    Recover

    Investigate known failures, recall proven remediation, apply a cataloged fix, and validate again.

  8. 08

    Approve

    Pause at READY_FOR_APPROVAL until an authenticated human approves the exact plan hash.

  9. 09

    Cut over

    Cut over, monitor row-count and hash health, and mark the run complete only from recorded state transitions.

P.03Durable state

A run is a legal path, or it is an error.

  1. REQUESTED
  2. DISCOVERED
  3. ANALYZED
  4. RISK_ASSESSED
  5. PLANNED
  6. MIGRATING
  7. VALIDATING
  8. PASSED
  9. READY_FOR_APPROVAL
  10. APPROVED
  11. CUTOVER
  12. MONITORING
  13. COMPLETE
On failureFAILEDINVESTIGATINGREMEDIATINGVALIDATING

A failed validation branches to FAILED → INVESTIGATING → REMEDIATING → VALIDATING. Illegal transitions raise an error rather than silently skipping state. Handlers claim idempotency keys transactionally, acknowledge messages only after successful completion, and can redo stale claims after a crash.

When validation fails, the recovery path builds an incident from deterministic evidence and uses lineage to locate the responsible pipeline. Gemini can explain a bounded root-cause hypothesis; ordinary code selects and applies only an approved remediation. Confirmed fixes are written to cross-run memory, but every future reuse still requires fresh validation.

Next

The system

Architecture