bridge: from SKU to GTIN candidates, with the evidence attached

One thesis: for the enormous class of systems that carry no GTIN at all, candidate resolution with confidence and evidence — never a silent best guess — is the entire product, and the verb's willingness to answer "no candidate" is what makes its other answers usable.

This post is written for the deputized reader: the integration-class agent onboarding supplier item files for a multi-unit restaurant org, working inside a granted scope, with a human who authored the mandate and no patience anywhere in the chain for a wrong match written quietly into a master file. The contract below is shaped so that every answer you pass upstream is one you can defend with the evidence attached.

The demand map: where identity is missing, freetext, or wrong-grained

The connector landscape sorts into three failure classes, verified system by system:

• No identity at all. Small-business accounting platforms carry SKU only — no GTIN field exists. Restaurant POS platforms in the Toast class: none. Parcel APIs carry tracking_number plus carrier and nothing product-shaped anywhere.
• Freetext identity. NetSuite holds a upccode field — unvalidated text. Square holds upc on catalog item variations, twelve to fourteen digits, merchant-filled. Present, but nothing checked it, ever.
• Wrong-grain identity. WMS platforms carry UPCs per packaging level (unit, package, pallet) — real data at a grain your recipe or receiving system doesn't speak. That class is the hierarchy post.

Your onboarding workflow lives in the first two classes daily: a supplier's item file says CS CHKN BRST 40LB #4417, your ordering system says ITM-002213, and the receiving record that would make a trace worth anything needs a GTIN. verify serves the freetext class (check the digits somebody typed). bridge serves the empty class — and the empty class is most of the market.

The contract

barcoding bridge "CS CHKN BRST 40LB #4417" --vendor "Acme Poultry" --json

{
  "candidates": [
    {
      "gtin": "10850012345677",
      "confidence": 0.94,
      "evidence": [
        { "kind": "catalog-listing", "match": "title+brand+pack", "source": "per-caller marketplace authorization" },
        { "kind": "prefix-legitimacy", "note": "GS1 US range; licensee consistent with vendor" },
        { "kind": "pack-agreement", "note": "40 lb case grain matches indicator-digit 1 form" }
      ]
    },
    { "gtin": "00850012345673", "confidence": 0.61,
      "evidence": [ { "kind": "catalog-listing", "match": "title only" } ] }
  ],
  "floor": 0.5
}

barcoding bridge "misc kitchen supplies" --json
→ exit 1   {"error":{"code":"no_candidate","message":"no candidate above floor"}}

Three properties are the product:

• Candidates, plural, ranked. bridge proposes; it never decides. The write into your item master is your principal's act, inside your mandate, with the ranking visible.
• Evidence objects, per candidate. Every candidate says why: which catalog matched on which fields, whether the GS1 prefix's licensee is consistent with the vendor name, whether the pack grain agrees. An auditable match is one whose evidence survives being read back later; a confidence number without evidence is just a mood.
• The floor, and exit code 1. Below the floor, the verb refuses. For an agent this is the load-bearing feature: a typed "no candidate" is an answer you can act on (route to the human, flag the supplier row), while a low-quality best guess silently written through you is exactly how deputized automation loses its mandate. Refusals are honest tool errors here, never fabricated answers — the same rule the MCP door applies to every verb.

Where the evidence comes from — and where it is not allowed to come from

The strongest single evidence rail is a fact about the market: the dominant marketplace requires a GTIN to list a product (absent an explicit exemption), and its catalog is searchable by GTIN, EAN, and UPC — which makes it the de-facto public oracle for the SKU-to-GTIN join. The licensing shape matters as much as the signal: that evidence runs per caller, on the caller's own authorization, uncached — a pass-through pattern, never a corpus we retain. Alongside it: prefix-legitimacy from pinned GS1 range tables (pure, local), pack-grain agreement, and the license-clean registries where the category has one. Every evidence object names its kind and source, because a bridge built on rights nobody can show would be the aggregator failure wearing a new verb.

Feeding the join

The reason your workflow wants the bridge at onboarding rather than at incident time: a bridged GTIN is what makes the downstream record joinable. The receiving scan becomes an event whose product identity is canonical; the event's transaction context ties to the PO and the despatch advice via transactions.dev; and the trace your food-safety seat runs during a recall drill walks supplier item to GTIN to case to store with no freetext seams. Store the evidence alongside the mapping and the mapping survives its own audit — six months later, "why does ITM-002213 map to this GTIN" has a stored answer with a confidence, an evidence list, and a timestamp.

bridge is a network verb and runs behind keys. Get an API key — the access flow asks what actually arrives at your door, in machine-checkable terms, and provisioning follows the list in order. Bring one real supplier item file; the first value moment is watching the worst row in it come back as an honest exit 1 instead of a confident wrong answer.

Keys open the network half of the verb set. Get an API key — say what arrives at your door, and the provisioning order follows the list.

We answer in writing. We take at most five conversations a month, only when you ask for one, and only after you already have the written read.