6.2 Specification Bundle y autoridad de datos

Al terminar esta lección

• Asignar una fuente de autoridad a cada campo del contrato de CU-01 y justificarla con evidencia del caso.
• Detectar en un bundle referencias rotas, valores inventados para reglas BLOCKED y contexto que es ruido.
• Corregir una referencia errónea entre reglas (RN-03 precio, RN-07 expiración de reserva) sin duplicar texto.
• Redactar la sección "el agente no puede decidir" y un presupuesto de contexto para un agente.
• Versionar un bundle como baseline y propagar un cambio de evidencia a los artefactos derivados.

6.6 Del documento legible al contrato ejecutable

La especificación empieza a volverse poderosa cuando artefactos diferentes dicen cosas compatibles sin copiarse enteros. El caso de uso referencia reglas (RN). Los criterios de aceptación citan CU y RN. El contrato describe datos y errores pero no redefine la política comercial. El modelo conceptual fija vocabulario, no estructura de tablas. Esa separación permite cambiar una regla en un lugar y revisar sus consecuencias en los derivados.

El peligro real es la duplicación textual. Si la regla de sobregiro aparece escrita de tres formas (en el caso de uso, en un prompt y en un test), tarde o temprano divergen. Un bundle para agentes contiene la definición autoritativa o una copia versionada y claramente identificada.

6.7 Contratos de entrada: confiar en la identidad, no en la autoridad del cliente

Un boundary recibe datos, pero no todos tienen la misma autoridad. El cliente dice qué SKU y cantidad quiere; no dicta el precio autoritativo, el descuento final, su límite de crédito ni el estado del pedido. Esos valores se resuelven desde fuentes controladas por el sistema o por integraciones confiables. La matriz de autoridad de la lección 6.1 es la herramienta; acá la ponemos a prueba con el caso.

También conviene separar validación estructural de reglas de negocio y de concurrencia. Que quantity sea un entero positivo se rechaza en el boundary. Que respete el múltiplo de venta (RN-08) depende del dominio. Que haya stock suficiente requiere la base y su transacción. Poner todo en un schema o todo en una entidad produce acoplamientos y pruebas menos expresivas.

1import type { CreateOrderCommand } from "../../application/create-order.contract";
2​
3type Session = { userId: string };   // viene de la autenticación, no del body
4​
5export function parseCreateOrder(body: unknown, session: Session): CreateOrderCommand {
6  const b = body as Record<string, unknown>;
7  const items = Array.isArray(b.items) ? b.items : [];
8  if (typeof b.requestId !== "string" || typeof b.clientId !== "string" || items.length === 0) {
9    throw new BadRequest("estructura inválida");
10  }
11  if (b.deliveryMethod !== "pickup" && b.deliveryMethod !== "delivery") {
12    throw new BadRequest("deliveryMethod fuera del conjunto cerrado");
13  }
14  return {
15    requestId: b.requestId,
16    sellerId: session.userId,               // nunca b.sellerId
17    clientId: b.clientId,
18    items: items.map((i: any) => {
19      if (!Number.isInteger(i.quantity) || i.quantity <= 0) throw new BadRequest("quantity");
20      return { sku: String(i.sku), quantity: i.quantity };   // se descarta unitPrice si vino
21    }),
22    deliveryMethod: b.deliveryMethod,
23    preferredDepositId: typeof b.preferredDepositId === "string" ? b.preferredDepositId : undefined,
24  };
25}

Esta función no sabe nada de múltiplos ni de crédito: eso vive en el dominio. Y descarta lo que no pertenece al contrato en lugar de rechazar todo el request, una decisión que el bundle también tiene que registrar (¿se rechaza o se ignora y se registra el intento?).

Nexo B2B · El primer bundle falla una revisión

El Responsable del Desarrollo pide una revisión del primer bundle de CU-01 antes de entregárselo al agente de IA que va a proponer el plan. El equipo lo armó en una tarde. Esta es su primera versión:

