Sincronización actual de entornos locales mesh nodes¶

Objetivo

Explicar de forma visual, técnica y rápida cómo se sincronizan hoy los nodos mesh locales en ATLANTYQA: qué capas existen, qué se sincroniza realmente, qué flujo sigue cada componente y dónde siguen mandando los gates humanos.

Lectura en 60 segundos¶

La sincronización actual no depende de un daemon mesh único. Hoy se compone de cinco piezas gobernadas:

perfil de nodo → define sync_mode, capacidad y política de workload,
descriptor mesh local → materializa identidad y labels del nodo,
sincronización Git por rama → trae la ola de trabajo correcta al dispositivo,
sincronización host → VM / runtime → propaga env y repo al nodo operativo,
gobierno humano → decide bootstrap, apply, PR, promoción y cambios sensibles.

Arquitectura visual¶

graph TD
    A[Perfil de nodo<br/>knowledge/datasets/citizen-mesh-device-profiles.tsv] --> B[Descriptor mesh local<br/>outputs/proxmox/mesh/*.node.env]
    B --> C[Runner self-hosted local<br/>self-hosted,local,mesh-ready,...]
    C --> D[Repo local del colaborador<br/>branch sync local-first]
    D --> E[Bootstrap de dispositivo<br/>bootstrap_device_artifacts.sh]
    E --> F[Host / Laptop / Workstation]
    F --> G[VM o runtime remoto<br/>MicroK8s / host operativo]
    D --> G
    F --> H[GitHub / origin]
    G --> I[Workloads<br/>docs-build, qa-checks, local-inference, model-eval]
    G --> J[Evidencia en outputs/**]
    H --> D

    style A fill:#eef9f5,stroke:#37a880,stroke-width:2px,color:#182232
    style B fill:#fdf8ef,stroke:#e7ae4c,stroke-width:2px,color:#182232
    style C fill:#f8f9fa,stroke:#182232,stroke-width:2px,color:#182232
    style D fill:#eef9f5,stroke:#37a880,stroke-width:2px,color:#182232
    style E fill:#fdf8ef,stroke:#e7ae4c,stroke-width:2px,color:#182232
    style F fill:#f8f9fa,stroke:#182232,stroke-width:2px,color:#182232
    style G fill:#eef9f5,stroke:#37a880,stroke-width:2px,color:#182232
    style H fill:#f8f9fa,stroke:#182232,stroke-width:2px,color:#182232
    style I fill:#fdf8ef,stroke:#e7ae4c,stroke-width:2px,color:#182232
    style J fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#182232

Capas del sistema¶

1. Capa de perfil¶

Fuente de verdad: - knowledge/datasets/citizen-mesh-device-profiles.tsv

Qué define: - mesh_profile_id - device_class - node_role - compute_tier - workload_policy - privacy_mode - sync_mode

Modos actualmente declarados:

Perfil	Clase	Rol	Sync mode	Uso esperado
`mesh-smartphone-edge`	smartphone	`edge-helper`	`periodic`	apoyo ligero y telemetría
`mesh-laptop-collab`	laptop	`collab-worker`	`hybrid`	docs, QA, inferencia local
`mesh-tablet-edu`	tablet	`edu-worker`	`periodic`	contenido educativo guiado
`mesh-workstation-power`	workstation	`power-worker`	`real-time`	evaluación pesada y batch jobs

2. Capa de identidad de nodo¶

Fuente operativa: - scripts/proxmox/device_sso_cli_framework.sh

Qué hace: - resuelve el perfil mesh, - calcula mesh_id, - recomienda labels del runner, - opcionalmente escribe el descriptor: - outputs/proxmox/mesh/<mesh-id>.node.env

Datos clave generados: - ATLANTYQA_MESH_ID - ATLANTYQA_MESH_PROFILE - ATLANTYQA_MESH_SYNC_MODE - ATLANTYQA_MESH_LABELS=self-hosted,local,mesh-ready,...

3. Capa de sincronización Git local¶

Fuente operativa: - scripts/proxmox/bootstrap_device_artifacts.sh

Contrato actual: - cada dispositivo se alinea con una rama explícita, - la actualización base del repo se hace con:

bash git fetch origin <branch> git checkout <branch> git pull --ff-only origin <branch>

Esto aplica tanto al bootstrap Linux/macOS como al flujo Windows+WSL.

4. Capa de bootstrap de runner¶

Fuente operativa: - scripts/proxmox/bootstrap_device_artifacts.sh - scripts/proxmox/bootstrap-self-hosted-runners.sh

Qué sincroniza: - tooling mínimo, - registro/reconfiguración del runner, - labels mesh-ready y mesh-id cuando el nodo entra en la federación local.

Patrón actual:

bash bash scripts/proxmox/bootstrap-self-hosted-runners.sh \ --scope repo \ --owner <owner> \ --repo <repo> \ --profile <profile> \ --labels <runner-labels> \ --reconfigure \ --token-paste-once \ --mesh-ready \ --mesh-id <hostname>

5. Capa host → VM / runtime¶

Fuente operativa: - scripts/proxmox/k8s_agent_orchestrator_ops.sh

Qué sincroniza realmente: 1. env file del host hacia la VM/runtime, 2. repo hacia la VM/runtime, 3. validación y apply de manifests remotos.

Modos de sync soportados hoy: - archive - required - best-effort - off

Lectura práctica: - archive: el host manda un overlay reproducible usando git archive, - required: la VM debe poder hacer git fetch/switch/pull, - best-effort: intenta Git remoto y, si falla, puede caer al overlay, - off: no sincroniza repo; usa el estado ya presente en la VM.

Flujo de comunicaciones entre componentes¶

sequenceDiagram
    autonumber
    participant U as Humano tech
    participant P as Perfil mesh
    participant D as Descriptor local
    participant R as Repo local
    participant G as GitHub origin
    participant H as Host local
    participant V as VM / Runtime remoto
    participant O as outputs/**

    U->>P: Selecciona perfil / política de nodo
    U->>D: Genera descriptor mesh
    D-->>H: Expone mesh_id, labels, sync_mode
    U->>R: Sincroniza rama local-first
    R->>G: fetch / pull / push (según gate humano)
    U->>H: Ejecuta bootstrap de runner
    H-->>G: Registra / reconfigura self-hosted runner
    U->>H: Lanza operación k8s-agent / reconcile
    H->>V: Copia env file host -> vm
    alt repo-sync=archive
        H->>V: Overlay repo vía git archive
    else repo-sync=required|best-effort
        V->>G: git fetch + switch + pull --ff-only
    end
    V->>V: validate/apply workloads
    V-->>O: Evidencia técnica y reportes
    U->>O: Revisión humana y decisión siguiente

Flujos de adopción rápida¶

Flujo A — dar de alta un nodo mesh local¶

```bash

1) generar descriptor gobernado¶

bash scripts/proxmox/device_sso_cli_framework.sh mesh \ --mesh-profile mesh-laptop-collab \ --write-mesh

2) generar artefactos de bootstrap¶

bash scripts/proxmox/bootstrap_device_artifacts.sh \ --owner atlantyqa-labs \ --repo atlantyqa-universe \ --branch $(git rev-parse --abbrev-ref HEAD) \ --mesh-ready ```

Flujo B — alinear repo local del nodo¶

bash git fetch origin $(git rev-parse --abbrev-ref HEAD) git pull --ff-only origin $(git rev-parse --abbrev-ref HEAD) source .venv/bin/activate

Flujo C — sincronizar host local con runtime remoto¶

bash bash scripts/proxmox/runbook_operacion.sh \ --phase reconcile \ --reconcile-mode apps \ --control-plane k8s-agent \ --hilt-audience ops

Qué se sincroniza y qué no¶

Sí se sincroniza hoy¶

identidad declarativa del nodo,
labels de runner,
rama Git activa,
env file del runtime,
repo del runtime por git pull o git archive,
evidencia en outputs/**.

No se sincroniza automáticamente por contrato¶

decisiones HILT,
creación automática de PR,
promoción a main,
cambios sensibles fuera de la rama/entorno acordados,
sustitución de ramas asignadas por ramas nuevas sin decisión humana.

Regla operativa para tech people¶

Regla simple

Si un nodo mesh tiene que ponerse al día, piensa siempre en este orden:

perfil,
descriptor,
rama local,
runner labels,
sync host → vm/runtime,
evidencia + decisión humana.

Referencias canónicas¶

knowledge/datasets/citizen-mesh-device-profiles.tsv
scripts/proxmox/device_sso_cli_framework.sh
scripts/proxmox/bootstrap_device_artifacts.sh
scripts/proxmox/bootstrap-self-hosted-runners.sh
scripts/proxmox/k8s_agent_orchestrator_ops.sh
docs/internal/sovereign-device-mesh-program.md
docs/ops/federated-mesh-verification-checklist.md
docs/internal/policies/common-agent-collaboration-policy.md