# Column guide / Guía de columnas

Version 1.0.0 · 2026-09-26. UTF-8, comma-delimited, one header row, decimal point, LF line endings. Blank observation fields mean unknown, never zero. / UTF-8, separado por comas, una fila de encabezados, punto decimal y saltos LF. Una observación vacía significa desconocida, nunca cero.

## sample-products.csv

One row is one sellable variant. This is a neutral source dataset to map to a provider's current template, not a universal import template. All products and barcodes are synthetic. / Una fila representa una variante vendible. Es un origen neutral para adaptar a la plantilla actual del proveedor; no una plantilla de importación universal. Todos los productos y códigos son sintéticos.

| Column(s) | Meaning (EN) | Significado (ES) |
|---|---|---|
| product_id | Text parent-product key. Three distinct parents. | Clave textual del producto principal. Tres productos distintos. |
| variant_id | Unique text key for each sellable combination. Keep a mapping if the POS assigns its own ID. | Clave textual única de cada combinación vendible. Conserva correspondencia si el POS asigna otro ID. |
| sku | Unique text stock-keeping code. Exact comparison, including case. | Código SKU textual único. Comparación exacta, incluidas mayúsculas. |
| barcode | Exact 12-character numeric text beginning 000. Internal test identifiers, not assigned GS1/UPC/EAN codes. | Texto numérico exacto de 12 caracteres que empieza por 000. Identificadores internos de prueba, no códigos GS1/UPC/EAN asignados. |
| product_name_en / product_name_es | Alternative English/Spanish names. Import one display language or map supported translated fields. Keep TEST/PRUEBA. | Nombres alternativos inglés/español. Importa un idioma o campos traducidos compatibles. Conserva TEST/PRUEBA. |
| option1_name_en / option1_name_es | First attribute label, such as Color or Pack. | Etiqueta del primer atributo, como Color o Envase. |
| option1_value_en / option1_value_es | First attribute value for this variant. | Valor del primer atributo de esta variante. |
| option2_name_en / option2_name_es | Second attribute label, such as Size. Blank for the coffee item. | Etiqueta del segundo atributo, como Talla. Vacía en café. |
| option2_value_en / option2_value_es | Second attribute value. Blank when the attribute is absent. | Valor del segundo atributo. Vacío si no existe. |
| unit | each: one saleable package. The 250 g coffee bag is sold by the bag, not by weight. | each: un envase vendible. La bolsa de café de 250 g se vende por bolsa, no por peso. |
| currency | USD as a synthetic arithmetic unit; no currency conversion or market eligibility claim. | USD como unidad de cálculo sintético; no supone conversión ni disponibilidad por país. |
| unit_price | Synthetic per-unit price before discount and tax. Decimal with two places. | Precio sintético por unidad antes de descuento e impuesto. Dos decimales. |
| unit_cost | Synthetic cost reference. It does not define the provider's costing method or a verified margin. | Coste sintético de referencia. No define el método del proveedor ni un margen verificado. |

CSV quoting is syntax, not a spreadsheet text type. Import barcode, product_id, variant_id and sku explicitly as TEXT. Never remove the zeros or add a formula such as ="000…" to the master CSV. Re-export and compare the original strings. / Las comillas CSV son sintaxis, no un tipo textual de hoja de cálculo. Importa barcode, product_id, variant_id y sku como TEXTO. No elimines ceros ni añadas fórmulas como ="000…" al CSV maestro. Vuelve a exportar y compara las cadenas originales.

## opening-inventory.csv

Twelve rows = six variants × two locations. `scenario_id` identifies the synthetic test; `variant_id` joins to products; `location_id` is TEST-A or TEST-B; `available_quantity` is the opening sellable integer count; `unit` is each; `checkpoint` is OPENING; `data_class` labels expected synthetic data. Initialize these quantities once, using the provider's stock workflow. Do not also add them as a receiving transaction. / Doce filas = seis variantes × dos locales. `scenario_id` identifica la prueba sintética; `variant_id` enlaza productos; `location_id` es TEST-A o TEST-B; `available_quantity` es la cantidad entera vendible inicial; `unit` es each; `checkpoint` es OPENING; `data_class` identifica datos sintéticos esperados. Inicializa las cantidades una sola vez mediante el proceso de inventario del proveedor. No las añadas también como recepción.

## expected-inventory-ledger.csv

| Column(s) | Meaning (EN) | Significado (ES) |
|---|---|---|
| scenario_id / variant_id | Scenario and exact target variant. | Escenario y variante exacta de prueba. |
| sequence / checkpoint | Ordered checkpoints 0–6. OPENING is a starting balance. | Puntos de control ordenados 0–6. OPENING es saldo inicial. |
| planned_reference | Suggested test label, not an ID generated by any POS. Map to actual IDs during your run. | Etiqueta propuesta, no ID generado por un POS. Relaciónala con los IDs reales de tu ejecución. |
| action_en / action_es | The same action in English and Spanish. | La misma acción en inglés y español. |
| delta_available_a / delta_available_b | Signed changes to sellable stock at A/B. Opening row initializes the balance. | Cambios con signo de existencias vendibles en A/B. La fila inicial establece el saldo. |
| delta_in_transit | Signed change to good units travelling A → B; unavailable for sale at either store. | Cambio con signo de unidades buenas en camino de A a B; no vendibles en ningún local. |
| delta_damaged_excluded | Increase in separately held/rejected damaged units; never added to availability. | Aumento de unidades dañadas separadas/rechazadas; nunca se suma a disponibles. |
| expected_available_a / expected_available_b | Calculated available balance after each step. | Saldo disponible calculado después de cada paso. |
| expected_in_transit / expected_damaged_excluded | Calculated transit and damage balances after each step. | Saldos calculados en tránsito y dañados después de cada paso. |
| expected_good_units_including_transit | Available A + available B + good units in transit. This is not all immediately available stock. | Disponibles A + disponibles B + unidades buenas en tránsito. No todo está disponible de inmediato. |
| po_ordered_cumulative / po_accepted_cumulative / po_damaged_cumulative | Supplier-order accountability counters. Damaged items were delivered but not accepted into sellable stock. | Contadores de control del pedido. Los dañados llegaron, pero no se aceptaron como vendibles. |
| po_undelivered_outstanding | Ordered − accepted − damaged, assuming no cancellation/replacement in this scenario. | Pedidas − aceptadas − dañadas, sin cancelación/reemplazo en este escenario. |
| data_class | SYNTHETIC_EXPECTED_ONLY. | SYNTHETIC_EXPECTED_ONLY: solo datos sintéticos esperados. |