1# Bundle CU-01 v1
2## Objetivo
3Que los vendedores carguen pedidos más rápido.
4## Reglas
5- RN-01: crédito estándar.
6- RN-03: expiración de reserva a las 24 horas, configurable.
7## Contrato
8POST /api/orders { clientId, items[{sku, qty, unitPrice}], creditLimit, status }
9## Contexto adjunto
10- catálogo completo (30 páginas)
11- capturas de la UI actual
12## Tests
13- que ande bien

El problema no es solo del agente. El bundle era ambiguo: decía qué campos entraban pero no quién tenía autoridad sobre cada uno. Cada línea defectuosa tiene una causa distinta, y las causas se repiten en casi todo primer bundle: objetivo comercial sin oráculo, regla citada por nombre, contrato heredado de un prototipo, contexto "por si acaso" y tests declarativos.

El agente devuelve una pregunta, no código

Con el bundle v1, un agente propone aceptar el unitPrice que manda el frontend "para mantener el precio que vio el cliente". Es razonable y está mal: el precio final depende de lista, acuerdo y vigencia que resuelve el servidor (RN-03). Esa propuesta no es culpa del agente: el bundle no dijo quién tenía autoridad.

En una segunda revisión, ya con la sección de autoridad, el agente señala algo más sutil: la línea RN-03: expiración de reserva a las 24 horas contradice el dossier, donde RN-03 es el cálculo de precio en servidor y la expiración es RN-07, BLOCKED. Esta vez no inventa las 24 horas. Propone parametrizar el mecanismo sin fijar valor productivo y pregunta qué comportamiento debe tener un pedido pendiente de autorización.

Ese resultado es mejor que "código completo": el agente devolvió incertidumbre a la especificación. También muestra una verdad práctica sobre las referencias: un ID equivocado es un defecto de especificación, igual que un tipo equivocado en el código. Por eso la auditoría del bundle se hace con búsquedas de IDs, no leyendo "a ver si se entiende".

6.8 Qué significa "contexto suficiente" para un agente

Dar al agente todo el repositorio, todas las reuniones y todo el manual no garantiza mejores decisiones: aumenta la superficie de contradicción. Un bundle eficaz responde cinco preguntas:

1. Qué objetivo observable implementamos.
2. Qué reglas lo gobiernan.
3. Qué contratos no se pueden romper.
4. Qué código existente es relevante.
5. Qué gates demuestran éxito.

Y contiene lo que el agente no puede decidir. Esa sección reduce la tendencia a rellenar huecos: no definir el TTL de reserva, no modificar la política de precios, no introducir dependencias nuevas, no cambiar el schema fuera del plan aprobado. Si surge una ambigüedad, el resultado correcto del agente puede ser una pregunta.

Microtaller · Presupuesto de contexto

Suponé que solo podés entregar 12.000 tokens de contexto. Este es un presupuesto posible para el bundle de CU-01; las cifras son aproximadas y lo importante es qué se excluye y por qué.

Se excluyen: logs de producción (no cambian el diseño del slice), capturas de UI, el catálogo completo, las transcripciones de las reuniones (su contenido ya está en las RN). Si el agente necesita algo excluido, la regla es que lo pida y diga por qué.

Autoridad campo por campo: tres preguntas del agente

El bundle v2 no nace de una revisión de formato. Nace de que el agente, en modo plan y sin permiso para escribir código, hizo tres preguntas que el equipo no sabía contestar. Cada una cambió un artefacto.

Pregunta 1: precio. "El request incluye unitPrice; ¿debo persistirlo o recalcularlo?" El campo venía copiado del prototipo de UI. La revisión volvió a la evidencia: los clientes ven un precio, pero comercial mantiene acuerdos especiales (el Excel de acuerdos, EV-04) y el ERP puede quedar desactualizado durante una promoción. Se decide que el precio no es input: el servidor resuelve el aplicable desde la política vigente y lo devuelve en la respuesta. El precio que el vendedor vio puede enviarse solo como referencia para detectar desactualización, y qué hacer si difiere es una regla de negocio, no un default del agente.

