Skip to main content
Una Collection no es una hoja de cálculo. Es el sustrato operacional: una tabla configurada cuyos records leen el Knowledge del equipo antes de que alguien los trabaje. Esta guía trabaja un solo record de la forma correcta, leyendo primero el criterion de la collection, así la actualización refleja los criterios del equipo en vez de una conjetura recién hecha. El ejemplo es una collection pipeline donde cada record es una cuenta. Léelo como un lead, un cliente, un ítem de contenido o una señal de producto: la forma es la misma, solo cambia la configuración.

​
Resultado

Un record avanzado con los criterios del equipo aplicados: el Knowledge de criterion leído primero, los fields confirmados actualizados, y el status cambiado solo porque el estado subyacente cambió, no porque el workflow llegó a un paso.

​
Cuándo usarlo

  • Estás trabajando un record en una collection pipeline, analysis o content y quieres aplicar los criterios registrados del equipo, no improvisar.
  • La misma identidad del mundo real aparece en más de una collection y quieres que se entienda como una sola Entity.
  • Quieres mantener el estado operacional donde pertenece mientras escalas cualquier seguimiento finito a Work.

​
Disponibilidad y prerrequisitos

Necesitas la CLI instalada y con login. Por MCP u OAuth, escribir collections, records y entities requiere el scope work:write; las lecturas y collection doctor son de nivel member.

​
Objetos involucrados

​
Antes de empezar

Encuentra la collection que quieres trabajar y confirma el workspace. Las búsquedas son por intención y active-only por defecto.

​
Context preflight

La costura que hace que una Collection sea más que una tabla es su criterion: los criterion_rel_slugs que resuelven a los Topics que el equipo quiere leídos antes de trabajar un record. Léelos antes de evaluar nada. Dos formas de tirarlo, según si además quieres los records:
retrieve devuelve { records, nextCursor, criterion, criterion_missing }. Si criterion_missing lista un slug que no resuelve, eso es una brecha: la collection apunta a Knowledge que todavía no existe. Ciérrala con una Nota o un Topic (ver Govern agent learning) en vez de trabajar el record a ciegas. No tires el workspace entero; el criterion es el contexto acotado que esta collection pidió.

​
Workflow paso a paso

1

Resuelve la Collection y lee su forma

Lee el archetype, el schema, los stages, las views y las relaciones de criterion antes de tocar un record. Los stages son los únicos status en los que un record puede estar. get es brief por defecto; pasa --view full para leer la config completa (record_schema, views, distill_policy).
2

Lee el criterion, luego tira los records relevantes

Carga primero el “cómo hacemos esto” del equipo, después los records a trabajar.
Lee criterion antes de leer los records. Es la diferencia entre trabajar con el criterio del equipo y trabajar desde cero.
3

Resuelve o crea la Entity

Si esta cuenta también aparece en otra collection, ata los records a una sola identidad. Una Entity hace upsert idempotente sobre (kind, dedup_key), así re-agregar el mismo par la actualiza en vez de crear un duplicado.
Deberías recibir un <entity-id>. Una Entity no es una fila de una collection; es una identidad aparte a la que los records apuntan.
4

Resuelve el Record

Encuentra el record específico y lee sus fields y status actuales.
5

Evalúa, luego actualiza los fields confirmados

Juzga el record contra el criterion y su estado actual, luego escribe solo los fields que puedes confirmar. Enlázalo a la entity ya que estás aquí.
6

Avanza el status solo cuando el estado de verdad cambió

Un status es una afirmación sobre la realidad. Mueve el record a un stage nuevo solo porque la cosa subyacente cambió, nunca porque el workflow llegó a este paso. Una transición a un stage terminal dispara el distill_policy y la respuesta lleva un context_outcome (created · already_exists · skipped · failed) — best-effort, nunca bloquea la escritura.
El status se valida contra los stages propios de la collection; un valor fuera de ellos se rechaza.
7

Borra un record, o retira la collection

El safe delete de un record previsualiza el impacto antes de tocar nada: el Entity link que se removería y las distilled Notes que se preservan (no se borran).
Cuando la collection misma está lista, archívala y (si es realmente permanente) púrgala. El ciclo de vida es explícito — collection update --status no puede archivar.
purge es solo owner/admin y permanente; preserva las distilled Notes que engendró la collection (sobreviven al borrado). Restaura con collection restore <id> (archived → active).
Misma superficie por MCP: driftless_collection action:'search' \| 'retrieve' \| 'context' \| 'archive' \| 'restore', driftless_collection_record action:'update', driftless_collection_purge (owner/admin), driftless_collection_record_delete (safe, con dry_run) y driftless_entity action:'upsert'. Por REST es GET /workspaces/:slug/collections/:id/retrieve, POST .../:id/archive|restore, DELETE .../:id?expected_version= y las rutas de record y entity bajo la misma base. Ver API: Collections, Records, and Entities.

​
Estados esperados

​
Knowledge write-back

La mayor parte de lo que tocas aquí es estado operacional, y debería quedarse así. Escala deliberadamente:
  • Los valores propios del record se quedan en el Record. Eso es estado operacional, no Knowledge.
  • El seguimiento finito se queda explícito en el Record y su siguiente acción.
  • Una observación reusable (un patrón en cómo se comportan estos records, una regla que se repite) se vuelve una Nota. Captúrala, no la inlines en el record.
  • Un porqué durable que valga la pena que todo el equipo confíe (cómo debería trabajarse esta collection) puede volverse Knowledge, pero solo tras revisión humana.
El resultado de un solo record no es Knowledge. El patrón recurrente detrás de muchos records podría serlo, una vez revisado.

​
Qué no hacer

  • No inventes un status terminal. Nunca setees won, published, signed, completed, validated, deposited ni committed salvo que eso de verdad haya ocurrido. Un status es una afirmación, y un agente que lo escribe está haciendo la afirmación.
  • No trates una Collection como una tabla aislada. Lee primero el criterion; ese es todo el sentido del sustrato.
  • No confundas Entity y Record. Un Record es una fila en una collection; una Entity es una identidad entre collections. Deduplica identidades en la Entity, no editando filas.
  • No promuevas el resultado de un solo record a Knowledge. Los resultados operacionales viven en el record; solo un patrón durable y revisado se vuelve un Topic.

​
Troubleshooting

  • Una escritura de field devuelve 400 VALIDATION_FAILED. El field no está en el record_schema de la collection, o su valor es del tipo equivocado. Lee el schema con collection get y ajusta las field keys y los tipos.
  • Un cambio de status se rechaza. El status no es uno de los stages declarados de la collection. Un record solo puede estar en un stage que su collection define.
  • Apareció una entity duplicada. Usaste un dedup_key distinto (o ninguno). El upsert es idempotente sobre (kind, dedup_key); usa la clave estable de forma consistente.
  • Algo se ve raro entre los records. Audita la collection antes de confiar en ella:

​
Límites y truth states

​
Referencia relacionada