## expected-transactions.csv

Two planned documents, one sale and one linked return. Nothing in this file is an executed transaction. / Dos documentos previstos: una venta y una devolución vinculada. Ninguna fila es una operación ejecutada.

`planned_document_id` is a test label; `document_type` is SALE/RETURN; `original_sale_reference` is populated only for the return; `variant_id` and `location_id` identify the stock. `quantity_signed` is +3 for sale and −1 for return. `unit_price` is 12.00; `line_discount_rate` is the fraction 0.10. Signed monetary columns reverse on return: `gross_before_discount_signed` = quantity × price; `discount_signed` = gross × discount rate; `net_sales_ex_tax_signed` = gross − discount; `tax_signed` = 0.00 for this isolated arithmetic exercise; `document_total_signed` = net + tax. `test_tender_net_signed` matches that total only under the pack's test-tender assumptions. `currency` is USD; `data_class` identifies synthetic expectations.

`planned_document_id` es etiqueta de prueba; `document_type` es SALE/RETURN; `original_sale_reference` solo se completa en devolución; `variant_id` y `location_id` identifican las existencias. `quantity_signed` vale +3 en venta y −1 en devolución. `unit_price` es 12.00; `line_discount_rate` es la fracción 0.10. Los importes con signo se invierten al devolver: `gross_before_discount_signed` = cantidad × precio; `discount_signed` = bruto × descuento; `net_sales_ex_tax_signed` = bruto − descuento; `tax_signed` = 0.00 en este ejercicio aislado; `document_total_signed` = neto + impuesto. `test_tender_net_signed` coincide solo bajo los supuestos de cobro de prueba. `currency` es USD; `data_class` identifica expectativas sintéticas.

## reconciliation-worksheet.csv

`check_id` is a stable check key; `check_en`/`check_es` name it; `scope` identifies catalog/final/test-day scope; `synthetic_expected_value` is the calculated reference; `unit` is count, each or USD. Enter your source POS report in `observed_report_value`, and the value independently rebuilt from its export in `observed_export_value`. Fill `report_minus_expected` and `export_minus_report` only when both operands are known. CSV has no formulas. For counts and identifiers, require exact agreement; for money, compare two-decimal currency units and explain any rounding. `actual_record_or_file_reference`, `issue_owner` and `next_action` retain the evidence and follow-up. `explanation_en`/`explanation_es` explain each check. `status` starts NOT_TESTED.

`check_id` es una clave estable; `check_en`/`check_es` dan el nombre; `scope` distingue catálogo/final/jornada de prueba; `synthetic_expected_value` es referencia calculada; `unit` es count, each o USD. Introduce el informe original del POS en `observed_report_value` y el valor reconstruido por separado de su exportación en `observed_export_value`. Calcula `report_minus_expected` y `export_minus_report` solo si conoces ambos operandos. El CSV no contiene fórmulas. Recuentos e identificadores deben coincidir exactamente; en importes, compara dos decimales y explica el redondeo. `actual_record_or_file_reference`, `issue_owner` y `next_action` conservan pruebas y seguimiento. `explanation_en`/`explanation_es` explican cada fila. `status` comienza en NOT_TESTED.

## demo-scorecard.csv and run-context.csv

Scorecard: `task_id` is the task key; `task_en`/`task_es` and `expected_en`/`expected_es` are instructions and expectations. Set `required_yes_no` to YES/NO before the demo. Fill `observed_result`, `evidence_reference`, `actual_record_id`, `assistance_and_manual_steps`, `issue_owner` and `next_action` from actual evidence. `elapsed_seconds_if_measured` stays blank unless timed. Do not invent durations. All statuses start NOT_TESTED. Run context: `field` is a stable metadata key, bilingual label columns describe it and `observed_value` is your blank input.

Ficha: `task_id` es clave de tarea; `task_en`/`task_es` y `expected_en`/`expected_es` son instrucciones y expectativas. Define `required_yes_no` como YES/NO antes de la demo. Completa `observed_result`, `evidence_reference`, `actual_record_id`, `assistance_and_manual_steps`, `issue_owner` y `next_action` con pruebas reales. `elapsed_seconds_if_measured` queda vacío salvo cronometraje; no inventes duraciones. Los estados empiezan en NOT_TESTED. Contexto: `field` es clave estable, las etiquetas bilingües la describen y `observed_value` es tu entrada vacía.

Status values: NOT_TESTED = not attempted / sin probar; PASS = demonstrated and reconciled / demostrado y conciliado; NEEDS_CONFIRMATION = missing configuration or evidence / falta configuración o evidencia; FAIL = observed requirement mismatch / incumplimiento observado; NOT_REQUIRED = explicitly not needed / declarado innecesario. A mandatory failure or unresolved requirement is not offset by optional passes. These labels do not produce a vendor ranking.