Pregunta 2: crédito. "¿Debo leer creditLimit del objeto cliente cacheado o consultar la cuenta corriente?" El modelo había puesto el límite como atributo de Cliente por simplicidad. Laura, de administración, explica que saldo y documentos pendientes cambian durante el día y que cheques y transferencias pendientes viven en una planilla propia. El modelo se corrige antes de escribir código.

Pregunta 3: transacción. "Si reservar falla después de crear el pedido, ¿el pedido queda en borrador?" CU-01 garantizaba que un fallo previo a confirmación no deja efectos parciales, pero no lo decía con precisión. Se agrega la garantía mínima y la decisión transaccional: creación del pedido, líneas, reserva y registro de idempotencia son una misma unidad de consistencia en PostgreSQL. La facturación, en cambio, será un efecto separado porque depende de un servicio externo y tiene otra estrategia de fallo (outbox).

6.11 Especificar errores como comportamiento: el caso de la idempotencia

Los errores forman parte del contrato. "Validation failed" es insuficiente si el consumidor necesita distinguir SKU inexistente, cantidad inválida, conflicto de idempotencia o falta de autorización. Pero tampoco conviene exponer detalles internos: el contrato define categorías estables y datos útiles, y los logs conservan el diagnóstico técnico.

Un error estable reduce la libertad interpretativa de agentes y tests. Si conflict está definido, el agente no decide devolver 422, 409 o el pedido anterior según preferencia: la decisión se toma una vez y se verifica. RN-06 es el mejor ejemplo del caso, porque tiene tres salidas posibles y las tres son comportamiento de negocio.

1Característica: Idempotencia del registro de pedido (RN-06)
2​
3  Escenario: AC-07 reintento con el mismo contenido devuelve el mismo pedido
4    Dado un pedido registrado con requestId "REQ-7001" y una línea de 3 unidades de AX-442
5    Cuando el vendedor reenvía el mismo requestId con el mismo contenido
6    Entonces el resultado es el mismo pedido
7    Y existe un único pedido para REQ-7001
8    Y las reservas de AX-442 no se duplican
9​
10  Escenario: AC-07 mismo requestId con contenido distinto es conflicto
11    Dado un pedido registrado con requestId "REQ-7001" y una línea de 3 unidades de AX-442
12    Cuando el vendedor envía REQ-7001 con 5 unidades de AX-442
13    Entonces el resultado es conflict con razón request_id_reused
14    Y no se crea un segundo pedido
15    Y las reservas de AX-442 no cambian

Para detectar "contenido distinto" hay que decidir qué cuenta como contenido. ADR-006 define una huella (fingerprint) sobre cliente, depósito y líneas normalizadas por SKU y cantidad, e ignora los metadatos de tracing. Sin esa decisión, un reintento con distinto traceparent sería un conflicto falso.

1import { createHash } from "node:crypto";
2import type { CreateOrderCommand } from "./create-order.contract";
3​
4// ADR-006: cliente, depósito y líneas normalizadas por sku/cantidad. Sin metadata de tracing.
5export function requestFingerprint(cmd: CreateOrderCommand): string {
6  const lines = [...cmd.items]
7    .map((i) => `${i.sku.trim().toUpperCase()}:${i.quantity}`)
8    .sort();
9  const canonical = [cmd.clientId, cmd.preferredDepositId ?? "", ...lines].join("|");
10  return createHash("sha256").update(canonical).digest("hex");
11}

1type Seen = { orderId: string; requestHash: string } | null;
2export type Replay = { kind: "first_time" } | { kind: "replay"; orderId: string } | { kind: "conflict" };
3​
4export function resolveReplay(seen: Seen, hash: string): Replay {
5  if (seen === null) return { kind: "first_time" };
6  return seen.requestHash === hash
7    ? { kind: "replay", orderId: seen.orderId }   // mismo contenido: mismo pedido
8    : { kind: "conflict" };                       // otro contenido: sin segundo efecto
9}

