CK Discount Intelligence — Phase 0 Audit (read-only)

Date: 2026-06-14 Author: Claude (handoff from PR #1641) Companion spec: ck-discount-intelligence-layer.md §6 “Phase 0” Status: Complete. Read-only audit — no code or data was mutated.

Phase 0 of the discount-intelligence plan is: “Pull the real CK custom_line_definitions + a sample of extracted discount lines/pins; quantify how many fall outside the SKU path (the actual miss rate). Materialize pins → first discount golden set.” This report answers it against live data so we can size the Phase A investment before writing the hybrid-recall code.

Method

• Definition catalog: read-only query of the prod Typesense custom_line_definitions collection (search-scoped key).
• Live labels / order signal: read-only SELECTs (read-only session, zero writes) against the prod Neon genfit DB — extracted_orders.custom_line_items (auto-resolved set) and extracted_order_items.custom_line_definition_id/name (operator pins, added in migrations 0063/0076).
• Target tenant: connection 4f234677-7bc5-43c1-9059-bd616b33ef75 = “Cleveland Kitchen WhereFour (Sandbox)” ↔ org org_3DisstYyUfNutmFA68xw5hxXfq1 (confirmed via erp_connections). This is the only connection with discount definitions and the only org with applied discounts.

Finding 1 — Definition catalog gap (the investment sizer)

122 custom_line_definitions exist; 80 are active. Classifying each name by whether it carries a CK SKU token (≥4-char alphanumeric mixing letters+digits, e.g. 1616CC):

Class	Count	% of active	Matchable by today’s resolver?
SKU-bearing (Giant Eagle - 1616CC, 1616CC UNFI Promotional Allowance, Generic Off Invoice Discount 1216CD)	52	65%	✅ Yes — SKU token in name
Free-text / no-SKU (Walmart Warehouse Allowance, Slotting Fees, Costco DFI Percentage - Trade Spend)	28	35%	❌ No — structurally invisible to the SKU-keyed path

The 35% headline is real, but only part of it is a hybrid-recall win. Of the 28 free-text defs:

• ~9 are retailer/customer-scoped — Walmart ×5 (Warehouse Allowance, Swell Allowance - {Sauces,Kraut,Pickles…} Retail), Costco ×3 (DFI Percentage - {Trade Spend, Spoils - Pickles - Club, Spoils - Veggies - Club}), Kehe ×1 (Cooperative Advertising/Merchandising Allowance). These are the genuine Phase-A targets — the “Walmart Sauce Allowance” archetype where customer + product category/brand is the discriminating signal and hybrid recall adds value the SKU path never can.
• ~19 are generic operational charges/discounts — Boxing Services, Cash Discounts, Damaged Goods Discount, Slotting Fees, Tooling Charges, Hotel - Service, Flight Service, Fixed Travel Rate, Pallet Charges, Short Delivery Discount, Promotions, SSA, etc. These are not retailer- or product-tied, so context-based hybrid recall won’t meaningfully beat the keyword search that already exists (searchCustomLineDefinitions). They’re found by an operator typing a word, and that won’t change.

Sizing conclusion: hybrid recall’s defensible, demonstrable win is the ~9 retailer-scoped allowances, not a flat 35%. That is still exactly the gap the doc leads with and worth building — but the demo/eval should center on the Walmart/Costco/Kehe cases, and we should not over-claim recall on the generic-charge tail.

Finding 2 — There is no real label data yet → the pins-based golden set is blocked

Signal	Count	Detail
Operator pins (custom_line_definition_id not null)	0	across all 158,114 extracted items. The pin UI/endpoint (PR #1624) is too new to have been used.
Auto-resolved custom_line_items	5, in 2 orders	all SKU-bearing — 1616{CC,KM,KS,RG} UNFI Promotional Allowance, customer “OK Produce”. Never a free-text def.
Distinct discount-like extracted lines (CK)	7	6 SKU-bearing (Generic Off Invoice Discount 0632CD…) + 1 free-text (Deduct off invoice).

Consequence: the doc’s Phase 0 plan to “materialize pins → first discount golden set” cannot be satisfied — operators have pinned nothing and auto-resolution has only ever fired on SKU-bearing defs. There is no labeled (line text, customer, chosen def) corpus to calibrate or measure recall@k against.

Decision this forces: Phase A’s recall validation must use a synthetic fixture (this is already what eng-review task T4 calls for — “synthetic no-SKU recall fixture”), seeded from the 28 free-text def names + plausible order contexts (e.g. a Walmart PO with a sauce line → expect Walmart Swell Allowance - Sauces Retail). The real recall@k golden set (T5) is deferred until the pin feature accumulates labels in production — it is not buildable today. T5 should be explicitly marked “blocked on production pin volume,” not attempted now.

Finding 3 — Typesense version confirmed 29.1; model-enabled check is the only T0 unknown

• The cluster is Typesense Cloud (*.typesense.net), reachable (/health → {"ok":true}), and GET /debug (admin key, op://ERP-Unlocked/Typesense/api_key) returns {"state":4,"version":"29.1"}. This confirms the doc’s “~v29+” — vector_query and server-side auto-embedding (embed.from) are natively supported. Open question #1 in the spec §7 is resolved.
• Note: the root .env TYPESENSE_API_KEY is the search-scoped key (cannot read /debug or /collections); the admin key is a distinct value in 1Password. The webapp must keep using the search key (it can run hybrid auto-embedding queries fine); only dagster/admin paths use the admin key.
• Still open for T0: whether the built-in ts/all-MiniLM-L12-v2 model is enabled on this Cloud cluster. Confirming it requires creating a probe collection with an embed field (a write) — out of scope for this read-only audit. T0 should verify it locally first (spin up typesense:29.1 in docker, create a test embed collection, run a vector_query), then carefully on the cloud cluster. If the built-in model is not enabled on Cloud, T0 grows to configuring a remote embedding provider + key — a cost/decision for David.

Finding 4 — Adjacent context (not blocking)

• erp_connection_custom_line_defs Postgres table exists — a per-connection def store independent of Typesense. Phase A uses the Typesense hybrid query (per the spec), but this is a useful fallback/source to keep in mind.
• 1,023 of 1,094 non-deleted CK line items have a null erp_item_id (≈93% unmatched to an ERP product). This is a broad product-matching gap (separate from discounts, and the subject of the sibling product-matching doc), but it’s relevant: hybrid discount recall keys partly on the matched product name/brand/category, and that signal is absent on most CK lines today. The query-context assembly for fetchHybridCandidates must degrade gracefully when the product match is missing (fall back to customer + raw line text).

Implications for the build

1. Proceed to T0 (Typesense infra PR) as planned — it remains the gate. Version is now known: bump docker-compose.yml typesense/typesense:0.25.2 → 29.1 to match prod; the only remaining verification is the built-in-model-enabled check (Finding 3).
2. Phase A is worth building, scoped to the ~9 retailer-scoped allowances as the proof case (Finding 1). Don’t over-claim on the generic-charge tail.
3. T4 uses a synthetic fixture; T5 (real golden set) is blocked on production pin volume — mark it deferred, don’t attempt it now (Finding 2).
4. fetchHybridCandidates query-context must tolerate a missing product match (Finding 4) — most CK lines have no erp_item_id.

Appendix A — the 28 free-text / no-SKU defs (Phase-A recall targets)

Retailer-scoped (high-value — build/demo around these):

Walmart Warehouse Allowance
Walmart Swell Allowance - Sauces Retail
Walmart Swell Allowance - Kraut Retail
Walmart Swell Allowance - Pickles Retail MS - CK
Walmart Swell Allowance - Pickles Retail MS - PL
Costco DFI Percentage - Trade Spend
Costco DFI Percentage - Spoils - Pickles - Club
Costco DFI Percentage - Spoils - Veggies - Club
Kehe Cooperative Advertising/Merchandising Allowance

Generic operational charges/discounts (keyword-search already covers; hybrid adds little):

Boxing Services · Cash Discounts · Damaged Goods Discount · Dot Poundage Fee
Fixed Travel Rate · Fixed service rate tech · Flight Service · Freefills
Hotel - Service · Labor Charge for 600012 · Other Sales Discounts · Pallet Charges
Promotions · Rental Car - Service · SSA · Short Delivery Discount
Slotting Fees · Temp. Recorder · Tooling Charges

Appendix B — live applied / extracted discount signal

Auto-resolved custom_line_items (all of it):

def#17605 '1616KM UNFI Promotional Allowance'  erpItem=1616KM
def#17606 '1616KS UNFI Promotional Allowance'  erpItem=1616KS
def#17603 '1616CC UNFI Promotional Allowance'  erpItem=1616CC   (×2 orders)
def#17608 '1616RG UNFI Promotional Allowance'  erpItem=1616RG

Distinct discount-like extracted lines (CK):

Generic Off Invoice Discount {0632CD,1216CD,1216KP,1235CD,1235HP,1235KP}   (SKU-bearing)
Deduct off invoice                                                          (free-text)