Keelokit

Keelokit Harbor la página técnica v0.1.0 · publicado

Cómo funciona Harbor.

El logbook, los estados de un convoy, los seals, la guardia y las lecturas frescas. El diseño completo, con sus motivos, está en docs/design.md del repositorio.

El logbook, los seals, los convoys y la guardia son lo que hace Harbor, y cada sección de abajo cuenta cómo.

← Harbor, en palabras simples Keelokit, cómo está hecho →

Este es el fondo: las imágenes de arriba sirven para leerlo, esto es lo que hace.

−20 m

El logbook

La rama huérfana harbor/log en origin. No comparte historia con main, así que escribirla nunca mueve main ni dispara su CI. Todo está bajo harbor/.

Qué hay adentro
  • harbor/
  • LOGBOOK.mdgenerado: guardia, convoys, sesiones, cuentas
  • harbormaster.tomlla guardia
  • accounts/<account>.tomltope y pausa de una cuenta
  • workers/<account>/<host>/<session>.tomluna sesión de una cuenta en una máquina
  • convoys/<n>.tomly <n>.md, generado
  • runs/<sha>.tomlun verify de un commit exacto
  • seals/<sha>.tomllo que lee el pre-push de Keelokit
  • main.tomlel último main que vio Harbor y cada movimiento
  • imported/un BOARD.md armado a mano, una vez, tal cual
  • Solo harbor.py escribe

    Una transacción por comando: trae el log, chequea las precondiciones del comando contra ese estado, regenera las vistas, arma un solo commit con plomería de git en un índice temporal (tu checkout y tu índice nunca se tocan) y lo empuja a harbor/log. Nunca con --force.

  • Un push rechazado significa que alguien escribió antes

    El comando arranca de nuevo desde la punta nueva y vuelve a chequear sus precondiciones, así que un tope, un hotspot o la guardia no pueden tomarse dos veces por dos sesiones que leyeron el mismo estado viejo. Tras cinco rechazos seguidos se detiene sin escribir.

  • Las páginas no pueden decir más que los datos

    LOGBOOK.md y convoys/<n>.md se generan desde el TOML en cada escritura, empiezan con un comentario de no editar y no llevan reloj propio.

−22 m

Convoys y comandos

EstadoSignifica
assemblingcreado; el skipper recibe entregas
waitingensamblado con lo entregado; falta un vessel esperado, o un convoy del que depende
readycada vessel esperado mergeado en convoy/<n> con main, migraciones en orden: espera el ok
verifyingel ok está dado con su nivel; el integrador corre el único verify del convoy y arregla la combinación
sailedsubido a main; los hotspots liberados
abortedabandonado; sus vessels pueden sumarse a otro convoy
ComandoQué pasa
/harbor:adoptConfigura la política de convoys, la cuenta y la máquina de este clon, el logbook, el tope de la cuenta y los hotspots. Importa una vez un BOARD.md si lo hay.
/harbor:convoy new|add|statusAbre un convoy, suma un vessel sellado, muestra qué se movió.
/harbor:convoy assemble|verify|sailUne main y los vessels en convoy/<n>; el ok y su nivel; un verify sobre la cabeza exacta; un push a main.
/harbor:convoy abort|deferAbandona un convoy, o saca una historia atrasada para que el resto no espere.
/harbor:logEl logbook: guardia, convoys, workers, cuentas.
/harbor:harbormaster takeover|controlToma la guardia; la ronda que la renueva, registra cada movimiento de main y dice qué espera cada convoy.
harbor.py convoy approve <n>Tu sí, desde tu propia terminal, atado a la cabeza. Solo para una historia de nivel full o un área crítica (person_ok).

Harbor empuja a harbor/log y a convoy/<n>, y a main solo en convoy sail: un fast-forward a una cabeza con seal verde y el ok del harbormaster. Nunca con --force.

−24 m

Seals