Observá qué quedó afuera de la spec: la forma de calcular el hash y el nombre de las clases son decisiones de diseño. Lo que no es negociable es que replay y conflict son dos resultados distintos con efectos distintos y que ninguno crea un segundo pedido.

Reserva en espera: un criterio escrito sobre lo que sí se sabe

AC-08 es el caso opuesto. Depende de RN-02 y RN-07, ambas BLOCKED. El criterio no inventa tolerancias ni plazos: fija lo que está confirmado (el pedido queda pendiente, hay solicitud, no hay reserva firme) y marca los parámetros como pendientes de decisión.

1  Escenario: AC-08 un pedido que excede la política automática queda pendiente de autorización
2    Dado un cliente PLATINO cuyo pedido supera el límite más allá de lo que la política automática permite
3    # RN-02 BLOCKED: la tolerancia no está definida; el escenario usa un caso claramente por encima
4    Cuando el vendedor registra el pedido
5    Entonces el pedido queda en PENDIENTE_AUTORIZACION con la causa de crédito
6    Y existe una solicitud para el Responsable de crédito
7    Y existe una reserva blanda con vencimiento
8    # RN-07 BLOCKED: el plazo es un parámetro, no un valor
9    Y no existe reserva firme
10    Y el límite permanente del cliente no cambia

Fijate que el escenario no dice "un porcentaje por encima del límite" ni "24 horas". Un valor ficticio en un AC se vuelve, en dos semanas, un requisito.

6.9 Baseline no significa congelar el mundo

Aprobar un slice significa que hay suficiente definición para construirlo, no que el negocio deje de aprender. Si aparece nueva evidencia, se actualiza primero el artefacto que expresa la intención y luego se propaga el cambio. La baseline existe para poder decir qué cambió y por qué.

1bundle: BUNDLE-CU-01
2version: v2
3fecha: 2026-10-09
4aprobado_por: Responsable del Desarrollo, Laura (administración y crédito)
5alcance_aprobado: "plan y diseño; no implementación de reglas BLOCKED"
6cambios_desde_v1:
7  - "RN-07 reemplaza la referencia errónea a RN-03 para expiración de reserva"
8  - "creditLimit sale de Cliente y pasa a CuentaCorriente"
9  - "unitPrice sale del contrato de entrada (RN-03)"
10  - "creación de pedido, reserva e idempotencia: una sola transacción"
11bloqueados:
12  - { id: RN-02, falta: "tolerancia Platino", responsable: "Marta y Laura" }
13  - { id: RN-07, falta: "plazo de la reserva blanda", responsable: "depósito y comercial" }
14  - { id: cheques, falta: "tratamiento de cheques pendientes", responsable: "administración" }

Nexo B2B · Bundle de seis páginas, segunda versión

El bundle revisado contiene objetivo, CU-01, RN focales, modelo conceptual mínimo, contrato de CreateOrder, autoridad de datos, garantía mínima, ASR de concurrencia e idempotencia, y BLOCKED. Se eliminan las capturas de UI y el documento de 30 páginas sobre el catálogo. Este es el esqueleto completo de v2, con sus referencias:

