Documentación pública · runtime experimental

Cómo pensar y operar Argentic Kernel

Esta página profundiza el concepto de la landing con vocabulario técnico, ciclo de trabajo, CLI, memoria externa y fronteras de autoridad. Está escrita para poder leerse sin conocer la historia interna del proyecto.

Alcance: AK sigue siendo experimental. Esta documentación explica la arquitectura observable y sus límites; no presenta como terminadas capacidades que todavía están en construcción.

Qué es AK, técnicamente

Un runtime y conjunto de contratos para convertir intención humana en trabajo asistido por IA sin delegar al modelo toda la memoria, la verdad, la validación y la autoridad.

Probabilístico

El modelo interpreta, resume, genera y propone. Puede cambiar de proveedor o tamaño.

Determinista

Identidades, hashes, contratos, validators, lifecycle y reglas de transición pertenecen al Kernel.

Humano

Las decisiones sensibles se expresan como autoridad sobre subjects y scopes identificables.

Principio arquitectónico: separar “el modelo cree que esto es correcto” de “el sistema puede demostrar qué objeto fue revisado, qué reglas pasaron y quién autorizó la siguiente acción”.

Ciclo gobernado

Los nombres concretos de artifacts pueden evolucionar. La separación de responsabilidades es la parte importante.

1 · Intención humana
2 · Interpretación estructurada + unknowns
3 · Revisión humana
4 · Base suficiente para proyectar
5 · Mission + Context
6 · Modelo / tool → candidate
7 · Verify / validators
8 · Human authorize
9 · Apply + observation + evidence

Materializado hoy

  • Intent review estructurado.
  • Evaluación determinista de resolución.
  • Base de proyección con objetivo anclado y roles explícitos.
  • Evaluación de suficiencia para avanzar hacia una misión.
  • Mission explícita.
  • Contexto verificable.
  • Provider/model configurable.
  • ChangeSet candidate.
  • Verify separado.
  • Autorización humana exacta.
  • Apply con re-verificación, rollback y observación.

Puente todavía en construcción

La intención humana ya puede estructurarse, revisarse y evaluarse para determinar si contiene suficiente significado relevante y un objetivo anclado para solicitar la siguiente proyección. Lo que todavía falta es derivar requirements sin inventarlos y materializar una Mission gobernada desde esa base.

El límite es deliberado: “suficiente para avanzar” no significa que existan requirements, que una Mission esté autorizada ni que el Kernel pueda seleccionar trabajo o conceder autoridad por inferencia.

CLI: superficie actual

El comando principal expuesto por el runtime es ak. Los siguientes comandos muestran la experiencia relevante sin intentar listar cada ruta interna o experimental.

Bootstrap y proyecto

ak quickstart [directory] ak init [directory] ak status ak setup ak setup --check ak setup --check --probe ak project list --observe ak project register [path] ak project refresh <binding-id> [path]

Quick Start prepara y diagnostica. Deliberadamente no inventa intención ni ejecuta automáticamente un modelo.

Misión y contexto

ak mission create <mission-id> ak mission show <mission-id> ak mission explain <mission-id> ak raw digest <mission-id> ak context pack create --mission <id> --role <role> ak context pack verify <pack-file> ak context pack supplement <parent-pack> ...

La Mission todavía puede ser creada explícitamente por una persona. AK ya puede evaluar si la intención revisada tiene base suficiente para avanzar; la derivación de requirements y la materialización automática de esa Mission siguen en construcción.

Propuesta

ak changeset propose \ --mission <id> \ --intent "..." \ [--provider <id>] [--model <id>] ak changeset show <change-set-file> ak changeset verify <change-set-file> --report

El provider genera una propuesta; el Kernel conserva la identidad del artifact y su validación.

Autoridad y efecto

ak changeset authorize <mission-id> \ --change-set <file> \ --authorized-by <human-reference> \ --confirm-change-set-id <exact-id> \ --confirm-artifact-hash <exact-hash> ak changeset apply <mission-id> \ --change-set <file> \ --authorization <file>

La autorización y la aplicación son operaciones distintas. Apply vuelve a verificar antes de producir efecto.

Autoridad y lifecycle

AK evita usar una sola palabra —“aprobado”— para estados que significan cosas distintas.

Artifact

candidate

Existe como propuesta. Puede ser verificable sin tener autoridad para producir efecto.

Efecto

applied

El cambio fue efectivamente aplicado y observado. No implica que todo su contenido sea una verdad estable.

Lifecycle

stable

Una promoción más fuerte que debe ocurrir mediante reglas específicas; tests o merge no la conceden por sí solos.

REVIEW

Una persona declara haber revisado un sujeto exacto. No es lo mismo que autorizar una acción.

AUTHORIZE

Permite una acción concreta bajo un scope y sujeto determinados.

REVOKE

Retira una autoridad previa sin reescribir la historia de que esa autoridad existió.

Fail-closed: ante sujetos ambiguos, autoridad incompatible, cambios no reconciliados o ubicaciones no resolubles, el runtime se detiene en vez de seleccionar silenciosamente “el más nuevo” o “el primero”.

Memoria externa y contexto

La memoria conversacional puede ayudar a una persona, pero no es una base suficientemente estable para gobernar trabajo reproducible.

RAW

Fuentes crudas que todavía pueden contener ruido, dudas o hipótesis.

Digest

Conocimiento procesado para volver a usarse sin reenviar siempre todo el RAW.

Unknowns

Incertidumbres explícitas que bloquean o acompañan una decisión.

Source Context

