Skip to main content
Una Collection es una tabla configurada sobre la spine del workspace; un Record es una fila tipada en ella. Esta es la mitad operacional del workspace, donde el trabajo vive (leads, bugs, tickets, posts), a diferencia de los Topics, que capturan lo que el equipo sabe. La gracia del sustrato es que no construyes apps. Un CRM, un bug tracker, una mesa de soporte y un calendario de contenido son todos el mismo primitivo: un Record tipado que fluye por una Collection configurada. Un caso de uso nuevo es una configuración, no código nuevo. Las lecturas son active-only, acotadas y brief por defecto en toda la superficie. Un collection list devuelve collections activas en una página acotada; las archived solo aparecen cuando optas explícitamente con --include-archived (CLI), include_archived: true (MCP) o ?include_archived=true (REST). Un collection get vuelve brief salvo que pidas full. Archive, restore y purge son operaciones separadas y explícitas — el ciclo de vida nunca se colapsa en update --status.
Las Collections son el primitivo operacional de Driftless: un sistema de registro operado por humanos y aumentado por IA. No se construyen sobre Topics; una Collection puede referenciar Knowledge de criterio que guía cómo deben manejarse sus Records.

​
Los tres arquetipos

Todo caso de uso colapsa en una de tres formas:
  • Pipeline: los records fluyen por un ciclo de vida de status en un board: leads, bugs, tickets de soporte, campañas de ads.
  • Analysis: un record es un artefacto anclado a una fuente que puede entrar en drift (la fuente cambió) frente a decaer (sin actividad): análisis de llamadas, seguimiento de competidores, auditorías SEO.
  • Content: un record con un ciclo de vida de publicación (draft → published): posts de blog, copy de producto. El artefacto publicado vive en tu sitio/CMS; la collection rastrea el trabajo.

​
Qué contiene una Collection

  • record_schema: las definiciones de campos tipados (las columnas). Tipos de campo: text, long_text, number, currency, date, datetime, select, multi_select, status, relation, user, url, email, phone, file, anchor_ref, ai_field. Un campo status lleva stages[], el ciclo de vida por el que fluye un record.
  • views: vistas guardadas sobre los records: board, table, list, calendar, gallery, cada una con group_by, filter, sort y visible_fields.
  • criterion_rel_slugs: los Topics de Knowledge que el trabajo lee antes de actuar. Esta es la costura que baja: un pipeline de leads lee how-we-sell e icp, así el trabajo ocurre con los criterios del equipo.
  • distill_policy: un campo de configuración de cómo un record terminal debería destilarse de vuelta en una Nota (la costura que sube): cerrar un bug o ganar un deal puede dejar un aprendizaje durable en el vault. El distill devuelve un context_outcome (created · already_exists · skipped · failed), expuesto en la respuesta de create/update del record — un resultado observable y best-effort que nunca bloquea la escritura.

​
Un Record

Un Record es una fila: sus fields son los valores tipados (indexados por las field keys de la Collection), y su status se valida contra los stages propios de la Collection. Cada Collection define su propio ciclo de vida, así que un record solo puede estar en un stage que su Collection declara.

​
Entities

Un Record es una fila dentro de una Collection. Una Entity es una identidad que puede abarcar varias Collections: el mismo cliente que aparece como lead en el pipeline de ventas y como ticket en soporte. Una entity no es una fila de una Collection; es un objeto aparte al que los Records apuntan. Una entity lleva:
  • kind: el tipo de identidad (por ejemplo company, person).
  • name: su nombre para mostrar.
  • dedup_key: la clave estable que la hace única dentro de su kind.
  • attributes: valores tipados de forma libre.
Las entities hacen upsert idempotente sobre (kind, dedup_key): escribir el mismo par dos veces actualiza la entity en vez de crear un duplicado. Un Record se enlaza a una entity al setear su entity_id top-level (nunca un campo dentro de fields), así varios Records de distintas Collections pueden resolver a una sola identidad. Las entities están disponibles en tres superficies: la CLI (driftless collection entity add|list), MCP (driftless_entity, action: list | get | upsert) y REST (/workspaces/:slug/entities).
El import de conector (vía el Broker) mapea los records espejados de un provider a Records de Collection. Eso es distinto del index del Broker, que materializa connector documents para retrieve, no Records de Collection. Ver Broker: lecturas y materialización.

​
Usar collections

Desde la CLI (la superficie también existe en MCP como driftless_collection y driftless_collection_record):

​
Recuperar antes de actuar: la costura en una sola llamada

Antes de trabajar un record, un agente lee el Knowledge de criterion de la collection: los criterion_rel_slugs resueltos en los topics reales (how-we-sell, icp), así el trabajo ocurre con los criterios del equipo, no desde cero. La acción retrieve entrega las dos mitades de la costura de una vez: los records relevantes y el criterion para leer primero:
criterion es el Knowledge del equipo a aplicar; criterion_missing marca cualquier slug de criterion que no resuelve (una brecha por cerrar). Los records paginan por keyset (nextCursor). Lee el criterion, luego actúa sobre un record con driftless_collection_record action:'update'. Para solo el criterion (sin records), usa driftless_collection action:'context'. Esto refleja el retrieve de topics: una sola llamada devuelve qué leer y en qué trabajar, en lugar de encadenar a mano una lista y una búsqueda de criterion aparte.

​
Ciclo de vida, archive y purge

Una collection se mueve por uno de dos estados de ciclo de vida (active · archived):
  1. Active — los records se leen y trabajan.
  2. Archived — collection archive retira una collection activa. Una collection archived es inmutable: solo restore (de vuelta a active) y purge pueden tocarla. update, las escrituras de records y retrieve se rechazan con 409.
  3. Purged — collection purge es permanente y solo owner/admin. Corre --dry-run primero para leer el impacto (version, records, entity_links_removed y distilled_notes_preserved — las distilled Notes que engendró la collection se preservan, no se borran). Confirma con --expected-version <n> (compare-and-set sobre la versión que acabas de leer). La llamada se audita y es idempotente: un reintento tras borrar la collection devuelve already_absent, nunca 404.
El safe delete de records tiene la misma forma: collection record rm solo elimina un record de una collection no archived, y --dry-run previsualiza el Entity link que se removería y las distilled Notes que se preservan (no se borran). El delete está gateado por membresía del workspace, no por owner/admin — cualquier member puede remover un record.
archive y restore son reversibles; purge es la única operación permanente. Son comandos/rutas/actions separados en toda la superficie — un update --status que intente archivar se rechaza con 409 y nombra la ruta de ciclo de vida que usar en su lugar.