1# Specification Bundle · BUNDLE-CU-01 · v2 (baseline 2026-10-09)
2​
3## 1. Objetivo observable
4Registrar un pedido mayorista válido: precio autorizado, crédito evaluado y stock
5reservado sin sobreventa, o un resultado explícito de por qué no puede aceptarse.
6​
7## 2. Reglas focales (definición única en dossier/reglas/)
8- RN-01 crédito estándar (borde: igual al límite permite, un centavo más bloquea)
9- RN-03 precio calculado en servidor desde lista vigente y acuerdos autorizados
10- RN-05 una reserva nunca hace disponible < 0 por depósito y SKU
11- RN-06 un requestId, un pedido (mismo contenido: mismo resultado; otro: conflicto)
12- RN-08 cantidad entera, múltiplo de la unidad de venta del SKU
13- RN-09 cliente de contado: se evalúa condición de pago, no crédito
14- RN-02 y RN-07: BLOCKED (ver sección 10)
15NFR focales: NFR-02 auditoría, NFR-03 seguridad, NFR-04 recuperación
16​
17## 3. Caso de uso
18CU-01 v4 (docs/cu/CU-01.md), alternativos A1 a A5. CU-02 solo como consumidor
19del estado PENDIENTE_AUTORIZACION.
20​
21## 4. Autoridad de datos
22(ver matriz de la lección 6.1: sellerId desde sesión; unitPrice, límite,
23saldo, estado y reserva desde el servidor)
24​
25## 5. Invariantes
26INV-01 disponible >= 0 · INV-02 un requestId, un pedido · INV-03 línea conserva
27precio aplicado y regla · INV-04 autorización auditada · INV-05 sin parciales
28​
29## 6. Contrato
30src/application/create-order.contract.ts (CreateOrderCommand y CreateOrderResult)
31Tabla de resultados con HTTP y reintento (docs/api/errores.md)
32​
33## 7. Decisiones que restringen el cambio
34ADR-002 PostgreSQL es la fuente transaccional de pedido y reserva
35ADR-001 monolito modular con worker · ADR-004 outbox para el handoff a preparación
36ADR-005 idempotencia por requestId · ADR-006 huella sobre cliente, depósito y líneas
37​
38## 8. Aceptación y gates
39AC-01 a AC-12 (docs/cu/CU-01-aceptacion.feature)
40npm run typecheck · npm run test:unit · npm run test:integration -- stock-reservation
41​
42## 9. Fuera de alcance
43UI, emisión fiscal real, división multi-depósito, sustituciones automáticas
44​
45## 10. BLOCKED (no convertir en constantes)
46RN-02 tolerancia Platino · RN-07 plazo de reserva blanda · cheques pendientes
47​
48## 11. El agente no puede decidir
491. Valores de RN-02 o RN-07, ni siquiera "provisorios".
502. Política de precios ni qué fuente prevalece si el Excel contradice al ERP.
513. Nuevas dependencias (Redis, colas) ni cambios de schema fuera del plan aprobado.
524. Qué hacer cuando el precio mostrado difiere del aplicado.
535. Nombres públicos del contrato (CreateOrderCommand, CreateOrderResult).
546. Resolver una contradicción entre dos fuentes: la devuelve como pregunta.
55​
56## 12. Archivos autorizados
57src/application/create-order.ts · src/ports/stock.ts
58src/adapters/postgres-stock.ts · tests/integration/stock-reservation.test.ts

Un agente nuevo recibe solo este bundle y un mapa del repositorio. Antes de código pregunta por la ubicación del adapter de stock y por la semántica exacta del conflicto de idempotencia. No pregunta qué significa "cliente Platino" porque la regla está incluida. Esa diferencia es la prueba de calidad del contexto: las preguntas que hace ya no son huecos de especificación sino detalles de ubicación.

Prueba de transferencia

Antes de entregarlo, otra persona que no participó del discovery intenta explicar el slice y escribir un plan. Cada pregunta que obliga a consultar recuerdos del equipo es candidata a entrar al bundle; cada detalle que no cambia ninguna decisión se elimina. El criterio no es la longitud sino cuánta ambigüedad relevante sobrevive a la transferencia.

El bundle final no resuelve esa pregunta: la deja como regla candidata y como pregunta para Marta. Es exactamente la división buscada. El contexto restringe las decisiones críticas y deja espacio para que la herramienta acelere el trabajo reversible: nombres, estructura interna, secuencia de cambios. El humano conserva la autoridad porque las reglas están materializadas fuera de la conversación.

1Rol: ingeniero que va a implementar, pero hoy solo planifica. No escribas código.
2Entrada: el Specification Bundle BUNDLE-CU-01 v2 y el mapa del repo.
3Tarea:
41. Enumerá cada decisión que tendrías que inventar para implementar este slice.
52. Proponé un plan de máximo 6 pasos, cada uno con el gate que lo valida.
63. Para cada ambigüedad escribí una pregunta cerrada y quién podría responderla.
7Regla: si una regla figura como BLOCKED, no propongas un valor; pedí que se parametrice.