Archivos y hashes que indican qué fuente concreta fue usada.

Context Pack

Paquete de contexto por rol y misión, verificable y suplementable.

Evidence

Qué ocurrió, qué pasó validators y qué resultado se observó.

Local Universe

Identidad de proyecto y bindings locales independientes de una única ruta física.

Knowledge Graph

Próximo horizonte para consultar relaciones y provenance sin convertir el grafo en autoridad.

Estado público actual

Una lectura útil es “runtime experimental / pre-alpha”: ya existen operaciones reales y verificables, pero todavía falta cerrar la experiencia guiada de extremo a extremo.

Existe

Núcleo gobernado

  • CLI ak.
  • Setup y Quick Start.
  • Providers/modelos.
  • Context packs y source context.
  • ChangeSet propose/verify/authorize/apply.
  • Rollback, observation y evidence.
  • Revisión estructurada de intención.
  • Clasificación compartida del significado revisado.
  • Objetivo anclado + evaluación de suficiencia para proyectar.
En construcción

Experiencia por intención

  • Partir de una base ya revisada y evaluada como suficiente.
  • Derivar requirements sin inventarlos.
  • Materializar una Mission gobernada.
  • Probar el vertical completo en un proyecto externo.
Horizonte

Continuidad mayor

  • Knowledge Graph consultable.
  • Shared Universe y grants.
  • Relay/federación.
  • Móvil/IDE y otros clientes.
  • Distribución pública cuando el núcleo lo justifique.

Principios operativos

Diseñar para el universo,
construir primero el átomo.

La visión puede ser amplia; cada incremento debe justificarse con una unidad pequeña que pueda medirse y gobernarse.

Unknown antes que invención

Cuando una decisión depende de un dato que no está, el Kernel debe poder preservar la duda.

El modelo no se autoautoriza

Capacidad para generar una propuesta y autoridad para ejecutarla son propiedades distintas.

Regla de peso: si el método se vuelve más difícil que el problema que intenta resolver, el Kernel falló.

Glosario

Artifact

Objeto durable y versionable que el Kernel puede identificar, verificar y relacionar: por ejemplo una misión, un estado de revisión, una propuesta de cambio o evidencia.

Mission

Unidad de trabajo delimitada con objetivo, inputs, outputs, contexto, restricciones y validators.

Candidate

Artifact propuesto que todavía no debe confundirse con verdad estable ni con autoridad para actuar.

Unknown

Incertidumbre registrada: algo que el sistema todavía no sabe o no debe completar por inferencia.

Capability

Capacidad declarada. Puede estar implementada por una tool, un modelo, código local o una composición de componentes.

Validator

Regla que comprueba una propiedad del artifact, contexto, ejecución o transición sin depender del juicio del modelo que produjo la propuesta.

Evidence

Rastro durable de inputs, resultados, verificaciones, receipts y observaciones.

ChangeSet

Representación de un cambio material propuesto. En el flujo gobernado se propone, verifica, autoriza y aplica como etapas distintas.

Universe

Conjunto durable de proyectos, conocimiento, identidades, relaciones y capacidades que puede sostener continuidad más allá de una conversación.

UI y clientes: otra superficie, el mismo gobierno

Una futura UI local, un cliente móvil o una integración de IDE pueden simplificar la experiencia, pero no deberían crear autoridad nueva ni una ruta paralela que evite las reglas del Kernel.

Missions e intención

Mostrar objetivo, contexto, unknowns, estado de revisión y qué parte del trabajo todavía necesita decisión humana.

Review gate

Hacer visibles candidate, diff, source context, validators, evidence y el objeto exacto que una persona está autorizando.

Context preview

Permitir ver qué contexto viajará al modelo, de dónde proviene y qué información quedó deliberadamente fuera.

Regla de interfaz: una mejor experiencia puede ocultar complejidad accidental; no debe ocultar incertidumbre, evidencia ni autoridad.

Distribución y confianza

Mientras el runtime siga siendo experimental, la documentación pública puede avanzar más rápido que la distribución del core. Una futura release debería poder demostrar qué se entrega, de dónde proviene y cómo verificarlo.

Core privado

Mantiene fuera de una release prematura código experimental, RAW, evidencia sensible y decisiones internas todavía no preparadas para soporte público.

Docs públicas

Explican concepto, método, estado, límites, CLI relevante, glosario, FAQ y ejemplos sanitizados sin exigir acceso al repositorio.

Release verificable

Cuando corresponda: versión, changelog, checksums, firmas, SBOM/notices y una política explícita de compatibilidad y soporte.

Límites que siguen vigentes

No autonomía total

La revisión y la autoridad humana siguen siendo parte del diseño, no una limitación accidental.

No stable por defecto

Un artifact puede existir, pasar CI y estar aplicado sin haber sido promovido a una referencia estable.

No Knowledge Graph completo

Ya existen relaciones y provenance parciales, pero la superficie global de consulta sigue siendo un horizonte.

No Shared Universe

El universo local existe; multiusuario, grants, sync y federación todavía no.

No autoridad del modelo

El modelo puede proponer o interpretar; no ratifica por sí mismo su interpretación ni autoriza su propio cambio.

No promesa de costo

La eficiencia con modelos más pequeños o contexto selectivo debe demostrarse con evaluaciones y métricas.

La documentación explica el método; el runtime debe demostrarlo

El objetivo público no es exponer la historia interna del desarrollo, sino permitir que otra persona entienda qué problema intenta resolver AK, qué puede observar hoy y cuáles son todavía sus límites.