> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operar una Collection con contexto gobernado

> Trabaja un Record operacional con los criterios del equipo cargados, no como una tabla aislada. Lee primero el criterion de la collection, evalúa el record contra él y cambia el estado solo cuando de verdad cambió.

Una [Collection](/es/concepts/collections) 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

| Ítem                                              | Estado                                                     |
| ------------------------------------------------- | ---------------------------------------------------------- |
| Collections, records, entities (CLI, MCP, REST)   | Available                                                  |
| `retrieve` (records más criterion en una llamada) | Available                                                  |
| `collection context` (solo criterion)             | Available                                                  |
| `distill_policy` como campo de configuración      | Available (declara intención; no es un runtime automático) |

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

| Objeto         | Rol en este workflow                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------- |
| **Collection** | La tabla configurada: `record_schema`, stages, `views`, criterion.                                  |
| **Record**     | Una fila tipada; su `status` se valida contra los stages de la collection.                          |
| **Entity**     | Una identidad cross-collection a la que los records apuntan, deduplicada sobre `(kind, dedup_key)`. |
| **Criterion**  | Los Topics de Knowledge que el trabajo lee antes de actuar (`criterion_rel_slugs`).                 |

## 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.

```bash theme={"theme":"github-light"}
driftless workspace current
driftless collection search "pipeline de qualified accounts"   # por intención; active-only
driftless collection list --status active --cursor <token>   # página acotada de collections activas
```

## 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:

```bash theme={"theme":"github-light"}
driftless collection context <collection-id>                      # solo criterion
driftless collection retrieve <collection-id> --status qualified --limit 25   # records más criterion
```

`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](/es/guides/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

<Steps>
  <Step title="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`).

    ```bash theme={"theme":"github-light"}
    driftless collection get <collection-id> --view full
    ```
  </Step>

  <Step title="Lee el criterion, luego tira los records relevantes">
    Carga primero el "cómo hacemos esto" del equipo, después los records a trabajar.

    ```bash theme={"theme":"github-light"}
    driftless collection retrieve <collection-id> --status qualified --limit 25
    ```

    Lee `criterion` antes de leer los records. Es la diferencia entre trabajar con el criterio del equipo y trabajar desde cero.
  </Step>

  <Step title="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.

    ```bash theme={"theme":"github-light"}
    driftless collection entity add --kind company --name "Globex" --dedup globex.com
    ```

    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.
  </Step>

  <Step title="Resuelve el Record">
    Encuentra el record específico y lee sus fields y status actuales.

    ```bash theme={"theme":"github-light"}
    driftless collection records <collection-id> --status qualified
    driftless collection record get <collection-id> <record-id>
    ```
  </Step>

  <Step title="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í.

    ```bash theme={"theme":"github-light"}
    driftless collection record update <collection-id> <record-id> \
      --fields '{"owner":"me","next_step":"schedule review"}' \
      --entity <entity-id>
    ```
  </Step>

  <Step title="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.

    ```bash theme={"theme":"github-light"}
    driftless collection record update <collection-id> <record-id> --status engaged
    # un move a un stage terminal (ej. won, published) devuelve context_outcome en el record
    ```

    El status se valida contra los stages propios de la collection; un valor fuera de ellos se rechaza.
  </Step>

  <Step title="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).

    ```bash theme={"theme":"github-light"}
    driftless collection record rm <collection-id> <record-id> --dry-run
    driftless collection record rm <collection-id> <record-id>   # idempotente; los reintentos devuelven already_absent
    ```

    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.

    ```bash theme={"theme":"github-light"}
    driftless collection archive <collection-id>
    driftless collection purge <collection-id> --dry-run    # owner/admin; impact = { version, records, entity_links_removed, distilled_notes_preserved }
    driftless collection purge <collection-id> --expected-version <n>   # confirmación CAS; idempotente
    ```

    `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).
  </Step>
</Steps>

<Note>
  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](/es/api/collections).
</Note>

## Estados esperados

| Momento                          | Qué deberías ver                                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Tras `collection get`            | El archetype, el `record_schema`, los stages, las views y el criterion. `--view full` añade `distill_policy`. |
| Tras `retrieve`                  | `{ records, nextCursor, criterion, criterion_missing }`.                                                      |
| Tras `entity add`                | Un `<entity-id>`; re-agregar el mismo `(kind, dedup_key)` actualiza, no duplica.                              |
| Tras un `update` de fields       | El record lleva los nuevos fields y su `entity_id`.                                                           |
| Tras un move a un stage terminal | El record lleva un `context_outcome` (`created` · `already_exists` · `skipped` · `failed`).                   |
| Tras `record rm --dry-run`       | `impact` previsualiza el `entity_link` removido y `distilled_notes_preserved`.                                |
| Un status fuera de los stages    | Rechazado con `400 VALIDATION_FAILED`.                                                                        |
| Tras `collection archive`        | Status `archived`; inmutable — solo `restore`/`purge` lo tocan.                                               |

## 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.

```bash theme={"theme":"github-light"}
driftless note add --content "Accounts stalled in qualified for 30+ days are usually mis-scored, not lost"
driftless context propose <slug>    # después, si prueba ser durable y revisado
```

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:

```bash theme={"theme":"github-light"}
driftless collection doctor    # records fuera de ciclo, violaciones de schema, en drift, entities huérfanas
```

## Límites y truth states

| Capacidad                                                    | Estado                                      |
| ------------------------------------------------------------ | ------------------------------------------- |
| Collections, records, entities en las tres superficies       | Available                                   |
| `retrieve` y `collection context` (la costura de criterion)  | Available                                   |
| Dedup de Entity sobre `(kind, dedup_key)`                    | Available                                   |
| `distill_policy` como campo de configuración                 | Available (declara intención)               |
| Ejecución automática de `distill_policy` al cerrar un record | Not available (no es un runtime automático) |

## Referencia relacionada

* [Colecciones](/es/concepts/collections) - archetypes, tipos de campo y la costura de criterion.
* [CLI: Collections, Records, and Entities](/es/cli/collections) - cada comando y flag.
* [API: Collections, Records, and Entities](/es/api/collections) - la superficie REST.
* [External context with Broker](/es/guides/external-context-with-broker) - importar records externos a una collection.