Alternativas que descartamos, y por qué

Un bundle también explica lo que no se eligió. Si no lo escribís, el próximo agente o la próxima persona reabre la discusión con los mismos argumentos, y la respuesta puede cambiar sin que nadie lo note.

• Aceptar unitPrice y validarlo contra la lista. Parece prudente, pero un acuerdo vigente puede dar un precio distinto de la lista y el cliente tiene derecho a él. Validar contra la lista bloquea pedidos legítimos y sigue tratando al request como fuente de precio.
• Guardar creditLimit en Cliente y refrescarlo por caché. La cuenta corriente cambia durante el día. Un límite cacheado evalúa RN-01 contra un dato viejo. Se descarta en favor de consultar CuentaCorriente en el momento de evaluar.
• Lock en Redis o una cola para la última unidad. Agrega una dependencia y un segundo lugar donde vive el stock, y la consistencia depende de sincronizarlos. La decisión queda en el ADR: PostgreSQL es la fuente transaccional de la reserva, con actualización condicional dentro de la transacción.
• Darle al agente el repositorio entero y el manual. Aumenta la superficie de contradicción sin cambiar el plan. El bundle reemplaza ese contexto por IDs y por una lista corta de archivos autorizados.
• Crear un estado CONFIRMADO_COMERCIAL para evitar la colisión de “confirmado”. Se descarta como estado nuevo. La figura 9 define los estados del modelo, y la colisión de palabras se resuelve en el glosario del equipo, no con un estado paralelo que el agente tendría que mantener.

Cada una de estas alternativas tiene un motivo que se puede discutir con evidencia. Si alguna cambia, el cambio se registra como versión nueva del bundle, con la evidencia que lo motivó.

Comprobá tu criterio

Errores frecuentes

• Síntoma: el agente persiste un unitPrice que vino del frontend. Causa: el campo se heredó de un prototipo sin definir su autoridad. Corrección: matriz de autoridad en el bundle y AC-04 que verifique que el valor se ignora.
• Síntoma: el bundle cita "RN-03" para la expiración de reserva. Causa: se copió una referencia de memoria sin abrir el dossier. Corrección: búsqueda por ID en toda la spec (RN-03 es precio, RN-07 es expiración) y una sola definición por regla.
• Síntoma: aparece "24 horas" en un prompt, un test o un AC. Causa: alguien rellenó un BLOCKED para avanzar. Corrección: el valor desaparece; el mecanismo queda parametrizado y el pedido pendiente con reserva blanda sin plazo cerrado.
• Síntoma: un cache de cliente decide el límite de crédito. Causa: el modelo puso creditLimit como atributo de Cliente. Corrección: moverlo a CuentaCorriente y consultarla al evaluar RN-01.
• Síntoma: un reintento legítimo devuelve conflicto. Causa: el hash incluye metadatos de tracing. Corrección: la huella se calcula sobre cliente, depósito y líneas normalizadas (ADR-006).
• Síntoma: el bundle pesa treinta páginas y el agente igual inventa. Causa: se agregó contexto "por si acaso". Corrección: quitá un documento y mirá si el plan cambia; si no cambia, era ruido.

Para llevarte

• Un bundle es la interfaz de trabajo: objetivo, reglas con ID, contratos, autoridad, invariantes, AC, fuera de alcance y BLOCKED.
• La autoridad de cada campo se decide con evidencia y se escribe; el servidor resuelve precio y crédito siempre.
• Un ID equivocado es un defecto de especificación: auditá referencias buscando IDs, no leyendo.
• Los valores de reglas BLOCKED nunca aparecen como constantes: se parametrizan y se dejan con dueño.
• Los errores son comportamiento: resultados con nombre, HTTP definido y efectos verificables (replay vs conflict).
• Medí la calidad del contexto por las preguntas que hace el agente: de ubicación, no de negocio.