Skip to main content

ADR-0203: Navin Enterprise Purchasing and Suppliers Agent, retail product layer on top of the Control Plane

  • Status: proposed (2026-11-05)
  • Deciders: Navin Enterprise AI platform team, mission UC-14 (agent_uses_cases/14_Retail_Achats_Fournisseurs.md)
  • References: ADR-0176 (copied generic modules pattern), ADR-0180 (generic manifest-driven frontend shell), ADR-0174 (Navin Memory Provider contract), ADR-0191 (UC-09 agent whose generic modules, supplier scorecards and maker-checker purchase orders are copied then adapted, never imported), OPA package eai.retail_achats (deploy/policies/opa/retail_achats.rego), OpenFGA fragment deploy/policies/openfga/products/retail-achats-fournisseurs.fga, contracts contracts/v1/retail-achats-fournisseurs-action-request.schema.json and contracts/v1/retail-achats-fournisseurs-copilot-event.schema.json, Manager template navin-retail-achats-fournisseurs-agent (published: false).

Context​

A retailer wants to compare supplier offers on a truly comparable cost, follow its orders and price anomalies, match order, receipt and invoice, then prepare negotiations and purchasing decisions, without ever letting a language model send an RFQ, award a deal, promise a volume, place an order, change supplier bank details or pay an invoice. The brief requires eight modules (supplier register, needs and RFQs, offer extraction and normalisation, comparison and prepared award, negotiation, purchase orders, 3-way match, performance), an explicit server-side state machine and six numeric acceptance scenarios.

The platform provides identity, OpenFGA, OPA, the Action Gateway with maker-checker, durable jobs, the document pipeline, RAG, memory and observability. No real ERP, PIM, WMS, invoice system or supplier portal is connected in the repository: connectors run in a deterministic sandbox declared as such.

Decision​

1. Comparable landed cost, per currency​

The landed cost engine (Decimal, versioned rounding rule) computes for a requested quantity the cost of each offer from the unit or pack price, pack size, MOQ, freight, duties, payment terms and lead time. A per-carton price is compared with a unit price only after a validated pack conversion; an unknown component (missing freight) makes the cost incomplete, never zero. A conditional rebate not yet earned stays a scenario separate from the certain cost. Offers in different currencies are ranked together only with an approved rate whose date and source are shown; otherwise they are shown per currency with no common ranking.

2. 3-way match and price anomalies​

Order, accepted receipt and invoice are matched per line, with tolerances per variance type versioned as data. Every variance (quantity, off-contract price, unplanned charges, duplicate) produces an exception for human review; no payment is triggered. An invoice imported twice (same reference and same hash) is deduplicated and creates neither two debts nor two disputes.

3. The model prepares, the human decides, the source confirms​

RFQs, awards, volume commitments, orders, amendments, disputes and sensitive supplier master changes are Gateway plans approved by a human other than their preparer, within the OPA delegation limits, with Idempotency-Key and If-Match. The order link stays unknown_pending_confirmation until the ERP or portal confirms; an uncertain answer leads to re-reading the source before any retry. A bank change email opens an independent review and never updates the supplier. Negotiation preparation shows sourced facts only and invents no commitment.

4. Generic modules copied, business modules written​

The generic modules of the UC-09 model are copied into navin_achats (schema achats, prefix /api/v1/retail-achats-fournisseurs, ports 3487, 8486 and 6407). The tables of section 18.1 (supplier_projections, purchase_requisitions, rfq_records, supplier_offer_lines, award_decisions, purchase_order_links, invoice_match_results, supplier_disputes) and their complements are created with tenant then project RLS. A supplier sees only its RFQ and its offers (relation supplier in OpenFGA).

Consequences​

  • Positive: no external effect without an approved plan and source confirmation; reproducible, explained costs; no sum across currencies; tested isolation; the generic shell renders the product from its manifest.
  • Negative: real ERP, PIM, WMS and portals are not connected; acceptance scenarios run on the sandbox and are not a production integration.
  • The template navin-retail-achats-fournisseurs-agent stays published: false until explicit validation.