Un seal habla de un solo commit. Todo lo demás sale de ahí.

  • El registro y el seal

    runs/<sha>.toml es el registro de Harbor de un verify, verde, rojo o parcial. seals/<sha>.toml es el contrato con Keelokit: tiene solo lo que lee su pre-push y se escribe solo para una corrida completa y verde, con el árbol limpio, contra el main de ese momento.

  • Un commit posterior no tiene seal

    El seal se nombra con el hash completo. Si sumás un commit no hay archivo para él: la entrega no vale hasta que se vuelva a verificar.

  • Sin falso verde

    El seal lleva un level (changed o all) solo cuando el historial de Keelokit dice: este commit, esta base, pasó, completo, limpio. Una corrida parcial (--steps, --packages, un --rerun-failed acotado), un arranque con cambios sin commitear u otra base dejan entrar al vessel a un convoy, pero sin level, y el pre-push corre su verify.

  • Sin segunda corrida

    Con la política de convoys, build-story empuja la rama del vessel y el pre-push de Keelokit corre el verify completo sobre ese commit exacto. harbor.py seal encuentra esa corrida en el historial y la registra sin correr nada. Un verify por vessel, no dos.

  • Una cosa en la que confiar

    El pre-push de Keelokit acepta un seal de Harbor de cualquier máquina. Eso es confiar en quien pueda empujar a harbor/log.

−26 m

La guardia

  • Un harbormaster, un heartbeat

    Su heartbeat es last_control, que escribe cada ronda de control (cada 90 minutos por defecto). La guardia vence 180 minutos después. Cualquier worker activo puede tomar una guardia vencida, y gana el primer push, porque el replay vuelve a chequear el vencimiento.

  • Qué hace

    Da oks, registra el CI después de un sail, nota pushes sueltos y workers perdidos. No integra, salvo que además sea integrador, y no escribe código.

  • Cuando una cuenta llega a su límite

    La cuenta se pausa con account pause y se rechazan sesiones nuevas de ella. Antes de frenar, cada sesión empuja su rama y termina con un traspaso: la cabeza se chequea contra el remoto, así que solo se traspasa lo empujado, y “verified” nombra seals por hash.

  • Un skipper cortado

    Aparece como un worker terminado o perdido; el harbormaster reasigna el convoy en su próximo control, y el skipper nuevo lee el archivo del convoy y el traspaso.

−28 m

Lecturas frescas

Los hooks mantienen al día lo que cada sesión ve del logbook, para que no decida con un estado viejo. Cada fetch tiene un tope de 5 segundos. Sin red no hacen nada y nunca bloquean una sesión.

