# Corvana's payables ontology: the single source of truth for definitions and rules. # Definitions are in Spanish because people and agents read them; the core implements each rule id. # Generates ontology/generated.ts, ontology/generated.document.ts and each agent's context. # Anything marked `ilustrativa: true` is illustrative, pending contador review. meta: name: Ontología de cuentas por pagar de Corvana version: 1.0.0 date: 2026-10-01 status: vigente owner: gerenteFinanciera fiction: Empresa, personas, sistemas y cifras inventados para esta demostración. roles: # The same six people as in Nodus's ontology. - { id: gerenteGeneral, label: Gerente general, person: Martín Bustamante } - { id: gerenteFinanciera, label: Gerente financiera, person: Liliana Peñaranda } - { id: directorComercial, label: Director comercial, person: Hernán Cuello } - { id: contador, label: Contador, person: Ricardo Montes } - { id: jefeCartera, label: Jefe de cartera, person: Yolanda Ariza } - { id: coordinadorTi, label: Coordinador de TI, person: Andrés Pacheco } # New in Collegium: payables needs them. - { id: jefeCuentasPorPagar, label: Jefe de cuentas por pagar, person: Elvira Fontalvo } - { id: tesorero, label: Tesorero, person: Rubén Cantillo } - { id: jefeCompras, label: Jefe de compras, person: Diana Vergara } # Who holds each duty. No person holds two of them (concept segregacionFunciones). duties: decidesEscalations: jefeCuentasPorPagar releasesPayments: tesorero approvesAmendments: jefeCompras relationTypes: - { id: perteneceA, label: pertenece a, inverse: tiene } - { id: refiereA, label: se refiere a, inverse: es referido por } - { id: derivaDe, label: se calcula a partir de, inverse: alimenta } - { id: resta, label: resta, inverse: se resta de } - { id: seRigePor, label: se rige por, inverse: rige } concepts: # Documents - id: proveedor label: Proveedor group: documento kind: identity owner: jefeCompras definition: >- Empresa o persona a quien Corvana le compra mercancía, identificada por su NIT. Su tipo determina las retenciones que se le aplican. relations: - { type: seRigePor, concept: retenciones } - id: ordenCompra label: Orden de compra group: documento kind: entity owner: jefeCompras definition: >- Lo que Corvana acordó comprarle a un proveedor: productos, unidad de medida, cantidad y precio unitario. Es la referencia contra la que se compara todo lo demás. relations: - { type: refiereA, concept: proveedor } - id: enmiendaPrecio label: Enmienda de precio aprobada group: documento kind: entity owner: jefeCompras definition: >- Cambio de precio de una línea de la orden de compra, con el nombre de quien lo aprobó y la fecha. Sin aprobación no es una enmienda, aunque el proveedor haya avisado del aumento. relations: - { type: refiereA, concept: ordenCompra } rules: [R-PRICE-AMENDMENT] decisions: [D-001, D-003] - id: recepcionMercancia label: Recepción de mercancía group: documento kind: entity owner: jefeCompras definition: >- Lo que de verdad llegó a la bodega de Corvana contra una orden de compra. Una entrega puede quedar en varias recepciones, y una recepción puede registrarse en otra unidad de medida, como cajas de 12. relations: - { type: refiereA, concept: ordenCompra } rules: [R-RECEIPTS-SUM, R-UOM-NORMALIZE] - id: facturaElectronica label: Factura electrónica group: documento kind: entity owner: contador definition: >- Lo que el proveedor le cobra a Corvana, con su CUFE. Aquí el documento y su CUFE son simulados. Puede traer líneas que no están en la orden de compra, como un flete. relations: - { type: refiereA, concept: proveedor } - { type: refiereA, concept: ordenCompra } decisions: [D-005] - id: notaCredito label: Nota crédito group: documento kind: entity owner: contador definition: >- Documento del proveedor que reduce el valor de una factura ya emitida. Corvana se la pide cuando le cobraron de más. relations: - { type: refiereA, concept: facturaElectronica } rules: [R-CREDIT-NOTE] - id: mensajeProveedor label: Mensaje del proveedor group: documento kind: entity owner: jefeCompras definition: >- Correo u otro texto libre del proveedor, por ejemplo el aviso de un aumento de precio. Sirve como evidencia de lo que el proveedor dijo; por sí solo no cambia ningún precio. relations: - { type: refiereA, concept: proveedor } decisions: [D-003] # Tolerances - id: toleranciaCantidad label: Tolerancia de cantidad group: tolerancia kind: rule owner: gerenteFinanciera definition: >- Diferencia máxima entre la cantidad facturada y la recibida que se acepta sin abrir una excepción: {toleranciaCantidadBps}. params: toleranciaCantidadBps: { label: Tolerancia de cantidad, min: 0, max: 500, step: 50, default: 100 } rules: [R-TOL-QTY] ilustrativa: true - id: toleranciaPrecio label: Tolerancia de precio group: tolerancia kind: rule owner: gerenteFinanciera definition: >- Diferencia máxima entre el precio facturado y el de la orden de compra que se acepta sin abrir una excepción: {toleranciaPrecioBps}. params: toleranciaPrecioBps: { label: Tolerancia de precio, min: 0, max: 300, step: 25, default: 50 } rules: [R-TOL-PRICE] ilustrativa: true # The four values: the multiple-figures problem for payables. - id: valorFacturado label: Valor facturado group: valor kind: measure unit: COP owner: contador definition: >- Lo que el proveedor cobró: el total de la factura, con IVA y con todas sus líneas. calculation: Suma de todas las líneas de la factura, con su IVA. relations: - { type: derivaDe, concept: facturaElectronica } decisions: [D-005] - id: valorConciliado label: Valor conciliado group: valor kind: measure unit: COP owner: jefeCuentasPorPagar definition: >- Lo que la evidencia respalda: la cantidad recibida al precio que se puede demostrar, con su IVA, sin pasar de lo facturado menos las notas crédito ya emitidas. Lo calcula el sistema a partir de los documentos. calculation: >- Por cada línea de la orden, la menor entre cantidad facturada y cantidad recibida, por el precio de la orden o de la enmienda aprobada, más IVA, sin pasar de lo facturado en esa línea menos sus notas crédito. Las líneas sin orden no suman. relations: - { type: derivaDe, concept: valorFacturado } - { type: derivaDe, concept: ordenCompra } - { type: derivaDe, concept: recepcionMercancia } - { type: derivaDe, concept: enmiendaPrecio } - { type: resta, concept: notaCredito } rules: [R-QTY-RECEIVED, R-PRICE-OC, R-PRICE-AMENDMENT, R-UNMATCHED-HOLD] decisions: [D-001, D-002] - id: valorAPagar label: Valor a pagar group: valor kind: measure unit: COP owner: jefeCuentasPorPagar definition: >- Lo que se va a pagar después de la resolución, antes de retenciones. Lo calcula el sistema a partir de las líneas aprobadas: el agente elige cantidades y base de precio, nunca el valor. calculation: >- Por cada línea marcada para pagar, cantidad aprobada por el precio de la base elegida, más IVA. Las líneas retenidas o pendientes de nota crédito no suman. relations: - { type: derivaDe, concept: valorConciliado } rules: [R-PRICE-OC, R-AGENTS-DO-NOT-COMPUTE] decisions: [D-001] - id: retenciones label: Retenciones group: valor kind: measure unit: COP owner: contador definition: >- Lo que Corvana descuenta del pago para girarlo a la autoridad tributaria: retención en la fuente, reteIVA y reteICA. Las tablas de esta demostración son ilustrativas. calculation: >- Retención en la fuente y reteICA sobre el valor a pagar sin IVA; reteIVA sobre el IVA. Cada tarifa sale de la tabla según el tipo de proveedor. relations: - { type: derivaDe, concept: valorAPagar } - { type: refiereA, concept: proveedor } rules: [R-WH-RETEFUENTE, R-WH-RETEIVA, R-WH-RETEICA, R-ROUNDING] decisions: [D-005] ilustrativa: true - id: valorNetoGirado label: Valor neto girado group: valor kind: measure unit: COP owner: tesorero definition: >- Lo que sale del banco: el valor a pagar menos las retenciones. Solo existe cuando una persona de tesorería libera el pago. calculation: Valor a pagar menos retenciones. relations: - { type: derivaDe, concept: valorAPagar } - { type: resta, concept: retenciones } rules: [R-RELEASE-PERSON] # Governance - id: excepcion label: Excepción group: gobierno kind: entity owner: jefeCuentasPorPagar definition: >- Factura que no coincide con su orden de compra y sus recepciones dentro de las tolerancias. Solo las excepciones llegan a los agentes; una factura limpia no gasta nada. relations: - { type: refiereA, concept: facturaElectronica } - { type: seRigePor, concept: toleranciaCantidad } - { type: seRigePor, concept: toleranciaPrecio } - id: escalamiento label: Escalamiento group: gobierno kind: rule owner: gerenteFinanciera definition: >- Cuando el caso pasa a la jefe de cuentas por pagar con un resumen de una pantalla. Lo decide el sistema con reglas escritas, no un agente. relations: - { type: refiereA, concept: excepcion } rules: [R-ESC-VERIFIER-REJECT, R-ESC-PRICE-NO-AMENDMENT, R-ESC-AMOUNT, R-ESC-CONFIDENCE, R-ESC-COST, R-ESC-EVIDENCE] decisions: [D-003, D-004] - id: costoPorCaso label: Costo por caso group: gobierno kind: measure unit: COP y tokens owner: gerenteFinanciera definition: >- Lo que costó resolver una excepción con agentes, en tokens y en pesos. Se mide en cada ejecución y queda en la traza. Las facturas limpias no tienen este costo. calculation: Tokens de cada ejecución de agente del caso, por su precio, a la tasa de cambio fija declarada. relations: - { type: refiereA, concept: excepcion } rules: [R-COST-CASE] - id: segregacionFunciones label: Segregación de funciones group: gobierno kind: rule owner: gerenteFinanciera definition: >- Nadie propone, aprueba y paga a la vez. Cada agente y cada persona tiene una sola función y solo ve lo que necesita para cumplirla. rules: [R-SEGREGATION, R-RELEASE-PERSON] - id: lotePago label: Lote de pago group: gobierno kind: entity owner: tesorero definition: >- Grupo de facturas listas para pagar en una fecha, con su valor a pagar, sus retenciones y su valor neto. Lo arma el sistema y lo libera una persona de tesorería. relations: - { type: refiereA, concept: valorNetoGirado } rules: [R-RELEASE-PERSON] # The rule catalogue. The verifier cites these ids; the core implements each one. # `audience` lists the agents that read a rule. Escalation rules have none: routing is code. rules: - id: R-TOL-QTY label: Tolerancia de cantidad statement: Una diferencia de cantidad de hasta {toleranciaCantidadBps} no abre excepción por cantidad. audience: [investigator, resolver, verifier] ilustrativa: true - id: R-TOL-PRICE label: Tolerancia de precio statement: Una diferencia de precio de hasta {toleranciaPrecioBps} no abre excepción por precio. audience: [investigator, resolver, verifier] ilustrativa: true - id: R-UOM-NORMALIZE label: Misma unidad de medida statement: Antes de comparar, toda cantidad se lleva a la unidad de medida de la orden de compra, con la conversión que consta en el documento. audience: [investigator, resolver, verifier] - id: R-RECEIPTS-SUM label: Se suman todas las recepciones statement: La cantidad recibida de una línea es la suma de todas las recepciones de esa orden de compra para esa línea. audience: [investigator, resolver, verifier] - id: R-QTY-RECEIVED label: No se paga lo que no se recibió statement: La cantidad a pagar de una línea no puede superar la cantidad recibida. audience: [resolver, verifier] - id: R-PRICE-OC label: Precio de la orden de compra statement: Una línea se paga al precio de la orden de compra, salvo que exista una enmienda de precio aprobada. audience: [resolver, verifier] decisions: [D-001] - id: R-PRICE-AMENDMENT label: Enmienda aprobada statement: Una enmienda de precio solo cuenta si tiene quién la aprobó y cuándo. Con enmienda aprobada, la línea se paga al precio de la enmienda. audience: [investigator, resolver, verifier] decisions: [D-001] - id: R-PRICE-NO-AMENDMENT label: Ningún agente resuelve un aumento sin enmienda statement: Un aumento de precio sin enmienda aprobada no lo resuelve un agente. La línea se propone al precio de la orden de compra, con nota crédito por la diferencia. El sistema pasa el caso a una persona; la propuesta no tiene que pedirlo. audience: [investigator, resolver, verifier] decisions: [D-003] - id: R-UNMATCHED-HOLD label: Línea sin orden de compra se retiene statement: Una línea de la factura que no está en la orden de compra, como un flete sin términos de contrato, se retiene. audience: [resolver, verifier] decisions: [D-002] - id: R-CREDIT-NOTE label: Lo cobrado de más se pide en nota crédito statement: Si la factura cobra más de lo que se va a pagar por una línea, se propone una solicitud de nota crédito para esa línea. Cubre toda la diferencia, de cantidad y de precio, y su valor lo calcula el sistema. audience: [resolver, verifier] - id: R-EVIDENCE label: Toda línea cita su evidencia statement: Cada línea propuesta cita los documentos y campos que la respaldan. Una cita a algo que no existe invalida la propuesta. audience: [investigator, resolver, verifier] - id: R-AGENTS-DO-NOT-COMPUTE label: Los agentes no calculan statement: Los agentes eligen cantidades, base de precio y acción, y justifican. Ningún agente calcula valores, retenciones ni totales; eso lo hace el sistema. audience: [investigator, resolver, verifier] - id: R-SEGREGATION label: Segregación de funciones statement: Nadie propone, aprueba y paga a la vez, y quien decide un escalamiento no es quien libera el pago. audience: [verifier] - id: R-RELEASE-PERSON label: Una persona libera el pago statement: Solo una persona de tesorería libera un pago. Ningún agente ejecuta ni autoriza pagos. audience: [investigator, resolver, verifier] - id: R-ROUNDING label: Redondeo statement: Los valores se redondean por línea, al centavo, mitad hacia arriba. ilustrativa: true - id: R-WH-RETEFUENTE label: Retención en la fuente statement: Se aplica sobre el valor a pagar sin IVA, según la tabla y el tipo de proveedor, cuando la base supera el mínimo de la tabla. decisions: [D-005] ilustrativa: true - id: R-WH-RETEIVA label: ReteIVA statement: Se aplica sobre el IVA del valor a pagar, según la tabla y el tipo de proveedor. decisions: [D-005] ilustrativa: true - id: R-WH-RETEICA label: ReteICA statement: Se aplica sobre el valor a pagar sin IVA, según la tabla. decisions: [D-005] ilustrativa: true - id: R-COST-CASE label: Costo por caso statement: El costo de un caso es la suma medida de sus ejecuciones de agente, y queda en la traza. - id: R-ESC-VERIFIER-REJECT label: El verificador rechazó statement: Si el verificador rechaza la propuesta, el caso se escala. - id: R-ESC-PRICE-NO-AMENDMENT label: Aumento sin enmienda statement: Todo caso con un aumento de precio sin enmienda aprobada se escala, sin excepción. decisions: [D-003] - id: R-ESC-AMOUNT label: Monto en juego statement: Si el monto en juego supera el umbral, el caso se escala. El monto en juego es el valor facturado menos el valor a pagar. decisions: [D-004] ilustrativa: true - id: R-ESC-CONFIDENCE label: Confianza baja statement: Si la confianza declarada por el agente que propone está por debajo del piso, el caso se escala. - id: R-ESC-COST label: Costo tope statement: Si el costo del caso alcanza el tope, se detiene el gasto y el caso se escala. - id: R-ESC-EVIDENCE label: Evidencia inválida statement: Si una cita de evidencia no existe o falta evidencia, se rechaza la propuesta y el caso se escala. exceptionTypes: - { id: QTY_OVER_RECEIVED, label: Facturado más de lo recibido, agentMaySettle: yes, rule: R-QTY-RECEIVED } - { id: UOM_MISMATCH, label: Unidad de medida distinta, agentMaySettle: yes, rule: R-UOM-NORMALIZE } - { id: PARTIAL_SPLIT, label: Entrega en varias recepciones, agentMaySettle: yes, rule: R-RECEIPTS-SUM } - { id: PRICE_WITH_AMENDMENT, label: Aumento con enmienda aprobada, agentMaySettle: yes, rule: R-PRICE-AMENDMENT } - { id: PRICE_NO_AMENDMENT, label: Aumento sin enmienda aprobada, agentMaySettle: no, rule: R-PRICE-NO-AMENDMENT } - { id: UNMATCHED_LINE, label: Línea que no está en la orden, agentMaySettle: holdOrEscalate, rule: R-UNMATCHED-HOLD } # Each agent's job and limits (SPEC §8.2). A context contains only what its section lists. agents: - id: investigator label: Investigador does: Reúne lo que muestran los documentos de este caso y lo que no se puede saber con ellos. cannot: - Proponer qué pagar. - Ver otros casos. concepts: [proveedor, ordenCompra, enmiendaPrecio, recepcionMercancia, facturaElectronica, notaCredito, mensajeProveedor, toleranciaCantidad, toleranciaPrecio, excepcion] - id: resolver label: Resolutor does: Propone para cada línea de la factura qué acción tomar, con qué cantidad y con qué base de precio, y justifica con evidencia. cannot: - Calcular valores. - Aprobar. - Cambiar datos maestros. concepts: [ordenCompra, enmiendaPrecio, recepcionMercancia, facturaElectronica, notaCredito, mensajeProveedor, toleranciaCantidad, toleranciaPrecio, valorConciliado, valorAPagar, excepcion] - id: verifier label: Verificador does: Revisa la propuesta contra cada regla y contra la evidencia, y la aprueba o la rechaza. cannot: - Ver el razonamiento del resolutor. - Editar la propuesta. concepts: [ordenCompra, enmiendaPrecio, recepcionMercancia, facturaElectronica, notaCredito, mensajeProveedor, toleranciaCantidad, toleranciaPrecio, valorConciliado, valorAPagar, excepcion, segregacionFunciones] # The bridge shown for every case. Each checkpoint is computed independently by the core and # must equal the running total to the centavo. bridge: id: puenteCaso label: Del valor facturado al valor neto girado owner: jefeCuentasPorPagar steps: - { checkpoint: valorFacturado, label: Valor facturado, explanation: Lo que cobró el proveedor. } # Credit notes come first, line by line: the rest of the gap is only what they don't already cover. - { id: notasCreditoEmitidas, label: Notas crédito ya emitidas, effect: subtract, explanation: Lo que el proveedor ya reconoció. } - { id: cantidadNoRecibida, label: Cantidad no recibida, effect: subtract, explanation: Unidades facturadas que no llegaron a la bodega y que ninguna nota crédito cubre. } - { id: diferenciaPrecio, label: Diferencia de precio sin respaldo, effect: subtract, explanation: Lo cobrado por encima del precio de la orden o de la enmienda aprobada. } - { id: lineasSinOrden, label: Líneas que no están en la orden, effect: subtract, explanation: "Cobros sin orden de compra, como un flete." } - { checkpoint: valorConciliado, label: Valor conciliado, explanation: Lo que la evidencia respalda. } - { id: ajusteResolucion, label: Ajuste de la resolución, effect: adjust, explanation: Lo que la decisión aprobada paga de más o de menos frente a la evidencia. } - { checkpoint: valorAPagar, label: Valor a pagar, explanation: "Lo que se va a pagar, antes de retenciones." } - { id: reteFuente, label: Retención en la fuente, effect: subtract, explanation: Según la tabla ilustrativa. } - { id: reteIva, label: ReteIVA, effect: subtract, explanation: Según la tabla ilustrativa. } - { id: reteIca, label: ReteICA, effect: subtract, explanation: Según la tabla ilustrativa. } - { checkpoint: valorNetoGirado, label: Valor neto girado, explanation: Lo que sale del banco. } # Illustrative, pending contador review. Rates in basis points; amounts in centavos. withholding: status: ilustrativa note: Tablas simplificadas para la demostración. No reemplazan el estatuto tributario. supplierTypes: - { id: juridicaDeclarante, label: Persona jurídica declarante } - { id: naturalDeclarante, label: Persona natural declarante } - { id: naturalNoDeclarante, label: Persona natural no declarante } - { id: granContribuyente, label: Gran contribuyente } - { id: regimenSimple, label: Régimen simple } reteFuente: minBaseCentavos: 52374000 rateBps: { juridicaDeclarante: 250, naturalDeclarante: 250, naturalNoDeclarante: 350, granContribuyente: 250, regimenSimple: 0 } reteIva: rateBps: { juridicaDeclarante: 1500, naturalDeclarante: 1500, naturalNoDeclarante: 1500, granContribuyente: 0, regimenSimple: 1500 } reteIca: municipality: Barranquilla rateBps: 70 decisions: - id: D-001 date: 2026-09-15 decided_by: gerenteFinanciera concerns: [valorAPagar, valorConciliado, enmiendaPrecio] decision: El valor a pagar usa el precio de la orden de compra, salvo que exista una enmienda aprobada. rationale: >- La orden es lo que Corvana acordó. Un precio distinto necesita a alguien de compras que responda por él. - id: D-002 date: 2026-09-15 decided_by: jefeCuentasPorPagar concerns: [valorConciliado] decision: Las líneas de flete sin términos de contrato se retienen. rationale: >- Sin contrato no hay forma de saber si Corvana debe ese flete. Retenerlo no lo niega: lo deja pendiente hasta tener el respaldo. - id: D-003 date: 2026-09-15 decided_by: gerenteFinanciera concerns: [enmiendaPrecio, mensajeProveedor, escalamiento] decision: Los agentes no pueden resolver cambios de precio sin una enmienda aprobada. rationale: >- Aceptar un aumento es una decisión comercial con un responsable. Un correo del proveedor informa, pero no compromete a Corvana. - id: D-004 date: 2026-09-15 decided_by: gerenteFinanciera concerns: [escalamiento] decision: El monto en juego de un caso es el valor facturado menos el valor a pagar. rationale: >- Es lo que Corvana dejaría de pagar si la propuesta está bien, y lo que perdería si está mal. Ilustrativa, pendiente de revisión del contador. - id: D-005 date: 2026-09-15 decided_by: contador concerns: [valorFacturado, facturaElectronica, retenciones] decision: El valor facturado incluye el IVA, y la base de la retención en la fuente y del reteICA no lo incluye. rationale: >- El IVA es parte de lo que se paga al proveedor, pero no de su ingreso. Ilustrativa, pendiente de revisión del contador. out_of_scope: - { item: "Integración real con ERP, bancos o DIAN", reason: "Todos los documentos son simulados y ningún pago se ejecuta." } - { item: Cambios fraudulentos de cuenta bancaria, reason: "Otra familia de excepciones; esta versión cubre factura contra orden." } - { item: Cuentas por cobrar, reason: "Solo se modela lo que Corvana paga." } - { item: Varias empresas o monedas, reason: "Una sola empresa, en pesos colombianos." } changelog: - { version: 1.0.0, date: 2026-10-01, summary: "Primera versión vigente." }