Devuelve un espacio de trabajo de Carbon Forge a un corte

También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: construimos Carbon Forge en 100monkeys.ai, así que lee esto como el relato de quien lo fabrica. Esta guía la redactó uno de nuestros agentes de IA a partir de la documentación pública, sobre todo la página Snapshots del catálogo y Working in lanes, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Los nombres de herramientas, los argumentos y las frases citadas son los de la documentación, y las citas van en inglés con la traducción al lado; la documentación no da JSON de ejemplo para estas llamadas, así que no se muestra ninguno. Donde la documentación deja una pregunta abierta, la última sección lo dice.

Qué son una instantánea y un corte

Una instantánea registra la revisión actual de cada página, átomo, árbol de código y entrada de biblioteca, y los parches vivos de cada lane abierta, "as one sealed manifest of ids and hashes chained to the previous snapshot." (como un único manifiesto sellado de ids y hashes encadenado a la instantánea anterior). Guarda "ids and hashes only, never a body or a blob's bytes" (solo ids y hashes, nunca un cuerpo ni los bytes de un blob), así que cuesta poco tomarla. Un corte es un nombre para una instantánea, y "it never moves." (nunca se mueve). Instantáneas y cortes solo se añaden: "the database refuses to change or remove either while the workspace exists." (la base de datos se niega a cambiar o eliminar cualquiera de los dos mientras exista el espacio de trabajo).

Paso 1. Corta el estado que quizá quieras recuperar

Antes de un cambio grande o arriesgado, llama a snapshots.cut con un name. Un nombre tiene de 1 a 128 letras, dígitos, puntos, guiones y guiones bajos, y empieza por una letra o un dígito; los ejemplos de la documentación son stable, v0.9 y release-2026.10.16. Reutilizar un nombre se rechaza, porque un corte nunca se mueve: el rechazo dice que nombres el estado nuevo con un corte nuevo. Cortar necesita el rol de editor.

Paso 2. Encuentra el corte más tarde

cuts.list devuelve los cortes del espacio de trabajo, del más reciente al más antiguo, cada uno con la instantánea que nombra. snapshots.get con cut devuelve una instantánea: su digest, su sello, su predecesora, sus recuentos y las lanes abiertas que registró. Ambas son lecturas para el rol de lector.

Paso 3. Lee qué cambió desde el corte

cuts.notes enumera cada changeset integrado después de un límite y hasta otro, en orden de integración, agrupado por la primera palabra de su intención. Su to debe ser un corte o un id de instantánea, así que para comparar el corte con el espacio de trabajo tal como está ahora, llama primero a snapshots.cut sin nombre y luego pasa tu corte como from y el id de la instantánea nueva como to. Añade path_glob para quedarte solo con los changesets que tocaron las rutas que te importan. Cada changeset nombra su intención, su autor, la lane desde la que se integró y las rutas que tocó, y eso suele bastar para ver de quién es el trabajo que vas a deshacer.

Paso 4. Mira una entidad tal como la guarda el corte

snapshots.materialize con cut devuelve una página del manifiesto del corte, cada entrada con estos campos:

kind, entity_id, revision_id, content_hash, seal_hash, path, title

Añade entity_id y devuelve esa entidad en la revisión que nombra el corte: el cuerpo y los metadatos de una página, el cuerpo de un átomo, las entradas de un árbol, el hash de una entrada de biblioteca. "The same snapshot answers the same every time." (La misma instantánea responde lo mismo cada vez). Una entrada cuya revisión se ha purgado desde entonces responde purged y no lleva contenido.

Paso 5. Comprueba quién puede revertir

snapshots.revert necesita el rol de administrador, y de los perfiles de token solo está en full, así que un agente con un token SCM agent o SCM release no puede llamarlo. En un espacio de trabajo cuyo trunk está protegido, una reversión que escribiría un árbol de código o una entrada de biblioteca, o una página o un átomo donde las páginas también están protegidas, se rechaza antes de escribir nada: workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.

Paso 6. Revierte al corte

Llama a snapshots.revert con cut e intent, el mensaje del changeset, de 1 a 4.096 caracteres. "Revert is forward only: nothing is removed or rewritten." (La reversión solo va hacia delante: no se elimina ni se reescribe nada). Cada entidad cuyo contenido difiere del del corte recibe una revisión nueva con el contenido del corte, todo en un único changeset sellado. Una revisión restaurada de página o átomo lleva el comentario Restored from cut <cut> (R#<revision>). Donde el corte registró rutas y títulos, una página renombrada vuelve a su ruta y título anteriores, y la ruta que deja sigue redirigiendo a ella. Después se corta una instantánea nueva, marcada con el corte desde el que se revirtió.

Paso 7. Lee la respuesta

La respuesta es la instantánea nueva con estos campos:

snapshot, cut, changeset_id, restored, unchanged, extraneous, collisions

Cada fila de restored es:

kind, entity_id, from_revision_id, new_revision_id

unchanged es un recuento. collisions enumera las entidades cuya ruta anterior ocupa ahora otra página o átomo vivo: ahí "the body and metadata alone are restored, and nothing moves." (solo se restauran el cuerpo y los metadatos, y nada se mueve). Dos rechazos no escriben nada en absoluto: un corte que nombra una revisión purgada, o una entidad que ahora está en la papelera, que el rechazo te pide restaurar primero; y un corte con el que el espacio de trabajo ya coincide, que se responde con Every entity already holds what cut <cut> names; nothing changes.

Paso 8. Ocúpate de lo que la reversión deja intacto

"Entities created after the cut are reported as extraneous and left as they are." (Las entidades creadas después del corte se informan como extraneous y se dejan como están). Una página que creó el agente nocturno sigue ahí después de la reversión; decide para cada una si se queda. Como la reversión es un changeset como cualquier otro, el trabajo de la noche y su vuelta atrás siguen legibles en el historial, y cuts.notes sobre un tramo que cruce la reversión muestra los dos. Para una sola integración en lugar de todo un espacio de trabajo, changesets.revert deshace un único changeset, y acepta lane, así que en un trunk protegido puede guardarse en una lane e integrarse desde ahí.

Para nombrar versiones con cortes y publicarlas, lee nuestra guía Corta una versión en Carbon Forge y súbela a GitHub.

Lo que la documentación deja sin responder

• Cómo devolver un trunk protegido a un corte. snapshots.revert no acepta lane, y la documentación no recorre la reversión de un corte entero a través de una lane.
• Cómo eliminar de una vez las entidades extraneous. La documentación las informa y se detiene ahí.
• Qué contiene cut en la respuesta de una reversión. En la descripción de la documentación, la instantánea nueva se corta sin nombre propio, y el campo no se explica para esta llamada.
• Un ejemplo completo. El catálogo indica cada argumento pero no da ninguna llamada ni respuesta de ejemplo para estas siete herramientas.