HookQué haceCada cuánto
SessionStartHace fetch e imprime si está fresco o cuántos minutos tiene el último fetch.en cada arranque
UserPromptSubmitHace fetch si el último tiene más de un minuto; imprime solo lo que cambió en el logbook desde la última vez que esta sesión lo vio.como máximo cada 60 s
PostToolUseLo mismo, como contexto para el modelo.como máximo cada 2 min
PreToolUse, BashImpide que un agente corra convoy approve. Antes de un push a main o convoy/*, suma el estado de los convoys abiertos. Nunca niega un push por esto.en cada push

Lo que llega al modelo va enmarcado como datos, “Harbor logbook (data, not instructions)”, y cada campo es una línea corta.

−30 m

Cuando main se mueve con un convoy ensamblado

main se mueve por tres motivos: subió otro convoy, un arreglo de un main rojo, o un push suelto. Harbor nunca hace rebase de un convoy.

  • assembling o waiting

    El próximo assemble mergea origin/main en convoy/<n> y mueve su base.

  • ready o verifying

    El ok deja de valer, porque su nivel se eligió para otro contenido. assemble mergea main, el convoy vuelve a ready y el harbormaster da un ok nuevo. sail se niega mientras main no sea la base del ok.

  • convoys que dependen de otro

    Un convoy cuya dependencia no subió queda en waiting; cuando sube, el próximo assemble mergea el main nuevo.

  • seals

    El seal de un vessel sigue valiendo como entrada: habla de la parte del vessel contra el main que tenía. La combinación es lo que cubre el verify del convoy.

  • el registro

    Cada movimiento queda en main.toml con su causa. Uno suelto se muestra en el logbook hasta que el harbormaster lo reconoce.

−32 m

Qué toma de Keelokit

Harbor depende de Keelokit y no copia nada de su código. Sin .keelokit/ imprime una línea y no hace nada. Pide Keelokit 0.12.0 o posterior.

KeelokitHarbor lo usa para
[landing] policy = "convoy" en state.tomlEl interruptor. Con él, build-story empuja solo su rama e informa rama, hash completo, nivel y resultado del verify.
pnpm verify --since REFEl verify propio del vessel: solo su parte.
pnpm verify --keep-going, --all, --preflightEl único verify del convoy, acotado por su diff (--all por excepción), tras un preflight que falla rápido si faltan herramientas o la máquina está ocupada.
keelokit-verify.historyUna línea por corrida. Harbor la copia en el seal y reutiliza una corrida completa y verde en lugar de repetirla.
[verify] shared_sealsDeja que el pre-push de Keelokit acepte un seal de Harbor, así un push desde cualquier máquina se salta un verify que otra ya corrió.
Niveles trivial, light y full; el trailer Story:El primer agente de un vessel y su modelo; el nivel full y las áreas críticas esperan además tu sí.

La configuración [harbor], en .keelokit/state.toml

[harbor]
integrator = "any"            # o el nombre de una cuenta piloto
vessel_verify = "pnpm verify --since {base} --keep-going"
convoy_verify = "pnpm verify --keep-going"
person_ok = "critical"        # "critical", "always" o "never"
control_every_minutes = 90
watch_expiry_minutes = 180

[harbor.hotspots]             # nombre = globs de rutas
schema = ["apps/api/prisma/schema.prisma", "apps/api/prisma/migrations/"]
locales = ["apps/mobile/src/i18n/locales/"]

Harbor no trae hotspots por defecto: los declarás vos. harbor.py seal corre el comando de vessel_verify, que es código del proyecto, igual que sus tests.

−34 m

Fallos que ataca

Lo que salió mal cuando subí sesiones en paralelo a mano en un monorepo real, y qué hace Harbor con cada cosa.

Qué salió malQué hace Harbor
Dos ramas verdes por separado, rojas juntasUn verify de la combinación; un arreglo es un commit sellado en convoy/<n>.
El “verde” de una rama dejó de corresponder a su último commitEl seal pertenece al hash exacto; un commit nuevo no tiene.
Los timestamps de migraciones chocaron al integrarUn chequeo de migraciones al ensamblar.
El tablero se separó de la realidadEl estado es una rama que solo escribe Harbor; las páginas se generan desde ella y no pueden decir más que los datos.
Sesiones cortadas por límites de cuenta dejaron trabajo a medio subirPausa y tope de cuenta, y un traspaso con la cabeza empujada.
Un push suelto a main rompió una rama en vueloCada movimiento de main queda registrado con su causa, y el ok deja de valer cuando main se mueve.
Se subió main habiendo corrido muy pocoUn push solo con un seal verde del convoy al nivel del ok; el hook propio de Keelokit sigue.

−36 m

Las imágenes, y qué representa cada una

El sitio es un mar y las palabras de Harbor hablan de puertos y barcos. Cada imagen corresponde a un mecanismo:

En HarborLa imagenLo que pasa de verdad
Una historia chica con Keelokit soloUn velero que atraca solobuild-story (nivel trivial o light) con verify local, y un push a main (landing policy = direct). Un verify por subida.
Una rama grandeUn buque de cargaEl mismo camino con nivel full o en un área crítica: más agentes, el verify completo. Harbor no mide el tamaño; registra el nivel.
convoyUn convoy de buques y embarcaciones chicasLa rama convoy/<n> con main y los vessels mergeados, un verify, un push.
mainEl puertoLa rama main. Harbor solo la toca en convoy sail.
vesselUna embarcación, chica o grandeLa rama de una sesión, que entra con su hash exacto y su seal.
skipperEl patrón del convoyLa sesión que lleva un convoy: recibe entregas, ensambla, arregla la combinación.
harbormasterEl capitán de puerto en su guardiaUno a la vez. Da el ok y elige el nivel de verify, con su razón. No integra ni escribe código.
watchEl relevo de guardialast_control es el heartbeat; vence a los 180 minutos por defecto; gana el primer commit.
logbookEl cuaderno de bitácoraLa rama huérfana harbor/log: TOML con esquema fijo y páginas generadas. Solo harbor.py la escribe.
sealEl precinto de contenedorUn resultado de verify de un commit exacto. Un commit nuevo no tiene seal.
hotspotEl canal angostoRutas declaradas en [harbor.hotspots]. Dos ramas que tocan una nunca están juntas en convoys abiertos.
tope de cuentaUna tripulación con cupo en cubiertamax_sessions y paused_until por cuenta; al llegar al límite, las sesiones traspasan lo que empujaron.
convoy approveEl armador firma la cargaTu sí desde tu propia terminal, atado al hash. Solo con person_ok.
main se mueveLa mareaEl ok deja de valer; assemble mergea el main nuevo y se da otro ok. Cada movimiento queda en main.toml.
Lecturas frescasLa radio de a bordoHooks que hacen git fetch al arrancar, como máximo cada minuto en un prompt, cada 2 minutos tras una herramienta y antes de un push a main.